Step-By-Step Business Process Setup

For example, let’s create a business process for processing a dwarf transformation request. In the Hydra OMS we'll set up the following fields:

Hydra OMS user can confirm the request or reject it:

  1. Request denied: order processing is completed.
  2. Request confirmed:
    • the request acceptance message and the fields are displayed for reading only,
    • order processing is completed.

Creating New Order Type and Importing It into the Hydra OMS

To create and activate a new order type — Transformation Request — first you must describe its configuration in a file with the same name (see the Orders Types section):

common: &common type: string order_type: code: transformation_request name: Transformation Request fields: requesterName: <<: *common label: Requester Name hatColor: <<: *common label: Hat Color comment: <<: *common label: Comment resolution: <<: *common label: Resolution

The order type code (transformation_request) and the name displayed in the interface (Transformation Request) are specified here.

The following data is stored in the order:

The system utilizes the pattern common for the field type (string) and determines the displayed name (label) for each field displayed on the interface.

Upload the given configuration into the Hydra OMS and activate the new order type Transformation Request (see Loading Order Types in the Hydra OMS Application):

Creating New Business Process and Importing It into the BPM System

Business Process Creation in the Eclipse Development Environment

The Eclipse IDE together with the Activiti Designer plug-in are utilized for business process diagram creation (as it was described in the Business Process Configuration section). Let's start with the general parameters setup:

This business process has the transformationRequestProcess code (used in the BPM widget configuration file hbw.yml) and the Transformation Request name.

In order to keep logs and autosave changes of the order add event listeners in the process configuration (org.activiti.latera.bss.eventListeners.EventLogging and org.activiti.latera.homs.eventListeners.AutoSaveOrderData respectively). […] <process id="transformationRequestProcess" name="Transformation Process" isExecutable="true"> <extensionElements> <activiti:eventListener events="ACTIVITY_CANCELLED,ACTIVITY_COMPENSATE,ACTIVITY_COMPLETED,ACTIVITY_ERROR_RECEIVED,ACTIVITY_MESSAGE_RECEIVED,ACTIVITY_SIGNALED,ACTIVITY_STARTED,ENTITY_ACTIVATED,ENTITY_CREATED,ENTITY_DELETED,ENTITY_INITIALIZED,ENTITY_SUSPENDED,ENTITY_UPDATED" class="org.activiti.latera.bss.eventListeners.EventLogging"></activiti:eventListener> <activiti:eventListener events="ACTIVITY_COMPLETED" class="org.activiti.latera.homs.eventListeners.AutoSaveOrderData"></activiti:eventListener> </extensionElements> […]

The process of business process diagram creation and configuration is described below.

It begins with the Start block. At the same time, the logging is initialized with the listener org.activiti.latera.bss.executionListeners.InitLogging, which allows listener org.activiti.latera.bss.eventListeners.EventLogging to log events for the process:

The rules for the BPM system and the Hydra OMS API interaction are defined within the task named Set Process Parameters:

The following listeners start order processing and retrieve order data:

Now let’s add the Handle Request task. The process initiator is set by the initiator variable and the screen form of the task is displayed on the interface as described in the configuration file named handle_request.yml (the configuration itself is discussed below):

Now we are going to define the Handle Request task form configuration as described in the User Task Forms Configuration in the BPM Widget section.

This form contains: customer name field, query fields group and decision making buttons. The BPM widget form field names correspond to the names specified in the transformation_request order type configuration. Thus, the prefix homsOrderData is added to the names in the lowerCamelCase style.

form: css_class: col-xs-12 col-sm-6 col-md-5 col-lg-4 fields: - name: homsOrderDataRequesterName label: Requester Name type: string css_class: col-xs-12 col-sm-6 col-md-4 - name: parameters type: group label: Choose parameters of your transformation css_class: col-xs-12 fields: - name: homsOrderDataHatColor label: Choose color of the hat type: select css_class: col-xs-12 col-sm-6 col-md-4 choices: - Red hat - Green hat nullable: false - name: homsOrderDataComment type: text rows: 3 label: You can write additional details css_class: col-xs-12 - name: homsOrderDataResolution type: submit_select css_class: col-xs-12 options: - name: Do Magic! value: Do Magic css_class: btn btn-success btn-lg - name: Cancel Request value: Canceled css_class: btn btn-danger btn-lg

The homsOrderDataRequesterName customer name field is stored in the string type. The group parameters has two fields: homsOrderDataHatColor and homsOrderDataComment. The first one is intended for the hat color selection (red or green) and is stored in the select type. Since the choice is mandatory, empty field is prohibited (nullable: false). Here we use the text type field with three rows for entering additional wishes in homsOrderDataComment. Once order fields are filled in, the request can be accepted or rejected with the homsOrderDataResolution buttons of the submit_select type. This type allows simultaneous form and button values submitting. Both choices are described in the options attribute by specifying displayed name (name) and value (value). The value is recorded in the order field named Resolution (described in the order type configuration) on the appropriate button click: Do Magic! or Cancel Request.

