Subflows

You define a subflow to provide a common sequence of actions to be used by several message flows, applications, or integration services. You can include subflows in your message flows in the same way as you include built-in or user-defined nodes. You can also connect subflows to other nodes in the same way.

A subflow provides the following benefits:

  • Reusability and reduced development time
  • Consistency and increased maintainability of your message flows (consider a subflow as analogous to a programming macro, or to inline code that is written once but used in many places)
  • Flexibility to tailor a subflow to a specific context (for example, by updating the output queue or data source information)
Consider these examples of subflow use:
  • You can define a subflow that provides a common sequence of actions that applies to several message flows if an error is encountered. For example, you might have a common error routine that writes the message to a database through the Database node, and puts it to a queue for processing by an error recovery routine. The use of this routine in multiple message flows, or in several places within one message flow, provides an efficient and consistent use of resources and avoids reinventing such routines every time an error is encountered.
  • You might want to perform a common calculation on messages that pass through several different message flows; for example, you might access currency exchange rates from a database and apply them to calculate prices in several different currencies. You can include the currency calculator subflow in each of the message flows in which it is appropriate.
Note: You should not use a standard input node (a built-in input node such as MQInput, or a user-defined input node) in a subflow; instead use an Input node to provide the In terminal to a subflow. For more information, see Input node.

If you want to reuse subflows between multiple applications or integration services, store the subflows in a shared library. You can change those subflows and redeploy the shared library without the need to redploy the applications or integration services that reference the shared library.

Types of subflows

You define a subflow once, and use it in more than one message flow, application, integration service, and integration project. You define subflow content in the same way as you define message flow content, by adding, configuring, and connecting message flow nodes.

Note: At run time, each instance of a subflow creates a copy of all the message flow nodes that define that subflow. This behavior affects resource usage, which can affect your overall message flow performance.

You can create a subflow as a .subflow file or as a .msgflow file. Choose which type of subflow to use based on the following information:

A .subflow file subflow

A subflow that is defined in a .subflow file can be deployed in any of the following ways:
  • The subflow is deployed separately from any of the message flows that use this subflow. The subflow and the message flows that include this subflow must be deployed in the same integration server. The subflow can be deployed directly to an integration server or as part of a library. If you update this type of subflow and redeploy it, all message flows that use this subflow, and are not part of an application or the integration service, are automatically updated. You do not need to redeploy these message flows. If you update a subflow in a shared library and redeploy it, all message flows in an application or integration service that use this subflow are updated automatically.
  • The subflow is deployed as part of an application or integration service.
You cannot use the following nodes in this type of subflow:
  • Nodes representing subflows that are defined in .msgflow files
  • User-defined nodes created from subflows that are defined in .msgflow files
  • MQOptimizedFlow nodes
If you create a BAR file that contains both ESQL code and a subflow that is defined in a .subflow file, you cannot include the ESQL code directly in compiled message flow files.

A .msgflow file subflow

A subflow that is defined in a .msgflow file is embedded inside any parent message flows that use it when the message flow is placed in a BAR file. This type of subflow can only be deployed to an integration server with the message flow in which it is used. If you update this type of subflow, you must redeploy all message flows that use the subflow so that the updated subflow is used. This type of subflow can be packaged as a user-defined node.

Conditions that apply when you convert a subflow between .msgflow and .subflow and vice versa

You can convert a subflow created as a .msgflow file to a .subflow file.
  • If the .msgflow file contains subflows that are defined as .msgflow files, these subflows must also be converted to .subflow files.
  • If the .msgflow file is used as a subflow, the parent flow must be updated so that it references the new .subflow file.
You can convert a subflow created as a .subflow file to a .msgflow file.
  • You cannot use the name of a file that already exists in that application, library, or integration project where you create your subflow as a .msgflow file. You must include .msgflow at the end of your subflow file name. An application or integration service can use subflows with the same name in one or more shared libraries if the subflows are in different broker schemas.

Conditions that apply when you want to add a subflow into a message flow

You can add subflows into a message flow if either of the following statements is true:
  • The subflow that you want to add in a message flow is defined in a library, and you have specified the dependency of the current message flow container on that library. Applications and integration services can reference libraries. (A library is a logical grouping of related code, data, or both that typically contains reusable subflows, and other type of resources.)
  • The subflow that you want to add in a message flow is defined in the same integration project, application, or integration service as the message flow.

When you store subflows in a shared library, you must place the subflows inside a schema that is not the default empty schema.

When an application or shared library references other shared libraries, all the subflows for a broker schema must be in a single container. Subflows for a broker schema must not be in both an application (or shared library) and a shared library that is referenced by that application (or shared library). Subflows for a broker schema must not be in two or more shared libraries that are referenced by a single application or shared library. All the subflows in a broker schema must be either in the main application or shared library, or in a single referenced shared library.

Conditions that apply when you want to add a subflow into a subflow

You can add subflows into a subflow in any of the following cases:
  • You can add subflows that are defined in .subflow files into subflows that are defined in .subflow files and .msgflow files.
  • You can add subflows that are defined in .msgflow files into subflows that are defined only in .msgflow files.
  • A subflow in a shared library can contain another subflow in the same or a different shared library.

Conditions that apply when you deploy a subflow

You can deploy subflows in any of the following ways:
  • Deploy a subflow as an independent resource that is defined in an integration project.
  • Deploy a subflow in an application.
  • Deploy a subflow as part of a service operation.
  • Deploy a subflow in a library.

You deploy a subflow to an integration server by sending a BAR file to an integration server, which unpacks and stores the contents ready for when your message flows are started. You can also deploy a subflow directly to an integration server.

The following conditions apply when you deploy a subflow:
  • If you deploy a message flow that contains a subflow that is defined in a .subflow file, the subflow is automatically included in the BAR file.
  • If you deploy a subflow that is contained in an application, you must deploy the application to an integration server, which results in a complete deployment of the application.
  • If you deploy a subflow that is contained in an integration service, you must deploy the service to an integration server, which results in a complete deployment of the integration service.
  • If you deploy a subflow that is contained in a library, you can deploy the library to an integration server directly, outside of an application or an integration service. Then the subflow included in the library can be referenced by other message flows and subflows that are deployed directly to the same integration server as the library.
  • A subflow that is created as a .msgflow file in an integration project can only be deployed as a separate resource if it contains at least one Input node.

Version control

Use the Passthrough node to enable version control of a subflow at run time.

By including a Passthrough node, you can add a label to your message flow or subflow. By combining this label with keyword replacement from your version control system, you can identify which version of a subflow is included in a deployed message flow. You can use this label for your own purposes. If you have included the correct version keywords in the label, you can see the value of the label in a any of the following ways:
  • By using the mqsireadbar command to read the properties stored in the BAR file.
  • In the IBM® Integration Toolkit, on the properties of a deployed message flow when it was last deployed to a particular integration node.
  • In the runtime environment, if you enable user trace for that message flow.
For subflows that are created as .subflow files, consider the following behavior when you deploy a new version of a subflow:
  • If the subflow is deployed separately from any of the message flows that use this subflow, and you deploy a new version of the subflow, all the message flows are updated automatically.
  • If the subflow is deployed as part of an application or an integration service, you need to update your applications and integration services to include the new subflow version, and redeploy them.
For subflows that are created as .msgflow files, consider the following behavior when you deploy a new version of a subflow:
  • You must update your applications, integration services, and independent resources that use the subflow to include the new subflow version, and redeploy them.

To learn more about subflows, see the following scenario Scenario: Reusing common application logic in multiple integration solution.