Release

Release Notes Hotfixes Setup

Overview

Integration Guides

Feature Guides

Bonding

Transport

Configuration

Polling

Administration

Scripting

Attachments

The Message we shall be configuring for the 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 the Message and its respective Fields in turn over the next few pages, before moving on to Test.

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.

Introduction

Welcome to the release notes for Unifi - Version 2.2. Please have a read through to see new features and fixes that have been added.

Feedback and Reviews

We really appreciate feedback on what we’re doing - whether it’s right or wrong! We take feedback very seriously, so if you feel you’d give us anything less than a 5 star rating, we’d love to hear from you so we can find out what we need to do to improve!

If you would rate us 5 stars, and haven’t left a review on the ServiceNow Store yet, we’d be grateful if you would head over there to leave us your feedback. It only takes a few minutes and really does help us a lot. Go on, you know you want to

Highlights

Paris Support

We’ve tested and verified that Unifi continues to work as expected on the latest Paris release of ServiceNow.

Packager

We’ve introduced a brand new feature that makes exporting and migrating integrations seriously easy, 1-click easy in fact. You can now click the “Package” button on an integration in the Portal and the system will gather all the related files that make that integration work and put them in a brand new update set and download it to your desktop. This feature does require the latest version of the Unifi Global Utility.

Details

New Features & Improvements

• An API name is automatically generated when creating a new Process. [UN-192]

• Integration Diagnostic now checks for global utility installation and version. [UN-369]

• Millisecond time fields have been added to transactional records. [UN-541]

• Integration Diagnostic now checks for hotfix version. [UN-682]

Changes

• The display value for Connections now includes the Integration. [UN-347]

• Bond reference method is no longer available for Response and Receipt type Messages. [UN-603]

• Integration no longer controls number of attachments per message as this is done by the message itself. [UN-651]

General Fixes

• Added the connection variable page to Portal. [UN-656]

• Copying a Connection Variable now works. [UN-657]

• Fixed icon alignment on Messages list in UID. [UN-755]

• Fixed typo with Event Action. [UN-659]

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.

To set up a scheduled poll that will query the remote system at regular intervals, check whether any data has changed and then pass that data to Unifi, we will need to configure the following records:

• Poll Processor

• Poller

Once those records are configured, we will need to configure inbound Messages to process the returned data. We will look at the polling records in turn over the next couple of pages.

We're now ready to configure the Poll Processor.

To set up a scheduled poll that will query the remote system at regular intervals, check whether any data has changed and then pass that data to Unifi, we will need to configure the following records:

• Poll Processor

• Poller

Once those records are configured, we will need to configure an inbound message to process the returned data. We will also need to make some changes to our outbound messages before we can test our update scenario (in order to prove the poll is returning the expected data and the target record is updated accordingly). We will look at the polling records in turn over the next couple of pages.

We're now ready to configure the Poll Processor.

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.

Unifi Integration Designer

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

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

1. Response

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.

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):

1) Click New.

New Message Modal

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

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

• Process

• Integration

• Connection

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

1. CreateIncidentResponse

2. 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.

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

1. Response

2. CreateIncidentReceipt

3. CreateIncident

Our previously configured Outbound Incident Integration was very simple example and we weren't concerned with identifying which system made the updates. Neither were we concerned with telling the remote system which record they were bonded with.

Now that we're polling our PDI for data as well as sending data, we need to be aware of both the above concerns.

The first concern (identifying which system made the updates) has been taken care of in the Poll Processor Setup script (only returning data not updated by the Basic Authentication User). However, it doesn't make sense to try and return that data from all the records in the remote system. We should only be concerned with those records we're bonded with. To facilitate this we need to make a few configuration changes. We need to make a change in the remote system (our PDI) and some changes to our existing outbound CreateIncident Message.

First, we will need to Edit the Incident Form in our PDI.

In order to process the data that is returned from the remote system, we will need to create the appropriate messages in Unifi. To satisfy the requirements of this Guide, we will only need to configure the one message:

• UpdateIncidentInbound

We shall look in detail at how to configure that message and the appropriate message scripts over the next couple of pages.

