Automation Rules

Overview

Automation Rules functionality in Encodify system allows to configure an action that will be applied to an item when specified condition is met for the item(s). 

Originally developed for CA Print Studio to automate the process of template assignment for Inputs items, automation rules can also be used as an individual actions starting from version 9.105. (For version 9.104.0 this action type is in Beta version).

Automation Rules overview page is available on clicking a separate menu on Dashboard.

Access Restriction

As per release 9.104.0 Rules overview and configuration page is available solely to the user with Site/System Admin rights.

Starting from version 9.105.0, access to rules configuration is configured on the user access right level per each rule type individually.

Actions Configuration

For Automation Rules to be applied in the UI, the module has to have Actions configured in the Site Configuration. 

Site Configuration > {Module Name} > Actions

To configure action allowing execution rules on items from current module:

1. Click 'Create Action' button from Actions to create new action

2. Select 'Create and Update' from the 'Event' dropdown list

3. Select 'Execute Task' from the 'Action' dropdown list

4. Select 'Execute selection rules' from the 'Task Name' dropdown list

5. Click 'OK' button

To configure action allowing execution rules on items from another module:

1. Click 'Create Action' button from Actions to create new action

2. Select 'Create and Update' from the 'Event' dropdown list

3. Select 'Execute Task' from the 'Action' dropdown list

4. Select 'Execute selection rules' from the 'Task Name' dropdown list

5. Select module link field from the 'Field with Items in Remote Module for Executing Rules' dropdown list

6. Select rule(s) in the 'Rules' multiselect field

7. Click 'OK' button

Execute selection rules configuration page

Where:

• "Field with Items in Remote Module for Executing Rules" - contains field with items; rules will be executed for item/items in that field

• "Rules" - contains active selection rules that will be executed for all items from the field above.

Automation Rules Overview Page

Automation Rules page displays the list of already created Rules ordered by Sort Order. From the Automation Rules page it is possible:

• Enable/Disable existing rules

• Filter list of Rules by Module

• Create a new Rule

• Bulk-enable/Disable rules 

• Bulk-delete rules

• Open rule configiraton page

Automation Rule Types:

THIS DOCUMENT IS WORK IN PROGRESS

• Selection - Static

• Selection - Dynamic

• Validation

• Formatting

• Merge PDF

• Notifications

Selection Rules

Pay attention, you have to configure an action for triggering the selection rules. See Actions Configuration chapter.

Starting from version 9.105 there are 2 types of Automation Selection rules: Static and Dynamic.

• Selection Rule - Static assigns predefined field value selected in rule configuration when rule conditions are met.

Example: Set "Template" field value to "Template A4" if Format field equals A4.

• Selection Rule - Dynamic allows populating fields with values by matching field values of source item and items in linked module. In other words field values of the source item will be used as a search criteria to find items(options) in the linked module.

Example of such rule can be assigning/linking images to a product based on the values of Format and Brand.

Pictures:

Products with assigned pictures based on values of Format and Brand fields:

Create a Static Rule

1. Click the Add Rule button to open New Automation Rule Configuration Page.

1. Enter descriptive name for the rule.

2. Select a module from the Module select box.

3. In Conditions section it is possible to add conditions and groups of conditions based on fields and field values.

4. In the Selection type selectbox, select Static.

5. Specify field value that will be set when all configured conditions are met in Action section. Note that Action section allows configuration of 1 action only and supports only fields of the type Module links (single and multi-select).

6. Save the changes. As long as rule is enabled it will be applied when corresponding action is triggered in the module. 

For applying rules in CA Print Studio, no additional configuration is needed. Rules is applied on the Output generation step assigning templates to the Input items.

Create a Dynamic Rule

1. Click the Add Rule button to open New Automation Rule Configuration Page.

1. Enter descriptive name for the rule.

2. Select a module from the Module select box.

3. Add conditions in Conditions section.

4. Select Dynamic in the Selection Type selectbox

5. In the Field Mapping section, select module link field that will be populated as a result of rule execution.

6. Value of the Module field will be automatically prefilled with current module. Value of the Lookup Module field will be automatically prefilled with module previously selected module link is pointing to.

7. In the following When section select fields in source and taregt modules that will be used to match items/options in Lookup module.

Field types supported in Dynamic rules mappings:

• Module link

• Text

• Decimal numeral

• Integer

• Fields taking options from site configuration (Country, Region etc)

• User fields

• Searchable text concatenation

• Automatic Numbering (starting from release 11.1.0)

Dynamic rules can also be applied in CA Print Studio on the Output generation step.

