Process Engine Configuration File

Process engine consists of two engines. An Engine is either the process interpreter or the task executor. While there can be the only one process interpreter there can be several task executors. Process engine configuration file defines:

nodes with endpoints on which engines of process engine can run
engines (PROCESSINTERPRETER, TASKEXECUTOR01, ...)

It allows to define e.g. that PROCESSINTERPRETER can run only on node W, or X and TASKEXECUTOR01 can run only on nodes Y, or Z.

The same process engine configuration file has to be used on all involved nodes. See how to define location of the configuration file.

Section nodes

Node is defined by its name, url, process interpreter and task executor endpoints.
Node name is displayed in the process engine console.
Node url is used, in concatenation with relativeEndpointAddress, to call the corresponding webservice on the node.
Node endpoints should correspond to endpoints defined on the node in cxf-servlet.xml

To define a new node, copy and paste the existing node definition.
Separate node definitions by comma ,.
Define a new node name and url.

"nodes": [

    {
      "name": "Y",
      "url": "http://localhost:8080/vmweb/services/",
      "processInterpreterEndpoint": {
      "relativeEndpointAddress": "ProcessInterpreterControllerPort"
      },
      "taskExecutorEnpoints": [
        {
          "name": "A",
          "relativeEndpointAddress": "TaskExecutorControllerPort/A"
        },
        {
          "name": "B",
          "relativeEndpointAddress": "TaskExecutorControllerPort/B"
        }
     ]
    },

    {
      "name": "Z",
      "url": "http://localhost:8081/vmweb/services/",
      "processInterpreterEndpoint": {
       "relativeEndpointAddress": "ProcessInterpreterControllerPort"
},
"taskExecutorEnpoints": [
        {
          "name": "A",
          "relativeEndpointAddress": "TaskExecutorControllerPort/A"
        },
        {
          "name": "B",
          "relativeEndpointAddress": "TaskExecutorControllerPort/B"
        }
      ]
    }
  ]

Section engines

The following example shows 2 engines: TASKEXECUTOR01 and TASKEXECUTOR02.
TASKEXECUTOR01 will be started on node Y - endpoint A. When node Y fails, it will be started on node Z.
TASKEXECUTOR02 will be started on node Z - endpoint B. When node Z fails, it will be started on node Y.

  "taskExecutors": [
   {
      "userName": "TASKEXECUTOR01",
      "cryptedPassword": "9A1E8801BD3B8B1AFF764F3709D0DF19",
      "startOnLoad": true,
      "sessionTimeoutInMinutes": 120,
      "canRunAt": [
        {
          "nodeName": "Y",
          "endpointName": "A"
        },
        {
          "nodeName": "Z",
          "endpointName": "A"
        }
      ]
    },
    {
      "userName": "TASKEXECUTOR02",
      "cryptedPassword": "9A1E8801BD3B8B1AFF764F3709D0DF19",
      "startOnLoad": true,
      "sessionTimeoutInMinutes": 120,
      "canRunAt": [
        {
          "nodeName": "Z",
          "endpointName": "B"
        },
        {
          "nodeName": "Y",
          "endpointName": "B"
        }
      ]
    }
  ],

Section mailProblem

When a problem occurs, WatchDog will e-mail a problem notification to a defined list of emails using Valuemation Mail setup.

"mailProblemTo": "support1@company.de,support2@company.de ",

"mailProblemCc": "supportCC@company.de"

Setup of Mail in Global Settings is used by the WatchDog.

Help Image

Help Image
Global Settings

WatchDog uses sender's e-mail defined for PEWATCHDOG user, or if one is not defined, sender's mail defined in Global Settings.

Set Sender's mail to indicate that it was sent by a program, from which environment (development, test, integration, production). E.g. app-valuemation-test@customer.de

Default configuration

When the parameter processEngineConfigurationLocation is not defined, default process engine configuration defined in the file WEB-INF/classes/ProcessEngineConfiguration.json is used.

