Setup in LeanIX
Once the LeanIX app in ServiceNow is configured, we can get started with the implementation on the LeanIX workspace.
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.
Section | Details |
---|---|
Navigation | Quick Overview on how to get to the configuration and definitions of each tabs. |
Client Configuration | Information on how to setup credentials created on the ServiceNow side. |
Synchronisation | Overview on sync frequency, types of syncs and how to read them. |
Field Mapping | Description on all possible field mapping types and supported ServiceNow attributes. |
Sync Filters | Description on all possible ways to filter on the data in sync with the Integration |
Relationships | Defines the concept of relationships and the preset relationships loaded as part of the Default Supported Configuration |
Supported Custom Relationship Types | Defines the methods through which custom relationships can be set with the Integration |
Additional Information | The following section defines some of the exceptions and additional filtering options that can be used and also details the behavior the integration takes on the first sync. |
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'.

Integrations Page
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.

Credentials tab
Basic Tab
Basic Tab is the UI section provided to help quickly setup 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.

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. 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.
Tip - Use the JSON in the advanced section to backup and restore configurations
The JSON can be copied and saved locally as a way of version control, backup, and restore tasks. Simply select all in the advanced section and paste it in your IDE of choice and save it as a
.JSON
file.
Tip - Restore back to default configuration
If you clear out the configuration in the json editor, just put in an empty json document '{}', then the default supported configuration mapping is restored you can use as a good starting point.
Credential Configuration
Fill in the credentials of the Integration user created under the Create an Integration User
section in Setup in ServiceNow.

