Configure automatic server actions

Automatic server actions execute multiple-step operations in censhare. Actions are triggered by defined events and executed on all assets that match the trigger event condition. Learn how to configure the events and optional asset filters for automatic server actions.

Target groups

System administrators

Context

Automatic server actions are configured in the censhare Admin Client in the respective action configuration in the Configuration/Modules directory.

Prerequisites

You can only enable and set up an automatic server action if a configuration file [server action name] (automatic) exists. Automatic server actions are configured independently from the manual server actions.

Introduction

Any operation in censhare that changes asset data is considered an asset action. For the censhare server and database, it makes no difference whether the data manipulation is initiated manually or automatically. Therefore, most asset actions can be configured for manual and/or automatic execution.

The trigger for automatic actions can be a simple timer or cron event, or any asset event that is logged in the server log. Time-based, periodic trigger events are fired independently from asset operations. Asset-event triggers require a previous action that can for their part be manual or automatic.

The target of an automatic server action can be a single asset, an asset structure or multiple assets in a mass editing. For example, the asset event Asset workflow changed can be launched:

on a single asset, when this asset is edited and set to a new workflow step,
on an asset structure, when the new workflow step is inherited to all child assets,
on multiple assets, when the workflow step is updated with the mass edit wizard.

Setup

These parameters define how censhare handles and processes the trigger events.

Field	Remarks
Work package size	Events are submitted to an instance in packages. The work package size sets the maximum number of events that censhare processes per command instance.
Sync Timeout	Only applies when Sync is selected. Defines when a fork process terminates if there is no response.
Persistent events	If disabled, tasks are only written in the command queue. If a command or server fails, the task cannot be restored. If enabled, censhare creates a persistent event. Persistent events are written in the command queue and stored in the event_task table of the censhare database. Persistent events are restored after a server failure.
Process limit	Defines the maximum number of events that censhare processes simultaneously from the event_task table. This parameter only works when persistent events and parallel execution are enabled. The process limit counts for all instances in total. For example, the process limit is 10 and there are 2 instances already working on 10 event tasks. If a third instance is started, it stays idle because the process limit is already reached. censhare checks after a defined time if there are still event tasks in the table: When a new instance starts, it processes no more event tasks than half of the process limit, in this example 5 event tasks. This reserves the capacity to process new incoming event tasks. The reduction of 50% is hard-coded.
Retries on error	Sets the number of retries before the process is skipped.
Local file system	Limits recognition of trigger events to events on the local file system. For example, preview images.
Ignore remote events	Enable this field to filter trigger events from remote servers. Events are only accepted when they are created on the Master server.

Configure trigger event

These parameters define the event that triggers the action.

Field	Description
Asset events	Shows pre-defined asset events that are logged in the server logs and can trigger an action. For example, when a user saves and closes an asset, the Save and Close event triggers the action. If you define multiple asset events, any of these events triggers the action. The server action can be related or unrelated to the asset event that triggers an action. For more information, see Hints & tips.
Timer event	Enter a period (in seconds) to trigger the action. For more information, see Hints & tips.
Cron event	Enter a cron expression to trigger the action. For more information, see Hints & tips.
Generic asset events	Configure any asset event that is logged in censhare as trigger event.

Configure asset filters (optional)

censhare executes the action only on assets that match the filter conditions. For more information see Configure asset filters.

Configure server action for asset structures (optional)

Actions can be applied to asset structures. For example, if an action is executed on a Product asset, the same action also applies to all Product items related to that asset. You can configure asset relations or asset references here and apply additional asset filters for related and referenced assets.

Field	Description
Hierarchical	Activate this field to show the configuration options for asset structures. The following fields are only visible if "Hierarchical" is enabled.
Relation types	Select a relation type and sub-type to which the command is applied.
Features	The list shows features of the type "Asset reference". These features reference assets using their ID. The command is applied to assets referenced in the selected features. For more information see Create asset features.
Asset reference features	The list shows features of the type "Asset key reference". These features reference assets using their resource key. The command is applied to assets referenced in the selected features. For more information see Create asset features.
Asset filters	censhare executes the action only on child assets or referenced assets that match the filter conditions. For more information see Configure asset filters.

Configure batch event processing (optional)

Batch event processing reduces the load on the censhare Server. Batch processing groups asset events for the related server action. The server action is then executed only once per group.