Starting from version 15.0.0 Selection rules start respecting Filters on Module Links. Meaning: only options selectable by filter restrictions will be populated by ‘Selection’ rule from now on.

Important to know: ‘Selection’ automation rule is performed under System user, so:

• Group and Status restrictions are ignored while populating options by selection rule

• Filter by Current User cannot be applied

Conditions

This configuration is the same for all rule types. It defines the field or function to match condition that can be a field, a value or a function.

Field as condition:

example: field: 'text' is EQUAL to field 'fixed text'

Value as condition:

example: field 'Name' is EQUAL to value 'James'

List of Field Types and Supported Operators/Expressions

THIS DOCUMENT IS WORK IN PROGRESS

Please, note: Separator, File Info and XMP fields are not available in Conditions.

Functions in Rules

It is possible to use a formula as a value for comparison. The formula may include the math operators, numerics, and functions.

Available Functions:

• LENGTH

• IS UNIQUE

• CURRENT TIMESTAMP

• START OF PERIOD

• ADD DATE

Operator/Expression:

• is EQUAL to

• is NOT EQUAL to

• is NULL

• is NOT NULL

• is LESS than

• is GREATER than

• is LESS than or EQUAL to

• is GREATER than or EQUAL to

Target for comparison Functions:

• CURRENT TIMESTAMP

• START OF PERIOD

• ADD DATE

• Trigger Action in (starting from version 15.0.0)

With 'Trigger Action in' function, it is possible to make delayed Email Notifications Rule, which will be triggered when a certain date comes. It is required to have Field Object Watcher Scheduler Job running to handle delayed actions and rules. Examples:

• Date IS GREATER than Trigger Action in 1 Day(s) - equivalent of Trigger Action 1 day After deadline (as in actions)

• Date IS LESS than Trigger Action in 1 Day(s) - equivalent of Trigger Action 1 day Before deadline (as in actions)

Rule Conjunction

It is possible to combine several rules into one using AND/OR conjunction logic in Conditions:

Rules for different date accuracy formats

Date field can be configured with different skeletons which can show date with different accuracy (time, day, week, month, year):

• ww-YYYY;

• mm-YYYY;

• dd-MM-YYYY;

• dd-MM-YYYY hh:mm;

• etc.

Rules can be applied to fields with different accuracies:

Create Nested Structure

THIS DOCUMENT IS WORK IN PROGRESS

Nested structure is nothing but structure within structure. One condition can be created inside other condition.  

How to configure a nested structure within Automation Rule Conditions:

1. From left side of the condition, select Function == CURRENT TIMESTAMP

2. From right side of the condition select any of the available functions

3. Click 3 dot menu to select different function than previously selected

4. Enter desired values on each field

Validation Rules

Starting from version 10.2 Validation Rule types can be configured using Automation Rules.

Validation Rule allows checking the value against some custom logic and show validation message if the value is incorrect. For example, the start date cannot be later than the end date of the campaign, or name field cannot be empty.

The Rule Configuration window for Validation Rule:

Starting from v.17.0.0 it is possible to select options "Do NOT Match" and "Match" to evaluate rule and show validation message depending on whether conditions met selected option or not.

It is also possible to specify target fields to apply validation message to. In case of no target fields are specified - validation message will be applied to the fields from conditions.

Several actions can be added within validation rule configuration.Each added action allows to specify validation message and set of target filed(s) to apply validation message to.

Please note:

It is not allowed to add several actions with contradicted options "Do NOT Match" and "Match" within one validation rule configuration.

It is not allowed to specify the same target field(s) in several actions.

In case of adding several actions - "Target filed(s)" filed becomes required.

Validation rule applied:

When saving a new item that violates the validation rule, an error message is displayed:

Please note: validation message for corresponding field is shown after interaction with it.

Formatting Rules

Starting from version 10.2 Formatting Rule types can be configured using Automation Rules.

Formatting Rule allows applying custom formatting to the field that depends on its value. For example, change the color of the item's status.

There are 2 types of formatting rules available Full Cell and Chip.

Full Cell: As the name suggests, the formatting is applied to the full cell of the field

Chip: Formatting rules for this type are only applied inside of the 'cell' or 'bubble' containing the values. 

The Rule Configuration window for Formatting Rule:

Formatting Rules: Type Full Cell

Using full cell as type for a formatting rule can be used for all format the fields types. 

Main color will be applied to text, border and icon colors using the Hex Value selector

Background Color defines the cell color of the entire cell

Preview on the right side of the Actions pane will display the preview of the formatting rule

Adding Borders

Borders can be added to include cell border color. This will be the same color as selected for the text i.e. 'Main Color. This function is available for both Full Cell and Chip types.

