ServiceNow Integration

Fundamentals about LeanIX integration to ServiceNow

Knowledge

Before embarking the LeanIX ServiceNow integration, please make sure you or a colleague/ consultant is available and has fundamental knowledge about ServiceNow which contains:

  • Add users, groups, and roles
  • Manage data with tables, the configuration management database (CMDB)
  • Protect ServiceNow data

It would be good your knowledge covers the key topics of the ServiceNow certification https://www.servicenow.com/services/training-and-certification/system-administration.html.

Introduction / Synchronisation Mechanism

Generally speaking, ServiceNOW (SN) and LeanIX's have a lot in common. Both maintain tables and relations between them and offer a browser based application for viewing and updating those tables.

For synchronisation purposes every mapping between tables in both systems defines the following:

  • Name of table in LeanIX.
  • Name of table in SN.
  • Whether SN or LeanIX holds the master record.
  • Whether one should use the 'strict' mode, i.e. whether unsynchronised slave objects shall be deleted right away.
  • Whether there are any synchronisation constraints, e.g. only synchronise applications with a specific lifecycle status or only those software product models which are actually installed on a server belonging to a managed business service.
  • For every field to be held in sync:
    • type of the mapping (see types of mapping further below)
    • name of field in LeanIX (if applicable)
    • name of field in SN (if applicable)
    • whether the attribute is to be synced from master to slave object or vice versa.
    • How values are being mapped (as is or explicit mapping of one value to another)

Do not synchronise huge tables to LeanIX

LeanIX is supposed to be 'lean' - it makes no sense to synchronise tables with hundreds of thousands of entries (or even millions) to LeanIX. All the advantages of LeanIX will be nullified if too many objects clutter reports and the inventory.

