Setup in ServiceNow

Prepare ServiceNow for Integration

To get the communication between LeanIX and ServiceNow running, the LeanIX Integration app is required which is available in ServiceNow's AppStore. Please install the app from the AppStore.

Install app from ServiceNow Store

Click here to find the appropriate application.

1

Select the option to purchase the application. Make sure to select the most recent version of the app available for your version of ServiceNow

2

Log in to your ServiceNow Enterprise account as an admin

3

Open the System Applications → Applications module and click the Downloads tab to view the LeanIX Integration application

4

Click Install on the 'LeanIX Integration' application

Configure the app 'LeanIX Integration'

After successful installation, you will have a new menu item in SN:

ServiceNow menu after LeanIX Integration has been installed.ServiceNow menu after LeanIX Integration has been installed.

ServiceNow menu after LeanIX Integration has been installed.

In the 'LeanIX Properties', you are required to add an API-token, which you created in the previous step, and a 'host_name', e.g. 'app.leanix.net' or 'us.leanix.net'. On default, the 'log_level' is set to 'INFO'. Setting the 'log_level' to 'DEBUG' is recommended only to troubleshoot and not in a productive environment.

ServiceNow properties configurationServiceNow properties configuration

ServiceNow properties configuration

❗️

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. Link provides information on how to setup data preservers : ServiceNow_link

Setup an Integration User and ACLs

If you specify that data is synchronised from LeanIX to SN, then the user that you specify in the 'Integrations' part in LeanIX's admin section of the workspace requires the application role x_lixgh_leanix_int.admin and write access to the tables at hand. If LeanIX is to be master side for the synchronisation of a table, the right to 'create' and 'write' is necessary as well. If you decide to enable the strict mode (i.e. having unsynchronised slave objects deleted), then the permission to 'delete' is necessary as well.

Create an Integration user

Create a new integration user, for example leanix.integration, mark 'Web service access only' as 'True'. It is recommended that the integration user have limited access.

Roles

The roles which are required for the Integration User.

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 Category and Models

Customised System Tables in ServiceNow

In case you have a customised ServiceNow for the ACLs, below are some of the tables which we need read access to along with the one's you want to configure to pull/push information information.

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

Only required if SAM module should be used

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 for REST communication

If you want to use OAuth for communication, please active OAuth as described in ServiceNow's documentation and configure one "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 oauth 2This example shows one OAuth API Application Registration used for communication between LeanIX and ServiceNow via oauth 2

This example shows one OAuth API Application Registration used for communication between LeanIX and ServiceNow via oauth 2

Separate Queue for 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.

We will suggest to use Queue Name : leanix_integration

Follow the ServiceNow KB Article on the steps to be performed.

Pitfalls on User Adapted SN systems

One should find out what 'Business Rules' are configured in SN on the tables that are being synchronised and whether they conflict with the synchronisation process.

🚧

Business Rules and Uniqueness

Find out what 'Business Rules' are configured in SN on the tables that are being synchronised and whether they conflict with the synchronisation process, e.g. one customer had a business rule in place that prohibited the creation of objects with the exact same name in one of the tables to synchronise.

This itself is not a problem: In LeanIX fact sheet names are unique per fact sheet type as well. However, LeanIX compares names by ignoring any letter cases. SN by default checks for exact matching including the upper and lower case of characters.