Skip to main content
Version: 1.15.0

Monitoring Source

The monitoring source is a fundamental element of the event management process. The main task of the Monitoring Source is to translate messages from an external monitoring system to the target message table via the Data Import mechanism. The system supports two types of data sources: JSON data received from an API endpoint and email messages that are converted into JSON for subsequent processing.

The monitoring source has the information about the following entities:

  • the specified monitoring system.
  • the data structure provided by the system.

Create a monitoring source​

tip

Role required: admin.

To create a monitoring source, complete the following steps:

  1. Navigate to Monitoring and Event Management → Configuration → New Monitoring Source.
  2. Follow the instructions given on the page.
  3. When all the steps are completed, click Finish.

Monitoring source name and type​

Specify a unique monitoring source Name. It will be used in the title of the target table as follows: Name + Target Messages.

Select the Type of the monitoring source. Available options:

  • JSON – the monitoring source receives data from an API endpoint connected to an external monitoring service.
  • Emails – the monitoring source receives data from email messages sent by an external monitoring system. The received messages are converted into JSON for subsequent processing.

Depending on the selected type, the creation of a monitoring source includes the following steps:

JSON​

caution

Before proceeding, switch to the ITSM application in the Admin preferences menu.

  1. Add attributes and keys
  2. Create columns
  3. Map attributes

Emails​

caution

Before proceeding, ensure that an email account is configured on your instance and switch to the Simple application in the Admin preferences menu.

  1. Generate JSON
  2. Add attributes and keys
  3. Create columns
  4. Map attributes

Generate JSON​

This step appears if Emails was selected as the monitoring source type.

Fill in the fields:

  • Email template – add a template of the email messages sent by the external monitoring system.

  • Parsing script – add a script to convert the email body into JSON data.

Add attributes and keys​

info

When creating an Emails type monitoring source, the JSON and Attributes and keys fields are filled in automatically and cannot be modified. You can only select attributes to be used as composite keys.

Specify the data structure that you want to get from the monitoring source. You can use one of the available fields to enter the data:

  • JSON – insert the data in JSON format. Use Latin letters, , "" _ : symbols, and [0...9] digits.

    You cannot put digits at the beginning of attribute names.

The system recognizes a multilevel JSON object. Nested attributes are displayed in the Attributes and keys area.

  • Attributes and keys – create attributes by entering them in the input field. Use Latin letters, the "" symbol, and [0...9] numbers. Attribute names can only begin with letters or the "" symbol.
note

You cannot create the same attributes.

When data is inserted in one of the fields, it is automatically transferred to the other field in the required format.

You can also edit and delete attributes. There are two ways to do so:

  • Click to edit or to delete an attribute in the Attributes and keys area.
  • Edit or delete data in the JSON area.
note

The system does not support creating nested attributes and editing the nesting order in the Attributes and keys area. You can only do it in the JSON area.

Select the attributes from the list on the right to use as composite keys.

note

You need to select at least one attribute from the list to use it as the composite key to go to the next step.

Composite key​

A composite key is a set of values of several attributes. These attributes are considered to be a unique identifier that precisely defines an object that the monitoring system sends a message about. It can be an attribute with an ID or a combination of many attributes.

The role of the composite key:

  1. After receiving a message from the monitoring system, the system forms a composite key from the values of those attributes that are specified as the Composite Key in the Monitoring Source.
  2. The system checks the generated composite key of the message for uniqueness against the records in the Composite Keys table that have the corresponding Monitoring Source value.
  3. The system generates a new record in the Composite Keys table if the composite key of the message is unique.

Create columns​

Create columns for the target table. To do so, complete the following steps:

  1. In the New column area, fill in the fields. See the Create Columns article to learn more about this process.
  2. Click Add.
  3. Repeat and create as many columns as you need.
  4. When all columns are created, click Next to go to the last step.

To change the values of the created column or delete it, complete the steps below:

  1. Click the title in the Added columns area. The form appears on the left. Make changes and click Save, or click Delete to delete the column.
  2. To close the form without any changes, click in the top right corner of the area.

Map attributes​

Set the field mapping to define the correlation between the fields of the monitoring source and the fields of the target table.

To do so, complete the following steps:

  1. Click the element in one of the areas. The chosen element is highlighted.
  2. In the opposite area, click the corresponding element.

As a result, the formed pair is highlighted in green, a connecting line runs between the elements. The pair is sorted to the bottom of the element list.

To disconnect the elements, click .

Add, edit, and delete a script​

You can add a script to the connected field pair that takes the record object of the monitoring source as an argument and returns the value to put into the target table field.

To add a script, complete the following steps:

  1. Click to open the modal window.
  2. Enter the script using the SimpleOne Server-Side API.
  3. Click Add.

tip

When there is a script for a pair of fields, the icon becomes green .

To open the edit window with the script specified, click . Make changes and click Save, or click Delete to delete the script.

Results​

As a result:

  • The Monitoring Source record is created. The field values are populated automatically with the values specified during the setup.
  • (when configuring a JSON type monitoring source) An endpoint in the API Actions (sys_api_action) table is created and the endpoint link is generated. You can copy it by clicking the icon.
  • The Import Source record is created. It contains the import text in JSON format inserted in step 2.
  • The Target Table is created. The table contains columns that were created in step 3.
  • The field mapping between the fields of the monitoring source and the target table is set.
  • According to the data import mechanism, an intermediate table and mapping rules are created.

For further setup, you need to create monitoring rules, event rules and actions. When creating an Emails type monitoring source you also need to configure an inbound email action to filter the messages that must be processed by the monitoring source.

caution

When configuring the inbound email action, only modify the validationEmail function. Modifying other parts of the code may cause errors in the monitoring system operations.

Receive messages to the source endpoint​

To receive messages from an external monitoring system on a configured source endpoint, you need to:

  1. Set up a system user with the monitoring_message_creator or import_admin role.
  2. Log in as the user and use the s_user.accessToken() methods in the browser console or getAccessToken() in the server script to get the user's token. The lifetime of the token is limited (you can set the time in the user.token.ttl system property).
  3. When sending messages to the endpoint, use authorization by token.