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]

Introduction

The ShareLogic Unifi 3.0 release includes a range of new features, improvements and fixes. Read on to find out about exciting new capabilities that will further enhance your experience.

Unifi 3.0 Highlights

Test Assistant

Unifi 3.0 introduces the Unifi Test Assistant as a way to view, run and analyse automated tests in your instance. Test Assistant helps to remedy the issues of regression testing large numbers of integrations when you come to upgrade your ServiceNow instance or Unifi itself. Tests are created with one click from existing bonds, and can be tested at any time. Exporting tests to your other instances is a breeze as the tests are packaged with your integrations.

Dynamic Documentation Update

The integration documentation automatically generated for every integration has had a major overhaul with a new layout, better navigation, and major performance improvements.

New Features & Improvements

• UN-114 Added a Connection Test button to perform a simple high-level test of the connection to the specified endpoint.

• UN-187 Automate creation of the Business Rule on any table that has a Unifi message assigned to it.

• UN-783 The table field is now cleared when copying Receipt or Response messages.

• UN-794 Added Run Conditions Section to Event Actions in Unifi Designer.

• UN-796 Added checks for Unifi properties in Diagnostic.

• UN-797 Attachment trigger Business Rule is now wrapped by console so it generates Activity Logs.

• UN-807 Improve ActivityLog performance within loops.

• UN-809 Added system property to control of the maximum age of Activity Logs.

• UN-810 Modified attachment processing so that it will only be processed when the related record is already bonded.

• UN-811 Improvements to Activity Log performance.

• UN-812 Inbound REST methods are automatically created when Processes are defined/updated.

• UN-813 Warning during outbound message processing (e.g. "Ignoring messages for integration ...") have been changed to debugs.

• UN-818 Editing a field map now causes the Integration Build button to be shown.

• UN-828 Transaction Replay from list view now informs the user if replays have been unsuccessful.

• UN-890 Connections can be assigned an instance to prevent production integrations running in sub-production instances when cloned.

• UN-908 Add fields and field maps to documentation.

• UN-912 Added links to various configuration records in platform so they can be easily opened in Unifi Designer.

• UN-915 Show number of active integrations to make it easy for people to know how many licences they have used.

• UN-916 Add Response Actions to Unifi documentation generator.

• UN-917 Add Poll Processors to Unifi documentation generator.

• UN-918 Add Scheduled Jobs to Unifi documentation generator.

• UN-924 Update to Transaction and HTTP Request numbers to show decimal suffix on first attempt.

• UN-930 Allow message scripts to be toggled on dynamic documentation.

• UN-952 Bond ownership can now be controlled from Message fields.

• UN-953 Bond state can now be controlled from Message fields.

• UN-967 Added information box to Connections page in Unifi Designer to show the inbound endpoints of the integration.

• UN-968 Process page now shows all fields in Unifi Designer.

• UN-969 Attempt number is now shown on inbound HTTP requests.

• UN-972 Related Event Actions are now shown on Messages.

• UN-973 Messages are no longer prefixed with 'Copy of' if copying to another Integration.

• UN-976 Messages are now ordered by name in Unifi Designer.

• UN-977 Inbound transactions now set the source connection on the bond.

• UN-978 Field inheritance is now active by default.

• UN-988 Authorization header is masked in the headers on HTTP Request.

• UN-992 Add support for headers and request in Payload to Stage message scripts.

• UN-1000 Enhance Activity Log with success messages.

• Other minor portal improvements.

Changes

• UN-830 Bond history has been removed from the Bond form for performance.

• UN-882 Updated the top navigation menu links in portals.

• UN-889 Updated the 'Get help' portal page to show new branding and information.

• UN-978 Field inheritance is now active by default and the form is locked down if inherit box is checked.

Fixes

• UN-771 Fixed auto-documentation printing layout.

• UN-795 Fixed an issue where sending an attachment on new would incorrectly commit a new empty bond when the attachment failed to send.

• UN-798 Fixed the Event Actions table field so it shows Unifi tables.

• UN-799 Fixed an issue with the Event Action advanced condition also running the standard condition.

• UN-800 Fixed an issue where no table being set on an Event Action would cause it to break.

• UN-803 Fixed an issue where inactive Event Actions were being processed.

• UN-808 Fixed domain value during HTTP Request retry.

• UN-816 The Response Action field is now cleared when replaying a Transaction.

• UN-820 Modified the attachment business rule condition to prevent an error when 'previous' object does not exist.

• UN-822 Fixed the Diagnostic and Self-Test roles so they accessible by the Unifi admin role.

• UN-829 Fixed an issue preventing a Unifi admin user from replaying Transactions.

• UN-831 Fixed the inbound processing so that the transaction and bond domain are set correctly from the domain on the request.

• UN-833 Added measures to prevent the increased async rule performance from causing blank tickets.

• UN-865 Fixed an issue with the domain not being set when replaying a transaction or request.

• UN-867 Fixed an issue with a successful Transaction not changing the Integration Status from "Awaiting" to "Up".

• UN-868 Prevented a situation where an outbound sync response that updated the process record could cause an update loop.

• UN-870 Fixed JellyRunnerLite from leaking a global 'result' object.

• UN-880 Fixed an issue where copying an integration and clearing the target scope would result in the new integration being in the Unifi scope.

• UN-909 Fixed an issue where the HTTP Request retry count failed when it gets to number 10.

• UN-910 Fixed an issue where the HTTP Request attempt number was not updated when Replay is used.

• UN-914 Introduced auto-refresh to the Operations portal to prevent the connection from being dropped.

• UN-946 Fixed an issue with the Resume integration worker popup showing the wrong number of transactions

• UN-962 Field bug where copying a Message between Integrations showed 'Build Integration' in the originating Integration, and not the target integration.

• UN-971 Fixed an issue where copying a Message to another integration resulted in fields in a different integration.

• UN-987 Fixed issue with form choice fields becoming unresponsive in portal forms.

• UN-993 Fixed Resume and Repair worker counters being wrong when processing more than 100 records.

Notices

Unifi 4.0 Highlights

Datasets

We are extremely proud to introduce official support for mass data import and export with a brand new feature called Datasets.

Datasets allow you to easily configure imports and exports of large amounts of data on a schedule, with transformation being achieved through the standard use of Unifi Fields and Field Maps, and transportation via automatically generated attachments sent within Unifi Messages. Data is automatically chunked and filtered for delta updates, with full sync being available at any time with one button click. Datasets have been built so you still get the benefit of Unifi operational data but with huge efficiency gains for large amounts of data.

Integration Dashboard

Diagnose and managed your integration with the new Integration Dashboard, containing stats, diagnostics, and access to common integration development actions.

Portal Performance

We're continuing to refine the portal interfaces and this update includes a significant performance boost to the Designer experience, along with several developments and updates to make integrations easier to manage and maintain.

Snapshot Table Cleaner

The Snapshot table was introduced in a previous release as both a mechanism to support automated testing and a precursor to a more efficient method of processing outbound messages which we intend to move towards in a future release. Unfortunately, no cleanup job was included and this table has been known to become very large.

While this update includes a cleanup job to rectify this issue, we strongly recommend the table be emptied before updating to this version since this will be much faster than relying on the job. Note: Once the table is emptied, Unifi will not be able to create tests for existing bonds.

New Features & Improvements

UN-933 Bond cleanup logic to use scheduled jobs rather than events

Previously, transactional data relating to bonds was removed by an event specifically for that bond that was created when the bond was closed. For customers with long data retention requirements, this could result in thousands of queued cleanup events.

The cleanup logic has now been updated to improve this. A new field called Cleanup date has been added to Bond records. The Cleanup date is set when the bond is closed and specifies the time the transactional data for the bond should be cleaned. A scheduled job triggers an event and script action once per day. Any records which have a cleanup date before the current date are cleaned. (Note: the job is designed to chunk the processing to prevent excessive system resource consumption for systems with high cleanup volumes.)

UN-980 Add a role check to the inbound user on Connection

A new diagnostic test has been added to ensure the inbound users specified on a Connection has the x_snd_eb.integration role.

UN-1044 Improve the Designer Dashboard

The dashboard in Unifi Designer has been improved and updated with a number of new features including:

• New “All Integrations” pane with tabs for switching between processes and integrations

• Search bar to allow contextual search for all integrations or just those in the selected process

• Reversible sorting for Name and Updated date

UN-1070 Parent field should show child fields in Designer

A field that has its configuration inherited by child fields now shows a list of those inherited fields.

UN-1092 Fields list needs more fields

The list of fields in Designer now shows more columns to make it easier to find and identify fields.

UN-1096 Add message direction to Scenarios list in Test Assistant

The Scenarios tab show within a test in Test Assistant now shows the direction of the scenario to make it easier to see which way the messages are flowing.

UN-1125 Prepopulate the instance name on the connection

Connections have the ability to specify the name of the instance the connection belongs to. This value is now prepopulated with the instance name when the connection is created. The value used is from the system property instance_name.

UN-1127 Allow receipts to ignore timeout

Asynchronous integrations use a request-receipt pair of messages where the receipt is a new message sent by the other system to confirm it has processed the original request. Unifi allows a timeout to be specified so that transactions with requests that do not receive a receipt within a given duration can be flagged for investigation with the Timed Out state. By default, Unifi operates in best practice and discards receipts to messages that have timed out, however this update introduces a new setting on the integration to change this behaviour. Setting Process timed out transactions to true on the integration will allow receipts to be processed regardless of how long they take.

UN-1128 Update error text for inbound receipts that are rejected

Previously, when an inbound receipt was rejected because the Transaction state was not “Awaiting Receipt”, the response error would just indicate that it is because it has been “processed already”. This is not always the case so the error message has been updated to explain the actual reason which should be more helpful in testing and operational investigations.

UN-1129 Update inbound connection error responses so it's clear they are from Unifi and not ServiceNow

Response errors for inbound requests that are generated by Unifi have been updated with a [Unifi] prefix so that users can more easily determine if the error is a platform issue such as an invalid user/password or a Unifi issue such as no connection was found.

UN-1130 Update Unifi data preservers to be included in system clones

The Unifi Data Preservers have been updated so the Include in system clone field is now true, allowing system clones to keep existing data on the target instance.

UN-1137 Add last successful execution time to Poller data

Pollers generally need to know the last successful request time so future queries can filter the data efficiently. A new Data Store called $last_completed which contains an ISO date time is now automatically stored on Pollers and is set when a Poll Request state changes to Complete. The Poller object has a new method getLastCompleted() that can be used which returns a GlideDateTime object of the $last_completed value or a new GlideDateTime object if any validation on the datetime fails.

UN-1140 Integration dashboard

A new dashboard has been added to Integrations in Designer to make it easier to manage and diagnose the integration. The dashboard is now the default view of the integration, with the integration settings being moved to a new "Integration" menu option.

UN-1148 Prevent "Copy of" prefix when copying configuration to another integration

Updated copy logic so "Copy of" is only prepended when the name and integration have not been changed by the user or the copy process.

UN-1149 Update Message Path hint to show ${} as well as {} since both are valid

Minor label update to show that ${code} and {code} are valid in the Message path field for running inline code.

UN-1152 Triggering a poller should open a window of poll requests

Executing a Poller in Designer will now open the new Poll Request.

UN-1160 Default the action method field on Message to POST when integration is REST

Unifi has always used POST as the default REST method when no method has been specified on a Message by the user. This value is now set by default for REST integrations so it is explicitly defined and easy to see.

UN-1165 Add snapshot cleanup logic

A new cascading job has been introduced to cleanup Snapshot records.

UN-1167 Update async business rules to use the new async type

ServiceNow have deprecated async business rule with the introduction of new async processing. All Unifi async rules have been updated to use the new version.

UN-1173 Add a check to diagnostic for pollers in production which have the attach response payload set to true

Best practice in Unifi is to turn off unnecessary logging and payload storage in Production since these are generally only necessary in development. A new diagnostic check has been added to find active pollers belonging to active integrations in a production instance which have the Attach response payload flag set as true. The recommendation is that this flag is disabled for Production instances.

UN-1179 Add recent history links to Designer dashboard

Unifi now stores 30 recent items that have been viewed in Designer for each user so they can be accessed easily. These are accessed through a new icon and menu system which has been added on the top-right of Designer.

UN-1181 New diagnostic checks

Unifi Diagnostic has been fully updated with new diagnostic tests, updated messages, and the ability for many issues to be fixed at the click of a button.

UN-1186 Improve form load times

Forms now render much faster in Designer, in many cases almost immediately, with fewer round trips to the server and less work for the server to do.

UN-1187 New capability for Unifi to synchronise large datasets efficiently

Introduced the new Dataset feature to allow mass data import and export within Unifi.

UN-1188 Add new message type called Dataset

A new Message type called Dataset has been added to support Dataset processing. Dataset messages are not processed by Unifi trigger rules.

UN-1189 Add dataset records to the Integration Packager

Datasets are packaged with integrations for export.

UN-1194 Add support for inbound request query parameters

Payload to Stage and Stage to Request scripts now have access to a new variable called query. This is a key-value object that represents the search query parameters in the URL and operates in the same way as the headers object. It can be used to read query parameter values inbound and write them outbound. When writing outbound in the Stage to Request script, the query object will be compiled and automatically added to the search query of the URL.

UN-1198 Allow Script Editor fields to be selected individually

It is now much easier to select one script when editing message scripts in Designer. The menu bar has been updated, with a new "Only" option being added to Scripts shown in the "Change view" menu.

UN-1202 Response Action and Event Action lists should always show Integration

Integration is now always shown in Response Action and Event Action lists, making it easier to distinguish between integration specific and Unifi specific records.

Fixes

UN-654 Transaction Timed Out does not set Bond to error

A Bond is now set to an Error state when the current Transaction gets set to the Timed Out state, reflecting the fact that no more Transactions can be processed until the current one has been addressed.

UN-1040 Multiple heartbeats in a single integration do not process correctly

Introduced a new rule to prevent more than one Heartbeat message being active at one time.

UN-1056 Copying Unifi records in Designer causes the system to hang

Fixed a bug that occured when copying a field map in the Designer portal. The request would hang and the system would be blocked. The only way to resume things was to manually call cancel_my_transaction.do. This was caused by a scope issue with Field Maps, Response Actions and Event Actions; they now have their scope set automatically to be the same as the integration scope.

UN-1058 The list of fields shown on message does not show integration level data fields

The embedded list of fields on a message in Designer now shows all integration level fields, not just those that specify a table.

UN-1060 Clicking New from a list in Designer will show previously entered data

Creating a new record in Designer using a modal will now always have default values reset.

UN-1061 Clicking New from a list in Designer will always take a long time to load

Added caching support for new records so the user does not need to wait for a full form load from the server in order to create a new record.

UN-1062 Readonly Unifi records are not showing as readonly in Designer

Fixed a bug where fields were not being checked for readonly.

UN-1068 Changing the name of a field does not inherit

Field name changes are now inherited by all child fields.

UN-1069 Scripts that have syntax errors can fail silently

If a field has a map to the payload containing a reserved word, e.g. class, then the script will fail silently and no error will show in the ActivityLog. Since ServiceNow basically ignores any issues with scripts wherever possible and just stops working when it cannot, a new diagnostic test has been added to ensure that message scripts pass Javascript validation tests.

UN-1078 ActivityLog user is always shown as the user viewing the log

Fixed a bug with Activity Log rendering so it shows the user that created the Activity Log instead of the user viewing it.

UN-1109 Field inherited notification is missing when viewing Portal fields

Fixed notifications and other display issues introduced with form caching by adding manual support for display business rules.

UN-1110 Rest Service details are not populated on the Process

Fixed an issue when creating a new Process where the corresponding REST service details are not automatically populated meaning they would not be packaged.

UN-1117 Empty bonds are created and a duplicate sys_id error is thrown

In newer versions of ServiceNow, several customers have reporting that they very rarely see an issue with an empty bond which ends up stopping the transactions from flowing. This was not an issue until the introduction of the new async business rule processing which executes rules almost immediately. Previous inherent latency with event processing meant the issue was entirely hidden and therefore not a problem. New logic has been added which checks for the bond before the transaction is allowed to move into the processing phase.

UN-1123 Replaying a request a second time will run as the current user

Since the current user inserted the new request, ServiceNow executes the request replay as that user. This is fixed with the use of user impersonation for executing the request as it was originally and is supported by the latest version of Unifi Global Utility.

UN-1124 Messages do not authenticate correctly when using OAuth 2.0

Systems using bidirectional asynchronous integrations between two ServiceNow instances where both instances are using OAuth 2.0 can experience connection problems with receipt processing. This is fixed with the use of user impersonation when sending the receipt and is supported by the latest version of Unifi Global Utility.

UN-1132 Transaction number in queueing message instead of integration

Removed the log section . The integration is "TXN0000098040.01". as the integration and transaction number are already mentioned.

UN-1133 Resuming an Integration does not change the Integration status away from Down

Resuming the integration now sets the status to "Awaiting". Once a transaction completes, the integration is set to "Up".

UN-1138 Poll requests do not have responses attached.

Since the deprecation of the integration attach logs debug feature, successful poll requests no longer have responses stored as attachments. A new field called Attach response payload has been added to the Poller and this is what now controls the payloads.

UN-1144 Duplicate bonds caused by triggering updates to records from parent table query

Fixed an issue where records in a hierarchy (e.g. CMDB) that have been updated on the root table would create bonds for the root table record instead of using the existing bond on the extended table record.

UN-1151 In Designer, browser history navigation does not work records

Fixed navigation in Designer so that the browser history is better maintained.

UN-1155 EventAction triage condition can fail to trigger the action

Fixed an issue where strings were being compared to numbers which would prevent the triage condition from working.

UN-1161 Custom auth headers are masked

In a previous release, Unifi introduced auth header masking on the HTTP Request. While intended only for inbound requests, it was a blanket mask since there should never be any auth headers stored. However, we have since found out that there are some custom auth solutions which manually add the auth header which would then be masked by Unifi and break the integration. This release fixes this issue so custom outbound auth headers are allowed.

UN-1162 Payload to stage errors do not fail an HTTP Request

When an error is thrown in an inbound Payload to Stage script for a synchronous message, the system still attempts to identify the bond reference and the HTTP Request is marked as OK even though an error has occured. With this update, the original logic is used by default (since fixing this would be a breaking change for all customers using synchronous messaging), but the new logic that exits when an error occurs can be used by setting request.$abort_process_with_request_error = true; on the payload to stage message script. This will cause the request to exit and prevent further inbound sync logic from running.

UN-1163 Bonded attachment errors are not flagged as errors for integration notes

Fixed attachment errors so that options.type == "error" making it more easily recognisable by the Integration feedback script.

UN-1168 Diagnostic fails with an error when no Global Uitility is installed

Added a check to prevent this issue from occuring.

UN-1169 Script fields do not work in Designer

Some instances of ServiceNow handle UI Script URL's differently, with inline forward slashes working most of the time, but not all the time. This means the UI Script x_snd_eb.keymap/sublime.min.js may not load and this would prevent scripts from loading. The issue has been fixed by changing the slash to a dot: x_snd_eb.keymap.sublime.min.js.

UN-1171 Outbound heartbeat message fails with a custom stage table

Fixed an issue with internal configuration not being updated so the custom stage table was not known.

UN-1178 Designer navigation is slow due to ServiceNow sessionRotationTrigger update

ServiceNow have introduced a new URL flag to Service Portal which causes the URL to be rewritten after it's been requested, meaning it essentially does a double load. The issue has been fixed by manually adding the flag before ServiceNow does.

UN-1182 Calling ws_console.logActivity without a second parameter will throw an error

Fixed by checking for the second parameter before using it.

UN-1184 Instance names with HTML display badly in Unifi

Unifi Designer displays the name of the instance in the header bar, but this looks terrible for instances that have HTML in the instance name. HTML is now stripped from the instance name in Designer so it renders nicely.

UN-1185 Company link from integration panel does not work

Fixed the company table reference so that the links work properly in the operations dashboard.

UN-1193 Editing field order from a message field list view doesn't save

Fixed a bug with field level ACLs so they render correctly in Designer. The field order cannot be written to when it is an inherited field.

UN-1195 Message scripts are built with a missing semi-colon which causes lint error

Added a semi-colon to the checkpoint definition in automatically generated Message Scripts. The script is updated when it is next built.

UN-1196 Using Ctrl + M in the Message Script Editor does not work properly

Fixed Designer so full screen mode in script editors now renders nicely.

UN-1199 Portal does not render glide_time fields correctly

Added support for GlideTime fields in Designer which are not natively supported in Service Portal. This allows Pollers and Datasets to use proper scheduling.

UN-1203 Empty reference fields have invalid (empty) link in lists in designer

Fixed an issue in Designer where target link generation would still occur even if there was no sys_id on the reference.

UN-1206 Warnings are not highlighted correctly in Activity Logs

Fixed invalid CSS in the Activity Log renderer.

UN-1210 Creating new records from a list in Designer does not always show default values

Added manual display rule support so that forms can be rendered quickly using caching but new values are still populated as expected.

UN-1211 New fields created from a message in Designer do not use the message table

Fields now use the Message table if related to a Message, otherwise they will default to the Process table.

What is Unifi?

Unifi is an integration platform built specifically to support complex ticket exchange integrations to and from your ServiceNow instance. From no-code to pro-code, Unifi gives you the flexibility, insight, and control to create exceptional integration experiences for you, your partners and your customers.

How do I get Unifi?

Unifi is a ServiceNow application that is delivered and managed through the . You can find out more information and request a demo through our .

Follow these steps to install or upgrade Unifi.

1. Install or Upgrade Unifi

2. Install Global Utility

3. Install Hotfix

4. Configure

1. Install or Upgrade Unifi

Unifi is exclusively available through the ServiceNow Store with a limited trial or paid subscription.

To install Unifi on your instance, you will need to ensure it has been given entitlement to the application. You must do this through the ServiceNow Store.

Once you have setup entitlement, you can use the Application Manager in your ServiceNow instance to install and upgrade Unifi. You can find more information on how to Install a ServiceNow Store Application in the ServiceNow Product Documentation.

2. Install Global Utility

Unifi has some powerful features that will only work with access to the global scope. Access is granted through the Unifi Global Utility.

Full details can be found on the Global Utility page.

3. Install Hotfix

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

Full details can be found on the Hotfixes page.

4. Configure

You're good to start building your first integration or import one you already have.

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.

Unifi 3.1.2

Release date: 17 November, 2021

Improvements

UN-1077 Change "Created ms" and "Updated ms" to be date-time on transactional records

These fields were previously showing millisecond values. They now show system date-times which will make them easier to read and sort.

Fixes

UN-1003 Target caching fails when processing multiple messages in the same thread

Fixed an issue where multiple bonds could be created. When running multiple updates in the same thread, e.g. a GlideRecord loop, it was possible for the the target record to be changed which could result in new bonds being created unnecessarily. This was due to a new feature of GlideScopedEvaluator which replaces the object in memory thus breaking internal Unifi script references.

UN-1041 Field default scripts appear to be editable when they are locked

Due to native Service Portal modifications, script fields in Designer would no longer appear locked even though they were read-only. This fix addresses the styling.

UN-1055 Designer form loading does not update system fields

The latest performance improvements to Unifi Designer introduced a caching bug for system fields which is now fixed.

UN-1072 Execute Now on pollers runs the poller as the current user, not the user specified on the poller

The Execute Now button on Pollers has been fixed so that Pollers are executed as the specified user and not the user who is logged in.

UN-1098 Multiple bonded attachments from one attachment

We've seen some issues caused by attachment records being updated multiple times in rapid succession (thousandths of a second) by the system user which occasionally will result in multiple Bonded Attachment records being created for the same attachment. We suspect that this is due to ServiceNow Antivirus scanning and updating the attachment record. To account for this, we’ve created two business rules to fire attachments, one for inserts and one for updates.

UN-1106 Global utils version is not correct in the licence report

Fixed an issue with the licence report not identifying if the Unifi global utility was installed.

Unifi 3.1

Release date: 20 September, 2021

Automatic Heartbeat

Heartbeat messages can be setup to automatically monitor and manage the integration. When a heartbeat message fails, the integration status will be marked as "Down" and all outbound messages will be queued. As soon as another heartbeat is successful, the integration status is marked as "Up" and the integration is automatically resumed.

Portal Performance

Unifi Integration Designer benefits from a significant performance upgrade with lists and forms loading up to 10x faster than previous versions.

New Features & Improvements

UN-239 Add connection test/heartbeat

Users can now create Messages with type heartbeat which will be automatically sent periodically to the target endpoint and help to prevent failed outbound transactions.

UN-262 Add scripted condition to Response Actions

Response Actions now benefit from a scripted condition field so complex logic can be used to determine whether or not a Response Action should be used during outbound response processing.

UN-424 Default Response Action for heartbeat message

A new Unifi Response Action has been added to support the logic for heartbeat messages pausing and resuming the integration.

UN-435 Automatically create and maintain heartbeat message scheduled jobs

A scheduled job is automatically created and managed based on the presence and state of a heartbeat message within an integration and the integration itself.

UN-623 Add OAuth Get Token button to Connection

Connection records now benefit from an UI Action/button that can be used to generate OAuth tokens. The button only appears when the connection authentication is set to be OAuth 2.0.

UN-650 Allow Response Actions to cater for group codes

Response Actions are now able to handle group codes rather than just one code per action. For example, setting 5xx will match all 500 based response codes.

UN-1012 Add version and integrations to about modal

We've made it easier to find what version of Unifi you are using and included the number of active integrations in the About modal, available from the support menu.

UN-1016 Message Fields list should filter on Message table

Fields available to add to a Message are now filtered by the Message table in Designer, meaning you won't see fields that aren't relevant anymore.

UN-1017 Allow Async heartbeat messages

We've added support for heartbeat messages to be run both synchronously and asynchronously, meaning they work the same way as any other message in Unifi.

UN-1020 Add cleanup for old heartbeat transactions

Heartbeat transactions are automatically cleaned up every hour by the "[Unifi] Cleanup old heartbeat transactions" Scheduled Script. Two properties have been added to control the retention for complete vs failed heartbeat transactions.

UN-1027 Heartbeat messages should automatically send identifying request headers

Two identifying headers are automatically added to every heartbeat message that is sent: the identifying message header X-SND-EB-Message-Name and the heartbeat indicator X-SND-EB-Heartbeat.

UN-1029 Heartbeat messages should only send when the integration is active

As above. Heartbeat messages are sent only when the integration is active - this includes sending when the integration is paused.

UN-1030 Heartbeat messages should not be queued

Heartbeat transactions are not queued in the same way other transactions are queued in Unifi.

UN-1031 Prevent creation of integrations in the Unifi scope

We've added some measures to help prevent integrations and other content from being created in the Unifi scope. This is disabled by by default in 3.1.2.

UN-1036 Add headers variable to response action

Response Actions can now make use of the headers which were provided with the response to an outbound request.

UN-1037 Transaction Repair should not process heartbeat messages

Failed heartbeat messages are ignored when repairing an integration.

UN-1038 Message sending should be queued when the integration is down, not just paused

To support heartbeat functionality, we allow transactions to be created and queued for sending when the integration is flagged as down, not just when it is manually paused by an administrator.

UN-1043 Hide portal announcements for Unifi portals

Customer global portal announcements will no longer be shown in the Unifi portal.

UN-1046 Reduce number of calls to clear scope messages

This is a performance improvement to the portal to prevent "scope changed" UI messages from being shown in the native platform view.

UN-1047 Performance improvements

Numerous performance improvements made to the portal, including optimising widget dependencies, preventing global UI scripts from loading with every widget request, and reducing the use of $sp.getForm().

UN-1051 Make all UI Scripts of type "Desktop" to prevent global loading with every widget request

Addresses a bug with ServiceNow that allows all UI Scripts that are not "Desktop" to be downloaded with every widget request.

Fixes

UN-929 Field.active button flickers off before settling on

Fixed a bug with the portal when activating fields on a message which would have the button enabled then rapidly disabled and enabled again.

UN-974 Copying Field Records (between Integrations) retains reference to original Field Map

Updated the copy logic to remove field map references from fields that are copied between integrations. The user needs to specify which field map to use from the target integration.

UN-1006 Connection Test Response Body Result Overrunning Connection Test Modal

Updated the Connection Test interface so that large response bodies are contained properly.

UN-1007 Full page script fields aren't editable - Unifi Integration Designer

Fixed a bug with script fields not being editable in Designer when they were be the only thing on the page (.e.g. Message XML Template)

UN-1008 Integration Test Scenario not replacing Connection or Endpoint URL

Fixed a bug with test assistant not properly updating the URL when porting tests between instances.

UN-1009 TypeError on Process Portal Page for Unifi Admin role

Fixed a JavaScript TypeError that only showed for Unifi Admins on the Process page in Designer.

UN-1010 About Modal Logo Colour Wrong

Fixed an issue with the about modal logo colour in Designer.

UN-1011 TypeError for Unifi Admin on Test Assistant Dashboard (Firefox & Edge)

Fixed a JavaScript TypeError that only showed for Unifi Admins on the Test Assistant Dashboard.

UN-1018 Event action count is incorrect on Message

Fixed the record counter for Event Actions related list on Message in Designer.

UN-1019 When creating a new Message in Designer, async is true by default

Fixed an issue where creating a new Message from the list view in Designer would always result in a Message that was set to async=true instead of it being controlled by the type of Message being created, e.g. response messages should not be async.

UN-1022 Inbound endpoints filter on Connection is not specific enough

Improved the logic for displaying inbound endpoints on the Connections list in Designer so that similarly named API's are no longer shown (i.e. an API of incident would also show inbound endpoints for an API of unifi_incident.

UN-1026 Number generation does not work correctly when instance is preventing numbering gaps

When the property glide.itil.assign.number.on.insert is set to true, numbers are not generated for Transaction and HTTP Request records on insert, but because we are adding ".01" to the end, the value was being populated as "null.01" and the number was never generated. We now account for this during record initialisation so numbers are generated correctly.

UN-1028 Errors in Reference lookup scripts are ignored

Fixed an issue where errors would be hidden if the payload was null or there was an error in the Reference lookup script on a Message. Errors are now shown correctly in Activity Logs.

UN-1032 Embedded Field list on Message is not showing non-table fields

When viewing a list of fields in the embedded list on a message in Designer, the Fields counter would show a different number of records than the number of fields actually shown. This was because of a query to show only table-related Fields. Now, all fields related to the table or no table at all are shown.

UN-1035 Server scripts with "use strict" cause errors

Removed "use strict" from two portal widgets because of incompatibilities with the Rhino engine and false errors being thrown from prototype based objects.

Creating a new Dataset for exporting and importing data is a simple 3-step process.

1. Create a new Dataset

2. Configure the Process Message

3. Configure the Send Message

4. Setup an export schedule

Create a New Dataset

1. Open Integration Designer and select or create an Integration.

2. From the main integration menu, select Datasets.

3. Click New.

4. Fill in the required information and choose your configuration.

5. Click Submit and view.

Creating a new Dataset will automatically configure several dependencies in your instance. These are:

• A Message called Process_<table>

• A Message called Send_<table>

• A Scheduled Import Set with the same name as the Dataset

• A Transform Map

Configure Process Message

The Process Message handles the data mapping. Use the Fields list to configure which fields are being imported/exported.

1. From the Dataset details tab, navigate to the Process message and use the clickthrough button to open it.

2. From the Message, open the Fields list and add the fields that should be imported/exported. Each field will need to have a Dataset specific Field Map for transforming the data.

3. Ensure at least one field will Coalesce so the import can match to existing records.

4. Click Build Message.

Configure Send Message

The Send Message handles the data to be imported or exported as an attachment.

The Path will need to be configured depending on where the data is being sent. If you are connecting to another ServiceNow instance using a ShareLogic endpoint, you will likely need to configure the Path to use the dataset web service at path "/dataset".

1. From the Dataset details tab, navigate to the Send message and use the clickthrough button to open it.

2. Open the Outbound > Settings page.

3. Configure the Path as required, e.g. "/dataset".

4. Click Save.

Setup an Export Schedule

Datasets have the same schedule logic as any other scheduled job and can be configured to export data whenever needed.

1. Open the Dataset.

2. Click Scheduling to open the scheduling tab.

3. Configure the desired schedule.

4. Click Save.

The Poll Processor is a configuration record which contains the logic that will be applied when polling a remote system for data. There are three main scripts which are used to setup, execute and process the Poll Requests.

Setup Script

The Setup Script is the first script to run (it runs at the point in time the Poll Request is created). It 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). It also supplies a params object as one of the arguments, which will be passed through to the subsequent scripts (and on to further Pollers, if required).

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. This could include converting the data from its proprietary format to a more usable format, sending the data to Unifi, or even kicking off a new poll.

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

Integrations Enabled

Control all integrations using this master switch.

Read-only Role

Allow users with this role to read bond records for informational purposes. Intended for giving access using related bond lists on the process tables. It does not expose the application menu. For greater control use the x_snd_eb.user role**.**

System Logging

Choose the required logging level for the application: 'debug' writes all logs to the database, 'info' writes informational, warning and error logs to the database.

Debug Mode

Use for general integration debugging to capture debug messages in the console in addition to info, warn and error.

Trace Mode

Enable input/output trace logs for functions that have been wrapped for tracing.

Core Debug Mode

Enable input/output trace logs for core application methods. This produces extremely verbose logs from all core scripts which will help ShareLogic Ltd if you ever run into trouble with the app.

The choices are:

• Off: No debug mode is active. Performance is not affected.

• Silent: Enhanced exception handling and error logs. Performance is slightly affected.

• Trace: Functional profiling in addition to enhanced exception handling and error logs. Peformance is affected. Requires Trace mode to be enabled.

Log Portal Activities

Turns on Activity Logs for Service Portal interfaces.

Activity Log Cleanup

How many days should Activity Logs be kept before being removed?

Designer: Standard list columns

Configure which columns are always shown on lists in the Unifi Integration Designer portal. Multiple columns should be separated by a comma.

Orphaned Transaction Cleanup Age

How many days should orphaned transactions be kept before they are removed?

Orphaned Transaction Cleanup Limit

What is the maximum number of orphaned transactions to remove at any one time?

Complete Heartbeat Transaction Cleanup Age

How many hours should successful heartbeat transactions be kept for before they are removed?

Failed Heartbeat Transaction Cleanup Age

How many days should failed heartbeat transactions be kept for before they are removed?

Enable Integration Attachments

Enables logs and payloads generated by Unifi transaction processing to be attached to transactional records.

Allow Unifi Files

Control whether to allow files to be created in the Unifi scope on Unifi tables (prefix x_snd_eb_)

Definition

An Integration defines the connection between a Process and the single system it’s connecting with. It is a record that contains all of the properties and configurations for that unique connection.

Multiple Integrations can exist for one Process and each unique Integration will define the way in which the Process connects with that particular system. (Unifi defines an integration as the connection of two systems to transfer or exchange data for one process. This is represented by one integration record in Unifi.)

Example

Incident Process - JIRA = one Integration

Incident Process - ATOS = one integration

Incident Process - SAP = one integration

Incident Process total = three integrations

Automated Creation of Trigger Business Rule

For step-by-step instructions on how to configure Integrations (and other Integration components) see the Integration Guides section of the documentation.

Integration Fields

Details

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

Message Identification

Messages are central to the functionality of Unifi. Upon receipt of an inbound request, Unifi will be able to identify the Message, know how to process it and subsequently what actions to perform based on the Message configurations. For that reason, it is very important that each Message within an integration be unique (more on that in the Messages section).

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

Identify message script (examples)

Unifi automatically looks for a header called X-SND-EB-Message-Name to use as the message name. If the header is found then the Identify Message Script is not executed.

Both the payload and headers are passed into the script. The following example will parse the XML payload and identify the message name from the first child element of the body node:

function identify(xmlDoc) {
  var message_name = '';

  message_name = '' + x_snd_eb.utils.identifyFirstChild(
    xmlDoc,
    '/soapenv:Envelope/soapenv:Body'
  );

  return message_name.split(':').pop();
}

The following is an example which returns the message name from a JSON payload:

function identify(payload) {
  return (payload.$message_name || '') + '';
}

Settings Fields

Attachments

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

Bond

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

Feedback

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

Error Handling Fields

General

The General Error Handling fields to be configured for the Integration record are as follows:

Timeouts

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

Retry

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

Native ServiceNow

There are some fields which are visible in native ServiceNow. These can be viewed by clicking the hamburger menu & selecting 'Open in platform'.

Integration Fields

The following non-selectable Integration fields are visible on the platform Integration record (and are controlled by Unifi):

Properties Fields

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

Attach logs/payloads

These are used for debugging purposes.

Copying Integrations

Definition

A Field Map defines the template code used by a Field in the various Message Scripts. 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). The template scripts are compiled during the Build activity where details of a Field record are substituted into the template, producing a Message Script specific to the Message and Field.

The Field Map defines the behaviour, or ‘type’ of a Field. Below is a table of the Field Maps packaged with Unifi:

Field Choice

As stated above, Field Choice is strictly a ‘type’ of Field defined by a Field Map. However, it is worth going into a little more detail here. A Field Choice record represents the mapping of an internal value to/from an external value and a set of Field Choice records can be defined for an Integration level Field.

• Internal values are used and stored by the source and target records.

• External values are carried in the payload and exchanged between integrated systems.

Configuration

If, for example, you wanted to map the Description field as part of the CreateIncident Message, you would only need to configure the incident.description Field (see previous page) and allocate it the String ‘type’ Field Map. There would be no need to configure the Field Map record. This would be the case in the majority of instances, using the shipped Field Maps for standard integrations.

If, however, you had a custom requirement to manipulate or transform data in some unique way, then a custom Field Map can be created.

Best Practice

Best practice is to only use Field Maps that belong to an Integration. You can do this by copying the OOTB Field Maps which are shipped with Unifi and labelling them as belonging to a particular Integration. This should be done for each Integration. That way any future updates which may be made to any of the OOTB Field Maps will not impact any of your Integrations and each Integration will comprise its own stack of self-contained records.

Example

In this example we will copy the OOTB String Field and rename it to be used for the Incident Guide Integration.

To copy the String Field Map, navigate to the Field Maps page.

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

On the Copy Field Map modal, update the Name and Integration as appropriate & click Copy.

Code in Action

The following is an example of a Source to Stage Message Script template from the String Field Map. The code between the dollar braces, e.g. $[field.element], is executed as JavaScript during the compile phase. The field variable is the Field GlideRecord object.

// Determines whether this instance of the field map is for a mandatory field
var is_mandatory = $[field.mandatory];

if (is_mandatory) {
  $stage.$[field.element] = '' + source.$[field.element];
} else if (source.$[field.element] != '') {
  $stage.$[field.element] = '' + source.$[field.element];
}

if (default_value) {
  $stage.$[field.element] = default_value;
}

The following block of code is extracted from The Source to Stage Message Script belonging to a CreateIncident Message which was generated using the above String Field Map template against the incident.description Field:

x_snd_eb.ws_console.execute("Mapping incident.description [x_snd_eb_field.do?sys_id=24347d2cdbdd3340957ddd3b5e961917]", function () {
  log.debug("Field map: String [x_snd_eb_field_map.do?sys_id=4719793adb58b700957ddd3b5e961974]");

  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.description = '' + (source.description || default_value);
  } else if (source.description != '') {
    $stage.description = '' + source.description;
  }

});

Integration Phases

To help you understand and give some context as to where these configuration records fit, we thought it would be helpful to layout the phases of an Integration as we see them.

Configuration Phase

• Field records are configured and linked to Messages (and/or Integrations) and Field Maps.

• Field Maps can be edited or created as needed.

• Field Choice records are added/edited as needed.

Build Phase

• The configurations defined by Fields and Field Maps are compiled into executable code and stored in Message Scripts. Existing Message Scripts simply have their code updated. Code outside of the demarkation comments in the Message Scripts is retained.

Operational Phase

• Messages and Message Scripts (and Field Choices) are interpreted and executed.

• Operational records such as Bonds, Stages, Transactions and Requests are generated and maintained.

There are four different types of script which are used either before or after the Stage. Having these script types in relation to the Stage allows us to find any potential errors/discrepancies in data more easily.

• Payload to Stage (Inbound)

  Data coming in is going to be translated (moved ‘as is’) from the Request to the Stage.

• Source to Stage (Outbound)

  Data going out is going to be transformed (moved and changed) from the source to the Stage.

  The following example extract from the Source to Stage Message Script shows location data being mapped:

if (!source.location.nil()) {
  stage.u_location_id = source.location.name;
  stage.u_address = source.location.street;
  stage.u_town = source.location.city;
  stage.u_county = source.state;
  stage.u_postcode = source.zip;
  stage.u_country = source.country;
  stage.region = source.region;
}

• Stage to Target (Inbound)

  Data coming in is going to be transformed (moved and changed) from the Stage to the target.

• Stage to Request (Outbound)*

  Data going out is going to be translated (moved ‘as is’) from the Stage to the Request.

Bond State & Ownership

The Message Scripts can also be the place where Bond state & ownership are set manually (without using the control fields on Message).

The following Stage to Target Message Script from the AcknowledgeCreateIncident Message sets the Bond state to Open:

(function processStageToTarget(target, stage, transaction, bond, log) {

  bond.setOpen();
  
})(target, stage, transaction, bond, log);

The following extract from the Stage to Target Message Script for a CreateIncident Message shows the ownership of the Bond is with the internal system target.u_ebond_owner = true;; therefore, Bond ownership cannot be with the external system bond.setValue('owner', false);. It also shows the source of the Bond being identified as the unique Integration with the external system sending the Message target.u_ebond_source = transaction.integration; (which can be particularly useful with multi-vendor integrations).

// If this incident is being created in your instance then likely you are the owner
// Bond owner is set to false, as it is referring to the other system
bond.setValue('owner', false);

// We also update custom fields on the target record itself (i.e. Incident) so things like ACL rules can be used to restrict access to the Incident fields.
target.u_ebond_owner = true;
target.u_ebond_source = transaction.integration;

Fields and Field Maps

Much of the scripting (including mapping of fields on the source/target record & other Transaction specific data e.g. Name, Time stamp, Source reference, Target reference) can now be done using Fields & Field Maps (see those pages for further details).

The configurations defined by Fields and Field Maps are compiled into executable code and stored in the Message Scripts (between demarkation comments). Existing Message Scripts simply have their code updated. Code outside of the demarkation comments in the Message Scripts is retained.

A Connection is a property of an Integration. You must have a Connection set up to allow messages to be sent and received for your Integration.

The Connection stores all the authentication details of the Integration specific to a single environment. You can setup many Connections so you can easily switch between environments as necessary.

Activation

The Integration is controlled by the Connections. Making a Connection active will make it’s Integration active (and vice versa).

Connection Test

‌You can perform a basic connection test which will make a simple request to the endpoint to check if the user is authorized.‌

A failure is shown when the status is:‌

• 400 Bad Request

• 401 Unauthorized

• 403 Forbidden

• 404 Not Found

• 405 Method Not Allowed

‌Unifi will assume all other status codes mean the user is authorized even if the request was bad.

To perform the test:‌

• In Unifi Integration Designer, navigate to and open the Connection.

• Click 'Connection Test'.

• On the Connection Test Modal, click 'Test'.

• After viewing the results, click 'Done' to close the modal.

Environment

You can assign a Connection to a specific environment to make it easy to see what you are connecting to.

Available environment choices are:

• Production

• Pre-Production

• Test

• Development

• Sandbox

Inbound Connectivity

The Connection is the link between the ServiceNow endpoint that is receiving messages and the Integration that is used to process them. If you want to receive messages from a remote system, you must specify an Inbound user which the remote system will use to authenticate with.

Inbound Endpoints

The Inbound endpoints for your Integration are clearly displayed in a widget at the top of the Connections page. Clicking the link to the right of the endpoint url will open the Scripted REST Resource (in native ServiceNow) in a new window.

Outbound Connectivity

In order for a Connection to send messages to remote systems, you must provide an Endpoint URL and the method of authentication.

Authentication

Connections support several types of authentication: Basic, Mutual and OAuth.

Basic

Basic authentication is achieved by providing a username and password.

Mutual

Mutual Authentication (MAuth) using SSL certificates is available by selecting the Mutual auth checkbox and configuring certificates on a ServiceNow Protocol Profile record.

OAuth 2.0

You can connect using OAuth by configuring a ServiceNow OAuth Entity Profile.

MID Server

If the system you are connecting to is behind a firewall (such as an internal service) you can specify a MID Server for the integration to communicate over.

Fields

The following table is a summary of the fields to be configured for the Connection record:

Connection Variables

A Connection Variable is simply a key-value pair. If you have multiple connection environments (e.g. Dev, Test, Prod) - each containing different data, or information that needs to be passed between environments but changes - then use Connection Variables to provide a consistent entry point in the code.

Example Use Cases

They can be used to define static data as variables that can change between endpoints. The following example is from the Outbound Settings for a Message:

They could also be used instead of scripting data values directly into the code of Poll Processor scripts. See the following Guides for examples:

Import Logging

Inbound Datasets use ServiceNow Import Sets giving you the ability to view dataset imports as you would any other data import.

For detailed Activity Logs, navigate to the Transform page on a Dataset and enable the Import logging option.

Dataset Cleanup

Dataset Requests are a record of when all Dataset imports and exports occurred. They are linked directly to Transactions that belong to a Bond which is exclusive to the Dataset. The records are automatically deleted when the corresponding Transaction is deleted.

The number of Transactions to keep during the daily cleanup can be managed using the Cleanup option which can be configured on each Dataset. This value specifies the number of transactions that should remain following the cleanup process. The default retention is 10 records.

Any Dataset Requests which are somehow orphaned, meaning they have no Dataset or no Transaction specified, will be removed based on the Orphan Record Cleanup Age x_snd_eb.orphan_record.cleanup.age system property. The default orphan cleanup age is 7 days.

Export Tuning

When a Dataset export runs, the system will automatically export the records in small batches depending on its configuration.

Batch size options are:

• Max size: set the maximum file size to export. There is an internal maximum size of 5MB.

• Max rows: limit batches to a specific number of records.

• Max time: prevent long running exports by setting a maximum export time.

The final export size is determined by whichever limit is reached first. If more records are available to be processed, additional Dataset Requests will be created until all records have been exported.

Create a Dataset Field Map

New Field Maps can be configured for handling specific types of data in new ways. We recommend using the "Dataset" prefix when creating your new field map so it is easy to identify.

Dataset specific Field Maps are slightly different to eBonding integration field maps. The main difference is that the Stage to Target script is executed as a ServiceNow Transform Map script. This means that certain objects are not available, including transaction, bond, and request.

These Field Maps should reference the Import Set Row fields using the standard $stage object. Field name conversion from the Import Set Row source object to the Field Map $stage object is handled automatically, i.e. "u_" prefixes are removed.

The target object which represents the record being created or updated can be used normally.

The log object is updated to reference ws_console meaning all logs will be written to the Activity Log generated for each imported record. If required, logs can continue to be written to the Import Set Row using the source object.

Disable Dataset Import

By default, Datasets are automatically configured for both import and export. If you require a one-way data export without import, you can prevent inbound messages from being processed.

1. From Integration Designer, navigate to the Dataset in your integration.

2. Find the Send message and click the clickthrough button to open it.

3. Change the Direction from Bidirectional to Outbound.

4. Click Save.

Multiple Tables

Datasets are designed to work with one table at a time. If you need to import/export more than one table, setup a Dataset for each table.

Sending Data from a Third Party

Externally generated files can be processed by a Dataset. Files should match the file type the Dataset expects, e.g. CSV or JSON, and be streamed to the Dataset import endpoint. The maximum file size will depend on your instance configuration.

POST https://<instance>.service-now.com/api/x_snd_eb/unifi/<api_name>

Send a file to be processed by a Dataset.

Example: https://acme.service-now.com/api/x_snd_eb/unifi/incident/dataset?file_name=cmdb_ci.csv&reference=Sync%20Server

Query Parameters

Headers

Using IRE (Identification and Reconciliation Engine)

It is possible to add support for ServiceNow IRE to your Dataset imports. This will push data through the reconciliation engine rather than directly updating the target records from the Import Set.

Follow these steps to configure your Dataset for use with IRE.

1. Create a new Data Source.

2. Create a Field Map for setting up the import for IRE.

3. Create a Field Map to give the data to IRE.

4. Add header and footer fields to the Dataset.

5. Modify Field Maps being used by the Dataset.

Introduction

Attachments in ServiceNow are normally attached to the records they belong to, making it easy to identify and share those attachments over an integration. Embedded attachments require a bit more effort to integrate since they can belong to other records, or in some cases, no record at all. They are typically found inside journal fields.

Use Case

The use case being looked at in this example is embedding attachments in the Additional Comments field using HTML inside [code] tags so lengthy comments such as operational checks can be shared with third parties directly from the instance.

To recreate this scenario:

1. Open a record with a journal field, i.e. an Incident.

2. From the More options selector, choose Email. The Compose Email window will open.

3. Copy/paste or drag an image into the email composer. (In Windows, you can use Windows Key + Shift + S to take a screenshot and then Ctrl + V to paste it into the formatter).

4. Click the Source code button to view the HTML source code.

5. Select all the source code (Ctrl + A) and copy it (Ctrl + C).

6. Back in your Incident, go to a journal field, e.g. Additional Comments and paste in the HTML.

7. Wrap the comment in [code]...[/code] tags to tell ServiceNow to treat this comment as code.

8. If the record and field is integrated, the field will be shared over the integration, but the other system will not have the attachment so the image will not show.

Automatic Embedding

We can allow the integration to share embedded attachments with some modification to the outbound mapping scripts.

In this example, we are sharing a journal field so will modify the Field Map for Journal fields. We want the attachment data to be automatically embedded as base64 instead of sending the sys_attachment reference.

1. Open the Field Map

Open Integration Designer and navigate to the Field Map you want to modify. Find the Source to Stage mapping script in theOutbound panel.

2. Embed Image Attachments Function

Copy the function below into your Source to Stage mapping script. This function accepts some text and updates all<img> tags that reference the sys_attachment table.

3. Modify Journal Entries

The final step is to update the same Field Map to use the new embedImageAttachments() function that you've just added.

Add the code to the bottom of the same Source to Stage mapping script and modify as required.

This code is designed for the out of box Journal field map.

4. Build

Build your integration to push the Field Map changes to all the messages. You can now test.

Known Limitations

File size

Embedding attachments in this way will mean the maximum string length imposed by ServiceNow of 5mb will be easy to reach. Since base64 is a 4/3 compression, you have a realistic limit of around 3mb of images which can be transferred this way in any single request.

Instance security

This approach is not considered secure since it is possible for malicious Javascript to be rendered in the [code] tags.

The glide.ui.security.allow_codetag system property is responsible for rendering [code] tags. This is typically disabled as part of Instance Security Hardening.

If the property is disabled then [code] tags will not be rendered. Both systems must have this property enabled for this solution to work.

Alternative Approaches

Some alternative approaches to embedding attachments in this way are:

1. Create a document containing the images and upload it as an attachment on the record. If you are streaming attachments, you will be able to share a file up to 50mb in size.

2. Upload the images separately as attachments and reference them in your comments. If you are streaming attachments, each image could be up to 50mb in size.

Unifi can be patched between releases by using a special Script Include called hotfix. If you find a bug in Unifi we may issue an update to hotfix so you can get the features you need without having to upgrade.

Upgrading

When upgrading Unifi, you can revert to the latest version of hotfix included in the upgrade. We reset hotfix with each release when the fixes become part of the main application.

Patching

We occasionally release a hotfix when minor issues are found. 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.

/**
 * Executes a child function corresponding to the object's type property.
 * The object is passed to the child function so methods and properties can be overridden.
 *
 * @param  {Object} obj The full class object to be patched.
 */
function hotfix(obj) {
  var type = typeof obj === 'function' ? obj.prototype.type : obj.type;
  if (type && typeof hotfix[type] === 'function') {
    hotfix[type](obj);
  }
}

hotfix.version = '4.0.2.3';

hotfix.Dataset = function (Dataset) {
  // Fix import logging
  Dataset.beginTransform = function beginTransform(dataset_id, import_set) {
    var dataset = Dataset.getInstance(dataset_id);
    var request = DatasetRequest.findActive(dataset);
    if (request.isValidRecord()) {
      ActivityLog.setDocument(request.getRecord());
      request.setProcessing();
      request.setStatus('Transform in progress...');
      request.setImportSet(import_set.sys_id);
      request.commit();
    } else {
      ActivityLog.setDocument(dataset);
    }
    if (!dataset.getElement('import_logging')) {
      ws_console.info('Logging is disabled. Please enable import logging on the Dataset to see Activity Logs for import set rows.');
      ws_console.pause();
    }
  };
};

hotfix.AttachmentHandler = function (AttachmentHandler) {
  // Allow multi-table attachment handling
  AttachmentHandler.createBondAttachment = function createBondAttachment(attachment) {
    var send = false,
        bond_gr,
        gr;

    function getBonds(sys_id, table) {
      var gr = new GlideRecord('x_snd_eb_bond');
      gr.addQuery('document', '=', sys_id);
      gr.addQuery('table', '=', table);
      gr.addQuery('state', '!=', 'Closed');
      gr.query();
      return gr;
    }

    function getConfig(bond) {
      return new Process(bond.integration.process).getConfig();
    }

    bond_gr = getBonds(attachment.table_sys_id, attachment.table_name);

    while (bond_gr.next()) {
      if (AttachmentHandler.addToBond([attachment], new Bond(getConfig(bond_gr), bond_gr))) {
        send = true;
      }
    }

    if (send) {
      gr = new GlideRecord(attachment.table_name);
      gr.get(attachment.table_sys_id);
      if (gr.isValidRecord()) {
        Message.processOutbound(gr, {
          attachment_added: true, // only match messages with "Attachment added" condition
          parent_tables: true // search table hierarchy
        });
      } else {
        gs.error(t('Attachment %0 does not have a valid record. Cannot process outbound.', attachment));
      }
    }
  };
};

hotfix.IntegrationTest = function (IntegrationTest) {
  // Fix integration delete from Designer portal
  IntegrationTest.getDeleteStack = function getDeleteStack(config, sys_id) {
    var stack = new Stack('x_snd_eb_integration_test', 'integration_test');

    if (sys_id) {
      stack.filter('sys_id=' + sys_id); // delete this record
    } else {
      stack.filter(function (scope, data) { // deleting parent record
        if (scope.integration) {
          return 'integration=' + scope.integration;
        }
        return 'sys_id=-1';
      });
    }

    stack.each(function (integration_test, scope, data) {
      scope.integration_test = integration_test.sys_id + '';
    });
    stack.afterEach(function (integration_test, scope, data) {
      integration_test.deleteRecord();
    });

    stack.addChild(IntegrationTestScenario.getDeleteStack(config));

    return stack;
  };
};

hotfix.Bond = function (Bond) {
  // UN-1266 Insert the bond when it is created to prevent double bonds from sync updates that 
  // happen before the insert has finished. This only applies to inbound transactions.
  Bond.prototype.create = function create(integration, internal_ref, external_ref, ref_method) {
    var ref;

    if (!external_ref && !internal_ref) {
      throw this.customError('Cannot create bond. No reference given.');
    }

    if (this.locateReference(integration, internal_ref, external_ref, ref_method)) {
      ref = this._getRefText(internal_ref, external_ref);
      throw this.customError('Bond already exists for document. ' + ref + '.');
    }

    this.newRecord();
    this.setValue('integration', integration.getValue('sys_id'));
    this.setValue('internal_reference', internal_ref);
    this.setValue('external_reference', external_ref);
    this.setValue('state', 'Pending');
    this.setValue('status', 'OK');
    this.isNew(true);
    Model.prototype.commit.apply(this);
  };
};

hotfix.Integration = function (Integration) {
  // Fix UN-1298 error messages defined on the Integration are not retrieved properly
  Integration.prototype.getSyncErrorMessage = function getSyncErrorMessage() {
    return Message.getMessageById(this.getConfig(), this.getValue('sync_error_message'));
  };
  Integration.prototype.getAsyncErrorMessage = function getAsyncErrorMessage() {
    return Message.getMessageById(this.getConfig(), this.getValue('async_error_message'));
  };
};

hotfix.DataSetProcessor = function (DataSetProcessor) {
  // Fix UN-1299 prevent DataSetProcessor events from being queued when there is no additional data to process
  DataSetProcessor.prototype._executeQueue = function _executeQueue(callback) {
    var rows = this._execute(callback);
    if (this.event) {
      if (rows == this.limit && this.gr && this.gr.hasNext()) {
        ws_console.info('Event ' + this.event.name + ' processed the maximum ' + this.limit + ' records. Auto queueing next event.');
        this.queueNext(this.event, this.current);
      } else {
        ws_console.info('Event ' + this.event.name + ' processed less than the maximum ' + this.limit + ' records. Processing complete.');
      }
    } else {
      ws_console.warn('Cannot auto queue additional processing; event not found.');
    }
    return rows;
  };
};

Unifi Integration Designer is the primary and recommended interface used for creating and managing integrations in Unifi.

Designer can be accessed by clicking Unifi Integration Designer ➚ from the navigator menu.

Process is at the top of the configuration chain in Unifi. It is a mechanism which provides functionality not provided OOTB in ServiceNow. The purpose of a process is to keep like integrations in one place (e.g. Incident process integrations, or Change process integrations).

One Process may contain multiple Integrations which can each be configured separately and uniquely (more on that on the Integrations page).

Automated Creation of REST Service

Process Fields

The fields to be configured in the Process record are as follows:

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.

Messages are central to the functionality of Unifi. A Message brings together the disparate parts necessary for the configuration required in order to send, receive and process a request.

Automated Creation of Trigger Business Rule

For step-by-step instructions on how to configure Messages (and other Integration components) see the Integration Guides section of the documentation.

Message Fields

Details

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

Fields

From here you can configure the relevant Field records for the Message. A list of the available and active Fields is displayed*. For more information about Field records click here.

Response

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

Bond

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

Outbound Fields

Trigger

The Outbound Trigger fields to be configured for the Message record are as follows:

Template

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

CDATA

It is possible to use CDATA within an XML message, but because of the way ServiceNow handles XML it can be a little bit tricky. When ServiceNow see’s the CDATA tag, it actually processes it and the tag ends up being removed in the final. We need to use a little trick allow us to actually get the CDATA in the final result.

<?xml version="1.0" encoding="utf-8" ?>
<j:jelly trim="false" xmlns:j="jelly:core" xmlns:g="glide" xmlns:j2="null" xmlns:g2="null">
  <g:evaluate jelly="true">
    var stage = jelly.jvar_stage, transaction = jelly.jvar_transaction;

    // initiate the attachment sender
    var sender = new x_snd_eb.AttachmentSender(
      jelly.jvar_transaction,
      jelly.jvar_bond
    );

    // we only handle one attachment - use in while loop if there are many
    sender.next();

    // we need CDATA to not be processed by XML
    // It's added in the XML below to wrap the embedded document
    var cdata = [
      '&lt;![' + 'CDATA[&lt;?xml version="1.0"?&gt;',
      ']]&gt;'
    ];
  </g:evaluate>
  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="http://www.wsdl.com">
    <soapenv:Header/>
    <soapenv:Body>
      <wsdl:Request>
        <wsdl:RequestElement>
          <wsdl:server>dev.server.com</wsdl:server>
          <wsdl:formName>Attachment</wsdl:formName>
          <wsdl:id>ABC123</wsdl:id>
          <wsdl:xmlString>${cdata[0]}
            <Elements>
              <Element>
                <Name>Description</Name>
                <Value>Attachment Received from customer</Value>
              </Element>
              <Element>
                <Name>AttachmentName</Name>
                <Value>${HTML:sender.attachment_name}</Value>
              </Element>
              <Element>
                <Name>AttachmentData</Name>
                <Value><x-attachment-data sys_id="${sender.attachment_id}" /></Value>
              </Element>
            </Elements>${cdata[1]}</wsdl:xmlString>
          </wsdl:RequestElement>
        </wsdl:Request>
    </soapenv:Body>
  </soapenv:Envelope>
</j:jelly>

Attachments

The Outbound Attachments fields to be configured for the Message record are as follows:

Settings

The Outbound Settings fields to be configured for the Message record are as follows:

Inbound Fields

Settings

The Inbound Settings fields to be configured for the Message record are as follows:

payload = (function extractAttachments(payload, request) {
	
	// Convert from string to object
	var obj = JSON.parse(payload);
	
	// Extract the attachment here...
	
	// Update the payload
	payload = {
		attachment: ''
	};
	
	// Encode payload back to string
	return JSON.stringify(payload);
})(payload, request);

Advanced

Script Editor

From here you can view each of the Message Scripts for the Message (Source to Stage, Stage to Request, Payload to Stage, Stage to Target). The auto-generated code displayed is configured using Fields & Field Maps. For more information on Message Scripts click here.

Response Actions

From here you can view a list of the relevant Response Actions on the Integration. You can also configure a New Response Action from the list. For more information about Response Actions click here.

Event Actions

From here you can view a list of the relevant Event Actions on the Integration. You can also configure a New Event Action from the list. For more information about Event Actions click here.

With the introduction of Datasets, it is now possible for large amounts of user, hardware, network and other supporting data to be sent to and received from remote systems. While this has been possible for some time using Pollers, they are not specific to handling large amounts of data in the way that Datasets are.

Datasets provide easy configuration that is supported by platform intelligence and automation, making it is incredibly easy to setup a robust and efficient mechanism for handling large sets of data.

Integration Build

Each Dataset will create the following configuration:

• The Send message is used for sending the data in an attachment to the other system. The name is automatically generating using the prefix "Send" and the name of the table.

• The Process message is used for processing the record data both inbound and outbound. The name is automatically generating using the prefix "Process" and the name of the table.

• The Import set table is used for staging inbound data. The name is automatically generated using the prefix "dataset" with the sys_id of the dataset.

• The Scheduled import record is automatically created for processing import data. It is executed when an inbound Dataset Request has created the import set rows and is ready to be processed.

• The Transform map and associated coalesce fields are used for processing the import set.

Outbound Data

Data is automatically collected, transformed, packaged and sent to another system on a schedule. Each export creates one or more Dataset Requests depending on the number of records and a series of limits configurable on the Dataset.

Unifi automatically creates a Process message which can be used with outbound Fields and Field maps (via the Source to Stage and Stage to Request Message Scripts) to extract the data from the specified records.

The extracted data is written to an attachment which is then sent using the Send message which is also automatically created by Unifi.

Inbound Data

When an inbound Send message (as specificed on the Dataset) with a data attachment is received, the attachment will be processed with each record being inserted into an import set table directly related to the Dataset. The import set table is automatically created and maintained during the Integration Build process.

Unifi uses ServiceNow Import Sets since they offer a well understood mechanism for importing data with performance benefits. The mapping is automatically managed by Unifi and handled through a transform script which uses inbound Fields and Field maps (via the Stage to Target Message Script) to transform the data and write it to the target records.

Fields

The process message related to the Dataset is used for inbound and outbound mapping and transformation.

Simply create the fields that you want to export/import and configure them in the same way you would for any other Unifi message. Note: the field maps will likely need to be specific to the dataset fields.

Use the Coalesce field (specific to Dataset messages) to indicate which field should be used for identifying existing records to update during inbound processing.

By default, a successful request is determined by the response HTTP Code being in the info (1xx) or success (2xx) ranges and anything outside of these is treated as a request failure.

Sometimes, an API will return a response that needs to be treated differently to how it would normally be handled. For example, an API might return a 400 error to indicate a part of the request contains invalid data. We can use a response action to catch that error and do something about it.

Execution Flow

The Response Action executes the following steps:

1. Run retry logic. Retry logic takes precedence and will cancel the Response Action if possible. If no more retries can be made (or no retry is required), the Response Action is executed.

2. If no retry error has occurred, the request and transaction states are updated according to the Response Action.

3. Notify the user by adding an integration note. A note will only be added according to the notification script on the Integration.

4. If a script is specified, execute the script.

Response Action Fields

Details

The Details fields that can be configured for the Response Action record are as follows:

Settings

The Settings fields that can be configured for the Response Action record are as follows:

Active

The Active field can be configured for the Response Action record as follows:

Unifi has some 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.

With version 4.0, the Update Set also includes a queue processing job Unifi dataset events process which is necessary for Datasets to be processed.

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

1. Download Unifi Global Utility.

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

Dependent Features

Execute Now

Method: snd_eb_util.executeNow(job)

This is necessary for Datasets to execute their associated ServiceNow Import Job.

Get SOAP Response Element

Method: snd_eb_util.getSoapResponseElement(xml)

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.

Moving Attachments

Method: snd_eb_util.moveAttachments(attachment_ids, record)

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.

Run As User

Method: snd_eb_util.runAsUser(user, fn)

On occasion, Unifi needs to run some code as the given user. This is necessary things like replaying requests.

Jelly Processing

Method: snd_eb_util.runJelly(jelly_code, vars)

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.

Script Validation

Method: snd_eb_util.validateScript(script, scope)

Used by the Unifi Integration Diagnostic to check scripts for errors.

Binary Attachment Handling

Method: snd_eb_util.writeAttachment(record, filename, content_type, data)

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.

Web Service Creation

Method: snd_eb_util.web_service.*

The web service methods included in the global utility allow Unifi to automatically create and update REST Methods used by Unifi integrations.

Trigger Rule Creation

Method: snd_eb_util.trigger_rule.*

The trigger methods included in the global utility allow Unifi to automatically create a Trigger Business Rule on a table if one doesn't already exist.

Dataset Create Data Source

Method: snd_eb_util.datasetCreateDataSource(dataset, attachment)

Create a data source for datasets to use when importing data.

Dataset Delete Scheduled Import

Method: snd_eb_util.datasetDeleteScheduledImport(scheduled_import_id)

Delete a scheduled import that belongs to and was created by a Dataset. Used when deleting a Dataset.

Dataset Delete Transform Map

Method: snd_eb_util.datasetDeleteTransformMap(transform_map_id)

Delete a transform map that belongs to and was created by a Dataset. Used when deleting a Dataset.

Dataset Ensure Transform Map

Method: snd_eb_util.datasetEnsureTransformMap(dataset)

Update a transform map for a Dataset to use when importing data. Used when building a Dataset.

Dataset Update Transform Map Fields

Method: snd_eb_util.datasetUpdateTransformMapFields(dataset)

Update the coalesce fields for a transform map. Used when building a Dataset.

Introduction

Adding these elements to the Unifi configuration records brings a wealth of advantages. In the past, each Message Script has been maintained individually and manually. However, the introduction of Fields and Field Maps allows Message Scripts to be broken down into smaller, reusable components. Having these Field records also means we can easily view and manage the use of fields on Messages and Integrations.

Definition

A Field record defines the processing of a discrete component of a Message. Although the Field record is distinct from and separate to the field element of a form, it often represents the handling of an individual field on the source/target record (e.g. Short description). Not only that, a Field record is used to define the objects that will carry other Transaction specific data (e.g. Name, Time stamp, Source reference, Target reference).

A Field record identifies the field of a source/target record (optional - as stated above), the element used to stage the information and the property of the payload exchanged between systems. It can define the direction in which it is applied, any default values to use in each direction and whether it is mandatory. It can exist at the Integration or Message level (more on that in the Inheritance section). The behaviour, or ‘type’ of a Field is defined by the Field Map to which it is linked.

Inheritance

Field inheritance allows a Field record to be created at the Integration level rather than at an individual Message level. Individual, Message level Field records can then be configured to inherit their behaviour from the Integration level Field record.

For example, if a field is used by ten Messages, then we would define ten Field records and link them to the Messages (a separate Field record must be created for each of the Messages where the field is used). If we configure those Field records to inherit their behaviour from the Integration level Field record, then modifications made to the Integration level would immediately be available to the Message level Field records.

A Field record is shown to be an Integration level record when it is not linked to a specific Message i.e. the ‘Message’ field is left blank .

A Message level Field record can inherit from its Integration level counterpart by simply checking the ‘Inherit’ field.

The image below is an example of an ‘incident.short_description’ Field record:

We can see an example from this list view below that the incident.short_description Field record has been defined for seven different Messages on this Integration (plus the Integration level record):

Configuration

Best Practice

When configuring a Field record, it is best practice to only link it with a Field Map that belongs to the same Integration as the Field (for details, see the Field Maps page).

As an aid to help identify any issues, in the auto-generated Documentation a warning triangle will appear next to the Field Map and a message will be shown in the Document if the Field Map doesn't belong to the Integration.

Example

In this example, we will copy the incident.impact Field from one Integration to another.

To copy the Field record, navigate to the Fields page. Click on the ellipsis to the right of the incident.impact Field & then click Copy.

On the Copy Field modal, note the value of the Integration and Field Map.

Clear the value of the Integration and the Field Map is automatically cleared.

Select the Integration you wish to copy the Field record to. You are then able to select the equivalent Field Map for that Integration (which you have already created, per Field Maps Best Practice).