Welcome

Congratulations on your decision to use Unifi, the only integration platform you need for ServiceNow. We are sure you will be more than satisfied with this extremely powerful, versatile and technically capable solution.

Scope

We have created this Guide as an aid to customers who are beginning their journey in deploying the Unifi integration platform. This document will guide you through an example of how to configure a bidirectional asynchronous Incident integration, sending and receiving messages via the Scripted REST Service.

This guide is here to help you get up and running as quickly as possible, enabling you to realise the enormous benefits to be gained when using Unifi to configure your integration.

For more technical information on how to use Unifi, please see our technical documentation.

Warning

Guide Structure and Testing Approach

All of the configuration is carried out in Unifi Integration Designer (our portal interface) - Processes, Integrations, Connections, Messages, Fields & Field Maps are configured manually. The remaining configuration elements (Web Service & Trigger) - which were previously configured in native ServiceNow - are automatically created by Unifi.

We have structured this Guide to align with the testing approach. Firstly, we shall configure the main elements which have to be in place for the Integration to work, then we shall move on to build & test each of the scenarios individually. For example, build the CreateIncident Message (along with CreateIncidentReceipt & Response), configure the relevant Fields for those Messages and then test the CreateIncident Message. Then do the same for the UpdateIncident Message (& Receipt) and so on.

Some Dos & Don’ts

We want to include some advice on things to be aware of - either to ensure you do them, or avoid doing them - when building & testing Unifi integrations; in particular and especially if many people are building in one instance at the same time (whether that be a training instance or sub-production instance).

Installation

The prerequisite to configuring Unifi is to have it installed on your instance. As with any other ServiceNow scoped application, Unifi must be purchased via the ServiceNow Store before installation.

We recommend you follow the Setup instructions prior to configuring your Integration.

Scripted REST API

In native ServiceNow, navigate to System Web Services > Scripted Web Services > Scripted REST APIs. Click Unifi.

Scripted REST Resources

Navigate to the Resources Related List.

Updated Process

We will now continue to configure the Integration.

The first thing to do when creating a new integration is to assign it to its Process. For instance, a new Incident integration would be created within an Incident Process. If you do not yet have a Process defined, then you will need to create a new Process

From the Unifi Integration Designer Dashboard, click on New Process.

On the 'New Process' modal, the fields to be configured are as follows:

Your 'New Process' modal should look like this:

Click Create.

You will be redirected to your Process Dashboard:

Click either the '+' tile or 'New Integration' in preparation to configure the Integration.

Before we configure the Integration, let's view the Web Service which Unifi has automatically created.

Unifi Integration Designer

From within native ServiceNow, open the Unifi Integration Designer portal by navigating to Unifi > Unifi Integration Designer.

Dashboard

You will be greeted with the following Dashboard (which opens in a new window):

Any existing Processes will be listed as tiles, showing the number of Active Integrations for each. The total number of Active Integrations is also shown on the Dashboard.

Hovering over the tile of an existing Process will display 'Show integrations'. Clicking it will take you to the Integrations page (for that Process).

If appropriate, you can either edit the Settings of, or add a New Integration to an existing Process by clicking the ellipsis (at the bottom right of the tile).

In the next section, we shall look at configuring a new Process.

New Integration

Back in the Unifi Integration Designer window, after clicking either on the '+' tile or 'New Integration', you are given a 'New Integration' modal to complete.

The fields to be configured for the New Integration modal are as follows:

Your 'New Integration' modal should look like this:

Click Create.

You will be redirected to the Details page of the newly created Integration.

Icons

The icons are:

a) 'Integration' icon: Opens the current integration's Details page.

b) 'Messages' icon: Opens the current integration's Messages page.

c) 'Fields' icon: Opens the current integration's Fields page.

d) 'Field Maps' icon: Opens the current integration's Field Maps page.

e) 'Documentation' icon: Opens the automatically generated documentation for the current integration. (Another awesome feature in Unifi.)

f) 'Connections' icon: Opens the current integration's Connections page.

Details

The Details page of your Integration should look like this:

Navigate to Integration > Message Identification.

Message Identification Fields

Update the code in the 'Identify message script' field so that it looks like this:

function identify(payload) {

  return (payload.message.name || '') + '';

}

The Message Identification form should look like this:

Navigate to Settings > Feedback.

Feedback Settings Fields

The Feedback fields to be configured for the Integration record are as follows:

The Feedback Settings form should look like this:

Click Save.

Click the 'Connections' icon to move on and configure the Connection.

Integration User

Before we configure our Connection, we need to ensure we have a user in the instance to use as the Inbound user for our Integration. To configure our Integration user:

In the native ServiceNow window, navigate to User Administration > Users. Click New.

The fields to be configured for the User record are as follows:

Your User record should look like this:

Connection

Back in the Unifi Integration Designer window, after clicking the 'Connections' icon, the first thing you will notice is a widget at the top of the page which clearly displays the inbound endpoints (REST Resources) which were automatically created when the Process was configured.

