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.

SectionDetails
NavigationQuick Overview on how to get to the configuration and definitions of each tabs.
Client ConfigurationInformation on how to setup credentials created on the ServiceNow side.
SynchronisationOverview on sync frequency, types of syncs and how to read them.
Field MappingDescription on all possible field mapping types and supported ServiceNow attributes.
Sync FiltersDescription on all possible ways to filter on the data in sync with the Integration
RelationshipsDefines the concept of relationships and the preset relationships loaded as part of the Default Supported Configuration
Supported Custom Relationship TypesDefines the methods through which custom relationships can be set with the Integration
Additional InformationThe 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'.

3496

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

3496

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.

3584

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.

3496

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.

3584

Credentials Section

KeyType
1ServiceNow URL section to input url of the instance which is to be connected with the workspace. e.g. <https://clientdomain.service-now.com>
2Username section to input the username of the LeanIX Integration user created within the ServiceNow Instance
3In 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.
4Managing User dropdown allows to utilize a technical user on the LeanIX workspace to run the Integration. This is useful for auditing purposes
5Use 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"
    }
3496

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 TypeSync Logging NameDetails
Full SyncFULL_SYNCSync of all the configured mapping that takes place at a set schedule.
Manual Full SyncFULL_SYNC_MANUALSync of all configured mapping that gets triggered manually by the LeanIX admin
Partial Sync - ServiceNowSERVICENOW_CHANGESSync of changes due to an event trigger of Business Rules from ServiceNow's side.
Partial Sync - LeanIXLEANIX_CHANGESSync 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.

3496

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 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 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 -

3496

Business Rules installed by the LeanIX app that look for events to trigger a Partial Sync

Partial Sync Supported TablesBusiness 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_ciCI 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 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.

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

3496

Mapping Type dropdown

Mapping Types are described as follows -

Mapping TypeDescriptionMandatory FieldsSupported SN Attribute TypeSupported LeanIX Field Type
FOREIGN_FIELDMaps 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
URLUsed to map the url of the LeanIX Fact Sheet to the foreign object.Foreign FieldStringn/a
FIXED_VALUEOnly to be used to set a constant string value to be sent on every synchronised object.Foreign FieldStringn/a
VALUE_MAPPINGUsed to map fields with multiple choices.Fact Sheet Field
Foreign Field
Choice (1:1 mapping only)* certain exceptions explained belowSingle Select, Multiple Select (See Advanced Information section)
SUBSCRIPTIONUsed to map subscription values between systems.Fact Sheet Field (Subscription Type)Reference Fields that directly refer to the sys_user or sys_user_grouptable.
e.g. business_owner field.

Glide List fields that directly refer to the sys_user table.
Subscriptions Tab data only
ARCHIVED_STATUS_MAPPINGOnly Allowed when LeanIX is the source.

If a Fact Sheet is archived, then a special value is written to ServiceNow
Foreign FieldChoice.
e.g. operational_status field updated with 6. Which has the label of Retired.
n/a
TAG_GROUP_FIELDUsed to map tag group fieldsFact Sheet Field (Tags only / Other Tags)
Foreign Field
StringTag Groups, Other Tags
TAG_GROUP_MAPPINGUsed to map tag group with multiple tags within them.Fact Sheet Field (Tags Groups)
Foreign Field
ChoiceTag Groups
EXTERNAL_IDThis type is used to map a LeanIX ExternalId field to a ServiceNow column.Fact Sheet Field (Tags Groups)
Foreign Field
StringExternal ID Fields

Field Types in ServiceNow are explained in their documentations..

Fact Sheet Field

3496

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

3496

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 -

3496

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.

3496

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 -

3496

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) -

3496

Select - Show Choice List

Only the VALUES section is required for the mapping -

3496

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

3496

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.

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.

3496

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.

3496

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 -

3496

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 the filter_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.

3496

Graph Rule Constraints

Various types of Graph Rules are explained as follows -

Graph RuleDefinitionRequired Active Mapping and Plugin
APPLICATION_SAM_CONNECTIONSynchronise 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_CONNECTIONSynchronise 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_CATEGORYSynchronise 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_CONNECTIONSynchronise 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_CONNECTIONSynchronise this Hardware Product Model, if a connection to a Hardware exists.IT Component - Hardware - cmdb_hardware_product_model
APPLICATION_SOFTWARE_MANAGEMENT_MODEL_CONNECTIONSynchronise 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_CONNECTIONSynchronise 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_CONNECTIONSynchronises 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.

CaseDescriptionSource of TruthAction
Case 1.Relationship between 2 Fact Sheets that are both linked to ServiceNowServiceNow , LeanIXDeletions 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'tServiceNow, LeanIXDeletions 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 -

3584

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.

3584

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 TypeRelationship name*To Fact Sheet TypeDescriptionAdvanced Configuration RequiredSource
ApplicationIT ComponentsIT ComponentPulls 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.
NoServiceNow
ITComponentTech CategoriesTech CategoryPulls 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 ComponentsNoServiceNow
Business CapabilityApplicationsApplicationPushes 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.NoLeanIX
Business CapabilityParentBusiness CapabilityPushes parent-child hierarchies created within the Business Capability Fact Sheets in LeanIX to ServiceNow using the parent reference field.NoLeanIX

*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 CaseSupported SourceforeignRelationMappingAdvanced Configuration
Relationship between two ServiceNow tables using cmdb_rel_ci table.ServiceNow & LeanIXCMDB_REL_CIRequired
Relationship between two ServiceNow tables using a Reference Field.ServiceNow & LeanIXREFERENCE_FIELDRequired
Relationship between two ServiceNow tables using a Glide List field type.ServiceNow & LeanIXREFERENCE_FIELDRequired
Relationship between two ServiceNow tables using a Mapping table and Reference Fields.ServiceNowMAPPING_TABLERequired

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)DescriptionVisiblility 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 happenYes, 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-186No
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 happenNo
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 and foreignTo fields with the ServiceNow tables used for the corresponding typeFrom and typeTo Fact Sheet types in Sync Descriptors.This can be disabled to allow manual editing of foreign tables.

For this, set the automaticForeignTablesConfiguration field to false (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.

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 -

3496

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.

LineTypeDescription
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 Direction

Only 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.

3496

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 the business_unit reference field as seen below in the screenshot.
3584

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
3584

The (i) icon preview shows us the mini-view of the Australia record within the Business Unit table.

  • Step 2
    We notice that the name 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 be business_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
},
3584

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".

3584

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.

3496

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 and maximumDeletionratio 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.

3496

Line 185-186

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

3496

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.
3584

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
3584

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
3496

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 -

3584

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 -

3584

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 -

3584

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 -

3584

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

3584

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 -

3496

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 -

3496

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 and OR 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"
3496

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
}