Based on that the configuration can be saved, if the configuration is in a valid json format (don't worry, the editor will tell you so if the syntax is wrong).

The synchronisation mechanism works independently of state information, i.e., the integration code only gets the information that a particular object (uniquely identified by table name and sys_id or type of fact sheet and UUID respectively) has changed (created, updated, deleted) and then figures out by itself what to do. The sync mechanism retrieves (if not already done) slave and master object and checks, whether a change is necessary. Afterwards, relations are being checked in LeanIX and corrected if necessary.

LeanIX will not create a copy of any tables that are not being synchronised to LeanIX within the configuration. Objects that are not in synchronisation even though the table itself is synchronised (due to some sync constraint) won't be transferred to LeanIX either.

Settings from LeanIX Side:

Prepare a LeanIX workspace for the integration with ServiceNow

First, you need to make sure, the custom features are active. A minimum config of custom features is shown here:

Minimal Features

Though it might not be necessary to have a 'pathfinder.productive' workspace with a 'customizing.model' feature active to synchronise, it is highly recommended, as setting the former feature later, changes URLs and the latter is required to add the serviceNowId as external ID to the data model.

In order to store the externalID on LeanIX objects, the data model of the workspace needs to be extended. Add the following snippet to the part "externalIdFields" : { ... }:

        "serviceNowExternalId": {
            "quickSearch": true,
            "fullTextSearch": true,
            "urlTemplate": null,
            "uniqueFactSheet": false,
            "autoIncrement": false,
            "readOnly": true,
            "forFactSheets": [
                "ITComponent",
                "TechnicalStack",
                "Application"
            ]
        }

Please remove or add fact sheet types as you need it - the snippet shows the default configuration.

Also please make sure to add any fields to map to in SN and to LeanIX's data model, e.g. it has proven to be useful to add the LeanIX URL and ID to SN items that are being synced.

Lastly, create a new user in LeanIX under whose credentials the synchronisation shall be run and create an API-token with the new user. The token will be required in the SN configuration later on.

API-Token

Do not forget to copy the token content to a secure location, as you will need it later.
LeanIX suggest to use an expiration date that is not too long, since it is good practice to change these credentials within a defined time period.

Settings from ServiceNow Side:

Prepare ServiceNow for the integration

To get the communication between LeanIX and ServiceNow running, the LeanIX Integration app is required which is available in ServiceNow's AppStore. Please install the app from the AppStore.

Install app from ServiceNow Store

  • Click here to find the appropriate application.
  • Select the option to purchase the application. Make sure to select the most recent version of the app available for your version of ServiceNow.
  • Log in to your ServiceNow Enterprise account as an admin.
  • Open the System Applications → Applications module and click the Downloads tab to view the LeanIX Integration application.
  • Click Install on the 'LeanIX Integration' application.

Configure the app 'LeanIX Integration'

After successful installation, you will have a new menu item in SN:

ServiceNOW menu after LeanIX Integration has been installed.

ServiceNOW menu after LeanIX Integration has been installed.

In the 'LeanIX Properties', you are required to add an API-token, which you created in the previous step, and a 'host_name', e.g. 'app.leanix.net' or 'us.leanix.net'. On default, the 'log_level' is set to 'INFO'. Setting the 'log_level' to 'DEBUG' is recommended only to troubleshoot and not in a productive environment.

ServiceNow properties configuration

ServiceNow properties configuration

Important when cloning ServiceNow Instances

Do not move/use LeanIX Integration Property : API Token on two different ServiceNow Instances, this will result in unexpected behaviour.
Add LeanIX Integration Properties to data preservers during the Cloning activity to avoid any issues. Link provides information on how to setup data preservers : ServiceNow_link

LeanIX Integration in SN is a scoped application. If you want to have the right to edit the configuration, you need to add your user to the role x_lixgh_leanix_int_admin.

User Role x_lixgh_leanix_int_admin and API-Token

Be careful with these permissions, as every user with that role is able to see the API-token and with it can do everything, the synchronisation user is able to do in LeanIX.

If you ever suspect that the API-token is compromised, simply log in as the synchronisation user, invalidate the API-token and create a new one. Next enter the token in the configuration of the LeanIX integration application in SN.

To confirm everything is working, check whether you can trigger a change from SN and check the SyncLog for a partial synchronisation.

Setup an integration user and ACLs

If you specify that data is synchronised from LeanIX to SN, then the user that you specify in the 'Integrations' part in LeanIX's admin section of the workspace requires the application role x_lixgh_leanix_int.admin and write access to the tables at hand. If LeanIX is to be master side for the synchronisation of a table, the right to 'create' and 'write' is necessary as well. If you decide to enable the strict mode (i.e. having unsynchronised slave objects deleted), then the permission to 'delete' is necessary as well.

Create an Integration user with limited access (recommended)

Create a new integration user, for example leanix.integration, mark 'Web service access only' as 'True'.

Roles required for Version : 1.0.12 and above and in case you do not want to create separate ACLs in ServiceNow

Role
Table and Permissions Provided by Role
Reason

x_lixgh_leanix_int.admin

x_lixgh_leanix_int_log(Read,Create,Write,Delete)

Access Application Endpoints

filter_global OR filter_group

sys_filter

Read Global/Group Filters from ServiceNow for a specific Table. Check Filter Section for more details on how to configure filters.
By Default : Only filters created by Integration user will be available.

asset

product_model, cmdb_model_category

Read and Write Access to Model Category and Models

Option to skip for Version >= V1.0.12

You can skip the below setup in ServiceNow for LeanIX Integration V1.0.12 and above as the default roles are already added except for asset and filter.

Roles required for Version < 1.0.12

Role
Table and Permissions Provided by Role
Reason

x_lixgh_leanix_int.admin

x_lixgh_leanix_int_log(Read,Create,Write,Delete)

Access Application Endpoints

personalize_choices

sys_choice(Read)

Pre-population and Validation of choices on LeanIX

filter_global OR filter_group

sys_filter

Read Global/Group Filters from ServiceNow for a specific Table. Check Filter Section for more details on how to configure filters.
By Default : Only filters created by Integration user will be available.

personalize_dictionary

sys_dictionary(Read)

Can personalize dictionary entries and labels.
LeanIX Integration App requires read Access to fetch fields for a specific table from sys_dictionary and provide as choices once table is provided.
Alternative can be create Read ACL for sys_dictionary.none and sys_dictionary.* with role "x_lixgh_leanix_int.admin"

Grant access to all target tables

To grant the LeanIX Integration user access to all relevant tables were information needs to be written, there are two variants of access configuration: Either add two additional ACL's to the base Configuration Item table (cmdb_ci) and assign a role for asset management OR set explicit ACLs on each target table.

Variant A) record ACLs on cmdb_ci table and role for asset management

Assign the role asset to your synchronization user, eg. leanix.integration.

Ensure these ACLs are assigned:

Table Name
Operations
Role to add
comment

cmdb_ci

create, write

x_lixgh_leanix_int.admin

cmdb_sam_sw_install

read

x_lixgh_leanix_int.admin

only required if SAM module should be used

x_lixgh_leanix_int_log

create, read, write, delete

x_lixgh_leanix_int.admin

just check, should already be added by app

If you want to limit the access of your cmdb_ci's ACLs in a way that only your target tables accept create and write access, you can add JavaScript code to your ACL. Therefore when creating the record ACL you must check the Advanced checkbox and add additional rules as JavaScript.
The example below checks, that only modifications to cmdb_ci_service are allowed. If the variable answer is true the ACL will pass, otherwise the ACL will reject.

// Limits access only to table cmdb_ci_service
var targetTableName = current.sys_meta.name;
answer = (targetTableName == 'cmdb_ci_service');

Here is a screenshot of the described scenario:

Sample JavaScript, which limits the write access to only 'cmdb_ci_service' table.

Sample JavaScript, which limits the write access to only 'cmdb_ci_service' table.

Variant B) record ACLs on all target tables only

Only assign the following record ACLs in case that the solution above is not configured:

Table Name
Operations
Role to add
comment

cmdb_ci_service

create, write

x_lixgh_leanix_int.admin

cmdb_sam_sw_install

read

x_lixgh_leanix_int.admin

only required if SAM module should be used

cmdb_hardware_product_model

write

x_lixgh_leanix_int.admin

cmdb_software_product_model