Click New.

The fields to be configured for the New Connection modal are as follows:

Outbound Connectivity

The format of the Endpoint URL is as follows:

https://<your_instance>.service-now.com/<your_resource_path>

Your New Connection modal should look like this:

Click Submit and view.

Connection Details

The fields to be configured for the Details form are as follows:

Your Details form should look like this:

Save the Connection.

Connection Test

At this stage you can carry our a basic connection test which verifies whether the user is authorized (i.e. whether you've configured the user/password/roles correctly). To do this, click Connection Test.

Then, on the Connection Test modal, click Test.

The results (Pass/Fail) will be displayed.

Click Done.

The main, manually configured elements are now in place for our Integration to work. We are now ready to configure and test each of our Scenarios in turn.

The Messages we shall be configuring for our Create Scenario are:

1. Response

2. CreateIncidentReceipt

3. CreateIncident

We will define which Field records require configuring for each of those Messages at the appropriate time.

The scenario will need to be successfully tested before we can say it is complete.

We shall look in detail at each of the Messages and their respective Fields in turn over the next few pages, before moving on to Test.

In Unifi Integration Designer, click on the 'Messages' icon & then New to begin configuring the Response Message.

The fields to be configured for the New Message modal are as follows:

Your Response New Message modal should look like this:

Click Submit.

You will be redirected to the Messages page. We need not configure our Response Message any further.

Next, we shall move on and configure the CreateIncidentReceipt Message.

You will have been redirected to the Messages page after submitting the Response Message. If navigating from elsewhere, click the 'Messages' icon and you will see the following screen (note: the previously configured message is visible in the list):

Click New.

New Message Modal

The fields to be configured for the CreateIncidentReceipt New Message modal are as follows:

Your CreateIncidentReceipt New Message modal should look like this:

Submit and view to further configure the Message.

Response Fields

Navigate to Message > Response.

The Response fields to be configured are as follows:

Your Response form should look like this:

Navigate to Message > Bond.

Bond Fields

The Bond fields to be configured are as follows:

Your Bond form should look like this:

Navigate to Inbound > Settings.

Inbound Settings Fields

The Inbound Settings fields to be configured are as follows:

The code in the 'Reference lookup script' field should look like this:

Your Inbound Settings form should look like this:

Click 'Save'.

We are now ready to configure the Fields for our CreateIncidentReceipt Message.

As previous, after clicking the 'Messages' icon, you will see the following screen (note: both the previously configured messages are now visible in the list):

Click New.

New Message Modal

The fields to be configured for the CreateIncident New Message modal are as follows:

Your CreateIncident New Message modal should look like this:

Submit and view to further configure the Message.

Response Fields

Navigate to Message > Response.

The Response fields to be configured are as follows:

*This field is automatically defaulted to true.

Your Response form should look like this:

Navigate to Message > Bond.

Bond Fields

The Bond fields to be configured are as follows:

*These fields are automatically populated.

Your Bond form should look like this:

Navigate to Outbound > Trigger.

Outbound Trigger Fields

The Outbound Trigger fields to be configured (as required)* are as follows:

The code in the 'Outbound condition' script field should look like this:

Your Outbound Trigger form should look like this:

Navigate to Outbound > Settings.

Outbound Settings Fields

The Outbound Settings fields to be configured are as follows:

Your Outbound Settings form should look like this:

Navigate to Inbound > Settings.

Inbound Settings Fields

The Inbound Settings fields to be configured are as follows:

The code in the 'Reference lookup script' field should look like this:

Your Inbound Settings form should look like this:

Click Save.

We are now ready to configure the Fields for our CreateIncident Message.

Copy Field Maps

The Field Maps we shall use for our CreateIncidentReceipt Field records are:

• Message Header

• Receipt Status

To copy the Message Header Field Map, navigate to the 'Field Maps' icon.

Click on the ellipsis to the right of the Message Header Field Map & then click Copy.

Copy Field Map Modal

The fields to edit for the Copy Field Map modal are as follows:

*This field is automatically populated.

Your Copy Field Map modal should look like this:

Click Copy.

You will be redirected to the Details page of the newly created Field Map.

Field: message.message_header

From the CreateIncidentReceipt Message, navigate to Message > Fields. Click New.

The fields to be configured for our message_header New Field modal are as follows:

*These fields are automatically defaulted to true, or automatically populated.

**Field map: Value may vary. Choose the copy Field Map you created for your Integration.

Your 'message_header' New Field modal should look like this:

Submit the record.

You will be redirected back to the Fields page of the CreateIncidentReceipt Message.

Field: message.transaction_details

Click New.

The fields to be configured for our transaction_details New Field modal are as follows:

*These fields are automatically defaulted to true, or automatically populated.

**Field map: Value may vary. Choose the copy Field Map you created for your Integration.

Your 'transaction_details' New Field modal should look like this:

Submit the record.

You will be redirected back to the Fields page of the CreateIncidentReceipt Message.

Build

Now that we’ve configured the Field records for the CreateIncidentReceipt message, we are ready to build our message scripts.

The following Field records should now be in place for your CreateIncidentReceipt messsage:

Navigate to Advanced > Script Editor.

When you first open the Script Editor, you will see the following:

Click on Build Message.

You will see the 'Message build successful' Info Message.

Your Script Editor fields should now look like this:

You can click View to adjust the layout and change the view to show various combinations of, or individual script fields.

Message Scripts

//===== [ws] Begin Unifi Auto Generated Code =====//

/*
 * This code (between the Begin and End comments) is generated from the
 * Field and Field mapping records which are configured as part of the integration.
 *
 * All code either above or below the comments will be automatically maintained
 * through the build cycle.
 *
 * WARNING: Do not edit the Begin or End comments.
 */

(New auto-generated code will appear here)

//===== [ws] End Unifi Auto Generated Code =====//

(Old pre-existing code will appear here)

Once you have finished examining the code, click 'Close' to navigate back to the Fields page of the CreateIncidentReceipt Message.

We are now ready to configure our CreateIncident Message.

Business Rule

In native ServiceNow, navigate to System Definition > Busines Rules. Find and navigate to the automatically generated Business Rule.

The top section of your Business Rule record should look like this:

When to run Fields

Your 'When to run' tab should look like this:

Advanced Fields

The code in the script field should look like this:

(function executeRule(current, previous /*null when async*/) {
  x_snd_eb.ws_console.logExecute('Business rule: [S] Unifi ' + current.getTableName() + ' trigger rule', function () {
    x_snd_eb.ActivityLog.setDocument(current, 'sys_script');
    x_snd_eb.Message.processOutbound(current);
  });
})(current, previous);

Your 'Advanced' tab should look like this:

We have confirmed the main elements are in place for our Integration to work. We are now ready to Test our CreateIncident Message.

Again, after clicking the 'Messages' icon, you are directed to the following screen (note: the three previously configured messages are now visible in the list):

Click on the ellipsis to the right of the CreateIncidentReceipt Message & click Copy.

Copy Message Modal

The fields to edit for the Copy Message modal are as follows:

Your Copy Message modal should look like this:

Click Copy.

You will be redirected to the Details page of the newly created Receipt Message.

Bond Fields

Navigate to Message > Bond.

The Bond fields to be edited are as follows:

Your Bond form should look like this:

Click Save.

Click Build Message.

You will see the 'Message build successful' Info Message.

Click the 'Messages' icon to move on & configure the UpdateIncident Message.

Field: message.message_header

It is now easier than ever to create a Message level Field record for its Integration level counterpart.

From the CreateIncident Message, navigate to Message > Fields.

Find the message.message_header (Integration level) Field & set Active to true.

By simply setting the Active flag to true on the Integration level Field record listed on the Message, Unifi has automatically created the Message level counterpart. The Integration level record still exists (and can be seen when you click on the ‘Fields’ icon to navigate to the Fields page), but is no longer visible in the list view on the Message because the Message level record has been created.)

