Configuring the ServiceNow Connector

Last updated on 31 January, 2023

The following describes how to install and configure the LogicMonitor Data Exchange (LMDX) connector for data synchronization between ServiceNow (SN) and LogicMonitor (Dexda). Dexda has a configurable connector to integrate with ServiceNow. The integration has default mappings to transfer information from Dexda to incidents in ServiceNow, but it is possible to configure the connector for any table within ServiceNow.

You can get notified about issue in ServiceNow, and through links access the information in Dexda to investigate issues. You can look at insight details, see associated alerts and type of issue, and understand why they were correlated. For information on how to investigate issues in Dexda, see Exploring Data.

Requirements

Ensure you have the following before getting started with the configuration:

  • A ServiceNow account with the “admin” role. This is required to configure the LMDX application, as the app saves changes in update sets.
  • A ServiceNow account to allow LogicMonitor to access the API. To get access to the API, the account must have the x_lomo_dx.apiUser role. Enable the “Web Service Access Only” setting for the account.
  • A LogicMonitor API Endpoint and Token provided by your LMDX administrator. See API Tokens.

Installation and Configuration

The data synchronization is controlled using LMDX configuration records in ServiceNow. These contain the table records to which you want to read or write data from or to. The Config (x_lomo_dx_config) record is the main table determining which tables are set up to be synchronized when using the LMDX application.

The default configuration for the Incident table created in LMDX contains the following related artifacts:

  • Business Rules defining when to run.
  • Inbound Transform Map with Field Maps and Transform Scripts.
  • Outbound Transform Map and Field Maps.

Use these configurations as-is, or modify them as desired.

The integration comes with these fully working configuration records:

  • Incident (LMDX0001001). Manages synchronization with the Incident (incident) table in ServiceNow.

In addition, create your own configuration records to synchronize other tables if needed. You can use the preexisting Incident configuration and artifacts as a reference when setting up synchronization for other tables.

To get started, install the LMDX connector from the ServiceNow App Store and complete the built-in configurations as described in the following. The built-in configuration options are inactive by default, and must be activated.

Setting Configuration Properties

Before you can use LMDX you need to define a set of authentication and automation properties. Consult with your LMDX administrator to get these values for your implementation.

Navigate to Configuration properties and add values as follows:

  • Value for x_lomo_dx.outbound.endpoint in the field LMDX endpoint to use if domain separation support (x_lomo_dx.domainEnabled) is not enabled.
  • Value for x_lomo_dx.auth.apiKey in the field LMDX API key to use if domain separation support (x_lomo_dx.domainEnabled) is not enabled.

The x_lomo_dx.config.artefactAutoCreation property associated with the field Will attempt to auto-create related artifacts if set to true… is used when automatically setting up custom synchronization tables. See Setting up a new Table.

Completing the Incident Configuration

Follow these steps to complete the setup and activation of the default Incident Configuration in ServiceNow.

  1. In the list under Configuration, select the record for which you want to update the configuration, for example “Incident (LMDX0001001)”.
  2. On the Outbound tab, enter values as described in the following.
  • Condition: You can add a condition to the Outbound payload creation so that only records that match the condition are considered for processing.
  • Trigger fields: This triggers a payload to be sent to LMDX only when a specific field is changed, as you may not want to send every change on the record. Only changes in the fields are considered, not specific values. Trigger fields are used in conjunction with Condition, like adding a “changes” condition in the condition builder. Typical trigger fields of interest are “State” and “Configuration item”.
  • Record type: The value (string) depends on the selected table, for example sncIncident. Consult your LMDX administrator what to put in this field.
  • Type: Defines how a payload should be sent to LMDX. Options:
    • Incremental: The payload is sent as soon as it is generated. Recommended for task-like records such as incidents.
    • Batch: The payload is periodically sent in a batch. Recommended for data records such as CMDB. See Sending Batch Payloads.
  • Only send LMDX created records: Select this if you only want records created by LMDX to be synchronized. This means you do not need to set up a condition that relies on records being created or updated by a specific user. This setting is intended primarily for task-like records such as incidents.
  1. Check Active when you want the configuration to be activated. This activates the configuration record, along with the associated Business Rule, Transform map and Outbound transform Map.
  2. Select Update to save the configuration record.

Sending Batch Payloads

The Type setting does not affect when a payload is generated. All payloads are generated as soon as a change is detected in a “valid” record, as specified in the conditions and trigger fields. The “Batch” payload type is intended to be used for background data records like “cmdb_ci”.

To send batch payloads, you must activate the LMDX – Process batch outbound payloads scheduled job and set a repeat interval. The minimum repeat internal is recommended to be no less than every 5 minutes. For domain separated instances, see Batch Payloads in Domain Separated Instances for more details on setting up batch payload sending.

Batch payloads are merged so that only a single payload is sent with the latest values, even if there are multiple changes to the record within the repeat interval period.

Setting up a new Table

You can create your own synchronization table if the built-in tables do not support the requirements in your specific use case. To do this through LMDX, you need to first create a configuration record and activate it. Then you create the necessary artifacts and associate them with the new table.

You can let LMDX automatically create the artifacts by setting a system property and running a script once on your instance. You can also create the artifacts manually. Both methods are described in the following.

Creating a new Configuration Record

Navigate to Configuration and select New. Add configuration values as described in Completing the Incident Configuration.

Creating Artifacts Automatically

Follow these steps to create a synchronization table with artifacts.

Step 1. Run the Global Table Script

Run the following script on your instance, either as a “Fix” script or a “Background” script.

Note: You cannot add the script into the application as it must be run in global scope, and not as part of the scoped application.

function update(tableName){
  var updateGR = new GlideRecord('sys_db_object');
  updateGR.setWorkflow(false);
  updateGR.get('name', tableName);
  updateGR.setValue('create_access', true);
  updateGR.setValue('update_access', true);
  updateGR.setValue('delete_access', true);
  updateGR.update();
  GlideTableManager.invalidateTable(tableName);
  GlideCacheManager.flushTable(tableName);
}
update('sys_db_object');
update('sys_dictionary');
update('sys_transform_map');
update('sys_transform_entry');
update('sys_transform_script');
update('sys_script');

The script selects the “Can create”, “Can update”, and “Can delete” checkboxes for the following tables:

  • Tables (sys_db_object)
  • Dictionary (sys_dictionary)
  • Table Transform Map (sys_transform_map)
  • Field Maps (sys_transform_entry)
  • Transform Scripts (sys_transform_entry)
  • Business Rules (sys_script)

This lets the application create, update, and delete records on those tables from within the application scope.

Note: The calls to GlideTableManager and GlideCacheManager functions reset the table cache so that the newly updated values are used across all node instances. If these calls are not made, the automatic creation may fail due to security rules not being refreshed across all node instances. See the ServiceNow documentation.

Step 2. Update Configuration Properties

When you have run the script, do the following:

  • Navigate to Configuration properties.
  • Select the checkbox for Will attempt to auto-create related artifacts if set to true….
  • Select Save.

This sets the x_lomo_dx.config.artefactAutoCreation property to “true” (false by default).

Note: Even if you have run the script in step 1, you must set this system property to “true” for the artifacts to be automatically created. If all of these conditions are met, the artifacts are created through a Flow inside of the application scope. If the system property is set to “true”, but the script has not been run, the Flow does not create the artifacts.

Creating Artifacts Manually

If you do not want to run the script on your instance, you can manually create the required artifacts for data synchronization to a new table.

Before you start creating artifacts, do the following:

  • Ensure that the checkbox for Will attempt to auto-create related artifacts if set to true… on Configuration properties is deselected. The system property x_lomo_dx.config.artefactAutoCreation will then be set to “false”, indicating that artifacts are created manually.
  • Ensure that you are creating your artifacts within the LogicMonitor Data Exchange (x_lomo_dx) scope.

Inbound artifacts

Follow these steps to create the artifacts:

  1. Create a new Import Set Table extending Import Set Row (sys_import_set_row) within the LMDX scope.
  2. Create a new Inbound Transform Map within the LMDX scope.
  3. Relate these to the previously created Configuration record through relevant fields in the Inbound section.
  4. Create coalesce_type and external_reference string fields on the new Import Set Table.
  5. Create a scripted sys_id coalesce field on the new Inbound Transform Map (copy the coalesce field from the existing Incident Transform Map).
  6. Create an onAfter Transform Script (copy the onAfter transform script from the existing Incident Transform Map).
  7. Continue by creating the relevant fields on the Import Set Table and Field Maps on the Transform Map. Use the available default import set tables as reference.

Outbound artifacts

Follow these steps to create the artifacts:

  1. Create a Business Rule by copying the existing “LMDX Sync” on the Incident table to your desired SN table.
  2. Create an Outbound Transform Map.
  3. Relate these to the previously created Configuration record through relevant fields in the Outbound section.
  4. Continue by creating the relevant field maps on the Outbound Transform Map, as required for your use case.

When done creating your Inbound and Outbound artifacts, you must associate them with your newly created LMDX Config record.

Outbound Transform Maps

Outbound transform maps work in the same way as ServiceNow transform maps. Using these you can configure which fields on a given record should be sent from ServiceNow to LogicMonitor. The fields are specified using Outbound field maps, similar to ServiceNow field maps.

Outbound Field Maps Features

The following features for Outbound field maps are specific to the LogicMonitor integration.

  • Value type: Available for fields which have an underlying value along with the value displayed in the user interface. It indicates if a field should send the “real” value (for example, a sys_id for a reference field), the “display value” (the value you see in a reference field), or both values.

    Selecting “Both” sets the “display” value to be the value for the field, along with a field with a suffix of “_fv” that will contain the “real” value.

  • Operation type: Indicates if a field is to be sent for a specific record operation type. For example, a field should only be sent if a record has been inserted, updated, or both.

Scripting in Outbound Field Maps

Similar to field maps in ServiceNow, LogicMonitor outbound field maps can run scripts during the transform process. In the Outbound field map for a mapped field, select the Use script checkbox to display the Script field and the associated Field name.

When adding scripts in the Scripts field you can use the following variables:

  • current: A GlideRecord of the record being processed by the outbound transform. The same current object as in Business Rules.
  • ignore: A boolean indicating if a field should be ignored. This value does not need to be returned.

Note: To use the script field, you must return a value as shown in the following example. Alternatively, you can set “ignore” to “true”.

There is validation to ensure that the Field name is unique within the outbound transform map across all outbound field maps, both scripted and non-scripted. This is because JSON is used as data format. Therefore you cannot have duplicate keys as the keys will overwrite the newest value. If you enter a duplicate field name, an error is returned and the action is aborted.

There is also validation to ensure that GlideRecord.insert() and .update() are not used in the Script field. This is because it may have consequences to the logical data flow if the script here is used to insert or modify any records.

Domain Separation Support

The LMDX Connector supports domain separation. This allows the logical separation of instance into separate domains where a single instance can support multiple organizations. See Grouping by Tenant and Domain Separation in About Correlation Models.

All LMDX artifacts (LMDX config, Transform Map and Field Maps, Outbound Transform Map and Outbound Field Maps, Import Set Table and fields) must be created within the global domain. The only exception is the Business Rule – these must reside in the domain set on the LMDX config record through the selected Enabled domain.

If you have set up the application to automatically create artifacts, the domains for these artifacts will be handled automatically as part of the creation process.

Enabling Domain Support

Do the following to enable domain support for LMDX:

  1. Navigate to Conifguration > Configuration properties, and set the system property x_lomo_dx.domainEnabled to “true”.


  2. Under Domain Separation > Endpoints, add the Endpoint URL using the API key provided by your LMDX administrator.


  3. Create an Enabled domain record defining which ServiceNow domain should synchronize using LMDX. This will link the ServiceNow domain to an LMDX endpoint. In the Dexda domain field, enter the value provided by your LMDX administrator.


  4. The Config table displays a mandatory Domain field indicating which Enabled domain record is associated with a Config record.


Domain Hierarchy Support

LMDX supports domain hierarchies. If a record in a child domain matches the parameters set for a Config record in a parent domain, that record triggers the parent domain’s config. This allows for configuration standardization across multiple child domains, for example different customers. You can make changes in one place and apply them across all child domains.

Recommendation: If there is a Config record set for both a child domain and its parent, then any interaction uses the child domain’s Config record. Therefore, you should not set Config records to be on TOP.

Batch Payloads in Domain Separated Instances

There must be an individual scheduled job per Enabled Domain set up in LMDX. All scheduled jobs must have the name of the SN domain added as a string parameter in the script.

Troubleshooting

LMDX has a set of system properties that lets you turn on debugging messages for specific areas. You can find all debugging properties in ServiceNow under Developer Debug.

Property NameDescription
x_lomo_dx.inbound.logLevelInbound HTTP requests.
x_lomo_dx.payload.inbound.logLevelInbound payload processing.
x_lomo_dx.coalesce.logLevelTransform map coalescing.
x_lomo_dx.internal.logLevelServiceNow application configuration, for example reference qualifier and client scripts.
x_lomo_dx.payload.outbound.logLevelOutbound payload processing.
x_lomo_dx.outbound.auth.logLevelDexda authentication.
x_lomo_dx.outbound.logLevelOutbound HTTP requests.
x_lomo_dx.debugOverall debug switch. Only use this if you are unsure of which area is causing errors.

Recommendation: All logging messages have a granular timestamp in the message body. Filter the Message field in descending order when looking at the Application Logs.

In This Article