Launching a business process by schedule

🌐 This document is available in both English and Ukrainian. Use the language toggle in the top right corner to switch between versions.

1. General overview

This page demonstrates an example of implementing and launching a business process that is automatically activated according to a schedule using the Timer BPMN element. The process initiates itself at a specified time and performs tasks according to a defined sequence.

A reference business process has been created to help registry developers and modelers to better understand and effectively use timers.

2. Reference example

Where can I find an example of a reference business process?

The Platform administrator can deploy for you a demo-registry  — a reference registry containing reference and other example files for creating a digital registry regulations. It includes various elements for developing data models, business processes, UI forms, analytical reporting, extracts, notifications, external integrations, and more.

Detailed instructions on deploying the demo-registry and obtaining reference modeling examples can be found on page Deploying demo registry with reference examples.

An example of a BPMN process diagram will be available in the demo-registry’s regulations by searching for the keywords — automatic-external-system-data-saving. The names of the forms can be found inside the corresponding User Tasks of the business process in the Form key field.

2.1. Brief overview of process components and their purpose

  1. Start Event with the timer — initiates the business process at a set time, daily from Monday to Friday at 8:00.

  2. Script—retrieves data from an external system and creates an object for further storage.

  3. Data signing with a system key — ensures that the data received from the external system is authentic and intact.

  4. Entity creation in the database — stores the received data in the database.

  5. Setting the business process status — indicates the successful completion of the business process.

  6. End Event — marks the end of the business process.

2.2. Modeling

  1. Log in to the Administrative portal.

  2. Open the Process models section.

  3. Create a new business process. Enter business and service name for this process. Go to the Builder tab.

    bp timer launch 1

  4. Model a pool for the business process.

    bp timer launch 2

  5. Create a Start event starting event and perform the following settings:

    1. Enter the task name, for example, Start.

    2. In the Timer section, set the schedule for starting and executing the business process.

    3. In the Type field (Timer Definition Type), specify the timer type - Cycle.

      The Cycle option allows you to configure recurring processes or events based on a specific time interval. A cyclic timer can be set at the level of a start event, intermediate event, or boundary event associated with a task performer.

      For more details on timer types, refer to Timer Event.

    4. In the Value field, specify the schedule in a specific format for process execution. For example, 0 8 * * MON-FRI.

      You can configure a cyclic timer using the standard ISO 8601 format for repeat intervals or a cron expression.

      Examples of values for the ISO 8601 format:

      • R5/PT10S — every 10 seconds, up to 5 times.

      • R/P1D — daily, indefinitely.

      Examples of values for the cron format:

      • 0 8 * * MON-FRI:

        0: minutes (exactly at 0 minutes)
8: hours (8:00 in the morning)
*: day of the month (any day of the month)
*: month (any month)
MON-FRI: day of the week (Monday - Friday)

      Thus, the above cron expression means that the process will be triggered every day from Monday to Friday at 8:00 in the morning.

      • 0 0 9-17 * * MON-FRI:

      This cron expression means that the process will be triggered every hour from 9 to 17 UTC time from Monday to Friday.

    5. Specify the process initiator as initiator.

      What is an initiator?

      The phrase "Start initiator = initiator" indicates that the value of the initiator (i.e., the person or system that initiated the process) will be set as the initiator.

      In the context of business processes, the initiator is the person who starts the process or is responsible for its initiation. Typically, the initiator is a user who triggers an action or a system that automatically initiates the process.

      In this case, the term initiator can be used to identify the person or system that initiated the process in subsequent stages of the business process or for access control to resources.

      bp timer launch 3

  6. Create a script task and use the script to retrieve and process data. To do this, open the visual code editor (for more information about the code editor, refer to Editing business process scripts in a visual code editor).

    In our example, we retrieve data from another system.

    bp timer launch 4

    Script for data retrieval and processing 
    import java.text.SimpleDateFormat;
import java.util.Date;

SimpleDateFormat date = new SimpleDateFormat("dd_MM_yyyy")
String url = 'https://wallpapercave.com/wp/wp2601438.jpg'
String fileName = 'file_'.concat(date.format(new Date())).concat('.jpeg')
def documentMetadata = save_digital_document_from_url(url, fileName)

def payload = [:]
def listFileObj = []
payload.name = fileName
def fileObj = [:]
fileObj.id = documentMetadata.id
fileObj.checksum = documentMetadata.checksum
listFileObj << fileObj

