Technical Documentation

processNow consists of 4 main components:

  • i-doit: The documentation platform and CMDB serves as a central repository for data used for further automation.
  • The i-doit processNow Addon includes an integrated interface for starting workflows directly from the i-doit interface.
  • Camunda: The open source workflow engine. It uses the BPMN standard for modeling automatable workflows and business processes as well as a lean and highly scalable architecture.
  • Worker: Small Java-executables that run on the servers and connect Camunda to the outside world or perform special activities.

Camunda can be downloaded from  https://camunda.com/ 

Recommended (and used in this manual) is version 7 of the distribution type „Tomcat“. 

It can be found here: https://camunda.com/download/#download-other-menu

 BPMN models (the actual workflows) are drawn or edited with the Camunda modeler and then deployed on the Camunda server. Details about this can be found on the Camunda website and their documentation. There you will also find an introduction to BPMN.

In order to execute an action via Camunda in a process step (called „activity“ in BPMN), for example to execute a command on the operating system level, a so-called worker is necessary.

The processNow solution already provides some workers for special activities:

  • The sys-worker: This worker executes arbitrary scripts on the operating system level – e.g. starting a shell script
  • The idoit-worker: This worker integrates the i-doit Webservice API into Camunda – e.g. it allows fetching data of an i-doit Object, as well as creating new or changing existing objects.
  • The qtag.me-worker: This worker integrates the QR code platform qtag.me with Camunda e.g. to start processes via QR code.
  • [planned] A Saltstack-worker: This worker will integrate the Saltstack infrastructure automation platform with Camunda to perform secure, cross-platform automation in the data center. 

Install Camunda

In our examples, we use the Tomcat distribution of version 7 from Camunda.

The ZIP or TAR/GZ file simply needs to be unpacked at the desired location.

For workers to perform correctly, the following setting must be made in the camunda-bpm-tomcat-7.xx.xx/server/apache-tomcat-xxxxx/conf/bpm-platform.xml file:

<property name=“jobExecutorDeploymentAware„>false</property>

After that Camunda can be started with start-camunda.bat or start-camunda.sh.

On Linux, the Java runtime may need to be installed (e.g. package default-jre).

Worker In General

The provided workers are utilities that allow Camunda to interact with the environment.

Each worker serves a certain specific purpose (e.g. sys-worker for executing commands, reading or writing files or the idoit-worker for accessing i-doit via REST webservice API).

Since the workers are designed as independent JAVA programs, but the configuration file always has the same name, it is necessary to provide a separate directory for each worker, in case several workers are running on the same server.

Details on the sys-worker:

The sys-worker is used to execute commands or read and write files on a server.

The sys-worker must therefore be installed on each server on which corresponding commands are to be executed or files are to be read or written.

The installation is done by copying the corresponding camunda-sysworker-x.xx-yyy.jar file into any directory and creating an application.yml configuration file in the same directory. The placeholders x.xx-yyyy stand for the current version and package name and can vary.

To start the sys-worker, a Java runtime must be installed (e.g. on Linux Debian and derivatives of the package default-jre).

The sys-worker is then started with the command java -jar camunda-sysworker-x.xx-yyy.jar

Note: Since the sys-worker can execute commands and read and write files, it is recommended to create a corresponding user that is restricted to the necessary rights. It is usually not a good idea to start the sys-worker as root or administrator.

Details on the sys-worker

Examples/Explanation: When To Install The Sys-worker On Which Server?

Case 1: If a shell script is to be executed directly on a database server via Camunda, the sys-worker must be installed on the database server.

Case 2: If the i-doit cli-console is to be opened on the i-doit server by Camunda, a sys-worker must be installed on the i-doit server.

If one uses Ansible to configure different systems, Camunda and the sys-worker can be installed on the Ansible-host. The sys-worker can then be used to open the Ansible runbooks.

If Powershell-scripts are to be opened via Camunda, the sys-worker must be installed on an appropriate Windows-server.

Details on the sys-worker

Functionality Of The Sys-worker

The sys-Worker is installed on one or more servers.