write

x_lixgh_leanix_int.admin

x_lixgh_leanix_int_log

create, read, write, delete

x_lixgh_leanix_int.admin

just check, should already be added by app

Adding a record ACL to a target table like cmdb_ci_service, may change the access behavior. When specifying a record ACL to a table, the new ACL may mask ACLs from base tables. Therefore it is possible that a user has write access by an ACL on cmdb_ci but afterwards this will be denied by the ACLs on cmdb_ci_service.

Pitfalls on user adapted SN systems

Also, one should find out what 'Business Rules' are configured in SN on the tables that are being synchronised and whether they conflict with the synchronisation process.

Business Rules and Uniqueness

Find out what 'Business Rules' are configured in SN on the tables that are being synchronised and whether they conflict with the synchronisation process, e.g. one customer had a business rule in place that prohibited the creation of objects with the exact same name in one of the tables to synchronise. This itself is not a problem: In LeanIX fact sheet names are unique per fact sheet type as well, BUT: LeanIX compares names by ignoring any letter cases. SN by default checks for exact matching including the upper and lower case of characters.

Custom Deletion Rules

If you modified SN's behaviour on what happens with reference fields upon deletion of reference objects, please contact LeanIX support to get a customised version of the LeanIX integration app on the ServiceNOW platform.

Configure the LeanIX for integration

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

Then navigate to 'Administration' > 'Integrations' and select the ServiceNOW integration by clicking on 'Configure'.

LeanIX integration page

LeanIX integration page

General synchronization configuration

Fill in the credentials under which the integration shall access ServiceNOW's REST API, the address to the SN instance and check the 'Active' box.

LeanIX ServiceNow integration, Credentials page

LeanIX ServiceNow integration, Credentials page

Short event buffering

In case the check box 'Short event buffering' is activated, all changes in LeanIX and SN will be synchronized immediately. This setting increases is useful for testing or demo purposes, but it will increase the amount of CPU usage and network traffic and should be disable for production workspaces.

As soon as you click 'Save', LeanIX's integration will check the access to SN and all configured tables and columns in your SN instance. If everything goes well, you should see a green Toastr in the upper right corner. If an error occurs, please check your credentials, whether the account you entered is allowed to access the REST API of SN, roles assigned to your your synchronization user (eg. leanix.integration) and whether read access to configured tables is granted.

Detailed Fact Sheet and SN's table mapping configuration

When this has been successful, you can change to the next tab called 'Basic' to define the synchronization of Fact Sheet types against SN tables and the way each Fact Sheet field must be synchronized to SN table fields.

LeanIX ServiceNow integration, empty Basic page

LeanIX ServiceNow integration, empty Basic page

A typical configuration can look like this:

LeanIX ServiceNow integration, Basic page used for mapping configuration

LeanIX ServiceNow integration, Basic page used for mapping configuration

JSON configuration

Sometimes it will be useful to prepare a customer's configuration using a json editor and send this configuration to the admin who can configure it easily via copy-and-past. Therefore a third tab called 'Advanced' will be visible, when the Feature 'integration.servicenow.json' is enabled.

LeanIX ServiceNow integration, Advanced page showing the configuration in a json format

LeanIX ServiceNow integration, Advanced page showing the configuration in a json format

Advanced configuration

  • In case you do not see the Advanced tab in your configuration, please feel free and contact the LeanIX customer success team to activate this feature.
  • If you clear out the configuration in the json editor, just put in an empty json document '{}', then a default config is restored you can use as a good starting point.

Configuration of tables and fields

Overview to the default mapping

The default mapping, which is created for new configurations, maps in this way:

  • Applications are mapped to Business Services
  • Hardware Product Models are mapped to IT-Components
  • Software Product Models are mapped to IT-Components and
  • Model Categories are mapped to Technical Stacks
simplified overview of the default mapping between LeanIX and ServiceNow

simplified overview of the default mapping between LeanIX and ServiceNow

The configuration for this scenario in json editor looks like this:

