Advanced Configuration

Once the LeanIX app in ServiceNow is configured, we can get started with the implementation on the LeanIX workspace.

The Advanced Configuration 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

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.

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.

clientSecret is encyrpted upon saving and will not be visible.

Relation Mapping Behaviour

There are some settings on the behaviour of the Relation Mapping, that can only be applied using the Advanced Configuration.

General Flags

Key (Line Number)Description
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
queryDefines the constraint to use for the Integration while processing relationships from CMDB_REL_CI mapping type.

📘

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

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

There are no additional flags for the REFERENCE_FIELD mapping type.

MAPPING_TABLE

👍

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

Line 115 shows the Advanced Graph Constraint applied

Other Settings

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.

Line 184 - Deletion Ratio by default is 50.

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.

Line 185-186

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

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"
Hardware Filter applied to only bring over Software Models which are attached to Hardware CIs that are Operational.

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.

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
}