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 order

Step

Details

1

Activation of the Integration on the LeanIX side

Please reach out to your CSM or at [email protected] to ensure the Integration is activated on your workspace. Proceed only after confirmation.

Technical User on the LeanIX side

Technical 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 Setup in LeanIX section.

Installation of the LeanIX Integration App(s)

Configuration & Setup of Integration User

Additional Information

Additional information related to the configuration depending on use-cases.

Once the integration is activated on the LeanIX workspace, it is recommended to start the setup of the Integration first on your Sandbox workspace. This allows to ensure the data-mappings, incoming data is as expected before moving to Production data.

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 UserServiceNow Integration Technical User

ServiceNow Integration Technical User

Key

Type

1

Username
It is helpful to name the technical user with contextual username as it will show up in the audit logs.

2

Permission Role
ADMIN is the default role required to have for the Integration to work seamlessly.

3

Customer Roles / ACEs
Does not apply in this use-case and can be left blank.

4

Expiry Date
Depending on 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.

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.

App

Link

LeanIX Integration
Required

Link to the Application

LeanIX Integration SAM add-on
Optional

Link to the Add-on

📘

Requests for applications are approved within 1-2 business days after verification of credentials.

Request the applicationRequest the application

Request the application

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.

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

Enter the API token generated in the step above of the Technical User.

3

Log Level

As indicated to keep the log level at the minimum the default is INFO. During setup it can be changed to DEBUG.

4

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

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

Similar to the technical user on 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 -

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 Categories and Product Models

Minimum required roles needed for the Integration UserMinimum 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 as the ability to read the following backend tables -

Table

Reason

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 as choices once 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 Component (Software)

cmdb_sam_sw_discovery_model(Read)

Required for creating the link between Applications and IT Component (Software)

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.

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

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 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_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');
Sample JavaScript, which limits the write access to only 'cmdb_ci_business_app' table.Sample JavaScript, which limits the write access to only 'cmdb_ci_business_app' table.

Sample JavaScript, which limits the write access to only '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.

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

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 -

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

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 for the ServiceNow admin to review any Business Rules configured in ServiceNow on the tables that are being synchronised and whether they conflict with the Integration synchronisation process or not.

👍

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.


Did this page help you?