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.
|Activation of the Integration on the LeanIX side
|You 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.
|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 the Setup in LeanIX section.
|Installation of the LeanIX Integration App(s)
|Configuration & Setup of Integration User
|Setup of Integration User
|Additional 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.
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 -
It is helpful to name the technical user with a contextual username as it will show up in the audit logs.
ADMIN is the default role required to have for the Integration to work seamlessly.
|Customer Roles / ACEs
Does not apply in this use case and can be left blank.
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 -
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.
In your ServiceNow instance:
- 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.
After successful installation, properties for the Integration will show up within the instance.
|Host Name will be the domain in use on the LeanIX side.
Before the configuration of domain/SSO, it can be the default such as
Please do not enter the workspace name under this property as it is determined automatically by the API token set below.
|Enter the API token generated in the step above of the Technical User.
|sys_id for Application Registry: LeanIX from table oauth_identity
|Value to be updated
|As indicated to keep the log level at the minimum the default is
INFO. During setup, it can be changed to
|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 Tokenon 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
Within the Users administration section of the ServiceNow instance connected to 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 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 -
|Table and Permissions Provided by Role
Contains( ITIL, personalize_dictionary, personalize_choices)
(Read, Create,Write, Delete)
|Access Application Endpoints
Basic Access to interact with CMDB tables
Read Choices and Dictionary Attributes
|filter_global OR filter_group
|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.
|Read and Write Access to Model Categories and Product Models
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 -
|Pre-population and Validation of choices on LeanIX
|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"
|Required to find table referenced by specific field on a table.
|Required for creating the link between Applications and IT Components (Software)
|Required for creating the link between Applications and IT Components (Software)
|Required for Subscription mapping. Access to
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.
The following section details specific optional configurations that can be done during the implementation
If you want to limit access of your
The example below checks, that only modifications to the
cmdb_ci_business_app are allowed. If the variable
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.
OAuth 2.0 can be configured for additional security during the authentication between LeanIX and ServiceNow.
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 -
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.
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.
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.
Updated about 2 months ago