Camunda Core

For the most up-to-date documentation, please visit docs.brix.ch

No UI

The Camunda Core extension provides a synchronization of CELUM users and groups with Camunda and other utilities. Additionally it gives access to the Camunda REST API via CELUM (/main/camunda/*), so that Workflow extensions in CELUM only need to communicate with CELUM directly.

Properties

To be configured in {home}/appserver/conf/custom.properties

General

camundaCore.license

type: string, required: yes, default: -

The license key for the plugin (product: camundaCore), provided by brix.

camundaCore.camunda.url

type: string, required: yes, default: -

The URL to the camunda REST API. Has to start with http or https and end in /. E.g. http://localhost:8080/engine-rest/

camundaCore.camunda.username

type: string, required: no, default: -

The username for the Camunda REST API (only required if it is protected).

camundaCore.camunda.password

type: string, required: no, default: -

The password for the Camunda REST API (only required if it is protected).

camundaCore.web.token

type: string, required: no, default: -

The token for the services which don't require login (e.g. mail service) to protect them.

User and Group Synchronization

Only synchronizes the following events immediately, the rest is done by the sanitize job:

  • user/group added to group
  • group/user deletion
  • group/user creation (only if everything is synced)

This ensures, that the users can immediately work with Camunda as soon as they are created in CELUM.

camundaCore.userSync.enabled

type: boolean, required: no, default: true

Enables/disables the user and group synchronization. Server restart required.

camundaCore.userSync.sanitize.cronExpression

type: string, required: no, default: 0 0 1 * * ? (hourly)

Quartz cron trigger that tells the sanitize job when and how often it should run.

camundaCore.userSync.groups

type: comma-separated list of group ids, required: no, default: - (all groups)

The groups (and members of those groups) which should be synchronized. If this property is not set, all groups are synchronized.

camundaCore.userSync.groupsRecursive

type: boolean, required: no, default: false

Also synchronize all the sub-groups of the specified groups. Users are always resolved recursively because Camunda doesn't support hierarchical groups (only users can be members of groups and not other groups).

camundaCore.userSync.prefix.user

type: string, required: no, default: CelumUser

The prefix to use for the CELUM users in Camunda. E.g. the user with ID 123 and the default prefix would become CelumUser123 in Camunda.

camundaCore.userSync.prefix.group

type: string, requierd: no, default: CelumGroup

The prefix to use for the CELUM groups in Camunda. E.g. the group with ID 456 and the default prefix would become CelumGroup456 in Camunda.

camundaCore.userSync.groupType

type: string, required: no, default: CELUM

The group type of CELUM groups in Camunda. This is just a string and can be anything, but it can be helpful for searching the synchronized groups in Camunda.

Password Checker

The password checker provides an internal service and a controller to verify passwords.

The controller accepts POST requests to /main/camundaCore/password?userId=...&password=.... userId is optional (defaults to the logged-in user). The following responses are possible:

  • 406 NOT ACCEPTABLE: the user sending the request does not match the specified user id (can only happen if loggedInUserOnly is set to true)
  • 405 NOT ALLOWED: the user is deactivated
  • 404 NOT FOUND: the user wasn't found
  • 403 FORBIDDEN: the user was locked because the maximum number of incorrect attempts was reached within the configured time interval
  • 401 UNAUTHORIZED: the password was wrong (could probably also happen if the user's CELUM session timed out)
  • 200 OK: password was correct

To be able to use the password checker, the following table has to be created:

create table camunda_password_check_attempts (
    id bigint auto_increment primary key,
    user_id bigint not null,
    timestamp timestamp not null
);
camundaCore.passwordChecker.maxFails

type: integer, required: no, default: 5

After failing the password check this many times in the specified time interval the user will be deactivated.

camundaCore.passwordChecker.intervalInMinutes

type: integer, required: no, default: 5

The time interval in minutes.

camundaCore.passwordChecker.resetAfterSuccess

type: boolean, required: no, default: true

Delete the failed attempts after successful check?

camundaCore.passwordChecker.controller.loggedInUserOnly

type: boolean, required: no, default: true

If set to false, every logged-in user can check the password of any user. Should not be false, otherwise it is possible to lock out other users by intentionally entering a wrong password enough times. This only affects the controller and not the internal password check service.

Absences

There is an internal service and a controller to manage the absences. Tasks which are directly assigned to users can be automatically re-assigned to the replacement unless he already has the same task.

The controller provides the following methods to manage absences:

  • GET main/camundaCore/absence?userId=...&active=... both parameters are optional, for userId the default is the logged-in user and the default for active is true (only return absence if it is active). Returns an Absence JSON object.
  • GET main/camundaCore/absence/list?active=... only available if loggedInUserOnly is set to false, active is optional and the default is true (only return active absences, not those in the future). Returns a list of Absence JSON objects.
  • POST main/camundaCore/absence creates or updates an absence. Has to be send as absence JSON object in the body. userId is optional, the default is the logged-in user.
  • DELETE main/camundaCore/absence?userId=... userId is optional, the default is the logged-in user.

Response codes:

  • 406 NOT ACCEPTABLE: the user sending the request does not match the specified user id (can only happen if loggedInUserOnly is set to true)
  • 404 NOT FOUND: no absence found for specified userId
  • 400 BAD REQUEST: wrong date format
  • 201 CREATED: the absence was created (wasn't an update)
  • 200 OK

Absence JSON object:

{
    "id": ...
    "userId": 487
    "replacementId": 430,
    "from": "2020-03-17",
    "to": "2020-03-17",
}

To be able to use the absence service, the following table has to be created:

create table camunda_absence (
    id bigint auto_increment primary key,
    user_id bigint not null,
    replacement_id bigint not null,
    from_date date not null,
    to_date date not null
);
camundaCore.absence.controller.loggedInUserOnly

type: boolean, required: no, default: true

The logged-in user can only request or modify his own absence (recommended).

Observers

There is an internal service and a controller to manage observers. Observers can be informed automatically with the mail service.

The controller provides the following methods to manage observers:

  • GET main/camundaCore/observer?userId=... userId is optional, the default is the logged-in user. Returns an Observer JSON object.
  • GET main/camundaCore/observer/list only available if loggedInUserOnly is set to false. Returns a list of Observer JSON objects.
  • POST main/camundaCore/observer creates or updates an observer, has to be sent as observer JSON object in the body. userId is optional, the default is the logged-in user.
  • DELETE main/camundaCore/observer?userId=... userId is optional, the default is the logged-in user.

Response codes:

  • 406 NOT ACCEPTABLE: the user sending the request does not match the specified user id (can only happen if loggedInUserOnly is set to true)
  • 404 NOT FOUND: no observer found for specified userId
  • 201 CREATED: the observer was created (wasn't an update)
  • 200 OK

Observer JSON object:

{
    "id": ...
    "userId": 487
}

To be able to use the observer service, the following table has to be created:

create table camunda_observer (
    id bigint auto_increment primary key,
    user_id bigint not null
);
camundaCore.observer.enabled

type: boolean, required: no, default: true

If this property is set to true, then deleted users will be removed automatically from the observer list. Restart required.

camundaCore.observer.controller.loggedInUserOnly

type: boolean, required: no, default: true

The logged-in user can only request or modify his own observer status (recommended).

Mails

There is an internal mail service and a controller. Both accept a SendMailRequest object. The mail engine uses velocity templates, which have to be placed in the class path, e.g. CELUM_HOME/appserver/velocity (recommended).

Mail template with all variables:

#* @vtlvariable name="data" type="ch.brix.camundaCore.mail.MailData" *#
#* @vtlvariable name="additionalData" type="java.util.Map<java.lang.String, java.lang.Object>" *#
<div id="body" style="font-family: Arial, Helvetica, sans-serif;">
    Always available (all but the first property depend on the recipient), but maybe not set in CELUM:
    <ul>
        <li>${data.celum}: link to CELUM, guaranteed to end in /</li>
        <li>${data.userId}</li>
        <li>${data.username}</li>
        <li>${data.email}</li>
        <li>${data.firstName}</li>
        <li>${data.lastName}</li>
    </ul>
    Available if assetId is set for the request:
    <ul>
        <li>${data.assetId}: an asset link is created as follows <a href="${data.celum}main/opennodeview.do?assetId=${data.assetId}">${data.assetName}</a></li>
        <li>${data.assetName}</li>
    </ul>
</div>

The controller accepts POST requests to camundaCore/mail (note that there is no main) with a SendMailRequest object as the body and the response will be a SendMailResult object (JSON).

The SendMailRequest object has the following properties:

  • token (string): if this token doesn't match the configured one the response code will be 401: UNAUTHORIZED.
  • subjectMessageKey (string): the message key for the subject of the mail
  • template (string): the mail of the template (without the _locale.vm)
  • locale (string): the language in which the mail should be sent (default is the CELUM default system locale)
  • recipients (array of integers): the user ids of the recipients (the users to which the mail should be sent)
  • includeObservers (boolean): if set to true the mail will also be sent to the observers (default is false)
  • assetId (integer): the id of the asset
  • taskId (string)
  • taskName (string)

The SendMailResult object properties:

  • success (array of integers): the user ids to which a mail could be sent
  • failed (array of integers): the user ids for which sending the mail failed (only if not failed due to the three other reasons below)
  • ignored (array of integers): the user ids which were ignored because the user is deactivated
  • notFound (array of integers): the user ids which couldn't be found in CELUM
  • noMail (array of integers): the user ids for which the mail address is missing in CELUM
camundaCore.mail.from

type: string, required: yes, default: -

The email address which should be deplayed in the from field.

camundaCore.mail.bcc

type: string, required: no, default: -

If the bcc is set then this email address receives a copy of every mail that was sent with this mail service.

camundaCore.mail.ignoreDeactivatedUsers

type: boolean, required: no, default: true

If set to true then deactivated users won't receive any mails and will be ignored.

Deployments

Dev Deployments

  1. Stop the CELUM app server service
  2. Stop the Camunda service
  3. Update the Camunda *.jar-File
  4. Update the Camunda connector for CELUM (either core or customized extension)
  5. Delete the Camunda tables in the Camunda database
  6. Start the Camunda service
  7. Start the CELUM app server service
  8. Run the "Camunda > User and Group Sync Sanitize" system task in CELUM

Prod Deployments

  1. Stop the CELUM app server service
  2. Stop the Camunda service
  3. Update the Camunda *.jar-File
  4. Start the Camunda service
  5. Migrate the running process instances if required (or skip this step and let them complete using the old process definition)
  6. Update the Camunda connector for CELUM (either core or customized extension)
  7. Start the CELUM app server service
  8. If the process instances weren't migrated wait until all old process instances have finished and then do a clean-up of the stuff in CELUM that was only needed for the previous process definition and is removable now (e.g. information fields that aren't needed anymore)

Compatibility Matrix

Camunda Core CELUM
1.0.0 5.13.4 (tested with 6.4)

Release Notes

1.0.0

Released 2020-03-09

Initial version