1 of 7

Create Scenario

For each of our Scenarios we will need to configure the relevant Messages & Fields. This scenario will need to be tested before moving on to the next.

The Messages we shall be configuring for the Create Scenario are:

CreateIncidentResponse
CreateIncident

We will define which Field records require configuring for each of those Messages at the appropriate time.

The scenario will need to be successfully tested before we can say it is complete.

We shall look in detail at each of the Messages and their respective Fields in turn over the next few pages, before moving on to Test.

CreateIncidentResponse Message

The CreateIncidentResponse Message is the immediate, synchronous response that is sent after processing the Createincident Message.

In Unifi Integration Designer, navigate to the 'Messages' icon. Click New.

The fields to be configured for the CreateIncidentResponse New Message modal are as follows:

Field

Description

Value

Your CreateIncidentResponse New Message modal should look like this:

Click Submit and view to further configure the Message.

Bond Fields

Navigate to Message > Bond.

The Bond fields to be configured are as follows:

*Set bond state choices: None, Pending, Open, Suspended, Vendor suspended, Closed

Your Bond form should look like this:

Setting the Bond state to Open allows messages to be sent/received. See the 'Bonds' page for details.

Click Save.

We are now ready to configure the Fields for our CreateIncidentResponse Message.

CreateIncidentResponse Fields

We will utilise the Field & Field Map records to configure the Message Scripts for the CreateIncidentResponse Message.

Copy Field Maps

It is worth copying all relevant OOTB Field Maps as are necessary for your integration before using any of them in your Field Records - thereby mitigating the risk of any potential issues with future upgrades.

The Field Map we shall use for our CreateIncidentResponse Field record is:

Source Reference

To copy the Source Reference Field Map, navigate to the 'Field Maps' icon.

Click on the ellipsis to the right of the Source Reference Field Map & click Copy.

The fields to edit for the Copy Field Map modal are as follows:

*Name: We have chosen to prefix the existing Field Map Name with the initials of our Integration (you are free to choose any appropriate means of identifying/differentiating your copy).

Your Copy Field Map modal should look like this:

Integration should be automatically populated.

Click Copy.

You will be redirected to the Details page of the newly created Field Map.

Field: result.sys_id

In Unifi Integration Designer, from the CreateIncidentResponse page, navigate to Message > Fields. Click New.

The fields to be configured for the sys_id New Field modal are as follows:

*These fields are automatically defaulted to true, or automatically populated.

**Field map: Value may vary. Choose the copy Field Map you created for your Integration.

Property: We are setting 'sys_id' as the property because that is what is required by the table API. If it were possible, it would better to use something more meaningful, like the Number of the ticket integrated with, as this aids in debugging.

The 'result.sys_id' New Field modal should look like this:

Submit the record.

You will be redirected back to the Fields page of the CreateIncidentResponse Message.

Build

Now that we’ve configured the Field records for the CreateIncidentResponse message, we are ready to build our message scripts.

The following Field record should now be in place for your CreateIncidentResponse messsage:

Feature Alert: In the picture above you will notice that a 'Build Integration' button has appeared in the banner at the top of the page. Whenever a change is made to a Field record that is associated to a Message (whether that is being created, updated, or deleted) the button will be available and acts as a visual reminder that changes have been made and Message Script(s) need to be built. We will talk more about this feature in the Build Integration Level page.

Navigate to Advanced > Script Editor.

When you first open the Script Editor, you will see the following:

Having visibility of your message scripts in the one pane makes scripting so much more efficient.

Click on Build Message.

You will see the 'Message build successful' Info Message.

Your Script Editor fields should now look like this:

You can click View to adjust the layout and change the view to show various combinations of, or individual script fields.

Message Scripts

The newly auto-generated code will appear between a Begin & End Comment immediately prior to any code that may already be there (pre-existing code will be retained).

//===== [ws] Begin Unifi Auto Generated Code =====//

/*
 * This code (between the Begin and End comments) is generated from the
 * Field and Field mapping records which are configured as part of the integration.
 *
 * All code either above or below the comments will be automatically maintained
 * through the build cycle.
 *
 * WARNING: Do not edit the Begin or End comments.
 */

(New auto-generated code will appear here)

//===== [ws] End Unifi Auto Generated Code =====//

(Old pre-existing code will appear here)

We will now examine our new, auto-generated Message Script.

Payload to Stage:

//===== [ws] Begin Unifi Auto Generated Code =====//

/*
 * This code (between the Begin and End comments) is generated from the
 * Field and Field mapping records which are configured as part of the integration.
 *
 * All code either above or below the comments will be automatically maintained
 * through the build cycle.
 *
 * WARNING: Do not edit the Begin or End comments.
 */

x_snd_eb.ws_console.checkpoint("MessageScript")

x_snd_eb.ws_console.execute("Mapping result.sys_id [x_snd_eb_field.do?sys_id=a163e73e1b11b81090dfdb9ebd4bcbdc]", function () {
  log.debug("Field map: PI - Source Reference [x_snd_eb_field_map.do?sys_id=eca02f3e1b11b81090dfdb9ebd4bcb63]");
  payload = payload || {};
  payload.result = payload.result || {};
  var $payload = payload.result;
  
  stage.external_reference = '' + ($payload.sys_id || '');

});

var error = x_snd_eb.ws_console.findCheckpointError("MessageScript");
if (error) throw error.message;

//===== [ws] End Unifi Auto Generated Code =====//

Both the stage & bond external reference are being set to the sys id only because we are integrating with the table API and that's what it requires. If possible, it is better to use something more meaningful, like the Number of the ticket integrated with, as this aids in debugging.

Once you have finished examining the code, click 'Close' to navigate back to the Fields page of the CreateIncidentResponse Message.

Next, we will configure the CreateIncident Message.

CreateIncident Message

The CreateIncident Message will create a ticket on the target table of the integrated system.

After clicking the 'Messages' icon, you will see the following screen (note: the previously configured message is visible in the list):

Click New.

The fields to be configured for the CreateIncident New Message modal are as follows:

Your CreateIncident New Message modal should look like this:

Submit and view to further configure the Message.

Response Fields

Navigate to Message > Response.

The Response fields to be configured are as follows:

*This field is automatically defaulted to true.

Your Response form should look like this:

Navigate to Message > Bond.

Bond Fields

The Bond fields to be configured are as follows:

*These fields are automatically populated.

Your Bond form should look like this:

Navigate to Outbound > Trigger.

Outbound Trigger Fields

The Outbound Trigger fields to be configured (as required)* are as follows:

*Outbound condition (as required):

It is not necessary for you to enter a condition. The value given is an example. You may create any condition (or not) to align with your business process requirements.

Your Outbound Trigger form should look like this:

Navigate to Outbound > Settings.

Outbound Settings Fields

The Outbound Settings fields to be configured are as follows:

*Path

Only add this value if you have used the truncated Endpoint URL in the Connection. If you have used the full Endpoint URL, this step can be skipped.

Your Outbound Settings form should look like this:

Click Save.

We are now ready to configure the Fields for our CreateIncident Message.

CreateIncident Fields

We will utilise the Field & Field Map records to configure the Message Scripts for the CreateIncident Message.

Fields & Field Maps

Depending on your requirements, you will need to create Field records for each of the relevant Incident record field elements (see the table below for an example). For the sake of brevity, this Guide will focus on a select few. If you wish, however, you are free to continue & configure the remaining Field records. The table below lists an example of the Incident record field elements you may wish to map and the relevant Field Maps required to configure each Field record. For a fuller definition of available Field Maps, please see the relevant page in our .

Incident Field

Field Map

*caller_id: we have chosen String type here because we are integrating with the table API. This will return the sys id of the caller as a string value. Note: If we were integrating Unifi to Unifi we may use a Reference type which would return the caller as an object with "value", "link" & "display_value" elements.

The Field records we will focus on will be for Caller (String), Short description (String) and State (Choice).

Copy Field Maps

If you haven't already, you will need to copy the relevant additional Field Maps for the CreateIncident Field records as follows:

String
Choice

Field: incident.caller_id

In Unifi Integration Designer, from the CreateIncident page, navigate to Message > Fields. Click New.

The fields to be configured for the 'incident.caller_id' New Field modal are as follows:

*These fields are automatically defaulted to true, or automatically populated.

**Field map: Value may vary. Choose the copy Field Map you created for your Integration.

Your 'incident.caller_id' New Field modal should look like this:

Submit the record.

You will be redirected back to the Fields page of the CreateIncident Message.

Field: incident.short_description

Because the incident.short_description Field record is the same 'type' (PI - String) & the majority of the settings are the same as the previously configured Field, it will be quicker to copy the incident.caller_id Field & make a few minor changes.

Feature Alert: The 'result.sys_id' Field is visible and inactive. It is an integration level Field which was automatically created by Unifi at the time we created the Message level record (in CreateIncidentResponse Fields). We'll talk in more detail about this feature in the following section.

Click the ellipsis next to the incident.caller_id Field record & click Copy.

The fields to edit for the Copy Field modal are as follows:

*This field is automatically populated.

Your Copy Field modal should look like this:

Click Copy.

You will be redirected to the Details page of the newly created incident.short_description Field record.

The following info message is also displayed (which can be closed):

Field: incident.state

Field records can exist at both the Integration and the Message level (a Field record exists at the Integration level if it isn't linked to a Message i.e. the 'Message' field element is left blank). We noted previously that an Integration level Field record is automatically created when we create one at the Message level. We will utilise and configure both when mapping 'incident.state'.

The 'incident.state' Field record is a Choice 'type' Field. These are used when you’re mapping choice field elements with static values that don't change per Message (e.g. State, Impact, Urgency) i.e. you're not going to have one set of choices/values for create and another for update.

Rather than configure choices for each Message, configure choices once at the Integration level. This means we only need define them once. The Field Map will take care of it and any 'incident.state' Field records that are set at the Message level (i.e. with a value in the 'Message' field) would use the choices configured at the Integration level.

We'll first configure the Message level Field and then move on to configure the choices on its Integration level counterpart.

Field: incident.state (Message level)

There is no need to 'Generate field choices' for Message level Field records because the Field Map always looks for them on an Integration level Field which has the same name.

To quickly navigate to the CreateIncident Message from the Details page of the newly created incident.short_description Field record...

...click the 'Preview' icon to the left of the Message field.

From the CreatIncident Message, navigate to Message > Fields. Click New.

The fields to be configured for our 'incident.state' (Message level) New Field modal are as follows:

*These fields are automatically defaulted to true, or automatically populated.

**Field map: Value may vary. Choose the copy Field Map you created for your Integration.

Your 'incident.state' (Message level) New Field modal should look like this:

Submit the record.

You will be redirected back to the Fields page of the CreateIncident Message.

Field: incident.state (Integration level)

We will need to 'Generate field choices' for this Integration level Choice 'type' Field.

Navigate to the 'Fields' icon to open the Fields page.

Click to open the incident.state (Integration level) Field record (the one where Message is empty).

The incident.state Field record opens to the Details page.

Navigate to Field > Field Choices.

Click Generate field choices.

Click Generate on the 'Generate field choices' modal which displays.

The Field Choices are generated & now visible in the list.

At this stage, you could carry on and configure the remaining Field records for the rest of the Incident fields (as per the table at the top of this section). However, we will now run the Build process to auto-generate our Message Scripts.

Build

Now that we’ve configured the Field records for the CreateIncident message, we are ready to build our message scripts.

From the CreateIncident Message, navigate to Message > Fields.

The following Field records should now be in place for your CreateIncident messsage:

Click on Build Message.

You will see the 'Message build successful' Info Message.

Navigate to Advanced > Script Editor to view the auto-generated code.

Your Script Editor fields should look like this:

Message Scripts

The newly auto-generated code will appear between a Begin & End Comment immediately prior to any code that may already be there (pre-existing code will be retained).

We will now examine our new, auto-generated Message Scripts.

Source to Stage:

Stage to Request:

We are now ready to Test our CreateIncident Message.

Before we do, let's view the Trigger which Unifi automatically created when we ran 'Build Message'.

Trigger

The Trigger is a Business Rule which stipulates the conditions under which Messages will be sent for the process concerned.

Business Rule

There is no need for you to manually create a Trigger (Business Rule). If you have more than one, you will make duplicate updates.

Unifi will automatically create a Trigger (Business Rule) for the Process being integrated (if one doesn't already exist) when you run 'Build' either on the Integration or Message once your Create Message is configured.

In native ServiceNow, navigate to System Definition > Busines Rules. Find and navigate to the automatically generated Business Rule.

The format of the name will be '[S] Unifi ' + <Table Name> + ' trigger rule'.

The top section of your Business Rule record should look like this:

When to run Fields

Your 'When to run' tab should look like this:

Advanced Fields

The code in the script field should look like this:

Your 'Advanced' tab should look like this:

We have confirmed the main elements are in place for our Integration to work. We are now ready to Test our CreateIncident Message.

Test CreateIncident

We will test our CreateIncident Message.

Create an Incident

Navigate to Incident > Create New.

The Incident fields to configure are as follows:

Field

Description

Value

*Note: We have chosen these fields as these were the ones we mapped when creating our Field records for the CreateIncident Message. Your choices may differ depending on which Field records you created.

Your Incident form should look like this:

Right-click & Save.

Note the values entered (including State & Priority), so that you can check them against the mapped fields on the corresponding record in the instance being integrated to.

You should see an Info Message, confirming the CreateIncident Message is being sent to your Integration:

You should also see a note in the Activities stream:

When you scroll down to the 'Unifi Integrations' related list (you may have to configure the related lists to add it to your Incident form), notice:

A Bond has been created. The State remains 'Pending' until the list is refreshed.

Refresh the list by clicking Bonds.

You should see the External reference populated & the State changed to 'Open':

We are using a sys_id for the External reference in our example because we are integrating with the table API. If possible, it is better to use something more meaningful, like the Number of the ticket integrated with, as this aids in debugging.

Click the Bond Number link to open the Bond record.

View the Bond

Your Bond record should look like this:

Bond details:

Integration: < Your Integration >
Connection: < Your Connection >
Table: 'Incident [incident]'
Document: < Your Incident >
State: 'Open' (Message exchange is available)
Status: 'OK' (All transactions have completed)
Internal reference: < ServiceNow ticket reference > (Same as 'Document')
External reference: < External system's ticket reference >

Transaction:

Message: 'Createincident'
Direction: 'Outbound'
Transaction state: 'Complete' (The data has been successfully transported)
Process state: 'Accepted' (The transaction was accepted as within the scope of the business logic that's in place)

You are able to view the logs in the 'Unifi Activity Logs' related list.

Transaction process next queued: Logs from checking whether there are any other transactions queued and processing those.

Transaction sending: Logs from taking the Stage data, building the Request record & sending the Request to the integrated system.

Business rule: < Your Trigger >: Logs from the Business Rule that triggers Unifi.

View the Transaction

Click through to the Transaction record from the related list on the Bond.

Your Transaction record should look like this:

Transaction details:

Table: 'Incident [incident]'
Document: < Your Incident >
Integration: < Your Integration >
Connection: < Your Connection >
Bond: < Your Bond >
Message: 'CreateIncident'
Direction: 'Outbound'
Transaction state: 'Complete' (The data has been successfully transported)
Process state: 'Accepted' (The transaction was accepted as within the scope of the business logic that's in place)

Errors:

Error: (If there was a transactional error the Transaction state would show as 'Error' and the details would be captured here).
Process error: (If there was a process error the Process state would show as 'Rejected' and the details would be captured here)

Stage:

Direction: 'Outbound'
Message: 'CreateIncident'
Internal reference: < ServiceNow ticket reference > (Same as 'Document')
External reference: < External system's ticket reference >

View the Stage

Click through to the Stage record from the related list on the Transaction.

Check the values in the fields match what you expect.

Your Stage record should look like this:

Stage details:

Direction: 'Outbound'
External reference: < External system's ticket reference >
Internal reference: < ServiceNow ticket reference >
Snapshot: < Snapshot record reference >
Message: 'CreateIncident'
Transaction: < Your Transaction >
Integration: < Your Integration >

Mapped Staged Data fields (yours may differ depending on which Field records you created):

Caller ID: < Your caller.id >
Short description: < Your Short description >
State: '1'

View the HTTP Request

Click through to the HTTP Request record from the related list on the Transaction.

This is where you will find details of the data that was transported between the systems being integrated. (These records are extremely useful for developing and debugging integrations because of the immediate availability and contextual relevance to the integration you are developing.)

Your HTTP Request record should look like this:

HTTP Request details:

Integration: < Your Integration >
Connection: < Your Connection >
Transaction: < Your Transaction >
Message: 'CreateIncident'
Direction: 'Outbound'
Request state: 'OK' (There are no errors with the HTTP Request.)
Attempt number: < Number of HTTP Request attempts > (Failed requests are retried up to the maximum attempts number as configured on the Integration.)
Endpoint URL: < The external system’s access URL >
Action Method: 'POST'
Request headers: < The header of the request being sent >
Request payload: < The payload of the request being sent >

Response details:

Status code: '200'
Response headers: < The header of the response being received >
Response payload: < The payload of the response being received >

Compare with the External System's Incident

Navigate to the corresponding Incident in the external system.

Check the values in the fields match those you noted when you saved the Incident in the internal system.

Your external system's Incident record should look like this (depending on the system you're integrating with, your record may look different; the important matter is that the values match):

Caller: < Your Caller >

State: < Your State >

Short description: < Your Short description >

Activities: < Note showing activity on the Incident > (Opened by < your.external.system.user > configured in the Connection)

We are now ready to move on to the Update Scenario.

CreateIncidentResponse Fields

We will utilise the Field & Field Map records to configure the Message Scripts for the CreateIncidentResponse Message.

Copy Field Maps

The Field Map we shall use for our CreateIncidentResponse Field record is:

Source Reference

To copy the Source Reference Field Map, navigate to the 'Field Maps' icon.

Click on the ellipsis to the right of the Source Reference Field Map & click Copy.

The fields to edit for the Copy Field Map modal are as follows:

Field

Description

Value

*Name: We have chosen to prefix the existing Field Map Name with the initials of our Integration (you are free to choose any appropriate means of identifying/differentiating your copy).

Your Copy Field Map modal should look like this:

Integration should be automatically populated.

Click Copy.

You will be redirected to the Details page of the newly created Field Map.

Field: result.sys_id

In Unifi Integration Designer, from the CreateIncidentResponse page, navigate to Message > Fields. Click New.

The fields to be configured for the sys_id New Field modal are as follows:

Field

Description

Value

*These fields are automatically defaulted to true, or automatically populated.

**Field map: Value may vary. Choose the copy Field Map you created for your Integration.

The 'result.sys_id' New Field modal should look like this:

Submit the record.

You will be redirected back to the Fields page of the CreateIncidentResponse Message.

Build

Now that we’ve configured the Field records for the CreateIncidentResponse message, we are ready to build our message scripts.

The following Field record should now be in place for your CreateIncidentResponse messsage:

Navigate to Advanced > Script Editor.

When you first open the Script Editor, you will see the following:

Having visibility of your message scripts in the one pane makes scripting so much more efficient.

Click on Build Message.

You will see the 'Message build successful' Info Message.

Your Script Editor fields should now look like this:

You can click View to adjust the layout and change the view to show various combinations of, or individual script fields.

Message Scripts

The newly auto-generated code will appear between a Begin & End Comment immediately prior to any code that may already be there (pre-existing code will be retained).

//===== [ws] Begin Unifi Auto Generated Code =====//

/*
 * This code (between the Begin and End comments) is generated from the
 * Field and Field mapping records which are configured as part of the integration.
 *
 * All code either above or below the comments will be automatically maintained
 * through the build cycle.
 *
 * WARNING: Do not edit the Begin or End comments.
 */

(New auto-generated code will appear here)

//===== [ws] End Unifi Auto Generated Code =====//

(Old pre-existing code will appear here)

We will now examine our new, auto-generated Message Script.

Payload to Stage:

//===== [ws] Begin Unifi Auto Generated Code =====//

/*
 * This code (between the Begin and End comments) is generated from the
 * Field and Field mapping records which are configured as part of the integration.
 *
 * All code either above or below the comments will be automatically maintained
 * through the build cycle.
 *
 * WARNING: Do not edit the Begin or End comments.
 */

x_snd_eb.ws_console.checkpoint("MessageScript")

x_snd_eb.ws_console.execute("Mapping result.sys_id [x_snd_eb_field.do?sys_id=a163e73e1b11b81090dfdb9ebd4bcbdc]", function () {
  log.debug("Field map: PI - Source Reference [x_snd_eb_field_map.do?sys_id=eca02f3e1b11b81090dfdb9ebd4bcb63]");
  payload = payload || {};
  payload.result = payload.result || {};
  var $payload = payload.result;
  
  stage.external_reference = '' + ($payload.sys_id || '');

});

var error = x_snd_eb.ws_console.findCheckpointError("MessageScript");
if (error) throw error.message;

//===== [ws] End Unifi Auto Generated Code =====//

Once you have finished examining the code, click 'Close' to navigate back to the Fields page of the CreateIncidentResponse Message.

Next, we will configure the CreateIncident Message.

CreateIncident Fields

We will utilise the Field & Field Map records to configure the Message Scripts for the CreateIncident Message.

Fields & Field Maps

Incident Field

Field Map

The Field records we will focus on will be for Caller (String), Short description (String) and State (Choice).

Copy Field Maps

If you haven't already, you will need to copy the relevant additional Field Maps for the CreateIncident Field records as follows:

String
Choice

See (on the 'CreateIncidentResponse Fields' page) for details.

Field: incident.caller_id

In Unifi Integration Designer, from the CreateIncident page, navigate to Message > Fields. Click New.

The fields to be configured for the 'incident.caller_id' New Field modal are as follows:

Field

Description

Value

*These fields are automatically defaulted to true, or automatically populated.

**Field map: Value may vary. Choose the copy Field Map you created for your Integration.

Your 'incident.caller_id' New Field modal should look like this:

Submit the record.

You will be redirected back to the Fields page of the CreateIncident Message.

Field: incident.short_description

Click the ellipsis next to the incident.caller_id Field record & click Copy.

The fields to edit for the Copy Field modal are as follows:

Field

Description

Value

*This field is automatically populated.

Your Copy Field modal should look like this:

Click Copy.

You will be redirected to the Details page of the newly created incident.short_description Field record.

The following info message is also displayed (which can be closed):

Field inheritance is set to true by default. This means the record will be updated with integration-level Field values when saved (except for Active, Inherit and Message values). Uncheck the Inherit field to configure locally. For more information on Field Inheritance click .

Field: incident.state

We'll first configure the Message level Field and then move on to configure the choices on its Integration level counterpart.

Field: incident.state (Message level)

There is no need to 'Generate field choices' for Message level Field records because the Field Map always looks for them on an Integration level Field which has the same name.

To quickly navigate to the CreateIncident Message from the Details page of the newly created incident.short_description Field record...

...click the 'Preview' icon to the left of the Message field.

From the CreatIncident Message, navigate to Message > Fields. Click New.

The fields to be configured for our 'incident.state' (Message level) New Field modal are as follows:

Field

Description

Value

*These fields are automatically defaulted to true, or automatically populated.

**Field map: Value may vary. Choose the copy Field Map you created for your Integration.

Your 'incident.state' (Message level) New Field modal should look like this:

Submit the record.

You will be redirected back to the Fields page of the CreateIncident Message.

Field: incident.state (Integration level)

We will need to 'Generate field choices' for this Integration level Choice 'type' Field.

Navigate to the 'Fields' icon to open the Fields page.

Click to open the incident.state (Integration level) Field record (the one where Message is empty).

The incident.state Field record opens to the Details page.

Navigate to Field > Field Choices.

Click Generate field choices.

Click Generate on the 'Generate field choices' modal which displays.

The Field Choices are generated & now visible in the list.

Build

Now that we’ve configured the Field records for the CreateIncident message, we are ready to build our message scripts.

From the CreateIncident Message, navigate to Message > Fields.

The following Field records should now be in place for your CreateIncident messsage:

Click on Build Message.

You will see the 'Message build successful' Info Message.

Navigate to Advanced > Script Editor to view the auto-generated code.

Your Script Editor fields should look like this:

Message Scripts

The newly auto-generated code will appear between a Begin & End Comment immediately prior to any code that may already be there (pre-existing code will be retained).

//===== [ws] Begin Unifi Auto Generated Code =====//

/*
 * This code (between the Begin and End comments) is generated from the
 * Field and Field mapping records which are configured as part of the integration.
 *
 * All code either above or below the comments will be automatically maintained
 * through the build cycle.
 *
 * WARNING: Do not edit the Begin or End comments.
 */

(New auto-generated code will appear here)

//===== [ws] End Unifi Auto Generated Code =====//

(Old pre-existing code will appear here)

We will now examine our new, auto-generated Message Scripts.

Source to Stage:

//===== [ws] Begin Unifi Auto Generated Code =====//

/*
 * This code (between the Begin and End comments) is generated from the
 * Field and Field mapping records which are configured as part of the integration.
 *
 * All code either above or below the comments will be automatically maintained
 * through the build cycle.
 *
 * WARNING: Do not edit the Begin or End comments.
 */

x_snd_eb.ws_console.checkpoint("MessageScript")

x_snd_eb.ws_console.execute("Mapping incident.caller_id [x_snd_eb_field.do?sys_id=3a5cbbbe1b51b81090dfdb9ebd4bcb66]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  
  var default_value = (function () {
    return '';
  })();
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory) {
    $stage.caller_id = '' + (source.caller_id || default_value);
  } else if (source.caller_id != '') {
    $stage.caller_id = '' + source.caller_id;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.short_description [x_snd_eb_field.do?sys_id=49debf3e1b51b81090dfdb9ebd4bcba5]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  
  var default_value = (function () {
    return '';
  })();
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory) {
    $stage.short_description = '' + (source.short_description || default_value);
  } else if (source.short_description != '') {
    $stage.short_description = '' + source.short_description;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.state [x_snd_eb_field.do?sys_id=f32e8cc31b91b81090dfdb9ebd4bcb09]", function () {
  log.debug("Field map: PI - Choice [x_snd_eb_field_map.do?sys_id=c7b97f7a1b51b81090dfdb9ebd4bcb62]");
  
  var default_value = (function () {
    return '';
  })();
  
  var field_choice;
  var is_mandatory = false;  
  
  if (!source.state.nil()) {
    field_choice = new GlideRecord('x_snd_eb_field_choice');
    field_choice.addQuery('table',         '=', 'incident');
    field_choice.addQuery('element',       '=', 'state');
    field_choice.addQuery('integration',   '=', '27be43a91b9db41090dfdb9ebd4bcb2e');
    field_choice.addQuery('field.message', '=', '');
    field_choice.addQuery('direction',     '=', 'Outbound');
    field_choice.addQuery('value',         '=', source.state);
    field_choice.addQuery('active',        '=', 'true');
    field_choice.query();
  
    if (field_choice.next()) {
      $stage.state = '' + field_choice.external_value;
    }
  } 
  
  if (!$stage.state) {
    $stage.state = '' + (source.state || '');
  }
  
  if (is_mandatory) {
    $stage.state = '' + (source.state || '');
  }

});

var error = x_snd_eb.ws_console.findCheckpointError("MessageScript");
if (error) throw error.message;

//===== [ws] End Unifi Auto Generated Code =====//

Stage to Request:

//===== [ws] Begin Unifi Auto Generated Code =====//

/*
 * This code (between the Begin and End comments) is generated from the
 * Field and Field mapping records which are configured as part of the integration.
 *
 * All code either above or below the comments will be automatically maintained
 * through the build cycle.
 *
 * WARNING: Do not edit the Begin or End comments.
 */

x_snd_eb.ws_console.checkpoint("MessageScript")

x_snd_eb.ws_console.execute("Mapping incident.caller_id [x_snd_eb_field.do?sys_id=3a5cbbbe1b51b81090dfdb9ebd4bcb66]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  payload = payload || {};
  var $payload = payload;
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory) {
    $payload.caller_id = '' + $stage.caller_id;
  } else if ($stage.caller_id) {
    $payload.caller_id = '' + $stage.caller_id;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.short_description [x_snd_eb_field.do?sys_id=49debf3e1b51b81090dfdb9ebd4bcba5]", function () {
  log.debug("Field map: PI - String [x_snd_eb_field_map.do?sys_id=da997f7a1b51b81090dfdb9ebd4bcb5e]");
  payload = payload || {};
  var $payload = payload;
  
  // Determines whether this instance of the field map is for a mandatory field
  var is_mandatory = false;
  
  if (is_mandatory) {
    $payload.short_description = '' + $stage.short_description;
  } else if ($stage.short_description) {
    $payload.short_description = '' + $stage.short_description;
  }

});


x_snd_eb.ws_console.execute("Mapping incident.state [x_snd_eb_field.do?sys_id=f32e8cc31b91b81090dfdb9ebd4bcb09]", function () {
  log.debug("Field map: PI - Choice [x_snd_eb_field_map.do?sys_id=c7b97f7a1b51b81090dfdb9ebd4bcb62]");
  payload = payload || {};
  var $payload = payload;
  
  var is_mandatory = false;  
  
  if (is_mandatory) {
    $payload.state = $stage.state;
  } else if ($stage.state) {
    $payload.state = $stage.state;
  }

});

var error = x_snd_eb.ws_console.findCheckpointError("MessageScript");
if (error) throw error.message;

//===== [ws] End Unifi Auto Generated Code =====//

We are now ready to Test our CreateIncident Message.

Before we do, let's view the Trigger which Unifi automatically created when we ran 'Build Message'.

Test CreateIncident

We will test our CreateIncident Message.

Create an Incident

Navigate to Incident > Create New.

The Incident fields to configure are as follows:

Field

Description

Value

Your Incident form should look like this:

Right-click & Save.

Note the values entered (including State & Priority), so that you can check them against the mapped fields on the corresponding record in the instance being integrated to.

You should see an Info Message, confirming the CreateIncident Message is being sent to your Integration:

You should also see a note in the Activities stream:

When you scroll down to the 'Unifi Integrations' related list (you may have to configure the related lists to add it to your Incident form), notice:

A Bond has been created. The State remains 'Pending' until the list is refreshed.

Refresh the list by clicking Bonds.

You should see the External reference populated & the State changed to 'Open':

Click the Bond Number link to open the Bond record.

View the Bond

Your Bond record should look like this:

Bond details:

Integration: < Your Integration >
Connection: < Your Connection >
Table: 'Incident [incident]'
Document: < Your Incident >
State: 'Open' (Message exchange is available)
Status: 'OK' (All transactions have completed)
Internal reference: < ServiceNow ticket reference > (Same as 'Document')
External reference: < External system's ticket reference >

Transaction:

Message: 'Createincident'
Direction: 'Outbound'
Transaction state: 'Complete' (The data has been successfully transported)
Process state: 'Accepted' (The transaction was accepted as within the scope of the business logic that's in place)

You are able to view the logs in the 'Unifi Activity Logs' related list.

Transaction process next queued: Logs from checking whether there are any other transactions queued and processing those.

Transaction sending: Logs from taking the Stage data, building the Request record & sending the Request to the integrated system.

Business rule: < Your Trigger >: Logs from the Business Rule that triggers Unifi.

View the Transaction

Click through to the Transaction record from the related list on the Bond.

Your Transaction record should look like this:

Transaction details:

Table: 'Incident [incident]'
Document: < Your Incident >
Integration: < Your Integration >
Connection: < Your Connection >
Bond: < Your Bond >
Message: 'CreateIncident'
Direction: 'Outbound'
Transaction state: 'Complete' (The data has been successfully transported)
Process state: 'Accepted' (The transaction was accepted as within the scope of the business logic that's in place)

Errors:

Error: (If there was a transactional error the Transaction state would show as 'Error' and the details would be captured here).
Process error: (If there was a process error the Process state would show as 'Rejected' and the details would be captured here)

Stage:

Direction: 'Outbound'
Message: 'CreateIncident'
Internal reference: < ServiceNow ticket reference > (Same as 'Document')
External reference: < External system's ticket reference >

View the Stage

Click through to the Stage record from the related list on the Transaction.

Check the values in the fields match what you expect.

Your Stage record should look like this:

Stage details:

Direction: 'Outbound'
External reference: < External system's ticket reference >
Internal reference: < ServiceNow ticket reference >
Snapshot: < Snapshot record reference >
Message: 'CreateIncident'
Transaction: < Your Transaction >
Integration: < Your Integration >

Mapped Staged Data fields (yours may differ depending on which Field records you created):

Caller ID: < Your caller.id >
Short description: < Your Short description >
State: '1'

View the HTTP Request

Click through to the HTTP Request record from the related list on the Transaction.

Your HTTP Request record should look like this:

HTTP Request details:

Integration: < Your Integration >
Connection: < Your Connection >
Transaction: < Your Transaction >
Message: 'CreateIncident'
Direction: 'Outbound'
Request state: 'OK' (There are no errors with the HTTP Request.)
Attempt number: < Number of HTTP Request attempts > (Failed requests are retried up to the maximum attempts number as configured on the Integration.)
Endpoint URL: < The external system’s access URL >
Action Method: 'POST'
Request headers: < The header of the request being sent >
Request payload: < The payload of the request being sent >

Response details:

Status code: '200'
Response headers: < The header of the response being received >
Response payload: < The payload of the response being received >

Compare with the External System's Incident

Navigate to the corresponding Incident in the external system.

Check the values in the fields match those you noted when you saved the Incident in the internal system.

Your external system's Incident record should look like this (depending on the system you're integrating with, your record may look different; the important matter is that the values match):

Caller: < Your Caller >

State: < Your State >

Short description: < Your Short description >

Activities: < Note showing activity on the Incident > (Opened by < your.external.system.user > configured in the Connection)

We are now ready to move on to the Update Scenario.