Setup in SAP LeanIX

Overview

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

📘

Note

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

Adding a Configuration

📘

Note

You can configure integrations with multiple ServiceNow instances. This is relevant for organizations that use different ServiceNow instances for various aspects of their IT landscape, such as dedicated instances for specific regions.

To add a configuration for a ServiceNow instance, follow these steps:

1. In the administration area, navigate to the Integrations section. Depending on whether the ServiceNow integration is already configured in the workspace or not, do one of the following:

   • The integration is configured: Click on the ServiceNow tile. You land on the overview page displaying ServiceNow configurations. To add a configuration, click Add Configuration.
   • The integration is not configured: Click Add Integrations, then locate the ServiceNow integration and click Configure. To add a configuration, click New Integration.

2. On the ServiceNow configuration page, review how the integration works, then click Next. From here, you can navigate to the SAP LeanIX documentation to get additional guidance on the integration.

3. Enter a name for the configuration, then click Next.

4. To establish a connection with a ServiceNow instance, enter authentication details:

   • ServiceNow URL: Enter the URL of the ServiceNow instance, for example, https://clientdomain.service-now.com.
   • Authentication Type: Select an authentication method and enter the required details. For more information, see Authentication Options for ServiceNow.
   • Managing User: Select a Service user to run the integration. Alternatively, a technical user can also be leveraged for this. To learn how to create a technical user, see Create a Technical User.

5. Click Save.

   

A connection with a ServiceNow instance is established. Now, you can continue to configure the integration:

• Configure the mapping of fields between ServiceNow and SAP LeanIX. For more information, see Field Mapping.
• If needed, configure advanced settings. For more information, see Advanced Configuration.

Overview of the Configuration Page

This section provides an overview of tabs available on the configuration page of a ServiceNow integration.

Credentials Tab

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

Partial Sync Mode

This is the property that sets how the partials sync should be executed. It has three options: FULL, SKIP and WITHOUT_RELATION

Mappings Tab

The Mappings Tab is the UI section provided to help quickly set up the configuration of the Integration in a no-code way. It is detailed further in the Core Concepts section of ServiceNow Integration.

Advanced Tab

Advanced Tab is the JSON representation of everything set in the Basic Tab. Any configurations or additional changes made in the Basic section will be represented within the advanced tab.

There are a few items in the Integration that can only be configured in the advanced tab. Such as OAuth 2.0 setup, advanced relationship mapping, dot walking, and others. For more details, read the corresponding page on the Advanced Configuration.

In case you do not see the Advanced tab in your configuration, you may reach out to support at SAP LeanIX Support to activate this feature.

Versions Tab

On the Versions tab, you can view the current and previous versions of the ServiceNow configuration in JSON format. Here, you can:

• View JSON configurations: To view the JSON configuration for the current version, click Current Version. To view the JSON configuration for a previous version, hover over the version that you need, then click View JSON.
• Compare configuration versions: To compare two versions, select them, then click Compare. On the page that opens, the differences between the two configurations are highlighted. If the current version (indicated by the Current Version label) is one of the selected versions, you can restore the previous version by clicking Restore Previous Version.

📘

Note

As we continuously enhance the ServiceNow integration, we occasionally perform data migrations from one format to another. If such a migration impacts a configuration, the changes are reflected in a distinct configuration version. This version is labeled as owned by the ServiceNow Migration User, an internal user designated to manage and document the changes in that specific migration version.

Credential Configuration

This section is used to provide the most crucial information which covers the authentication against ServiceNow and the SAP LeanIX workspace and the partial synchronisation mode.

The Credentials tab contains the following configuration parameters:

• ServiceNow URL: The URL of the instance that is to be connected with the workspace. e.g. https://clientdomain.service-now.com.
• Authentication Type: Authentication type for the specified instance.
• Short event buffering: When activated, all changes in SAP LeanIX and ServiceNow will be synchronized as soon as possible. This setting is useful for testing or demo purposes, but it will increase the amount of CPU usage and network traffic and should be disabled for production workspaces.
• Managing User: Select a user type to run the integration in SAP LeanIX. Typically, a service user can run the integration, but a technical user can also be leveraged for this. This is useful for auditing purposes, and showing changes done by the integration. For more information, see Create a Technical User.
• Partial sync mode: For more information, see Partial Sync Mode.

