Call Activities

General

A BPMN Call Activity is used to call the process contained in a different diagram.

In this example, above, there is an existing process diagram for the order processing and fulfillment process (‘order to cash’). The Marketing department want to create a workflow-based application for a promotion that they are running, which targets a set of customers, makes them an offer, and then fulfils those orders. The process for this promotion has its own application for the promotion, and then it ‘drops’ any orders received into the standard ‘order-to-cash’ process. This is implemented by including a call activity into the promotion process, calling the ‘order-to-cash’ process.

Topics

• Adding a call activity into your model
• Specifying which Diagram to Call
• Variable Scoping
• Passing Process Variables into a called activity
• Returning process variables from a called activity
• Specifying the interface to your called activity
• Using the Process Viewer with Call Activities
• Nesting of Call Activities
• Boundary Events on Call Activities
• Lanes and Call Activities
• For Administrators: Resetting a process instance involving Call Activities
• Tech Note: Understanding the architecture of Call Activities

Adding a CallActivity to your Process Model.

The BPMN Symbol for a Call Activity is shown above. To add a call activity, first add a standard task, then select the ‘spanner’ tool in the tool palette, and then change it to a call activity.

To configure a Call Activity, use the properties panel in the Flow Modeler. While setting parameters, the Flow Modeler can use meta-data already stored in Flows for APEX to set, for example, the model name or the required Input and Output Variables, or they can be entered manually. The Input Method pull down can be changed from Manual to ‘use mata-data’, as required.

The following properties need to be set:

1. Diagram to be Called
2. Version of the Diagram to be called. Version information is evaluated when the process instance is created, not when the call is made. Version selection can be based on either:
   1. A Specific Version, which you must then enter, or
   2. The Latest Version, which would select the current released version of the model, or failing that, a draft model with version of 0.

1. In-Variables. These are Process Variables or values from the Calling process that you want to be created in the Called process when it is entered. In-Variables can be set using any of the methods used in variable expressions. In Variables are created in the scope of the Called Process. Any expressions or variables copied will refer to variables in the Calling process.

2. Out-Variables. These are Process Variables or values from the Called process that you want to be returned to the Calling process when the called process is complete. Out-Variables can be set using any of the methods used in variable expressions. Out Variables are created in the scope of the Calling Process. Any expressions or variables copied will refer to variables in the Called process.

Two helper functions exist (usually colored in green on the properties panel) to help specification.

1. Load Defined Variables. If the Called diagram has specified its required Input and Output Variables to document its interface, the required input and output variables will be loaded into the In Variables and Out Variables regions, ready for you to complete.
2. Copy Business Reference. The Business Reference for a process is usually the Primary Key of the subject record in the system of reference. Clicking this willadd the Business_ref of the calling process to be copied to the business_ref of the called diagram.

Sometimes the Business Ref will be the same in both calling and called processes – typically when the called diagram is just a decomposition of a larger process into sub-processes. On other occasions, the Business Ref of the Called Process might be different to the Business ref in the calling process (for example, an inventory stocktaking process might have a business ref which is the stocktaking_event_id. If it calls a re-ordering process for each item found to need re-ordering, the business ref in the called ‘Reorder Item’ process might be the item part_number).

Variable Scoping

Process Variables are defined within the scope of a single diagram.

At runtime, and once a diagram has been called (entered) by a process instance, a diagram is given a scope. All process variables created in that diagram have that scope.

The scope of the initial diagram used by a process instance is always scope 0. The scopes of called diagrams are set to the subflow_id of the first subflow to operate in that diagram.

So a variable 'myVar' created in the top level diagram for a process has scope `0`, and is a different process variable to the variable 'myVar' created in a called diagram having, for example, a scope of '270'.

If you are not using Call Activities, all processes are running in their top level diagrams, all with scope = ‘0’, and you don’t need to worry about scope. If you are going to use Call Activities to next your diagrams, as a developer you need to be aware of and use variable scoping.

More information about Scope is contained in the Flows for APEX Concepts section, here. (link to be created).

Creating a Process Diagram that can be Called by Other Diagrams.

A Process Diagram should be able to be run as a process in its own right.

If you want to make a process diagram so that it can be called by a callActivity in another diagram, you should take the following steps with the called diagram:

1. Set the Process as Callable, using the switch in the General Tab of the diagram’s Process Object. This will make the ‘In/Out Variables’ tab appear.
2. Define the Interface properties of the Process in the ‘In/Out Variables’ tab. What process variables are required to be passed into the process, and what will be returned? (This is just like defining the in and out parameters on, for example, a PL/SQL procedure specification.)
3. Check that your expressions, scripts, etc., are scope aware.

Nesting of Call Activities

Diagrams can be nested in any arbitrary nesting structure of any complexity, proving that you do not create recursive loops, directly or indirectly.

Setting Boundary Events on Call Activities

A Call Activity can have the following boundary events attached to it:

• Interrupting Timer Boundary Event
• Non-Interrupting Timer Boundary Event
• Error Boundary Event (always interrupting)
• Interrupting Escalation Event
• Non-Interrupting Escalation Event

If the boundary event is interrupting and fires:

• processing inside the Call Activity is terminated.
• OutVariables are not returned by the Call Activity to the calling process.
• processing continues on the interruption path back in the calling process.

If the boundary event is non-interrupting and fires:

• processing inside the Call Activity continues.
• new processing occurs back in the calling process on the boundary event’s forward path.

Lanes and Call Activities.

Some BPMN diagrams contain Collaboration and Participant information, i.e., they contain Lanes and Lanesets; other diagrams just contain a Process, without lane information.

Call Activities are able to handle called and calling diagrams with or without lanes.

	Calling Diagram Without Lanes	Calling Diagram With Lanes
Called Diagram Without Lanes	No Lane Information is Available	All Tasks in the Called Diagram inherit the lane of the CallActivity from the Calling Diagram
Called Diagram With Lanes	Tasks in the Calling Diagram have no lane. Tasks from the Called Diagram contain lane information from the Called Diagram	Tasks in the Calling Diagram have lane information from the Calling Diagram. Tasks from the Called Diagram contain lane information from the Called Diagram.

If diagrams are nested in an arbitrary, complex fashion, these rules are applied from Calling to Called diagram at runtime, and are available through the task inbox view.

Note for Developers and Adminstrators on Resetting a Process Containing Call Activities.

Resetting a process instance with the flow_reset call resets a process instance back to its created state, ready to be started with flow_start. As previously documented, this is a convenience function on the API that is often useful during development, testing, and – very occasionally– during system administration. It is NOT designed to be used widely in production systems.

With a process that has Call Activities, instance creation builds a map of the process diagrams to be used, and the call structure of those diagrams for the new instance. This is stored in the FLOW_INSTANCE_DIAGRAMS table, with one row for each diagram call that will be made. Determination of which version of a diagram will be used for the instance is made at this time. As the process instance progesses, information about the diagram-level and variable scope to be used is added to this table when the diagram is called.

As a developer / administrator / tester, be aware that if you modify the diagrams or the callActivity nesting during administration or testing, you need to create a new process instance to get these changes! If you just reset an existing process instance, you return the instance to its previous created state and the call structure will not be updated. Remembering this will save you time and frustration!