Task 4. Modeling a business process with a start form and dependent form components

1. Goal

The goal of this task is to learn how to:

  • Model a business process with a start form.

  • Model forms with dependent components and an Edit Grid component.

2. Prerequisites

Before you start working on the task, complete these prerequisite steps:

3. Task steps

3.1. Modeling the business process

At the business process modeling stage, you need to create and save the corresponding BPMN diagram.

Download the add-personnel.bpmn file with a sample business process schema to use as an example.

3.1.1. Business process modeling stages

Use the following checklist to track the steps of the modeling process.

After completing all the steps, be sure to save the business process schema you modeled to the appropriate folder with the registry regulations.

3.1.2. Creating a pool for the business process

To model a pool for your business process, perform the following steps:

  1. Open the Camunda Modeler app and create a new BPMN diagram. To do this, open the menu in the upper left corner and click File > New File > BPMN Diagram.

  2. In the toolbar on the left, find the Create pool/Participant item and drag it to the modeling panel. Fill out the following fields in the General tab:

    • Name: Enter the task’s name — for example, Add personnel data.

    • Process Id: Enter the process ID — for example, add-personnel.

    • Process Name: Enter the process name — for example, Add personnel data.

task 4 1 bp

3.1.3. Creating a start event

To create a start event, perform the following steps:

  1. In the toolbar on the left, find the CreateStartEvent item (a circle) and drag it to the modeling panel.

  2. In the properties panel on the right, fill out the following parameters in the General tab:

    • Id: Enter event ID — for example, start_event.

    • Name: Enter the event’s name — for example, Start process.

    • Initiator: Enter initiator. This variable will contain information about the user who started the business process.

      task 4 2 bp

  3. In the Forms tab > Form key field, enter shared-search-lab:

task 4 3 bp

3.1.4. Create a script task to prepare variables for records

Fill out the following fields:

  • Id: extractLabIdFromFormActivity

  • Name: Prepare variables for records

  • Script Format: groovy

  • Script Type: InlineScript

  • Result Variable: laboratoryId

Script 
submission('start_event').formData.prop('laboratory').prop('laboratoryId').value()

task 4 4 bp

3.1.5. Creating a service task to search lab data

To create a service task to search lab data, perform the following steps:

  1. Set the task type by clicking the wrench icon and selecting Service Task from the menu.

  2. Click Open Catalog, select the Read entity from data factory template, and click Apply.

  3. Fill out the following fields:

    • Id: Enter searchLabInDataFactoryActivity.

    • Name: Enter the task’s name — for example, Search lab data.

    • Resource: Enter laboratory.

    • Resource id: Enter ${laboratoryId}.

    • X-Access-Token: Enter ${initiator().accessToken}.

      After the first user task, it is preferable to use the completer('<task_id>') function to get user data instead of initiator().

      The access token is taken either from the initiator (for example, $initiator().accessToken}) or the completer of the last user task (for example, ${completer('taskDefinitionId').accessToken}).

      The JWT token has a validity period of 300 seconds. If you specify the token of the initiator of the business process, and the user takes a long time to do the task, then the token will expire, and the business process must be restarted.

      For details on the JUEL functions, see JUEL functions in business processes.

    • Result Variable: Enter labResponse.

task 4 5 bp

3.1.6. Creating a script task to prepare document data for display (transient var)

Fill out the following fields:

  • Id: extractAddPersonnelFormPrepopulationActivity

  • Name: Prepare document data for display (transient var)

  • Script Format: groovy

  • Script Type: InlineScript

Script 
var name = labResponse.responseBody.prop('name').value()
var edrpou = labResponse.responseBody.prop('edrpou').value()
var cephData = ['edrpou':edrpou,'name':name]
execution.removeVariable('payload')
set_transient_variable('payload', S(cephData, 'application/json'))

task 4 6 bp