We will now configure Field records for a select few Incident record field elements.

Fields & Field Maps

Depending on your requirements, you will need to create Field records for each of the relevant Incident record field elements (see the table below for an example). For the sake of brevity, this Guide will focus on a select few. If you wish, however, you are free to continue & configure the remaining Field records. The table below lists an example of the Incident record field elements you may wish to map and the relevant Field Maps required to configure each Field record. For a fuller definition of available Field Maps, please see the relevant page in our technical documentation.

The Field records we will focus on will be for Caller (Reference), Short description (String) and State (Choice).

Copy Field Maps

If you haven't already, you will need to copy the relevant additional Field Maps for the CreateIncident Field records as follows:

• Reference

• String

• Choice

See Copy Field Maps (on the 'CreateIncidentReceipt Fields' page) for details.

Field: incident.caller_id

From the CreateIncident Message, navigate to Message > Fields. Click New.

The fields to be configured for the incident.caller_id New Field modal are as follows:

*These fields are automatically defaulted to true, or automatically populated.

**Field map: Value may vary. Choose the copy Field Map you created for your Integration.

Your 'incident.caller_id' New Field modal should look like this:

Submit the record.

You will be redirected back to the Fields page of the CreateIncident Message.

Field: incident.short_description

Click New.

The fields to be configured for the incident.short_description New Field modal are as follows:

*These fields are automatically defaulted to true, or automatically populated.

**Field map: Value may vary. Choose the copy Field Map you created for your Integration.

Your 'incident.short_description' New Field modal should look like this:

Submit the record.

You will be redirected back to the Fields page of the CreateIncident Message.

Field: incident.state

