Unifi - Version 2.0

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.

Upgrade Notice

Please note that this is a major release which may not be entirely compatible with your existing integrations. While we do everything to make sure you won’t have to fix your integrations when upgrading, we strongly encourage all our customers to perform full end-to-end tests of their integrations before upgrading Unifi in Production.

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.

Unifi Dashboard

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.

Unifi Activity Log

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.