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 leave a 5-star review on the Store!

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]

• Activity Log will show “No logs.” if no logs are generated. [UN-768]

• Errors are no longer duplicated in Activity Log to make it easier to debug. [UN-769]

• Improved documentation interface in UID. [UN-772]

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]

• Message Scripts now only throw their own errors (e.g. with Fields). [UN-749]

• Improved spacing with UID Dashboard grid items. [UN-770]

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.

Introduction

Welcome to the release notes for Unifi - Version 2.0. 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 really appreciate you heading 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 leave a 5-star review on the Store!

Release Overview

The following items are the major talking points for this release.

Service Portal Interface

Now that Unifi has a solid and proven foundation for building and running integrations, we have built a new Service Portal interface to make it simpler and easier than ever to build an integration. This new interface has been developed from the ground up to be scalable, intuitive and capable of supporting advanced features.

Unifi version 2.0 marks the first release of the portal, with the ability to build Processes, Integrations and Messages, but we will be adding to it in future releases.

Also of importance is the new Dashboard which gives a clear overview of what is happening in your instance right now. A live view of the last 20 transactions to be processed and the bonds that have been worked on today really helps you to see what's going on.

Madrid Ready

Unifi is tested to be compatible with all current ServiceNow releases: Kingston, London and Madrid.

Queue Management

A lot of effort has been put into upgrading the queue management options that are available. Things like replaying Transactions and Requests now use brand new technology which allows them to be much more robust and as close to a clone of the original as possible. It's also now possible to repair all the outstanding Transactions directly from the Integration with the click of a button.

Field Mapping

This release introduces the concept of Field Maps. These allow you to configure your messages with Fields and reusable Field Maps which then automatically generate all your scripts, so you don't need to write any code.

Field Maps have no negative performance impact - in fact, they might be slightly faster - because all the logic to be executed is copied into the Message Scripts when the integration is built. Any existing code in your Message Scripts is retained so you always have the option of doing things manually.

Activity Logs

Anyone that's used Unifi knows that a major benefit of building integrations in Unifi is the logging and profiling capability. We've now expanded this capability to make it more easily and widely accessible, so even background processes have complex logs available to see.

With the introduction of the Activity Log table, this becomes your first port of call when trying to looking for issues.

Features

[UN-124] - Add description to connection variables to allow explanation of their use

It is now possible to add a description to the Connection Variable (up to 4000 characters) so notes or explanations can be stored.

[UN-127] - Replay All errored transactions

The Integration record now features a 'Repair' button which will automatically batch process all errored transactions. A background process is executed and with status being displayed through a progress bar.

[UN-152] - Sending attachments

• This is a breaking change

Some improvements have been made to the attachment sending.

Two new fields are now available on Message:

• Send attachments [true/false]

• Send attachments max [Integer - default 1]

In addition to these new fields, the method AttachmentHandler#getAttachmentsToSend(message, transaction) now takes two arguments where previously it took one. It is this method modification that may break some existing installations that manually call this method (e.g. in a UI Macro or Script Include). Please check usage of this before upgrading.

[UN-170] - Add reprocess/resend to HTTP requests

Replaying an HTTP Request now works properly for both inbound and outbound requests. Previously, complexities with the process prevented this from being fully implemented.

[UN-178] - Activity Log

Unifi has a very smart profiling and logging tool called console which allows detailed logs to be attached to contextually relevant records. While this has been incredibly useful it fell short in two areas. The first is that it would add lots of attachments to the database over time, and the second is that it wasn't easily possible to log non-record generating processes, such as background clean-up jobs.

This update addresses both of these issues through the addition of a new table called Activity Log. The table means that attachments are no longer needed because all transactions are automatically logged. It also means that background processes can be tracked because they do not need a record to belong to. The logs are stored in the table and rendered without needing to download or open an attachment.

Activity Logs will also track (where possible) the integration they belong to and the contextual record it is about. Related lists have been added in places like Bond, Transaction and Request so that Activity Logs can be easily referenced.

By default, Activity Logs are stored for 7 days.

[UN-210] - Dynamic Stage object so we don’t need to extend

Traditionally, local staging tables have been required for each process to capture data at a point in time. This data would then be available to process accurately, but it was also providing a log for future reference. The problem was a new Stage table would need to be created before the Process could be created. Then, any time a data point was needed, a new field would have to be added to the custom stage table.

Dynamic Stage does away with the need for custom stages per process and removes the need to create fields by storing data dynamically as you use it. New Processes only need to reference the Unifi Stage table, and Dynamic Stage will take care of everything else.

• This change is fully backwards compatible with the traditional one stage table per process.

Start using Dynamic Stage in your Message Scripts by assigning to and from the $stage object instead of stage. It is possible to add not only strings to $stage, but also complex objects and arrays. Just make sure that things like field objects are coerced to strings (or use getValue()) otherwise you'll see something like [object Object] instead of the string value you expect.

