The following documentation is in continuation of the Setup in ServiceNow document. Please ensure the outlined steps there are complete before proceeding with the setup in LeanIX.

👍

Access

The following document assumes that there are point of contacts ready both on the LeanIX side (LeanIX Admins) and ServiceNow (ServiceNow Instance admin) who have the necessary rights and roles within the organization to make the outlined changes.

Navigation

To configure the synchronisation, within a workspace click your profile icon in the upper right corner and select 'Administration'.

Then navigate to 'Discovery & Integrations' > 'Integrations' and select the ServiceNow integration by clicking on 'Configure'.

Credentials Tab

Further detailed in the Client Configuration section below in the document, this section is used to configure the credentials and status of the Integration.

Partial Sync Mode

This is the property that sets how the partials sync should be executed. It has three options: FULL, SKIP and WITHOUT_RELATION

Mappings Tab

The Mappings Tab is the UI section provided to help quickly set up the configuration of the Integration in a no-code way. It is detailed further in the Core Concepts section of ServiceNow Integration.

Advanced Tab

Advanced Tab is the JSON representation of everything set in the Basic Tab. Any configurations or additional changes made in the Basic section will be represented within the advanced tab.

There are a few items in the Integration that can only be configured in the advanced tab. Such as OAuth 2.0 setup, advanced relationship mapping, dot walking, and others. For more details, read the corresponding page on the Advanced Configuration.

In case you do not see the Advanced tab in your configuration, you may reach out to support through our Support Form Submission to activate this feature.

Versions Tab

The Versions Tab allows you to see previous versions of your configuration.

You can view each version by clicking the "View JSON" button after hovering over the version's row.

You may compare two versions by marking the checkboxes beside them and then clicking the "Compare" button:

The differences in configuration between the two versions will be shown in highlights as you scroll up and down.

If one of the versions you selected is the current version (highlighted by a green "Current Version" text), you can restore the previous configuration version by clicking the "Restore Previous Version" button below.

Credential Configuration

Fill in the credentials of the Integration user created under the Create an Integration User section in Setup in ServiceNow.

Upon clicking on 'Save' with the Active box checked, LeanIX will check the access to ServiceNow and all configured tables and columns in the provided ServiceNow Instance.

If everything goes well, a green Toastr message will appear in the upper right corner.

If an error occurs, please check the credentials and whether the account created is according to the required roles and access as shown in Setup in ServiceNow.

Enable OAuth 2.0 for Authentication

In case an OAuth authentication should be used for communication between LeanIX and the ServiceNow instance, configure the respective credentials using the Advanced Configuration.

Synchronisation

The following section explains the type of synchronization offered depending on the configurations. Details of the synchronization runs are visible in the Sync Logging section within the workspace.

Manual Full Sync

A manual full synchronization can be triggered from LeanIX's administration within a workspace.

During a manual full sync, the integration sequentially goes through the mapped configuration to sync records and relationships. If triggered manually as seen above, it will show up as the type FULL_SYNC_MANUAL within the sync logging section.

🚧

Sync Logging Time

Time taken by a sync depends heavily on the size of the records in sync with the configured ServiceNow environment. Additionally the sync could show up as RUNNING with no visible updates in the log for long periods of time. This usually happens when the Integration is processing data within the backend tables such as cmdb_rel_ci or cmdb_sam_sw_install.

Scheduled Full Sync

Beyond the manual full syncs that can be triggered anytime by the LeanIX admin, there are also full sync runs that take place automatically on the workspace.

Full Sync is scheduled to run at midnight related to the time zone in which the LeanIX Instance is hosted.

Partial Sync

Partial syncs are event-driven that get triggered from both sides (LeanIX and ServiceNow). In each case, it gets triggered any time a Fact Sheet or a record is created, updated, or deleted in the systems.

In the default model (flag 'short event buffering' is not set), the partial sync is triggered as soon as the batch is full (5000 changes have been logged) or the batch wait time has been exceeded (15 minutes after the first change was logged).

📘

Short event buffering

In 'short event buffering' mode, the batch wait time is reduced to five seconds. We only recommend using the short event buffering for manual testing purposes.

For ServiceNow, the LeanIX application installs a couple of Business Rules to track these events and trigger a sync as seen here -

👍

Tip - Disable Business Rules in ServiceNow for Operational Tables

For highly operational ServiceNow instances, having the business rule triggered for tables such as cmdb_rel_ci or cmdb_sam_sw_install etc. can cause a lot of triggered runs. By Disabling (Mark as not active) the Business Rules, the SERVICENOW_CHANGES partial syncs will not be triggered for those tables.

First Sync Behavior

On the first sync, the Integration matches the records based on the name field in LeanIX and name in ServiceNow. In case there are redundancies, but with the same name then the Integration will match the record in LeanIX and link the ServiceNow external ID to it.

If there is no match then a new Fact Sheet is created in LeanIX or a new record is created in ServiceNow.

Field Mapping

For each specified Fact Sheet Type and ServiceNow table, the mapping of fields can be specified by pressing the 'Edit Mapping' button. Here the configuration is set for the data that will be transferred from a Fact Sheet field to a ServiceNow table attribute in its form and direction.

The following section describes in detail the type of mappings available within the LeanIX-ServiceNow Integration and how to map them.

Mapping Type

Mapping Types are described as follows -

Field Types in ServiceNow are explained in their documentation..

Fact Sheet Field

The following dropdown lists fields, tag groups, external IDs, subscription types, and lifecycles based on what is selected as the Mapping Type.

Direction

Direction specifies the direction the data flows. From LeanIX to ServiceNow or from ServiceNow to LeanIX for that particular field.

ServiceNow Field

The following dropdown lists the attributes available within the configured ServiceNow table.

❗️

Not all ServiceNow Attributes are supported to sync

Even though the Foreign Field mapping displays all available attributes in the table, not all fields are currently supported to be synced with LeanIX.

Configure Details

Configure Details is a button that is only offered for some special mapping types to provide more configuration, like a mapping of fixed values for choices.

One example of the use of the Configure Details section is theVALUE_MAPPING.VALUE_MAPPINGis used when fixed values from aSINGLE_SELECTfields must be mapped to choices in theCHOICE` field type in ServiceNow.

The example below shows VALUE_MAPPING configuration of LeanIX's businessCriticality field with ServiceNow's business_criticality attribute.

Here the left side indicates the data-model name values of within the businessCriticality field in LeanIX. Similarly, the right side is mapped to the value of the choices within the business_criticality attribute in ServiceNow.

👍

Tip - Use Self-Configuration Menu to get the data-model key of the fields in LeanIX

Translations are not relevant in the VALUE_MAPPING section

The data-model keys are visible within brackets as seen below -

Similarly, within ServiceNow, they can be seen by right-clicking on the field and selecting "Show Choice List"(Admin access required) -

Only the VALUES section is required for the mapping -

Each VALUE_MAPPING is validated when you save the configuration, and during every synchronization, to ensure only valid values are used for mapping from LeanIX to ServiceNow.

❗️

n:1 Value Mapping Supported only when the source of truth is LeanIX

Attaching multiple values in the SINGLE_SELECT field to 1 VALUE in the Choice List field in ServiceNow is supported, provided the source of truth is LeanIX.

Advanced Field Mapping Use Cases

Sync Multiple Select Fields between LeanIX and ServiceNow

The Integration can sync between Multiple Select fields in LeanIX with Glide Lists fields of ServiceNow that refer to a table in ServiceNow.

Pre-Requisites

• Multiple Select Field with values in LeanIX
• GlideList field in ServiceNow, with the values of the records you wish to map to LeanIX or the sys_id of the records in the referenced table in ServiceNow.

Within ServiceNow however, there can be two types of list fields -

• List fields that reference another ServiceNow Table

• List fields that do not refer to another ServiceNow Table and have a choice list defined

To map both of these fields, the Mapping Type of VALUE_MAPPING is used -

❗️

Make sure to fill in the extra fields section!

Mapping multiple select fields requires you to map the data model name of the values of the multiple select field in LeanIX with the values of either the sys_ids of the records or the values of the choices from the ServiceNow side.

• Example Extra field mapping when the field is referencing another table -

Collect the sys_id of all the records you wish to map with the multiple select values in LeanIX, this can be done for multiple records by exporting or by selectively copying the sys_id as follows -

These collected sys_ids can be mapped to LeanIX as follows -

❗️

Unmapped values will be ignored

If the extra field section does not fully cover the mappings, any additional values on each system will be ignored by the sync.

Once saved, the sync will automatically match the sys_ID with the respective record in ServiceNow. Similarly, it will also match the sys_ID with the mapped field in LeanIX from the extra fields section.

Examples -

Supported Lifecycle and Dates Sync Methods

👍

Supported Lifecycle Sync Methods

Case 1 - Lifecycle current phase can be pushed from LeanIX to a ServiceNow field.
Case 2 - Lifecycle date values can be pulled from ServiceNow to LeanIX lifecycle phase fields
Case 3 - LeanIX lifecycle phase dates can be pulled and pushed to ServiceNow Date fields
Case 4 - String fields in LeanIX can pull the values of dates from ServiceNow
Case 5 - String fields in LeanIX can push the values of dates to ServiceNow

Case 1 -
The source of truth for the fields is LeanIX, selecting the main Lifecycle field instead of one of its phases (e.g. using lifecycle, not lifecycle/active or lifecycle/phaseIn). Only for this case, it is not a Date but a String representing the current phase that is synchronized to ServiceNow. This value can be mapped if needed using theVALUE_MAPPING as mapping type.

Case 2 -
The source of truth for the fields is ServiceNow instead of LeanIX. Supported Date type attributes can sync date values from ServiceNow to the respective Lifecycle phase (e.g. lifecycle/active, lifecycle/phaseIn) fields in LeanIX. Input date should be in the format: yyyy-mm-dde.g. 2014-01-01

Case 3 -
The source of truth for the fields is LeanIX. LeanIX lifecycle date values of Plan, Active, Phase Out, etc can now be synced to supported Date type attributes in ServiceNow. Similar to Case 1 above, within the advanced section set the lifecycle/plan etc value to a date field in ServiceNow.

Case 4 and 5 -

In this case, it is required to create a field of type STRING which is rendered as a DATE in LeanIX -

Within the Integration configuration's Basic UI Tab, the fields are mapped as follows -

Sync Filters

The following section details the methods that can be used depending on the source of truth to limit the number of records in sync with the Integration.

Filtering from LeanIX to ServiceNow

When LeanIX is the source of truth, Fact Sheets can be filtered through the same methods of Inventory filtering to only allow a certain subsection of Fact Sheets to go to the ServiceNow table in sync.

It can be done by clicking on the Filters button.

Once selected, the Inventory view opens up allowing to set specific filters based on any filterable property for the Fact Sheet type.

Once the filter is set, select Use Fact Sheet Filter and click on Save button on the Mapping Tab to ensure the filter is saved permanently.

👍

Tip - Popular Filters applied for Applications

Data Quality Broken Inversed - Only send over Applications from LeanIX that have an approved Data Quality status.
Lifeycle - Active - Only send over Applications from LeanIX that have an Active lifecycle

Filtering from ServiceNow to LeanIX

When ServiceNow is the source of truth, the filter needs to be created on the ServiceNow side to limit the number of records that get created in LeanIX. In addition, when clicking on the three ..., the drop-down changes to say "Edit Constraints".

To create a filter on the ServiceNow side, one would either need to Impersonate the leanix.integration user which is in the credentials section, or create a filter that is globally visible or at least visible to the Integration user.

For the table in sync, create a filter through the filtering functionality and save it. If logged in as the Integration user, it can be set to be visible to only me. However, if logged in as an admin, please ensure to either select everyone or group to ensure the Integration user will have access to it.

Once saved, the filter will be visible in the ServiceNow filter drop-down on the LeanIX side -

Once again, ensure to not only press OK at the dialog box but then Save the whole configuration again from the Basic UI tab.

📘

Visibility of available filters for your integration user

The amount of available filters for a table in ServiceNow depends on the visibility of those filters to the Integration user (for example leanix.integration). By default, any user can see only filters created by the same user for a table.

If the user belongs to a user group, it can see filters created for that group if the filter_group role is assigned to the user, and it can see filters created for everyone if the filter_global role is assigned to the user.

Graph Rule Constraints

A Graph Rule Constraint controls whether a record is synchronized at all based on a connection found on the ServiceNow side. Depending on the ServiceNow table used in a mapping from ServiceNow to LeanIX, different or no Graph Rule Constraint might be applicable.

The configuration dialog for Sync Constraints is opened when ServiceNow is the Source, the configured ServiceNow Table supports the Graph Rules, and the '...' button is pressed.

Various types of Graph Rules are explained as follows -

Mapping Relations

After configuring how you want to map certain Fact Sheets into ServiceNow tables - or vice versa - you can also decide to map relations between those Fact Sheets or records to the other system.

When you add a new Relation mapping, you first need to select the following options:

• Active: Allows you to activate or deactivate a certain relation mapping
• Fact Sheet Mapping: Select which of the two entities the relationship has to be with
• Fact Sheet Mapping : Select which of the two entities the relationship has to be with
• Source System: Select the source system from which the relationship should be managed

Next, click on Configuration to open a dialog that allows you to configure the details of the relation.

Selecting the LeanIX Relation

First, select the relation that is to be used on the LeanIX side. Depending on the Source you selected in the previous step, this is either the relation in LeanIX that is read from or the relationship that is created based on a relation within ServiceNow.

Configuring the ServiceNow Relation

Next, you need to configure the relation to be used on the ServiceNow side. Depending on the Source you selected in the basic tab, this is either the relation in ServiceNow that is read from or the relationship that is created based on the relation within LeanIX.

Depending on the relation that you choose, you may need to configure additional information.

CMDB_REL_CI

This mapping type is used to create or pull from relationships between two ServiceNow tables that use the cmdb_rel_ci table. A common example is the relationship between a Business Capability and a Business Application in ServiceNow.

For this relation mapping, you need to select the type of the relations in the cmdb_rel_ci table that should be read or pushed (in case of reading from ServiceNow, you can also decide to read all of the available types).

Configuring query filters is only possible using the Advanced Configuration, in this dialog you can only view them. Please ask for guidance from Customer Success, as these filters can have subtle effects on the mapping (e.g. performance).

REFERENCE_FIELD

This mapping type is used when pulling or pushing to a Reference or Glide List field in ServiceNow that refers to a table in sync. During the synchronization run, the LeanIX-ServiceNow Integration will automatically detect the exact technical type behind the field which is selected in the following dropdown and apply the suitable updates.

MAPPING_TABLE

The MAPPING_TABLE configuration defines the case when a custom table which holds two columns of field type Reference in ServiceNow are used to hold relations between two items in arbitrary tables.

This case is analogous to a mapping table concept as used in databases.

❗️

Supported Direction

Only supported where ServiceNow is configured as the source of the relation.

For this relation mapping, please select the table and fields you want to read the relation from.

GRAPH_RULE_CONSTRAINT

For this relation to work, at least one of the involved ServiceNow tables needs to have a Graph Rule Constraint configured (see above). The respective Graph Rule that is configured to constraint the number of records to be mapped will then be used to model this very graph as a relation in LeanIX.

❗️

Supported Direction

Only supported where ServiceNow is configured as the source of the relation.

This relation type does not need any additional configuration.

Relation Sync Behavior

❗️

Relationships of Fact Sheets in sync with ServiceNow are always in Strict Mode

Unlike Fact Sheet descriptors, there is no strict flag to turn off for relationship descriptors. This is intended functionality that allows the Integration to delete relationships if they are no longer in the source system to always maintain parity.

🚧

Ensure Fact Sheet descriptors are active before syncing relationships.

For example, if syncing relationships between Applications and Business Capabilities, it is necessary to have Application and Business Capability set to Active in the section above.

Here we define a few cases and the intended action the Integration will take for each of them about the relationships.

The following above cases can be illustrated in the following example of an Application to IT Component relationship. Consider an Application Fact Sheet called "AC Management LeanIX" which is linked to two IT Components -

For the Fact Sheet above, the two connected IT Components are all coming from ServiceNow and thus are also linked to ServiceNow. If the Integration is not able to read the relationship between these 2 IT Components and the Application in the next sync, they will be deleted. (Case 1)

Subsequently, We then consider adding another manual relationship to this Application, an IT Component Fact Sheet which is not linked to ServiceNow, but rather created manually in LeanIX either by the user or other Integrations.

In the case above, the Integration's logic knows not to touch the third relationship as it could be managed by the user and/or another Integration. This is known also because the third Fact Sheet also illustrated by its name, is not linked to ServiceNow. In the case of a sync run, if the Integration sees no relationships in the source system, it can at best delete the first two relationships, but not the third one. (Case 2).