Use Business Keys

Business keys are application specific identifiers that are used to tag related processes and tasks within an application. You can define business keys using the businessKey predefined variable under process data objects.

For example, a company can have multiple shipping orders tied to the same main order ID. When a process is started to ship an order, that process instance can be linked to the main order by using the main order ID as the business key. At a time, multiple shipping orders can occur. Using the business key, the company can track all shipping order process instances that are tied to the same order ID.

Set business key value in the start of a structured or dynamic process. In the Properties pane, specify the business key in the Business key field. You can use the in-built expression builder to set the business key. See Work with Expressions.

• Set a business key to a structured process that starts with a form or a message.
• Set a business key to a dynamic process that starts with a form.
• Propagate the business key to any task or child processes called by the process through data association.

Let us see how you can set a business key to a process and propagate it to a child process that is called by the main process.

1. Set the business key to the process start.
   1. Create a structured process that starts with a form.
   2. Select the start activity of the process, and open its Properties pane.
   3. Under the End User Display section, enter a name for the activity in the Title field.
   4. In the UI field, select a form to associate with the activity from the drop-down list.

      We’ll use a data object of this form to configure the business key.

   5. In the Business key field, enter an expression using the in-built expression builder. For example, bKStartFormArgs.orderID, where orderID is the data object of the Start form.
      
      Description of the illustration business-key.png
   6. Close the Properties pane to save the changes.
2. Create another structured process, and associate/tag the business key to it.
   1. Create a structured process that starts with an empty start event.
   2. Add a human task activity into the process flow.
   3. Open the Data Association editor for the human task. Click the human task, and from the menu that displays select Open Data Association.
   4. On the Data Association editor's Input tab, from the left Data Objects pane expand Predefined Variables, then drag and drop the businessKey variable into the Input field.
   5. From the right Data Objects pane, expand Process Data, then drag and drop the process data object you want to associate with the business key.

      In the example below, the orderID data object is associated with the businessKey predefined variable.

      
      Description of the illustration business-key-da.png

   6. Click Apply.
3. Propagate the business key to the called process.
   1. Open the first structured process where you defined the business key to the process start.
   2. In the Activity palette, expand System, and then drag and drop a Call Activity into the process flow.
   3. Select the call activity, then click Open Properties to open its Properties pane.
   4. Under Implementation, select the second structured process you created in step 2 from the drop-down list in the Process field.
   5. Select the check box Propagate business key when process is called.
   The business key that is set at the start of the parent process is propagated to the child called process.
4. Activate and run the process application to see how it works in run time.
   1. Click Activate.
   2. In the Activate dialog, click Test in Workspace.
   3. From the Start Requests page, select your application instance.
   4. In the application start form that appears, enter a value, for example 123456, in the Order ID field that is configured for the business key.
   5. Navigate to the Tracking page. Select Tracking from the workspace navigation menu options.
   6. All the process instances associated with the same reference ID are displayed. The reference ID’s value is same as the business key value you entered in the start form.
      
      Description of the illustration business-key-referid.png

The business key associated with a task is displayed in the My Tasks page. When you open a task, you can see if there is a business key associated with it under the More Information section.