Welcome

There are many useful features in Unifi designed to aid administrators and developers with debugging and error handling - making it an easier, more efficient process.

Scope

This document will guide you through features & functionality built-in to Unifi which are designed to support developers and administrators whilst debugging and error handling. It will demonstrate how straightforward and efficient those tasks can be.

We will focus on the following features.

• Retry

• Replay

• Ignore

• Repair

• Pause and Resume

Approach

We will talk through each of the features mentioned above, giving example use cases and talking through how to use them and the benefits they bring.

Retry Logic

The retry functionality is like a first line of defence when it comes to error handling. It builds in time to allow the system to deal with potential issues in the first instance and saves the analyst or administrator having to step in at the first sign of any problems. This can be useful in scenarios where, perhaps the external system is temporarily preoccupied with other tasks and is unable to respond in sufficient time.

Rather than fail or error a Transaction at the first unsuccessful attempt, Unifi will automatically retry and process it again. The number of times it attempts to do so and how long it waits (both for a response and before attempting to retry again) are configurable parameters.

Although the retry logic itself is applied at the HTTP Request level, the settings to configure it can be found on the Integration. This means that they can be configured uniquely and specifically for each Integration. Unifi will automatically retry errored Requests according to those settings.

The fields that can be configured are as follows:

Timeout Fields

In Unifi Integration Designer, navigate to and open < The Integration you wish to configure >.

Click the ‘Integration’ icon (this will open the Details page).

Navigate to Error Handling > Timeouts.

The Timeout fields that can be configured for the Integration are as follows:

Retry Fields

Navigate to Error Handling > Retry.

The Retry fields that can be configured for the Integration are as follows:

User Intervention

Retry is automated in Unifi. Should the number of retries be exhausted, the Transaction will be errored and any subsequent Transactions are queued. This prevents Transactions from being sent out of sync and updates being made to bonded records in the wrong sequence.

There are a number of UI Actions available to help and subsequent sections will look at each of those in turn.

In the next section, we'll look at the first of those UI Actions, the Replay feature.

Ignore is a UI Action on the Transaction record which allows administrators to manually ignore Transactions. Clicking it prevents queued Transactions being processed.

You can ignore a Transaction either from the record itself, or the list view:

Use Case

You would normally use Ignore for Transactions that are Queued, Timed Out or in an Error state. You would perhaps ignore a Transaction that cannot be processed because it is broken and you know it won't work.

Another example might be that you choose to ignore an update because the other system has processed it but not responded correctly (putting the Transaction in Error), so rather than replaying and duplicating the update, it would be better to ignore it. You may even have a number of Transactions that you want to ignore (perhaps in the case of system unavailable).

Queue Processing

We've already said that setting Transactions to Ignored stops the queue from processing. Unifi doesn't automatically continue processing subsequent Transactions - they remain Queued. This is because it is more beneficial to have a focused environment when debugging - to not have Transactions automatically firing off (potentially blurring issues).

Attachments

In the case of an Outbound Transaction with an attachment being ignored, the associated Bonded Attachment record will be set to Rejected. This means that it will be available to be sent with the next Transaction.

Repair is a UI Action on the Integration. Clicking it will cause a bulk replay of all its broken Transactions (those in an Error or Timed Out state).

You can repair an Integration either from Unifi Integration Designer, or native ServiceNow:

Use Case

As a further aid, there is also a 'View broken transactions' Related Link on the Integration record which will take you to a list of all Transactions in an Error or Timed Out state.

Replay, Repair and Ignored

When a Transaction is replayed (whether individually, or in bulk), the original record is set to 'Ignored' and a new Transaction (with a decimal suffix) is generated (taking the same Stage data & reprocessing it) and sent.

Pause

Pause is a UI Action on the Integration. Clicking it will pause the Integration, causing all subsequently created Transactions to queue in the order they were created.

Pause is different to deactivating the Connection. Deactivating the Connection would stop all processing completely, whereas Pause simply prevents the Messages from being sent until the Integration is resumed.

To pause an Integration, click the the Pause UI Action in the header of the Integration record in native ServiceNow.

An Info Message will be displayed, stating the Integration is paused.

Resume

Once an Integration has been paused, the Resume UI Action is available on the Integration. Clicking it will restart the queue, processing the queued Transactions in order.

To resume an Integration, click the the Resume UI Action in the header of the Integration record in native ServiceNow.

A modal is displayed asking to confirm Resume Integration. Click OK.

The Resume Integration Worker modal is displayed, showing progress.

Use Case

It is not envisaged to use this feature when dealing with errors (use 'Ignore' in that case). The primary use case for Pause and Resume would be for occasions where there are planned outages. For example, the other system is undergoing planned maintenance.

Unlike retries (which are automated), replays are a user initiated action. You can replay both Requests and Transactions directly from their respective records by simply clicking the UI Action.

Replay Request

You can replay a single HTTP Request (whether inbound or outbound). Having the ability to focus in on and replay the specific Request which has errored allows you to identify and correct errors more accurately, quickly and easily.

To replay a Request, click the Replay Request UI Action in the header of the Request record.

Replay Transaction

A Transaction comprises a Request/Receipt pair of HTTP Requests and represents an instance of a Message being sent/received. You can replay the whole Transaction again (not just a single Request). Replaying a Transaction works differently to replaying a Request and both would be used at different stages of the debugging process - though they are both equally as simple to perform.

You can replay a Transaction either from the record itself, or the list view:

Benefits

Firstly, having the ability to replay errored Requests/Transactions can save a significant amount of time and effort when debugging and error handling. For example, typically after spotting an error, you would have to step into the config & make a change, step out to the bonded record and send data again, step into the logs to check what happened and continue around until rectified. Compare that to being on the errored HTTP Request, making a change to the data in that request, replaying it and getting immediate feedback (seeing the response codes) all from within the same record.

Not only that, Unifi automatically replays as the originating user*. You don't have to impersonate to replay. Not only does this also save time & effort, but you can debug with confidence - being able to replay as the original sender (not the user replaying), allowing functionality that relies on the identity of the user to run correctly.

Differences

When you replay a Request, you replay that specific instance of that data (as-is) at that time. When you replay a Transaction, Unifi takes the Stage data and reprocesses it before sending - building the payload/HTTP Request again.

Use Case

You would normally replay a Request during development & testing, when debugging (making changes during investigation).

You would normally replay a Transaction once you have completed your investigation and made configuration changes, as reprocessing the data would take those changes into account when building a new payload/HTTP Request. Operationally, you are perhaps more likely to replay a Transaction in cases where, for example, the other system was unavailable and the attachment was not sent - so you want to reprocess and attempt to resend the attachment.

Easy Identification

Each new attempt to replay either a Transaction or a Request will be incremented with a decimal suffix (.1, .2 etc.)*. This means you can easily identify which replay relates to which record and in which order they were replayed. For example, TX00123 will replay as TX00123.1 and then TX00123.2 etc.