A common scenario when having Bizagi integrate with a Web or REST service, is to handle a response which is incoming as an Array of items.
This means, that you may need to store one or more record into your Process data model.
For this scenario in Bizagi, you may use the interfaces wizard and its graphical mapping feature to specify that such results are to be stored in a collection.
Append, Replace and Replace With Children
When mapping into a collection, you may also set if you wish to Append (A), Replace (R) or Replace With Children (RWC) the items into the collection.
By default, Bizagi will append items, meaning that the incoming records will be stored alongside any previously existing ones.
When mapping into a collection is set to Append, you will notice an A label in the collection's name:
When choosing to replace them, Bizagi will first delete any records contained in the collection.
When mapping into a collection is set to Replace, you will notice the R label in the collection's name:
When choosing the option Replace With Children, Bizagi will first delete any records contained in the sub-collections and finally, any records contained in the collection. To perform a recursive deletion, all the sub-collections within the collection has to be marked with this option.
When mapping into a collection is set to Replace With Children, you will notice the RWC label in the collection's name:
In the following example, we will invoke a Web service which returns an Array of available Products for a given customer.
First, use the interfaces wizard to configure the Service type, its URL, and method:
Click next and specify any input information for the invocation:
Now for your output parameters, make sure you identify both the collection in your data model and the incoming array of items.
You will need to map:
1.The output array representation of your service, into the collection in your Process data model.
2.Any additional information contained inside the array into the corresponding attributes inside the collection as well.
In our example, we map the ArrayOfProducts into our collection, and specify that the pname is to be stored into info1.
When mapping output parameters into collections, you may choose one of the following options
•Append: inserts the records in the response to the collection without deleting the existing ones.
•Replace: deletes the previous records and inserts the records in the response to the collection. If there are collections within the target collection (sub-collections), the records will remain in the database, but they will be disconnected.
•Replace with children: deletes the existing records including the records within sub-collections and inserts all records in the response to the collection. If there are collections within the target collection, we recommend to mark Replace with children.
Notice that by default, Bizagi will Append these records.
Double click at the name of your collection:
When changing this setting and clicking OK, you will notice that the label will automatically show you the changed configuration:
Finally, configure Error handling if any (in this example we skip this step and click on Finish).
In some scenarios, a Web service may not necessarily define an entity element contained in the collection element (XML-represented), and instead just have the 1-n inner elements spread directly inside the collection.
For these scenarios, it is important that you explicitly map in Bizagi the entity element instead (in our previous example, that would mean mapping the Products entity to the returnedcollection collection).