3.1.7. Creating an error handling event

  1. Drag the Intermediate/Boundary event item from the toolbar on the left and add it to the "Search lab data" service task.

    task 4 12 bp

  2. Click the wrench icon and select the Error Boundary Event type from the menu.

    task 4 13 bp

  3. Create a Gateway that will act as a checkpoint for redirecting in case of an error.

    task 4 14 bp

  4. Add error handling logic by connecting the Error Boundary Event and the XOR Gateway. This way, if an error occurs at the "Search lab data" stage, the user will automatically return to the checkpoint, from where the process will start again.

    task 4 15 bp

The DOC and Data Factory modeling components with the dashed lines in the example are purely demonstrational. This instruction does not cover how to create them.

3.1.8. Creating a user task to add personnel data

  1. Set the task type by clicking the wrench icon and selecting User Task from the menu.

  2. Click Open Catalog, select the User Form template, and click Apply.

  3. Fill out the following fields:

    • Id: addPersonnelFormActivity

    • Name: Add personnel data

    • Form key: add-personnel-bp-add-personnel

    • Assignee: ${initiator}

    • Form data pre-population: ${payload}

task 4 7 bp

3.1.9. Creating a user task to sign data with an electronic signature

  1. Set the task type by clicking the wrench icon and selecting User Task from the menu.

  2. Click Open Catalog, select the Officer Sign Task template, and click Apply.

  3. Fill out the following fields:

    • Id: signPersonnelFormActivity

    • Name: Sign data with QES

    • Form key: add-personnel-bp-sign-personnel

    • Assignee: ${initiator}

    • Form data pre-population: ${submission('addPersonnelFormActivity').formData}

task 4 8 bp

3.1.10. Creating a script task to prepare data for saving (transient var)

Fill out the following fields:

  • Id: convertSignFormDataToDataFactoryFormatActivity

  • Name: Prepare data for saving (transient var)

  • Script Format: groovy

  • Script Type: InlineScript

Script 
def personnelGrid = submission('signPersonnelFormActivity').formData.prop('personnelGrid').elements()
for (var personnel : personnelGrid) {
personnel.prop("laboratoryId", laboratoryId)
personnel.prop("staffStatusId", personnel.prop("staffStatus").prop("staffStatusId").value())
personnel.deleteProp("staffStatus")
if (personnel.hasProp('hygienistCertificateFile') && !personnel.prop('hygienistCertificateFile').elements().isEmpty()) {
def hygienistCertificateFile = personnel.prop('hygienistCertificateFile').elements().first()
} else {
personnel.prop('hygienistCertificateFile', null as String)
}
if (personnel.hasProp('ordersFile') && !personnel.prop('ordersFile').elements().isEmpty()) {
def ordersFile = personnel.prop('ordersFile').elements().first()
personnel.prop('ordersFile', ordersFile)
} else {
  personnel.prop('ordersFile', null as String)
}
if (personnel.hasProp('hireStaffFile') && !personnel.prop('hireStaffFile').elements().isEmpty()) {
def hireStaffFile = personnel.prop('hireStaffFile').elements().first()
} else {
personnel.prop('hireStaffFile', null as String)
}
}
execution.removeVariable('dataPayload')
set_transient_variable('dataPayload', S(personnelGrid.toString()))

task 4 9 bp

3.1.11. Creating a service task to save data to the data factory

  1. Create a new service task by clicking the wrench icon and selecting Service Task from the menu.

  2. Click Open Catalog, select the Batch creation of entities in data factory template, and click Apply.

  3. Fill out the following fields:

    • Id: createStaffInDataFactoryActivity

    • Name: Save data to data factory

    • Resource: staff

    • Payload: ${dataPayload}

    • X-Access-Token: ${completer('signPersonnelFormActivity').accessToken}

      After the first user task, it is preferable to use the completer('<task_id>') function to get user data instead of initiator().

      The access token is taken either from the initiator (for example, $initiator().accessToken}) or the completer of the last user task (for example, ${completer('taskDefinitionId').accessToken}).

      The JWT token has a validity period of 300 seconds. If you specify the token of the initiator of the business process, and the user takes a long time to do the task, then the token will expire, and the business process must be restarted.

      For details on the JUEL functions, see JUEL functions in business processes.

    • X-Digital-Signature source: ${sign_submission('signPersonnelFormActivity').signatureDocumentId}

    • Result Variable: response

