Skip to main content
Matrix42 Self-Service Help Center

Compliance Rules

Overview

Compliance rules define how Matrix42 Workspace Management reacts to specific data changes, such as sending alerts, creating tasks, starting Workflow, or changing data.

How to create Compliance Rule

  1. Start Matrix42 Workspace Management and click the Administration workspace.
  2. In the navigation area, click Services & Processes > Compliance Rules.
  3. On the toolbar, click New. An input wizard opens.
  4. Enter a name for the compliance rule and select the type of configuration item to monitor. Click Next.
  5. Select the condition type and one or more conditions that should be met for the compliance rule to apply. Click Next.
  6. Select the type of processing and the processing type. Click Next.
  7. Select actions that should be performed if the compliance rule applies.
  8. Click New to add additional actions.
  9. In the Action column, click a field to select the type of action.
  10. The Order column determines the sequence of actions to perform. Enter one number per row. The action with the lowest number is performed first; the one with the highest number is performed last.
  11. The Configured column displays whether each action is fully configured (green flag) or not (red flag). Only actions that are fully configured are performed.
  12. In the last column, click the button to configure the action.
  13. Click Finish.

Setting Names and Configuration Items

There are two main options when you create a compliance rule (CoRu):

  • Define a CoRu for a single CI (CI-based rules)
  • Define a CoRu for a number of CIs on the basis of a shared data definition (class-based rules)

The main difference is that the second option is more restrictive and supports conditions only for the shared data definition. As a result, you can create rules that can be shared by different connected CIs. Setting a corresponding target means that you create either a CI-based or a class-based CoRu.

Compliance Rules for a Configuration Item

CoRu_CI.png

You select a Configuration Item (CI) that will be a target; in this case, a CI-based CoRu is created. After you set the provided options, you proceed to the page where you can define how the CoRu is triggered.

Compliance Rules for a Data Definition

If you select a data definition, you will see a list of CIs that include this data definition. By selecting the checkboxes, you can choose the CIs with which your CoRu will work.

CoRu_DD.png

You select a data definition that will be a target; in this case, a class-based CoRu is created. After you set the provided options, you proceed to the page where you can define how the CoRu is triggered.

Setting Condition Types and Rule Conditions

CoRus can react to the following basic events:

  • Action was successfully completed.
  • Object/fragment was created.
  • Object/fragment was deleted.
  • Object/fragment was changed.
  • By external code.

Additional conditions can be defined for filtering the events that are generated by basic condition type to a precise number of business events, which will trigger the desired resulting action.

Action Was Successfully Completed

This condition type allows reactions to successful completion of specific actions inside of the system, such as relocating, closing, assigning a license, and so on. It means that the CoRu will be triggered by successful completion of the action.
Successful completion (for UI actions) is usually confirmed by:

  • clicking Finish,
  • clicking OK without any exceptions.

Successful completion for system actions (without the UI) is usually confirmed by completion of a code block without exceptions. You can also set data condition for actions, but be aware that the following condition clauses are not supported:

  • "Before" values of attributes.
  • Attribute was changed.
  • Relation was added/removed.
  • Fragment was added/removed.

CoRu_COND_ACT.png

Object/Fragment Was Created
  • For CI-based rules: When an object (instance of a configuration item - CI) is created, CoRus can react to it. The reaction will follow if the DataLayer or any other component inserts a record in a type table, for example, in SPSUserType.
  • For class-based rules: When a fragment is created, CoRus can react to it. The reaction will follow if the DataLayer or any other component inserts a record in a class table, for example, in SPSAssetClassBase.

Supports Data Conditions.

CoRu_COND_Create.png

Object/Fragment Was Deleted
  • For CI-based rules: When an object (instance of a configuration item - CI) is deleted, CoRus can react to it. The reaction will follow if the DataLayer or any other component deletes a record in a type table, for example, in SPSUserType.
  • For class-based rules: When a fragment is deleted, a CoRu can react to it. The reaction will follow if the DataLayer or any other component deleted a record in a class table, for example, in SPSAssetClassBase.

Supports Data Conditions.

CoRu_COND_delete.png

Object/Fragment Was Changed
  • For CI-based rules: You can define conditions on any data attribute that is a part of the CI (any data definition of the CI). You define a data condition that should result in successful evaluation for the CoRu to be triggered. Whenever any of the attributes that was stated in the condition is changed, the system evaluates the entire condition, and if its result is successful, the action is triggered. For more information about data conditions, see the next section.
  • For class-based rules: The only difference is that data conditions can be created only for a data definition that was selected as shared for the CoRu.

