Transact

  1. Home
  2. Transact
  3. System Configuration
  4. Ephesoft Transact Property Files Reference Guide
  5. Pickup Service

Pickup Service

Introduction

This page provides an overview of the pickup service feature and its recommended settings in Ephesoft Transact.

Overview

Pickup service refers to the automatic services that feed the Activiti framework to execute a batch. The workflow for this feature varies by version:

2020.1.02 and below

  1. New documents are uploaded into the system and converted to batch instances.
  2. Batch instances are queued in the database using the Activiti framework.
  3. The pickup service runs (based on a cron job) and picks new batch instances based on pickup capacity and Batch Instance Priority.
  4. The pickup service creates a job for each batch instance using the Activiti framework.
  5. The Activiti processor thread processes one job at a time, waiting a set time between picking up new jobs. This wait time varies by version and mode.
Mode Average Wait Time
(between batches)
application.cluster.mode=true

(2020.1.02 and above)

500-5,000 milliseconds
application.cluster.mode=false

(All versions)

5,000+ milliseconds

2020.1.03 and above

  1. New documents are uploaded into the system and converted to batch instances.
  2. This activates an event-based trigger mechanism, which sends the event to the distribution pickup node.
  3. The pickup service runs and forwards the job to an available node using an intelligent distribution system.

Note: In 2020.1.03 and above, the previous pickup service is no longer available. This means the following settings have been removed:

  • application.cluster.mode
  • activity.job.interval.time
  • activity.thread.wait.time

Pickup Settings

The pickup service is executed on a single server in a cluster with a fail-over functionality. This is an automatic service that assigns a random server in the cluster to execute the pickup service.

The server on which the pickup service is being executed is responsible for picking up all the batches for the cluster while keeping a check on the total execution capacity of the cluster. This is controlled through the following properties:

  • server.instance.max.process.capacity.mode
  • server.instance.max.process.capacity
  • server.instance.pick.capacity.mode
  • server.instance.pick.capacity
  • application.cluster.mode *
  • activity.job.interval.time *
  • activity.thread.wait.time *

Perform the following steps to configure the pickup settings.

  1. Navigate to the dcma-workflows.properties file located at [Ephesoft_Directory]\Application\WEB-INF\classes\META-INF\dcma-workflows.


Figure 1. dcma-workflows.properties File

  1. Configure the following properties according to your workflow needs:
Configurable Property Options
server.instance.max.process.capacity.mode 0 – max process capacity will be calculated automatically based on the number of cores in the system. Refer to Execution Capacity by Cores.

1 – max process capacity will be equal to the value specified for server.instance.max.process.capacity.

server.instance.max.process.capacity If the above property is set to 1, set this property to the total maximum number of batches that each server in a cluster will execute.

For example, if you have a 3-node cluster and each server should execute 5 batches, set this property to 5.

server.instance.pick.capacity.mode 0 – pickup capacity will be calculated automatically based on the number of cores in the system. Refer to Execution Capacity by Cores.

1 – pickup capacity will be equal to the value specified for server.instance.pick.capacity.

Set this value to 1.

If this value is set to zero (0), the capacity will be calculated automatically, and you will not be able to configure the next property.

server.instance.pick.capacity Set this property to the total maximum number of batches that will be distributed in a cluster.

For example, if you have a 3-node cluster and you want it to pick up 15 batches, set this property to 15.

application.cluster.mode * true – application is using improved pickup services distribution. This allows for an even distribution across all nodes when running under server capacity.

false – application is using previous pickup services distribution.

activity.job.interval.time * This is the activity job interval time in milliseconds.

Set this property to 500.

Important: If you have more than two processing nodes in a cluster, stagger the interval times by 100 milliseconds (500/600/700).

activity.thread.wait.time * This is the activity thread wait time in milliseconds.

Set this property to 5000.

Important: If you have more than two processing nodes in a cluster, stagger the wait times by 100 milliseconds (5000/5100/5200).

dcma.pickup.wait.ms This listening mechanism thread distributes jobs after receiving an event-based trigger or at the specified interval time in milliseconds.

The default value is 6000.

Note: There should be no need to change this property.

