Merging resources

Different Observers deployed as part of the Agile Service Manager solution may represent the same resource as different resources. To prevent the UI from depicting multiple resource views of the same resource, you can merge them into a single composite resource by assigning them the same value in their mergeTokens set.

Before you begin

You must know your tenant ID.
You also need to know which resources exist as duplicate records across your Observers before you can merge these into composites.

About this task

To merge resources so that they are displayed as single, composite resources in the UI, resources must share values in their mergeTokens set. This triggers the Merge Service to create a composite resource vertex merging those resources together.

Merge rules

Merge rules are applied before each observation job is sent to the topology service, and they can be manged using the Rules REST API in the Merge Service.

For each Agile Service Manager Observer the merge rules control which tokens are considered merge tokens.

Live Swagger documentation for rules is here:

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

Merge rule example

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

Note: The name of the rules is dockerId and it applies only to instances of Observers named docker_observer. It applies to all entity types and all providers and will copy the dockerId property into the merge tokens for all resources which have this property set. The optional excludeTokens property discards any values that match the regular expression. A corresponding (mutually exclusive) includeTokens property exists, which applies a merge token only if the value matches the regular expression.

rules:
    - name: dockerId
      ruleStatus: enabled
      mergeTokens: [ dockerId ]
      entityTypes: null
      observers: [ docker_observer ]
      providers: null
      "excludeTokens": [ "^asm-default.*"]

Procedure

Using the live Swagger interface or cURL commands, write a rule for each record to be merged into a composite record, and POST it to the Rules API.

Use the following information as guidance when defining each merge rule:

Name: The name of the merge rule, which must be unique within the context of the tenant.
ruleStatus: The rule status can be either enabled or disabled, and the observers will only apply merge rules which are in an enabled state.
mergeTokens: The merge tokens set in a merge rule contains the list of resource parameter names which will become merge tokens for those resources to which the rule is applied.; Merge tokens can be constructed using variable substitutions, which allows you to combine more than one property value in a mergeToken, and also combine them with literal strings, as shown in this example.; Important: These are the shared elements that the duplicate records to be merged have in common.
entityTypes: The entity types set in a merge rule contains the list of resources entity types for which this rule is valid.; If omitted, the merge rule will apply to all entity types.
observers: The observers set contains the list of names of the observers to which this rule applies.; If omitted, or set to include the value '*', the merge rule will apply to all observers.
providers: The providers set contains the list of names of the providers so which this rule applies.; If omitted, or set to include the value '*', the merge rule will apply to all providers.; The mutually exclusive excludeTokens and includeTokens properties can filter providers.
excludeTokens: These properties discard any values that match the regular expression.
includeTokens: These properties apply a merge token only if the value matches the regular expression.

Results

After you have created and posted your merge rules, these are applied before each observation job is sent to the topology service. Composite, merged resources are displayed in the Agile Service Manager UI as a single resource, which includes the properties of all merged resources.

Example

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

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

{
  "_id": "ABC",
  "name": "host1",
  “propertyAbc”: “This property only exists on ABC”,
  "entityTypes": [ "host" ],
  "mergeTokens": [ "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

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

{
  "_id": "DEF",
  "name": "host1",
  “propertyDef”: “This property only exists on DEF”,
  "entityTypes": [ "host" ],
  "mergeTokens": [ "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

http://<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" ],
  "mergeTokens": [ "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",
    "mergeTokens": [ "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 mergeToken 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 mergeToken, which in this case is the / character.
To be backwards compatible, mergeTokens 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: http://<your host>/1.0/merge/swagger/#/Composites