Configure the Task Management App

This article explains the available configuration options for the Activiti task management in the CMS.

Starting with CMP 7.16 (which contains Gentics CMS 5.45) this is no longer supported.

1 Base configuration

To configure the task management app create a gentics-activiti.properties file in the /Node/etc/ directory on the CMS-server (or on the server where the task management app is running). Make sure the Java-Process under which the app runs is allowed to read the file. If the tomcat server for activiti does not have access to the /Node/etc/ directory, you can also place the properties file into a custom location and set the JVM system property com.gentics.activiti.config to the location of the properties file.
(e.g.: -Dcom.gentics.activiti.config=/my/custom/location/activiti.properties)

1.1 Database

To configure the database access for the task management please add the following properties

gentics-activiti.properties

db=mysql
jdbc.driver=org.mariadb.jdbc.Driver
jdbc.url=jdbc:mariadb://<URL_TO_ACTIVITI_DB>
jdbc.username=<DB_USERNAME>
jdbc.password=<DB_PASSWORD>

We currently only support MySQL-Databases for the activiti task management app.

You maybe also need to configure SSL properties in the MySQL JDBC URL. Read the MySQL SSL documentation for more information.

1.2 CMS connection

To configure access to the CMS REST API the following properties need to be set

gentics-activiti.properties

cms.rest.url=http://<HOSTNAME>/CNPortletapp/rest/
cms.rest.username=<USERNAME>
cms.rest.password=<PASSWORD>

The CMS user used by the engine to access the CMS REST API must have the Administration priviledge on Task Management and must be member of a sufficiently high CMS group. Users that can not be managed by this user will not be able to properly use the Task Management.

1.3 Other configuration properties

gentics-activiti.properties

activiti.app.available-processes.keys=onetaskprocess,dummyprocess
activiti.task.enable.comments=langselectTask
activiti.task.enable.files=langselectTask
  • activiti.app.available-processes.keys may contain a comma separated list of process definition keys of processes, that may be started directly from the UI
  • activiti.task.enable.comments may contain a comma separated list of task ids of tasks, for which comments should be available
  • activiti.task.enable.files may contain a comma separated list of task ids of tasks, for which file attachments should be available

1.4 Configuring access to the activiti server