*Only applicable to Ephesoft Transact 2020.1.02
Only applicable to Ephesoft Transact 2020.1.03

Important: We recommend configuring all servers in the cluster using the same max process capacity and pick capacity values. This is because any server in the cluster can be assigned to run the pickup service in case of a failover.

  1. Restart the Ephesoft server. If a clustered environment, start all Ephesoft servers one by one.

Examples

2020.1 and below: The following excerpt shows an example of recommended settings for a 3-node cluster that should pick up and distribute up to 15 batches at a time.

## Node 1
server.instance.max.process.capacity.mode=1
server.instance.max.process.capacity=5
server.instance.pick.capacity.mode=1
server.instance.pick.capacity=15

## Node 2
server.instance.max.process.capacity.mode=1
server.instance.max.process.capacity=5
server.instance.pick.capacity.mode=1
server.instance.pick.capacity=15

## Node 3
server.instance.max.process.capacity.mode=1
server.instance.max.process.capacity=5
server.instance.pick.capacity.mode=1
server.instance.pick.capacity=15

2020.1.02: The following excerpt shows an example of additional recommended settings for a 5-node cluster with more than two processing nodes when application.cluster.mode=true.

## Node 1
application.cluster.mode=true
activity.job.interval.time=500
activity.thread.wait.time=500

## Node 2
application.cluster.mode=true
activity.job.interval.time=500
activity.thread.wait.time=500

## Node 3
application.cluster.mode=true
activity.job.interval.time=600
activity.thread.wait.time=600

## Node 4
application.cluster.mode=true
activity.job.interval.time=600
activity.thread.wait.time=600

## Node 5
application.cluster.mode=true
activity.job.interval.time=700
activity.thread.wait.time=700

2020.1.03 and above: Not applicable

UI Servers

In 2020.1.03 and above, UI nodes can be configured to not perform any workflow pickup execution, eliminating the associated inefficiencies. This is accomplished by disabling the new server.type.processing property.

UI servers should be set where:

server.instance.max.process.capacity.mode=1
server.instance.max.process.capacity=0
server.type.processing=false

Note: The UI node can still be the pickup service distribution node if assigned the PICKUP_SERVICE from the service status table, and server.type.processing is set to “false”. All other nodes with server.instance.max.process.capacity greater than zero (0) should have server.type.processing set to “true”.

Execution Capacity by Cores

If either capacity.mode properties are set to zero (=0), the execution capacity will be automatically calculated based on the total number of cores available for active processing servers. This is detailed in the table below.

Number of Cores Execution Capacity

(# of batches)

≤ 4 Equal to the number of server cores
5-8 Server cores – 1
9-15 8
16-32 10
≥ 33 15

Cron Settings

The pickup service within Ephesoft Transact is controlled using cron job expressions. A cron is a string which schedules a task to run on your server automatically at a specified interval. A cron job is the scheduled task itself. For more information on creating cron jobs, refer to Cron Job Expressions.

Cron settings for the pickup service determine the wait time to move a batch from New to Running state. This is controlled in the dcma-workflows.properties file, located at [Ephesoft_Directory]\Application\WEB-INF\classes\META-INF\dcma-workflows.


Figure 2. Edit the dcma-workflows.properties File

Example of cron settings:

Server 1 Server 2
dcma.pickUp.cronjob.expression=0/15 * * ? * *

dcma.resume.cronjob.expression=0/15 * * ? * *

dcma.pickUp.cronjob.expression=0/30 * * ? * *

dcma.resume.cronjob.expression=0/30 * * ? * *

Note: All cron settings for the pickup service must be offset per server. We recommend that there is a minimum of 15 seconds difference per server.

Activiti

Activiti is a light-weight workflow and Business Process Management (BPM) Platform that uses the Business Process Model and Notation (BPMN) standard for defining workflows. It provides a fast and reliable workflow engine for Java. It is open-source and distributed under an Apache license. Each batch class, module, and plugin is defined as a BPMN.

Specifications

  • License : Apache License 2.0
  • Version : 5.16.1
  • Process Definition Language : BPMN2.0

Conclusion

This completes an overview of the pickup service feature and its recommended settings in Ephesoft Transact.

Was this article helpful to you? Yes 1 No 1