Setup in ServiceNow
This documentation covers key information to help you get started with implementing the integration from the ServiceNow side.
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. |
| 2. | 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. |
| 3. | Installation of the LeanIX Integration App(s) | |
| 4. | Configuration & Setup of Integration User | |
| 5. | 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 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.
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 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.
| 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 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
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.
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 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.
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.
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.
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.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.
Updated almost 3 years ago