Overview

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

General 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. If you want to use REST OAuth to communicate with ServiceNow, please configure this inside the Advanced Tab configuration.

🚧

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.

Example of typical 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.
Also some functionality can only be configured inside this JSON file.

📘

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.

REST OAuth Configuration

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

...
  "oauth": {
        "clientId": <client id of Application Registration's endpoint>,
        "clientSecret": <client secret of Application Registration's endpoint>
    }

maximumDeletionRatio

To avoid accidentally the deletion of of FactSheets or ServiceNow items because of an erroneous configuration, a 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 ration in percent.

skipPartialSyncCondition

The configuration skipPartialSyncCondition can be used to skip the partial synchronization in case the table cmdb_rel_ci is bigger than a specified number. Here is a configuration that skips the partial synchronization in case cmdb_rel_ci has more than 50k of items.

...
"skipPartialSyncCondition": {
        "relCiIsBiggerThan": 50000
    },

readRelCiIterative

When using readRelCiIterative the integration uses a different approach when resolving relations persisted in cmdb_rel_ci. In case this is not specified, the integrations reads the whole table into the memory to detect relations. If set to true the integration will try to query for cmdb_rel_ci relations and follow relations up to 5 hops.
#Configuration of tables and fields

Overview of Default Mapping

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

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

{
 "factSheetSyncDescriptors": [
  {
   "active": true,
   "factSheetType": "Application",
   "foreignType": "cmdb_ci_business_app",
   "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",
   "automaticForeignTablesConfiguration": true,
   "typeFrom": "Application",
   "typeTo": "ITComponent"
  },
  {
   "active": true,
   "masterSite": "FOREIGN",
   "relationName": "relTechnologyStackToITComponent",
   "reverseRelationName": "relITComponentToTechnologyStack",
   "automaticForeignTablesConfiguration": true,
   "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.

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

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/', e.g. subscriptions/IT Owner.
    More details on the Subscription mapping options available :-
  • In the direction LeanIX to ServiceNow Subscription type eg. "Responsible" used in combination with the role eg. "Application Owner" will send specific subscription related to type and role from the FactSheet to ServiceNow object. In case the role is missing in the configuration, this will send the Subscription of type "Responsible" without roles into ServiceNow.
  • In the direction LeanIX to ServiceNow if only role eg. "Application Owner" without a subscription type eg. "Responsible" is configured, this will send the Subscription of type "Application Owner" irrespective of roles into ServiceNow.
  • In the direction ServiceNow to LeanIX it is mandatory to provide both role eg. "Application Owner" and type eg. "Responsible" , this will pull the Subscription into LeanIX.
  • 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.
    • "uniqueFactSheet" attribute on the serviceNowExternalId should be set to false in order for this to work.
  • EXTERNAL_ID: This type is used to map a LeanIX ExternalId field to a ServiceNow column. The node name has the structure '[/]', eg: 'myExternalId/externalId', or 'myExternalId/comment'. If no optional '/' is specified, the externalId itself (field externalId) is used for synchronization, like 'myExternalId'. (Because the serviceNowExternalId field is used for linking internally, it can only be used if data flows from LeanIX to ServiceNow.) Mandatory attributes are:
    • foreignFieldName
• 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 business_criticallity . 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.

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.

🚧

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 table below in field value.

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

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.

Field Mapping for ServiceNow Lifecycle Information

The following configuration is supported:

{
 "lifecycle/plan": {
  "fieldType": "FOREIGN_FIELD",
  "foreignFieldName": "attested_date",
  "useNormalDirection": true
 },
 "lifecycle/active": {
  "fieldType": "FOREIGN_FIELD",
  "foreignFieldName": "start_date",
  "useNormalDirection": true
 },
 "release": {
  "fieldType": "FOREIGN_FIELD",
  "foreignFieldName": "attested_date",
  "useNormalDirection": true
 }
}

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.

Synchronisation constraint can be of different types:

hardwareFilter

If using the graph constraints APPLICATION_SAM_CONNECTION or APPLICATION_HARDWARE_CONNECTION, sys_params can optionally be set to only retrieve models that are linked to Operational Hardware CIs.

The hardwareFilter field can contain a sysparm_query for filtering the hardware table like the sysparm_query used in ServiceNow REST API, but only containing AND and OR operators (^ and ^OR in ServiceNow query notation).

A valid example of filtering for the documentation would be:

"hardwareFilter": "operational_status=1^ORinstall_status=1"

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.

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.

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

Integration provides four options to detect relations between tables:

Relation Pull from CMDB_REL_CI using a filter

This a case when you want to only pull specific relationships from CMDB_REL_CI using a query to avoid pulling millions of records from relationship table.

{
 "active": true,
 "masterSite": "FOREIGN",
 "relationName": "relToRequires",
 "reverseRelationName": "relToRequiredBy",
 "typeFrom": "Application",
 "typeTo": "Application",
 "automaticForeignTablesConfiguration": true,
 "foreignFrom": "cmdb_ci_appl",
 "foreignTo": "cmdb_ci_appl",
 "referenceToField": "",
 "foreignRelationMapping": {
  "type": "CMDB_REL_CI",
  "relationName": "Uses::Used by",
  "query": "parent.sys_class_name=cmdb_ci_appl^child.sys_class_name=cmdb_ci_appl"
 }
}

📘

The above relationship config will pull all the relationships if applied along with the GraphRule constraints to pull Application-ITC relationships as in that scenario we have to pull all the relationships.

Relation Mapping Using a custom relationship table

The MAPPING_TABLE configuration defines the case when a customer specifies a custom table which holds two columns of type reference that 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.

You also have an option to define a Sync constraint in the Advanced Section : MAPPING_TABLE_CONNECTION which limits the objects to the one's available in the custom relationship table.

Here is 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 pointing to cmdb_ci_appl has the name u_application and the column pointing 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"
 }
}

🚧

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.

Three options are are supported:

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:

Relation 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",
 "automaticForeignTablesConfiguration": true,
 "foreignFrom": "cmdb_ci_business_app",
 "foreignTo": "cmdb_ci_business_app",
 "referenceToField": "",
 "foreignRelationMapping": {
  "type": "CMDB_REL_CI",
  "relationName": "Depends on::Used by"
 }
}

