Invoke Sub-Process Service

The Invoke Sub-Process service provides a way to reuse the same business process in multiple business processes by invoking the subprocess from within a parent process.

Note: This service is also referred to as the Invoke Business Process service and the Invoke service.

The following table provides an overview of the Invoke Sub-Process service:

System name Invoke Sub-Process Service
Graphical Process Modeler (GPM) category All Services, Sync Mode, Transactional Mode
Description Starts a subprocess.
Business usage The Invoke Sub-Process service provides a way to reuse the same business process in multiple business processes by enabling you to invoke the subprocess from within a parent process.
Usage example Runs a standard deenveloping (for example, EDI or SOAP) business process to extract business payload from a document bundle for transmission.
Preconfigured? Yes
Requires third-party files? No
Platform availability All supported Sterling B2B Integrator platforms
Related services No
Application requirements No
Initiates business processes? Yes. Each call to the Invoke Sub-Process service starts one subprocess (child). The Invoke Sub-Process service can be called multiple times from a business process. Subprocesses can be started in asynchronous or synchronous mode. Subprocesses can optionally be run as separate processes, or inline as part of the parent business process.
Invocation If a child process is disabled, a service is disabled, or there is a license error causing the subprocess to halt, the parent will not continue. Additionally, if the subprocess is manually stopped, or stopped using a system shutdown, the parent will not continue.
Note: You can fix the failures to continue the parent by resuming the subprocess.
Business process context considerations The Invoke Sub-Process service adds the business process instance ID to the INVOKE_ID_LIST object stored in the business process context. The Invoke Sub-Process service also places the business process instance ID of the generated sub-process into the IWF_Id name/value pair and stores it in the business process context. The tracking feature uses this value to be able to show information about subprocesses. This value is then deleted from the business process context before any services that follow are run.
Returned status values Returned status values:
  • Success – If the subprocess was started correctly (async, inline modes) or if the child executed successfully (sync or inline modes).
  • Error – If the subprocess was not started correctly (async) or if the child did not execute successfully (all modes).
When running in embedded mode:
  • Error – From the error step in the subprocess, if the subprocess ended with an error.
  • Success – if the subprocess completed.
Restrictions Restrictions by mode are:
  • Synchronous

    When the Invoke Sub-Process service is set to synchronous mode, the parent business process suspends processing until it receives data from the child business process. In synchronous mode, the parent is notified when the child encounters errors.

  • Asynchronous

    When the Invoke Sub-Process service is set to asynchronous mode, the parent and child process simultaneously and independently of each other. Therefore, the parent does not receive notification when the child encounters errors.

  • Inline

    When the Invoke Sub-Process service is set to run a subprocess inline, the subprocess runs as part of the parent process, sharing the same process data.

  • Embedded

    Use to run a subprocess with no persistence.

Note: A subprocess run inline will be displayed in tracking just like other steps in the parent process.
Persistence level
Valid values:
  • Full (except in Embedded mode, which runs the subprocess with no persistence)
Note: If you select one of the following persistence levels, you must also force to persist the last step of the child business process. This is so that the "Invoke Notify/Complete Service" can find the last step of the child business process and can be successfully returned.

  • Step Status Only

  • Step Status - Engine May Override

  • BP Start Stop Only

  • BP Start Stop Only - Engine May Override

  • Error Only

Example of force to persisting the last step of the child business process:
<operation name="Sleepy1"> 
      <participant name=
          "TestSleepService"/> 
      <output message="Xout"> 
        <assign to="SLEEP_INTERVAL">1
          </assign> 
        <assign to="preferredNode">node2
          </assign> 
       <assign to="WF_RUNTIME_OVERRIDE
          _PERSISTENCE_LEVEL">PERSISTENCE
          _FULL</assign> 
        <assign to="." from="*"></assign> 
      </output> 
      <input message="Xin"> 
        <assign to="." from="*"></assign> 
      </input> 
    </operation>
Testing considerations None

How the Invoke Sub-Process Service Works

When the Invoke Sub-Process service is set to synchronous mode, the parent suspends processing until it receives data from the child. In synchronous mode, the parent is notified when the child encounters errors.

When the Invoke Sub-Process service is set to asynchronous mode, the parent and child process data simultaneously and independently of each other. Therefore, the parent does not receive notification when the child encounters errors.

When the Invoke Sub-Process service is set to run a subprocess inline, the subprocess runs as part of the parent process, sharing the same process data.

When the Invoke Sub-Process service is set to run in embedded mode, the subprocess runs with no persistence, meaning that no record of the process is recorded in Sterling B2B Integrator and no tracking is done.

Performance Tips

By default, when you use the Invoke Sub-Process service in a business process, all process data passes from the parent process to its subprocess.

However, if you are using the Invoke Sub-Process service in sync mode, a special tag called ‘message_to_child/message_to_parent' enables you to pass along only the ‘message_to_child/message_to_parent' node in the process data of the parent process or subprocess. Using this tag can provide significant performance improvement.