Upon clicking Save with the Active checkbox selected, SAP LeanIX will check the access to ServiceNow and all configured tables and columns in the provided ServiceNow Instance.

If an error occurs, please check the credentials and whether the account created is according to the required roles and access as shown in Setup in ServiceNow.

Authentication Options for ServiceNow

When adding a ServiceNow configuration, you need to select an authentication method and specify the required details. If needed, you can change the authentication method for your existing configurations.

The ServiceNow integration supports the following authentication methods:

• Basic authentication: This method requires the username and password of the integration user that you created in ServiceNow. This user is a specific account created for the purpose of the integration. For instructions on how to create an integration user, see Create an Integration User.
• Certificate-based authentication: This method uses a private key and certificate to establish an SSL connection with your ServiceNow instance. During the SSL handshake, the certificate and private key are used to identify the client and the corresponding ServiceNow user for authorization. This method ensures a secure connection between the client and ServiceNow. To learn how to set up this authentication method, refer to the ServiceNow documentation.
• OAuth authentication: This method uses tokens instead of credentials to grant access. Provide the following details:
  • Username and password: Enter the username and password of the integration user that you created in ServiceNow. For instructions, see Create an Integration User.
  • Client ID and secret: Enter the client ID and client secret that you obtained in ServiceNow when enabling OAuth 2.0 for authentication. For details, see Enable OAuth 2.0 for Authentication.

Synchronisation

The following section explains the types of synchronization offered depending on the configurations.

To view the details of synchronization runs, navigate to the Sync Logging section in the administration area. Incomplete mappings or errors while updating an attribute appear as errors in the synchronization logs. If a mapping issue occurs due to a change in the configuration in the background, this is also displayed in the synchronization logs.

To configure notifications for errors during synchronizations, you can use webhooks. To learn how to send notifications to Slack and Teams, see Sending Alerts to Slack and Teams.

Only the fields that are specified in the mapping configuration are synchronized. Any other fields in the respective system are not synchronized.

📘

Note

When synchronizing fact sheet subscriptions from SAP LeanIX to ServiceNow, in case there are multiple ServiceNow users with the same email address, the integration checks the ServiceNow user status first and prioritizes active users. The following logic is applied:

• If at least one active user is listed, the first active one is added as a subscriber.
• If no user is active, the first inactive user is added as a subscriber.

Manual Full Sync

A manual full synchronization can be triggered from SAP LeanIX's administration within a workspace. To start a synchronization, on the Credentials tab, click Run Sync.

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

🚧

Sync Logging Time

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

Scheduled Full Sync

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

Full Sync is scheduled to run at midnight related to the time zone in which the SAP LeanIX Instance is hosted.

Partial Sync

Partial syncs are event-driven that get triggered from both sides (SAP LeanIX and ServiceNow). In each case, it gets triggered any time a Fact Sheet or a record is created, updated, or deleted in the systems.

In the default model (flag 'short event buffering' is not set), the partial sync is triggered as soon as the batch is full (5000 changes have been logged) or the batch wait time has been exceeded (15 minutes after the first change was logged).

📘

Short event buffering

In 'short event buffering' mode, the batch wait time is reduced to five seconds. We only recommend using the short event buffering for manual testing purposes.

For ServiceNow, the SAP LeanIX application installs a couple of Business Rules to track these events and trigger a sync as seen here -

👍

Tip - Disable Business Rules in ServiceNow for Operational Tables

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

First Sync Behavior

Upon initial synchronization, the integration matches records based on the following logic:

1. If either displayName or fullName is specified in the field mapping, the corresponding ServiceNow field is used.
2. If only name is specified in the field mapping (but neither displayName nor fullName are present), the corresponding ServiceNow field is used.
3. If no field mapping exists for displayName, fullName, or name, then the name field in SAP LeanIX and the name field in ServiceNow are used.

If a record with the same name already exists in the target system, then the integration matches the record in SAP LeanIX and links the ServiceNow external ID to it. If there is no match, then a new fact sheet is created in SAP LeanIX or a new record is created in ServiceNow.

Aggregation and Linkage of Software Records

You can import software records from ServiceNow as aggregated software fact sheets and automatically link these consolidated fact sheets to the reference catalog that provides lifecycle data for obsolescence risk management. By using the aggregation and linkage feature, you can streamline the import process and enhance data quality. To learn more about this feature and how to use it, see Aggregation and Linkage of Software Records.