Batch event processing is recommended for the following conditions:

Many asset events occur in a short time for the same asset.
The automatic server action cannot execute on an asset after each update event. It is enough to execute only once after a series of update events.

With batch event processing, censhare does not execute an automatic server action each time when a defined asset event occurs. Instead, censhare marks these events as processed and creates a new batch event for a group of source events. For example, based on certain rules, censhare aggregates events.

The batch events are processed at certain intervals that a cron pattern defines. For each batch event, censhare executes the related automatic server action.

Asset events are stored in the event_task database table. censhare fetches the events from the table in defined chunks and processes them as follows:

Marks events as batched.
Groups events with a specific criterion. Currently, the only criterion that you can select is the asset ID.
Stores each event group as a batch event in the event_task table. censhare creates a new batch event. Existing batch events are not updated.
Fetches the next chunk of assets.

The parameters:

Field	Comment
Batch handled events	Check the box to activate the batch handling. Activates the batch handling.
Cron pattern	Defines when the custom events are processed.
Group events by	Selects the grouping criteria for the asset events. Currently, asset ID is the only criterion available.
Event buffer size	Defines the number of events that censhare fetches from the database for one chunk.

Configure the server action for asset structures (optional)

Actions can be applied to asset structures. For example, if an action is executed on a Product asset, the same action also applies to all Product items related to that asset. You can configure asset relations or asset references and apply additional asset filters for related and referenced assets.

Field	Description
Hierarchical	Activate this field to show the configuration options for asset structures.
Relation types	Select the relation types and sub-types to which the command is applied.
Features	The list shows features of the Asset reference type that reference assets with their ID. The command is applied to assets that are referenced in the selected features. For more information see Create asset features.
Asset reference features	The list shows features of the type "Asset key reference" that reference assets by using their resource key. The command is applied to assets referenced in the selected features. For more information see Create asset features.
Asset filters	censhare executes the action only on related or referenced assets that match the filter conditions. For more information, see Configure asset filters.

Set mode and user (optional)

censhare can check out assets while they are processed. This method prevents users from working on them. You can also assign a system user to the action. Use this to track the actions in the asset history.

Field	Remarks
Modification mode	Perform asset check out/check in locks assets while processing them. With Perform asset check out, assets remain locked after processing.
Process user	Assign a user to the action.

Configure update status (optional)

Update the workflow step or any asset property of the processed assets.

Field	Remarks
Update assets afterwards	Activate this field to show the configuration options for status updates.
Type filter	Limit the status update to the selected asset type. Create multiple status updates for different types.
Workflow / Workflow step	Assign assets to a new workflow and workflow step.
Workflow target	Assign the asset to a new user.
Domain	Assign the asset to a new domain.
2nd domain	Assign the asset to a new second domain.
Features	Select a feature and the value. When an asset is processed, the feature is updated to the new. If the feature does not exist, censhare creates it. Existing features can be deleted. Date values and asset references can only be deleted, but not updated. You can add/update multiple features in one action.

Configure follow-up asset events (optional)

Fire asset events when an action is finished. These events are written in the event log and can be used to monitor automatic actions or create actions based on these events.

Field	Remarks
Finished	Select the default event Task calculation completed.
Skipped	Select the default event Task calculation completed and add a log message to indicate that the action was skipped.
Failed	Select the default event Task calculation completed and add a log message to indicate that the action failed.

Hints & tips

General

A censhare server sends events
If a command is listening to an event, a task is being generated.
An event is going to be discarded if no command is listening to it.
A command can start working based on time (cron expression/timer event) and on events.
Every command has its own queue for incoming events. This can be viewed in AdminClient/Status/Commands
There is also an event queue in the Oracle database (event task).
Note the difference between command event queue and event task.

Work package size

The work package size is the maximum number of events of an instance.

An instance is a command instance. One instance will be created at server start and it can be called the root instance of a command. By default, the instance is in wait state.
Events will be submitted in packages to the command.
The XML-queue-size sets the maximum submitted events per package.
Also, fewer events than the XML-queue-size can be submitted in a package to the command.

Parallel execution

The parallel execution with multiple instances.

Parallel execution ON

Parallel execution OFF

More Instances of a command can be started = parallel working.

