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

👍

Access

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

Navigation

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

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

Credentials Tab

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

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.

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, please feel free and contact the LeanIX Support team 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.

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

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.

Manual Full Sync

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

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

🚧

Sync Logging Time

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

Scheduled Full Sync

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

Full Sync is scheduled to run at 04:00 AM UTC for all the LeanIX Instances.

📘

Time Zone

Click here to see time zone conversions.

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 factsheet or a record is created, updated or deleted in the systems. For ServiceNow, the LeanIX application installs a couple of Business Rules to track these events and trigger a sync as seen here -

👍

Tip - Disable Business Rules in ServiceNow for Operational Tables

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

Field Mapping

For each specified Factsheet 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 factaheet's field to an ServiceNow table attribute in its form and direction.

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

Mapping Type

Mapping Types are described as follows -

Field Types in ServiceNow are explained in their documentations..

Factsheet Field

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

Foreign Field

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 -

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.

👍

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 -

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

Only the VALUES section is required for the mapping -

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

❗️

1 : n Value Mapping support

Only attaching multiple fields in SINGLE_SELECT field to 1 VALUE to target system is supported.

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, factsheets can be filtered through a the same methods of Inventory filtering to only allow a certain subsection of factsheets to go to the ServiceNow table in sync.

It can be done by clicking on the three ... on the descryptor you want to filter and selecting Edit Filters.

Once selected, the Inventory view opens up allowing to set specific filters on the basis of any filterable property for the factsheet type.

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.

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

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

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

📘

Visibility of available filters for your integration user

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

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

Graph Rule Constraints

❗️

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.

Various types of Graph Rules are explained as follows -

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.

Preset Relationships

The following relationships have a hardcoded logic in them in the backend and are loaded automatically as part of the default supported configuration.

*Relationship name is relevant as the relationship will be created as per the name mentioned here.

🚧

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

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 -

📘

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

Subsequently, this newly created relationship will show up in the Advanced tab as follows -

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.

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.

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

Additional Information

The following section details out specific use-cases while configuring the Integration.

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.

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.

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

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 - String fields in LeanIX can pull the values of dates from ServiceNow
Case 3 - 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
 }
}

❗️

Sending Lifecycle Date Values to Attributes of type Date in ServiceNow is currently not supported

e.g. Sending the date value stored within lifecycle/active field from LeanIX to an attribute of type Date in ServiceNow is not supported at the moment.

Case 2 and 3 -

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

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

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"

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 factsheet is created in LeanIX or a new record is created in ServiceNow.