The configuration file assigns an identity to the sys worker (see xxx-topic parameter in the configuration).

With this identity (or, to be correct, with these topics) the sys-worker logs in to the Camunda server and waits for tasks to be executed.

In most cases, it makes sense that the identity of the sys-worker includes the hostname of the server to avoid confusion → This allows to conveniently model „and now run script <abc.sh> on server <s123>“ in the process flow.

Note: The sys-worker requires a network connection to the Camunda Server web service REST-interface (by default: port 8080).

Details on the sys-worker

Configuration Of The Sys-workers

In the directory of the camunda-sysworker-x.xx-yyy.jar file, a configuration file named application.yml must be created with the following content:

 

server:

  port: 8083

 

application:

  base-url: http://localhost:8080/engine-rest # the URL pointing to the Camunda Platform Runtime REST API

  user: demo

  password: demo

 lock-duration: 10000 # defines how many milliseconds the External Tasks are locked until they can be fetched again

  execute-topic: execute-serverhostname

  execute-white-list: C:\temp\test.bat, C:\temp\test1.bat, test3, test.sh

  write-file-topic: write-file-serverhostname

  write-file-white-list: c:\temp, c:\test

  read-file-topic: read-file-serverhostname

  read-file-white-list: c:\temp

 

logging:

  level:

    at.kohel.camunda.sysworker: info

    org.apache.http: info

    org.camunda: info

ATTENTION: Since this is a yml file, the indentations must be strictly observed!

Parameter

Beschreibung

base-url

Specifies the URL to the REST web service of the Camunda server.

user

Specifies the user to the Camunda server.

password

Specifies the password to the Camunda server.

execute-topic

This topic is used by the sys-worker to identify itself to the Camunda server in order to execute commands/scripts.

Best practice is to let the topic start with execute- and append the server hostname behind it.

e.g. execute-ansiblehost

execute-white-list

A comma-separated list of commands that the sys-worker is allowed to execute.

If the commands are in the same directory as the .jar file, no absolute path needs to be specified.

write-file-topic

This topic is used by the sys-worker to identify itself to the Camunda server in order to write files.

Best practice is to start the topic with write-file- and append the hostname of the server behind it.

e.g. write-file-ansiblehost

This topic is used, for example, to write a configuration file directly from a Camunda process.

write-file-white-list

A comma-separated list of directories to which the sys-worker may write files.

read-file-topic

This topic is used by the sys-worker to identify itself to the Camunda server in order to read files.

Best practice is to start the topic with read-file- and append the hostname of the server behind it.

e.g. read-file-ansiblehost

This topic is used, for example, to read a configuration file directly in a Camunda BPMN model and then process the data.

read-file-white-list

A comma-separated list of directories from which the sys-worker may read files.

If several sys-workers (also on different servers) are started with the same topic (i.e. identical entries for execute-topic, write-file-topic, read-file-topic), Camunda distributes the tasks to all sys-workers listening to the same topics. 

This can be used for load balancing, since a sys-worker does not accept any other tasks for the time of command execution. This can also be useful for redundancy aspects.



Troubleshooting note: If commands are not executed or are executed only sometimes on a particular server, one or more sys-workers with identically configured topics may be running on at least one other server and that other server is executing the commands.

Details on the sys-worker

Usage Of The Sys-worker

A new Camunda Version 7 BPMN model must be created in the Camunda BPMN Modeler.

There a so-called „service task“ is inserted.

The implementation is set to type „external“.

In the topic field, the execute-topic from the configuration file is inserted (in this example, the sys-worker is started on the server „zhukov“ and the execute-topic was set to „execute-zhukov“ in the application.yml file).

Then 2 input parameters are created:

Input-Parameter

Beschreibung

command

The command to execute – this command must be listed in the application.yml configuration file under execute-white-list.

arguments

The commandline parameters for initiating  the command.

Once the sys-worker has executed the command, 3 variables are automatically created in the Camunda process instance (if the contents of several successive sys-worker service tasks are required simultaneously these can of course be mapped to other variable names accordingly under outputs):

Output-Parameter

Beschreibung

exitCode