Credentials Section
Key | Type |
---|---|
1 | ServiceNow URL section to input url of the instance which is to be connected with the workspace. e.g. <https://clientdomain.service-now.com > |
2 | Username section to input the username of the LeanIX Integration user created within the ServiceNow Instance |
3 | 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. |
4 | Managing User dropdown allows to utilize a technical user on the LeanIX workspace to run the Integration. This is useful for auditing purposes |
5 | 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 23.97.217.0 |
Upon clicking on 'Save' with the Active
box chceked, 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 on 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, a ClientId
and a ClientSecret
needs to be added to the configuration.
If this is specified, the integration will use the oauth
settings in addition to the user's name and password to fetch an oauth token for the REST calls.
Instructions on how to create the the ClientID
and ClientSecret
are detailed in the `Enable OAuth 2.0 for Authentication section in Setup in ServiceNow.
On the LeanIX side, this is configured only in the Advanced tab as follows -
...
"oauth": {
"clientId": "client id of Application Registration's endpoint",
"clientSecret": "client secret of Application Registration's endpoint"
}

clientSecret
is encyrpted upon saving and will not be visible.
Synchronisation
The following section explains the type of synchronization offered depending on the configurations. Details of th e synchronization runs are visible in the Sync Logging
section within the workspace.
Synchronization Type | Sync Logging Name | Details |
---|---|---|
Full Sync | FULL_SYNC | Sync of all the configured mapping that takes place at a set schedule. |
Manual Full Sync | FULL_SYNC_MANUAL | Sync of all configured mapping that gets triggered manually by the LeanIX admin |
Partial Sync - ServiceNow | SERVICENOW_CHANGES | Sync of changes due to an event trigger of Business Rules from ServiceNow's side. |
Partial Sync - LeanIX | LEANIX_CHANGES | Sync of changes due to an event from LeanIX side. |
Manual Full Sync
A manual full synchronisation can be triggered from LeanIX's administration within a workspace.

Sync Now
button can be triggered by an admin of the workspace to trigger a full sync run.
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 ascmdb_rel_ci
orcmdb_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 12:00 AM related to the time zone 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 -

Business Rules installed by the LeanIX app that look for events to trigger a Partial Sync
Partial Sync Supported Tables | Business Rule Name |
---|---|
cmdb_ci which by inheritance includes any table in sync such as -cmdb_ci_business_app ,cmdb_ci_business_capability , cmdb_ci_hardware or any other custom table. | CMDB CI |
CI Relationship - cmdb_rel_ci | CI Relationship |
SAM/SAM Pro - cmdb_sam_sw_install Legacy - cmdb_software_instance | SAM Software Install & Software Instance |
Product Model - (cmdb_model ) which by inheritance includes -cmdb_hardware_product_model cmdb_software_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_rel_ci
orcmdb_sam_sw_install
etc. can cause a lot of triggered runs. By Disabling (Mark as not active) the Business Rules, theSERVICENOW_CHANGES
partial syncs will not be triggered for those tables.
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 Type dropdown
Mapping Types are described as follows -
Mapping Type | Description | Mandatory Fields | Supported SN Attribute Type | Supported LeanIX Field Type |
---|---|---|---|---|
FOREIGN_FIELD | 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 Foreign Field | String Choice (will send untranslated values) | Text |
URL | Used to map the url of the LeanIX Fact Sheet to the foreign object. | Foreign Field | String | n/a |
FIXED_VALUE | Only to be used to set a constant string value to be sent on every synchronised object. | Foreign Field | String | n/a |
VALUE_MAPPING | Used to map fields with multiple choices. | Fact Sheet Field Foreign Field | Choice (1:1 mapping only)* certain exceptions explained below | Single Select, Multiple Select (See Advanced Information section) |
SUBSCRIPTION | Used to map subscription values between systems. | Fact Sheet Field (Subscription Type) | Reference Fields that directly refer to the sys_user or sys_user_group table.e.g. business_owner field.Glide List fields that directly refer to the sys_user table. | Subscriptions Tab data only |
ARCHIVED_STATUS_MAPPING | Only Allowed when LeanIX is the source. If a Fact Sheet is archived, then a special value is written to ServiceNow | Foreign Field | Choice. e.g. operational_status field updated with 6. Which has the label of Retired . | n/a |
TAG_GROUP_FIELD | Used to map tag group fields | Fact Sheet Field (Tags only / Other Tags) Foreign Field | String | Tag Groups, Other Tags |
TAG_GROUP_MAPPING | Used to map tag group with multiple tags within them. | Fact Sheet Field (Tags Groups) Foreign Field | Choice | Tag Groups |
EXTERNAL_ID | This type is used to map a LeanIX ExternalId field to a ServiceNow column. | Fact Sheet Field (Tags Groups) Foreign Field | String | External ID Fields |
Field Types in ServiceNow are explained in their documentations..
Fact Sheet Field

Fact Sheet Field dropdown
The following dropdown lists fields, tag groups, external IDs, subscription types on the basis of what is selected as the Mapping Type.
Foreign Field

Foriegn Field Dropdown
The following dropdown lists the attributes available within the configured ServiceNow system.
Not all ServiceNow Attributes are supported to sync
Even though the Foriegn Field mapping displays all available attributes in the table, not all fields are currently supported to be synced with LeanIX.
Normal Direction
Normal Direction specifies the direction the data flows. If check, the field's data flows from specified source of truth to child system. Of unchecked, the data flows opposite from child to specified source of truth parent.
Extra Fields
Extra fields 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 Extra Fields section is VALUE_MAPPING
.VALUE_MAPPING
is used when fixed values from a SINGLE_SELECT
fields must be mapped to choices in the CHOICE
field type in ServiceNow.
Example below shows VALUE_MAPPING
configuration of LeanIX's Lifecycle
field with ServiceNow's operational_status
attribute.
An additional option of Extra Fields with three ...
opens up to configure -

Value Mapping example of operational_status
Here the left side indicates the data-model
name values of within the Lifecycle field in LeanIX. Similarly the right side is mapped to the value of the choices within the operational_status
attribute in ServiceNow.

The left column contains the strings used on LeanIX side, the right column contains the values used in ServiceNow choice fields.
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 key's are visible within brackets as seen below -

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

Select - Show Choice List
Only the VALUES
section is required for the mapping -

Only the Value
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 LeanIXAttaching multiple values in the
SINGLE_SELECT
field to 1VALUE
in the Choice List field in ServiceNow is supported, provided the source of truth is LeanIX.

n:1
Value Mapping support. Business Operational and Administrative Service Criticality both get mapped to the Low choice in ServiceNow.
Sync Filters
The following section details out 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 three ...
on the descriptor you want to filter and select Edit Filters
.

Edit Filters per Fact Sheet type.
Once selected, the Inventory view opens up allowing to set specific filters on the basis of any filterable property for the Fact Sheet type.

Inventory View for filters
Once the filter is set, select Use Fact Sheet Filter
and click on Save
button on the Basic 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.

Filter from the ServiceNow side
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 -

Filter from the ServiceNow side available to choose from on the LeanIX Basic UI.
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 thefilter_global
role is assigned to the user.
Graph Rule Constraints
Only Supported on default configuration mappings
Graph Rule Constraints is only supported when the default supported configuration is in use. i.e. Applications are linked to
cmdb_ci_business_app
and IT Component SW/HW are linked to the respective Product Model tables. (cmdb_software_product_model
,cmdb_hardware_product_model
).They will only be functional on the IT Component Software and Hardware dropdowns.
A Graph Rule Constraint controls whether a record is synchronised at all based on a connection found on the ServiceNow side. At the moment, this only works for Hardware and Software Product Models.
It can be used to configured for usage of the Software Asset Management (SAM/SAM Pro) or regular Software Management of SN.
The configuration dialog for Sync Constrains is opened when the '...' button is pressed.

Graph Rule Constraints
Various types of Graph Rules are explained as follows -
Graph Rule | Definition | Required Active Mapping and Plugin |
---|---|---|
APPLICATION_SAM_CONNECTION | Synchronise 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 out below in the Additional Information section of the documentation. | SAM/SAM PRO + Discovery Service IT Component - Software - cmdb_software_product_model Application - cmdb_ci_business_app |
IN_USE_SAM_CONNECTION | Synchronise this Software Product Model, if a connection to a Hardware exists that can be found via the SAM module. | SAM/SAM PRO + Discovery Service IT Component - Software - cmdb_software_product_model |
MODEL_CATEGORY | Synchronise this Product Model, if a connection to a Model Category exists in SN. | IT Component - Software - cmdb_software_product_model Technical Categories - cmdb_model_category |
APPLICATION_HARDWARE_CONNECTION | Synchronise this Hardware Product Model, if a connection to a Business Application exists. Tip - Check Additional Information tab for further filter options on this Graph Constraint. | IT Component - Hardware - cmdb_hardware_product_model Application - cmdb_ci_business_app |
IN_USE_HARDWARE_CONNECTION | Synchronise this Hardware Product Model, if a connection to a Hardware exists. | IT Component - Hardware - cmdb_hardware_product_model |
APPLICATION_SOFTWARE_MANAGEMENT_MODEL_CONNECTION | Synchronise 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 - cmdb_software_product_model Application - cmdb_ci_business_app |
IN_USE_SOFTWARE_MANAGEMENT_MODEL_CONNECTION | Synchronise 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 - cmdb_software_product_model |
MAPPING_TABLE_CONNECTION | Synchronises the objects which are available in the custom relationship table defined in relationship type: "MAPPING_TABLE" Please note that this Graph Constraint is not available within the UI dropdown and can only be set in the Advanced Section. | n/a |
Relationships
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.
Here we define a few cases and the intended action the Integration will take for each of them pertaining to the relationships.
Case | Description | Source of Truth | Action |
---|---|---|---|
Case 1. | Relationship between 2 Fact Sheets that are both linked to ServiceNow | ServiceNow , LeanIX | 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 | ServiceNow , LeanIX | 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 -

2 Connected LeanIX Relationships which are linked to ServiceNow.
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 Application in the next sync, they will be deleted. (Case 1)
Subsequently, We then consider adding another manual relationship to this Application, of an IT Component Fact Sheet which is not linked to ServiceNow, but rather created manually in LeanIX either by the user or other Integrations.

First two related IT Components are connected to ServiceNow, but the third one isn't.
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 from 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).
Preset Relationships
The following section details out on how to configure relationships between LeanIX and ServiceNow.
Advanced Tab configuration required in some cases.
Relationship configurations beyond the presets of the relationships created by the default supported config require some additional modifications in the advanced configuration.
The following relationships have a hardcoded logic in them in the backend and are loaded automatically as part of the default supported configuration.
From Fact Sheet Type | Relationship name* | To Fact Sheet Type | Description | Advanced Configuration Required | Source |
---|---|---|---|---|---|
Application | IT Components | IT Component | Pulls relations between Applications and IT Components by traversing through the relations in the table cmdb_rel_ci , cmdb_ci_hardware and software installation tables and establishing a link to the IT Components.As explained in the default supported configuration. | No | ServiceNow |
ITComponent | Tech Categories | Tech Category | Pulls relations between Tech Category and IT Components by checking the cmdb_model_category attribute on the Product Model records and establishing a link to the IT Components | No | ServiceNow |
Business Capability | Applications | Application | Pushes relationships created within the Business Capability and Application Fact Sheets in LeanIX to ServiceNow using the cmdb_rel_ci table and the Provided By::Provides relationship type. | No | LeanIX |
Business Capability | Parent | Business Capability | Pushes parent-child hierarchies created within the Business Capability Fact Sheets in LeanIX to ServiceNow using the parent reference field. | No | LeanIX |
*Relationship name is relevant as the relationship will be created as per the name mentioned here.
Ensure Fact Sheet descryptors are active before syncing relationships.
For example, if syncing relationships between Applications and Business Capabilities as we see above, it is necessary to have Application and Business Capability set to Active in the section above.
Supported Custom Relationship Types
The Integration can detect the following types of custom relationships for syncing -
Supported Case | Supported Source | foreignRelationMapping | Advanced Configuration |
---|---|---|---|
Relationship between two ServiceNow tables using cmdb_rel_ci table. | ServiceNow & LeanIX | CMDB_REL_CI | Required |
Relationship between two ServiceNow tables using a Reference Field . | ServiceNow & LeanIX | REFERENCE_FIELD | Required |
Relationship between two ServiceNow tables using a Glide List field type. | ServiceNow & LeanIX | REFERENCE_FIELD | Required |
Relationship between two ServiceNow tables using a Mapping table and Reference Fields . | ServiceNow | MAPPING_TABLE | Required |
Subsequently the next section goes through each supported case and see how to configure it within LeanIX.
However, for a foundational understand, here is the explanation of each key in the advanced configuration while working with relationships -
Key (Line Number) | Description | Visiblility in Basic UI tab |
---|---|---|
active (178) | Determine whether the folllowing relationship type should be synced or not. | Yes, Active checkbox |
masterSite (179) | Determine the source of truth of the relationship. | Yes, Source dropdown |
relationName (180) | Reads the relationship in LeanIX from or with which the records will be synced. | Yes, Relationship Name dropdown. However, in the UI only the relationship label is presented. Example - In the example above, Line 180 reads relToParent . Whereas, in the UI it will just show its label, which is Parent . |
reverseRelationName (181) | Reverse of the relationship defined above. LeanIX Integration automatically sets this field accordingly. | No |
typeFrom (182) | Details the name of the Fact Sheet Type from which the relationship sync will happen. | Yes, From Fact Sheet Type dropdown |
typeTo (183) | Details the name of the Fact Sheet Type to which the relationship sync will happen | Yes, To Fact Sheet Type dropdown |
automaticForeignTablesConfiguration (184) | Determines whether the LeanIX Integration should automatically read the ServiceNow table connected to the From and To Fact Sheet Types in the descryptors and set it in Lines 185-186 | No |
foreignFrom (185) | Details the name of the ServiceNow table from which the relationship sync will happen. | No |
foreignTo (186) | Details the name of the ServiceNow table to which the relationship sync will happen | No |
referenceToField (187) | Defaults to null but is mandatory to be set when doing REFERENCE_FIELD mapping type. | No |
foreignRelationMapping (188) | Defaults to null but is mandatory to be set when doing any custom relationship mapping. | No |
type (189) | Mandatory to be set for CMDB_REL_CI , REFERENCE_FIELD , or MAPPING_TABLE types. | No |
relationName (not visible in screenshot above) | Defines the name of the relationship type to pull or push to from ServiceNow. This is mandatory to set when using the CMDB_REL_CI mapping type. | No |
query (not visible in screenshot above) | Defines the constraint to use for the Integration while processing relationships from CMDB_REL_CI mapping type. | No |
Tip -
automaticForeignTablesConfiguration
By default, configuration for each relation automatically fills the
foreignFrom
andforeignTo
fields with the ServiceNow tables used for the correspondingtypeFrom
andtypeTo
Fact Sheet types in Sync Descriptors.This can be disabled to allow manual editing of foreign tables.For this, set the
automaticForeignTablesConfiguration
field tofalse
(default: true).
CMDB_REL_CI
Tip - Start by creating the relationship first in the Basic Tab
By doing so, the Integration will automatically set the syntax with many fields already set such as
active
,masterSite
,relationName
etc.
This mapping type is used to create or pull from relationships between two ServiceNow tables that use the cmdb_rel_ci
table. Common examples being the relationship between a Business Capability and Business Application in ServiceNow. It uses the Provided By::Provides
relationName available through the cmdb_rel_ci
table.
By using the tip above, first set the relationship in the UI and save the configuration. It is important to save the configuration in this state first before configuring in the advanced tab.

Relationship first set in the UI as follows and then saved.
Subsequently, this newly created relationship will show up in the Advanced tab as follows -

Advanced Tab automatically filled out the majority of the keys.
For CMDB_REL_CI
mapping type use-cases we then fill in the remaining information as follows -
{
"active": true,
"masterSite": "LEANIX",
"relationName": "relBusinessCapabilityToApplication",
"reverseRelationName": "relApplicationToBusinessCapability",
"typeFrom": "BusinessCapability",
"typeTo": "Application",
"automaticForeignTablesConfiguration": true,
"foreignFrom": "cmdb_ci_business_capability",
"foreignTo": "cmdb_ci_business_app",
"referenceToField": "",
"foreignRelationMapping": {
"type": "CMDB_REL_CI",
"relationName": "Provided By::Provides",
"query":"parent.sys_class_name=cmdb_ci_business_capability^child.sys_class_name=cmdb_ci_business_app^typeISNOTEMPTY"
}
}
In the above snippet, we added the contents from line 13-15.
Line | Type | Description |
---|---|---|
13 | "type": "CMDB_REL_CI", | This type lets the integration know to form/pull this relationship using the cmdb_rel_ci table. |
14 | "relationName": "Provided By::Provides", | Relation Name is the name of the relationship to use in ServiceNow to form the relationship or to pull from. This is provided by ServiceNow. |
15 | "query": "parent..." | Query is an optional key added to improve performance of the Integration. The example here is of a query that reads from only those relationships where the Parent Class is Business Capability and Child Class is Business Application. |
REFERENCE_FIELD
- Relationship between two ServiceNow tables using a
Reference Field
. - Relationship between two ServiceNow tables using a
Glide List
field type.
This mapping type is used when pulling or push to a reference 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 specified by referenceToField
and apply the suitable updates.
Following example is when LeanIX sends the parent-child hierarchies created in LeanIX for Business Capabilities to ServiceNow using the parent
field as the reference field.
{
"active": true,
"masterSite": "LEANIX",
"relationName": "relToParent",
"reverseRelationName": "relToChild",
"typeFrom": "BusinessCapability",
"typeTo": "BusinessCapability",
"automaticForeignTablesConfiguration": true,
"foreignFrom": "cmdb_ci_business_capability",
"foreignTo": "cmdb_ci_business_capability",
"referenceToField": "parent",
"foreignRelationMapping": {
"type": "REFERENCE_FIELD"
}
}
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 analogue to a mapping table concept as used in databases.
To define this type of relation, the referenceToField
needs to be empty and the foreignRelationMapping
defines the name of the mapping table and its two reference field columns.
MAPPING_TABLE
Supported DirectionOnly supported where ServiceNow is the source of truth. i.e. Currently it is not possible to push relationships to a Mapping Table in ServiceNow from LeanIX.
Tip - Advanced Graph Constraint
There is an additional option to define a Graph Rule sync constraint in the Advanced Section:
MAPPING_TABLE_CONNECTION
. This limits the objects to the one's available in the custom relationship table while pulling into LeanIX. Image below shows the constraint applied in line 115.

Line 115 shows the Advanced Graph Constraint applied
One example configuration for relations between Applications (persisted in cmdb_ci_appl) and IT Components (persisted in cmdb_software_product_model), where the mapping table has the name u_tech_stack_product_models
.
The column referencing to cmdb_ci_appl
has the name u_application
and the column referencing to cmdb_software_product_model
has the name u_software_model -
{
"active": true,
"masterSite": "FOREIGN",
"relationName": "relApplicationToITComponent",
"reverseRelationName": "relITComponentToApplication",
"typeFrom": "Application",
"typeTo": "ITComponent",
"automaticForeignTablesConfiguration": true,
"foreignFrom": "cmdb_ci_appl",
"foreignTo": "cmdb_software_product_model",
"referenceToField": "",
"foreignRelationMapping": {
"tableName": "u_tech_stack_product_models",
"referenceFrom": "u_application",
"referenceTo": "u_software_model",
"type": "MAPPING_TABLE"
}
}
Advanced Information
The following section details out specific use-cases while configuring the Integration.
Dot Walking
It is possible to dot walk
certain field mappings within the advanced configuration of the Integration. This is especially useful if it is required to pull information of some record from its corresponding referenced field.
In the following example, we know that Schedule & Track is linked to the Business Unit of Australia. To bring this information into LeanIX as a relationship, we will have to -
- Map the table which the reference field is from to a LeanIX Fact Sheet type. In this case it would be linking the LeanIX User Group Fact Sheet Type to the
business_unit
table. - Create a relationship descriptor of type
REFERENCE_FIELD
between the Applications and the User Group Fact Sheet Type using thebusiness_unit
reference field as seen below in the screenshot.

Business Unit field here is a field of type Reference
that is connected to the business_unit
table.
While the above method works, it is often times too much work just to bring in data from the field. Especially so if it is not required to have as a Relationship. In such a case, dot-walking functionality can be used to bring the name of the Business Unit into LeanIX as a string field.
Example - Bring data of reference fields into text fields in leanix
Use Dot Walking Functionality to get a Business Unit's name which is assigned to a Business Application.
- Step 1
Review the field in ServiceNow by clicking on the (i) icon

The (i) icon preview shows us the mini-view of the Australia record within the Business Unit table.
-
Step 2
We notice that thename
field is the one that stores the actual value of "Australia" in a string field. -
Step 3
Logically speaking another way to put this would bebusiness_unit.name
. Wherein, the first part before the "." is the name of the field within the main table. Subsequently, the second part after the "." is the name of the field within the referenced table where the value is stored. This is known as dot-walking. -
Step 4
Within LeanIX, this can be modeled within the advanced tab as follows -
"alias": {
"fieldType": "FOREIGN_FIELD",
"foreignFieldName": "business_unit.name",
"useNormalDirection": true
},

Configuration example within advanced tab
In the code example above, we are pulling the name of the attached business unit to the Application into the Alias field of LeanIX which for the purposes below we have renamed to "Business Unit".

Business Unit's name coming through to LeanIX through dot-walking.
Deletion Ratio
To avoid accidentally the deletion of of Fact Sheets or ServiceNow records because of an erroneous configuration, a deletion ratio threshold can be configured.

Line 184 - Deletion Ratio by default is 50.
If a maximumDeletionRatio
is specified and the number of items to delete / synchronized items is less than maximumDeletionRatio, than the synchronization is allowed to delete. maximumDeletionRatio
describes the ratio in percent.
By default it is set to 50%
. i.e. If the total candidate records for deletion are higher than 50%, then the Integration will not delete those records and output an error in the synclog to review.
Tip - Set the Deletion Ratio to lower or higher depending on the preferred result.
Be careful with the use of
strict mode
andmaximumDeletionratio
as it can lead to unintended permanent deletion of data.If the expectation is to delete majority/all of records on either side, then the deletionratio can be set to higher or 100%.
However, if the expectation is to carefully review each and every candidate for deletion within the synclog, the ratio can be set to 1. Further still, for the latter use-case we recommend to not have Strict Mode turned on to begin with as the synsclog will still show records that are not part of the source system, which inherently are deletion candidates.
Disable Partial Sync
In the section above for Partial Synchronization, the tip provided explained how to turn off Business Rules from the ServiceNow Instance to disable Partial Synchronization jobs of the type SERVICENOW_CHANGES
from being triggered.
On the LeanIX side however, there is a way where the Integration can be requested to skip the Partial Sync run to process even if they are being triggered. This is achieved by setting the following condition within the advanced tab configuration -
...
"skipPartialSyncCondition": {
"relCiIsBiggerThan": 1
},
By configuring this to 1
or a lower number, the Integration skips the partial sync from processing as the ServiceNow Instance is bound to have larger than 1
record in the cmdb_rel_ci
table.

Line 185-186
Subsequently, whenever a SERVICENOW_CHANGES
or a LEANIX_CHANGES
job is triggered, the sync log will show the following update -

Skipped Partial Sync
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 a table in ServiceNow.
Pre-Requisites
- Multiple Select Field with values in LeanIX
- Glide List 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.

Example MULTIPLE_SELECT
field in LeanIX with the values of legal
, sales
, finance
, and hr
.
Within ServiceNow however, there can be two types of list
fields -
- List fields that reference another ServiceNow Table

Example of a List field u_lix_multiple_select_bu_table
which references the business_unit
table in ServiceNow.
- List fields that do not refer another ServiceNow Table and have choice list defined

Example of a List field u_lix_multiple_select_no_reference
which does NOT refer to any table but has set choices listed.
To map both of these fields, Mapping Type of VALUE_MAPPING
is used -

VALUE_MAPPING
type dynamically understands if the LeanIX field is SINGLE_SELECT
or MULTIPLE_SELECT
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 value in LeanIX, this can be done for multiple records by exporting or by selectively copying the sys_id
as follows -

Copy or collect the sys_ids
of all the records that are to be mapped in LeanIX
These collected sys_ids
can be mapped to LeanIX as follows -

In this case, the ServiceNow side of the extra fields section expects for the sys_id
to match to when sending or pulling data to sync with the Multiple Select Fields.
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 -

Example of the sync from LeanIX sending the values to the highlighted glide list field.

Example of the sync from ServiceNow sending the values to the highlighted multiple select field in LeanIX.
Supported Lifecycle and Dates Sync Methods
Supported Lifecycle Sync Methods - Can only be configured from Advanced Tab
Case 1 - Lifecycle date values can be pulled from ServiceNow to LeanIX lifecycle fields
Case 2 - Lifecycle date values can be pushed from LeanIX to ServiceNow Date fields
Case 3 - String fields in LeanIX can pull the values of dates from ServiceNow
Case 4 - String fields in LeanIX can push the values of dates to ServiceNow
Case 1 -
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 (lifecycle/active
, lifecycle/phaseIn
) fields in LeanIX.
{
"lifecycle/plan": {
"fieldType": "FOREIGN_FIELD",
"foreignFieldName": "attested_date",
"useNormalDirection": false
},
"lifecycle/active": {
"fieldType": "FOREIGN_FIELD",
"foreignFieldName": "start_date",
"useNormalDirection": false
},
"release": {
"fieldType": "FOREIGN_FIELD",
"foreignFieldName": "attested_date",
"useNormalDirection": false
}
}
Case 2 -
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.
{
"lifecycle/plan": {
"fieldType": "FOREIGN_FIELD",
"foreignFieldName": "attested_date",
"useNormalDirection": true
}
Case 3 and 4 -
In this case, it is required to create a field of type STRING
which is rendered as a DATE
in LeanIX -

Create a new field of type STRING
rendered as Date
to sync with ServiceNow
Within the Integration configuration's Basic UI Tab, the fields are mapped as follows -

The newly created field mapped with a field in LeanIX of the type Date
.
Graph Constraint Hardware Filter
While utilizing the graph constraints APPLICATION_SAM_CONNECTION
or APPLICATION_HARDWARE_CONNECTION
additional parameters can be applied optionally to only retrieve Software Product Models that are linked to Operational Hardware CIs.
The hardwareFilter
key within the advanced configuration tab can contain a sysparm_query
for filtering the hardware table like the sysparm_query used in ServiceNow REST API.
Supported Params
Queries only containing
AND
andOR
operators (^ and ^OR in ServiceNow query notation are supported.
A valid example of filtering for the documentation would be:
"hardwareFilter": "operational_status=1^ORinstall_status=1"

Hardware Filter applied to only bring over Software Models which are attached to Hardware CIs that are Operational.
Read Relationship Table Iteratively
In some cases, it can be useful to iteratively load and process relationships during the synchronization. Thus, the readRelCiIterative
condition as seen above in Line 188
of the screenshot can be set to true
.
In case this is not specified or is set to null, the integrations reads the whole table into the memory to detect relations.
First Sync Behavior
The Integration on the first sync matches the records on the basis of the name
field in LeanIX and name
in ServiceNow. In the scenario 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.
Default Supported Configuration Mapping
The following JSON snippet is the default supported configuration that loads when setting up the Integration for the first time.
{
"factSheetSyncDescriptors": [
{
"active": true,
"factSheetType": "BusinessCapability",
"foreignType": "cmdb_ci_business_capability",
"masterSite": "LEANIX",
"strict": false,
"fieldMapping": {
"mapping": {
"name": {
"fieldType": "FOREIGN_FIELD",
"foreignFieldName": "name",
"useNormalDirection": true
},
"description": {
"fieldType": "FOREIGN_FIELD",
"foreignFieldName": "short_description",
"useNormalDirection": true
}
}
},
"filter": {
"facetFilters": [
{
"facetKey": "FactSheetTypes",
"operator": "OR",
"keys": [
"BusinessCapability"
]
}
],
"fullTextSearchTerm": null,
"ids": []
},
"snowTableFilter": null,
"syncConstraint": null
},
{
"active": true,
"factSheetType": "Application",
"foreignType": "cmdb_ci_business_app",
"masterSite": "LEANIX",
"strict": false,
"fieldMapping": {
"mapping": {
"name": {
"fieldType": "FOREIGN_FIELD",
"foreignFieldName": "name",
"useNormalDirection": true
},
"lifecycle": {
"fieldType": "VALUE_MAPPING",
"foreignFieldName": "operational_status",
"useNormalDirection": true,
"valueMapping": {
"active": "1",
"phaseIn": "5",
"phaseOut": "2",
"endOfLife": "6"
}
},
"description": {
"fieldType": "FOREIGN_FIELD",
"foreignFieldName": "short_description",
"useNormalDirection": true
},
"businessCriticality": {
"fieldType": "VALUE_MAPPING",
"foreignFieldName": "business_criticality",
"useNormalDirection": true,
"valueMapping": {
"missionCritical": "high",
"businessCritical": "medium",
"businessOperational": "low",
"administrativeService": "low"
}
},
"subscriptions/RESPONSIBLE/IT Owner": {
"fieldType": "SUBSCRIPTION",
"foreignFieldName": "it_application_owner",
"useNormalDirection": true,
"referenceTable": "sys_user"
},
"subscriptions/RESPONSIBLE/Business Owner": {
"fieldType": "SUBSCRIPTION",
"foreignFieldName": "owned_by",
"useNormalDirection": true,
"referenceTable": "sys_user"
}
}
},
"filter": {
"facetFilters": [
{
"facetKey": "FactSheetTypes",
"operator": "OR",
"keys": [
"Application"
]
}
],
"fullTextSearchTerm": null,
"ids": []
},
"snowTableFilter": null,
"syncConstraint": null
},
{
"active": true,
"factSheetType": "ITComponent",
"foreignType": "cmdb_hardware_product_model",
"masterSite": "FOREIGN",
"strict": false,
"fieldMapping": {
"mapping": {
"name": {
"fieldType": "FOREIGN_FIELD",
"foreignFieldName": "name",
"useNormalDirection": true
},
"category": {
"fieldType": "FIXED_VALUE",
"foreignFieldName": "",
"useNormalDirection": true,
"fixedValue": "hardware"
}
}
},
"syncConstraint": {
"graphRules": [
"IN_USE_HARDWARE_CONNECTION"
]
},
"filter": null,
"snowTableFilter": {
"filter": null
}
},
{
"active": true,
"factSheetType": "ITComponent",
"foreignType": "cmdb_software_product_model",
"masterSite": "FOREIGN",
"strict": false,
"fieldMapping": {
"mapping": {
"name": {
"fieldType": "FOREIGN_FIELD",
"foreignFieldName": "name",
"useNormalDirection": true
},
"category": {
"fieldType": "FIXED_VALUE",
"foreignFieldName": "",
"useNormalDirection": true,
"fixedValue": "software"
}
}
},
"syncConstraint": {
"graphRules": [
"IN_USE_SAM_CONNECTION"
]
},
"filter": null,
"snowTableFilter": {
"filter": null
}
},
{
"active": true,
"factSheetType": "TechnicalStack",
"foreignType": "cmdb_model_category",
"masterSite": "FOREIGN",
"strict": false,
"fieldMapping": {
"mapping": {
"name": {
"fieldType": "FOREIGN_FIELD",
"foreignFieldName": "name",
"useNormalDirection": true
}
}
},
"syncConstraint": {
"graphRules": []
},
"filter": null,
"snowTableFilter": null
}
],
"relationSyncDescriptors": [
{
"active": true,
"masterSite": "LEANIX",
"relationName": "relToParent",
"reverseRelationName": "relToChild",
"typeFrom": "BusinessCapability",
"typeTo": "BusinessCapability",
"automaticForeignTablesConfiguration": true,
"foreignFrom": "cmdb_ci_business_capability",
"foreignTo": "cmdb_ci_business_capability",
"referenceToField": "parent",
"foreignRelationMapping": {
"type": "REFERENCE_FIELD"
}
},
{
"active": true,
"masterSite": "LEANIX",
"relationName": "relBusinessCapabilityToApplication",
"reverseRelationName": "relApplicationToBusinessCapability",
"typeFrom": "BusinessCapability",
"typeTo": "Application",
"automaticForeignTablesConfiguration": true,
"foreignFrom": "cmdb_ci_business_capability",
"foreignTo": "cmdb_ci_business_app",
"referenceToField": "",
"foreignRelationMapping": {
"type": "CMDB_REL_CI",
"relationName": "Provided By::Provides",
"query": "parent.sys_class_name=cmdb_ci_business_capability^child.sys_class_name=cmdb_ci_business_app^typeISNOTEMPTY"
}
},
{
"active": true,
"masterSite": "FOREIGN",
"relationName": "relITComponentToTechnologyStack",
"reverseRelationName": "relTechnologyStackToITComponent",
"typeFrom": "ITComponent",
"typeTo": "TechnicalStack",
"automaticForeignTablesConfiguration": true,
"foreignFrom": "cmdb_software_product_model,cmdb_hardware_product_model",
"foreignTo": "cmdb_model_category",
"referenceToField": "cmdb_model_category",
"foreignRelationMapping": {
"type": "REFERENCE_FIELD"
}
},
{
"active": true,
"masterSite": "FOREIGN",
"relationName": "relApplicationToITComponent",
"reverseRelationName": "relITComponentToApplication",
"typeFrom": "Application",
"typeTo": "ITComponent",
"automaticForeignTablesConfiguration": true,
"foreignFrom": "cmdb_ci_business_app",
"foreignTo": "cmdb_software_product_model,cmdb_hardware_product_model",
"referenceToField": "",
"foreignRelationMapping": null
}
],
"version": 1,
"lastModified": "2022-05-13T18:06:33.429420366Z",
"maximumDeletionRatio": 50,
"skipPartialSyncCondition": {
"relCiIsBiggerThan": 250000
},
"readRelCiIterative": null,
"hardwareFilter": "",
"oauth": null
}
Updated about 21 hours ago