Defining file enrichment rules

A file enrichment rule provides additional resource information (via file) that is matched to specific resources via a specified resource identifier (the token).

About this task

The supplemental resource information provided via a file enrichment rule can be geolocation data provided as a GeoPoint file, or any other data provided as a more complex JSON file.

Using a GeoPoint file

The GeoPoint format is specific to geolocation data. A file enrichment rule matches a specified resource identifier (the token) to the longitude and latitude (the geographical location) of the resource. Resources that have been enriched with a geographical location can be displayed on the topology resource map.

Before you begin

Remember: To enrich your resource records with geolocation data, you can use a file enrichment rule as described here, or you can load resource data with geolocation properties included.

Create a file that contains the additional geolocation data for your resources.

The file enrichment rule uses the following parameters for GeoPoint:
{
"tokens" : ["clli"],
"fileName" : "example-geopoint.txt",
"format" : "geoPoint,
...
}
File format
The file you use must be in the TSV (tab-separated values) format. The values on each line are 'token', 'latitude' and 'longitude':
token	longitude	latitude
Tip: CLLI (Common Language Location Identifiers) are supported and can be used as tokens.
Example GeoPoint file
A file enrichment rule allows the value of a token to be used to map that resource to its location on a map.
Example TSV file
LONDON-CTR-01	-0.120226	51.509287
LONDON-CTR-02	-0.108514	51.485100
MCHSTR-CTR-01	-2.248665	53.482641
LVERPL-CTR-01	-2.996455	53.403925
Example rule
name = serverBuildingLocations
enabled = true
token = buildingCode
file = server-buildings.tsv
Example resource
{
  "uniqueId": "server-001",
  "name": "server-001",
  "entityTypes": [
    "server"
  ],
  "buildingCode": "LONDON-CTR-01"
}

Procedure

Details

On the Details section of the New file enrichment rule (or Edit file enrichment rule) page, you define the name, status, tokens and file to be used for the rule.

  1. 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.
  2. Toggle the rule status to be either Enabled or Disabled
    Observers will only apply rules which are in an enabled state.
  3. Define a token for the rule, then click Add+.

    The token is used to uniquely identify the resource to which the rule is applied.

  4. Specify the format of the enrichment file, in this case GeoPoint.
    Remember: You must create this file before you can create a new file enrichment rule.
  5. Specify the enrichment file to be uploaded.
    Under File mode, select one of the following options:
    Upload local file
    Either drag-and-drop or click and browse to choose a file.
    Use server file
    Specify the name of the file to be loaded.
    The file must have been uploaded previously.
    Do not specify a path.

Conditions

  1. Select observers to which this rule applies from the Observer name drop-down.
    Leave empty to apply the rule to all observers.
  2. Select providers to which this rule applies from the Provider name drop-down.
    Leave empty to apply the rule to all providers.
  3. Select resource types to which this rule applies from the Resource type drop-down.
    Leave empty to apply the rule to all resource types.
  4. 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.
  5. Validate your filters using the Validate token filters button.
  6. Click Save.

Results

Additional resource information added via the file enrichment functionality is displayed on the Resource details screen.

Using a JSON file

The JSON file format lets you enrich resource data with any custom properties required. A file enrichment rule using a JSON file matches a specified resource identifier (the token) as well as a file enrichment key (a second token) in order to provide additional data for specified resources.

Before you begin

Create a file that contains the additional information for your resources.

The file enrichment rule uses the following parameters for JSON:
{
"tokens" : ["uniqueId"],
"fileName" : "example-json.txt",
"format" : "json",
"fileEnrichmentKey":"cityName",
...
}
File format
The JSON file format requires separate tokens for the resource and for the file data.
Example JSON file
name = fileEnrichmentKey
token = uniqueId
{"name":"Ireland","capital":"Dublin","tags":["green","wet"]}
{"name":"UK","capital":"London","geolocation":{"geometry":{"type":"Point","coordinates":[0.00000,0.00000]}}}
{"name":"France","capital":"Paris","population":70000000}
{"name":"Germany","capital":"Berlin","entityTypes":["rave scene"]}
{"key":"Switzerland","capital":"Bern"}
Resources
V:{"uniqueId":"Ireland","entityTypes":["country"],"tags":["republic"]}
V:{"uniqueId":"UK","entityTypes":["country"]}
V:{"uniqueId":"France","entityTypes":["country"]}
V:{"uniqueId":"Germany","entityTypes":["country"]}
V:{"uniqueId":"Switzerland","entityTypes":["country"]}
Enriched resources
V:{"uniqueId":"Ireland","entityTypes":["country"],"tags":["republic","green","wet"],"capital":"Dublin"}
V:{"uniqueId":"UK","entityTypes":["country"],"capital":"London","geolocation":{"geometry":{"type":"Point","coordinates":[0.00000,0.00000]}}}
V:{"uniqueId":"France","entityTypes":["country"],"population":70000000,"capital":"Paris"}
V:{"uniqueId":"Germany","entityTypes":["country","rave scene"],"capital":"Berlin"}
V:{"uniqueId":"Switzerland","entityTypes":["country"],"capital":"Bern"}

Procedure

Details

On the Details section of the New file enrichment rule (or Edit file enrichment rule) page, you define the name, status, tokens and file to be used for the rule.

  1. 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.
  2. Toggle the rule status to be either Enabled or Disabled
    Observers will only apply rules which are in an enabled state.
  3. Define a token for the rule, then click Add+.
    The token is used to uniquely identify the resource to which the rule is applied.
    Remember: The fileEnrichmentRule you are creating uses this token to match the file to the resource.
  4. Specify the format of the enrichment file, in this case JSON.
    Remember: You must create this file before you can create a new file enrichment rule.
  5. Specify the enrichment file to be uploaded.
    1. Under File mode, select one of the following options:
      Upload local file
      Either drag-and-drop or click and browse to choose a file.
      Use server file
      Specify the name of the file to be loaded.
      The file must have been uploaded previously.
      Do not specify a path.
    2. Specify the enrichment file key.
      This identifies the property in each line of the enrichment file to be matched against the rule token.
      Remember: The enrichmentFileKey is the token used in the JSON file to perform the matching against the token chosen in step 3.

Conditions

  1. Select observers to which this rule applies from the Observer name drop-down.
    Leave empty to apply the rule to all observers.
  2. Select providers to which this rule applies from the Provider name drop-down.
    Leave empty to apply the rule to all providers.
  3. Select resource types to which this rule applies from the Resource type drop-down.
    Leave empty to apply the rule to all resource types.
  4. 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.
  5. Validate your filters using the Validate token filters button.
  6. Click Save.

Results

Additional resource information added via the file enrichment functionality is displayed on the Resource details screen.