{
	"factSheetSyncDescriptors": [
		{
			"active": true,
			"factSheetType": "Application",
			"foreignType": "cmdb_ci_service",
			"masterSite": "LEANIX",
			"strict": false,
			"fieldMapping": {
				"mapping": {
					"id": {
						"fieldType": "FOREIGN_FIELD",
						"foreignFieldName": "u_leanix_id",
						"useNormalDirection": true
					},
					"status": {
						"fieldType": "ARCHIVED_STATUS_MAPPING",
						"foreignFieldName": "operational_status",
						"fixedValue": "103",
						"useNormalDirection": true
					},
					"release": {
						"fieldType": "FOREIGN_FIELD",
						"foreignFieldName": "version",
						"useNormalDirection": true
					},
					"lifecycle": {
						"fieldType": "VALUE_MAPPING",
						"foreignFieldName": "operational_status",
						"valueMapping": {
							"active": "100",
							"phaseIn": "101",
							"phaseOut": "102",
							"endOfLife": "103"
						},
						"useNormalDirection": true
					},
					"description": {
						"fieldType": "FOREIGN_FIELD",
						"foreignFieldName": "short_description",
						"useNormalDirection": true
					},
					"businessCriticality": {
						"fieldType": "VALUE_MAPPING",
						"foreignFieldName": "busines_criticality",
						"valueMapping": {
							"missionCritical": "1 - most critical",
							"businessCritical": "2 - somewhat critical",
							"businessOperational": "3 - less critical",
							"administrativeService": "4 - not critical"
						},
						"useNormalDirection": true
					},
					"subscriptions/IT Owner": {
						"fieldType": "SUBSCRIPTION_ROLE_MAPPING",
						"foreignFieldName": "supported_by",
						"useNormalDirection": true
					},
					"subscriptions/Bus Owner": {
						"fieldType": "SUBSCRIPTION_ROLE_MAPPING",
						"foreignFieldName": "owned_by",
						"useNormalDirection": true
					},
					"subscriptions/IT Steward": {
						"fieldType": "SUBSCRIPTION_ROLE_MAPPING",
						"foreignFieldName": "assigned_to",
						"useNormalDirection": true
					},
					"subscriptions/Bus Steward": {
						"fieldType": "SUBSCRIPTION_ROLE_MAPPING",
						"foreignFieldName": "managed_by",
						"useNormalDirection": true
					},
					"_no_mapping_field_u_leanix_url": {
						"fieldType": "URL",
						"foreignFieldName": "u_leanix_url",
						"useNormalDirection": true
					},
					"subscriptions/Notification Distribution List": {
						"fieldType": "SUBSCRIPTION_ROLE_USERGROUP_MAPPING",
						"foreignFieldName": "support_group",
						"useNormalDirection": true
					}
				}
			},
			"filter": {
				"facetFilters": [
					{
						"facetKey": "FactSheetTypes",
						"operator": "OR",
						"keys": [
							"Application"
						]
					},
					{
						"facetKey": "lifecycle",
						"operator": "OR",
						"keys": [
							"plan",
							"phaseIn",
							"active"
						],
						"dateFilter": {
							"from": null,
							"to": null,
							"type": "TODAY"
						}
					}
				],
				"fullTextSearchTerm": null,
				"ids": []
			},
			"snowTableFilter": null
		},
		{
			"active": true,
			"factSheetType": "ITComponent",
			"foreignType": "cmdb_hardware_product_model",
			"masterSite": "FOREIGN",
			"strict": false,
			"fieldMapping": {
				"mapping": {
					"id": {
						"fieldType": "FOREIGN_FIELD",
						"foreignFieldName": "u_leanix_id",
						"useNormalDirection": false
					},
					"alias": {
						"fieldType": "FOREIGN_FIELD",
						"foreignFieldName": "u_alias",
						"useNormalDirection": false
					},
					"release": {
						"fieldType": "FOREIGN_FIELD",
						"foreignFieldName": "model_number",
						"useNormalDirection": true
					},
					"category": {
						"fieldType": "FIXED_VALUE",
						"foreignFieldName": "",
						"fixedValue": "hardware",
						"useNormalDirection": true
					},
					"description": {
						"fieldType": "FOREIGN_FIELD",
						"foreignFieldName": "comments",
						"useNormalDirection": false
					},
					"snowUModelId": {
						"fieldType": "FOREIGN_FIELD",
						"foreignFieldName": "u_model_id_bdna",
						"useNormalDirection": true
					},
					"technopediaId": {
						"fieldType": "TECHNOPEDIA_MAPPING",
						"foreignFieldName": "u_model_id_bdna",
						"useNormalDirection": true,
						"valuePrefix": "hw_"
					},
					"_no_mapping_field_u_leanix_url": {
						"fieldType": "URL",
						"foreignFieldName": "u_leanix_url",
						"useNormalDirection": false
					}
				}
			},
			"syncConstraint": {
				"graphRules": [
					"IN_USE_HARDWARE_CONNECTION",
					"MODEL_CATEGORY"
				]
			},
			"filter": null,
			"snowTableFilter": null
		},
		{
			"active": true,
			"factSheetType": "ITComponent",
			"foreignType": "cmdb_software_product_model",
			"masterSite": "FOREIGN",
			"strict": false,
			"fieldMapping": {
				"mapping": {
					"id": {
						"fieldType": "FOREIGN_FIELD",
						"foreignFieldName": "u_leanix_id",
						"useNormalDirection": false
					},
					"alias": {
						"fieldType": "FOREIGN_FIELD",
						"foreignFieldName": "u_alias",
						"useNormalDirection": false
					},
					"release": {
						"fieldType": "FOREIGN_FIELD",
						"foreignFieldName": "version",
						"useNormalDirection": true
					},
					"category": {
						"fieldType": "FIXED_VALUE",
						"foreignFieldName": "",
						"fixedValue": "software",
						"useNormalDirection": true
					},
					"description": {
						"fieldType": "FOREIGN_FIELD",
						"foreignFieldName": "comments",
						"useNormalDirection": false
					},
					"snowUModelId": {
						"fieldType": "FOREIGN_FIELD",
						"foreignFieldName": "u_model_id_bdna",
						"useNormalDirection": true
					},
					"technopediaId": {
						"fieldType": "TECHNOPEDIA_MAPPING",
						"foreignFieldName": "u_model_id_bdna",
						"useNormalDirection": true,
						"valuePrefix": "sw_"
					},
					"_no_mapping_field_u_leanix_url": {
						"fieldType": "URL",
						"foreignFieldName": "u_leanix_url",
						"useNormalDirection": false
					}
				}
			},
			"syncConstraint": {
				"graphRules": [
					"IN_USE_SAM_CONNECTION",
					"MODEL_CATEGORY"
				]
			},
			"filter": null,
			"snowTableFilter": null
		},
		{
			"active": true,
			"factSheetType": "TechnicalStack",
			"foreignType": "cmdb_model_category",
			"masterSite": "FOREIGN",
			"strict": false,
			"fieldMapping": null,
			"filter": null,
			"snowTableFilter": null
		}
	],
	"relationSyncDescriptors": [
		{
			"active": true,
			"masterSite": "FOREIGN",
			"relationName": "relApplicationToITComponent",
			"reverseRelationName": "relITComponentToApplication",
			"typeFrom": "Application",
			"typeTo": "ITComponent"
		},
		{
			"active": true,
			"masterSite": "FOREIGN",
			"relationName": "relTechnologyStackToITComponent",
			"reverseRelationName": "relITComponentToTechnologyStack",
			"typeFrom": "TechnicalStack",
			"typeTo": "ITComponent"
		}
	]
}

