Defining tags rules

A tags rule copies the value of another field to the tags field so that it becomes searchable in the UI.

About this task

A resource's tags can be searched via the UI, and matching resources can be displayed. Resources with common tags can optionally be grouped using a tag-based template definition.

A tags rule populates the tags of resources matched by the rule. See the following sample tags rules for more information.

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 Table 1.

ITNM Observer tip:

You can create custom tags on IBM Tivoli Network Manager, which the ITNM Observer can integrate into Agile Service Manager tags. For information on creating custom tags in Network Manager, see the Adding name-value pairs to entities using the File finder topic in the IBM Tivoli Network Manager IP Edition documentation.

Having added a custom tag in Network Manager, you can extract the value into an Agile Service Manager tag. The following example uses a regular expression to extract the value of the `Country` custom tag:

customTags=~/[\\{]Country=(.+?)[,\\}]/

Procedure

Details

On the Details section of the New tags rule (or Edit tags 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 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 tags for those resources to which the rule is applied. Tag 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.

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

Tags rules:

The tags rule allows the value of another field to be copied to the tags field so that it becomes searchable in the UI. It populates the tags of resources matched by the rule.

Example 1: Simple example of a tagsRule:

- name: tagRuleCustomProp
  ruleType: tagsRule
  ruleStatus: enabled
  tokens: [ name ]
  entityTypes: null
  observers: null
  providers: null

Example 2: The following example creates tags rules for the Docker Observer and will add com.docker.compose.service and com.docker.compose.project properties to the tags list, for entities of the type container:

curl -k -s -X POST --user $PROXY_USER:$PROXY_PASSWORD --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255' -w "Response code: %{http_code}\n" -d '{
  "tokens": [
    "com.docker.compose.service",
    "com.docker.compose.project"
  ],
  "name": "tag-docker-container-service-project",
  "ruleStatus": "enabled",
  "ruleType": "tagsRule",
  "observers": [
    "docker_observer"
  ],
  "entityTypes": [
    "container"
  ]
}
' "https://${PROXY_HOST}/1.0/merge/rules"

To verify:

{
   "_createdAt": "2019-09-10T02:24:03.652Z",
   "_executionTime": 10,
   "_id": "YEaGjuCJT5-wCH-SAfCssA",
   "_modifiedAt": "2019-09-10T15:29:33.829Z",
   "_observedAt": "2019-09-10T15:29:33.829Z",
   "_startedAt": "2019-09-10T15:29:33.829Z",
   "architecture": "x86_64",
   "changeTime": 1568129373829,
   "com.docker.compose.config-hash": "6afc3ec12fd17d2b815df61e4ab276af6a27324a1487567f1bbba29a4a4bca1e",
   "com.docker.compose.container-number": "1",
   "com.docker.compose.oneoff": "False",
   "com.docker.compose.project": "asm",
   "com.docker.compose.service": "search",
   "com.docker.compose.version": "1.11.2",
   "createTime": 1568082243652,
   "dockerId": "dc39b5ea19cb79755e48a525bfbd2d479777464b1e80c708cb851da1b22fa952",
   "entityTypes": [
       "container"
   ],
   "matchTokens": [
       "asm_search_1",
       "dc39b5ea19cb79755e48a525bfbd2d479777464b1e80c708cb851da1b22fa952"
   ],
   "mergeTokens": [
       "dc39b5ea19cb79755e48a525bfbd2d479777464b1e80c708cb851da1b22fa952"
   ],
   "name": "asm_search_1",
   "observedTime": 1568129373829,
   "tags": [
       "asm_search_1",
       "asm",
       "search"
   ],
   "uniqueId": "dc39b5ea19cb79755e48a525bfbd2d479777464b1e80c708cb851da1b22fa952",
   "vcs-type": "git",
   "vendor": "IBM",
   "version": "1.0.10-SNAPSHOT"
}

Example 3:

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}.