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 setup 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 data base, 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.

Configure trigger event

These parameters define the event that triggers the action.

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.

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

1. Marks events as batched.

2. Groups events with a specific criterion. Currently, the only criterion that you can select is the asset ID.

3. 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.

4. Fetches the next chunk of assets.

The parameters:

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.

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.

Configure update status (optional)

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

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.

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 have 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.

• A 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.

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.

Process limit

The process limit is the maximum number of events that are processed in parallel. Only active at persistant 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:

1. Edit

2. Save and close

3. Asset updated

4. 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 setup 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 sub commands 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:  

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.

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 tasks is split into two work packages (2 x 20). The root command forks two new command instances.
• Each of this command 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 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 tasks is split into 40 work packages (40 x 1). The root command forks 40 new command instances.
• Each of this command 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 into max 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 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 this command 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 this command 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.