10.2.3

Edit

Orchestrate Use Case

note

The instruction describes running, stopping, and scheduling Business Processes based on the ODF 2 Full Archetype.

Set up Business Processes

After you create and build the project from the Full Archetype, check the following four zip files inside the [project-name]/[project-name]-package/src/main/resources/business-process folder:

  • Data_Intake_v_[version].zip takes data from external sources, validates, sanitizes, and prepares to be processed.
  • Data_Processing_v_[version].zip processes the prepared data.
  • Data_Submission_v_[version].zip is responsible for aggregating results, creating reports, and submitting data to other systems.
  • Error_Handling_v_[version].zip handles exceptional cases raised by other processes.

Each file represents a Business Process that can be imported to a Control Tower instance. All processes operate out of the box. No extra configuration is required.

You can import the Business Processes to Control Tower using the bundle-maven-plugin. After the import is completed, you should see all the processes groped together by the Use Case name and version on the Use Cases page in Control Tower.

You might have different versions of the same project. By clicking on the specific version, you can navigate to the imported processes.

To start a process, click on it and navigate to the Run tab. You can start a process right away (no input data is required) as any other Business Process by clicking the Run This Process button.

note

The Full Archetype Business Processes depend on each other and should be started altogether one by one. For example, the Submission process is waiting for the data from the Processing process. In its turn, Processing can take results from the Intake process only.

Each Business Process starts with a special Bot Task called a Monitor Task. Once a Business Process is started, a Monitor Task regularly wakes up. Each time it wakes up, it can pass some records to the next step of its Business Process. By default, Monitors are configured to work during the infinite time and to wake up once a minute. It means that a Business Process works infinitely until stopped manually, and new records are produced once a minute. You can change this default behavior.

To configure Monitors, set up records in the monitor_configuration Data Store. The best practice for configuring Monitors is to provide records for the monitor_configuration Data Store using database migrations. You can also do it manually.

For each class of a Monitor Task, there is a configuration record. If there is none, the default configuration is used.

The Monitor behavior is defined by four parameters:

  • polling_interval defines the amount of time that a Monitor Task leaves between consequent polls for data. By default, the interval is equal to 60 seconds.
  • sleep_time defines an interval after which the Monitor wakes and checks if polling_interval is elapsed. This interval cannot be less than 60 seconds because of a Control Tower limitation.
  • max_loops is the number of polls after which the Monitor stops working. By default, the number of polls is unlimited.
  • max_running_time defines a time period after which the Monitor finishes execution. By default, the Monitor execution time is unlimited.

The following two parameters define which Monitor the configuration belongs to:

  • monitor_class is the name of a Java class that represents a Monitor, for example, EmailMonitorTask.
  • uuid is the unique database key for the Monitor configuration. If you set up this field manually, you can use this online tool to generate a new UUID.
important

Specify the polling_interval, sleep_time, and max_running_time parameters in the ISO-8601 duration format.

For example, "P1D" means one day, and "PT1H30M10S" means 1 hour, 30 minutes, and 10 seconds.

Find the state of each running Monitor Task instance in the monitor Data Store. To stop any Monitor manually, set a stopped field of the corresponding record to "1".

Run Business Process once

The ODF 2 Full Archetype Business Processes are designed to run continuously, handing data as it appears. Sometimes, you require to run a Business Process for one time only. This is especially useful during the development phase of your project or when testing capabilities.

To make a Business Process run only once, specify the correct configuration inside the monitor_configuration Data Store. The best practice is to use database migrations.

Let's take a look at the Intake Business Process as an example. The migration look as follows:

<changeSet author="${author_name}" id="${change_set_id}">
    <insert tableName="uc_${uc_code}_monitor_configuration_v${uc_version}">
        <column name="monitor_class" value="EmailMonitorTask"/>
        <column name="polling_interval" value="PT1M"/>
        <column name="sleep_time" value="PT15S"/>
        <column name="max_loops" value="1"/>
        <column name="max_running_time" value="PT0S"/>
    </insert>
</changeSet>

Mind the following column values:

  • <column name="monitor_class" value="EmailMonitorTask"/> defines the Monitor Name. EmailMonitorTask is the target Monitor or the first step of the Intake Business Process.

  • <column name="max_loops" value="1"/> defines the number of Monitor's loops. Only one loop is required in this case.

You can also specify this configuration manually in Control Tower UI. Navigate to the monitor_configuration Data Store, click the Add Record button, and add a new record with the following parameters:

  • monitor_class—EmailMonitorTask
  • max_loops—1
  • uuid—${random_uuid_value}

You can leave the rest of the columns with empty values. In this case, the framework applies default values—max_running_time is unlimited, and sleep_time is 60 seconds.

note

The database migration does not require to specify the uuid column. When applying a migration script, the database generates a value for this column automatically. However, when creating a new record in Control Tower, you must manually specify the value for the uuid column.

Stop Business Process

There are two options to stop a running Business Process instance:

  • Go to Control Tower > Business Processes and navigate to the Business Process you are planning to stop. Click the Stop button from the ... dropdown menu. When you stop a Business Process this way, it leads to a near-instant stop of the execution. Transactions not processed by that time won't be processed, while processed transactions advance to the next Business Process.

  • Navigate to the monitor Data Store, find the Monitor entity responsible for the Business Process instance, and set the "1" value to the stopped field. The Business Process continues running transactions that had already been started, but the Monitor won't produce new transactions. Once all in-progress transactions are finished, the Business Process is marked as stopped.

