Transactions

A Transaction is an instance of a Message occurence. It contains and tracks the processing of a Message using Stages and HTTP Requests.

A Transaction is a vehicle used in the flow of Messages on a bonded ticket. It is essentially a container for a Request/Receipt pair. The Transaction record contains the necessary fields to facilitate and track both the movement and the processing of the pair of Messages.

Functions

A Transaction’s primary functions are:

  • To contain the Request/Receipt pair of Messages.

  • Handling the queueing of Requests and Receipts.

  • Tracking the state of the Transaction from two perspectives:

    • Transaction state

      • The condition of the Transaction from a movement (transactional) perspective (i.e. the condition of the transport of the data).

    • Process state

      • The condition of the Transaction from a process perspective (i.e. its relation to the business logic that’s in place).

    • Example:

      • System A sends a Request to system B to update the value of the urgency field on a ticket without having ‘ownership’ of that ticket. The Request is properly formed and authenticated and is received in system B.

        System B sends a response acknowledging the Request and then subsequently processes the Request asynchronously. If, on processing the Request from system A, system B discovers that system A did not have the authority to change the value of the urgency field, they would send a Receipt Message stating the error. That Receipt is also properly formed and authenticated and is received in system A without any problems.

        The Transaction state in this case would be set to ‘Complete’ as both the Request and the Receipt were transported successfully. However, the Process state would be set to ‘Rejected’ as system A did not have the authority to update the value of the urgency field.

State Control

One of the many defining features of Unifi is its ability to track the state of the Transaction from both a transport (What’s happening with the movement of the message?) and a process (How does the content of the message align with business logic?) perspective.

Having the combination of these two states is extremely useful and gives a far more precise understanding of the condition of the Transaction and opens up more options. This means, for example, that an analyst can see and has the opportunity to fix issues based on a process error without the need for technical support (Unifi won’t break an Integration for a process error). For transactional errors Unifi can throw events which can be correlated to send notifications, or trigger the system’s Incident process as appropriate.

Transaction State

LabelSequenceDescription

Sending

0

An outbound Message is being sent to the integrated system.

Received

1

An inbound Message has been received from the integrated system (but not processed).

Awaiting Receipt

2

An outbound Message has been sent to the integrated system and we are awaiting an asynchronous Receipt.

Sending Receipt

3

We are sending an asynchronous receipt in response to receiving and processing an inbound Message from the integrated system.

Received Receipt

4

An inbound asynchronous Receipt has been received from the integrated system.

Complete

5

The Message exchange was completed.

Queued

6

The Message exchange has been temporarily delayed because of incomplete transactions.

Timed Out*

7

An outbound Message has been sent to the integrated system, but we have not received the asynchronous Receipt in the expected timeframe.

Error

8

There was a transactional error with the Message exchange (e.g. invalid message format, unknown endpoint, code error etc.).

Ignored**

9

Transactions can be ignored manually to allow the integration to proceed.

*Timed Out

This is configured on the integration by the value in the 'Async timeout' field.

**Ignored

This can be used when a Transaction does not complete (i.e. when it is in an ‘Error’ or ‘Timed Out’ state), or at any time when a Transaction is in progress or ‘Queued’ (e.g. when a system error occurs outside our control).

Process State

LabelSequenceDescription

Pending

0

The Message is being processed and is awaiting a decision as to whether it falls within or outside of the scope of the business logic.

Accepted

1

The Message has been processed and accepted as within the scope of the business logic.

Rejected

2

The Message has been processed and rejected as outside the scope of the business logic.

Fields

The following table gives a description of the fields that are visible on the Transaction record:

FieldTypeDescription

Message ID*

String

The unique internal message identifier.

External message ID*

String

The external system’s unique message identifier.

Table

Table name

The target table this record applies to.

Document

Reference

The integrated ServiceNow ticket.

Integration

Reference

The integration this record belongs to.

Bond

Reference

The bond this record belongs to.

Message

Reference

The message used to process this record.

Direction**

Choice

The direction this record is travelling in.

Transaction state

Choice

The state of communication for this transaction.

Process state

Choice

The business logic process state.

Created

Glide date time

The date and time the transaction was created.

Receipt due by

Glide date time

The date a receipt must be received before this transaction times out. Only applies to asynchronous transactions.

Error

String

The internal communication error.

Process error***

String

The business logic error in processing this transaction.

*External/Message ID

These are used in Unifi to match the related Requests and Receipts (i.e. the Message ID of one system will be used as the External message ID of the other system and vice versa).

**Direction

The direction of the initiating (or first) Message in the Request/Receipt pair will determine the direction of the Transaction.

***Process error

The value in this field can be rolled up to the bonded ticket, giving the analyst insight and the opportunity to resolve process errors.

Debugging

You can view the transaction logs from the Transaction record by navigating to the 'Unifi Activity Logs' related list, or from the Unifi Operations Manager portal. This hugely significant feature offers considerably more detail than is available with the OOTB ServiceNow system logs and puts that information right where you need it - saving an inordinate amount of time hunting through the [sys_log] table.

Activity Logs will be populated if logging is enabled when debugging. They are particularly helpful to ShareLogic when debugging Unifi itself.

Navigate to the 'Unifi Activity Logs' related list:

Common Activity Logs

Transaction process next queued

Once the initial Transaction has completed, Unifi checks if there are any other transactions queued and processes them.

Request sending

Here Unifi is processing the outbound HTTP Request and sending it to the integrated system.

Transaction sending

Unifi is picking up the generated Stage data and generating an outbound HTTP Request.

Transaction receive message

A payload has been received from the external system and Unifi is processing that data and updating the target record within ServiceNow.

RestHelper

An inbound request has been received and generated an inbound HTTP Request.

The logs that can be viewed from the Transaction are for the Transaction itself and the Requests that relate to that Transaction.

Activity Log Sequence

Each of the logs relate to a specific part of the process flow, so depending on the direction of the Transaction the logs will occur in a different sequence. From a process perspective, the logs would occur as follows:

Inbound Message

  • Inbound request: RestHelper (relates to the inbound HTTP Request), Transaction receive message (relates to the inbound Transaction).

  • Corresponding outbound receipt: Transaction sending (relates to the outbound Transaction Receipt), Request sending (relates to the outbound Request).

  • When Transaction completes: Transaction process next queued.

Outbound Message

  • Outbound: Unifi Business Rule (relates to the logs defined in the Trigger on the process table being integrated), Transaction sending (relates to the outbound Transaction), Request sending

    (relates to the outbound Request).

For a synchronous integration that would be it. For an asynchronous integration Unifi would also expect the following:

  • Corresponding inbound receipt: RestHelper (relates to the inbound Transaction Receipt), Transaction receive message (relates to the Receipt processing).

Replay

You can click the Replay button on the Transaction record to replay that transaction.

This will be used when testing/debugging. For example, if there is a transactional error, after you have investigated the cause & made any required changes you will want to replay the Transaction to check if the error clears.