• Custom stage tables will work with Dynamic Stage, but you will need to add the Stage Data Render formatter to the form layout.

[UN-266] - Clone cleanup should disable all non-instance specific connections

By default, the Integrations Enabled system property (x_snd_eb.active) is disabled when an instance is cloned. This update also disables all Connections to prevent accidental connection to the wrong endpoint.

[UN-268] - Add automatic domain setting for Bond and Transaction stack

The domain field is now automatically set for transactional records using the following logic:

• Bond domain comes from Target domain (e.g. Incident).

• Transaction domain comes from Bond domain.

• Stage domain comes from Transaction domain.

• HTTP Request domain comes from Transaction domain.

• Bonded Attachment domain comes from Bond domain.

[UN-269] - Modify response action override message

The response action error message has been modified to be more descriptive.

e.g. Socket timeout handled by response action "Default 0 Script Errors"

[UN-272] - Add indexes

All tables have been indexed according to the data and queries being used. This should improve performance, especially when loading/searching lists.

[UN-276] - Allow multiple ignore and ignore from right click (Transaction)

Transactions can now be ignored from the list context menu and by a list button.

[UN-299] - Add description fields to configuration records

Add description field to all configuration type records.

• Process

• Integration

• Message

• Response Action

• Poller

• Poll Processor

[UN-304] - Break out GlideRecord#operation() to Model method

It is now possible to check the record operation from the Unifi Model class.

[UN-307] - Add link to app log

The System Log module has been updated to point to the scoped log rather than the system log.

[UN-309] - Update sync overdue transaction job BR on integration

The business rule that generates the overdue transaction jobs for each integration is now wrapped so it appears in the Activity Log.

[UN-317] - Refine Message.processOutbound

The Message.processOutbound() method has been improved to be more efficient and provide better visibility of processing.

[UN-318] - Add method to console for executing a function

A new method ws_console.execute() wraps an inline function in console logic and prevents errors from leaking (as errors are captured by the Activity Log and automatically put in gs.error()).

It should be used in all business rules and scheduled jobs, and anywhere else a script runs in Unifi.

ws_console.execute('Business rule: Do something', function () {
 // run some code
 // errors will be caught and logged in the Activity Log and System Log
});

[UN-320] - Add cleanup job for pollers

A scheduled job has been added run every hour and uses a new cleanup field on the Poller record to determine how many days to keep Poll Requests for.

[UN-326] - Poll Requests module should filter by created on today

Viewing Poll Requests from the application navigator will now filter to show only those created today.

[UN-340] - Sync responses do not have automatic access to internal reference

When an inbound sync request was made, the internal stage did not get auto populated with the internal_reference field for use by the response message (e.g. to give the Incident number that was created). Unifi now checks if it has a value and if not, auto-populates it.

[UN-352] - Copy message

A Copy action is now available on the Message form which copies the Message and its Scripts.

[UN-353] - Copy connection

A Copy action is now available on the Connection form which copies the Connection and its Variables.

[UN-354] - Add support for streaming an attachment over REST

Unifi now supports sending a whole attachment as the request instead of having it sent as part of the body. This method streams the attachment rather than embedding it which means attachments larger than the string limit (5MB) can now be sent.

To use this feature, simply set the payload of the request to be sys_attachment:<sys_id> and Unifi will automatically sent the specified attachment.

[UN-355] - Improve environment objects for identify_message script

The Identify message script on the Integration is now provided with integration and connection GlideRecord objects. The objects now available are payload, headers, integration, connection and variables.

[UN-361] - Add link parsing to console

Console logs now replace text in the format table.sys_id with a link to the record in HTML format. If the record is found then the table label and record display value are also shown. This allows users to easily open records used during the process.

[UN-363] - Add link to broken transactions on integration

A View broken transactions related link is now available on the integration to easily view all transactions that are errored or timed out.

[UN-366] - Process stage table should be default to x_snd_eb_stage.

With the introduction of Dynamic Stage, new Process records default to use the Unifi Stage table.

UN-367] - Allow request error to show in Transaction instead of 'Final retry failed.'

The "Final retry failed" error shown in transactions was not helpful and has now been replaced with the error generated by the latest request that failed.

[UN-368] - If transaction is ignored, prevent in flight request from sending

Ignoring a transaction midway through a request being processed would not prevent the request from being sent. Requests now check if the transaction is cancelled just before sending and will automatically cancel themselves if the transaction is cancelled.

[UN-374] - Remove irrelevant debug statements

Irrelevant debug statements have been tidied up so they either do not show or only show when trace logging is enabled.

[UN-376] - Replace snd_console with ws_console

When Unifi was first created, snd_console was also created to be used for profiling and debugging. With the company transitioning from the old name SN Developer to Whitespace Studios, we have replaced snd_console with ws_console. You might even see ws_console become available for your own apps in future!