CSS classes essential (by css_class attributes) to display order fields correctly are applied within the Handle Request task.

Similarly, Show Request task will be assigned to the initiator of the process, while the configuration with the form definition will be set up in the show_request.yml file.

At this stage, the user is notified that the customer request is accepted and the transformation will occur within the 24 hour period. The user can view the fields in the read-only mode (editable: false option). Configuration form of the Show Request task looks like this:

form: css_class: col-xs-12 col-sm-6 col-md-5 col-lg-4 fields: - name: homsOrderDataRequesterName label: Requester Name type: string css_class: col-xs-12 col-sm-6 col-md-4 editable: false - name: parameters type: group label: Thanks for the request! Your transformation into gnome will be done within 24 hours with those parameters css_class: col-xs-12 fields: - name: homsOrderDataHatColor label: Color of the hat type: select css_class: col-xs-12 col-sm-6 col-md-4 choices: - Red hat - Green hat editable: false - name: homsOrderDataComment type: text rows: 3 label: Additional details css_class: col-xs-12 editable: false

The standard Submit button is added automatically as there are no buttons described in this configuration. Click on this button to go to the next step of the business process (i. e. completion).

The branching is added by the excluding gateway that allows you to select one of the options: to accept or reject the request.

If the user chooses to click the Do Magic! button in the Handle Request step its value is recorded in the Resolution order field (as specified in the configuration file handle_request.yml). The business process goes to the Show Request task.

This condition is specified in the Condition field of the Main Config section for this branch:

If the user clicks the Cancel Request button the Canceled value is recorded in the Resolution order field. It’s recognizsed by the BPM system as business process completion criteria.

At the bottom of the business process the order completion date is set up using the org.activiti.latera.homs.executionListeners.FinishOrder listener:

Uploading the Configuration Files to the BPM System

Once the business process diagram is established with the all necessary settings and the configuration files of user task forms are prepared, you need to upload them to the BPM system to start order processing.

You should add the TransformationRequestProcess.bpmn file (business process diagram created in the Eclipse IDE), handle_request.yml file and show_request.yml file in a single ZIP -file and upload it to the Deployments section of the BPM system.

Mapping Order Types to Business Processes

The method of matching orders types to their potential business process is described in the Business Process and Order Types Matching section. You can describe the order type matching to transformation_request start button of the created business process with transformationRequestProcess code in the widget configuration file (hbw.yml):

hbw: bp_toolbar: transformation_request: - name: 'Handle transformation request' title: 'Start handle transformation process' class: 'btn btn-default' fa_class: 'fa fa-exchange' bp_code: 'transformationRequestProcess'

Order Processing in the Hydra OMS

You can create a new order in one of two ways:

  1. Using the API and the following commands: $ curl -H "Content-Type: application/json" --data '{"order": {"order_type_code": "transformation_request", "data": {"requesterName": "Pinkman Jesse"}}}' --user user@example.com:exampleAPItoken http://homs.example.com/api/orders

    In this example transformation_request — is the code of order type; user@example.com, user@example.com, exampleAPItoken — email and API token for the user of the Hydra OMS and the BPM system; http://homs.example.com/api/orders — order processing API URL. You can specify a custom order field in the data block, in this case — the name of the customer, Pinkman Jesse.

    If the order is successfully created, you get a response with the order fields:

    { "order": { "id": 27, "code": "ORD-27", "ext_code": null, "bp_id": null, "bp_state": null, "state": "to_execute", "archived": false, "data": { "requesterName": "Pinkman Jesse", "hatColor": null, "comment": null, "resolution": null }, "done_at": null, "order_type_code": "transformation_request", "user_email": null } }

    Here is the documentation for the Hydra OMS API: http://hydra-oms.com/api/.

  2. Directly at the Hydra OMS interface using the Add button in the Orders section:

To start the order processing in the first case you must find it in the Orders section by the code specified in code field from the API response. In the second case, you will be automatically redirected to the created order:

To run the business process, click on the Handle Transformation Request button defined earlier in the configuration file hbw.yml. Then you will see the first custom task form (Handle Request):

Assume that the customer has changed his mind and he wants to cancel the request.Click on the Cancel Request button and complete the business process:

The date of the business process completion is set in the Completed at field. The Resolution field stores the Cancelled value so the Hat Color field and Comment field are empty.

To re-start the business process, you should click the Handle Transformation Request button. To make changes to the order manually use the Edit button.

Let’s re-start the process and take a look at the alternative outcome.

Assume that our customer is ready to be transformed into a dwarf. He prefers the green hat and would like to have a thick beard after the transformation. In this case, choose the Green hat in the Choose color of the hat field and write a corresponding comment in the Comment field. Click the Do Magic! button and follow to the next stage of the business process.

The request is accepted, it is reported in the BPM widget form and all details are recorded in the order fields (Hat Color, Comment, and Resolution). Complete the process by clicking the Submit button.

The order processing is completed; all the fields are saved and the current date is set up in the Completed at field: