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.
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||Quick Overview on how to get to the configuration and definitions of each tab.|
|Client Configuration||Information on how to set up credentials created on the ServiceNow side.|
|Synchronisation||Overview of sync frequency, types of syncs, and how to read them.|
|Field Mapping||Description of all possible field mapping types and supported ServiceNow attributes.|
|Sync Filters||The description of all possible ways to filter the data in sync with the Integration|
|Mapping Relations||Defines the methods through which relationships can be pushed or pulled with the Integration|
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'.
Further detailed in the Client Configuration section below in the document, this section is used to configure the credentials and status of the Integration.
This is the property that sets how the partials sync should be executed. It has three options: FULL, SKIP and WITHOUT_RELATION
|FULL||FactSheet Mappings and Relation Mappings will be processed during a partial change|
|SKIP||Partial Changes will not trigger a synchronization run|
|WITHOUT RELATIONS||Only FactSheet Mappings will be processed during a partial change. Relation Mappings are skipped|
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 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.
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.
Fill in the credentials of the Integration user created under the
Create an Integration User section in Setup in ServiceNow.
|ServiceNow URL section to input the URL of the instance which is to be connected with the workspace. e.g. |
|Username section to input the username of the LeanIX Integration user created within the ServiceNow Instance|
|In case Short event buffering is activated, all changes in LeanIX and SN will be synchronized immediately. This setting is useful for testing or demo purposes, but it will increase the amount of CPU usage and network traffic, and should be disabled for production workspaces.|
|Managing User dropdown allows the utilization of a technical user on the LeanIX workspace to run the Integration. This is useful for auditing purposes|
|Use Proxy User check-box is only needed to be activated if the ServiceNow Instance requires a single IP address that can call it as per whitelisting rules. The help text box provides the IP address that is required to be whitelisted as well in such a use case. The current IP Address to whitelist is |
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.
In case an OAuth authentication should be used for communication between LeanIX and the ServiceNow instance, configure the respective credentials using the Advanced Configuration.
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.
|Synchronization Type||Sync Logging Name||Details|
|Full Sync||Sync of all the configured mapping that takes place at a set schedule.|
|Manual Full Sync||Sync of all configured mapping that gets triggered manually by the LeanIX admin|
|Partial Sync - ServiceNow||Sync of changes due to an event trigger of Business Rules from ServiceNow's side.|
|Partial Sync - LeanIX||Sync of changes due to an event from the LeanIX side.|
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
RUNNINGwith 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
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 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 -
|Partial Sync Supported Tables||Business Rule Name|
|CI Relationship - ||CI Relationship|
|SAM/SAM Pro - |
|SAM Software Install & Software Instance|
|Product Model - (||Product Model|
Tip - Disable Business Rules in ServiceNow for Operational Tables
For highly operational ServiceNow instances, having the business rule triggered for tables such as
cmdb_sam_sw_installetc. can cause a lot of triggered runs. By Disabling (Mark as not active) the Business Rules, the
SERVICENOW_CHANGESpartial syncs will not be triggered for those tables.
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.
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 Types are described as follows -
|Mapping Type||Description||Mandatory Fields||Supported SN Attribute Type||Supported LeanIX Field Type|
|Maps the (untranslated) value (ignoring any labels in SN or LeanIX) of a field to the corresponding field in the child system.||Fact Sheet Field|
Choice (will send untranslated values)
|Text, Location (will map the raw location address), Lifecycle (will map the name of the current phase), Lifecycle Phase (will map the start date of the respective phase).|
Location and Lifecycle (current phase) fields can only be used as a source of data, synchronizing from LeanIX to ServiceNow.
|Used to map the URL of the LeanIX Fact Sheet to the foreign object.||Foreign Field||String||n/a|
|Only to be used to set a constant string value to be sent on every synchronized object.||Fact Sheet Field or Foreign Field||String||n/a|
|Used to map fields with multiple choices.||Fact Sheet Field|
|Choice (1:1 mapping only)* certain exceptions explained below||Single Select, Multiple Select (See Advanced Information section)|
|Used to map subscription values between systems.||Fact Sheet Field (Subscription Type)||Reference Fields that directly refer to the |
Glide List fields that directly refer to the
|Subscriptions Tab data only|
|Only Allowed when LeanIX is the source.|
If a Fact Sheet is archived, then a special value is written to ServiceNow
|Used to map tag group fields||Fact Sheet Field (Tags only / Other Tags)|
|String||Tag Groups, Other Tags|
|Used to map tag groups with multiple tags within them.||Fact Sheet Field (Tags Groups)|
|This type is used to map a LeanIX ||Fact Sheet Field (Tags Groups)|
|String||External ID Fields|
|Maps a comma-separated list of Display Names of the related Fact Sheets found for the selected relation.||Fact Sheet Field (relation name)|
|String (Limited to 10 FactSheets, Once the limit is reached text added in the end (+X more)||Relation|
Field Types in ServiceNow are explained in their documentation..
The following dropdown lists fields, tag groups, external IDs, subscription types, and lifecycles based on what is selected as the Mapping Type.
Direction specifies the direction the data flows. From LeanIX to ServiceNow or from ServiceNow to LeanIX for that particular 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 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
is used when fixed values from aSINGLE_SELECT
fields 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
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
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) -
VALUES section is required for the mapping -
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:1Value Mapping Supported only when the source of truth is LeanIX
Attaching multiple values in the
SINGLE_SELECTfield to 1
VALUEin the Choice List field in ServiceNow is supported, provided the source of truth is LeanIX.
The Integration can sync between Multiple Select fields in LeanIX with Glide Lists fields of ServiceNow that refer to a table in ServiceNow.
- 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_idof 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 -
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 -
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.
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/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 the
VALUE_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/phaseIn) fields in LeanIX. Input date should be in the format:
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 -
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.
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.
Active- Only send over Applications from LeanIX that have an Active lifecycle
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
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_grouprole is assigned to the user, and it can see filters created for everyone if the
filter_globalrole is assigned to the user.
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 -
|Graph Rule||Definition||Required Active Mapping and Plugin|
|APPLICATION_SAM_CONNECTION||Synchronize this Software Product Model, if a connection to a Business Application exists that can be found via the SAM module.|
Further filtering can be done while using this Graph Constraint. Detailed below in the Additional Information section of the documentation.
|SAM/SAM PRO + Discovery Service|
IT Component - Software -
|IN_USE_SAM_CONNECTION||Synchronize this Software Product Model, if a connection to Hardware exists that can be found via the SAM module.||SAM/SAM PRO + Discovery Service|
IT Component - Software -
|MODEL_CATEGORY||Synchronize this Product Model, if a connection to a Model Category exists in SN.||IT Component - Software - |
Technical Categories -
|APPLICATION_HARDWARE_CONNECTION||Synchronize this Hardware Product Model, if a connection to a Business Application exists.|
Tip - Check the Additional Information tab for further filter options on this Graph Constraint.
|IT Component - Hardware - |
|IN_USE_HARDWARE_CONNECTION||Synchronize this Hardware Product Model, if a connection to a Hardware exists.||IT Component - Hardware - |
|APPLICATION_SOFTWARE_MANAGEMENT_MODEL_CONNECTION||Synchronize this Software Product Model, if a connection to a Business Application exists that can be found via the Software Management module.||Only supported when Legacy Configuration is in use|
IT Component - Software -
|IN_USE_SOFTWARE_MANAGEMENT_MODEL_CONNECTION||Synchronize this Software Product Model, if a connection to a Hardware exists that can be found via the Software Management module.||Only supported when Legacy Configuration is in use|
IT Component - Software -
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.
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.
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.
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).
This mapping type is used when pulling or pushing to a
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 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.
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.
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.
Only supported where ServiceNow is configured as the source of the relation.
This relation type does not need any additional configuration.
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.
|Case||Description||Source of Truth||Action|
|Case 1.||Relationship between 2 Fact Sheets that are both linked to ServiceNow||Deletions will happen|
If the relationship does not exist in ServiceNow/LeanIX, it will be deleted in LeanIX. This is to honor the defined source of truth.
|Case 2.||Relationship between 2 Fact Sheets where one is linked to ServiceNow and the other one isn't||Deletions will not happen|
Because the other Fact Sheet is not linked to ServiceNow/LeanIX, the Integration will not touch this relationship and it will not be deleted.
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).
Updated about 1 month ago