Install and Configure OpenLM External Platform – KB881
The following document describes the process for installing the OpenLM ServiceNow Adapter. The External Platform Service configuration is also covered in order to make the Adapter establish a successful connection between OpenLM Server and ServiceNow.
This guide covers:
The following components are required for the OpenLM ServiceNow Adapter to work:
1. The OpenLM ServiceNow application in your ServiceNow account
2. A working installation of OpenLM Server v4.6 or higher
3. OpenLM Server configured to use MySQL 5.7 or 8 or MSSQL 2012 and up
4. An OpenLM Server license that has support for External Platforms. To verify, go to EasyAdmin Start → Administration → OpenLM License. Look for the External_Platforms flag:
In case your license is missing support for External Platforms, please contact firstname.lastname@example.org for assistance.
The steps for installing the ServiceNow Adapter are as follows:
1. Obtain the latest External Platforms Service & ServiceNow Adapter installer file (OpenLM_ServiceNow_Adapter_Installer_#.#.###.msi) from our Downloads page
2. Double-click the installer file to run it.
3. Check the “I agree to the license terms and conditions” box.
4. Click Next.
5. If you want to install the External Platforms & ServiceNow Adapter to a different location, click Browse and navigate to the destination folder of your choosing.
6. Click Next to begin the installation. Please note that this step may take up to several minutes depending on your hardware specifications.
7. Once the installer has finished, click Finish to close the window. This will open the External Platforms UI configuration screen which is described in the section below.
The External Platforms Service must be configured and connected to the OpenLM Server in order for the ServiceNow integration to work. The External Platforms configuration screen can be opened in a number of ways:
- Automatically, at the successful conclusion of the ServiceNow Adapter installation after the user has clicked the “Finish” button.
- Through the shortcut found in Start Menu → OpenLM → OpenLM External Platform Configuration
- By accessing the OpenLM Server address dedicated to the External Platforms Service in your browser (by default: http://localhost:5005/)
The purpose of this screen is to configure and test the connection between the External Platform Service and your installation of OpenLM Server. The fields are as follows:
- URL – Enter the path to your OpenLM Server with either http:// or https:// and the listening port (default v4: 7014; v5: 5015). E.g. http://localhost:5015
If you’re connecting to an SSL port of OpenLM, make sure that you have followed the OpenLM SSL configuration guide before you proceed.
- Require Login Credentials – toggle this if you have set up OpenLM to require login credentials
- User – the OpenLM Server user account
- Password – the OpenLM Server password for the user account
Once you have filled in the required fields, click on Test Connection to verify that a connection can be established. Please note that you will be able to advance the wizard only if a successful connection can be established. In case of success, you should see the following message:
If you see instead an error message similar to the one below, please check that:
- The correct OpenLM Server login credentials have been provided (if Server authentication is turned on)
- The correct port has been specified
- The Server URL is spelled correctly
- The OpenLM Server is up and running
- The OpenLM Server version is at least 4.6
- All database requirements from section 1 (“Requirements”) of this document have been met
- There are no firewall roles, security policies or other applications preventing communication on that port or between your machine and the OpenLM Server
To finalize the ServiceNow integration with OpenLM, you must launch the External Platforms Setup Wizard from the EasyAdmin interface.
To do so:
1. Open the EasyAdmin User Interface in the browser by going to Start Menu → OpenLM → OpenLM EasyAdmin User Interface
2. Go to EasyAdmin Start → Administration → click on External Platforms
3. The ServiceNow Setup Wizard will open.
Fill in the required fields as follows:
ServiceNow URL – The path to your ServiceNow instance. For example, https://abc123.service-now.com
Username – Your ServiceNow account username.
Password – Your ServiceNow account password.
4. Click Test Connection. Please note that you will be able to advance to the next screen only if the test is successful, as indicated by this notice in the UI:
5. Click Next to advance to the Sync Configurations screen.
This screen holds the options for configuring the synchronization of OpenLM with ServiceNow.
Select range to sync your data – You can pick the time range for the sync. Three options are available:
- Period – this will synchronize all the data within the selected time period
- Start date – this will synchronize all the data beginning with the selected start date up until today
- All available data – this will synchronize all data available from the OpenLM database
Schedule sync to run every day at – Specify the time you would like the synchronization of OpenLM with ServiceNow to start at.
Sync Now (Run initial sync at the end of this wizard) – turning this toggle on will start the initial synchronization as soon as you have completed all the steps and finished the Wizard configuration. Leaving it off means that the sync will begin at the scheduled sync time above.
6. Click Next.
7. On the ServiceNow Time Zone screen, select the time zone by which OpenLM will synchronize the aggregated data it sends to ServiceNow. Since synchronization once per day, you must specify the time zone by which OpenLM will adjust the time calculations.
8. Click Next to advance to the Notifications configuration part of the Wizard.
9. Configure the options on this screen as follows:
Notifications (on/off) – this is a global switch that enables or disables all sync notifications.
EasyAdmin Alerts (on/off) – this switch enables or disables notifications in the EasyAdmin user interface.
Email (on/off) – this switch enables or disables email notifications.
Notifications to both EasyAdmin and email can be sent whenever a sync has either:
- When the External Platform service is not reporting back to the OpenLM Server
Recipients – if the email switch has been turned on, enter the email(s) which you want to receive the notifications. For multiple emails, each email must be placed on its own line
10. Click Finish to commit the new ServiceNow configuration and close the Wizard.
11. In the ServiceNow interface, simply add a scoped application user that requires the following roles:
12. In the ServiceNow interface, go to your “Plugins” section and search for “OpenLM”. After finding it click on Install to install the OpenLM API on the ServiceNow side.
At this point configuration on the External Platforms side is complete. To finish the configuration, follow the steps in section 5 below.
Only for customers who have Domain Separation activated on their instances
In the ServiceNow navigation panel, navigate to Scripts – Background module and open this in a new tab. Copy the script from OpenLM Integration: Domain Field Fix Script and paste it in the Run Script field in Scripts – Background tab
Set the scope to global and click on Run script to execute.
For the customers which do not want to execute this script, they can go the Transform Map corresponding to each of the staging table and activate coalesce value and set choice action to reject on sys_domain field by following these steps:
1. Navigate to Transform Maps module which is present under the Administration subsection of System Import Sets
2. Click on the Filter icon and add Application is OpenLM Data Integration. Click on the Run button
3. Open each of the record and update the sys_domain mapping under Field Maps section to true and choice action to reject and click on the Update button when done.
The following records must be updated:
Information note: When creating an integration user in a domain separated environment, the integration user should be assigned to the appropriate domain and should not be part of a global domain as the data gets inserted into the domain the integration user is part of. Assigning a wrong/global domain to a user leads to the data being inserted in the wrong domain and can be visible to all users.