Configuring Mappings

On the Mappings tab of the ServiceNow configuration page, you can configure mappings for fact sheets and fact sheet relations between SAP LeanIX and ServiceNow. To learn more about configuration parameters, refer to the following sections in this document.

Field Mapping

For each specified Fact Sheet Type and ServiceNow table, you can configure field mapping by clicking Configuration under Field Mapping. Here the configuration is set for the data that will be transferred from a Fact Sheet field to a ServiceNow table attribute in its form and direction.

The naming conventions for mapped attributes must match in both systems. You can use aliases or additional attributes for alternative names.

The following section describes in detail the type of mappings available within the integration and how to map them.

👍

Tip

Download the mapping matrix as an XLSX file. The matrix provides a basic setup that you can modify according to your requirements.

AI-Generated Field Mapping Suggestions

To streamline the process of configuring field mappings, you can use the AI capabilities optional feature. To learn how to activate this feature, see Activating Base AI Capabilities.

To generate field mapping suggestions using AI, on the field mapping configuration page, click Generate Fields. AI generates mapping suggestions based on common patterns and your system configuration. Before applying suggested mappings, review and adjust them as needed. You can edit fields manually as well as add or remove fields.

📘

Note

AI-generated field mapping suggestions can be inaccurate or misleading. Ensure to review suggestions and adjust them if needed before applying the changes.

Mapping Type

The following table contains mapping types.

Field Types in ServiceNow are explained in their documentation..

Fact Sheet Field

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

Direction

Direction specifies the direction the data flows: drom SAP LeanIX to ServiceNow or from ServiceNow to SAP LeanIX for that particular field. You can make the synchronization bi-directional by specifying both directions for a field.

ServiceNow Field

The following dropdown lists the attributes available within the configured ServiceNow table.

❗️

Not all ServiceNow Attributes are supported to sync

Even though the Foreign Field mapping displays all available attributes in the table, not all fields are currently supported to be synced with SAP LeanIX.

Configure Details

Configure Details is a button that is only offered for some special mapping types to provide more configuration, like a mapping of fixed values for choices.

One example of the use of the Configure Details section is the VALUE_MAPPING. VALUE_MAPPING is used when fixed values from SINGLE_SELECT fields must be mapped to choices in the CHOICE field type in ServiceNow.

The example below shows VALUE_MAPPING configuration of SAP LeanIX's businessCriticality field with ServiceNow's business_criticality attribute.

Here the left side indicates the Meta Model name values of within the businessCriticality field in SAP LeanIX. Similarly, the right side is mapped to the value of the choices within the business_criticality attribute in ServiceNow.

👍

Tip

Use Fact Sheet configuration menu to get the Meta Model key of the fields in SAP LeanIX. Translations are not relevant in the VALUE_MAPPING section

The Meta Model keys are visible within brackets, as seen below -

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

Only the VALUES section is required for the mapping -

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

❗️

n:1 Value Mapping Supported only when the source of truth is SAP LeanIX

Attaching multiple values in the SINGLE_SELECT field to 1 VALUE in the Choice List field in ServiceNow is supported, provided the source of truth is SAP LeanIX.

Advanced Field Mapping Use Cases

Sync Multiple Select Fields between SAP LeanIX and ServiceNow

The Integration can sync between Multiple Select fields in SAP LeanIX with Glide Lists fields of ServiceNow that refer to a table in ServiceNow.

Prerequisites

• Multiple Select Field with values in SAP LeanIX
• GlideList field in ServiceNow, with the values of the records you wish to map to SAP LeanIX or the sys_id of the records in the referenced table in ServiceNow.

Within ServiceNow however, there can be two types of list fields -

• List fields that reference another ServiceNow Table

• List fields that do not refer to another ServiceNow Table and have a choice list defined

To map both of these fields, the Mapping Type of VALUE_MAPPING is used -

❗️

Make sure to fill in the extra fields section!

Mapping multiple select fields requires you to map the Meta Model name of the values of the multiple select field in SAP LeanIX with the values of either the sys_ids of the records or the values of the choices from the ServiceNow side.

• Example Extra field mapping when the field is referencing another table -

Collect the sys_id of all the records you wish to map with the multiple select values in SAP LeanIX, this can be done for multiple records by exporting or by selectively copying the sys_id as follows -

These collected sys_ids can be mapped to SAP LeanIX as follows -

❗️