• This change is backwards compatible. snd_console still exists in Unifi so any code in your instance that uses this method will still work.

[UN-377] - Message path should allow ${} variable format

The Path on Message would only allow inline scripts using the {} format, but this is inconsistent with the rest of ServiceNow so it now accepts ${} or {} to define inline scripts. e.g.

/upload?id={variables.uid}

or

/upload?id=${variables.uid}

Fixes

[UN-150] - Replay request/transaction needs to run as the original creator.

When replaying requests or transactions, the replay would run as the logged in user instead of the original user. It now runs as the original user to allow functionality that relies on the identity of the user to run correctly.

[UN-228] - Overhaul pending transactions counter

It is possible for Pending transactions counter on the Bond record to get out of sync. Pending transactions are now calculated differently to try to prevent this from happening.

[UN-257] - Message processOutbound is processing messages for inactive integrations

Integrations that were inactive were still being processed for messages to send when an insert/update was made to a record. This fix prevents inactive integrations from having their messages processed.

[UN-260] - Payload object is not automatically converted to JSON for Stage to Request

Integrations using JSON payloads had to manually stringify the payload object in the Stage to Request script. You can now just set the global variable payload to your payload object and it will automatically convert it to JSON.

[UN-274] - Poller doesn't check for integration off property

Pollers would still run even if the integration was disabled. This fix means Pollers will not run if the integration is disabled.

[UN-275] - RestHelper wraps with 'result'

• This is a breaking change

When using a scripted REST API with the Unifi RestHelper, ServiceNow automatically wrap any non-streamed response in a result object which makes it difficult to integrate with other systems that have specific response requirements. This fix uses the streaming method to send the response payload which means the message controls the whole response and no result wrapper is added.

[UN-283] - ITIL users cannot see the message names when viewing bond/transactions.

Security rules have been created to allow ITIL users to see the names of the messages that have been used when viewing from transactional data such as bonds and transactions.

[UN-285] - Attachment added can only be true on one message

Previously, only one message per integration could be configured with the 'Attachment added' trigger condition. This update allows one message per table per integration instead.

[UN-289] - Attachment business rule does not run on update

Some processes will update attachment records and these updates were not captured by Unifi. This fix addresses that so updates to attachments will check integrations.

[UN-290] - REST XML does not work

This fix allows XML to work properly with scripted REST API's using the Unifi RestHelper.

[UN-303] - When getting the bond need to order by created at ascending

This fix addresses issues finding the correct bond for integrations that can create more than one bond per ticket and see transactions spread between different (incorrect) bonds.

[UN-306] - ITIL users cannot see the integration names when viewing bond/transactions.

Security rules have been created to allow ITIL users to see the names of the integrations that have been used when viewing from transactional data such as bonds and transactions.

[UN-308] - Data Store checkOrphans method causing errors for empty table name

The scheduled orphan record checker for Data Stores would cause errors when the record that owner the data store was deleted. This would cause the getRefRecord() method to fail.

[UN-314] - Receiving errors in processing poll requests due to string being too big

Pollers that return strings that are outside the string size limit (usually > 5MB for scoped applications) will generate an exception. A try/catch has been added to help avoid the exception and allow the script to keep running and gracefully exit.

[UN-319] - Repeating an inbound create request causes multiple bonds

When replaying an inbound create request, it would run as the user who replayed the request. Unifi saw this as a new create as it wasn't created by the Integration User. This has been fixed by replaying using a scheduled job that runs as the user that created the original request.

[UN-328] - Outbound attachment sending loop

Sending an outbound attachment that is rejected could result in the attachment being picked up with the next transaction which could also fail, thus causing an infinite loop. Bonded attachments are now only picked up in the Ready state where previously it was Ready or Rejected.

[UN-334] - Sync integration doesn't update bond external reference from stage, but async does.

The External reference on the Bond had to be written to manually for a synchronous message, where it happened automatically for an asynchronous message. It now works automatically for both types of message.

[UN-343] - Multi-table attachment processing

If an integration belonged to a process which pointed to a different table to the attachment sending message, the attachment listener on sys_attachment would not find the message. This is fixed with an option being passable to Message.processOutbound so the table hierarchy will be searched.

Message.processOutbound(current, {parent_tables: true});

[UN-348] - Affected CI logic updating incident is causing double updates

A caching issue meant it was possible for a work note to be added to the Incident whenever a CI was added/removed from the form. This has been fixed with a more intelligent mechanism of referencing the target record.

[UN-350] - Unifi message name header needs to be case insensitive

Message identification can be done by the request passing a specific header that Unifi recognises rather than adding the message name to the payload. However, headers in ServiceNow Scripted REST are always converted to lowercase which meant the Unifi header name, which used uppercase characters, did not work. This has been fixed by using case-insensitive matching on the Unifi message name header.