payload.image = listFileObj
set_variable('payload', S(payload, 'application/json'))

    The script retrieves data from an external system, creates a payload object with the obtained data, and stores it as a process variable for further use in subsequent stages of the business process, namely:

    1. Imports the java.text.SimpleDateFormat and java.util.Date classes for working with dates:

      import java.text.SimpleDateFormat;
import java.util.Date;

    2. Creates a new SimpleDateFormat object with the format “dd_MM_yyyy” for date formatting:

      SimpleDateFormat date = new SimpleDateFormat("dd_MM_yyyy");

    3. Defines the image URL for downloading:

      String url = 'https://wallpapercave.com/wp/wp2601438.jpg';

    4. Generates a file name based on the current date, adding the prefix ‘file_’ and the extension .jpeg:

      String fileName = 'file_'.concat(date.format(new Date())).concat('.jpeg');

    5. Calls the function save_digital_document_from_url(url, fileName) to save the digital document (image) with the specified URL and file name:

      def documentMetadata = save_digital_document_from_url(url, fileName);

    6. Creates an empty payload dictionary and a list listFileObj for constructing the JSON data structure:

      def payload = [:];
def listFileObj = [];

    7. Assigns the generated file name to the name field of the payload dictionary:

      payload.name = fileName;

    8. Creates a new empty dictionary fileObj:

      def fileObj = [:];

    9. Assigns the id and checksum from the document metadata to the respective fields of the fileObj dictionary:

      fileObj.id = documentMetadata.id;
fileObj.checksum = documentMetadata.checksum;

    10. Adds fileObj to the list listFileObj:

      listFileObj << fileObj;

    11. Assigns the list listFileObj to the image field of the payload dictionary:

      payload.image = listFileObj;

    12. Sets the variable ‘payload’ with the value of the payload dictionary converted to a JSON string for use in subsequent steps of the business process.

      set_variable('payload', S(payload, 'application/json'));

  7. Model a Service Task for data signing with a system key.

    1. Use the delegate System signature by DSO service from the template catalog for applying the system signature.

    2. Pass the input data as the variable ${payload} in the corresponding field.

    3. Pass the user token. You can do this using the JUEL function system_user() and the accessToken method. For example, ${system_user().accessToken}. It can be further used in integration connectors for integration on behalf of the user.

      You can also use the process initiator’s token. For example, ${initiator().accessToken}.

      For more details, refer to JUEL functions in business processes.

  8. Save the response in a variable. For example, system_signature_key.

    bp timer launch 5

  9. Save data to the database. Create a new record in the database, storing the value of the entityLocation object in the respective column.

    1. Use the Create entity in data factory delegate to create an entity in the database.

      Alternatively, you can use the general integration connector Connect to data factory. For more information about integration extensions for business processes, refer to Connect to data factory.

    2. Specify the resource/API endpoint. For example, test-entity, which corresponds to the table name you defined when creating the data model registry — test_entity.

    3. Pass the input data as the ${payload} variable in the corresponding field.

    4. Pass the user token. You can do this using the JUEL function system_user() and the accessToken method. For example, ${system_user().accessToken}.

    5. Specify the X-Digital-Signature source — the source of the system signature. For example, ${system_signature_key}.

    6. Specify the X-Digital-Signature-Derived source — the Ceph document key that contains information about the signed data. For example, ${system_signature_key}.

    7. Save the response to a result variable, for example, response.

    bp timer launch 6

  10. Set the status of the business process to reflect a successful completion of the business process. To do this, create a Service Task and apply the Define business process status delegate.

  11. Finish the process using the End Event.

  12. Apply the made changes to the master branch to publish the process in the schedule.

    For more details, see Reviewing and managing the candidate version settings.

3. Use within the user portal

The business process modeled and published by the schedule becomes accessible in the Officer Portal.

This process can be found in the Available services > Reference business processes section. It will be launched and executed according to the established schedule in a Timer event.

The Officer portal is available via the pattern link:

https://officer-portal-<registry-name>-main.<dns-wildcard>

where <registry-name> is the name for your registry and <dns-wildcard> designates the domain and subdomain names for the cluster instance.

For example, for the demo-registry, deployed on the example.com Platform instance, the route to the Officer Portal service is:

https://officer-portal-demo-registry-main.example.com