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: | 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:
|
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