Adding an Icon

Icon can be added to the formatted field using 'Select Icon' dropdown list.  This function is available for both Full Cell and Chip types.

Full Cell type Formatting rule applied:

This is what the outcome of the above rule would look like inside Item Info Sheet for type full cell:

Formatting Rules: Type Chip

When using formatting rule type chip, the 'Format the Fields' can contain only status, single option or multiple option field types.

If a wrong field type is used, an error message is displayed when clicking 'save' and rule will not be saved.

Main color will be applied to text, border and icon colors using the Hex Value selector

Background Color defines the background color of the chip - cell color will remain transparent/white

Preview on the right side of the Actions pane will display the preview of the formatting rule

Chip type Formatting rule applied:

This is what the outcome of the above rule would look like inside Item Info Sheet for type chip:

Merge PDF Rules

Merge PDF rules can be used as part of Creative Automation Print Studio for merging PDFs. 

⚠️Merge PDF rule will be created automatically after migration if there were existed Merge PDF action(s) on the site.

Merge PDF Settings section contains features to be applied while merging:

• Search Key: Value to be used for searching rules available for specific group. As a result a list of ‘Merge PDF Rules’ will contain only rules that match the defined grouping. 

⚠️ Search Key uses "exact match" logic

• Copies: Source document will be repeated set number of times.

• Size App: Select previously configured Sizes app that enables output page combinations for the specified page size. Follow the link for Sizes app configuration instruction. Note, that feature is controlled by the feature flag.

• Size Field: Module link to the "Sizes" module storing the width and height values of different paper sizes.

• Field-To-Field Mapping: Select previously configured Many To One mapping. Follow the link for Field-To-Field Mapping for configuration instruction.

• Fill Page: toggle, if enabled - same source document will be repeated until current page is full.

⚠️ Copies field is ignored when Fill Page is enabled

• Direction: Select direction in which files will be generated on the merged pdf. There are 4 possible options: left to right, top to bottom from left, right to left, top to bottom from right.

• Rotation: Defines which pages are rotated with options: Odd, Even, Odd and Even. 

Example: when the document is repeated once and the rotation set Even it will always rotate the duplicated output. When there is no repetition and the rotation set to Even it will always rotate outputs 2, 4, 6 etc depending on the order of outputs in search results.

• File Name Formula: expression using velocity engine for formula evaluation that defines the name of the generated merged output pdf. Examples in the table below demonstrate functions that can be used to fetch output file name.

Notifications Rules

Starting from release 15.0.0, when configuring Automation Rules, it is possible to create a rule to define notifications so that you can easily maintain how users will be notified about key events (sub-types).

All previously created 'Send Email' actions will be migrated to the Notifications rules with the corresponding sub-types.

To create a Notification Rule, in general, you need to follow the following instruction:

1. Go to Automation Rules tab

2. Click on "Add Rules" button

3. Select "Notifications" in the field "Type"

4. Select one of the desired "Sub-Types" (event, based on which you want to generate a Notification)

5. Select Module from the list

6. Add Conditions (if possible or necessary)

7. Select a recipient in field "TO" using one of the available methods

8. Select a channel

9. Fill in all other required fields following instructions in the placeholders

10. Check the Preview of the future Notification

11. Save changes

Of course, configuration page might be different depending on a selected Sub-Type and channel. But the standard sections, usually looks the same:

where,

• Skip in Batch Operations to avoid double notifications - checkbox applicable only to single item events. When enabled, Notifications to be skipped in bulk operations (example: if Rule configured on Update event and checkbox is selected, Notification will not be created after Bulk Edit).

• Conditions section is hidden for some Sub-Types, more Information in the table below.

• "TO" field helps to select a recipient of a notification. There are 2 possible options to set a recipient: by selection Users filed (so the user(s) selected in the field will be set as recipient(s)) and by Velocity Code (where users email can be either inserted from keyboard or specified by one of the velocity formulas).

Note!

• If any selection rules are configured for the module, notifications will be sent after all selection rules have been executed (regardless of sort order).

• If notification is triggered by the action, recepient specified in "To" field will receive the notification from the System Account.

• "IN" field contains channels available for the selected Sub-Type. We are supporting Application and Email channels. But, some of them can be hidden for selected Sub-Type. More info in the table below.

• "Syntax help" - hyperlink that leads to the help page containing a list of useful placeholders, formulas and available field definitions from selected module, that can be used as Velocity Code.

In the table below, you can find a list of all available Sub-Types and peculiarities of their configuration.

$CurrentItem.changes().oldValue('User')
* if 'User' field is a module link to User management module, it should point to the Email field.