Default configuration defines a process engine which can run on the node named "8080", with url "http://localhost:8080/vmweb/services/", consisting of PROCESSINTERPRETER and TASKEXECUTOR01.

{
  "nodes": [
    {
      "name": "8080",
      "url": "http://localhost:8080/vmweb/services/",
      "processInterpreterEndpoint": {
        "relativeEndpointAddress": "ProcessInterpreterControllerPort"
       },
       "taskExecutorEnpoints": [
        {
          "name": "A",
          "relativeEndpointAddress": "TaskExecutorControllerPort/A"
        },
        {
          "name": "B",
          "relativeEndpointAddress": "TaskExecutorControllerPort/B"
        }
      ]
    }
  ],
  "processInterpreter": {
    "userName": "PROCESSINTERPRETER",
    "cryptedPassword": "9A1E8801BD3B8B1AFF764F3709D0DF19",
    "startOnLoad": true,
    "sessionTimeoutInMinutes": 120,
    "canRunAt": [
      {
        "nodeName": "8080",
        "endpointName": ""
      }
    ]
  },
  "taskExecutors": [
    {
      "userName": "TASKEXECUTOR01",
      "cryptedPassword": "9A1E8801BD3B8B1AFF764F3709D0DF19",
      "startOnLoad": true,
      "sessionTimeoutInMinutes": 120,
      "canRunAt": [
        {
          "nodeName": "8080",
          "endpointName": "A"
        }
      ]
    }
  ],
  "mailProblemTo": "",
  "mailProblemCc": ""
}

How to define location of the configuration file

Location of the configuration file can be specified by parameter "processEngineConfigurationLocation", either:

1) as parameter in vmconfig.properties, or

Help Image
Definition in vmconfig.properties overwrites definition in web.xml

2) as <context-param> in web.xml, or

Help Image
Definition in web.xml overwrites definition of java system property

3) as java system property, e.g.

-DprocessEngineConfigurationLocation="c:/config/ProcessEngineConfiguration.json"

Test of configuration file

Use batch file testPEConfiguration.bat, in the rich client installation root, to verify process engine configuration file. It:

checks that e.g. node names are unique, at most one engine is assigned to one endpoint. Full list of constraints is listed below,

tries to call operation testEcho() of each used webservice a defined number of times. The webservices call count is reported.

Output is redirected to a file. Successful pass of test is clearly stated in the output.

Which file is to be verified and amount of iterations is defined by java system properties:

-DprocessEngineConfigurationLocation="c:/temp/ProcessEngineConfiguration.json"

-DtestIterations=3

Help Image
Batch file testPEConfiguration.bat

# Configuration is valid if it satisfies the constraints below:
# ERR-01: There are 2 nodes with the same URL '%s'. URL of a node must be unique.
# ERR-02: There are 2 nodes with the same name '%s'. Name of a node must be unique.
# ERR-03: There are %d engines '%s' assigned to the same endpoint '%s' of the node '%s'.
# ERR-04: Engine '%s' is assigned to undefined node '%s'.
# ERR-05: There is Task Executor with undefined userName. User name must be defined.
# ERR-06: There are 2 engines with the same userName '%s'. User name identifies an engine and must be unique.
# ERR-07: Process Interpreter engine is not defined.
# ERR-08: Process Interpreter has undefined userName. User name must be defined.
# ERR-09: Engine '%s' is not assigned to any node.
# ERR-10: Engine '%s' is assigned to node '%s' which does not define corresponding endpoint '%s'.
# ERR-11: Engine '%s' is already assigned to node '%s'. Second assignment through the endpoint '%s' is not allowed.
# ERR-12: Invalid name of node '%s'. Name of node cannot start with '%s'.
# ERR-13: Name of node is not defined.

Constraints applied on process engine configuration

Help Image
Shortened example of output for valid configuration