Before invoking a subprocess, create a special tag called ‘message_to_child' in the parent process, and append all of the data needed in the subprocess under this node. The Invoke Sub-Process service will pass only this node to the subprocess. The following example shows how the BPML might look for this:

<process name="MessageToChildInvokeDoc"> 
  <sequence name="simple"> 
    <assign to="Msg1" from="'Hello'" append="true"/> 
    <assign to="Msg2" from="Msg1" append="true"/> 
    <assign to="Msg3" from="Msg1"/> 
     <assign to="OtherMsg4" from="//Msg2" append="true"/> 
    <assign to="OtherMsg5/OtherMsg6" from="//Msg2/Msg1/text()" append="true"/> 
    <assign to="message_to_child" from="//PrimaryDocument | // OtherMsg5 " append="true"/> 
  <operation> 
     <participant name="InvokeBusinessProcessService"/> 
       <output message="Xout"> 
         <assign to="." from="*"></assign> 
         <assign to="WFD_NAME">MessageToParentNode</assign> 
         <assign to="INVOKE_MODE">SYNC</assign> 
       </output> 
       <input message="Xin" > 
          <assign to="." from="*"></assign> 
       </input> 
    </operation> 
 </sequence> 
</process>

Or, you can specify the return node from the input message in the Invoke Sub-Process service. That is, only the ChildDoc node will be returned from the subprocess. In this case, you do not need to specify the ‘message_to_parent' node in the subprocess. This is shown in the following example:

<operation> 
     <participant name="InvokeBusinessProcessService"/> 
       <output message="Xout"> 
         <assign to="." from="*"></assign> 
         <assign to="WFD_NAME">MessageToParentNode</assign> 
         <assign to="INVOKE_MODE">SYNC</assign> 
       </output> 
       <input message="Xin" > 
           <assign to="test1" from="//ChildDoc"></assign> 
--- this 'ChildDoc' node is the sub node of the process data  in its
sub process MessageToParentNode---------------------------- 
       </input> 
    </operation>

If you are not specifying the return node in input message in the Invoke Sub-Process service, you can, in the subprocess, create a tag ‘message_to_parent' and append all of the data needed from the subprocess to the parent process under this node. Only data under this node will be returned to the parent process. The default is passing all process data to the parent process.

Example:

<process name="MessageToParentNode"> 
  <sequence name="simple"> 
    <assign to="ChildMsg1" from="'Hello World'" append="true"/> 
    <assign to="ChildMsg2" from="ChildMsg1" append="true"/> 
    <assign to="ChildMsg3" from="ChildMsg1"/> 
    <assign to="ChildDoc" from="PrimaryDocument/@SCIObjectID" append="true"/> 
    <operation name="Set Document"> 
               <participant name="XMLEncoder"/> 
               <output message="XMLEncoderTypeInputMessage"> 
               <assign to="mode">process_data_to_document</assign> 
               <assign to="root_element">DocumentSub</assign> 
               <assign to="xPath">/ProcessData</assign> 
               <assign to="." from="*"/> 
               </output> 
               <input message="inmsg"> 
               <assign to="xmldoc" from="PrimaryDocument" append="true"/> 
               </input> 
    </operation> 
    <assign to="message_to_parent" from="//PrimaryDocument | //ChildMsg3" /> 
  </sequence> 
</process>

Implementing the Invoke Sub-Process Service

To implement the Invoke Sub-Process service for use in a business process, complete the following tasks:
  1. Create a configuration of the Invoke Sub-Process service. See Managing Services and Adapters. For information about the fields specific to this service, see Configuring the Invoke Sub-Process Service.
  2. Specify field settings for the service configuration in the Sterling B2B Integrator Admin Console and in the GPM as necessary. For information, see Configuring the Invoke Sub-Process Service.
  3. Use the Invoke Sub-Process service in a business process.

Configuring the Invoke Sub-Process Service

To configure the Invoke Sub-Process service, you must specify settings for the following fields in the GPM.

Note: Any field values passed from a prior service can override any of configured fields for this service.
Field Description
Config Name of the service configuration. Required.
WFD_NAME Business process used in the service configuration. Valid value is the name of any business process checked into the system. Required.
INVOKE_MODE Mode in which to run the subprocess. Optional. Valid values are:
  • async = asynchronous (default)
  • sync = synchronous
  • inline = In-line
  • embedded = starts business process in SYNC mode with Enable Transaction on, and runs the subprocess in the same transaction as the Invoke Sub-Process service. The subprocess is run with no persistence.
Note: When persistance level is error only, sync invoke mode is not supported.
The following optional parameters can be used with embedded mode:
  • START_WITH_DOC – Use if the subprocess needs to be started with a document. The process checks the DOC_URL parameter for a filename (see following parameter) first. If the DOC_URL parameter is set to NONE, then the primary document is passed to the subprocess. This parameter is required if the subprocess needs a document from the parent business process.
  • DOC_URL – Name of the document from which the subprocess will retrieve data. Use this parameter with the START_WITH_DOC parameter if the parent primary document is not the document needed to start the subprocess.
  • DOC_ENCODING – Use if the document that is used to start the subprocess require different encoding from the default encoding.
  • USER_NAME – Use if the subprocess requires a different user name to start (permission to start).
  • PASS_DOC – Use if the subprocess needs to pass its primary document to back to the Invoke Sub-Process service.