Let's begin by configuring the UpdateIncidentInbound Message.

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.

When we configured our Outbound Incident Integration we weren't concerned with identifying inbound messages, because there weren't any (we were only sending outbound).

Now that we're polling our PDI for data as well as sending data, we need to be aware of the above concern.

To facilitate this we need to make a change to our Integration.

Message Identification

Unifi Integration Designer

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

To set up a scheduled poll that will query the remote system at regular intervals, check whether any new records have been created and then pass that data to Unifi, we will need to configure the following records:

• Poll Processor

• Poller

Once those records are configured, we will need to configure the relevant inbound and outbound messages to process and respond to the returned data. We will also need to make some further changes before we can test our create scenario (in order to identify which records to poll for). We will look at the polling records in turn over the next couple of pages.

In order to process and respond to the data that is returned from the remote system, we will need to create the appropriate Messages in Unifi. To satisfy the requirements of this Guide, we will need to configure the following Messages:

• CreateIncidentInboundReceipt

• CreateIncidentInbound

We shall look in detail at how to configure each of those Messages and the appropriate Fields to configure the Message Scripts over the next few pages.

Let's begin by configuring the CreateIncidentInboundReceipt

Navigation Overview

The navigation menu items are grouped logically according to several different areas:

• Bonding records hold all the data that links your instance to external systems.

• Transport records give full visibility into what messages were sent and received.

• Configuration is where you create and manage all your integrations.

• Polling allows for pollers to be setup to automatically pull data from systems that cannot push.

• Administration contains global settings and other items useful for working with the app.

• Support links to the Unifi Support page. Here you can find contact details and a link to our documentation.

Setup

Navigate to Administration > Properties and ensure the Integrations Enabled property is checked.

Configuration

Integrations are grouped by Process and each contains the configuration necessary to connect to one external system.

To add a new Integration you must have already configured a Process record (with associated web services) if you want to receive inbound Messages

Integrations must have an active Connection for them to work. The active Connection tells outbound Messages where to go and specifies the user that is allowed to send data inbound (you must create unique users for each vendor).

Add Messages to control when and what data is sent and received and how it is processed.

Operations

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 .

Warning

Guide Structure and Testing Approach

As with the previous release, the vast majority of the configuration is carried out in Unifi Integration Designer (our portal interface) - Processes, Integrations, Connections, Messages, Fields & Field Maps. Although there are many other elements which are configurable in the portal, they fall outside the scope of this document. For the purpose of this Guide, the remaining configuration elements are the Web Service & Trigger. These are to be configured in native ServiceNow as before.

We could have chosen to deal with those elements configured in the portal first & then move on to those configured in native ServiceNow. Instead, however, 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 (Process, Web Service, Integration, Connection, Trigger), 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.

Correlation ID

In order for the remote system to store data about which record they're bonded with and to enable us to identify and only return data from those bonded records, we need to send and store a unique identifier. We will make use of the available correlation_id field on the Incident record. First we will add the field to the Incident form in our PDI.

Incident Form

From any Incident record in your PDI, right-click & navigate to Configure > Form Layout.

Select the Correlation Id field from the 'Available' slushbucket and move it to the 'Selected' slushbucket.

Save to add the field to your form.

Next, we will need to Edit the CreateIncident Message.

This Guide has shown us how we might configure a poller integration - polling data from the table API of a Personal Developer Instance (PDI) and then configure multiple inbound messages to process that data (deciding which Message to use in the process). As such, we created the following records:

• Poll Processor

• Poller

• Inbound Message

• Fields

In testing our integration, we created some incidents in the remote instance which were bonded. We then updated the bonded records from both instances (polling for updates each time). We successfully proved that we were only querying bonded records, pulling back updates made in the remote instance since the last update time, only retrieving a select number of fields and that the returned requests were looped through, generating transactions for each updated ticket.

We also proved that we were able to store previously returned records in order to facilitate comparison & to enable the decision as to which Message to use to process the data - successfully telling Unifi which Message to use.

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 .

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

Welcome

We will be configuring a Poller and Poll Processor in order to pull Incident data which has been updated from an external instance and pass it to Unifi. We will then configure the relevant inbound Message in order to process that data.