task 4 10 bp

3.1.12. Creating a service task to set the business process result

  1. Create a new service task by clicking the wrench icon and selecting Service Task from the menu.

  2. Click Open Catalog, select the Define business process status template, and click Apply.

  3. Fill out the following fields:

    • Id: defineBusinessProcessStatusActivity

    • Name: "Personnel data added" execution result

    • Status: Personnel data added

task 4 11 bp

3.1.13. Creating an end event

Name the end event:

  • Name: Data added.

3.2. Modeling forms

During the forms modeling stage, you need to create and connect JSON forms to the business process tasks you modeled previously.

The forms are connected to business processes using the service name.

Use the add-personnel-bp-add-personnel.json, add-personnel-bp-sign-personnel.json, and shared-search-lab.json sample files with form examples.

3.2.1. Creating a form to search lab data

We recommend using the Google Chrome browser for this task.

First, you need to create a form where users can enter data. Perform the following steps:

  1. Sign in to the regulations administrator portal.

    admin portal form modeling step 1

  2. By default, the portal opens the master version of the regulations, displaying the forms that were already deployed. At this point, it will be empty.

    In the master version, forms are available in read-only mode and cannot be edited.

    To add and edit forms, you need to create a version candidate by selecting the Create new request item from the menu in the upper left corner.

    task 1 16 forms

  3. In the Create new request window, fill out the following fields:

    • Version name: Enter task-4.

    • Version description: Enter Creating forms for task 4.

      Click the Create button.

      task 4 32 forms

      After you create a request, the portal automatically redirects you to the version candidate, where you can add and edit forms.

  4. Go to the UI forms section. To create a new form for the business process, click the Create new form button.

    task 1 18 forms

  5. In the dialog window, fill out the following fields:

    • Form’s business name: Enter the name of the appropriate user task — Search lab data.

    • Form’s service name: Enter shared-search-lab.

    task 4 35 forms

  6. Go to the Build tab.

    We recommend using the components from the Updated section.

  7. From the panel on the left, drag the Text Field component onto the modeling canvas and configure the following parameters:

    task 4 36 forms

    • In the Display tab > Label field, enter EDRPOU:

      task 4 37 forms

    • In the API tab > Property Name field, enter edrpou.

      task 4 38 forms

      By default, the value of the Property Name field is identical to the Label field. Unlike the Label field, the Property Name field can only contain Latin letters.

    • In the Validation tab, select the Required checkbox to make the field mandatory. Click Save to save your changes.

      task 4 39 forms

  8. From the panel on the left, drag the Select component onto the modeling canvas and configure the following parameters:

    • In the Display tab > Label field, enter Lab name:

      task 4 40 forms

    • In the Data tab > Data Source Type field, select URL.

      • In the Data Source URL field, enter the following value:

        /api/data-factory/laboratory-start-with-edrpou-contains-name

        This is a reference to the previously created endpoint of the laboratory_start_with_edrpou_contains_name search condition in the data model.

      • Select the Lazy Load Data checkbox so that the valid values for the current Select component are updated each time it is accessed.

        task 4 41 forms

      • In the Value Property field, enter laboratoryId.

      • In the Filter Query field, enter edrpou={{data.edrpou}}.

      • In the Limit field, enter 100. This limits the search to the first 100 results. When used correctly, restrictions like this will help reduce the load on the registry systems.

      • In the Item Template field, enter <span>{{ item.name }}</span>.

        The {{ item.name }} value contains the following:

        • item: The current object from the list of found laboratories.

        • name: The object’s name.

        In this field, you specify what will be shown in the select query. In other words, the /api/data-factory/laboratory-start-with-edrpou-contains-name endpoint will return an array of found item objects in the following format:

        {
    "laboratoryId": "466ad903-7bd0-4078-9f80-972ed66780a8",
    "edrpou": "12345678",
    "name": "Lab Name"
}

        To display laboratory names in the dropdown list of the select query, specify the name field: (<span>{{ item.name }}</span>).

        Similarly, if you need to display the edrpou code of each laboratory in the dropdown list, indicate the edrpou field: {{ item.edrpou }}.

      • In the Refresh Options On field, select EDRPOU. This makes the select request dependent on the preceding EDRPOU field and will reset the previously selected value when the value specified in the EDRPOU field changes.

        For details on the Refresh Options On function, see Using the "Refresh Options On" function in the updated Select component.

    • In the Validation tab, select the Required checkbox to make the field mandatory.

      task 4 43 forms

    • In the API tab > Property Name field, enter laboratory. Click Save to save your changes.

      task 4 44 forms