CoRu_DD.png

By External Code

This condition type allows a custom code to trigger a CoRu. This can be useful in the following cases:

  • Complex conditions that cannot be evaluated by using the supported features.
  • When no action or DB operation can trigger a CoRu. For example, some code in the workflow.

Besides, such rules cannot be executed manually by using the Execute action. If you want to use this option, please contact us.

CoRu_COND_Ex.png
Data Conditions

As previously stated, the created/deleted/changed conditions support additional data conditions. These conditions are statements that result in a logical expression (returns true or false).
You can:

  • define conditions only for attributes of all data definitions that are included in the CI (for CI-based CoRus) or attributes of a shared data definition (for class-based CoRus).
  • add several condition clauses and combine them with the AND/OR logical operators.
  • group several clauses together in a single group that acts such as '()'. To do it, mark several conditions while holding the SHIFT key.
  • set conditional operators and values to check on each clause.
Before/After Values

Each clause can check the value for either Before or After attribute values.

  • Before: Value of an attribute that it had before the change which activated a rule. It means that if a CoRu has a clause that checks for attribute value and it was updated, the system will check its value before the update.

It makes no sense to use the Before values for the created CoRus. CoRus that have the Before values cannot be processed online. They can be processed only either by the manual Execute action or by scheduled action that checks dates.

  • After: Value of an attribute after the change. You can also consider it to be the "current" value of an attribute.

There can be several possible cases depending on the attribute type:

  • Normal data attribute
  • Relational attribute
  • Pickup attribute
  • Date attribute
  • Multi-fragment
Normal Data Attribute

In case of a normal data attribute it is possible to select several conditional operators:

  • Changed: Tracks only changes and ignores the value.
  • Equals
  • Greater Than
  • Greater Or Equal
  • Is Empty: Checks for Null values in the DB.
  • Is Not Empty: Checks for Null values in the DB.
  • Less Or Equal
  • Less Than
  • Like
  • Not Like
  • Unequal
Pickup Attribute

Pickups have the same set of possible conditions as normal attributes except the Value column that provides a set of pickup values in a drop-down list.

In case of the CommonClass.State and CommonClass.Reason pickups, the list of possible values will be filtered by the assigned StateGroup of the target CI for the CoRu. If the StateGroup is not set for the CI, then all possible state values are displayed.

In case of the CommonClass.State and CommonClass.Reason pickups, the list of possible values will be filtered by the assigned StateGroup of the target CI for the CoRu. If the StateGroup is not set for the CI, then all possible state values are displayed.

Date Attribute


Date attributes have the same set of possible conditions as normal attributes except the Value column that supports special date syntax. As a rule, performing a date check does not make sense for fixed dates because the CoRus are created for objects in general and using fixed dates limits all objects to conform to a single condition, which is usually not desirable. Therefore, a special syntax exists. You can enter a keyword Today, which means that the value that the system compares to is taken as the current date. The value for dates also supports the +/- operators.

Example:


Today + 5 means that 5 days will be added to the current date. Same with subtraction.
Additionally, you can use values from any integer attribute of the same data definition in this expression: Today + MailNumberOfDaysBeforeExpiration. Besides, you can use an attribute value only without Today. So, the syntax for the date value is the following: [Today] [<+|-> AttributeName]
Relational Attribute

For relational attributes, there are several options:

  • Changed
  • Equals
  • Is Empty
  • Is Not Empty
  • Relation Added: True if a new relational binding is set for that attribute.
  • Relation Removed: True if a relational binding is removed for that attribute.
  • Unequals
Multi-Fragments

Sometimes the list of attributes contains only names of data definitions (not followed by attribute name). It means that these data definitions are multi-fragments. In this case the following operators are available:

  • Fragment Added: True if a new fragment has been added to an object.
  • Fragment Removed: True if a new fragment has been removed from an object.

Multi-fragments are not supported for class-based rules.

When Rules Are Triggered

There are several nuances that are related to the moment when a CoRu is triggered.

  • When you create a CoRu for the created/deleted/changed conditions, a database trigger is created. It means that the CoRu is triggered every time an operation in the DB takes place.
  • For created and deleted conditions, these triggers correspondingly react to the insert and delete operations that are performed in the database.
  • For the updated condition, an update trigger is created. It reacts only to changes of attributes that were stated in clauses. It means that the trigger first checks if an update was made to any attributes in clauses and only then checks if the conditions are met.
Additional Condition Types: Attributes and Expressions

As previously stated, you can enter a value to compare it with in the Value field of a clause. Additionally, you can set an attribute that you want to compare or write an ASQL expression. It means that the system takes a value of an attribute or result of an expression that is stated in the Value field of a clause and compares it with the attribute value.
To identify what the Value column should contain, each condition has a Type value:

  • Value: The value is only data that is compatible with the attribute type as described above.
  • Attribute: The value will contain a list with available attributes to compare to.
  • Expression: The value will contain an ASQL expression, the value of which will be compared with the attribute in the clause.

The ASQL expression should return a single result.

Setting Options for Processing

Processing

When a CoRu is successfully triggered, it creates a compliance rule event, which is saved in the database. The system processes these events in a periodical manner. This influences the available processing options.
There are two main processing cycles:

  • every minute
  • every day

During these periods, many compliance rule events can occur. The following three options declare how these events should be processed:

  • Process each Compliance Rule event for each object [also multiple]: Processing each event means that the system will take a set of events (the number depends on the Processing Time option) and trigger an assigned CoRu action for each event.

Example: If you changed the state of a user several times, you will get several emails for that CoRu.

  • Only process the last Compliance Rule event per object within the processing period [prevents duplicate messages]: Processing the most recent event means that the system will take a set of events (the number depends on the Processing Time option) and trigger an assigned CoRu action only for the last event that exists for the same object and same CoRu.
  • Example: If you changed the state of a user several times, you will get only one email with the most recent changes.
  • Process the Compliance Rule events for the respective objects conjointly [especially for import/mass changes of objects]: Processing all events means that the system takes a set of events (the number depends on the Processing Time option), groups them by CoRu, and aggregates information about all objects that resulted in the execution of that rule.

CoRu_COND_delete.png

Processing Time
  • Immediately: By default, the system scans for events every minute and during these processing cycles it processes only CoRus that are set to Immediately. Besides, to reduce the workload on the system, the system processes events in chunks (pages). The default page size is 300. It means that for each processing cycle, the system will use only the first 300 (by date) immediate CoRus.
  • You can change the default value by modifying the given setting in SPS.config:  
<update4u.SPS.BizLayer.ComplianceRules processingThreshold="300"/> 
  • Delayed: When a CoRu is marked as Delayed, it means that it will be processed once per day at midnight. Such rules are useful in such scenarios where you need to be notified about all changes during the day, etc. Delayed CoRus are not processed in chunks.

Note: You can change the default values under Administration > Quick Start > Services > Show All Engine Activations.

  • The Immediately time interval is determined by the Process Compliance Rules - Immediately service.
  • The Delayed time interval is determined by the Process Compliance Rules - Delayed service.
  • The Scheduled time interval is determined by the Compliance Rules - Date conditions service process.

Coru_execution.png

Date Conditions

Although it is not marked in the UI, you need to be aware of the third implicit processing option. If your CoRu has a data condition that involves a date attribute such as the one that is shown below, it will be automatically scheduled for additional daily processing cycle. This cycle will check your rule for the date condition to be true. In the example, you see that there is one date clause. The system needs to process date rules daily because the Value for that clause is time-dependent and changes every day.

Important: When such a condition becomes true, it will be true on each subsequent processing cycle. It means that you can get the same expiration email every day. To overcome this, you have to use any special Boolean attribute in your object that will hold the state 'If mail has already been sent.

 Setting Subsequent Activities for Processing

When you create a CoRu, you can specify which activities it should start in case of success.
The CoRu can execute one or more of the following activities:
Executing Workflow from Compliance Rule

  • Sending E-Mail
  • Creating Tasks
  • Starting a Custom Action
  • Changing Data

The Order field specifies the order in which the actions should be executed. Actions with a lower order value are executed first. If actions have the same order value, they will be executed in parallel.
Example: We may need to start an action and send an email simultaneously, or if we have to change the data and send an email with changed data, we should execute the Send E-mail activity (with order 1) after the Change Data activity (order 0).

Although it is possible to use direct actions such as Send E-mail or Create Task as a result of CoRu triggers, it is not the recommended way anymore. The preferred approach is to execute workflow as a result of a CoRu and put business logic into it. You can take advantage of the rich Workflow Activity library and create more sophisticated business processes. In the workflows, it is possible to combine several actions such as Create/Update Task, Execute PowerShell, Create/Update Change, Send E-mail, etc. and orchestrate business processes by using conditions based on data from the system.

In addition, such approach provides the following advantages:

  • Increased system configuration transparency by managing and monitoring all business processes (workflows) in one place.
  • Ability to adjust business process without changing the corresponding CoRu.
  • Possibility to reuse the same business logic in other business processes (workflows).

Creating Tasks

Starting Custom Actions

You can configure custom actions as a result of a CoRu trigger. However, in most scenarios it is required to write custom code and provide custom assembly (.dll) for use of the action in the CoRu. Therefore, execution of custom business logic is not recommended anymore. The preferred approach is to use workflows. In this case you can take advantage of the rich Workflow Activity library and create complex business processes without coding by using the Workflow Studio. For more information, see Executing Workflow from Compliance Rule.

When you select an action to start, the action list is filtered by the following criteria:

  • For CI-based CoRu: Actions that are restricted to a specific CI.
  • For class-based CoRu: Actions that are restricted to CIs in which the target data definition is used.

Changing Data

The system can change an attribute value. The change data rule can contain one or more mapping rules. Each rule has the following parameters:

  • Target Type: Target attribute. Only Attribute is now supported.
  • Target Expression: Target attribute name.
  • Value Type: Type of Value Expression (Value or Expression).
  • Value Expression:
  • Value: Enter a simple value.

Note for Boolean values: If the Target Expression is a Boolean value, enter either true or false here.

Additionally, the following constants are supported:

  • Today+0: Current date. The value for dates also supports the +/- operators.

Example: Today + 5 means that 5 days will be added to the current date. Today - 5 means that 5 days will be subtracted from the current date.

  • @ChangedDate: Date of change. Like Today, the value supports the +/- operators.

Example: "@ChangedDate+ 5" means that 5 days will be added to a change date.

  • @ChangedUser: Unique identifier of the user who changed the data.
  • @ChangedUserDisplayName: Display name of the user who changed the data, the + operator is supported.

Example: User is:+@ChangedUserDisplayName means that the resulting value will be User is:[UserDisplayName].

  • Expression: Value expression contains an ASQL statement for CI level in format <DD name of CI>.<attribute name>.

Example: SPSAccountClassBase.Owner

Sending Emails

The Systems allows easily to setup sending email notifications on triggering Compliance Rule. For that an action "Send E-mail" needs to be added to Compliance Rule actions list, which is uses module Email Engine and Designer for authoring, generating and sending emails.

CoRuSendEmail.png

When configuring a Compliance Rule to send an e-mail:

  1. Use the Send Email action,

  2. Select existing E-mail Descriptor or create a new one. The System filters existing Email Descriptors to display only those which are relevant for current Compliance Rule context. On picking the Email Descriptors the System automatically display available parameters which need to be initialized either by static values or data available in Compliance Rule context (e.g. Object change of it causes the Compliance Rule triggering). Click on each parameter in the grid to open Edit for parameters. When the values for all required parameters are provided, the wizard allows to proceed to setting Recipients

  3. Specify e-mail Recipients.
    The System allows to specify either specific Recipient User(-s) or the whole Recipient Role(-s), then all members of the role obtain an email. The same functionality for the Carbon Copy recipients, which becomes visible on activate "Define CC". For each of this option the form provides three different way to reference User or Role.

    Static, concrete Users, or Roles need to be selected
    Dynamic, uses the Compliance Rule context Object attributes to reference the User (relation to SPSUserClassBase), or Role (relation to SPSScRoleClassBase)
    Expression, the A-SQL WHERE expression, which aimed to return data records of users (for Recipient User) or roles (for Recipient Role). The expression has the following format: DataDefinition: Expression
    DataDefinition: Internal name of the Data Definition which is used for query
    Expression: the A-SQL expression for filtering defined DataDefinition. The expression allows to use parameter %ObjectId% to refer Compliance Rule context object.

    CoRuRecipients.png

Legacy Send Email Actions and Migration

Besides the Send Email action based Email Engine, the Compliance Rule Engine also supports legacy Send Email actions based on Alerting Engine. It is not possible to review and edit this kind of actions in UUX, but only in Classical console.
The legacy Alerting Engine is maintained in a Product, but will be discontinued in the future. All new Send Email Actions for Compliance Rules need to be created only using the new technology.
The Product update automatically migrates all present legacy Send Email Compliance Rule Actions to use a new approach, but as far the full migration is not possible, the System marks the new Send Email actions as disabled. 
CoRuMigration.png 

Once the new migrated Send Email action is validated, use "Switch Mailing Engine" action (available on Compliance Rule preview page) to disable legacy action and activate the new ones. In case something goes wrong using the same action the System allows to fallback to use old Alerting engine actions again.
It is also possible to activate the new mailing engine for all Compliance Rule at once. For that use none context action "Set Default Mailing Engine" in Compliance Rules management area.

After switching Mail Engine, "Matrix42 HostCommon" Service restart is required

 

Running Compliance Rules Manually

Although compliance rules (CoRus) are designed to run automatically, depending on the state of the system. Sometimes it is useful to run a CoRu manually, in order to test the rule and process all existing objects by using this rule.

It is not required to explicitly Activate new or changed compliance rules. This action is intended only to test new custom

When executed, a compliance rule is applied to all corresponding data objects that match the condition defined within. ​​​​​​

There is a limitation for rules that can be executed manually. Only rules that match the following characteristics support manual execution:

  • Does not contain conditions with the before clauses.
  • Does not contain conditions with the changed clauses.
  • Does not contain conditions with the FragmentAdded clauses.
  • Does not contain conditions with the FragmentRemoved clauses.
  • Does not contain conditions with the RelationAdded clauses.
  • Does not contain conditions with the RelationRemoved clauses.

Enabling and Disabling Compliance Rules

  1. Start Matrix42 Workspace Management and click the Administration workspace.
  2. In the navigation area, click Services & Processes > Compliance Rules.
  3. In the selection list, choose a compliance rule.
  • To activate a compliance rule, click Enable in the action pane,.
  • To deactivate a compliance rule, click Disable in the action pane.

Copying and Editing Compliance Rules

There are three types of CoRus:

  • Customizable: Predefined rules of the system that can be changed by users.
  • Customized: System rules that were changed by users.
  • Custom: CoRus that were created by users.

When you create a new CoRu, it becomes Custom. When you edit a Customizable rule, it becomes Customized. Its name is automatically prefixed with UD_ to indicate that it is user defined. Technically, the copy of the Customizable CoRu is created with the new name and the Customizable CoRu is disabled. This saves customization during the updates of the Customizable rules.

To Edit/Copy a Compliance Rule

  1. Start Matrix42 Workspace Management and click the Administration workspace.
  2. In the navigation area, click Services & Processes > Compliance Rules.
  3. In the selection list, choose a compliance rule.
  4. In the action pane, click Edit. An input wizard appears.
  5. Edit the compliance rule.

To Undo Changes

For Customized CoRus, the user can return the Customized rule back to the Customizable state, including all system updates that were installed since the customization.

When reverted, all customization is lost.

  1. Start Matrix42 Workspace Management and click the Administration workspace.
  2. In the navigation area, click Services & Processes > Compliance Rules.
  3. In the selection list, choose the compliance rule that you want to apply.
  4. In the action pane, click Revert to Original, and then click Yes.

Tips & Tricks

Some general recommendations on how to design compliance rules:

  • Try to use class-based CoRus, if possible.
  • Try not to use condition clauses on Common class attributes, such as State.
  • Try not to set conditions that may result in huge amount of events, such as mass import.

If your compliance rule is not working, you can try the following steps for debugging:

  • Check HostCommon.log for any related exceptions.
  • Check that the system services are running.
  • Set the debug level for logging. You will see some useful processing messages.
  • Check whether compliance rules are triggered when you change data. Make a selection in SQL Browser: select * from CREventQueueClassBase
  • Immediately after your changes are made, you need to ensure that there is a record there with the object ID that you changed and triggerMaxState = 1. It means that the DB trigger fired successfully and the CoRu should process the event. If such record does not exist, then the problem is either with your condition or the way you changed your object. If such record exists, then the problem is with processing.
  • You can also validate your rule by running the Execute action on it. In addition, you can retrieve the ASQL condition from the corresponding record in SPSComplianceRuleClassBase and use it as a "Where" expression in QueryAnalyzer. In this case, you need to query SPSCommonClassBase if you have a CI-based CoRu, and the target class if you have a class-based CoRu.

As previously stated, CoRus that have date conditions are checked every day. In this way, they can result in the situation where a CoRu is triggered every day if the condition is met.

Example

A CoRu should Send mail if expiration date is due in 5 days.The CoRu has the following condition: ExpirationDate < Today + 5. Compliance rules that contain date conditions are retrieved daily. In this case, such compliance rules can be triggered daily, after the set conditions are met. To ensure that the email is sent only once, you need to add a Boolean attribute to your CI (here MailSent) and use it in the condition. The new condition should be ExpirationDate < Today + 5 AND MailSent Equals False.

  • Was this article helpful?