Unmapped values will be ignored

If the extra field section does not fully cover the mappings, any additional values on each system will be ignored by the sync.

Once saved, the sync will automatically match the sys_ID with the respective record in ServiceNow. Similarly, it will also match the sys_ID with the mapped field in SAP LeanIX from the extra fields section.

Examples -

Supported Lifecycle and Dates Sync Methods

👍

Supported Lifecycle Sync Methods

Case 1 - Lifecycle current phase can be pushed from SAP LeanIX to a ServiceNow field.
Case 2 - Lifecycle date values can be pulled from ServiceNow to SAP LeanIX lifecycle phase fields
Case 3 - SAP LeanIX lifecycle phase dates can be pulled and pushed to ServiceNow Date fields
Case 4 - String fields in SAP LeanIX can pull the values of dates from ServiceNow
Case 5 - String fields in SAP LeanIX can push the values of dates to ServiceNow

Case 1 -
The source of truth for the fields is SAP LeanIX, selecting the main Lifecycle field instead of one of its phases (e.g. using lifecycle, not lifecycle/active or lifecycle/phaseIn). Only for this case, it is not a Date but a String representing the current phase that is synchronized to ServiceNow. This value can be mapped if needed using theVALUE_MAPPING as mapping type.

Case 2 -
The source of truth for the fields is ServiceNow instead of SAP LeanIX. Supported Date type attributes can sync date values from ServiceNow to the respective Lifecycle phase (e.g. lifecycle/active, lifecycle/phaseIn) fields in SAP LeanIX. Input date should be in the format: yyyy-mm-dde.g. 2014-01-01

Case 3 -
The source of truth for the fields is SAP LeanIX. SAP LeanIX lifecycle date values of Plan, Active, Phase Out, etc can now be synced to supported Date type attributes in ServiceNow. Similar to Case 1 above, within the advanced section set the lifecycle/plan etc value to a date field in ServiceNow.

Case 4 and 5 -

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

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

Sync Filters

The following section details the methods that can be used depending on the source of truth to limit the number of records in sync with the Integration.

Filtering from SAP LeanIX to ServiceNow

When SAP LeanIX is the source of truth, Fact Sheets can be filtered through the same methods of Inventory filtering to only allow a certain subsection of Fact Sheets to go to the ServiceNow table in sync.

It can be done by clicking on the Filters button.

Once selected, the Inventory view opens up allowing to set specific filters based on any filterable property for the Fact Sheet type.

Once the filter is set, select Use Fact Sheet Filter and click on Save button on the Mapping Tab to ensure the filter is saved permanently.

👍

Tip - Popular Filters applied for Applications

Data Quality Broken Inversed - Only send over Applications from SAP LeanIX that have an approved Data Quality status.
Lifeycle - Active - Only send over Applications from SAP LeanIX that have an Active lifecycle

Filtering from ServiceNow to SAP LeanIX

When ServiceNow is the source of truth, the filter needs to be created on the ServiceNow side to limit the number of records that get created in SAP LeanIX. In addition, when clicking on the three ..., the drop-down changes to say "Edit Constraints".

To create a filter on the ServiceNow side, one would either need to Impersonate the leanix.integration user which is in the credentials section, or create a filter that is globally visible or at least visible to the Integration user.

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

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

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

📘

Visibility of available filters for your integration user

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

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

Graph Rule Constraints

A Graph Rule Constraint controls whether a record is synchronized at all based on a connection found on the ServiceNow side. Depending on the ServiceNow table used in a mapping from ServiceNow to SAP LeanIX, different or no Graph Rule Constraint might be applicable.

The configuration dialog for Sync Constraints is opened when ServiceNow is the Source, the configured ServiceNow Table supports the Graph Rules, and the '...' button is pressed.

Various types of Graph Rules are explained as follows -

The relations between applications and IT components are discovered in ServiceNow using Graph Rule Constraints. This information is abstracted by the integration, and only the abstracted information is pulled into SAP LeanIX. Then the relations between applications and IT components can be fetched using the GRAPH_RULE_CONSTRAINT relation. For more information, see GRAPH_RULE_CONSTRAINT.

Mapping Relations

After configuring how you want to map certain Fact Sheets into ServiceNow tables - or vice versa - you can also decide to map relations between those Fact Sheets or records to the other system.

When you add a new Relation mapping, you first need to select the following options:

• Active: Allows you to activate or deactivate a certain relation mapping
• Fact Sheet Mapping: Select which of the two entities the relationship has to be with
• Fact Sheet Mapping : Select which of the two entities the relationship has to be with
• Source System: Select the source system from which the relationship should be managed

Next, click on Configuration to open a dialog that allows you to configure the details of the relation.

Selecting the SAP LeanIX Relation

First, select the relation that is to be used on the SAP LeanIX side. Depending on the Source you selected in the previous step, this is either the relation in SAP LeanIX that is read from or the relationship that is created based on a relation within ServiceNow.

Configuring the ServiceNow Relation

Next, you need to configure the relation to be used on the ServiceNow side. Depending on the Source you selected in the basic tab, this is either the relation in ServiceNow that is read from or the relationship that is created based on the relation within SAP LeanIX.

Depending on the relation that you choose, you may need to configure additional information.

CMDB_REL_CI

This mapping type is used to create or pull from relationships between two ServiceNow tables that use the cmdb_rel_ci table. A common example is the relationship between a Business Capability and a Business Application in ServiceNow.

For this relation mapping, you need to select the type of the relations in the cmdb_rel_ci table that should be read or pushed (in case of reading from ServiceNow, you can also decide to read all of the available types).

Configuring query filters is only possible using the Advanced Configuration, in this dialog you can only view them. Please ask for guidance from Customer Success, as these filters can have subtle effects on the mapping (e.g. performance).

REFERENCE_FIELD

This mapping type is used when pulling or pushing to a Reference or Glide List field in ServiceNow that refers to a table in sync. During the synchronization run, the integration will automatically detect the exact technical type behind the field which is selected in the following dropdown and apply the suitable updates.

MAPPING_TABLE

The MAPPING_TABLE configuration defines the case when a custom table which holds two columns of field type Reference in ServiceNow are used to hold relations between two items in arbitrary tables.

This case is analogous to a mapping table concept as used in databases.

❗️

Supported Direction

Only supported where ServiceNow is configured as the source of the relation.

For this relation mapping, please select the table and fields you want to read the relation from.

GRAPH_RULE_CONSTRAINT

For this relation to work, at least one of the involved ServiceNow tables needs to have a Graph Rule Constraint configured (see above). The respective Graph Rule that is configured to constraint the number of records to be mapped will then be used to model this very graph as a relation in SAP LeanIX.

❗️

Supported Direction

Only supported where ServiceNow is configured as the source of the relation.

This relation type does not need any additional configuration.

Relation Sync Behavior

❗️

Relationships of Fact Sheets in sync with ServiceNow are always in Strict Mode

Unlike Fact Sheet descriptors, there is no strict flag to turn off for relationship descriptors. This is intended functionality that allows the Integration to delete relationships if they are no longer in the source system to always maintain parity.

🚧

Ensure Fact Sheet descriptors are active before syncing relationships.

For example, if syncing relationships between Applications and Business Capabilities, it is necessary to have Application and Business Capability set to Active in the section above.

Here we define a few cases and the intended action the Integration will take for each of them about the relationships.

The following above cases can be illustrated in the following example of an Application to IT Component relationship. Consider an Application Fact Sheet called "AC Management LeanIX" which is linked to two IT Components -

For the Fact Sheet above, the two connected IT Components are all coming from ServiceNow and thus are also linked to ServiceNow. If the Integration is not able to read the relationship between these 2 IT Components and the Application in the next sync, they will be deleted. (Case 1)

Subsequently, We then consider adding another manual relationship to this Application, an IT Component Fact Sheet which is not linked to ServiceNow, but rather created manually in SAP LeanIX either by the user or other Integrations.

In the case above, the Integration's logic knows not to touch the third relationship as it could be managed by the user and/or another Integration. This is also known because the third Fact Sheet, illustrated by its name, is not linked to ServiceNow. In the case of a sync run, if the Integration sees no relationships in the source system, it can, at best, delete the first two relationships but not the third one. (Case 2).

Other Information

👍

Mapping one ServiceNow table to multiple SAP LeanIX fact sheet types is supported

Note: This feature is only supported when:

• ServiceNow is the source of truth for mappings.
• Filters are set that ensure there is no overlap

One such example is a case where records in ServiceNow are not yet fully distributed in the suitable tables and exist under one table, such as the cmdb_ci_appl table. The user can make the following mapping -