Defining rules

Edit online

Rules help streamline topologies and conserve system resources, for example by merging different observer records of the same resource into a single composite resource, or by excluding specific changes from being recorded against a resource history.

Before you begin

You must know your tenant ID.
You also need to know specific details about resources for which you intend to develop rules. For example, to create merge rules you must know which resources exist as duplicate records before you can merge these into composites.

About this task

Tokens

Rules copy the values of properties to a token. Tokens are sets of strings that behave in ways specific to each rule type. You can combine several properties into a single token by using ${propertyName}.

Token filters

An 'Include' token filter applies only to resources or groups having the listed tokens.

You can use an 'Include' token filter simply to include (or exclude) specific properties, or extend its use with regular expressions to manipulate the input property.

Table 1. Example use of tokens and token filters
Token	Include token filter	Input properties	Single output token value
host		host=example.ibm.com	example.ibm.com
${host}		host=example.ibm.com	example.ibm.com
${host}location-${location}		host=example.ibm.com,location=1	example.ibm.com location-1
host	host=~/^(.?)\..$/	host=example.ibm.com	example
${uniqueId}Location-X	uniqueId=~/^.{.)$/	uniqueId=anything	Location-X

Rule types

You use different types of rules for different purposes. The rule type (ruleType) can be one of the following:

Merge rules (mergeRule): Define a merge rule to populate the mergeTokens of resources matched by the rule to prevent duplicate records of the same resource from being displayed in the topology.; A merge rule copies particular properties of a resource into the resource's mergeTokens property.
Match token rules (matchTokensRule): Define a match tokens rule to copy the value of another field to the matchTokens field so that it can be used to match events to resources.; A match token rule populates the matchTokens of resources matched by the rule.
Tags rules (tagsRule): Define a tags rule to copy the value of another field to the tags field so that it becomes searchable in the UI.; A tags rule populates the tags of resources matched by the rule.; Tip: Any field that isn't indexed and can therefore not normally be searched for becomes searchable if copied to the tags property. For a list of indexed properties, see the 'Generic properties' table.
History rules (historyRule): Define a history rule to identify properties that change every observation, but that don't indicate an important change, for example a host's sysUpTime property.; A history rule excludes properties from being retained in history, thereby saving resources by not maintaining detailed historical records of changes to these properties.
File enrichment rules: Define a file enrichment rule in order to enrich resources as they are loaded into the topology service database with their geographical location.
Events filter rules (eventsFilterRule): Define an events filter rule to prevent status derived from observer jobs from generating events in the system.
Business criticality rules: Define a business criticality rule to copy a particular property of a resource into the resource's businessCriticality property, which is then used to create a business criticality rule.

Custom observer rules:

Use the observers parameter to list the observers to which a rule applies.

Jenkins Observer: A mergeRule and an eventsFilterRule are included out-of-the-box for the Jenkins Observer.
A merge rule to merge Artifactory's published Docker modules information with the information provided by the Docker Observer is provided here: Defining Jenkins data merge rules.

Procedure

Access Topology configuration | Rules

As a user with the inasm_admin role, log into your DASH web application.
Select Administration > Topology configuration from the menu.
The Topology configuration page is displayed with a number of configuration options.
Click Configure on the Rules card.
The Rules page consists of a table listing all existing rules in sortable columns, including the rule type. You can create a new rule, or edit or delete an existing rule.
- To reload the rules, click Refresh (top right). This can be useful if other users are customizing the rule.
- To delete rules, select one or more rules in the table, then click Delete rule configuration(s).
- To edit a rule, select it in the table, then click Edit rule configuration. You define an existing rule as you would a new one.
- To create a new rule, click New (top right). The Create a new rule window is displayed, from where you select the type of rule you want to create before clicking Next to display the New rule window, which consists of the expandable Details and Conditions sections.

What to do next

To define specific types of rules, see the individual topics describing the creation of rules (including examples).