PARM_LIST List of business process parameters to override. Valid values are:
  • Name1=value1
  • &name2=value2
  • &name3=value3
Optional.
NOTIFY_PARENT_ON_ERROR Errors the subprocess reports to the parent business process. The valid values are:
  • NOTIFY_PARENT_ON_ERROR_SERVICE_ERRORS_ONLY = SERVICE - Notify parent of the error only if a service-generated error occurs in the subprocess.
  • NOTIFY_PARENT_ON_ERROR_ALL = ALL - Notify parent of the error if any type of error occurs in the subprocess.
  • NOTIFY_PARENT_ON_ERROR_NONE =NONE - This option does not notify the parent of the error from the subprocess. The subprocess completes with status error.
  • NOTIFY_PARENT_ON_ERROR_SYSTEM_ERRORS_ONLY = SYSTEM - Notify parent of the error only if a system-generated error occurs in the subprocess.

    OPTIONAL
PASS_STATUS_REPORT Pass status report to parent. Valid values are:
  • ON_SUCCESS
  • ON_ERROR
  • ALWAYS
  • NEVER
Default is ON_ERROR. Required.
COPY_SERVICE_PARMS Invoke service parameters passed to the subprocess. Valid values are True and False. Default is True. Required.

Parameters That Must Be Added in BPML

The following additional parameter is available for use with the Invoke Sub-Process service, but can only be added by editing your business process manually. This parameter is not available through the Admin console or the GPM:

Parameter Description
SAME_TRANSACTION

Use this parameter to allow the Invoke business process service and the first step of the sub-business process to run in the same transaction.

If set to true, the first step of the sub-business process runs in the same transaction as the Invoke business process service. If either the Invoke business process service or the first step of the sub-business process, the sub-business process fails to start and the Invoke business process service has an error status.

If set to false, the first step of the sub-business process runs as an independent transaction and is not part of the Invoke business process service transaction. The sub-business process may be in an active state or error state.

SAME_TRANSACTION should be manually set to false. The default is true.

When the sub-business process definition has the following setting, SAME_TRANSACTION will not be valid from the Invoke business process service. The system will internally set it to false:

  • startMode =Sync
  • Transaction =TRUE
  • persistence_level=PERSISTENCE_WF_NONE,
  • persistence_level=PERSISTENCE_ERROR_ONLY
DOC_STREAM

Use this parameter to allow the sub-business process to utilize document streaming to minimize the memory footprint for documents passed to it from the parent process.

This is useful for large documents that could potentially result in extreme memory usage.

This parameter is valid only when the Invoke Sub-Process service is set to run in embedded mode.

Business Process Example

The following BPML example illustrates using the SAME_TRANSACTION parameter:

<operation>
           <participant name="InvokeBusinessProcessService"/>
           <output message="Xout" >
           <assign to="INVOKE_MODE">SYNC</assign>
           <assign to="WFD_NAME">sleepy.bpml</assign>
           <assign to="SAME_TRANSACTION">false</assign>
           </output>
           <input message="Xin" >
           <assign to="." from="*"></assign>
           </input> 
</operation>

Output from Service to Business Process

The following table describes the output from the Invoke Sub-Process service to the business process:

Parameter Description
INVOKE_ID_LIST A generated list of business process IDs for the processes running.
WFD_VERSION Version of the business process captured by the system at run time. This is a system assigned parameter and is not configurable.

Business Process Example

The following example illustrates how the Invoke Sub-Process service could be used in a business process with Async mode:

<operation> 
       <participant name="InvokeBusinessProcessService" /> 
               <output message="Xout"> 
                       <assign to="INVOKE_MODE">ASYNC</assign> 
                       <assign to="WFD_NAME">mybusprocess</assign> 
                       <assign to="." from="*"></assign>  
               </output>  
               <input message="Xin" >  
                       <assign to="." from="*"></assign>  
               </input>  
</operation>

Running a Business Process with No Persistence

To enable a business process to run with no persistence, you must start it as a subprocess (child) of another business process (parent). Include the Invoke Sub-Process service in the parent business process, and set the service to use Embedded mode. Embedded mode starts the business process in SYNC mode with Enable Transaction on, and runs the subprocess in the same transaction as the Invoke Sub-Process service. The subprocess is run with no persistence.

When checking in the parent process to Sterling B2B Integrator, on the Process levels page, make sure that:
  • Enable Async Start Mode Select is not selected (so that the business process starts in SYNC mode)
  • Enable Transaction is selected

The following example illustrates using the Embedded mode:

<operation> 
<participant name="InvokeBusinessProcessService" /> 
<output message="Xout"> 
<assign to="INVOKE_MODE">EMBEDDED</assign> 
<assign to="WFD_NAME">mybusprocess</assign> 
<assign to="." from="*"></assign> 
</output> 
<input message="Xin" > 
<assign to="." from="*"></assign> 
</input> 
</operation>