The processNow i-doit Worker (camunda-bpm-idoit-bridge-x.xx-yyyy.jar) is based on java and a standalone program which connects to i-doit and to Camunda via REST webservice.
It provides some “topics” for BPMN “External Service Tasks” that can be used to retrieve data from i-doit or create/update objects in i-doit.
One big advantage is that no credentials are used in the BPMN diagram!
You can use an identifier (by default “idoit1”) to select the i-doit installation. Credentials like username, password and apikey are hidden in the application.yml file on the Server which runs the processNow i-doit Worker.
The input parameters for the topics of “External Service Tasks” (means the API calls) are the same as described in i-doit webservice API description.
There are some BPMN diagrams shipped that can be used as an abstraction layer by calling them as sub-processes to cover typical operations which makes things easier. For example load write a processNow log record to i-doit if a process was started or finished (see BPMN sub-process “cmdb-create-or-update-camundaprocess”).
Prerequisites processNow i-doit Worker
The processNow i-doit worker (camunda-bpm-idoit-bridge-x.xx-yyyy.jar) contains some methods to interact with i-doit using the i-doit API.
The i-doit API is bundled in the processNow i-doit open bundle or if you are using i-doit PRO version, you have to install the API addon.
Prerequisites to use the API from processNow i-doit worker
Activate the API in Administration -> Interface / external data -> JSON-RPC-API -> Common Settings.
Enable “Enforce authentication by username and password” and remember the API key.
Setup correct url, apikey, user and password in application.yml file for the camunda-idoitworker (you will find it in the same directory like camunda-bpm-idoit-bridge-x.xx-yyyy.jar file).
Hint: It’s best practice to install i-doit worker on same machine like i-doit (so you can use localhost in url).
Hint: It’s best practice to create a separate webservice user to access i-doit webservice.
Prerequisites to use processNow i-doit worker Workflow CI „Logging“
The i-doit processNow Addon contains a great feature to log processNow Flow Workflow/Camunda-Process information like start time, current state (running, waiting for customer, finished, …) in the corresponding CI.
With the i-doit processNow Addon there comes a new category “processNow Log” which can be enabled for every CI object type.
Just edit the Object type configuration and add class “processNow Log” to the “Assigned category”.
Overview processNow i-doit Worker functionality
The processNow i-doit Worker uses the i-doit API to read and write information from/to i-doit.
The provided worker methods (implemented as different “External Task topics”) are equal to the i-doit API methods (see https://kb.i-doit.com/display/de/API+Methoden).
These API methods are supported:
External Task “topic” | Description |
cmdb-object-create | Create a new i-doit object |
cmdb-object-read | Read an i-doit object |
cmdb-object-update | Update an existing i-doit object |
cmdb-object-delete | Delete an existing i-doit object |
cmdb-objects-read | Get a list of i-doit objects using some filter criterias |
cmdb-category-save | Create or update a category record for an i-doit object |
cmdb-category-read | Get list of category records |
cmdb-batch | Batch method to call multiple methods in a single batch call |
Some of these methods are used in a typical way like cmdb-objects-read to fetch some information (including category specific information) for one or more objects.
So processNow comes with some BPMN sub-processes to encapsulate these methods with some logic around to make things easier.
These sub-processes are available as ready-to-use BPMN diagrams:
BPMN Sub-Process ID | Description |
cmdb-objects-read | Sub-Process to search for an object and return information including given categories |
cmdb-category-save | Sub-Process to update values within a category of an object |
cmdb-create-or-update-camundaprocess | Sub-Process to create or update a “processNow Log” record for a given object. This is used to document, that a Workflow was triggered and which state this workflow has (e.g. STARTED, FINISHED, WAITING, …) |
Use processNow i-doit Worker in BPMN
The API methods can directly used by creating an “External Task” with specified topic (see table “External Task topic” above) and input/output variables.
Or use one of the sub-processes by creating a “Call Activity” using the BPMN Process-ID (see table “BPMN Sub-Process ID” above).
In general the input variables are pretty the same like described in i-doit API https://kb.i-doit.com/display/de/API+Methoden
The idoit variable will select the i-doit endpoint defined in application.yml file.
If you are not using multiple i-doit installations (real installations e.g. on different servers, not tenants) always use “idoit1” and don’t change it.
Details about Topic „cmdb-objects-read“
The Topic “cmdb-objects-read” accepts these input variables:
cmdb-objects-read Input Variables | Description |
idoit | The i-doit identifier used in application.yml file – by default this is always “idoit1” and should not be changed. Only use/change this if you have multiple idoit installations (not tenants – real installations on different servers). |
categories | JSON Array with list of categories to retrieve – example: [ „C__CATG__GLOBAL“, „C__CATG__CONTACT“, „C__CATG__LOCATION“, „C__CATG__IT_SERVICE“ ] |
filter | JSON Object with filter criterias – example: { „ids“: ${objid} } This will search for objects if id given in variable “objid” – see BPMN start event of this example. |
limit | [optional] Number of records to return – example: 100 |
order_by | [optional] Field to use as sort-criteria – example: title |
sort | [optional] Sort direction – example: ASC |
The input variables are the same described in i-doit API https://kb.i-doit.com/display/de/API+Methoden
The Topic “cmdb-objects-read” creates these output variables:
cmdb-objects-read Output Variables | Description |
result | String with JSON object with result of API call – example: “[{\“id\“:1,\“title\“:\“Root location\“,\“sysid\“:\“SYSID_1132672018\“,… }]” |
Details about Topic „cmdb-Category-save“
The Topic “cmdb-category-save” accepts these input variables:
cmdb-objects-read Input Variables | Description |
idoit | The i-doit identifier used in application.yml file – by default this is always “idoit1” and should not be changed. Only use/change this if you have multiple idoit installations (not tenants – real installations on different servers). |
category | The category to write to – example: C__CATG__PROCESSNOW |
data | String JSON Object with field/values to write to Object – example: { „title“: „test“ } |
object | The Object ID to use to update – example 53 |
entry | [optional] The entry id to use if target is a multivalue category – example 1 |
The Topic “cmdb-category-save” creates these output variables:
cmdb-objects-read Output Variables | Description |
entry | The entry id created (useful for multivalue categories) – example: 2 |
Details about Sub-Process “cmdb-create-or-update-camundaprocess”
This Sub-Process encapsulates all logic to create and update “processNow Log” records.
It is used by adding a Call Acitivity calling this Sub-Process as BPMN Element.
The BPMN Sub-Process “cmdb-create-or-update-camundaprocess” needs some input variables and an output variable:
cmdb-create-or-update-camundaprocess Input Variables | Description |
idoit | [optional] Only use/change this if you have multiple idoit installations (not tenants – real installations on different servers). |
targetObjectId | The i-doit Object ID – example: 53 |
targetObjectRequestor | String the name (free text) of the requestor – example: Leo Eibler |
targetObjectStatus | String the status code (free text) to be used – example: STARTED |
targetObjectTitle | String the title of the processNow Log record – example: |
targetSetStartdate | Bool true to set the startdate to current date/time – example: true |
targetSetEnddate | Bool true to set the enddate to current date/time – example: false |
targetEntry | [optional] The entry id of “processNow Log” record. This is used to update the log record within same process/workflow – example: 2 |
The Sub-Process “cmdb-create-or-update-camundaprocess” creates these output variables:
cmdb-create-or-update-camundaprocess Output Variables | Description |
entry | The entry id created. 2 |
Examples
Example External Task topic “cmdb-objects-read”
Create a new BPMN diagram (Camunda Platform 7) diagram using Camunda Modeler.
Add a start event with “Generated Task Forms” and Form fields ID “objid” and Default value “%OBJID%”.
The Default value “%OBJID%” will be replaced by the i-doit CI object-id.
There are some special placeholders which are automatically replaced by the processNow addon:
Placeholder | Description |
%HOSTNAME% | Uses the CIs hostname defined in primary “Host address” |
%HOSTNAME_FQDN% | Uses the CIs hosts FQDN (full qualified domain name) defined in primary “Host address” |
%OBJID% | The CIs objid |
%OBJTYPEID% | The CIs objtypeid |
%OBJTITLE% | The CIs title |
%SYSID% | The CIs sysid |
Next add a “Service Task” with Implementation Type “External” and Topic “cmdb-objects-read”.
So add the required input variables idoit, categories and filter as Inputs:
For variable “categories” use: [ „C__CATG__GLOBAL“, „C__CATG__CONTACT“, „C__CATG__LOCATION“, „C__CATG__IT_SERVICE“ ]
For variable “filter” use: { „ids“: ${objid} }
For variable “idoit” use: idoit1
At least add a “timer intermediate catch event” with Type “duration” and value “PT1H” (1 hour) to have some time to review the result before process instance ends automatically and disappears from the list of running process instances in Camunda.
Now deploy the diagram to Camunda server.
Now in i-doit open a CI and click on category “General” and use the “processNow” button which will Auto-Discover all deployed Camunda processes.
The dialog box will be empty because at this time, the deployed Camunda processes are not enabled for any CI Object Type nor a specific CI. It will only perform synchronization in the background.
Open Group “Other” and select “processNow Flow”. There should be at least 1 record representing the new BPMN process deployed to Camunda.
Assign some Object Types in field “valid for object types” of Category “processNow Flow Definition” to activate this workflow/Camunda Process for these Object Types.
Open a Server CI (if Server was assigned as “valid for object types” to the processNow Flow Definition) and in category “General” click on “processNow” Button.
Select the processNow Flow record (deployed Camunda Process/Workflow).
The “objid” Variable with default value “%OBJID%” should be replaced with the Object ID of the object.
After starting the Process, click on the Link to view the runtime instance in Camunda.
Now a new variable “result” appears – this holds all the information returned by “cmdb-objects-read” call.
Click on result “java.lang.String” to see the result (this may take some seconds).
The content is JSON formatted and can be used in other following BPMN Tasks to extract information.
Example reboot-server uses Sub-Process cmdb-create-or-update-camundaprocess
The bundled Camunda Sub-Process “cmdb-create-or-update-camundaprocess” can be used to create “processNow Log” records.
This is useful to document changes automatically in CMDB.
In this example we will extend the ansible reboot-server processNow Flow with logging using this Sub-Process.
Add a BPMN “Call Activity” with Called element Type “BPMN” and Called element “cmdb-create-or-update-camundaprocess” (case sensitive!).
Setup input variables:
cmdb-create-or-update-camundaprocess Input Variables | Variable |
targetObjectId | The i-doit Object ID (objid is the ID of a the Form Field): Source: objid Target: targetObjectId |
targetObjectRequestor | String the name (free text) of the requestor: Type: Source expression Source Expression: Leo Eibler Target: targetObjectRequestor |
targetObjectStatus | String the status code (free text) to be used: Type: Source expression Source Expression: REBOOTED Target: targetObjectStatus |
targetObjectTitle | String the title of the processNow Log record: Type: Source expression Source Expression: Server Reboot ${servername} Target: targetObjectTitle |
targetSetStartdate | Bool true to set the startdate to current date/time: Type: Source expression Source Expression: true Target: targetSetEnddate |
targetSetEnddate | Bool true to set the enddate to current date/time: Type: Source expression Source Expression: true Target: targetSetEnddate |
targetEntry | [optional] Not used, because we call this process only a single time – if not provided this will create a new processNow Log record. Type: Source Source: cmdbCamundaProcessEntry Target: targetEntry |
The Sub-Process “cmdb-create-or-update-camundaprocess” creates these output variables:
cmdb-create-or-update-camundaprocess Output Variables | Description |
entry | The entry id created.
It’s best practice to always assign this with a variable, so a second or third call of “cmdb-create-or-update-camundaprocess” will update the processNow Log record and not create another one.
So assign Out mapping: Type: Source Source: entry Target: cmdbCamundaProcessEntry
|
Now extend the start Event with the Form field ID “objid” of type “string” and Default value “%OBJID%”.
This “objid” is used as input for Call Activity “auto-document process in CDMB” input variable “targetObjectId”.
Deploy the new version – modify the process ID to a different value e.g. ”reboot-server-with-log” to not overwrite the existing reboot-server processNow Flow.
Now don’t forget to assign Object Type e.g. Server to the processNow Flow definition.
Open a Server CI and click on “processNow” button in General class.
The new processNow Flow should be available and Default Values %OBJID% and %HOSTNAME_FQDN% of Form Fields should be replaced with correct Object ID and hostname.
After processNow Flow finished without an error (incident) we should see a processNow Log record in the CI.
Using processNow Log records it is possible to automatically document CI changes from the workflow.
So e.g. if a new database user should be created using a processNow Flow this can be logged.
If a password reset was triggered by an user, this can be logged.
If the onboarding process of a new employee is modeled as BPMN process, the different states can be logged in a single processNow Log record and based on the employee CI it’s easy to check if the process already finished.
© 2022 processNow