Several types of process elements, namely the [Read data] and [Call web-service], can have outgoing parameters of the “Collection” type. To be able to work with the collection “instances” (separate records within a collection) the collection needs to be processed.
There are several ways of processing a collection:
-
Pass a collection of records to another parameter of a “collection” type. For example, you can pass a collection of records to a [Call web-service] element that has a collection in its request parameters.
-
Use the [Script task] element to process the parameters of the “collection” type. For example, you can use a C# script to parse the collections of records into separate records that can be passed to other process element to handle each instance of a collection in a separate instance of the sub-process. If any of the incoming parameters of the [Sub-process] element are mapped to a data collection, the element will automatically run a separate instance of the sub-process per each instance of the collection.
Using sub-processes to handle “collection” parameters
Using sub-processes is the preferable method for working with collections, as it does not involve coding like the [Script task] and is not limited by the capabilities of a third-party web service, like [Call web service].
The general procedure for processing a collection via the [Sub-process] element is as follows:
-
Prepare a process that will handle collection instances (this process will be used as s sub-process).
-
Add the [Sub-process] element in the parent process and select the prepared sub-process.
Prepare the process that will handle collection instances
Create or modify a process that will work with a collection instance as if it were a single record. For example, to send an email to a collection of contacts, prepare a process to send email to a single contact (Fig. 1).
The incoming parameters of the sub-process must match the nested parameters of the collection. For example, sending an email requires the contact’s email address. This means that the collection must include the [Email] column, while the process for sending email must have corresponding incoming [Email] parameter, whose value is then passed to the [Send email] element.
Note
You can access subprocess diagram “on the go”, while working with the parent process, by clicking (to create a new subprocess) or (to edit the current subprocess) in the [Which process to run] field of the [Sub-process] element. Read more in the “[Sub-process] element parameters“ article.
Set up the [Sub-process] element
Add the [Subprocess] element on the diagram of the process where a collection parameter is obtained. Select a process that will handle collections instances in the [Which process to run?] field and map the incoming parameters of the selected process (Fig. 2):
Attention
Parameters of each [Sub-process] element can only be mapped to the same collection. Map additional process parameters to element parameters from the same data collection as the already mapped process parameters or map additional process parameters to non-collection element parameters.
As a result, the [Sub-process] element will loop through the data collection. A separate process instance will be launched for each item in the data collection.
The sub-process instances run successively; a new sub-process instance runs upon completion of the previous instance. Upon completion of the last instance, the [Sub-process] element will update its outgoing and bidirectional parameter values from the corresponding parameters of the completed sub-process instance and activate its outgoing flows.
See also