The procedures described in this documentation are best practices for setting up Perspectium DataSync for the typical use cases when sharing data from your ServiceNow instance to target databases and files.
For other ways to get started with DataSync, click here or contact Perspectium Support.
Prerequisites
First, request for the downloadable link for Perspectium for ServiceNow application.
Make sure that the device you are installing the DataSync Agent on meets these basic requirements.
You will also need to request the Agent Installer from Perspectium Support.
You will need the following information from Perspectium Support:
- Perspectium Integration Mesh (MBS) server URL
- Integration Mesh (MBS) username
- Integration Mesh (MBS) password
ServiceNow Install
To install the Perspectium Application for ServiceNow you need to have admin access to the ServiceNow instance and should have received the update set from Perspectium Support which will be imported, validated and committed during installation. You can follow these steps to install in ServiceNow:
- Go to System Update Sets >> Retrieved Update Sets and import the update set xml file.
- Open the update set and click Preview. Errors or warnings are not expected but if there are any those need to be reviewed on a one to one basis.
- Click the Commit Update Set button to commit the update set.
- In the ServiceNow Navigator go to the new Perspectium module and open the Finish Install page.
- Click on the “Confirm” button and wait for a successful confirmation message.
Set up MBS Credentials and Encryption Keys
Once installation is finished you need set up some initial configurations:
- Go to Perspectium >> Properties >> General Settings.
- Enter the Perspectium Message Bus credentials provided to you by Perspectium
- Perspectium Integration Mesh username.
- Perspectium Integration Mesh password.
- Perspectium Integration Mesh server URL - this is usually in the form https://customername.perspectium.net
- The rest of the settings you can leave with their default values and scroll down to the bottom of the page to click Save.
- Go back to Perspectium >> Properties and navigate to the DataSync settings.
- Populate the Encryption key entry with an encryption string of your choice. We advise you to use at least 32 characters encryption key to be able to leverage AES256 payload encryption. This encryption key does not need to be shared with Perspectium. It is used to encrypt the data shared in transit when flowing through the Perspectium message bus so it can be properly secured.
- In the Decryption Key input specify a decryption string which can be used by the ServiceNow instance to descrypt any inbound messages. In many cases you will use the same key as your encryption key so data can be encrypted and decrypted the same in both directions.
- Scroll down to the bottom of the page to save it.
Create Queues
In order to share data to the Perspectium Integration Mesh (Message Broker Service aka MBS) you need to configure at least one shared queue since MBS is queue based. This queue will be used by the ServiceNow instance to share records while the DataSync Agent will subscribe to the same queue in order to be able to receive records, decrypt the shared content and issue the necessary SQL queries to populate those records into the target database.
- Go to Perspectium >> Shared Queues.
- Click the New button to create a new record.
- Set the status to Active.
- In the Queue type select DataSync from the dropdown.
- Enter a name of the queue without spaces e.g. acmedefault.
- You should notice that the queue user, password and encryption key should auto populate based on the details entered in the Perspectium Properties.
- Save the queue and notice in the record header the full queue name with the automatically added prefix. It should look like psp.out.replicator.acmedefault. You will need this queue name later when configuring the DataSync Agent to subscribe to it.
- Click on the Get Queue Status related link to query the Perspectium MBS for the validity of the queue. If the credentials are valid you should get a message indicating that either the queue exist and the credentials are valid or a message saying that the queue does not exist yet due to no sata being shared to it but still have valid credentials and will be auto created once you start sharing records.
- Go to Perspectium >> Subscribed Queues. You should notice one queue already existing there with a name of psp.out.servicenow.instancename where instancename is the name of your ServiceNow instance. Subscribed queues are used by ServiceNow to be able to receive messages form MBS. For example, messages are sent to the instance when the DatraSync agent needs to send some response back to ServiceNow. Usually you are fine with just the default subscribed queue and don’t need to add any more subscribed queues.