Field records can exist at both the Integration and the Message level (a Field record exists at the Integration level if it isn't linked to a Message i.e. the 'Message' field element is left blank). We noted previously that an Integration level Field record is automatically created when we first create one at the Message level. We will utilise and configure both when mapping 'incident.state'.

The 'incident.state' Field record is a Choice 'type' Field. These are used when you’re mapping choice field elements with static values that don't change per Message (e.g. State, Impact, Urgency) i.e. you're not going to have one set of choices/values for create and another for update.

Rather than configure choices for each Message, configure choices once at the Integration level. This means you only need define them once. The Field Map will take care of it and any 'incident.state' Field records that are set at the Message level (i.e. with a value in the 'Message' field) would use the choices configured at the Integration level.

We'll first configure the Message level Field and then move on to configure the choices on its Integration level counterpart.

Field: incident.state (Message level)

From the CreatIncident Message, navigate to Message > Fields. Click New.

The fields to be configured for our incident.state (Message level) New Field modal are as follows:

*These fields are automatically defaulted to true, or automatically populated.

**Field map: Value may vary. Choose the copy Field Map you created for your Integration.

Your 'incident.state' (Message level) New Field modal should look like this:

Submit the record.

You will be redirected back to the Fields page of the CreateIncident Message.

Field: incident.state (Integration level)

Navigate to the 'Fields' icon to open the Fields page.

Click to open the incident.state (Integration level) Field record (the one where Message is empty).

The incident.state Field record opens to the Details page.

Navigate to Field > Field Choices.

Click Generate field choices.

Click Generate on the 'Generate field choices' modal which displays.

The Field Choices are generated & now visible in the list.

At this stage, you could carry on and configure any remaining Field records for the rest of the Incident record field elements (as per your requirements - see the Fields & Field Maps table at the top of this section). However, we will now run the Build process to auto-generate our Message Scripts.

Build

Now that we’ve configured the Field records for the CreateIncident message, we are ready to build our message scripts.

From the CreateIncident message, navigate to Message > Fields.

The following Field records should now be in place for your CreateIncident messsage:

Click on Build Message.

You will see the 'Message build successful' Info Message.

Navigate to Advanced > Script Editor to view the auto-generated code.

Your Script Editor fields should look like this:

Message Scripts

//===== [ws] Begin Unifi Auto Generated Code =====//

/*
 * This code (between the Begin and End comments) is generated from the
 * Field and Field mapping records which are configured as part of the integration.
 *
 * All code either above or below the comments will be automatically maintained
 * through the build cycle.
 *
 * WARNING: Do not edit the Begin or End comments.
 */

(New auto-generated code will appear here)

//===== [ws] End Unifi Auto Generated Code =====//

(Old pre-existing code will appear here)

__

We are now ready to Test our CreateIncident Message.

Before we do, let's view the Trigger which Unifi automatically created when we ran 'Build Message'.

The Messages we shall be configuring for our Update Scenario are:

1. Receipt

2. UpdateIncident

We will define which Field records require configuring for each of those Messages at the appropriate time.

The scenario will need to be successfully tested before we can say it is complete.

We shall look in detail at each of the Messages and their respective Fields in turn over the next few pages, before moving on to Test.

Because we have configured Unifi to connect to itself, we don't need to wait until we've connected to the external system before we test. We can test both sending and receiving Messages in the one instance. It goes without saying that these tests should be repeated once we have connected to the external instance.

To test, we will create an incident in our instance and then follow the data as it flows through the Unifi transport stack and on to the newly created ticket (whether that be in our instance, or in the external system we are integrating with).

Assignment Group

We have data-driven the trigger for our Create Message so that it fires when a ticket is assigned to an assignment group which has the integration referenced on it. In order to test then, we’ll need to add our integration to the Unifi Integrations field on the assignment group that triggers our incidents. We will create a new assignment group as an example.

In native ServiceNow, navigate to User Administration > Groups. Click New.

The Group fields to be configured are as follows:

Your Group record should look like this:

Submit the record.

Create an Incident

In native ServiceNow, navigate to Incident > Create New.

The Incident fields to configure are as follows:

Your Incident form should look like this:

Right-click & Save.

Note the values entered (including State), so that you can check them against the mapped fields on the corresponding record in the instance being integrated to.

You should see an Info Message, confirming the CreateIncident Message is being sent to your Integration:

When you scroll down to the 'Unifi Integrations' related list (you may have to configure the related lists to add it to your Incident form), notice:

A Bond has been created. The External reference is populated & the State has changed to 'Open'. Click the Bond Number link to open the Bond record.

Note: You may need to refresh the list by clicking the Bonds breadcrumb to view the changes.

View the Bond

Your Bond record should look like this:

Bond details:

• Integration: < Your Integration >

• Connection: < Your Connection >

• Table: 'Incident [incident]'

• Document: < Your Incident >

• State: 'Open' (Message exchange is available)

• Status: 'OK' (All transactions have completed)

• Internal reference: < ServiceNow ticket reference > (Same as 'Document')

• External reference: < External system's ticket reference >

Transaction:

• Message ID: Internal system's unique Transaction identifier

• External Message ID: External system's unique Transaction identifier

• Message: 'Createincident'

• Direction: 'Outbound'

• Transaction state: 'Complete' (The data has been successfully transported)

• Process state: 'Accepted' (The transaction was accepted as within the scope of the business logic that's in place)

Transaction process next queued: Logs from checking whether there are any other transactions queued and processing those.

Transaction receive message: Logs from processing the inbound asynchronous receipt.

Transaction sending: Logs from taking the Stage data, building the Request record & sending the Request to the integrated system.

Business rule: < Your Trigger >: Logs from the Business Rule that triggered Unifi.

View the Transaction

Click through to the Transaction record from the related list on the Bond.

Your Transaction record should look like this:

Transaction details:

• Table: 'Incident [incident]'

• Document: < Your Incident >

• Integration: < Your Integration >

• Connection: < Your Connection >

• Bond: < Your Bond >

• Message: 'CreateIncident'

• Direction: 'Outbound'

• Transaction state: 'Complete' (The data has been successfully transported)

• Process state: 'Accepted' (The transaction was accepted as within the scope of the business logic that's in place)

Errors:

• Error: (If there was a transactional error the Transaction state would show as 'Error' and the details would be captured here).

• Process error: (If there was a process error the Process state would show as 'Rejected' and the details would be captured here)

Stages:

• Direction: 'Outbound' & 'Inbound'

• Message: 'CreateIncident' & 'CreateIncidentReceipt'

• Internal reference: < ServiceNow ticket reference > (Same as 'Document')

• External reference: < External system's ticket reference >

View the Stage

Click through to the Outbound Stage record from the related list on the Transaction. (If you wish, you could also do the same for the Inbound Stage record.)

Check the values in the fields match what you expect.

Your Stage record should look like this:

Stage details:

• Direction: 'Outbound'

• Internal reference: < ServiceNow ticket reference >

• Snapshot: < Snapshot record reference >

• Message: 'CreateIncident'

• Transaction: < Your Transaction >

• Integration: < Your Integration >

Mapped Staged Data fields (yours may differ depending on which Field records you created):

• caller_id: < Your caller.id >

• short_description: < Your Short description >

• state: '1'

View the HTTP Request

Click through to the outbound HTTP Request record from the related list on the Transaction. (If you wish, you could also do the same for the Inbound HTTP Request.)

Your HTTP Request record should look like this:

HTTP Request details:

• Integration: < Your Integration >

• Connection: < Your Connection >

• Transaction: < Your Transaction >

• Message: 'CreateIncident'

• Direction: 'Outbound'

• Request state: 'OK' (There are no errors with the HTTP Request.)

• Attempt number: < Number of HTTP Request attempts > (Failed requests are retried up to the maximum attempts number as configured on the Integration.)

• Endpoint URL: < The external system’s access URL >

• Action Method: 'POST'

• Request headers: < The header of the request being sent >

• Request payload: < The payload of the request being sent >

Response details:

• Status code: '200'

• Response headers: < The header of the response being received >

• Response payload: < The payload of the response being received >

Compare with the External System's Incident

Navigate to the corresponding Incident in the external system.

Check the values in the fields match those you noted when you saved the Incident in the internal system.

Your external system's Incident record should look like this (depending on the system you're integrating with, your record may look different; the important matter is that the values match):

Caller: < Your Caller >

State: < Your State >

Short description: < Your Short description >

Activities: < Note showing activity on the Incident > (Opened by < your.external.system.user > configured in the Connection)

Bond: Note that a bond exists in the external system in an 'Open' state and the 'Internal reference' & 'External reference' are reversed

We are now ready to move to the Update Scenario.

The Message we shall be configuring for our Resolve Scenario is:

1. ResolveIncident

We will define which Field records require configuring for that Message at the appropriate time.

The scenario will need to be successfully tested before we can say it is complete.

We shall look in detail at each of the Messages and their respective Fields in turn over the next few pages, before moving on to Test.

Again, after clicking the 'Messages' icon, you are directed to the following screen (note: the five previously configured messages are now visible in the list):

Click the ellipsis to the right of the UpdateIncident Message & then click Copy.

Copy Message Modal

The fields to edit for the Copy Message modal are as follows:

Your Copy Message modal should look like this:

Click Copy.

You will be redirected to the Details page of the newly created ResolveIncident Message.

Bond Fields

Navigate to Message > Bond.

The Bond fields to be edited are as follows:

Your Bond form should look like this:

Navigate to Outbound > Trigger.

Outbound Trigger Fields

The Outbound Trigger (as required)* fields to be edited are as follows:

Your Outbound Trigger form should look like this:

Click Save.

We are now ready to configure the Fields for our ResolveIncident Message.

Update the Incident

Navigate to < Your Incident > created in the previous test.

Your Incident record should look like this:

Enter < Your Work notes > in the 'Work notes' field.

Click Post.

You should see an Info Message, confirming the UpdateIncident Message is being sent to your Integration:

The Work note is added to the Activities stream on the 'Notes' tab:

View the Bond

Click through to the Bond record from the related list on the Incident.

Your Bond record should have been updated as follows:

Transaction:

• Message: 'Updateincident'

• Direction: 'Outbound'

• Transaction state: 'Complete' (The data has been successfully transported)

• Process state: 'Accepted' (The transaction was accepted as within the scope of the business logic that's in place)

View the Transaction

Click through to the Transaction record from the related list on the Bond.

Your Transaction record should look like this:

Transaction details:

• Table: 'Incident [incident]'

• Document: < Your Incident >

• Integration: < Your Integration >

• Connection: < Your Connection >

• Bond: < Your Bond >

• Message: 'UpdateIncident'

• Direction: 'Outbound'

• Transaction state: 'Complete' (The data has been successfully transported)

• Process state: 'Accepted' (The transaction was accepted as within the scope of the business logic that's in place)

Errors:

• Error: (If there was a transactional error the Transaction state would show as 'Error' and the details would be captured here).

• Process error: (If there was a process error the Process state would show as 'Rejected' and the details would be captured here)

Stages:

• Direction: 'Outbound' & 'Inbound'

• Message: 'UpdateIncident' & 'Receipt'

• Internal reference: < ServiceNow ticket reference > (Same as 'Document')

• External reference: < External system's ticket reference >

View the Stage

Click through to the Outbound Stage record from the related list on the Transaction. (If you wish, you could also do the same for the Inbound Stage record.)

Check the values in the fields match what you expect.

Your Stage record should look like this:

Stage details:

• Direction: 'Outbound'

• External reference: < External system's ticket reference >

• Internal reference: < ServiceNow ticket reference >

• Snapshot: < Snapshot record reference >

• Message: 'UpdateIncident'

• Transaction: < Your Transaction >

• Integration: < Your Integration >

Mapped Staged Data fields:

• work_notes: < Your Work note >

View the HTTP Request

Click through to the Outbound HTTP Request record from the related list on the Transaction. (If you wish, you could also do the same for the Inbound HTTP Request record.)

Your HTTP Request record should look like this:

HTTP Request details:

• Integration: < Your Integration >

• Connection: < Your Connection >

• Transaction: < Your Transaction >

• Message: 'UpdateIncident'

• Direction: 'Outbound'

• Request state: 'OK' (There are no errors with the HTTP Request.)

• Attempt number: < Number of HTTP Request attempts > (Failed requests are retried up to the maximum attempts number as configured on the Integration.)

• Endpoint URL: < The external system’s access URL >

• Action Method: 'POST'

• Request headers: < The header of the request being sent >

• Request payload: < The payload of the request being sent >

Response details:

• Status code: '200'

• Response headers: < The header of the response being received >

• Response payload: < The payload of the response being received >

Compare with the External System's Incident

Navigate to the corresponding Incident in the external system.

Check the values in the fields match those you noted when you saved the Incident in the internal system.

Your external system's Incident record should look like this (depending on the system you're integrating with, your record may look different; the important matter is that the values match):

Activities: < Your Work note > (added by < your.external.system.user >)

Challenge

• Repeat the steps above - this time placing a check in the 'Additional comments (Customer visible)' checkbox.

• What do you expect to happen?

We are now ready to move to the Resolve Scenario.

Field: message.message_header

From the UpdateIncident Message, navigate to Message > Fields.

Your UpdateIncident Fields page should look like this:

Find the message.message_header (Integration level) Field & set Active to true.

As before, by setting the Active flag to true on the Integration level Field record listed on the Message, Unifi has automatically created the Message level counterpart.

Field: incident.short_description

Your UpdateIncident Fields page should look like this:

Find the incident.short_description (Integration level) Field & set Active to true.

We will now configure Field records for two other Incident record field elements.

Fields & Field Maps

The table below lists the Incident record field elements we will map and the relevant Field Maps required to configure each Field record.

Copy Field Maps

If you haven't already, you will need to copy the relevant additional Field Maps for the UpdateIncident Field records as follows:

• Journal field

Field: incident.comments

From the UpdateIncident Message, navigaate to Message > Fields & click New.

The fields to be configured for our incident.comments New Field modal are as follows:

*These fields are automatically defaulted to true, or automatically populated.

**Field map: Value may vary. Choose the copy Field Map you created for your Integration.

Your 'incident.comments' New Field modal should look like this:

Submit the record.

You will be redirected back to the Fields page of the UpdateIncident Message.

Field: incident.work_notes

Click the ellipsis next to the incident.comments Field record & click Copy.

The fields to edit for the Copy Field modal are as follows:

*This field is automatically populated.

Your Copy Field modal should look like this:

Click Copy.

You will be redirected to the Details page of the newly created incident.work_notes Field record.

Build

Now that we’ve configured the Field records for the UpdateIncident message, we are ready to build our message scripts.

To quickly navigate to the UpdateIncident Message from the Details page of the newly created incident.work_notes Field record…

...click the 'Preview' icon to the left of the Message field.

From the UpdateIncident message, navigate to Message > Fields.

The following Field records should now be in place for your UpdateIncident messsage:

Click on Build Message.

You will see the 'Message build successful' Info Message.

Navigate to Advanced > Script Editor to view the auto-generated code.

Your Script Editor fields should look like this:

Message Scripts

We are now ready to Test our UpdateIncident Message.

The 'message_header', 'incident.comments', 'incident.work_notes' and 'incident.short_description' Field records are already be in place because they were also copied when we copied the Message. We can choose to include, or exclude as many of those and the Integration level ones that are available depending on our requirements (by either activating or deactivating the relevant Fields). We have chosen not to include 'incident.short_description' in our mappings, so we'll delete that.

In Unifi Integration Designer, from the ResolveIncident Message, navigate to Message > Fields.

Click on the ellipsis to the right of the incident.short_description Field & click Delete.

Confirm Delete.

Field: incident.state (Message level)

The fields to be changed to configure the incident.state (Message level) Field record are as follows:

By simply setting the Active flag to true on the Integration level Field record listed on the Message, Unifi has created the Message level counterpart.

Your ResolveIncident Message Fields page should look like this:

We will now configure Field records for the two remaining Incident record field elements which are required.

Fields & Field Maps

The table below lists the Incident record field elements we will map and the relevant Field Maps required to configure each Field record.

*Field map: Values may vary (dependent on your configuration of the copies). Choose the copy Field Maps you created earlier.

Field: incident.close_code (Message level)

As with 'incident.state' the 'incident.close_code' Field record is a Choice 'type' Field. We will, therefore, configure the choices once at the Integration level. We’ll first configure the Message level Field and then move on to configure the choices on its Integration level counterpart.

From the ResolveIncident Message, navigate to Message > Fields. Click New.

The fields to be configured for our incident.close_code (Message level) New Field modal are as follows:

*These fields are automatically defaulted to true, or automatically populated.

**Field map: Value may vary. Choose the copy Field Map you created for your Integration.

Your 'incident.close_code' (Message level) New Field modal should look like this:

Submit the record.

You will be redirected back to the Fields page of the ResolveIncident Message.

Field: incident.close_code (Integration level)

Navigate to the 'Fields' icon to open the Fields page.

Click to open the incident.close_code (Integration level) Field record (the one where Message is empty).

The incident.close_code Field record opens to the Details page.

Navigate to Field > Field Choices.

Click Generate field choices.

Click Generate on the 'Generate field choices' modal which displays.

The Field Choices are generated & now visible in the list.

Field: incident.close_notes

From the ResolveIncident Message, navigate to Message > Fields. Click New.

The fields to be configured for the incident.close_notes New Field modal are as follows:

*These fields are automatically defaulted to true, or automatically populated.

**Field map: Value may vary. Choose the copy Field Map you created for your Integration.

Your 'incident.close_notes' New Field modal should look like this:

Submit the record.

You will be redirected back to the Fields page of the ResolveIncident Message.

Build

Now that we’ve configured the Field records for the ResolveIncident message, we are ready to build our message scripts.

To quickly navigate to the ResolveIncident message from the Details page of the newly created incident.close_notes Field record…

...click the 'Preview' icon to the left of the Message field.

From the ResolveIncident message, navigate to Message > Fields.

The following Field records should now be in place for your ResolveIncident messsage:

Click on Build Message.

You will see the 'Message build successful' Info Message.

Navigate to Advanced > Script Editor to view the auto-generated code.

Your Script Editor fields should look like this:

Message Scripts

We are now ready to Test our ResolveIncident Message.

Again, after clicking the 'Messages' icon, you are directed to the following screen (note: the four previously configured messages are now visible in the list):

Click New.

New Message Modal

The fields to be configured for the UpdateIncident New Message modal are as follows:

Your UpdateIncident New Message modal should look like this:

Submit and view to further configure the Message.

Response Fields

Navigate to Message > Response.

The Response fields to be configured are as follows:

*This field is automatically defaulted to true.

Your Response form should look like this:

Navigate to Message > Bond.

Bond Fields

The Bond fields to be configured are as follows:

*These fields are automatically populated.

Your Bond form should look like this:

Navigate to Outbound > Trigger.

Outbound Trigger Fields

The Outbound Trigger fields to be configured (as required)* are as follows:

The code in the 'Outbound condition' script field should look like this:

Your Outbound Trigger form should look like this:

Navigate to Inbound > Settings.

Inbound Settings Fields

The Inbound Settings fields to be configured are as follows:

The code in the 'Reference lookup script' field should look like this:

Your Inbound Settings form should look like this:

Click Save.

We are now ready to configure the Fields for our UpdateIncident Message.

This Guide has shown us how to configure an asynchronous Incident integration, sending bidirectional messages via the REST service. The elements we configured were:

• Process

• Integration

• Connections

• Messages

• Fields

The items automatically created by Unifi were:

• Web Service

• Trigger

In testing our integration, we created, updated and resolved an Incident - following the data as it flowed from our ServiceNow Incident record, through the Unifi transaction message bus, to the external system's Incident record.

By Using the Unifi integration platform, we have discovered that building and testing our integration is simpler and more efficient, saving both time and money. Our hope is that this Guide has been a valuable aid to you in that process.

For further information please see our technical documentation.

If you have any feedback or questions, please contact us via our website contact form.

We have been running the Build process at the Message level in order to see the changes in our Message Scripts as we go. This may be considered good practice (particularly when first starting out) as any discrepancies can be discovered & rectified as you go (in potentially fewer, smaller batches). Once you are more practiced and confident in the accuracy of your configurations, you can run the Build process at the Integration level. This means that the process will cycle through all the Field records on each of the Messages on the Integration in turn & auto-generate all the relevant Message Script code.

As mentioned in the 'CreateIncidentReceipt Fields' page, we saw that a 'Build Integration' button had appeared in the banner at the top of the page. This was because, whenever a change is made to a Field record that is associated to a Message (whether that is being created, updated, or deleted) the button will be available and act as a visual reminder that changes have been made and Message Script(s) need to be built.

To run the Build Process at the Integration level we have two choices. We can either either run it from the Integration record, or we can use the 'Build Integration' button which appears in the banner at the top of the page.

On the Build Integration modal, click Build.

When complete, you will see the following Integration Build Worker modal:

Click Done.

Navigate to: 'Messages' icon.

Click through each Message in turn, navigating to Advanced > Script Editor to view the auto-generated code in the Message Scripts.

We have now built and tested the integration in one instance. We are now ready to move on and Build the other half.

If you're asking yourself, 'Do we have to do all that again?' the short answer is no, we don't. When using Unifi both ends, building the other half of the integration is a simple two-stage process.

• First we Move the Integration, exporting it from one instance and importing it to the other (creating a mirror image in the other instance).

• Second we Reconfigure the Connections so that each is pointed at the other.

We will look at both in more detail over the next couple of pages.

Export the Integration

In Unifi Integration Designer, navigate to and open < Your Integration >.

Click the 'Integration' icon to open the Details page.

Click Package.

The Package Integration modal is displayed.

Confirm by clicking Package.

Unifi packages the Integration into an Update Set which is automatically downloaded.

The Integration Package Worker modal is displayed.

Copy the name of the Update Set.

Click Done to close the modal.

Navigate to the downloaded Update Set and Show in folder*.

*Example shown in Chrome. Other browsers may vary.

Then rename the file (using your Update Set name in order to easily identify it when uploading to the other instance).

Import the Integration (external instance)

In the Application Navigator of the external instance, navigate to System Update Sets > Retrieved Update Sets.

At the bottom of the Retrieved Update Sets list, click the Import Update Set from XML related link.

The Import XML screen is displayed:

Click Choose file to upload the previously downloaded file.

Upload.

You are redirected back to the Retrieved Update Sets list view:

Open the Update Set

Your Retrieved Update Set form is displayed:

Click Preview Update Set.

Close the Update Set Preview modal.

Click Commit Update Set.

Close the Update Set Commit progress modal.

We have successfully installed the application containing our Integration on the external instance. The vast majority of the configuration is already in place. All that remains is to make a few configuration changes and Reconfigure the Connections to enable each instance to connect with the other.

Now that both halves of the Integration are in place, we need to reconfigure each of the Connections to point to the other instance. Before doing that though, we need to create a new Inbound User for the external instance.

Create an Inbound User (external instance)

To configure our Integration user:

In native ServiceNow, navigate to User Administration > Users. Click New.

The fields to be configured for the User record are as follows:

Edit the Connection (external instance)

We are going to edit the existing 'Development' Connection so that it will become our 'Test' Connection and use the Inbound user just created.

In Unifi Integration Designer, navigate to the 'Connections' icon.

Click to open the previously created Development Connection to edit it.

Edit the values in the Connection as follows:

*Inbound user created above.

Your Connection form should look like this

Save the Connection.

At this stage you can carry our a basic Connection Test (as outlined on the Connection page of this guide).

Create a Test Connection (internal instance)

Back in the internal instance, navigate to the 'Connections' icon. Click New.

The fields to be configured for the New Connection modal are as follows:

Outbound Connectivity

Your New Connection modal should look like this:

Submit and view to further configure the Connection.