If you have been following along with the Outbound Incident Guide you will know that it is given as an example of how you might configure such an integration. It is not meant to be prescriptive. The same applies here.

Having said that, this Guide has been written to follow on from that previous one and has been structured accordingly.

Scope

This document will guide you through an example of how you might configure a poller integration - polling the table API of your Personal Developer Instance (PDI).

The Outbound Incident Guide demonstrates how to configure outbound messages to the table API of your PDI. This Guide will demonstrate how you might poll data from the table API of your PDI and then configure inbound messages to process that data.

Definitions

It is not always possible for a remote system to send us the data. In such cases, we can make a scheduled request for it using Pollers. We can setup, execute and process those Requests using Poll Processors.

Poller

A poller defines the frequency of polling and which logic to use. It is effectively a scheduled job which ties together an Integration and Poll Processor. Although a Poller belongs to only one Integration, an Integration can have multiple Pollers.

Poll Processor

A Poll Processor contains the logic that will be applied when polling a remote system for data. It contains three main scripts:

Setup Script

The Setup Script is used to build the environment for the poll and define what it will do (for example, create/setup the URL that will be called).

Request Script

The Request Script is used to reach into the remote system and execute the request. This is usually done by making a REST call to the URL defined in the Setup Script.

Response Script

The Response Script is used to process the information returned from the remote system.

Warning

Approach

We will need to store and check some returned data in order to evaluate when the data was changed and which system has made the updates to the data (we don’t want to pull back data we have changed).

We will begin by polling for updates only and processing those requests using an update message in Unifi.

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

• Web Service

• Integration

• Connections

• Trigger

• Messages

• Fields

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 .

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

This Guide has shown us how we might configure a poller integration - polling data from the table API of a Personal Developer Instance (PDI) and then configure the relevant message to process and respond to that data. As such, we created the following records:

• Connection Variables

• Poll Processor

• Poller

• Messages

• Fields

We also created & used a specific Assignment group in the remote instance (PDI), in order to facilitate the following:

• Ticket Identification

In testing our integration, we created some incidents in the remote instance which were non-bonded and assigned to a range of groups. We then polled for newly created tickets. We successfully proved that we were only querying non-bonded records which were assigned to a specific group, pulling back records created in the remote instance since the last update time, only retrieving a select number of fields and that the returned requests were looped through, generating transactions for each non-bonded ticket.

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 .

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

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:

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 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.

We have been running the Build process at the Message level so as 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 '', 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.

It may help to turn off the Poller we created (set Active to 'false') whilst conducting these tests and to manually execute it as required (this can still be done even if the Poller is inactive). This is so that we don't have to wait for the Poller to run, but rather manually activate it when needed by clicking 'Execute Now'.

To turn off the Poller, in the Unifi Integration Designer window, navigate to the 'Pollers' icon & set Active to false.

Our Poll Processor has been configured to poll for updates from our PDI and make a decision, telling Unifi which Message to use to process that data. We will therefore test our poller by means of testing both of the inbound Messages on our Integration:

In order to process the data that is returned from the remote system, we will need to create the appropriate Messages in Unifi. The following Messages will be required:

• UpdateIncidentInbound

• ResolveIncidentInbound

To satisfy the requirements of this Guide (and because we have already configured one of those Messages in the previous Incident Update Poller Guide, we will only need to configure the one message i.e. ResolveIncidentInbound.

We shall look in detail at how to configure that Message and the appropriate Message Scripts over the next couple of pages.

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:

API Models

Unifi supports push-push and push-pull request models*.

* Use Direct Web Services or custom Scripted Web Services

Integrations

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:

6) Click Create.

You will be redirected to the Dashboard of your newly created Process:

Click either the '+' tile or 'New Integration' to move on and configure the Integration.

New Integration

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:

4) 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 form should look like this:

5) Navigate to Settings > Feedback.

Feedback Settings Fields

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

The Feedback Settings fields should look like this:

8) Click Save.

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

New Message Modal

In Unifi Integration Designer, navigate to the 'Messages' icon. Click New.

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

Your CreateIncidentResponse New Message modal should look like this:

4) Click Submit and view to further configure the Message.

Script Editor Fields

5) Navigate to Advanced > Script Editor.

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

Because we are dealing with an inbound message, we can adjust the view to only show the 'Payload to Stage' & 'Stage to Target' script fields.

6) Navigate to View > Inbound.

Your Script Editor fields will initially look like this:

Scripts

The Script Editor fields to be configured are as follows:

The code in the 'Stage to Target' script field should look like this:

Your Script Editor fields should now look like this:

8) Click Save.

9) Click Close to navigate back to the Message.

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

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 on the 'CreateIncidentInboundReceipt 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.

2) On the Build Integration modal, click Build.

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

3) Click Done.

Navigate to: 'Messages' icon.

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

We are now ready to move on and Test the Create Poller.

This Guide has shown us how we might configure a poller integration - polling data from the table API of a Personal Developer Instance (PDI) and then configure an inbound message to process that data. As such, we created the following records:

• Poll Processor

• Poller

• Inbound Message

• Fields

We also made further configuration changes to both the remote instance (PDI) and internal instance, in order to facilitate the following:

• Message Identification

• Bond Identification

In testing our integration, we created some incidents in the remote instance which were bonded. We then updated the bonded records from both instances (polling for updates each time). We successfully proved that we were only querying bonded records, pulling back updates made in the remote instance since the last update time, only retrieving a select number of fields and that the returned requests were looped through, generating transactions for each updated ticket.

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 .

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

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):

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

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):

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

Export the Integration

Welcome

We will be configuring another Poller and Poll Processor in order to pull data which has been updated from an external instance and then pass it to Unifi. We will then configure the relevant inbound Messages in order to process that data.

If you have been following along with the Outbound Incident Guide and the previous Poller Guide you will know that they are given as examples of how you might configure such integrations. They are not meant to be prescriptive. The same applies here.

Having said that, this Guide has been written to follow on from those previous ones and has been structured accordingly.

Overview

Follow these steps to install Unifi and get your system up and running quickly.

1. Install Unifi

Unifi Integration Designer

This is a quick link which will open the Unifi Integration Designer page in a new browser window. From here, much of the configuration of your integrations can be carried out in a more intuitive and efficient manner.

Unifi Operations Portal

This is a quick link which will open the Unifi Operations Portal page in a new browser window. It provides a live, real-time view of the last 20 Transactions processed & the Bonds that have been worked on today - showing their state & grouped by Integration. From here, you can jump straight into the relevant records (e.g. Transaction, HTTP Request, Bond, bonded record).

Dashboard

This is a quick link to the legacy Unifi Dashboard which displays reports providing operational insights into the data being exchanged.

Bonding

The bonding tables are used to manage the state of the connection between the two records in each system.

Bonds

Table: x_snd_eb_bond

A bond is a record that joins an integration to an internal process record (i.e. a ticket) by storing the internal and external system references together, along with the integration and other bond specific data. It also stores a commentary of the full history of the integration actions, making it very easy to see what has happened across the lifetime of the bond.

Bonded Attachments

Table: x_snd_eb_attachment

Bonded Attachment records track the synchronisation status of attachments on the record that has been bonded.

Transport

The communication tables facilitate the transportation, extraction, transformation and loading of data communications. They are used to simplify development and debugging, aid in operations management, and provide full insight into the details of every data exchange.

Transactions

Table: x_snd_eb_transaction

A Transaction is essentially a container used to group together the stages and requests created for single message exchange. Every inbound or outbound message belongs to a Transaction and this includes response and receipt messages.

Stages

Table: x_snd_eb_stage

The Stage table allows data to be extracted and stored before it is processed. Although a requirement for asynchronous messaging, this separation makes it very easy to develop and maintain the integrations that the application supports.

• Stage is configured so it can be extended for each process.

• The introduction of Dynamic Stage now means there is no need to manually create the staging table.

HTTP Requests

Table: x_snd_eb_http_request

HTTP Requests are the lowest level of communication, containing the raw data that is exchanged between systems.

Configuration

Processes

Table: x_snd_eb_process

