Data Enrichment with "external commands"
CLIP can locally execute an external command (i.e. a script, program or Windows batch file) before creating or updating incidents for the purpose of retrieving external values obtained from other data sources like SQL queries, Excel sheets etc.. These external values can be used for incident/event creation and for updates. As an example, an external script might return the assignment group for an incident to be created based on certain parameters.
CLIP allows you to use external values as a source of information in a similar way to the attributes of an event/incident. These external values are written by the external command to standard output as key / value pairs and then read by CLIP. You can use external values to add information to an event/incident that is not available in the original data object.
The configuration of an external command is defined within the <create/> and <update/> tags of a target, e.g.
<createARS>, <updateARS>, <createSN>, <updateSN>, or <updateOMi>
In the above example a perl interpreter is configured to process two arguments. The first argument is the absolute path to the perl script. (a sample perl script can be found in the Clip's „misc" directory) and the second and subsequent arguments can be any String-values or event attribute variable.
Different kinds of commands like a windows batch file, a linux shell-script or a java program are possible and any arguments that are required by the external command can be configured.
The perl script (eval-sample.pl) shows an example on how to read an argument and return the evaluated value to Clip.
All external values returned by the external command on standard output must consist of key and value pairs with the following format rules:
- The output contains plain text.
- Each key / value pair appears on a separate line.
- The key consists of any printable characters
- At least one delimiter (by default: BLANK) separates each key and value.
- The value is a string with any characters (including spaces)
General standard output format:
Example for standard output:
LOCATION Building 4 - Level 1
CONTACT_NAME Wilson, J
As mentioned the external command returns the evaluated values to standard output. These values are retrieved by Clip and can then be referenced in the <createARS> section by the key defined in the script and the EXT-prefix as follows: [EXT_KEY]. For the example output above, the external values are referenced by [EXT_CONTACT_NAME], [EXT_LOCATION] and [EXT_CONTACT_EXT].
The delimiter can optionally be configured in the
<externalCommand>-Tag. If nothing is specified the default value BLANK is used.
<externalCommand delimiter="|" name="/usr/bin/perl">
A successful termination of the external command should be indicated by an exit status code of "0". If a nonzero exit status is returned an error situation is indicated. In this case the incident status is set to failed by Clip.