Relation Mapping Using a reference or a glide_list Field

Relations that should be persisted using a reference or glide_list 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. During the synchronization run, the ServiceNow integration will automatically detect the exact technical type behind the field which is specified by referenceToField and apply the suitable updates.

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

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

Here is one example configuration for TechnicalStacks relations between IT-Components and Technical Stacks which are persisted in ServiceNow via the glide_list field model_category on table cmdb_software_product_model and cmdb_hardware_product_model. (Be aware that an IT-Component may get more than one relation to a Technology Stack and therefore the glide_list is the best choice.):

{
 "active": true,
 "masterSite": "LEANIX",
 "relationName": "relITComponentToTechnologyStack",
 "reverseRelationName": "relTechnologyStackToITComponent",
 "typeFrom": "ITComponent",
 "typeTo": "TechnicalStack",
 "automaticForeignTablesConfiguration": true,
 "foreignFrom": "cmdb_software_product_model,cmdb_hardware_product_model",
 "foreignTo": "cmdb_model_category",
 "referenceToField": "model_category",
 "foreignRelationMapping": {
  "type": "REFERENCE_FIELD"
 }
}

📘

Automatic Foreign Tables Configuration

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

Synchronisation

On-Demand Full Synchronisation

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

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.

Time taken by a Full Sync depends 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).

Scheduled Full Synchronisation

Full Synchronisation is scheduled to run at 05:00 CET for all the LeanIX Instances.

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:

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 (5000 changes have been logged) or the batch wait time has been exceeded (15 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:

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.

The default mapping represents a full blown example of an integration of LeanIX with SN. The tables and how they are connected are detailed within the ServiceNow Integration document.

📘

Monitoring

One way to automate monitoring of ServiceNow errors is to create an integration between Slack or Microsoft Teams and ServiceNow. Please see https://dev.leanix.net/docs/send-integration-stats-to-slack-and-teams for more details.