Tasks for a command start a new command instance, a subcommand.
The root command instance remains in wait state and is waiting for new tasks.
A new task starts a new command instance, a subcommand instance.
The root command instance remains in wait state and is waiting for new tasks.

Only one instance, the root instance of a command exists = serial working.

Tasks for a command wake up the root instance of the command.
The root command instance changes to active state and processes the events. No further command is created.
If the command has finished, the next events will be processed.

Persistent events

Events are stored in the event task table. Therefore they cannot get lost and can be executed by other application servers. A censhare server sends events and if a command is listening to an event, a task will be generated.

Persistent events ON	Persistent events OFF
Tasks are written into the command queue and event task. An active task is labeled and counted in the event task. Tasks can be resumed after failure.	Tasks are written into the command queue. Tasks will be lost if the command fails to process them, if the server stops working, or shuts down.

Process limit

The process limit is the maximum number of events that are processed in parallel. Only active at persistent events and parallel execution.

Only used if persistent events are switched ON.
Number of maximum requested tasks are labeled as EXECUTING in the event task table.
If parallel execution is enabled and more instances are started, only half of the limit is caught out of the event tasks.
If parallel execution is enabled and more instances are started, this limit applies to all commands together.

Asset events

When censhare processes an asset, it logs a series of asset events. For example, if a user checks out, edits, saves and checks in an asset, censhare creates a series of asset events that are logged:

Edit
Save and close
Asset updated
Asset changed

Timer events

A timer event is a simple time setting that forces censhare to execute a server action periodically. The base unit of a timer event is seconds. For example, if set a timer event value of 300, censhare executes the respective server action every 5 minutes.

The number of tasks is determined by the result of the search. The search and result limit is defined in the filter section of the command.
If persistent event processing is switched OFF, the command creates the events and the events are written into the command queue. The event task is not used. If you set up a very short timer event and the command can not process the search result before the next timer event happens, you can observe a growing command event queue. To avoid this, extend the time between the command calls.
If persistent event processing is switched ON, the command creates the events and they are written into the event task table. The event task is used.
In both cases, events are submitted to the limit of the search filter.
If parallel execution is switched ON, it is applied. Further command instances can be forked from the root command and use server resources.

Be aware that timer events can cause a high server load if you define a short period and/or a high number of server actions with a timer event.

Too many search results can result in performance problems or even a complete server downtime. To prevent that, switch off parallel execution and/or reduce the filter limit.

Example: A command is configured parallel but not persistent. The limit in the asset filter is set to 50. All 50 results are written in the command queue. 50 subcommands start at the same time and work on this queue.

Cron events

Use cron events to define a more fine-grained periodic execution of a server action than with time event. This is done in the Cron pattern field in the configuration dialog:

Field	Allowed values
Minute	0-59
Hour	0-23
Day of month	1-31
Month	1-12 (or names)
Day of week	0-7 (0 or 7 is Sun, or use names)

The syntax of a cron expression expects a value for each relevant field or an asterisk (*) for each field to be ignored. For instance, use an asterisk (*) for "first-last''. For example, the pattern "0 4 * * *" starts the command every day at 4 a.m. For more information, execute "man 5 crontab" in a terminal window.

Cron expression	Execution
1 0 * * *	Every day one minute past midnight.
1 0 * * 5	Weekly every Friday one minute past midnight (The value 0 corresponds to Sunday, the value 6 to Saturday).
0 0 1 * *	Monthly ate midnight of the first day of the month.
59 23 31 12 *	Yearly at 23:59 of 31st December.

Examples

Example 1

Parameter:

Work package 20
Parallel ON
Persistent OFF
Process limit 10

Task:

40 Events occur simultaneously

Important:

The process limit has no effect because persistent is switched OFF.
The Tasks will be split into two work packages (2 x 20). The root command will fork two new Command instances.
These two commands run unlimited to process their tasks.
Then 20 new events will be sent to the command:
One work package with 20 (1 x 20) tasks will be generated and a further command instance will be forked from the root command.
Now three commands are using the server resources to process their tasks.
Further events for the command: further command instances are forked from the root command and use server resources.
In this example, the command is running unlimited.
In the worst case, this can result in performance problems or even a complete server downtime.

Example 2

Parameter:

Work package 20, parallel on, persistent on, process limit 10

Task:

40 Events occur simultaneously