The Process record allows integrations to be aligned to particular process. Many processes can be made available for integrations, and many integrations can belong to each process.

Process records define the top level configuration that all integrations using this process will follow. A typical process to be made available for integration would be Incident.

Integrations

Table: x_snd_eb_integration

An Integration acts as the top level container for configuring a process to be used by a single external or internal supplier. All the options specific to the integration are set on this record.

• An integration is only active when a connection is active.

Connections

Table: x_snd_eb_connection

Connection records allow many endpoint access configurations to be set up for a single integration. This makes managing access for different instances very easy, such as development, test and production.

Only one Connection can be made active at any time. Making one Connection active will automatically enable the Integration and disable all the other Connections. Disabling a connection will disable the Integration.

Messages

Table: x_snd_eb_message

The Unifi application uses a message centric architecture, meaning that every outbound/inbound request is configured as a single Message. A Message might be a create or update request, a receipt or a response. All Messages will send/receive a response Message and asynchronous Messages can also be configured to send/receive a receipt.

Fields

Table: x_snd_eb_field

Fields simplify and bring additional functionality to the configuring of Messages & Message Scripts. They allow Message Scripts to be broken down into smaller, reusable components.

A Field record defines the processing of a discrete component of a Message and often represents the handling of an individual field on the source/target record (e.g. Short description). They are also used to define the objects that will carry other Transaction specific data (e.g. Name, Time stamp, Source reference, Target reference).

Field Maps

Table: x_snd_eb_field_map

The Field Map defines the behaviour, or ‘type’ of a Field. It defines template code into which details from Field records are substituted. It has a template script field for each of the Message Script types (Source to Stage, Stage to Request, Payload to Stage, Stage to Target).

Message Scripts

Table: x_snd_eb_message_script

Data extraction, transformation and loading is handled by the Message Scripts. Each message can have custom scripts added that facilitate one of the following scenarios:

• Payload to Stage (Inbound)

• Stage to Target (Inbound)

• Source to Stage (Outbound)

• Stage to Request (Outbound)

Response Actions

Table: x_snd_eb_response_action

Response Actions are interceptors that allow you to customise the way responses are handled.

Diagnostic

The Diagnostic module is a link to a diagnostic test that can be run to check the configuration of your integration.

Polling

In cases where it is not possible for a remote system to send us the data, we can make a scheduled request for it using Pollers.

Pollers

Table: x_snd_eb_poller

A Poller makes a scheduled request to a remote system. It is a configuration record which defines the frequency of polling and which logic to use.

Poll Processors

Table: x_snd_eb_poll_processor

The Poll Processor is a configuration record which contains the logic that will be applied when polling a remote system for data.

Poll Requests

Table: x_snd_eb_poll_request

The Poll Request is an operational record which stores the details and outcomes of a scheduled poll.

Administration

Activity Logs

Table: x_snd_eb_activity_log

The Activity Logs module displays all the entries to the Unifi Activity Log table from the current day.

Data Stores

Table: x_snd_eb_data_store

A Data Store is simply a key-value pair stored in the database that is available to all records in the system. They are used primarily in Message Scripts and Poll Requests when you want to get and set functional data that is relevant to the integration but does not belong on the target record.

Properties

The Properties module is where you will find the global system settings for the Unifi application.

Scheduled Scripts

Table: x_snd_eb_scheduled_script

The Scheduled Scripts module displays the scripts which are automatically created by the system in order to perform tasks.

System Logs

The System Logs module is a quick link to the ServiceNow system logs and shows errors and warnings from the current day.

Self-test

The Self-test module is a link to a suite of internal tests that can be run at any time.

Support

Get Help

The Get Help module is a quick link to the Unifi Portal welcome page where you will find links to our Documentation site along with ways to connect with us for application support.

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:

4) 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:

5) Navigate to Integration > Message Identification.

Message Identification Fields

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

The Message Identification form should look like this:

7) 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:

9) Click Save.

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

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):

1) 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:

3) 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:

6) 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:

9) Click Save.

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

Click on the 'Messages' icon to open the Messages page.

1) Click the ellipsis to the right of the UpdateIncidentInbound 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:

3) Click Copy.

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

Details Fields