important

To find a Monitor entity responsible for a particular Business Process, check the monitor_id column. It consists of the Monitor task name and the ID of a Business Process run. For example, to stop the Intake Business Process with the run ID 351133f9-2c8e-410b-9323-cfd4f3e97250, find the record with the monitor_id equal to EmailMonitorTask#351133f9-2c8e-410b-9323-cfd4f3e97250.

Schedule Business Process

With Monitor Tasks available, it is logical to keep Business Processes running for a long time. However, Control Tower limitations make this approach impractical. The recommended approach is to schedule the process execution at regular intervals and configure Monitors accordingly.

tip

For more details on Business Process scheduling, refer to the WorkFusion documentation.

The example below shows how to configure the Intake Business Process to run regularly, one hour per day.

To configure the EmailMonitorTask Monitor to work for one hour only, apply the following database migration:

<changeSet author="${author_name}" id="${change_set_id}">
    <insert tableName="uc_${uc_code}_monitor_configuration_v${uc_version}">
        <column name="monitor_class" value="EmailMonitorTask"/>
        <column name="polling_interval" value="PT1M"/>
        <column name="sleep_time" value="PT15S"/>
        <column name="max_loops" value="0"/>
        <column name="max_running_time" value="PT1H"/>
    </insert>
</changeSet>

Pay attention to the following values:

  • <column name="monitor_class" value="EmailMonitorTask"/> is the name of the Monitor to be configured.

  • <column name="max_running_time" value="PT1H"/> is the max running time in the ISO-8601 duration format, PT1H means one hour.

Or instead, go to Control Tower and create a new record in the monitor_configuration Data Store with the following parameters:

  • monitor_class—EmailMonitorTask
  • max_running_time—PT1H
  • uuid—${random_uuid_value}

In this case, the Monitor ensures that the Business Process is stopped right after one hour of the execution. However, to start the process, you need to create a Business Process scheduler. The scheduler is responsible for starting the process once a day. Using both the Monitor and the scheduler, you can fulfill any requirements regarding Business Process working hours.

To create a new scheduler, follow the steps:

  1. Navigate to Advanced > Schedules and click the Create button.

  2. On the next page, specify the following parameters:

    • Task or Process Definition—select the Business Process to run.
    • Input Data—select Empty as you don't require any Input Data.
    • Schedule Period—set a schedule period by selecting dates from the calendar.
    • Schedule Name—specify the schedule name.
    • Schedule Frequency—type in or select the required frequency values from the dropdown menu.

  3. Click Save.

note

The 0 0 9 * * ? Cron expression means "every day at 09:00".

Once you save the schedule, you cannot edit it. To edit a saved schedule, copy it, and edit the copy. You can pause and start a running schedule and delete a schedule at any time.

When the scheduler starts a Business Process, it creates a separate instance of this process.

Configure 24/7 schedule

When it comes to the 24/7 schedule, make sure that only one instance of a Business Process runs at a time. For example, you don't want to let the same two Intake processes work together since it might create duplicated transactions.

important

If you run your process 24/7 and the process can stand for 12 hours non-stop, configure the scheduler to start a new process instance every 12 hours, and set up your Monitors to run no longer than 11 hours and 59 minutes.

Let's take a look at the Monitor configuration for EmailMonitorTask that works no longer than 11 hours and 59 minutes:

<changeSet author="${author_name}" id="${change_set_id}">
    <insert tableName="uc_${uc_code}_monitor_configuration_v${uc_version}">
        <column name="monitor_class" value="EmailMonitorTask"/>
        <column name="polling_interval" value="PT1M"/>
        <column name="sleep_time" value="PT15S"/>
        <column name="max_loops" value="0"/>
        <column name="max_running_time" value="PT11H59M"/>
    </insert>
</changeSet>

Pay attention to the following values:

  • <column name="monitor_class" value="EmailMonitorTask"/> is the name of the Monitor to be configured.

  • <column name="max_running_time" value="PT11H59M"/> is the max running time in the ISO-8601 duration format, PT11H59M means 11 hours and 59 minutes.

Each Business Process will have the same Monitor configuration in your setup. The only thing that changes is the Monitor name. Out-of-the-box processes use the following Monitor names:

  • Data Intake—EmailMonitorTask
  • Data Processing—ProcessingMonitorTask
  • Data Submission—SubmissionMonitorTask
  • Error handling—ErrorMonitorTask

To create a separate scheduler for each Business Process to start twice a day in the interval of 12 hours, follow the steps:

  1. Navigate to Advanced > Schedules and click the Create button.

  2. On the next page, specify the following parameters:

    • Task or Process Definition—select the Business Process to run.
    • Input Data—select Empty as you don't require any Input Data.
    • Schedule Period—set a schedule period by selecting dates from the calendar.
    • Schedule Name—specify the schedule name.
    • Schedule Frequency—type in or select the required frequency values from the dropdown menu.

  3. Click Save.

tip

The 0 0 09,21 * * ? Cron expression means "every day at 09:00 and 21:00".

← Business Process integration testingTroubleshooting →