To scope or not to scope

As you can see from the default configuration, some fields with the prefix 'u' have been added to SN's schema. These are only available in the global application scope. The LeanIX integration application on SN itself works in a scope and does not add those field by default (they would have a prefix 'x' anyway). It is up to you, whether you want to define the fields in the application scope or your global scope and you can configure it in the configuration json file.

The 'Edit Mapping' dialog

Field mapping

For each specified Fact Sheet type and SN table, the mapping of fields can be specified by pressing the 'Edit Mapping' button, which opens the 'Edit Mapping' dialog. Here you can configure the data that will be transferred from a Fact Sheet's field to an SN table column in its form and direction.

For every mapping the following values can be set:

  • 'Mapping Type' specifies the way the data within a field is handled
  • 'Fact Sheet Field' specifies the Fact Sheet's field
  • 'Foreign Field Name' specifies the SN column name
  • 'Use Normal Direction' specifies the direction the data flows. If check, the field's data flows from specified master to slave system. Of unchecked, the data flows from specified slave to master.
  • '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.

Field mapping description based on the json format

  • The Fact Sheet's field name is the name of the node in mapping. If there is no such field, e.g. if we want to put in the URL of the LeanIX fact sheet into the foreign system, then we put in a prefix to the name: _no_mapping_field_.
  • The fieldType: This can be one of the following:
    • FOREIGN_FIELD: maps the (untranslated) value (ignoring any labels in SN or LeanIX) of a field to the corresponding field in the slave system. Mandatory attributes on the mapping are:
      • foreignFieldName
    • VALUE_MAPPING: Mandatory attributes on the mapping are:
      • foreignFieldName
      • valueMapping: This needs to be a json, that maps values of the field in LeanIX to choice values in SN, e.g.
        "valueMapping": {
        "missionCritical": "1 - most critical",
        "businessCritical": "2 - somewhat critical",
        "businessOperational": "3 - less critical",
        "administrativeService": "4 - not critical"
        }
        
    • SUBSCRIPTION_ROLE_MAPPING and SUBSCRIPTION_ROLE_USERGROUP_MAPPING both map the subscription role of the fact sheet to a user/group reference field in the foreign system and use the user's sys_id or group's sys_id respectively to be used in the field named in foreignFieldName. The syntax for the name is 'subscriptions/<Name of Role>', e.g. subscriptions/IT Owner. Mandatory attributes are:
      • foreignFieldName
    • URL: Used to map the url of the LeanIX Fact Sheet to the foreign object. Mandatory attributes are:
      • foreignFieldName
    • FIXED_VALUE: Only to be used to set a constant value on every synchronised object, e.g. set the category of ITComponents to Software, Hardware or Service. Mandatory attributes are:
      • fixedValue
    • TAG_GROUP_FIELD: Takes care of all tags encounter in a LeanIX tag group and synchronizes those between a fact sheet and a ServiceNow item. The node name of this mapping has the structure tags/<tag group name>, eg: tags/SLA for all tags of tag group SLA or tags/ for all tags which are not assigned to a tag group (other tags). Mandatory attributes are:
      • foreignFieldName
    • TAG_GROUP_MAPPING: same as TAG_GROUP_FIELD above, but this type supports an additional tag name mapping used to synchronize LeanIX tags against ServiceNow choice values. Mandatory attributes are:
      • foreignFieldName
      • valueMapping: This needs to be a json, that maps tag names to choice values in SN, e.g.
        "valueMapping": {
          "Gold": "c_gold",
          "Bronze": "c_bronze",
          "Silver": "c_silver"
        },
        
    • TECHNOPEDIA_MAPPING: This mapping maps a field from SN to the external id technopediaId in LeanIX and links the fact sheet to the correct technopedia record. The name needs to be the name of the externalId to match: technopediaId. Mandatory attributes are:
      • foreignFieldName
      • valuePrefix: Depending on which catalog to query, this will require a prefix of hw_ for hardware and sw_ for software.
    • ARCHIVED_STATUS_MAPPING: If a fact sheet is archived, then a special value is written to SN. Mandatory attributes are:
      • foreignFieldName
      • fixedValue: The value to write, if a fact sheet is archived, e.g. inactive, deleted etc to be written in status in ServiceNow.
  • foreignFieldName: the name of the field in the foreign table. Not necessary if putting in a constant value, e.g. with FIXED_VALUE
  • fixedValue: a constant value to be set on every object.
  • valueMapping: only relevant with type VALUE_MAPPING. This is a json formatted map which contains values in LeanIX and how they should be transferred to the foreign system.
  • useNormalDirection: boolean value. Set this to false if you want this field to be synchronised from slave to master (as opposed to the natural flow of information goes from master to slave system)
  • valuePrefix: a string to be put in front of every value that is transferred. Only to be used in connection with TECHNOPEDIA_MAPPING.

Field Mapping example for VALUE_MAPPING type

VALUE_MAPPING is used when fixed values must be mapped to other fixed values, eg: Application's business criticality to Business Service's _businesscriticallity . Therefore you need to open the mapping dialog pressing the ... button.

The dialog that opens is the 'Edit extra fields' and holds the strings used for the mapping.

The left column contains the strings used on LeanIX side, the right column contains the values used in SN choice fields.

The left column contains the strings used on LeanIX side, the right column contains the values used in SN choice fields.

Where do we get the exact strings for this mapping?
The left column contains strings as specified in LeanIX workspace datamodel which can be opened from the Administration's Model Editor page.

The LeanIX datamodel specifies the strings, which can be used for the `VALUE_MAPPING_TYPE` for LeanIX site.

The LeanIX datamodel specifies the strings, which can be used for the VALUE_MAPPING_TYPE for LeanIX site.

Model Editor

In case you have no Model Editor page in your Administration area, please contact LeanIX customer success team to get your datamodel.

The right column contains the strings as specified in SN's choice field. Therefore open the corresponding table configuration in SN, which means in the example above open the configuration of table cmdb_ci_service.

Select your table in SN

Select your table in SN

The 'Column Name' contains the exact name that must be used for the field mapping.

The 'Column Name' contains the exact name that must be used for the field mapping.

The 'Choices' area contains the exact strings used for the second column in 'Edit extra fields' dialog.

The marked rectangle shows the four strings that must be used for the `VALUE_MAPPING' type in the second column.

The marked rectangle shows the four strings that must be used for the `VALUE_MAPPING' type in the second column.

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.

Sync Constraints

Sync Constraints are additional rules used to synchronize SN object only in case conditions are fulfilled. They are used for example when only Software Product models should be synchronized as IT-Components when they are really used on a server.
The configuration dialog for Sync Constrains is opened when the '...' button is pressed.

Sync Constrains can be specified for each Fact Sheet Type / SN table mapping

Sync Constrains can be specified for each Fact Sheet Type / SN table mapping

Synchronisation constraint can be of different types:

  • graphRule, i.e., a rule that controls, whether an object is synchronised at all based on a connection found on SN side. At the moment, this only works for Hardware and Software Product Models and can be configured for usage of the SAM or regular Software Management of SN. Options are:
    • APPLICATION_SAM_CONNECTION: Synchronise this Software Product Model, if a connection to a Business Service exists that can be found via the SAM module.
    • IN_USE_SAM_CONNECTION: Synchronise this Software Product Model, if a connection to a Hardware exists that can be found via the SAM module.
    • MODEL_CATEGORY: Synchronise this Product Model, if a connection to a Model Category exists in SN.
    • APPLICATION_HARDWARE_CONNECTION: Synchronise this Hardware Product Model, if a connection to a Business Service exists.
    • IN_USE_HARDWARE_CONNECTION: Synchronise this Hardware Product Model, if a connection to a Hardware exists.
    • APPLICATION_SOFTWARE_MANAGEMENT_MODEL_CONNECTION: Synchronise this Software Product Model, if a connection to a Business Service exists that can be found via the Software Management module.
    • IN_USE_SOFTWARE_MANAGEMENT_MODEL_CONNECTION: Synchronise this Software Product Model, if a connection to a Hardware exists that can be found via the Software Management module.

Filters

In addition to sync constraint, filters can be specified to limit the visibility of Factsheets and/or ServiceNow items to be synchronized. For each sync descriptor, a filter from LeanIX to ServiceNow or from ServiceNow to LeanIX can be set depending on who is the Master (filters apply on the Master side of the specific sync descriptor in which they are configured).

Filtering from LeanIX to ServiceNow

When LeanIX is the Master, if you want to filter Factsheets for the selected Factsheet type in the descriptor, you can select the Edit Filters option.

Then you can create a Filter in the same way you create a Bookmark, but restricted to the Factsheet type of the sync descriptor.

Example; filtering from LeanIX to ServiceNow of Application Factsheets, synchronizing Applications only if their life-cycle is in `phaseIn` or `active`.

Example; filtering from LeanIX to ServiceNow of Application Factsheets, synchronizing Applications only if their life-cycle is in phaseIn or active.

Filtering from ServiceNow to LeanIX

When ServiceNow is the Master, if you want to filter items for the selected ServiceNow table in the descriptor, you can select a filter in the Edit Constraints option.

Below filter is pulled from filters created for "cmdb_hardware_product_model" table in ServiceNow.

Then you can select an existing filter created in ServiceNow for that table to use for synchronization. Filters available for that table are listed by its Name (Title) given when they were created in your ServiceNow instance.

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

Configuration of Relationships

LeanIX-ServiceNow integration gives an option to transfer relations from ServiceNow to LeanIX and into the opposite direction. For each relation the user can define the direction the relation synchronization has to work.

Relations from ServiceNow to LeanIX

Below table provides details about the options for relation configuration where ServiceNow is the master.

From Fact Sheet Type
Relationship name*
To Fact Sheet Type
Description

Application

IT Components

IT Component

Pulls relations between Applications and IT Components by traversing through the relations in the table cmdb_rel_ci, cmdb_ci_hardware and software installation tables and establishing a link to the IT Components.

Technical Stack

IT Components

IT Component

Pulls relations between Technical Stacks and IT Components by checking the Model Category on the Product Models and establishing a link to the IT Components

Business Capability

Applications

Application

Pulls relationship between Table corresponding to "From Factsheet" and "To Factsheet" cmdb_rel_ci Table in ServiceNow and creates relationship in LeanIX.

Business Capability

Children

Business Capability

Pulls relationship "From Factsheet" and "To Factsheet" in cmdb_rel_ci Table in ServiceNow and creates Child relationship in LeanIX.

Technical Stack

Parents

Technical Stack

Advanced: based on 'referenceToField'

Pulls relationship "From Factsheet" and "To Factsheet" based on references specified by reference field in ServiceNow and creates Parent relationship in LeanIX.
(This kind of configuration is only possible in the Advanced tab.)

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

1
From Business Capability TO Application: Pulls relationship in ServiceNow and creates relationship in LeanIX. (The arrow means, Parent and Childs in ServiceNow and “From to To” in LeanIX).

2
From Business Capability TO Children Pulls relationship in ServiceNow and creates Parent Child relationship in LeanIX. (Here you can see the Relationships of Config Items in ServiceNow between the same table)

Relation Mapping:

Integration provides three options to detect relations between tables:

  1. relationship between cmdb_ci_service and cmdb_hardware_product_model and cmdb_software_product_model, which is fixed build-in into the integration code and requires the configuration of a SyncConstraint.
  2. relationship between two ServiceNow tables using cmdb_rel_ci table
  3. relationship between two ServiceNow tables using a reference field configured in the Relations Sync Descriptor Mapping using the field 'referenceToField' (Only visible in the Advanced tab)

Relation limitations

When the relation type Requires and Required by is used for each 'From Fact Sheet Type' only one 'To Fact Sheet Type' can be selected over all configured Relation Sync Descriptors.

Relations from LeanIX to ServiceNow

In case LeanIX acts as a master for relations, the configuration of such case is only supported in the Advanced-tab.
Two options are are supported:

  1. relationship between two ServiceNow tables using cmdb_rel_ci table
  2. relationship between two ServiceNow tables using a reference field

Relation Mapping using cmdb_rel_ci table and a relation type

Prerequisite

In order to to provide the integration full access to table cmdb_rel_ci, the Application Access for this table needs to be increased. This can be done with these steps:

  1. Select Tables from System Definition and filter for table cmdb_rel_ci
  1. Open the record and check the Can delete in tab Application Access

Configuration

Relations which should be persisted in the cmdb_rel_ci table needs to be configured by using the field foreignRelationMapping with type CMDB_REL_CI and a relationName specified.

Here is one example configuration for Parents relations between Applications which are persisted in ServiceNow via the cmdb_rel_ci table as type Depends on::Used by:

...
{
			"active": true,
			"masterSite": "LEANIX",
			"relationName": "relToParent",
			"reverseRelationName": "relToChild",
			"typeFrom": "Application",
			"typeTo": "Application",
			"foreignFrom": "cmdb_ci_service",
			"foreignTo": "cmdb_ci_service",
			"referenceToField": "",
			"foreignRelationMapping": {
				"type": "CMDB_REL_CI",
				"relationName": "Depends on::Used by"
			}
		}

Relation Mapping using a reference field

Relations which should be persisted using a reference field in one of the linked table needs to be configured by using the field foreignRelationMapping with type REFERENCE_FIELD and the name of the reference field specified in field referenceToField.

Here is one example configuration for Parents relations between Applications which are persisted in ServiceNow via the reference field parent on table cmdb_ci_service:

...
{
			"active": true,
			"masterSite": "LEANIX",
			"relationName": "relToParent",
			"reverseRelationName": "relToChild",
			"typeFrom": "Application",
			"typeTo": "Application",
			"foreignFrom": "cmdb_ci_service",
			"foreignTo": "cmdb_ci_service",
			"referenceToField": "parent",
			"foreignRelationMapping": {
				"type": "REFERENCE_FIELD"
			}
		}

Full Synchronisation

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

Click on 'Sync Now' to trigger a full sync. We recommend to disable "short event buffering for that", see warning further below.

Click on 'Sync Now' to trigger a full sync. We recommend to disable "short event buffering for that", see warning further below.

During a full sync the LeanIX integration will gather all fact sheets from LeanIX of a single type and all entries from the associated table in SN and calculate what to do based on the mappings provided in the 'Advanced' tab. If necessary, other tables will be loaded as well, e.g. when determining whether a Product Model shall be synchronised.

Turn off 'short event buffering' for full sync

For full synchronisations, we highly recommend not setting the flag for 'short event buffering' as this will lead to an unnecessary large number of synchronisations getting triggered off of the initial full sync.

Depending heavily on the size of your SN environment and the amount of fact sheets (though in our experience the latter does not have such a high impact), the full sync can take up

Partial Synchronisation in Default Configuration

A partial synchronisation is triggered any time a fact sheet of the configured type is created, updated or deleted in LeanIX. By default these are 'Application', 'IT-Component' and 'TechnicalStack'.

Also a partial synchronisation is triggered every time an entry is created, updated or deleted in SN on the following tables:

  • CMDB CI (cmdb_ci), which by inheritance includes cmdb_ci_service and cmdb_ci_hardware.
  • CI Relationship (cmdb_rel_ci)
  • Software Instance (cmdb_software_instance) or - if you have the Software Asset Management (SAM) module installed - Software Installation (cmdb_sam_sw_install)
  • Hardware Product Model (cmdb_hardware_product_model)
  • Software Product Model (cmdb_software_product_model)
  • Model Category (cmdb_model_category)

If the flag 'short event buffering' is not set (this should be the default), then the synchronisation engine buffers all changes. So changes are only synchronised if the batch is full (100 changes have been logged) or the batch wait time has been exceeded (2 minutes after the first change was logged). In 'short event buffering' mode, the batch wait time is reduced to five seconds. We only recommend to use the short event buffering for manual testing purposes to see changes trigger synchronisations right away.

Details to the default ServiceNow configuration in LeanIX

LeanIX propagated default mapping

The default mapping, which is created on a new configuration maps in this way:

  • Business Services to Applications
  • Hardware Product Models to IT-Components
  • Software Product Models to IT-Components and
  • Model Categories to Technical Stacks

All involved ServiceNow tables and used connections among each table and the LeanIX Fact Sheet types and its relations are shown in a picture below. This picture should help to understand relations between ServiceNow tables and data flow conditions when constrains are used within the configuration.

On the left in Blue are the LeanIX fact sheet types and on the right are the tables in SN. double-lined arrows show synchronisation directions, other arrows show relations. On SN side these can be connections via CI Relation or foreign key values.

On the left in Blue are the LeanIX fact sheet types and on the right are the tables in SN. double-lined arrows show synchronisation directions, other arrows show relations. On SN side these can be connections via CI Relation or foreign key values.

The default mapping represents a full blown example of an integration of LeanIX with SN. The tables and how they are connected is shown here:

The workflow for this default scenario is as follows:

  1. Applications get created and maintained in LeanIX.
  2. The integration application synchronises these applications to Business Services (cmdb_ci_service) in SN.
  3. Business services are linked to Hardware objects via the CI Relation table (cmdb_rel_ci). These hardwares are directly associated with Hardware Product Models (cmdb_hardware_product_model) and via Software Instance (cmdb_software_instance) and Software (cmdb_ci_spkg) to Software Product Models (cmdb_software_product_model). If you use the Software Asset Management (SAM) module of SN, then other tables are used, but the methodology remains the same.
  4. LeanIX integration will synchronise only the Hardware and Software Product models (cmdb_hardware_product_model + cmdb_software_product_model) that have a link to a synchronised Business Service (see step 2) or a Hardware (cmdb_ci_hardware) depending on selected constraints.
  5. Additionally, Model Categories (cmdb_model_category) is synchronized from SN to LeanIX.
  6. If a relation exists in SN between a Business Service (cmdb_ci_service) and a Hardware or Software Product Model (cmdb_hardware_product_model + cmdb_software_product_model) as explained in step 3, then a relation of the corresponding objects in LeanIX will be created as well.
  7. If a relation exists in SN between a Model Category (cmdb_model_category) and a Hardware or Software Product Model (cmdb_hardware_product_model + cmdb_software_product_model), then a relation of the corresponding objects in LeanIX will be created.

ServiceNow Integration


Fundamentals about LeanIX integration to ServiceNow

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.