The Details fields to be edited are as follows:

Your Details form should look like this:

5) Navigate to Message > Bond.

Bond Fields

The Bond fields to be edited are as follows:

Your Bond form should look like this:

9) Click Save.

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

Resolve Test Incident

In the remote instance (your PDI), navigate to < Your Incident > created in the earlier test.

Update the Incident record as follows:

Your Incident record should look like this:

4) Right-click & Save.

Poll for Updates

Back in the originating instance, navigate to & open < Your Poller >. Click Execute Now.

Open the corresponding Poll Request & confirm that the Incident was found (and the Message name was ResolveIncidentInbound):

View the Transactions that have been sent. This can be done either in Native ServiceNow, or in the Unifi Operations Portal.

Confirm the Transaction has updated the bonded ticket in the originating instance:

Navigate to the Notes tab to view the Activities stream:

A Poller is a configuration record which defines the frequency of polling and which logic to use (the logic itself is defined in the Poll Processor). Each time it is run, it creates a corresponding Poll Request record.

New Poller

Click the 'Pollers' icon & then New.

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

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

Your New Poller modal should look like this:

5) Submit and view to further configure the Poller.

Details

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

Your Details form should look like this:

7) Navigate to Scheduling.

Scheduling

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

*This field is mandatory.

Your Scheduling form should look like this:

10) Save the Poller.

In order to process the inbound Requests, we next need to configure our Inbound Message.

Welcome

We will be configuring a Poller and Poll Processor in order to pull Incident records which have been created in an external instance and pass the data to Unifi. We will then configure the relevant Messages in order to process and respond to that data.

If you have been following along with the Outbound Incident Guide and each of the previous Poller Guides you will know that they are given as examples of how you might configure such integrations. They are not meant to be prescriptive. The same applies here.

Having said that, this Guide has been written to follow on from those previous ones and has been structured accordingly.

Scope

This document will guide you through an example of how you might configure a poller integration - polling the table API of your Personal Developer Instance (PDI).

Both the Incident Update Poller Guide and the Incident Multiple Message Poller Guide demonstrated how you might poll for updates from the table API of your PDI and then configure inbound Messages to process that data. This Guide will demonstrate how you might poll for newly created, unbonded records from the table API of your PDI and then configure an inbound Create Message (along with its outbound Receipt) to process and respond to that data.

Definitions

It is not always possible for a remote system to send us the data. In such cases, we can make a scheduled request for it using Pollers. We can setup, execute and process those Requests using Poll Processors.

Poller

A poller defines the frequency of polling and which logic to use. It is effectively a scheduled job which ties together an Integration and Poll Processor. Although a Poller belongs to only one Integration, an Integration can have multiple Pollers.

Poll Processor

A Poll Processor contains the logic that will be applied when polling a remote system for data. It contains three main scripts:

Setup Script

The Setup Script is used to build the environment for the poll and define what it will do (for example, create/setup the URL that will be called).

Request Script

The Request Script is used to reach into the remote system and execute the request. This is usually done by making a REST call to the URL defined in the Setup Script.

Response Script

The Response Script is used to process the information returned from the remote system.

Warning

Approach

We will need to store and check some returned data in order to evaluate when the data was changed and which system has made the updates to the data (we don’t want to pull back data we have changed).

We will begin by polling for newly created, unbonded records only and processing those requests using a create message in Unifi.

A Poller is a configuration record which defines the frequency of polling and which logic to use (the logic itself is defined in the Poll Processor). Each time it is run, it creates a corresponding Poll Request record.

New Poller

Click the 'Pollers' icon & then New.

The fields to be configured for our Poller record are as follows:

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

Your New Poller modal should look like this:

5) Submit and view to further configure the Poller.

Details

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

Your Details form should look like this:

7) Navigate to Scheduling.

Scheduling

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

*This field is mandatory.

Your Scheduling form should look like this:

10) Save the Poller.

In order to process the inbound Requests, we need to configure our Inbound Messages.

New Message Modal

Click the 'Messages' icon, then New.

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

Your CreateIncidentInboundReceipt New Message modal should look like this:

5) Click 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:

7) 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:

10) Click Save.

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

Business Rule Fields

A Poller is a configuration record which defines the frequency of polling and which logic to use (the logic itself is defined in the Poll Processor). Each time it is run, it creates a corresponding Poll Request record.

New Poller

Click the 'Pollers' icon & then New.

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

If you find a bug in Unifi we may issue a hotfix so you can get the features you need without having to upgrade.

Unifi has a Script Include called hotfix. Simply replace the script in the hotfix Script Include with the one shown below and you will instantly have access to the fixes.

These hotfixes will be shipped as real fixes with the next version of Unifi, so make sure you have the correct hotfix for your version.

Business Rule Fields

In the native ServiceNow window, navigate to System Definition > Business Rules > New.

The Business Rule fields to be configured are as follows:

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

'When to run' Tab Fields

Click on the When to run tab and configure the fields as follows:

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

'Advanced' Tab Fields

Click on the Advanced tab and configure the fields as follows:

*Script:

The code in the script field should look like this:

Your 'Advanced' tab should look like this:

10) Click Submit.

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

Update the Incident

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

Your Incident record should look like this:

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

2) 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:

3) History:

• < History updated on the Bond > (Sending UpdateIncident...)

4) 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:

5) Transaction details:

• Table: 'Incident [incident]'

• Document: < Your Incident >

• Integration: < Your Integration >

• Connection: < Your Connection >

6) 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)

7) 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:

8) Stage details:

• Direction: 'Outbound'

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

• Internal reference: < ServiceNow ticket reference >

• Message: 'UpdateIncident'

9) Mapped stage 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:

10) HTTP Request details:

• Integration: < Your Integration >

• Connection: < Your Connection >

• Transaction: < Your Transaction >

• Message: 'UpdateIncident'

11) 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):

12) 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.

After clicking the 'Messages' icon, you will see the following screen (note: the previously configured message is visible in the list):

1) 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:

5) 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:

7) 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:

9) Navigate to Advanced > Script Editor.

Script Editor Fields

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

Because we are dealing with an inbound message, we can adjust the view to only show the 'Payload to Stage' & 'Stage to Target' script fields.

10) Navigate to View > Inbound.

Your Script Editor fields will initially look like this:

Scripts

The Script Editor fields to be configured are as follows:

The code in the 'Stage to Target' script field should look like this:

Your Script Editor fields should now look like this:

12) Click 'Save'.

13) Click 'Close' to navigate back to the Message.

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

Update The Incident

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

Your Incident record should look like this:

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

2) Click Post.

The following activities are added to the 'Notes' tab (confirming sending the UpdateIncident Message to your integration):

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:

3) History:

• < History updated on the Bond > (Sending UpdateIncident...)

4) 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:

5) Transaction details:

• Table: 'Incident [incident]'

• Document: < Your Incident >

• Integration: < Your Integration >

• Connection: < Your Connection >

6) 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)

7) Stage:

• Direction: 'Outbound'

• Message: 'UpdateIncident'

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

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

View the Stage

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

Check the values in the fields match what you expect.

Your Stage record should look like this:

8) Stage details:

• Direction: 'Outbound'

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

• Internal reference: < ServiceNow ticket reference >

• Message: 'UpdateIncident'

9) Mapped stage fields:

• Work notes: < Your Work note >

View the HTTP Request

Click through to the HTTP Request record from the related list on the Transaction.

Your HTTP Request record should look like this:

10) HTTP Request details:

• Integration: < Your Integration >

• Connection: < Your Connection >

• Transaction: < Your Transaction >

• Message: 'UpdateIncident'

11) 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):

12) 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?

Field: incident.number

From the CreateIncidentInboundReceipt Message, navigate to Message > Fields.

Your CreateIncidentInboundReceipt Fields page should look like this:

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

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.

Build

We don't need to configure any more the Field records for the CreateIncidentInboundReceipt Message, so we are ready to build our message scripts.

2) Click on Build Message.

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

3) Navigate to Advanced > Script Editor > View > Outbound to view the auto-generated code.

Your Script Editor fields should look like this:

Message Scripts

We will look at the Message Scripts in turn.

Source to Stage: