Step 1: Mapping the Form Data

Follow Our Example User Story

David Stringer wants to display the related vendor name, item and quantity in the instance list. This data must be persisted so that it can be displayed in the instance list.

Good to Know: What is the meaning of "persisting data"?

Processes are based on data that is going in, is processed, and coming out. However, the application developer must determine which data can be accessed in which process step. Therefore, the execution diagram contains different sections:

Message: Section Message is shown for all BPMN elements that need to process an incoming message. As per default, the incoming message has type any . To gain access to the data used in your process, you have to apply the correct type from a customized library.
Persisted: Variables created in section Persisted are usable in all executions of the BPMN model. They are "persisted" during the execution of the entire process.
Local: Variables created in sectio Local are only available for use within the current execution. They are discarded when switching to the next process step.

Data that you want to be able to access throughout the process, you need to keep - this is the meaning of "persisting data".

If you want to learn more about how to persist data in the Designer, refer to Persisting Data in the Designer Guide.

Create Persisted Variables

In tutorial 1, you have created the service Order_approval_1. Open your service. It forms the basis for the following steps.

Click user task Enter web order to open its execution diagram:

In the service panel, expand folder Base Types, go to Bridge Base > Base Types and select type String from the list of available types:

Drag and drop it to the Persisted area. The newly created persisted variable should store the vendor name:

Double-click on the current name of the variable and change the name to vendorName:

vendorName: String

Proceed in the same way to create further persisted variables to store the information for item and quantity.

item: String
quantity: String

Create the Mapping

Follow Our Example User Story

To actually persist the incoming data from the form, David needs to map the information between the form input and the persisted variables.

This can easily be done with a mapping diagram.

Good to Know: What is mapping?

Data mapping is a very common task in the integration business: It is the process of connecting a data field from one source to a data field in another source. The Designer comes with a mapping editor that allows you to define attribute mappings directly in a mapping diagram by drawing relations between the properties of the involved classes.

Mapping diagrams are automatically created if you create a mapping operation on a class. The mapping diagram is based on the data model contained in the Implementation folder. It defines mappings between the data structures defined in this data model. You cannot change the data model in the mapping diagram, all attributes are read-only.

If you want to learn more about data mapping, refer to the chapters Modeling Data Mapping and Mapping Data Structures in the Designer Guide.

Create the Mapping Diagram

Go to the service panel and open package Mapping in folder Implementation. In class Shop, create a new mapping operation persistDataForInstanceList:

If you want to create new items in the Service Panel just hover over a folder (or its contents) and use the icons in the pop-up menu. To open the context menu of an item, right-click it in the tree.

Create the following parameters for the operation persistDataForInstanceList:

input parameter order of type WebShopOrder
output parameter vendorName of type String
output parameter item of type String
output parameter quantity of type String

Switch to the mapping diagram and expand the variable in the Input section:

Click the plus icon next to the items array to add an array element on the input side (item [0] in the picture). Then expand item [0] clicking the arrow icon:

Connect the corresponding data items of Input to the Output side with an object flow:

Refer to Modeling Data Mapping for more information on how to work with the Mapping Editor, and to Mapping Data Structures for reference information regarding data mapping with the Designer.

Add the Mapping Operation to the Process

Follow Our Example User Story

Now, David needs to add the mapping operation he created to his process in user task Enter web order.

Click user task Enter web order from your process to display the related UML diagram on the execution pane:

Select the operation persistDataForInstanceList you have created in the previous steps. Drag and drop the mapping operation to the activity flow in the execution diagram:

Pins on the left of the action node indicate needed incoming object flow, pins on the right indicate outgoing object flow. Operation persistDataForInstanceList needs an incoming object and provides three outgoing objects:

You need to provide the form data you want to map as input. Connect variable webShopOrder with pin order of the mapping operation:

Now connect the output pins of the mapping operation to the corresponding persisted variables vendorName, item and quantity:

While dragging the object flow, the Designer highlights all available targets in blue:

The form data now is persisted to three variables and therefore available throughout the process.

For more information on how to handle the execution editor, refer to Working with the Execution Editor in the Designer Guide. For more detailed information on operations in general and where you can use them, refer to Adding Operation Calls in the Designer Guide.