3.2.2. Modeling uniform entities on the forms using Edit Grid

3.2.2.1. Creating a form to enter data about new personnel

  1. Go to the UI forms section. To create a new form for the business process, click the Create new form button.

    task 1 18 forms

  2. In the dialog window, fill out the following fields:

    • Form’s business name: Enter the name of the appropriate user task — Add personnel data.

    • Form’s service name: Enter add-personnel-bp-add-personnel.

    task 4 33 forms

  3. Go to the Build tab.

    We recommend using the components from the Updated section.

Using Edit Grid, you can add and edit uniform data on your forms.

  1. From the panel on the left, drag the Edit Grid component onto the modeling canvas and configure the following parameters:

    • In the Display tab > Label field, enter Add personnel data:

      task 4 12 forms

    • In the Templates tab, fill out the following fields:

      • Add Another Text: Add

      • Save Row Text: Add record

      • Remove Row Text: Delete record

        task 4 13 forms

    • In the API tab > Property Name field, enter personnelGrid.

  2. Click Save to save your changes.

    task 4 14 forms

  3. Add components to Edit Grid.

    1. From the panel on the left, drag the Text Field component onto the Edit Grid field and configure the following parameters:

      • In the Display tab > Label field, enter Full name:

        task 4 15 forms

      • In the API tab > Property Name field, enter fullName.

      • Click Save to save your changes.

        task 4 16 forms

    2. From the panel on the left, drag the Checkbox component onto the Edit Grid field and configure the following parameters:

      • In the Display tab > Label field, enter Occupational hygienist:

        task 4 17 forms

      • In the API tab > Property Name field, enter hygienistFlag.

      • Click Save to save your changes.

        task 4 18 forms