SortTool in Velocity: Use of SortTool in Velocity is been enabled in version 19. This tool makes it easy to organize and manage lists of items in your templates.

Channel: Application

Application Channel can be used in order to generate an in-app notifications, that will appear on Notifications panel of the selected recipient.

For most of the Sub-Types configuration section of the Application channel looks the same:

Once user selects a corresponding channel, he can see a preview of the Notifications card at the right hand side of the screen.

Configuration extends for Create and Update Sub-Types:

where,

• ‘Reference field’ defines a custom link to the item. Any field can be selected here except MULTI_FILE,
  MULTI_SELECT, CHECK_BOX, SEPARATOR, TEXT_AREA.

  Reference field is always included to Fields updated section (if field was changed) on Notifications card and it will be always shown on the top of 'Fields updated' section

• ‘Custom Content' defines a text message to be shown on the card. Field accepts only usual text messages and doesn't handle Velocity Code.

• Field Values to Show in the Notification defines a list of field values to be shown on notifications card. It is possible to fetch old and new value from the item(s).

• Preview of the Notifications card at the right hand side of the screen.

  Separator, calculation, concatenation and fixed text fields are not available for selection in ‘Reference field’ and 'Field Values to Show in the Notification' fields.

Channel: Email

Email Channel can be used in order to generate email notifications, that will be sent to the email address of the selected recipient.

where,

• 'Reply to',  CC’, ‘BCC’ - selecting either user field or defining velocity code to identify recipients

• 'Email Subject' - accepts either text or velocity code

• 'Email Layout' section defines the way of the visual representation for notification(s). It contains few possibilities: User can either select one of the 3 provided templates or create Custom template.

Some Sub-Types will require to fill in additional settings:

In order to trigger Notification for Batch Field Import Action sub-type, corresponding Import Templates have to be mapped with the rule in the field "Linked Field Import".

New setting was also added to the 'Copy to HTTP Server' actions. Now, to trigger Notifications rule for Copy to HTTP Action sub-type, corresponding rule should be selected in 'Copy to HTTP Server' action under Linked Notification Rules section:

Email Layout

• Custom HTML/CSS Code:

By selecting this Email Layout option, user need to create own Email Template in the 'Email Body' field. Preview of the created templated will be shown in the right hand side of the screen, for the better overview.

Please, be aware, that not all custom emails are going to be responsive, so won’t always look good in our preview in the right hand side of the screen.

• Easy Templates:

By selecting this Email Layout option user has a choice through 3 standard email templates that can be selected using radio button. Once one of them is selected, Email Content section appears, showing the list of required fields available on the template.

Note: 'Body Text' field supports rich text formatting, meaning that you can use standard tags for the line breaks (
) etc.

Channel: Slack

Slack as a notification channel is available if corresponding feature flag is enabled.

Before configuring notification rule with Channel Slack, app in Slack and connected service need to be configured. 

Slack and Connected Service Configuration

Step 1: Create app with manifest in slack.

1. Go to https://api.slack.com/apps

2. Click Create New App

   

3. Select From an app manifest in the window that appears

   

4. Select your workspace for which slack bot will be created.

   

5. Enter app manifest in either yaml or json format. Follow the link to get the config files. 

6. Click Next > Click Create.

   Once the app has been created, save the values of Client ID and Client Secret that will be needed to configure connected account and connected service for Slack in Encodify system.

7. Proceed with configuration of connected service here.

Slack Rule Configuration

Configuration of the rules for notifications in Slack is similar to the configuration of notification rules for "In App" channel, where "Slack" is selected as notification channel.

Channel: MS Teams

MS Teams as a notification channel is available if corresponding feature flag is enabled.

Before configuring notification rule with Channel MS Teams, app in MS Development Portal and MS Teams connected service need to be configured. 

MS Teams App Configuration in MS Development Portal:

Step 1: Create app with manifest in Microsoft Development Portal

1. Go to https://dev.teams.microsoft.com/apps

2. Click +New App (or Import existing one)

   

3. Name the App and click 'Add' button:

   

4. Navigate to Tools > Bot Management:

   

5. Click '+New Bot'

6. Name the Bot and click 'Add' button:

   

7. Click 'Client secret' > 'Add a client secret for your bot':

   

8. Store your newly generated client secret for later use:
   

9. Navigate to Apps >{App Name} > App Features > Bot:

   

10. Make sure your bot is selected as bot  in Select Existing Bot:

    

11. Navigate App > App package > Manifest

    

12. Get Manifest id (id) and your Client ID (bot id) needed for MS Teams connected service configuration:

13. Publish application by clicking "Publish" button on topbar. The publishing request must be confirmed by admin account on https://admin.teams.microsoft.com/policies/manage-apps 

MS Teams Bot Configuration in MS Azure:

1. Go to MS Azure,  navigate to Enterprise Applications > All Applications

2. Locate your 'MS Teams Bot' created earlier in MS Development Portal using global search on the top:

   

3. Next, select Overview from Manage section and copy Directory (tenant) ID that is needed for MS Teams connected service configuration:

   

4. Switch to API permissions tab

5. Add Microsoft Graph permissions and grant admin consent as below. Pay attention permission type should be "Application".

   Permissions

   • APIConnectors.ReadWrite.All

   • AppCatalog.ReadWrite.All

   • Chat.Read.All

   • ChatMember.Read.All

   • ChatMessage.Read.All

   • TeamsActivity.Send

   • TeamsAppInstallation.ReadForChat.All

   • TeamsAppInstallation.ReadWriteSelfForUser.All

   • User.ManageIdentities.All

   • User.Read.All

6. Navigate to Webapp > Connected Services to configure MS Connected Service.

MS Teams and Connected Service Configuration

See detailed instructions on how to configure MS Teams connected Service here.

MS Teams Rule Configuration

Configuration of the rules for notifications in MS Teams is similar to the configuration of notification rules for "In App" channel, where "Slack" is selected as notification channel.

Copying Automation Rules

Starting from version 11.0.0 the ability to copy existing Automation Rules will be available from Rules Search Results and from View Rule action ellipsis lists.

The function will be available for the following rule types:

• Selection - Static

• Selection - Dynamic

• Validation

• Formatting

• Create Nested Structure

Option 1: Copy rule from Search Results:

Click the Action Ellipsis ( 3 dots ) next to the Automation Rule you want to copy and Select 'Copy Rule'.

This will open an editable copy of the selected rule in a new window.

All content within original rule will be copied over:

• Name

• Description

• Type of Rule

• Sort Order

• All condition properties specified

• All action properties

Note: The Rule Status will be the same ( Disabled/Enabled ) as the original Automation Rule.

Option 2: Copy rule from View Rule window:

Same editable copy of the Automation Rule will be displayed as in option 1.

Adding Multiple Actions in a Single Rule 

Starting from version 11.0.0 users can add multiple actions in a single Automation Rule to apply multiple selection in an item.

The multiple actions are only available for rule type 'Selection - Static'.

Adding new action: New Action can be added using the '+ Add action' button located in the bottom of the Actions section.

Removing action: Actions can be removed using the 'remove' action icon behind each action.

Scope of multiple actions in a singe rule:

• Applies only for Automation Rules of type ‘Selection - Static’.

• Does not apply for rules types: ‘Selection - Dynamic', ‘Formatting’ nor ‘Validation’.

Search and Filtering of Automation Rules 

Automation rules can be filtered by 'Module' and by 'Type'. The filter criteria can be found under the 'Filter' button next to '+Add Rule' button.

The search results will update automatically to display any rules that are matching with the selected filter criteria.

If any filters are currently applied, then a circle appears on the top right corner of the Filter button.

Filter criteria panel can be collapsed and expanded using the 'Filter' button, while displaying the filtered search results.

Any actions ( edit, copy, delete, bulk edit, disable or enable ) can be performed normally to any Automation Rule from the filtered search results.

Starting from version 12.0.0 onward, 2 additional filter criteria 'Rule Name' and 'Status' are available:

Applied filters can be removed by clicking 'Clear All' button and the Automation Rules search results will display again all existing rules for that site.

Limitations

• Null evaluates to true for Less than 0 conditions

• It is not possible to set the value by rule for fields having default values configured

• Like Operator and Length Expression does work for comparison with the field. Only static values are supported.

• LIKE conditions should be used with % sign (like in SQL expressions). Example: %testPhrase% matches 1testPhrase1, testPhrase1, 1testPhrase

• Application Notifications can appear in the wrong order. Issue happens if dates are identical. Example: if Item was created by the user and it triggered action that updated the same item right afterwards, it might happen that notifications with Create and Update sub-type will appear on the panel in reverse order.

• [Fixed in v16] Notifications config: Only 10 emails are shown in recipients list.

• Application Notifications with sub-type "Delete" or "Inactivate": Notifications will not be generated if the item is deleted via auto delete action.

• Batch Operations: Timeline 2 views display all items when opening a list of items with Batch ID.

Classes for Debug

dk.encode.ebms.core.rule.ExecuteSelectionRuleServiceImpl