Setup in ServiceNow

👍

Access

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

Steps orderStepDetails
1Activation of the Integration on the LeanIX sideYou may reach out to support at LeanIX Support or reach out to your CSM to ensure the Integration is activated on your workspace. Proceed only after the confirmation.
2.Technical User on the LeanIX sideTechnical user created on the 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 LeanIX section.
3.Installation of the LeanIX Integration App(s)ServiceNow Store
4.Configuration & Setup of Integration UserSetup of Integration User
5.Additional InformationAdditional information related to the configuration depends on use-cases.

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

Technical User on the LeanIX side

The LeanIX admin has the ability to create a technical user account to be used when integrating with external users. This helps in auditing as well as the management of API Tokens.

Within the technical user section, create a new Technical user with the following suggested configuration:

ServiceNow Integration Technical User

ServiceNow Integration Technical User

KeyType
1Username
It is helpful to name the technical user with a contextual username as it will show up in the audit logs.
2Permission Role
ADMIN is the default role required to have for the Integration to work seamlessly.
3Customer Roles / ACEs
Does not apply in this use case and can be left blank.
4Expiry Date
Depending on the security policy on refreshing API Tokens regularly, the API token expiry can be set. Please note that it is not possible to automatically update the Integration Application on the ServiceNow side with the regenerated token.

Once saved the technical user will be created and an API token is generated to be used -

Please copy the generated API token immediately as it is not shown again.

Please copy the generated API token immediately as it is not shown again.

Installation of LeanIX Integration App

To get the communication between 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.

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

Request the application

Update LeanIX Integration App (for admins)

In your ServiceNow instance:

  1. go to System Applications > All Available Applications > All.
  2. Find the application with the filter criteria and search bar.
  3. Next to the application listing, select the version to install.
  4. 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.

LeanIX Application Properties after LeanIX Integration has been installed.

KeyTypeDetails
1Host NameHost Name will be the domain in use on the 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.
2API TokenIt 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 LeanIX integration. The connection is used to inform LeanIX about changes in ServiceNow without passing details of the changes itself.)
3sys_id for Application Registry: LeanIX from table oauth_identityValue to be updated a439aa4adb79b300bac3d8c0cf96193e
4Log LevelAs indicated to keep the log level at the minimum the default is INFO. During setup, it can be changed to DEBUG.
5Comma Separated List of tables in Sync from LeanIX workspaceThis section does not have to be updated manually. It will be automatically updated according to the configuration and mapping on the 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 LeanIX, an Integration user needs to be created.

3496

Similar to the technical user on the LeanIX side, the username can be anything preferable to provide contextual information during auditing.

📘

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 LeanIX application. Some new LeanIX-specific roles are created which will be applied to the Integration user. The roles which are required for the Integration User are -

RoleTable and Permissions Provided by RoleReason
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_groupsys_filterRead 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.
assetproduct_model, cmdb_model_categoryRead and Write Access to Model Categories and Product Models
Minimum required roles needed for the Integration User

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 -

TableReason
sys_choice(Read)Pre-population and Validation of choices on 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/Write)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.

3496

Ensure that the LeanIX Integration user within its scope can make the intended changes in the tables.

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');
3496

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

❗️

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 LeanIX and ServiceNow.

3496

LeanIX Integration uses the "oAuth API endpoint for external clients" method.

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

3496

This example shows one OAuth API Application Registration used for communication between LeanIX and ServiceNow via oAuth2.0

Once created copy the Client ID and Client Secret and store it in a safe location to use when configuring the Integration on the 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 LeanIX side by the admin. It is recommended that the ServiceNow admin reviews the configuration mappings and initial sync runs together with the LeanIX admin for a seamless initial run.