3.2.2.2. Configuring the display of one component based on the value of another component

  1. From the panel on the left, drag the Date/Time component onto the Edit Grid field and configure the following parameters to retrieve information from the directory:

    • In the Display tab > Label field, enter Date of specialization completion.

    • In the Format field, enter yyyy-MM-dd::

      task 4 45 forms

    • In the Time tab, clear the Enable Time Input checkbox — we don’t need it for the current task.

      task 4 46 forms

    • In the API tab > Property Name field, enter specializationDate.

      task 4 47 forms

    • In the Conditional tab, fill out the following fields:

      • This component should Display: True

      • When the form component: Occupational hygienist (personnel.Grid.hygienistFlag)

      • Has the value: true

        This way, the component will be displayed only when the Occupational hygienist (personnel.Grid.hygienistFlag) component is true.

        task 4 48 forms

    • Click Save to save your changes.

  2. Drag and configure the following additional components to the form:

    • Radio component:

      • Display tab > Label field: Employment type

      • Data tab > Values > Label field: Full-time; Value field: true

      • Data tab > Values > Label field: Part-time; Value field: false

      • API tab > Property Name field: fullTimeFlag

    • Number component:

      • Display tab > Label field: Salary

      • Validation tab > Minimum value field: 1

      • API tab > Property Name field: salary

    • Day component:

      • Display tab > Label field: Date of status change

      • API tab > Property Name field: dismissalDate

  3. From the panel on the left, drag the Select component onto the Edit Grid field and configure the following parameters to retrieve information from the directory:

    • In the Display tab > Label field, enter Employee status.

    • In the Data tab, fill out the following fields:

      • Data Source Type: URL

      • Data Source URL: /api/data-factory/staff-contains-name, where:

        • /api/data-factory/ is the data factory path

        • staff-contains-name is the name of the search condition to retrieve data from the domain directory that was modeled and added to the repository

      • Value Property: staffStatusId

      • Item Template: <span>{{ item.name }}</span>, where name is the name of the parameter that returns the search condition and will be displayed on the form:

        task 4 22 forms

        task 4 23 forms

    • In the API tab > Property Name field, enter staffStatus.

    • Click Save to save your changes.

  4. From the panel on the left, drag the Checkbox component onto the Edit Grid field and configure the following parameters:

    • In the Display tab > Label field, enter Fixed-term employment contract.

    • In the API tab > Property Name field, enter fixedTermContractFlag.

    • Click Save to save your changes.

      task 4 24 forms

      task 4 25 forms

  5. From the panel on the left, drag the Day component onto the Edit Grid field and configure the following parameters:

    • In the Display tab > Label field, enter Contract end date.

      task 4 26 forms

    • In the API tab > Property Name field, enter contractEndDate.

      task 4 27 forms

    • In the Conditional tab, fill out the following fields:

      • This component should Display: True

      • When the form component: Fixed-term employment contract (personnelGrid.fixedTermContractFlag)

      • Has the value: true

        This way, the component will be displayed only when the Fixed-term employment contract (personnelGrid.fixedTermContractFlag) component is true.

    • Click Save to save your changes.

      task 4 28 forms

  6. From the panel on the left, drag the Text Field components outside the Edit Grid field and configure the following parameters:

    • For the first Text Field component:

      • In the Display tab:

        • In the Label field, enter Full name of the lab or sole proprietor.

        • Set the Disabled checkbox to true.

      • In the API tab > Property Name field, enter name.

    • For the second Text Field component:

      • In the Display tab:

        • In the Label field, enter EDRPOU or RNOKPP code.

        • Set the Disabled checkbox to true.

      • In the API tab > Property Name field, enter edrpou.

    • These fields will contain data from the business process.

  7. Save your form by clicking the Create form button in the upper right corner.

    task 4 29 forms

    To display fields as columns inside the Edit Grid component, open the field’s settings and select the Table View checkbox in the Display tab. When this checkbox is selected, the field is displayed in a separate column.

    task 4 50 forms

    task 4 49 forms

3.2.3. Creating a form to sign data

After you create a form to enter data, create one more form to sign data.

Copy the form you modeled previously using the copy icon — this way, you can create a form from a template.

task 4 34 forms

Configure the form’s parameters:

  • Form’s business name: Enter the name of the user task — Sign personnel data.

  • Form’s service name: Enter add-personnel-bp-sign-personnel.

  • For all components:

    • In the Display tab, select the Disabled checkbox.

    • Click Save to save your changes.

3.2.4. Saving the business process forms

  1. Save your form by clicking the Create form button in the upper right corner.

  2. Download your forms by clicking the download icon.

    task 4 31 forms

  3. Copy them to the forms regulations folder of your project in the local Gerrit repository.

3.3. Modeling business process access

At this stage, you need to grant access to the business process from the officer portal for the standard officer role.

Access parameters are configured via the officer.yml file from the bp-auth folder.

Edit the bp-auth/officer.yml file by adding the following parameters:

Configuring access to the business process from the officer portal
authorization:
  realm: 'officer'
  process_definitions:
    - process_definition_id: 'add-lab-test'
      process_name: 'Creating a laboratory'
      process_description: 'Laboratory creation regulations'
      roles:
        - officer
    - process_definition_id: 'add-lab'
      process_name: 'Creating a laboratory'
      process_description: 'Laboratory creation regulations'
      roles:
        - officer
    - process_definition_id: 'add-personnel'
      process_name: 'Entering personnel data'
      process_description: 'Entering personnel data'
      roles:
        - officer

3.3.1. Saving the access config file

Save the officer.yml file to the bp-auth regulations folder of your project in the local Gerrit repository.

4. Uploading the regulations files to a remote Gerrit repository

To successfully deploy the business process with forms and apply the correct access settings in the target environment, the regulations administrator must upload the locally stored registry regulations files to the remote Gerrit code repository.

To do this, perform the steps described in the following topic: Deploying registry regulations in Gerrit.