Defining file enrichment rules

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, for example by using the File or REST observers.

Create a file that contains the location information 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 latitude  longitude

Tip: CLLI (Common Language Location Identifiers) are supported and can be used as tokens.

Example

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   51.509287   -0.120226
LONDON-CTR-02   51.485100   -0.108514
MCHSTR-CTR-01   53.482641   -2.248665
LVERPL-CTR-01   53.403925   -2.996455

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

1. On the Rules administration page, select the File enrichment rules tab.

2. Complete the Details section by defining the name, status, token and file to be used for the rule.

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

   b. Toggle the rule status to be either Enabled or Disabled.

   When observer jobs are run, they apply only the rules that are in an enabled state.

   c. Define a token for the rule, then click Add+.

   The token is used to uniquely identify the resource to which the rule is applied, against which a location is mapped using the data contained in the rule file. Only a single token is used to map a location, but you can construct it using variable substitutions, which lets you combine more than one property value if required.

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

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

3. Complete the Conditions section by selecting the observers, provider, and resource type for the rule, and by setting the token include / exclude switch.

   a. Select observers to which this rule applies from the Observer name drop-down. Leave empty to apply the rule to all observers.

   b. Select providers to which this rule applies from the Provider name drop-down. Leave empty to apply the rule to all providers.

   c. Select resource types to which this rule applies from the Resource type drop-down. Leave empty to apply the rule to all resource types.

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

4. Validate your filters using the Validate token filters button.

5. Click Save.

Results

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

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

- 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

1. On the Rules administration page, select the File enrichment rules tab.

2. Complete the Details section by defining the name, status, token and file to be used for the rule.

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

   b. Toggle the rule status to be either Enabled or Disabled.

   When observer jobs are run, they apply only the rules that are in an enabled state.

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

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

   e. Specify the enrichment file to be uploaded, and the enrichment file key.

   • Under File mode, either upload a local file (drag-and-drop or click and browse), or specify the name of the file to be loaded from a server (uploaded previously; do not specify a path).

   • 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 2c.

3. Complete the Conditions section by selecting the observers, provider, and resource type for the rule, and by setting the token include / exclude switch.

   a. Select observers to which this rule applies from the Observer name drop-down. Leave empty to apply the rule to all observers.

   b. Select providers to which this rule applies from the Provider name drop-down. Leave empty to apply the rule to all providers.

   c. Select resource types to which this rule applies from the Resource type drop-down. Leave empty to apply the rule to all resource types.

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

4. Validate your filters using the Validate token filters button.

5. Click Save.

Results

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