[UN-351] - Inbound user should not be mandatory

The Inbound user field on Connection is no longer mandatory. This is important for outbound-only integrations which do not require or permit any inbound requests.

[UN-356] - Add condition to the sys_attachment Unifi trigger

There were scenarios where Unifi log attachments could be sent by Unifi via the integration. Additional conditions on the sys_attachment business rule now prevent this from happening.

[UN-375] - Request URL's have duplicate host

If an integration required two endpoints (such as a ServiceNow Table API integration which also uses the Attachment API), the secondary host defined in a connection variable would not replace the host defined on the connection. The resulting URL had the connection endpoint followed by the variable endpoint.

e.g. Connection URL: https://test.service-now.com/api/now/table Connection Variable value (attachment_api): https://test.service-now.com/api/now/attachment Message path: {variables.attachment_api} Resulting URL: https://test.service-now.com/api/now/tablehttps://test.service-now.com/api/now/attachment

The workaround was to put both hosts in variables, but it has now been fixed so that the message path is pre-processed first and then the connection path is prepended if the resulting URL does not contain a schema (i.e. ://).

[UN-379] - Inbound attachment does not trigger outbound attachments for other bonds

In the multi-bond scenario where one ticket is bonded to many integrations, an inbound attachment will automatically create Bonded Attachment records for all the other Bonds. The problem was it didn't trigger the outbound message processing so those attachments didn't get sent automatically. This is now fixed so the outbound messages are processed when the bonded attachments are created.

Overview

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

1. Install Unifi

2. Install Global Utility

3. Install Hotfix

4. Configure Your Integrations

1. Install Unifi

If you have purchased Unifi, you will need to ensure the instance you want to install Unifi on has been given entitlement to the application. You can manage this through the Store.

Once you have setup entitlement, you can use the Application Manager in ServiceNow to install Unifi. You can find more information on how to in the ServiceNow Product Documentation.

If you have not yet purchased Unifi, you can from the ServiceNow Store.

2. Install Global Utility

Unifi has some enhanced functionality that requires access to methods not available to scoped applications. We grant Unifi access to those methods through a single global utility Script Include which you can install via Update Set.

It is strongly advised that you install this utility to get the most out of Unifi.

1. Download [ws] Unifi Global Utility - 2.2.1

2. Import the file as an update set, then preview and commit it. You can find more information on how to in the ServiceNow Product Documentation.

Features

Moving Attachments

Method: snd_eb_util.moveAttachments

The ServiceNow scoped attachment API does not support moving attachments from one record to another. This is necessary for inbound attachments which initially reside on the HTTP Request and are then moved to the Target record.

Jelly Processing

Method: snd_eb_util.runJelly

Jelly processing is not supported in the ServiceNow scoped API’s, however it is very useful for XML processing. Use of the Global Utility drastically improves XML payload capabilities if you are working with XML payloads.

SOAP Response Element

Method: snd_eb_util.getSoapResponseElement

When working with Scripted SOAP Services, it’s important to be able to set the soapResponseElement directly in order to preserve the exact payload to be sent back to the calling system. This can only be done with the Global Utility.

Binary Attachment Handling

Method: snd_eb_util.writeAttachment

The Scoped Attachment API does not support writing binary attachments which can cause problems when receiving things like Word documents or PDF’s. This method allows Unifi to use the global attachment API to write those files to the database meaning they will work properly.

Update Set Packaging

Method: snd_eb_util.packager.*

The packager methods included in the global utility allow Unifi to automatically export all the components of an integration in one easy step. The packager methods will allow Unifi to create an update set for the integration, add all the configuration records to that update set, and export it as a file download from the Integration page on the Unifi Integration Designer portal.

3. Install Hotfix

Unifi has the ability to be patched between releases by using a special Script Include called hotfix.

4. Configure Your Integrations

If you’re new to Unifi then you might like to follow one of our integration guides. You can access the Integration Guides from the menu.

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

API Models

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

* Use Direct Web Services or custom Scripted Web Services

Integrations

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 Outbound Incident Guide as an aid to customers who are beginning their journey in deploying the Unifi integration platform. We would not want you to be overwhelmed by exploring all that Unifi has to offer here, so we have deliberately limited the scope of this document. It will guide you through an example of how to configure a basic Incident integration, sending outbound messages via the REST API to the table API of another ServiceNow instance (i.e. your Personal Developer Instance, ‘PDI’).

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

Warning

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.

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.

Introduction

Welcome to the release notes for Unifi - Version 2.1. 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

Major Portal Update

The biggest change in this release is the update to the Portal interface, now known as Unifi Integration Designer.

The old operations dashboard has now been moved to the new Unifi Operations Portal, ready for lots of exciting updates around operations in the near future. It's been replaced with a brand new configuration dashboard, allowing you to view, create, copy and manage your processes and integrations with ease.

There are lots of improvements across the board when configuring an integration, too, not least of all including support for all the components you need to build any Ticket Exchange integration together in an intuitive way.

Integration Pause

We've introduced a brand new capability to pause an integration. This allows you to temporarily prevent outbound messages from being sent, instead allowing them queue ready for sending in future. This is different to deactivating the integration, which would prevent message processing altogether. You might want to do this if you are having a lot of errors with the external system, or perhaps if it's gone down for maintenance. Once you know the system is back up and online, you can resume the integration with the click of a button and it will automatically start processing the queued messages.

Event Actions

The introduction of Event Actions is part of our ongoing strategy to improve operations management of integrations. By creating an Event Action, you can easily triage events such as transaction errors and perform actions to handle or report on those actions. For example, you might want to create an Incident record if you receive more than 5 transaction errors in 15 minutes.

Notes

Logged Attachments

With the introduction of Activity Logs you no longer need to attach logs to requests/transactions. Activity Logs are present in related lists on all relevant Transaction stack records.

The attached logs were previously controlled by the Attach logs and Attach payloads checkboxes on Integration, but they are now overridden off by a new Integration Enable Attachments system property. This property acts as the master switch and effectively disables the checkboxes on the Integration. Note: the checkboxes have been removed from the Integration form but can still be edited from the list view.

Details

New Features & Improvements

• Admins can now force close a bond. [UN-106]

• Description field added to Data Stores. [UN-123]

• New option on Integration to send attachments with Create messages. [UN-184]

• Activity Log now references the Target (e.g. Incident). [UN-288]

• Added a cleaner job, controlled by system properties, to remove orphaned Transactions. [UN-544]

• New Poll Request states (Retrieving, Processing) are set while a Poller is processing . [UN-293]

• Field style added to Active field on Poller. [UN-298]

• Activity Log is now able to show the table that called it. [UN-305]

• Field style added to Poll Request state. [UN-313]

• Queued Transactions are now ignored when the bond is closed. [UN-370]

• Fields can now be copied. [UN-389]

• The Integration field is now auto-populated when creating a Field from a Message. [UN-395]

• The Table field is now auto-populated when creating a Field. [UN-396]

• Added Domain field to Transaction stack forms (Bond, Transaction, Stage, and HTTP Request). [UN-401]

• Copy Message now copies all its Fields. [UN-420]

• Copying an Integration now copies all the Fields. [UN-421]

• Copy Integration is now available in the Portal. [UN-422]

• Connection is now shown on Transaction. [UN-426]

• Integration Status (Up, Down, Awaiting) is now tracked on the Integration. [UN-427]

• Integration State (Active, Paused, Off) is now tracked on the Integration. [UN-428]

• Added option to Run Event Actions on an Integration. [UN-431]

• Bond now references the Connection it was created for. [UN-438]

• Dynamic Stage ($stage) now has a getValue() method. [UN-441]

• Fields and Field Maps can now be configured in the Portal. [UN-443]

• Message level Fields can inherit from Integration level Fields. [UN-449]

• Pollers are now listed on Integration. [UN-456]

• Bonded Attachment records now track direction (Inbound or Outbound). [UN-461]

• Added console object to all scripts for ease of logging. [UN-477]

• Updated Activity Logs on the bond so it shows all Activity Logs for the Document record. [UN-513]

• Improved Activity Log titles. [UN-514]

• Admins can now force re-open a closed Bond. [UN-517]

• Improved Execute Now button for Pollers. [UN-521]

• Added Activity Logs to Poll Requests. [UN-522]

• Added Integration field to Poll Request. [UN-523]

• Improved naming for Portal based Activity Logs. [UN-529]

• HTTP Request and Transaction now shows the Response Action that was used. [UN-533]

• Cascade delete now applies to Field Maps belonging to an Integration. [UN-545]

• Cascade delete now applies to Fields belonging to an Integration. [UN-546]

• Cascade delete now applies to Pollers belonging to an Integration. [UN-547]

• Cascade delete now applies to Pollers belonging to an Poll Processor. [UN-547]

• Added Description field to Connection. [UN-565]

• Added Description field to Scheduled Scripts. [UN-570]

• Added Hints to Field Map fields. [UN-571]

• Added execution URL to Activity Log. [UN-574]

• Modified security on Activity Logs so they are visible to Unifi Managers. [UN-586]

• New Unifi REST service and integration role added to simplify REST API configuration. [UN-633]

• Changed Integration Format and Message Service defaults to be REST/JSON. [UN-634]

Changes

• Bond closed field has been removed from Message. [UN-332]

• The XML Template on Message no longer has a default value. [UN-398]

• Changing the Integration on a Field now clears the Message. [UN-399]

• Poll Processors are now copied when the Integration is copied. [UN-468]

• Improved the Field "Depends on" logic. [UN-476]

• Data Stores now inherit the domain from the parent document. [UN-481]

• Message.processOutbound() will not send anything if the action on the current record has been aborted using setAbortAction(true). [UN-490]

• Replay Request is now available to the Unifi manager role. [UN-494]

• Most system properties are now Private and not transferrable by Update Set. [UN-652]

• HTTP Request URL length limit increased to 2048 characters. [UN-118]

• Transaction count on bond has been deprecated. [UN-141]

• Number field has been removed from Messages and Message Scripts. [UN-208]

• Modified Bond Reference Method field visibility on Message. [UN-292]

• Ignore Transaction button now redirects to the Transaction being ignored. [UN-338]

• Deprecated ECC Queue attachment support for attaching logs. [UN-405]

• Deactivated the fix script x_snd_eb eBonding Upgrade. [UN-406]

• Response is no longer mandatory on Message. [UN-439]

• Integration properties which are numbers are now mandatory. [UN-440]

• Endpoint URL is now visible on inbound requests. [UN-511]

• Deprecated log attachments. [UN-540]

• Bonded Attachment fields are now locked down. [UN-577]

• Only Unifi Admins or Managers can replay HTTP Requests. [UN-581]

General Fixes

• Inbound Create messages are now rejected when a Bond with the same reference exists. [UN-136]

• Inbound Bonded Attachments now reference the Transaction they came in on. [UN-151]

• Fixed issue with connection name generation. [UN-159]

• Replaying a Transaction with attachments will now replay the attachments as well. [UN-226]

• The Bond state will now always reflect the overall status of its transactions. [UN-230]

• Bond status is now updated correctly when processing numerous queued messages. [UN-273]

• A new field Deferred count has been added to Bonded Attachment which tracks how many times the attachment was not sent and allows us to properly calculate attachment metrics on the Bond. [UN-287]

• Bond numbers are no longer used unnecessarily. [UN-315]

• Fixed issues with assigning headers in Stage to Request Message Scripts. [UN-333]

• Fixed an issue where calling a Unifi endpoint with GET would throw an error. [UN-380]

• UTF-8 encoded XML is now checked before processing to prevent parsing issues. [UN-382]

• The Name value on Field is now set even when a not mapping to a real field. [UN-397]

• Fixed an issue where the Field form would always show the alert for losing changes. [UN-451]

• Fixed duplicate attachment messages when using ServiceNow Antivirus scanning. [UN-465]

• Inbound transactions that are replayed are now executed as the integration instead of the current user. [UN-473]

• Fixed an issue with Field Choice generation not having the table set. [UN-475]

• Replaying an HTTP Request now increments the number correctly. [UN-478]

• Errors thrown in Field Map scripts will now show up in the Transaction. [UN-479]

• Fixed an issue with replaying Transactions created by system. [UN-482]

• Fixed Bond History state logging. [UN-485]

• Fixed an issue with false-positive updates from Transactions. [UN-505]

• The "Generate field choices" action on Field now checks for existing Field Choice entries. [UN-516]

• Reference fields in Messages are now correctly updated when copying an Integration. [UN-530]

• Fixed an issue where full Activity Logs would be sent to system log. [UN-534]

• Logging verbosity is now allowed at error level. [UN-535]

• Fixed an issue where queued Transactions would not be processed. [UN-543]

• Connection is now updated when the Integration name is changed. [UN-552]

• API names are now allowed to use a zero (0). [UN-553]

• Clicking the "Generate field choices" action on Field will save the record first to ensure choices are generated correctly. [UN-556]

• Response Action user notifications now work. [UN-562]

• Fixed undefined error with Ignore Transaction button [UN-592]

• Fixed issue in generating messages without a Connection URL [UN-638]

Integration Designer (Portal) Changes

• Transactions are now ordered by date created in the live feed. [UN-452]

• Side menu options are now highlighted when selected. [UN-453]

• Reference links now navigate to the Portal pages instead of native ServiceNow. [UN-454]

• Changed the style on inactive Boolean fields to differentiate them from read-only Boolean fields. [UN-564]

• Embedded fonts/icons to improve page loading times. [UN-572]

• Added Enable/Disable button to form headers for easy access. [UN-641]

Integration Designer (Portal) Fixes

• Fixed read error when attempting to view a record in Portal as a non-admin. [UN-403]

• Fixed Portal font size for instances running Madrid onwards. [UN-404]

• Fixed an issue with the operations dashboard truncating the live transaction feed when there are less than 20 transactions. [UN-407]

• Attachment sending can now be controlled from the portal. [UN-415]

• Condition widgets now work in Portal. [UN-434]

• Fixed an issue with variables payload and headers not being assignable in Message Scripts. (Closures have been replaced with instructive comments.) [UN-463]

• Outbound Attachment properties are no longer visible for inbound only messages. [UN-472]

• Bond scripted condition type only shows once instead of twice. [UN-558]

• Long text fields in Portal lists are now truncated to improve usability. [UN-569]

• Fixed render issue with reference fields that have no value in portal [UN-578]

• References in lists now show "(empty)" if there is no display value [UN-640]

• Fixed issue with form appearing read-only in Portal view when directly navigation to the URL [UN-642]

• Fixed issue with Portal form loads from an external link [UN-643]

• Added support for day-of-week type fields. [UN-566]

• Added support for time fields. [UN-567]

• Added support for interval fields. [UN-568]

• Lists and pages now update the title in Portal. [UN-637]

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.

Unifi Integration Designer

From within native ServiceNow, open the Unifi Integration Designer portal by navigating to [ws] 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.

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

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

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

Release

Overview

Integration Guides

Feature Guides

Bonding

Transport

Configuration

Polling

Administration

Scripting

Attachments

Inbound User

Before configuring the Connection, you need to ensure you have a user in the instance to use as the Inbound user for the Integration. To configure your Inbound 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, click on the 'Connections' icon, then 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_developer_instance>.service-now.com/api/now/table/incident

Your New Connection modal should look like this:

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

14) Save the Connection.

