If you're looking to integrate a new table with Unifi (prior to v3 as this is then done automatically), and you create a new trigger business rule for the new table from an existing Unifi trigger rule, be careful with what you copy! Old business rules use a different way to invoke the script from new ones!

Overwriting a new business rules invoke method with an old one will mean the business rule fails. Only copy the Unifi code inside the business rule invoke method.

Old business rule invoke:

New business rule invoke method:

Sometimes there is a need to receive messages from an external system for records which exist in your system, but aren't bonded in Unifi.

To do this setup an inbound create message for the target integration, this will ensure that the bond is created. Add the code below to the top of your stage to target script, before any auto generated code. It will look up the existing record and repoint Unifi to use that record instead of creating a new one.

var existing = new GlideRecord('change_request');
existing.addQuery(...); // Your look up code here - assuming other system knows ServiceNow sys_id/number
existing.query();

if (!existing.next()) {
  throw 'Target record with ID ' + /*whatever you use for your id here*/ + ' not found.';
}

target.$model.setRecord(existing);
target = target.$model.getRecord();
bond.setTarget(target.$model);
bond.setValue('internal_reference', target.number);
transaction.$model.setTarget(target);

bond.shouldCommitTarget(false);
bond.commit();
bond.shouldCommitTarget(true);

When you use the Unifi packager to move integrations from once instance to another, be aware that any records you delete will not be captured when the integration is packaged. It's better to deactivate records rather than delete them. If you do have to delete records, consider capturing them in an update set, or manually deleting them as part of the migration process.

Background

Multipart form data (usually written multipart/form-data) is an encoding format devised as a means of encoding an HTTP form for posting up to a server. It is often used to encode files for upload to web servers. The format is formally defined in RFC-7578 : Returning Values from Forms: multipart/form-data.

HTTP Header

A HTTP POST message can include a HTTP content-type header of type multipart/form-data to indicate that the body is encoded in this way and the header must contain a directive to define the 'boundary' string used to separate the 'parts' of the body.

content-type: multipart/form-data; boundary="9871z7t355g08e925"

The boundary is any string of ASCII characters which is unlikely to appear in the data carried in the body. The quotes around the boundary string are only required if it contains special characters, such as colon (:).

HTTP Body

Part Boundaries

Each part of the body is introduced by the boundary separator.

The sequence is: CRLF, -- (two hyphens), boundary string e.g.

--9871z7t355g08e925

Each part has one or more headers which indicate the encoding of that part and which follow immediately after the boundary separator. The content-disposition header is mandatory and must have a value of form-data ; it may also include a directive to specify the name of the field on the form e.g.

--9871z7t355g08e925
content-disposition: form-data; name="user_name"

When the form field is for a file to upload, it's also common practice to include a filename directive, which suggests the name to use to store the file data on the receiving system.

--9871z7t355g08e925
content-disposition: form-data; name="profile_picture"; filename="my_passport_photo.jpg"

Part Types

Another common (though optional) part header is content-type which is used to indicate the media-type of that part.

e.g. for text content

--9871z7t355g08e925
content-disposition: form-data; name="first_name"
content-type: text/plain

e.g. for binary content

--9871z7t355g08e925
content-disposition: form-data; name="details"; filename="config01.txt"
content-type: application/octet-stream

Binary data carried within multipart/form-data formatted messages is not encoded in any way, it is the raw sequence of binary bytes; it is only the presence of the boundary separator which terminates the sequence.

Part Terminators

The end of a part is indicated by the occurrence of the next boundary separator.

The final part of the body is terminated with a boundary separator which is immediately followed by two hyphens.

The sequence is: CRLF, -- (two hyphens), boundary string, -- e.g.

--9871z7t355g08e925--

Implementing Multipart in Unifi

To implement Multipart Form Data support in Unifi we perform the following steps:

• Set up a scripted REST API which takes text and attachments and generates a response that looks like the multipart body that we wish to ultimately send

• We call that API (as a loopback REST call to the same instance) with parameters which define the text and attachments (and boundary string) that we want to work with

• The API writes the combination of text and attachment data as a stream into its response

• We save the response from this loopback API into a temporary attachment (which will contain the exact multipart body that we wanted)

• We take the temporary attachment and stream that to the ultimate destination (we will need to know the boundary string that was embedded in the multipart body and include that in the content-type header of the request that we are sending)

UnifiMultipartHelper

The logic to support this implementation is in UnifiMultipartHelper which contains helper methods for both the client code which wants to generate multipart data and for the REST API server side which generates the body as a response.

Example usage

var mp = new UnifiMultipartHelper();

// We need a record to link the temporary attachment to.
// (Default is the the sys_user record of the calling user)
// For Unifi this is likely to be the HTTPRequest record
//
// Let's hang it off a record we created earlier and stored in 'grHost'
//
mp.setHostRecord(grHost);
// Alternatively, we could call setHostDetails( table_name, sys_id )

// When adding an attachment we need to specify two or three things
// - the name of the form field that the target is expecting
// - the sys_id of the attachment to add
// - (optional) the file name; if not supplied it will be taken from the attachment
mp.addAttachment('file','0e329292398101808125852108518');

// We could add more text or attchment parts here

// Generate the temporary attachment
mp.createBody();

// We can now use the generated attachment along with the boundary string
// to send the multipart body to the other system

var req = new sn_ws.RESTMessageV2();
req.setHttpMethod('POST');

// getContentType returns the content-type string including the boundary
// e.g. multipart/form-data; boundary="xxxxxxxxxxxx"
req.setRequestHeader('Content-Type',mp.getContentType());

// getBodyId returns the sys_id of the multipart attachment
req.setRequestBodyFromAttachment(mp.getBodyId());

req.setEndpoint( /* the url */ );
req.setAuthenticationProfile('basic',/* the auth profile */);

var resp = req.execute();

// Once we have sent the body we can delete the temporary attachment
mp.deleteBody();

If you are seeing duplicate messages being sent by Unifi, then there are two things you should check:

• Check for duplicate Unifi trigger business rules on your table. This is usually seen in domain separated instances where a trigger rule has been updated in a different domain and therefor inserted a new rule, causing Unifi to fire twice.

• You're performing a double update on the record being integrated. It's surprising how often this happens, you just don't see it until Unifi fires twice. Check the history of the record being integrated, are there two updates at the same time? This usually happens when a before rule inserts a record in another table, and that table then updates the initial record, creating a double update i.e. new incident saved with a CI, before rule on incident inserts a new Task CI record for the added CI, after rule on Task CI adds a work note to the incident causing a double update.

This error is caused by not having the correct version of the Unifi global utility script installed. Unifi v3 will automatically create trigger rules on newly integrated tables which do not have a trigger rule already defined. This isn't possible from an application scope, which is why our global utility is required. Installing the correct version will resolve this issue.