Bonds

Bonds store the data necessary to link your ServiceNow record to an external system.

In most integrations each system knows just enough about the other to facilitate correlation and a semblence of process. On task records in ServiceNow this has normally been done using the Correlation Display and Correlation ID fields. If you want to integrate non-task records, then you would need to add fields like these to the table. If you wanted to use one record with many integrations, then you have even more to do.

In Unifi, correlation has been normalised for global use through the use of the Bond record.

Functions

Bond records are used for much more than just storing correlation data; they are the glue that links everything together and ensures that you can maintain a high level of control in all your integrations. In addition to this, all transactions and attachments reference a bond making it easy to track communications.

A Bond record’s primary functions are:

• To store the internal and external references

• To give state control to each integration instance

• To provide insight into the health of the bond

• To track which system ‘owns’ the bond

• To store a running commentary of the bond history

• To ‘contain’ all transactions and attachments for the lifetime of the bond

• To track attachment totals

Manually Closing a Bond

Some integrations will not have a Message that closes the Bond. In these situations, it is preferable to close any open Bonds manually from a business rule on the Target table, e.g. when an Incident is closed . The following business rule script will close all the Bonds for a given record:

(function executeRule(current, previous /*null when async*/) {
  var bond;
 
  bond = new GlideRecord('x_snd_eb_bond');
  bond.addQuery('document', '=', current.sys_id);
  bond.addQuery('state', '!=', 'Closed');
  bond.query();
 
  while (bond.next()) {
    bond.state = 'Closed';
    bond.update();
  }
 
})(current, previous);

References

The references necessary for integration are stored on the bond. You do not need to store any integration data on the integrated record itself.

Internal reference

The display value of the reference field from the ServiceNow record. This is automatically captured based on the Reference field specified in the Process which the integration belongs to.

External reference

The reference used by the external system.

You must have at least one reference (either internal or external) to form a bond to another system. It is recommended to store both references wherever possible.

State Control

In complex integration processes it is often useful (or necessary) to track the state of the bond. This is mainly used to allow or prevent messages from being sent and received, but is also helpful to analysts who can quickly gain insight into what is happening without any additional configuration.

State	Description
New	The bond is created but not yet inserted.
Pending	The bond has been created and the system is waiting for confirmation from the external system.
Open	Message exchange is available.
Suspended	Message exchange has been suspended by the internal process.
Vendor suspended	Message exchange has been suspended by the external process.
Closed	Message exchange has been terminated.

Message Control

Every Message can be conditioned using the Bond state.

Message Scripts

The Bond state is set in the Source to Stage (outbound) and Stage to Target (inbound) Message Scripts.

Health

Bond health can be determined by the Status field. This is constantly updated as transactions are flowing between the integrated systems.

Status	Description
OK	All transactions have completed.
Awaiting	A request has been made and is awaiting completion.
Error	A transaction has failed.

Ownership

Ownership is not always used, but is extremely helpful in complex ticket integrations, especially where many systems might be involved (SIAM/Multi-vendor).

The Owner flag is used to track which system is currently in charge of the ticket. This allows complex security and process logic to take place, creating a much more robust integration.

The Owner flag must be set manually in the Message Scripts.

History

Every transaction update writes an entry to the Bond history. This gives great insight into what has happened and can aid in integration maintenance and debugging.

Cleanup

Automatic Cleanup

Unifi has a unique transactional management approach that is accomplished through the bond: all transactional data is stored against the bond until the bond state changes to Closed, at which point it is deleted. This balance gives integration admins full insight to view and debug integration issues while maintaining table efficiency.

Once the bond is closed, a scheduled job is created in the future using the Integration property Bond cleanup, which specifies how many days to wait before running the cleanup process.

The cleanup process deletes all Transaction and Bonded Attachment records.

Manual Cleanup

Some integrations may need to maintain an open bond for a significant amount of time, or even indefinitely. In this case, a traditional scheduled cleanup job should be created to run periodically to clear out historic records.

Name	Table
Transaction	x_snd_eb_transaction
Bonded Attachment	x_snd_eb_attachment

Cascade Delete

Deleting the Transaction record will cascade delete all Stage and HTTP Request records.

Debugging

You can view the Unifi logs from the Bond record by navigating to the 'Unifi Activity Logs' related list. Activity Logs are particularly helpful to ShareLogic when debugging Unifi itself and will be populated if logging is enabled when debugging.

Activity logs

The logs that can be viewed from the Bond are for the Bond itself and the Transactions that relate to that Bond.

In addition to the Transaction logs (for details of those click here), you will also see the following:

Business rule: <Your Trigger Business Rule>

These logs are defined in the Trigger on the process table being integrated.