Step 6 - Configure your ServiceNow to be ready for CI Sync
Task List
Task #
Task
Performed by
1
Configure the Batch API timeout
ServiceNow Admin
2
Configure the CMDB CI Software Package Name field for increased performance
ServiceNow Admin
3
Create a User Account (to be used by the CI Sync SaaS application)
ServiceNow Admin
4
Configure permissions on the new User Account
ServiceNow Admin
5
(Optional) Configure OAuth Authentication on the CI Sync User Account
ServiceNow Admin
6
(Optional) Consider applying additional changes to ServiceNow to support the specific requirements of source systems
ServiceNow Admin
Task 1: Configure the Batch API timeout
Navigate to your ServiceNow at this URL:
https://YourInstance.service-now.com/sysrule_quota_list.do?sysparm_query=nameLIKEbatch
From the list, locate the entry where the Name is “Rest Batch API request timeout”
Change the “Maximum Duration (seconds)” to 60, then click Update
Task 2: Configure the CMDB CI Software Package Name field for increased performance
This task only applies to customers syncing Installed Software records in the CMDB (i.e. into the cmdb_ci_spkg table).
If you are not sync’ing Installed Software records there is no need to perform this task.
Click to expand a Context Note (about why this task may be beneficial to customers sync'ing Installed Software)
The standard configuration of the “Software” (table: cmdb_ci_spkg) table has the “Package name” (field: package_name) field set as the Display field for the table.
The Package name field is a calculated fields which results in the table API performing additional redundant lookups.
Unchecking the Display property improvement in synchronization performance by approximately ten (10) times (i.e. Installed Software will sync around 10x faster thanks to this setting).
There are two options for completing the configuration of your ServiceNow instance.
Option
Summary and Link to Detailed Instructions
Option 1 – Automated Steps using Update Set
Download a Syncfish supplied Update Set, import, preview and commit.
Each of the above options achieves the same end-result. That is, each option applies the following changes:
Updates the dictionary record to display=False on the table “cmdb_ci_spkg” for column “package_name”
Add the “Package name” field to the “List Layout” on each of the following CI Class default views:
AIX Server
Computer
ESX Server
HPUX Server
Hyper-V Server
Linux Server
Netware Server
OS/X Server
Solaris Server
UNIX Server
Windows Server
Task 2 (Option 1): Automated Steps using Update Set
Expand the instructions below to use a ServiceNow Updateset (provided by Syncfish) to update the dictionary value on the various CI classes.
Click to expand the instructions for Option 1
Informational Note (about what the updateset updates)
The update set includes two types of update as follows.
It updates to the Dictionary on the table “cmdb_ci_spkg”.
It adds the “Package name” field to the default “List Layout” on a few CI Classes
These two updates are shown in the screen below.
When you preview the update set you may see preview errors if the above List Layouts have already been modified in your ServiceNow instance. If you receive preview errors and use the instructions further below to decide how best to proceed. If in doubt contact Syncfish for assistance.
Open a browser and navigate to your ServiceNow instance
In the left nav menu search for “Retrieved Update Sets” and click to open
Right click on the column heading row and select “Import XML”
Select “Choose File”
Select the downloaded file “cisync-fix-software_instance-import-slowness.xml”
Click to open the Update Set
Click “Preview Update Set”
If there are no preview errors, Click “Close” and proceed to Step 12 below to Commit the Update Set.
If there are preview errors, they are likely to be related to the List Layout update (as described in the Informational Note at the start of this task). Use the details below to diagnose and resolve the errors and if in doubt contact Syncfish for assistance.
View the errors in the ‘Update Set Preview Problems’ shown below.
Make sure all the errors are related to the UI List view updates and the error is not for the Dictionary update then you can Skip the remote update in the Available Actions list.
In the list, click on the record called cmdb_ci_spkg to open it.
Uncheck the Display checkbox.
Click Update.
Next, you need to update the “Software Installed” Related Lists column layout for a number of CMDB CI record types.
To begin with, execute the steps below to update the Windows Server – Default view(and the repeat these steps for the additional CI record types noted further below).
Navigate to the list of “Windows Servers” in your CMDB and open a server record.
Scroll down to the form to see the Related Lists (the set of tabs at the bottom of the form)
Click “Software Installed”
Right click the column heading (e.g. Package Name) within the “Software Installed” Related List
Select “Configure”
Select “List Layout”
In the Available list select “Product Name”, select “Expand selected reference field” in the middle buttons between the “Available” list and “Select” list
Scroll down to find “Package name” under the “.Product Name --> Software Fields”
Select “Package name”
Select the “Add” button
“Package name” should now be added to the “Selected” list on the right-hand side
Click “Save”
Repeat the above steps by navigating to each of the following CMDB CI record types and amending each of their “Software Installed” Related List:
Task 3: Create a User Account (to be used by your CI Sync SaaS instance)
Create a ServiceNow user account. It is recommended that it be named accordingly so users can identify the records created/updated by the integration. e.g. “cisync.integration”.
Log into ServiceNow as an Administrator
Navigate to System Security → Users
Click New to start creating a new account for the CI Sync integration
Some key points when creating the account:
Enter a User ID, First name and Last name that allow the CI Sync account to be easily identifable in the future.
The way you set the password will vary depending on your edition of ServiceNow. Make sure you know/capture the password as you’ll need it later on.
Set the Language to English in all cases. Important: If you set Language to anything other than English it will cause issues when you start to run synchronization jobs.
Set the Time zone to GMT
Syncfish recommend tagging the account as a non-interactive account. The way you do this varies based the version and patch level of your ServiceNow. Here are some guidance notes
The two ways to flag the account are:
Either, tick the “Web service access only” checkbox (as shown in the screen shot above)
Or, set the “Identify Type” as “Machine” (as shown in the screen shot direclty below)
Filter/Select the roles below and click the Save button
asset
cloud_admin
model_manager
personalize_choices
snc_platform_rest_api_access
tracked_file_reader
user_admin
Depending on certain conditions, several additional roles may be required, Click here for further information
Some additional permissions may be required depending which source systems you intend to use with CI Sync. See the table below and then add any additional roles accordingly.
Scenario
Additional permissions required by the CI Sync Integration User Account
If you intend to sync Tags from most cloud sources (Azure, AWS, GCP) an ACL update is needed.
The CI Sync Integration Account will need read/write on the cmdb_key_value table.
See Task 6 further below for more details.
If you intend to sync OT Assets from Lansweeper the CI Sync Integration user requires an additional role.
The CI Sync Integration Account will need the “cmdb_ot_editor” role.
See Task 6 further below for more details.
If you intend to create Application Service Mapping relationships from Lansweeper or Azure the CI Sync Integration user requires an additional role.
The CI Sync Integration Account will need the “app_service_admin” role.
See Task 6 further below for more details.
If you intend to sync Software Licence Key data from Lansweeper the CI Sync Integration user requires an additional role (possibly two roles).
The CI Sync Integration Account will need the “sam” role (and if you have installed the ServiceNow SAM Plug-In, you will also need the “sam_admin” role).
See Task 6 further below for more details.
If you intend to sync CVE data from MS Defender for Endpoint an ACL update is needed.
The CI Sync Integration Account will need read/write on the alm_licence and alm_entitlements tables.
Click Save. Then use the “Roles” tab to check the above roles and the various inherited ones have been applied by comparing to screen shot below.
Click to expand an Informational Note (about the permissions granted)
By granting these ServiceNow Out-of-the-Box (OOTB) Roles you are permitting the cisync user account, and therefore the CI Sync SaaS application access to your ServiceNow environment to the extent afforded by these roles.
It is probably these OOTB Roles grant CI Sync access to ServiceNow tables that are not needed or in-scope for CI Sync. A good example is the sys_user table in ServiceNow. The default CI Sync configuration rules do require the CI Sync SaaS application to access the sys_user, however the user_admin role grants such access (the user_admin role is needed for access to other reference tables (such as the core_company table) that stores manufacture reference data).
Syncfish recommend you review the ServiceNow system documentation (and system itself) to understand the permissions these roles provide to your CI Sync SaaS application.
Syncfish provide further details on this topic in the document titled “CI Sync - Overview of Source and Destination Fine Grain Permission Option for Personal Data”. The document also includes non-authoritative guidance on how to assess and potentially apply fine-grain permissions to further restrict CI Sync’s access within ServiceNow, in particular if your organization has concerns about Personal Data.
Task 5: (Optional) Configure OAuth Authentication on the CI Sync User Account
The CI Sync SaaS application supports the following authentication methods provided by the ServiceNow platform for API integrations:
Basic Auth
OAuth
Use the instructions below to configure OAuth Authentication if this is requried by your organisation.
You don’t need to use these OAuth instructions if you have decided to use Basic Auth.
Click to expand the instructions if using OAuth
Setting up the ServiceNow end of an OAuth endpoint is typically performed by a ServiceNow SME with specific knowledge of this functionality.
Also, different editions of ServiceNow may have different requirements for an OAuth endpoint.
The ServiceNow related instructions provided below are intended as a high level guide only, and are provided by Syncfish for general guidance.
If a Syncfish customer is unsure how to setup the ServiceNow elements for OAuth authentication for the incoming CI Sync connection, then we recommend the following:
Read the ServiceNow documentation on this same topic. The ServiceNow documentation can be less than clear, so if in doubt, contact your ServiceNow SME with OAuth experience. For ServiceNow Zurich release here are two articles Syncfish recommend are read in the order below
Navigate to All > System Properties > All Properties >
Filter for *oauth*
Make sure glide.oauth.allow.parameters.in.post.body.only is set to true
Step 4 - Create an OAuth application endpoint for external client applications to access the ServiceNow instance (i.e. create an OAuth endpoint for CI Sync to target for authentication)
Navigate to All > System OAuth > Application Registry and then click New.
On the interceptor page, click Create an OAuth API endpoint for external clients.
Complete the fields on this form using the screen shot below and the following points for guidance
Name: Use a meaningful/recognisable name relative to the endpoint being for CI Sync.
Client Secret: Enter a complex secret or allow ServiceNow to generate one on save.
Redirect URL and Logo URL: No need to enter these.
Public Client: No need to tick this.
Client Type: Integration as a service.
Application: Global scope.
Accessible from: All application scopes (or as otherwise directed by your ServiceNow SME).
Active: Tick.
Other settings: Leave as default (or as otherwise directed by your ServiceNow SME).
Note: This form may differ between versions of ServiceNow.
Once the OAuth setup is completed, open the application registry record created and copy the Client ID and Secret to setup the connection in the CI Sync SaaS application User Interface
Guidance Note
Click the Client Secret padlock to view/copy the secret.
Data Capture Note
Take note of the Client Id and Client Secret as they will be required when configuring the ServiceNow connection within the CI Sync SaaS application (via the CI Sync User Interface) when performing the tasks in S7 - Add your ServiceNow Instance as a Destination for CI Sync.
Task 6: (Optional) Consider applying additional changes to ServiceNow to support the specific requirements of source systems
Informational Note
The tasks in this section are optional depending on which source systems you intend to use with CI Sync.
Click to expand the detailed instructions in this section relative to the source systems you may be using with CI Sync.
CMDB CI Class Models plug-in
These instructions are relevant to the following source systems
Lansweeper IT (from Lansweeper On-Prem)
Lansweeper OT (from Lansweeper On-Prem)
Lansweeper OT (from Lansweeper Cloud)
Azure
AWS
Click for context and task instructions
Context
Several data sources used by CI Sync include record sets that rely on CI Classes only available via the CMDB CI Class Models plug-in.
If you plan to synchronize any of the following data sources and recordsets you will need to add the CMDB CI Class Models plug-in to your ServiceNow instance.
If you already have the plug-in you may want to upgrade it to the latest version (as ServiceNow occasionally update the plug-in to including extra CI Classes/tables).
Source System
Specific Record Sets that require the CMDB CI Class Models plug-in
Lansweeper IT
(from Lansweeper On-Prem)
IP Cameras
Lansweeper OT
(from On-Prem Lansweeper)
PLCs
Modules
Lansweeper OT
(from Lansweeper Cloud)
OT PLC
OT Field Device
OT Human Machine Interface
OT Industrial Device
OT Industrial Sensor
OT Module
OT OPC Server
Azure
Many/most Azure resources supported by CI Sync.
Synchronizing of Azure Tags into the cmdb_key_value table.
AWS
Many/most AWS resources supported by CI Sync.
Synchronizing of Azure Tags into the cmdb_key_value table.
Task Steps
Follow these steps to add this plug-in (and similar steps to locate it and upgrade it if required)
Assess the use/inclusion of this plug-in within your ServiceNow (ensure you are comfortable installing this plug-in).
Search for Plugins via the ServiceNow navigation menu.
Locate the CMDB CI Class Models plug-in.
Click Add -> Install and follow the instructions provided.
Add permissions for CI Sync to write to the cmdb_key_value table to support Cloud Tags
These instructions are relevant to the following source systems
Azure (for synchronizing Azure Tags to ServiceNow)
AWS (for synchronizing AWS Tags to ServiceNow)
Click for context and task instructions
Context
CI Sync writes Tags (or GCP Labels) to the cmdb_key_value table in ServiceNow.
The standard/out-of-the-box roles provided by ServiceNow (and recommended by Syncfish earlier in this page) do not provide access to the cmdb_key_value table. Therefore, the CI Sync Integration User account created above requires additional permissions to write to the cmdb_key_value table.
Syncfish provides a ServiceNow updateset to prepare your ServiceNow instance for CI Sync. The updateset does the following:
Creates a read/write ACL on the cmdb_key_value table.
Applies the ACL on the cmdb_key_value table and assigns the ACL to the ServiceNow role called “Asset” (which is one of the roles granted to the CI Sync Integration Account created above).
Task Steps
Follow these steps to apply the updateset provided by Syncfish:
Login to your ServiceNow instance with Admin permissions.
Open a browser and navigate to your ServiceNow instance
In the left nav menu search for “Retrieved Update Sets” and click to open
Right click on the column heading row and select “Import XML”
Select “Choose File”
Select the downloaded file “cisync-cmdb-key-value.xml”
Click to open the Update Set
Click “Preview Update Set”
If there are no preview errors, Click “Close”.
Click “Commit Update Set”.
Your ServiceNow instance is now ready to receive Azure Tag data from Azure via sync jobs from CI Sync.
Add custom tables and grant permissions for CI Sync to write CVE data to ServiceNow for MS Defender for Endpoint
These instructions are relevant to the following source systems
MS Defender for Endpoint (for synchronizing CVE data to ServiceNow)
Click for context and task instructions
Context
CI Sync synchronizes IT assets including their installed software with known CVEs from Defender for Endpoint.
CI Sync relies upon two custom tables in ServiceNow.
One table is used to store the CVE records.
A second table stores the link between CIs and the CVEs.
Syncfish provides a ServiceNow updateset to prepare your ServiceNow instance for CI Sync. The updateset does the following:
Creates the custom tables mentioned above.
Applies the ACL on the custom tables and assigns the ACL to the ServiceNow role called “Asset” (which is one of the roles granted to the CI Sync Integration Account created earlier in this page).
Task Steps
Follow these steps to apply the updateset provided by Syncfish:
Login to your ServiceNow instance with Admin permissions.
Open a browser and navigate to your ServiceNow instance
In the left nav menu search for “Retrieved Update Sets” and click to open
Right click on the column heading row and select “Import XML”
Select “Choose File”
Select the downloaded file “cisync-cmdb-vulnerabilities.xml”
Click to open the Update Set
Click “Preview Update Set”
If there are no preview errors, Click “Close”.
Click “Commit Update Set”.
Your ServiceNow instance is now ready to receive CVE data from MS Defender for Endpoint via sync jobs from CI Sync.
Add permissions for CI Sync to write Lansweeper Software Licence Key information to ServiceNow
These instructions are relevant to the following source systems
Lansweeper On-Prem
Click for context and task instructions
Context
If the customer plans to sync Software Licence Key records from Lansweeper then CI Sync needs additional permissions to create/update records in the following ServiceNow tables:
alm_licence (This table contains record for each unique Model/Asset/Product combination in the Lansweeper tblSerialNumber table. This record represents the Product License record containing the license key value Lansweeper retrieved from the windows computer.
alm_entitlements (This table contains record for each unique Model/Asset/Product combination in the Lansweeper tblSerialNumber table. This record links the Software License [alm_license] record to the Windows Computer CI in the CMDB).
Also, if you have installed the SAM Pro Module/Plug-In, CI Sync requires the sam_admin role.
The ServiceNow out-of-the-box roles described below provides the required permissions and therefore this role needs to be applied to your CI Sync Integration User if you intended to use CI Sync’s Software Licence Key synchronization feature.
Task Steps (to grant access to the two alm_* tables notes above)
Navigate to the cisync user account (e.g. “cisync.integration” or the name you used earlier on this page)
Select the Roles tab and click the Edit… button
Filter/Select the roles below and click the Save button
sam
Click Save. Then use the “Roles” tab to check the above role has been applied.
Task Steps (if you have the SAM Pro Module/Plug-In installed in your ServiceNow)
Navigate to the cisync user account (e.g. “cisync.integration” or the name you used earlier on this page)
Select the Roles tab and click the Edit… button
Filter/Select the roles below and click the Save button
sam_admin
Click Save. Then use the “Roles” tab to check the above role has been applied.
Add permissions for CI Sync to create Application Service Mapping relationships in ServiceNow
These instructions are relevant to the following source systems
Lansweeper On-Prem
Azure
Click for context and task instructions
Context
CI Sync needs additional permissions to create/update Application Service relationships in ServiceNow.
The ServiceNow out-of-the-box role described below provides the required permissions and therefore this role needs to be applied to your CI Sync Integration User if you intended to use CI Sync’s Application Service Mapping feature..
Please contact Syncfish if a custom role is preferred over this out-of-the-box role.
Task Steps
Navigate to the cisync user account (e.g. “cisync.integration” or the name you used earlier on this page)
Select the Roles tab and click the Edit… button
Filter/Select the roles below and click the Save button
app_service_admin
Click Save. Then use the “Roles” tab to check the above role has been applied.
Add permissions for CI Sync to create and update OT CIs in ServiceNow
These instructions are relevant to the following source systems
LansweeperOn-Prem
Click for context and task instructions
Context
CI Sync needs additional permissions to create/update OT CIs in the ServiceNow CMDB.
The ServiceNow out-of-the-box role described below provides the required permissions and therefore this role needs to be applied to your CI Sync Integration User if you intended to sync OT Assets into the CMDB.
Please contact Syncfish if a custom role is preferred over this out-of-the-box role.
Task Steps
Navigate to the cisync user account (e.g. “cisync.integration” or the name you used earlier on this page)
Select the Roles tab and click the Edit… button
Filter/Select the roles below and click the Save button
cmdb_ot_editor
Click Save. Then use the “Roles” tab to check the above role has been applied.