Setup in ServiceNow

Overview

👍
Access
The following 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.

Steps order	Step	Details
1	Activation of the Integration on the SAP LeanIX side	You may reach out to support at SAP LeanIX Support or reach out to your CSM to ensure the Integration is activated on your workspace. Proceed only after the confirmation.
2.	Create a technical user	Technical user created on the SAP LeanIX side that generates an API Token to be set on the ServiceNow side. It is also used as a Managing User which is detailed in the Setup in SAP LeanIX section.
3.	Installation of the SAP LeanIX Integration App(s)	ServiceNow Store
4.	Configuration & Setup of Integration User	Setup of Integration User
5.	Additional Information	Additional information related to the configuration depends on use-cases.

Once the integration is activated on the SAP LeanIX workspace, you can leverage the Sandbox workspace to ensure data mappings and incoming data are correct before moving to the Production workspace.

Create a Technical User

To configure the integration and connect to ServiceNow, you need an API token. To get an API token, in SAP LeanIX, create a technical user through which the integration will run. Technical users enable you to manage API tokens for your workspace and audit your integrations.

For instructions on how to create a technical user, see Create a Technical User. Specify the following details:

Username: Enter a name that enables you to identify the technical user for the ServiceNow integration. This name appears in the audit log.
Permission Role: Select the Admin permission role.
Customer Roles and Access Control Entities: Leave these fields blank.
Expiry Date: The expiration date of the API token. You can set this date based on your security policy on regularly refreshing API tokens. Please note that it is not possible to automatically update the Integration Application on the ServiceNow side with the regenerated token.

Once you've created a technical user, an API token is displayed. Save the API token. It is shown only once.

Installation of LeanIX Integration App

To get the communication between SAP LeanIX and ServiceNow running, the LeanIX Integration app is required which is available in ServiceNow Store.

ServiceNow Instance administrators can request installation of the app while logged on to the store.

App	Link
LeanIX Integration Required	Link to the Application
LeanIX Integration SAM add-on Optional	Link to the Add-on

Update LeanIX Integration App (for admins)

In your ServiceNow instance, follow these steps:

Go to System Applications > All Available Applications > All.
Find the application with the filter criteria and search bar.
Next to the application listing, select the version to install.
Click Update.

Configuration & Setup of Integration User

After successful installation, properties for the Integration will show up within the instance.

LeanIX Application Properties after LeanIX Integration has been installed.

Key	Type	Details
1	Host Name	Host Name will be the domain in use on the SAP LeanIX side. Example -`customerdomain.leanix.net`. Before the configuration of domain/SSO, it can be the default such as `us.leanix.net` or `eu.leanix.net`. Please do not enter the workspace name under this property as it is determined automatically by the API token set below.
2	API Token	It is recommended to create an additional Technical User as described in the step above that has only a `VIEWER` permission role. The API token of this less privileged user is used here. (This API Token is used to establish a hook between your ServiceNow instance and the SAP LeanIX integration. The connection is used to inform SAP LeanIX about changes in ServiceNow without passing details of the changes itself.)
3	sys_id for Application Registry: LeanIX from table oauth_identity	Value to be updated `a439aa4adb79b300bac3d8c0cf96193e`
4	Log Level	As indicated to keep the log level at the minimum the default is `INFO`. During setup, it can be changed to `DEBUG`.
5	Comma Separated List of tables in Sync from LeanIX workspace	This section does not have to be updated manually. It will be automatically updated according to the configuration and mapping on the SAP LeanIX side.

❗️
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. The following link provides information on how to setup data preservers : ServiceNow Documentation on Data Preservation

Create an Integration user

Within the Users administration section of the ServiceNow instance connected to SAP LeanIX, an Integration user needs to be created.

📘
Web Service Access Only
It is recommended to have this box unchecked during the Integration setup, configuration phase. As it makes it easier to impersonate the Integration user on the ServiceNow side to troubleshoot any access related issues. Once the setup is as expected, it can be reverted back to Web Service Access only.

As part of the installation of the SAP LeanIX application. Some new SAP LeanIX-specific roles are created which will be applied to the Integration user. The roles which are required for the Integration User are -

Role	Table and Permissions Provided by Role	Reason
x_lixgh_leanix_int.admin Contains( ITIL, personalize_dictionary, personalize_choices)	x_lixgh_leanix_int_log (Read, Create,Write, Delete)	Access Application Endpoints Basic Access to interact with CMDB tables Read Choices and Dictionary Attributes
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 the Integration user will be available.
asset	product_model, cmdb_model_category	Read and Write Access to Model Categories and Product Models

Minimum required roles needed for the Integration User

Customised System Tables in ServiceNow

In case of customised ServiceNow for the ACLs, it is necessary to ensure that the Integration User created above has the ability to read the following backend tables -

Table	Reason
sys_choice(Read)	Pre-population and Validation of choices on SAP LeanIX
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 choices once the table is provided. Alternative can be created Read ACL for sys_dictionary.none and sys_dictionary.* with role "x_lixgh_leanix_int.admin"
sys_db_object(Read)	Required to find table referenced by specific field on a table.
cmdb_sam_sw_install(Read)	Required for creating the link between Applications and IT Components (Software)
cmdb_sam_sw_discovery_model(Read)	Required for creating the link between Applications and IT Components (Software)
sys_user (Read)	Required for Subscription mapping. Access to `email`, `first_name` and `last_name` fields is mandatory.

If there are custom ACLs set for the tables that are part of the default configuration, it is necessary to review the access ACLs of the following tables as well.

Additional Information

The following section details specific optional configurations that can be done during the implementation
process.

Add ACLs in ServiceNow

If you want to limit 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 thecmdb_ci_business_app are allowed. If the variable answer is true the ACL will pass, otherwise, the ACL will reject.

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

❗️
Adding a record ACL to a target table like cmdb_ci_business_app, 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_business_app.

Enable OAuth 2.0 for Authentication

OAuth 2.0 can be configured for additional security during the authentication between SAP LeanIX and ServiceNow.

After enabling the plugin, the method used by SAP LeanIX is "OAuth API endpoint for external clients" to retrieve a clientId and a clientSecret. Here is an example -

Once created copy the Client ID and Client Secret and store it in a safe location to use when configuring the Integration on the SAP LeanIX side.

Separate Queue for LeanIX Integration

Use this feature when there is a possibility of long Script Action Processing times or rapid generation of events causing high volumes in the queues. Follow the ServiceNow KB Article on the steps to be performed to create a separate queue.

Review client-adapted ServiceNow Instances

If extensive custom changes have been made to the instance, it is worth it for the ServiceNow admin to review any Business Rules configured in ServiceNow on the tables that are being synchronized and whether they conflict with the Integration synchronization process or not.

🚧
Business rules defined for tables can affect the performance
Be careful with time expensive business rules defined for any table used for synchronisation. If there are rules triggered for actions on a table (creation, update or deletion of items for example), the execution of those rules when records are changed can slow down the response from ServiceNow for each action, slowing down the entire synchronization process.

👍
Successful ServiceNow Setup
After the configuration above for the Integration properties and the user with its roles. The Integration is ready to be configured on the SAP LeanIX side by the admin. It is recommended that the ServiceNow admin reviews the configuration mappings and initial sync runs together with the SAP LeanIX admin for a seamless initial run.