Important:

The process limit is kept because persistent is switched ON.
The task is split into two work packages (2 x 20). The root command forks two new command instances.
Each of these commands tries to label his 20 tasks in the event task as EXECUTING.
As much as a total of 10 tasks are in progress. The other tasks will be ignored for now.
Then 20 new events are sent to the command:
- One work package with 20 (1 x 20) tasks will be generated
- A further command instance will be forked from the root command.
This new command also tries to label all of these 20 tasks in the event task as 'EXECUTING'.
But it can only label as much as a total of 10 tasks as in progress. The other tasks are ignored for now again.
When one of the command instances has finished its tasks, it is closed. Now the event task is checked if there are still tasks to do.
If so, a new command instance is forked and tries to label only 50% of the process limit (5 in this example) as EXECUTING in the Event Task.
In this example, the command is running limited.
Only in a few cases, this can cause performance problems. If so, you can reduce the process limit.

Example 3

Optimize the PDF creation command (aa-render-pdf) for maximum parallel processing on a single censhare application server.

Parameter:

1 censhare Render Client
20 InDesign-Server instances, logged into a single censhare application server
Work package 1
Parallel ON
Persistent ON
Process limit 40

Task:

40 Events occur simultaneously

Important:

The process limit is kept because persistent is switched ON.
This example is valid for every render command (for example: aa-place-collection).
The task is split into 40 work packages (40 x 1). The root command forks 40 new command instances.
Each of these commands tries to label his task in the event task as EXECUTING.
As much as a total of 40 tasks are in progress.
As only 20 renderer Instances are available, 20 commands have to wait for free instances.
Then 20 new events are sent to the command.
If all instances are in use, the events are stored in the event task.
When the active command instances have finished their tasks, they are closed.
Now the event task is checked if there are still tasks to do.
If so, new command instances are forked and try to label only 50% of the process limit (20 in this example) as EXECUTING in the Event Task.
This will lead to max of 20 new commands and all available InDesign-Server instances are used.

Example 4

Optimize PDF creation command (aa-render-pdf) for maximum parallel processing on a multi-censhare application server (master and x nodes, all with direct db connection).

Parameter:

1 censhare Render Client
1 InDesign-Server instance, logged into the master censhare application server
1 censhare Render Client with 1 InDesign-Server instance, logged into node server (this setting is only valid if for each node server a Render-Client + IDS instance is available and logged in)
Work package 1
Parallel ON
Persistent ON
Process limit 1
Ignore remote events disabled, so that no matter where the event is posted by the user, app1 or app2, both Render-Clients incl. their IDS instance(s) are fully loaded at any time.

Task:

40 Events occur simultaneously

Important:

The process limit is kept because persistent is switched ON.
This example is valid for every render command (for example: aa-place-collection).
The tasks are split into work packages of 1.
The root command forks 40 new command instances.
Each of these commands tries to label his task in the event task as EXECUTING.
As much as a total of 40 tasks is in progress.
As only 2 renderer (IDS) Instances are available
The remaining commands have to wait for free instances.

Example 5

Optimize PDF creation command (aa-render-pdf) for maximum parallel processing on a multi-censhare application server (master and x remotes, only master has direct db connection).

Parameter:

1 censhare Render Client
1 InDesign-Server instance, logged into master censhare application server
1 censhare Render Client with 1 InDesign-Server instance, logged into remote server (this setting is valid independently if on the other remote servers a Render Client (with IDS instances) is logged in)
Work package 1
Parallel ON
Persistent ON
Process limit 1
Ignore remote events enabled (we need to avoid that a job is rendered e.g. on master which is located in Munich, but the event was posted by a user logged onto the remote server in India)

Task:

40 Events occur simultaneously

Important:

The process limit is kept because persistent is switched ON.
This example is valid for every render command (for example aa-place-collection).
The tasks are split into work packages of 1.
The root command forks 40 new command instances.
Each of these commands tries to label his task in the event task as EXECUTING.
As much as a total of 40 tasks is in progress. As only 1 renderer (IDS) Instance is available.
The remaining commands have to wait for free instances.

Result

censhare runs the server action in the defined period or starts the server action when the defined trigger event is executed.

Next steps

Configure the server action in the respective sections of the configuration dialog. The configuration is identical to the respective manual configuration.