We are now ready to step back into the native ServiceNow window to configure the Trigger.

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.

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.

Copy Field Maps

The Field Map we shall use for our CreateIncidentResponse Field record is:

• Source Reference

To copy the Source Reference Field Map, navigate to the 'Field Maps' icon.

1) Click on the ellipsis to the right of the Source Reference Field Map & click Copy.

Copy Field Map Modal

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

Your Copy Field Map modal should look like this:

3) Click Copy.

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

Field: result.sys_id

In Unifi Integration Designer, from the CreateIncidentResponse page, navigate to Message > Fields. Click New.

The fields to be configured for the sys_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.

The 'result.sys_id' New Field modal should look like this:

10) Submit the record.

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

Build

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

The following Field record should now be in place for your CreateIncidentResponse messsage:

11) Click on Build Message.

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

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

Your Script Editor fields should look like this:

Message Scripts

We will now examine our new, auto-generated Message Scripts.

Payload to Stage:

Stage to Target:

Next, we will configure the CreateIncident Message.

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 (String), 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:

• String

• Choice

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

Field: incident.caller_id

In Unifi Integration Designer, from the CreateIncident page, 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:

5) Submit the record.

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

Field: incident.short_description

Because the incident.short_description Field record is the same 'type' (IS - String) & the majority of the settings are the same as the previously configured Field, it will be quicker to copy the incident.caller_id Field & make a few minor changes.

6) Click the ellipsis next to the incident.caller_id Field record & click Copy.

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

Your Copy Field modal should look like this:

9) Click Copy.

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

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

To quickly navigate to the CreateIncident Message from the Details page of the newly created incident.short_description Field record...

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

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:

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

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

16) Navigate to Field > Field Choices.

17) Click Generate field choices.

18) 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 the remaining Field records for the rest of the Incident fields (as per the 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:

19) Click on Build Message.

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

20) 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 will now examine our new, auto-generated Message Scripts.

Source to Stage:

//===== [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.
 */

x_snd_eb.ws_console.execute("Mapping incident.caller_id [x_snd_eb_field.do?sys_id=2e3f564ddb7d985094dbd7795e961930]", function () {
  log.debug("Field map: IS - String [x_snd_eb_field_map.do?sys_id=006de8cddbf5985094dbd7795e96191e]");

  var default_value = (function () {
    return '';
  })();

  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;

  if (is_mandatory) {
    $stage.caller_id = '' + (source.caller_id || default_value);
  } else if (source.caller_id != '') {
    $stage.caller_id = '' + source.caller_id;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.short_description [x_snd_eb_field.do?sys_id=aa75199ddbb5d85094dbd7795e9619d5]", function () {
  log.debug("Field map: IS - String [x_snd_eb_field_map.do?sys_id=006de8cddbf5985094dbd7795e96191e]");

  var default_value = (function () {
    return '';
  })();

  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;

  if (is_mandatory) {
    $stage.short_description = '' + (source.short_description || default_value);
  } else if (source.short_description != '') {
    $stage.short_description = '' + source.short_description;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.state [x_snd_eb_field.do?sys_id=7c78295ddbf5d85094dbd7795e9619fd]", function () {
  log.debug("Field map: IS - Choice [x_snd_eb_field_map.do?sys_id=a58d2401db39985094dbd7795e9619fd]");

  var default_value = (function () {
    return '';
  })();

  var field_choice;
  var is_mandatory = false;  

  if (!source.state.nil()) {
    field_choice = new GlideRecord('x_snd_eb_field_choice');
    field_choice.addQuery('table',         '=', 'incident');
    field_choice.addQuery('element',       '=', 'state');
    field_choice.addQuery('integration',   '=', '642bd074dbb9585094dbd7795e9619a7');
    field_choice.addQuery('field.message', '=', '');
    field_choice.addQuery('direction',     '=', 'Outbound');
    field_choice.addQuery('value',         '=', source.state);
    field_choice.addQuery('active',        '=', 'true');
    field_choice.query();

    if (field_choice.next()) {
      $stage.state = '' + field_choice.external_value;
    }
  } 

  if (!$stage.state) {
    $stage.state = '' + (source.state || '');
  }

  if (is_mandatory) {
    $stage.state = '' + (source.state || '');
  }

});

if (x_snd_eb.ws_console.has_error) {
  var errors = x_snd_eb.ws_console.get({type: 'error'});
  if (errors.length) {
    throw errors[0];
  }
}

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

Stage to Request:

//===== [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.
 */

x_snd_eb.ws_console.execute("Mapping incident.caller_id [x_snd_eb_field.do?sys_id=2e3f564ddb7d985094dbd7795e961930]", function () {
  log.debug("Field map: IS - String [x_snd_eb_field_map.do?sys_id=006de8cddbf5985094dbd7795e96191e]");
  payload = payload || {};
  var $payload = payload;

  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;

  if (is_mandatory) {
    $payload.caller_id = '' + $stage.caller_id;
  } else if ($stage.caller_id) {
    $payload.caller_id = '' + $stage.caller_id;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.short_description [x_snd_eb_field.do?sys_id=aa75199ddbb5d85094dbd7795e9619d5]", function () {
  log.debug("Field map: IS - String [x_snd_eb_field_map.do?sys_id=006de8cddbf5985094dbd7795e96191e]");
  payload = payload || {};
  var $payload = payload;

  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;

  if (is_mandatory) {
    $payload.short_description = '' + $stage.short_description;
  } else if ($stage.short_description) {
    $payload.short_description = '' + $stage.short_description;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.state [x_snd_eb_field.do?sys_id=7c78295ddbf5d85094dbd7795e9619fd]", function () {
  log.debug("Field map: IS - Choice [x_snd_eb_field_map.do?sys_id=a58d2401db39985094dbd7795e9619fd]");
  payload = payload || {};
  var $payload = payload;

  var is_mandatory = false;  

  if (is_mandatory) {
    $payload.state = $stage.state;
  } else if ($stage.state) {
    $payload.state = $stage.state;
  }

});

if (x_snd_eb.ws_console.has_error) {
  var errors = x_snd_eb.ws_console.get({type: 'error'});
  if (errors.length) {
    throw errors[0];
  }
}

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

We are now ready to Test our CreateIncident Message.

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:

(function executeRule(current, previous /*null when async*/) {

    x_snd_eb.snd_console.execute('Business rule: Unifi Incident Trigger', function () {
        x_snd_eb.ActivityLog.setDocument(current, current.getTableName());
        x_snd_eb.Message.processOutbound(current);
    });

})(current, previous);

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.

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.

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.

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:

bond.setOpen();

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.

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.

Create an Incident

Navigate to Incident > Create New.

The Incident fields to configure are as follows:

Your Incident form should look like this:

3) Right-click & Save.

Note the values entered (including State & Priority), 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:

You should also see a note in the Activities stream:

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:

4) A Bond has been created. The State remains 'Pending' until the list is refreshed.

5) Refresh the list by clicking Bonds.

You should see the External reference populated & the State changed to 'Open':

6) Click the Bond Number link to open the Bond record.

View the Bond

Your Bond record should look like this:

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

8) History:

• < History of transaction updates on the Bond > (Sending CreateIncident...)

9) Transaction:

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

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

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

12) Business rule: < Your Trigger >: Logs from the Business Rule that triggers Unifi.

View the Transaction

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

Your Transaction record should look like this:

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

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

15) Stage:

• Direction: 'Outbound'

• Message: 'CreateIncident'

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

16) Stage details:

• Direction: 'Outbound'

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

• Internal reference: < ServiceNow ticket reference >

• Message: 'CreateIncident'

• Transaction: < Your Transaction >

• Integration: < Your Integration >

17) Mapped stage 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 HTTP Request record from the related list on the Transaction.

Your HTTP Request record should look like this:

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

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

20) Caller: < Your Caller >

21) State: < Your State >

22) Short description: < Your Short description >

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

We are now ready to move on to the Update 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 CreateIncident New Message modal are as follows:

Your CreateIncident 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:

*This field is automatically defaulted to true.

Your Response form should look like this:

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

10) Navigate to Outbound > Trigger.

Outbound Trigger Fields

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

Your Outbound Trigger form should look like this:

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

14) Click Save.

We are now ready to configure the Fields for our CreateIncident 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):

1) Click New.

New Message Modal

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