Defining merge rules

Edit online

A merge rule copies particular properties of a resource into the resource's mergeTokens property. Resources which contain the same merge token will be merged so that they are treated as a single 'composite' resource. In this way, the topologies from different data sources can be connected.

About this task

Different observers deployed as part of the Agile Service Manager solution may record and then display the same resource as two (or more) resources. To prevent this, you create a merge rule that ensures that the separate records of the same resource share values in their tokens set, which then triggers the merge service to create a single composite resource vertex. Composite, merged resources are displayed in the Topology Viewer as a single resource, which includes the properties of all merged resources. Merge rules are applied to a resource in an observer job before it is sent to the topology service.

Rules can be managed using the Rules REST API in the Merge Service. For each Agile Service Manager observer, merge rules control which tokens are considered merge tokens. Live Swagger documentation for merge rules is here:

https://<your host>/1.0/merge/swagger/#/Rules

Procedure

Details

On the Details section of the New merge rule (or Edit merge rule) page, you define the name, status and tokens for the rule.

Enter a name, which must be unique within the context of the tenant.
You cannot change the name of an existing rule. If you want a rule to have a different name, create a new rule, then delete the old one.
Toggle the rule status to be either Enabled or Disabled
Observers will only apply rules which are in an enabled state.
Define merge tokens for the rule, then click Add+.

The tokens defined as part of a rule contain the list of shared resource parameter names that will become merge tokens for those resources to which the rule is applied. Merge tokens can be constructed using variable substitutions, which allow you to combine more than one property value in a token and also combine them with literal strings, as shown in this example.
Important: The tokens are the shared elements that the duplicate records to be merged have in common.

Conditions

Select observers to which this rule applies from the Observer name drop-down.
Leave empty to apply the rule to all observers.
Select providers to which this rule applies from the Provider name drop-down.
Leave empty to apply the rule to all providers.
Select resource types to which this rule applies from the Resource type drop-down.
Leave empty to apply the rule to all resource types.
Set the Token filter mode to either Exclude or Include, then define a filter in the format of a regular expression. You can set more than one filter.

Exclude

Tokens which match any one of the expressions will not be applied to resources.

Include

Only tokens which match one of the expressions will be applied to the applicable resources.
Validate you filters using the Validate token filters button.
Click Save.

Example

Default merge rule for the Docker Observer:

The following example is the default merge rule defined for the Docker Observer:

rules:
    - name: dockerId
      ruleType: mergeRule
      ruleStatus: enabled
      tokens: [ dockerId ]
      entityTypes: null
      observers: [ docker-observer ]
      providers: null
    - name: almExternalId
      ruleType: mergeRule
      ruleStatus: enabled
      tokens: [ externalId ]
      entityTypes: null
      observers: [ alm-observer ]
      providers: null

Notice that the rules name in this example is dockerId, and that it applies only to instances of observers named docker-observer. The ruleType property here specifies the mergeRule rule type. This merge rule applies to all entity types and all providers and will copy the dockerId property into the merge tokens for all resources that have this property set.

Sample rules for merging resources:

A composite resource has its own unique identifier, and the merged resources continue to exist separately. The following example shows the individual and composite resources when retrieved from the topology Resources API.

Resource one

https://<your_NASM_host>/1.0/topology/resources/ABC

{
  "_id": "ABC",
  "name": "host1",
  “propertyAbc”: “This property only exists on ABC”,
  "entityTypes": [ "host" ],
  "tokens": [ "host1MergeToken" ],
  "_compositeId": "XYZ"
}

The resource has an id of ABC, and the value of compositeId denotes the single, merged resource, which is XYZ.

Resource two

https://<your host>/1.0/topology/resources/DEF

{
  "_id": "DEF",
  "name": "host1",
  “propertyDef”: “This property only exists on DEF”,
  "entityTypes": [ "host" ],
  "tokens": [ "host1MergeToken" ],
  "_compositeId": "XYZ"
}

The resource has an id of DEF, and the value of compositeId denotes the single, merged resource, which is XYZ.

Composite resource

https://<your_NASM_host>/1.0/topology/resources/XYZ

{
  "_id": "XYZ",
  "name": "host1",
  “propertyAbc”: “This property only exists on ABC”,
  “propertyDef”: “This property only exists on DEF”,
  "entityTypes": [ "host" ],
  "tokens": [ "host1MergeToken" ],
  "_compositeOfIds": [ "ABC", "DEF " ]
}

The resource has an id of XYZ, and the value of compositeOfIds lists the ids of the merged resources, in this case ABC and DEF. The XYZ composite resource includes the properties from both of the merged resources.

Resource with variable substitutions and exclude list

{
  "name": "sysNameMatching",
  "tokens": [ "sysName", "${name}/${customField}"],
  "ruleStatus": "enabled",
  "entityTypes": [ "host", "server" ],
  "observers": [ "ITNM", "TADDM" ],
  "providers": [ "*" ],
  "customField": "string",
  "excludeTokens": [ "^asm-default.*"]
}

The ^asm-default.* value set for excludeTokens ensures that any values that match the regular expressions are excluded.

The merge token with the value of ${name}/${customField} combine the ${name} and ${customField} properties using the ${} syntax, and demonstrate how variable substitutions work.

Literal values are entered as they are in the merge token, which in this case is the / character.
To be backwards compatible, tokens consisting of a single value, as in the sysName example, are treated as variable substitutions, that is, as if they are ${sysName}.

Tip: You can also view composite resources in the live Swagger Composite API in the Merge Service, which returns the properties of the composite itself, and provides methods to get all composite vertices: https://<your host>/1.0/merge/swagger/#/Composites

What to do next

You can find more information on merge rules at the following blog post:
https://medium.com/@ibmjdiaz/using-merge-rules-in-agile-service-manager-b66b36707b1c