Node/etc/conf.d/*.conf

$ACTIVITI_BASEURL = "/activiti"; ## /activiti is the default value

1.5 Triggering processes

It is possible to start processes automatically on certain CMS events like saving, deleting or moving objects. The configuration is done via the $PROCESSES variable which can be defined in any /Node/etc/conf.d/*.conf file. The two configuration entries are

  • triggers, and
  • failureHandling.
1.5.1 Possible triggers

The field triggers contains a mapping from “CMS events” to lists of processes to be triggered. Currently the following events can be used to trigger processes:

  • onContentFileDelete: a file or image has been deleted or put into the wastebin
  • onContentFileMove: a file or image has been moved
  • onContentFileSave: a file or image has been created or saved
  • onFolderDelete: a folder has been deleted or put into the wastebin
  • onFolderMove: a folder has been moved
  • onFolderSave: a folder has been created or saved
  • onPageDelete: a page has been deleted or put in to the wastebin
  • onPageMove: a page has been moved
  • onPagePublish: a page has been published
  • onPageSave: a page has been created or saved
  • onPageTakeOffline: a page has been taken offline
  • onFormDelete: a form has been deleted or put in to the wastebin
  • onFormMove: a form has been moved
  • onFormPublish: a form has been published
  • onFormSave: a form has been created or saved
  • onFormTakeOffline: a form has been taken offline
1.5.2 Provided data

Every process started by the ActivitiJob will get the ID of the “triggering” object1. This will be passed to the process as a form field, where the name is the type of the object. Depending on the type of the event, different data will be passed to the process (provided in the form field data):

  • for *Delete events:
    • folderId (Integer): the ID of the folder that contained the object2
    • name (String): the name of the deleted object
    • userId (Integer): the ID of the user, who deleted the object
    • wastebin (boolean): true when the object was put into the wastebin, false when it was actually removed.
  • for *Move events:
    • srcId (Integer): the ID of the source folder
    • dstId (Integer): the ID of the destination folder
  • for *Save events:
    • isNew (boolean): whether the object was newly created
    • userId (Integer): the ID of the user who saved the page
  • for the onPagePublish and onFormPublish events:
    • publisherId (Integer): the ID of the user who published the page/form
  • for the onPageTakeOffline and onFormTakeOffline events:
    • userId (Integer): he ID of the user who took the page/form offline
    • wasOnline (boolean): true when the page/form was online before, false otherwise.

1 This ID will be 0 on *Delete events which did not put the object into the wastebin, as the object is already deleted from the database at the time the process is started

2 This ID will be 0 on onTemplateDelete events, as templates do not reside in folders

1.5.3 Defining processes to be started

As mentioned the triggers field in the $PROCESSES configuration is a mapping of “events” to a list of processes to be started. Each entry supports the following fields:

  • constraint (String): a string that will be evaluated by the Expression Parser. The specified process will only be started, if the given constraint evaluates to true. The object that “triggered” the event will be available as a resolvable under the name of its type (contentfile, folder, page and template). Note that an invalid or empty constraint will be interpreted as false and the process will not be started. Another thing to consider is that if the triggering object is in a channel, the expression will be evaluated in the scope this channel, and it is not possible to reference any master objects in the constraint expression.
  • customData (Map): A key → value map of custom data for the process. The entries of this map will be merged with the form field data that will be passed to the process.
  • processKey (String, required): the key of the process to be started

When the constraint accesses tags (e.g. object tags) of objects, the render() function needs to be used. For example the constraint folder.object.name_de == "Ordner" will never work, whereas render(folder.object.name_de) == "Ordner" will work for folders, that have the object property “name_de” set to “Ordner”.

1.5.4 Shorthand notations

A single string in the list of processes will be interpreted as a process key, and a single entry for a trigger name will be wrapped in a list, so it is possible to write


$PROCESSES['triggers'] = array(
	'onPageSave' => array(
		'doSomething',
		array(
			'processKey' => 'doSomethingElse',
			'constraint' => 'page.folder.node.id == 23',
			'customData' => array('ignoreLanguageVariants' => 'true')
		)
	),
	'onFolderMove' => 'handleFolderMove'
)

which will be interpreted as


$PROCESSES['triggers'] = array(
	'onPageSave' => array(
		array('processKey' => 'doSomething'),
		array(
			'processKey' => 'doSomethingElse',
			'constraint' => 'page.folder.node.id == 23',
			'customData' => array('ignoreLanguageVariants' => 'true')
		)
	),
	'onFolderMove' => array(
		array('processKey' => 'handleFolderMove')
	)
)
1.5.5 Failure handling

The possible values for $PROCESSES['failureHandling'] are

  • Retry: entries in the *_processes tables will be marked as erroneous, when they did not terminate normally, but every time the ActivitiJob runs, they will be processed again.
  • Mark: erroneous entries in the corresponding tables will be marked as such, but they are will be ignored further on.
  • Ignore: entries corresponding to failed processes in the current ActivitiJob run will just be deleted from the process queue.
  • Purge: same as Ignore but all marked entries will be deleted.

1.6 Custom Processes

See Create Processes Webapp

1.7 Custom Translations

See Configuration of Custom Translations

1.8 Enabling the Task Management Custom Tool in the New UI

To enable the Task Management Custom Tool in the new UI you must add the following to your Gentics CMS configuration:

Node/etc/conf.d/*.conf

$CUSTOM_TOOLS[] = array(
    "id" => 1, // or whatever ID you want this tool to have
    "key" => "task-management",
    "toolUrl" => '/tools/task-management/?sid=${SID}',
    "iconUrl" => "assignment", // Material Icon name or a URL
    "name" => array(
        "de" => "Aufgaben-Management",
        "en" => "Task Management"
    ),
    "newtab" => false
);

For more information regarding custom tools, please see Custom Tools

2 Scheduler

The scheduler can be used to start Activiti processes in the scheduler at certain times or manually.

There is already a task template called “Activiti process” which can be used to create a task and a task event. Please note that the the activiti_variables parameter must be set in the following format:

var1: 123, var2: 456

3 Permission settings

The permission settings for the CMS groups on the “Task Management” will be mapped to group types in activiti:

  • Groups with the Show and Administration setting will have the group type admin in activiti and will be able to see and manage process instances.
  • Groups with the Show setting will have the group type user in activiti and will be able to use the task management as users.
  • Groups without the Show setting will have the group type guest in activiti. Users in those groups will not be able to use the task management, but may still be assignee of open tasks.