This is the exit code set by the command to be executed.

stdErr

This is the content that the executing command issued on stderr.

stdOut

This is the content that the executing command sends on stdout.

The output of the command in stdOut is usually processed in further steps.

Note: If the command returns a valid JSON, this JSON can be accessed directly with the Java-Script language integrated in Camunda and the values in it can be used further.

Details On The idoit-worker

The idoit-worker is used to interact with i-doit via the API.

Since the access is done via the web service, the idoit-worker can be installed either on the Camunda-server or on the idoit-server, if both are not running on the same server.

The installation on the Camunda server is recommended.

The installation is done by copying the corresponding camunda-bpm-idoit-bridge-x.xx-yyy.jar file into any directory and creating an application.yml configuration file in the same directory. The placeholders x.xx-yyyy stand for the current version and package name and can vary.

To start the idoit-worker a Java runtime must be installed (e.g. on Linux Debian and derivatives the package default-jre).

The idoit worker is then started with the command java -jar camunda-bpm-idoit-bridge-x.xx-yyy.jar. 

Note: Since the idoit-worker only uses the web service API of Camunda and i-doit, it is recommended to create a corresponding user that is restricted to the necessary permissions. It is usually not a good idea to start the idoit-worker as root or administrator.

Details On The idoit-worker

Functionality Of The idoit-worker

The idoit worker connects to Camunda to perform corresponding i-doit related tasks.

At the same time, the idoit-worker also connects to i-doit to perform the corresponding queries via the idoit web service API.

Details On The idoit-worker

Configuration Of The idoit-worker

In the directory of the camunda-bpm-idoit-bridge-x.xx-yyy.jar file, a configuration file named application.yml must be created with the following content:

server:

  port: 8082

 

camunda.bpm:

  client:

    base-url: http://localhost:8080/engine-rest # the URL pointing to the Camunda Platform Runtime REST API

    lock-duration: 10000 # defines how many milliseconds the External Tasks are locked until they can be fetched again

    subscriptions:

      cmdb-object-create: # topic name of the External Service Task

        variable-names: idoit, type, title, categories, purpose, cmdb_status, description

      cmdb-object-read:

        variable-names: idoit, id

      cmdb-object-update:

        variable-names: idoit, id, title

      cmdb-object-delete:

        variable-names: idoit, id, status

      cmdb-objects.read:

        variable-names: idoit, categories, filter, limit, order_by, sort

      cmdb-category-save:

        variable-names: idoit, object, category, data, entry

      cmdb-category-read:

        variable-names: idoit, objID, category

      cmdb-batch:

        variable-names: idoit, batch

 

idoits:

  idoit1: # the i-doit instance name if multiple seperate i-doit installation are used

    url: https://idoit-server/i-doit/src/jsonrpc.php # the URL pointing to the i-doit REST API

    apikey: xxx # the i-doit API key

    user: webservice # the i-doit username

    password: yyy # the i-doit password

  idoit2:

    url: url2

    apikey: apikey2

    user: user2

    password: password2

  idoit3:

    url: url3

    apikey: apikey3

    user: user3

    password: password3

logging:

  level:

    at.kohel.camunda.idoit: info

    org.apache.http: info

The red positions must be changed according to the specifications or wishes.

ATTENTION: Since this is a yml file, the indentations must be strictly observed!

Parameter

Beschreibung

base-url

Specifies the URL to the REST web service of the Camunda server.

idoits:
idoit1, idoit2, idoit3, …

If there are several separate i-doit installations, they can be specified here with a speaking identifier. This does not mean tenants, but actually independent installations of the application.

This allows use cases such as:


Extract data from a customer’s i-doit and use that data to perform appropriate activities in the service provider’s i-doit.


Recommendation: The first (main) i-doit should be left with idoit1, since all examples are based on this identifier.

url

Specifies the URL to the REST web service of the respective i-doit server.

apikey

Specifies the API key to the REST web service of the respective i-doit server

user

Specifies the user to the REST web service of the respective i-doit server.

password

Specifies the password to the REST web service of the respective i-doit server.

© 2022 processNow