1 of 3

Bond Identification

In order for both systems to identify & understand which records are bonded and to facilitate only returning data from bonded records, we need to make a few configuration changes.

Our previously configured Outbound Incident Integration was very simple example and we weren't concerned with identifying which system made the updates. Neither were we concerned with telling the remote system which record they were bonded with.

Now that we're polling our PDI for data as well as sending data, we need to be aware of both the above concerns.

The first concern (identifying which system made the updates) has been taken care of in the Poll Processor Setup script (only returning data not updated by the Basic Authentication User). However, it doesn't make sense to try and return that data from all the records in the remote system. We should only be concerned with those records we're bonded with. To facilitate this we need to make a few configuration changes. We need to make a change in the remote system (our PDI) and some changes to our existing outbound CreateIncident Message.

First, we will need to Edit the Incident Form in our PDI.

Edit Incident Form

The first configuration change we need to make to facilitate Bond identification is to add the Correlation ID field to the Incident form in our PDI.

Correlation ID

In order for the remote system to store data about which record they're bonded with and to enable us to identify and only return data from those bonded records, we need to send and store a unique identifier. We will make use of the available correlation_id field on the Incident record. First we will add the field to the Incident form in our PDI.

Incident Form

From any Incident record in your PDI, right-click & navigate to Configure > Form Layout.

Select the Correlation Id field from the 'Available' slushbucket and move it to the 'Selected' slushbucket.

Save to add the field to your form.

Next, we will need to Edit the CreateIncident Message.

Edit CreateIncident Message

Here we will deal with the configuration changes that need to be made to our CreateIncident Message to facilitate identifying and returning data from bonded records.

CreateIncident Message

Now that we've configured the remote system's Incident form to display our bonded ticket number as the correlation id, we need to update our CreateIncident Message to send it.

To ensure that our CreateIncident Message is sending the relevant data we need to configure a new Field record that will send the Incident number as the correlation id. We will make use of the previously copied String Field Map record.

Field: incident.number

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

The fields to be configured for our incident.number 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.number' 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.description

It is not necessary to configure this Field record to facilitate identifying and returning data from bonded records. It is only included here to facilitate the sending of data in the Description field of the Incident when testing our Integration. You may choose to ignore this if you wish. Similarly, if you had already configured the incident.description Field record for the CreateIncident Message (when completing the 'Outbound incident' Guide), you can ignore this.

The ‘incident.description’ (Integration level) Field record should already be in place (i.e. with Active set to false). This was automatically created by Unifi when we created the Message level record when configuring the Fields for the UpdateIncidentInbound Message. We will now create its Message level counterpart for the CreateIncident Message.

From the CreateIncident Message, navigate to Message > Fields.

Your CreateIncident Fields page should look like this:

Find the incident.description (Integration level) Field & set Active to true.

The empty circle icon next to the Field name turns green & contains a green ‘check’ (to indicate that Message level configuration exists for this Field) when we set Active to true. (The ‘Build Integration’ button became visible in the banner when we created the 'incident.number' Field record.)

By setting the Active flag to true on the Integration level Field record listed on the Message, Unifi has automatically created the Message level counterpart.

Click to open the incident.description (Message level) Field to make a few minor changes.

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

To edit, set Inherit to False.

Save the record (the fields now become editable).

Navigate to Field > Settings.

Edit the incident.description Field record as follows:

Your 'incident.description' Field record should look like this:

Save the record.

Build

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

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

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

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

Click on Build Message.

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

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

Your Script Editor fields should look like this:

Message Scripts

The new auto-generated code (mapping the incident number to the correlation id & mapping the Incident description) will appear between the Begin & End Comment along with the code that was already there (which we had previously created using the Outbound Incident Guide). Your code may differ, depending on which Field records you created to satisfy your mapping requirements.

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.number [x_snd_eb_field.do?sys_id=997a766c1be1bc1090dfdb9ebd4bcbb7]", 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.number = '' + (source.number || default_value);
  } else if (source.number != '') {
    $stage.number = '' + source.number;
  }

});


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.description [x_snd_eb_field.do?sys_id=618a766c1be1bc1090dfdb9ebd4bcb91]", 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.description = '' + (source.description || default_value);
  } else if (source.description != '') {
    $stage.description = '' + source.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.number [x_snd_eb_field.do?sys_id=997a766c1be1bc1090dfdb9ebd4bcbb7]", 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.correlation_id = '' + $stage.number;
  } else if ($stage.number) {
    $payload.correlation_id = '' + $stage.number;
  }

});


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.description [x_snd_eb_field.do?sys_id=618a766c1be1bc1090dfdb9ebd4bcb91]", 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.description = '' + $stage.description;
  } else if ($stage.description) {
    $payload.description = '' + $stage.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 have now completed the configuration and are ready to move on to Test our Update Scenario.

Edit CreateIncident Message

Here we will deal with the configuration changes that need to be made to our CreateIncident Message to facilitate identifying and returning data from bonded records.

CreateIncident Message

Now that we've configured the remote system's Incident form to display our bonded ticket number as the correlation id, we need to update our CreateIncident Message to send it.

Field: incident.number

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

The fields to be configured for our incident.number 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.number' 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.description

From the CreateIncident Message, navigate to Message > Fields.

Your CreateIncident Fields page should look like this:

Find the incident.description (Integration level) Field & set Active to true.

By setting the Active flag to true on the Integration level Field record listed on the Message, Unifi has automatically created the Message level counterpart.

Click to open the incident.description (Message level) Field to make a few minor changes.

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

To edit, set Inherit to False.

Save the record (the fields now become editable).

Navigate to Field > Settings.

Edit the incident.description Field record as follows:

Field

Description

Value

Your 'incident.description' Field record should look like this:

Save the record.

Build

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

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

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

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

Click on Build Message.

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

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

Your Script Editor fields should look like this:

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.number [x_snd_eb_field.do?sys_id=997a766c1be1bc1090dfdb9ebd4bcbb7]", 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.number = '' + (source.number || default_value);
  } else if (source.number != '') {
    $stage.number = '' + source.number;
  }

});


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.description [x_snd_eb_field.do?sys_id=618a766c1be1bc1090dfdb9ebd4bcb91]", 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.description = '' + (source.description || default_value);
  } else if (source.description != '') {
    $stage.description = '' + source.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.number [x_snd_eb_field.do?sys_id=997a766c1be1bc1090dfdb9ebd4bcbb7]", 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.correlation_id = '' + $stage.number;
  } else if ($stage.number) {
    $payload.correlation_id = '' + $stage.number;
  }

});


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.description [x_snd_eb_field.do?sys_id=618a766c1be1bc1090dfdb9ebd4bcb91]", 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.description = '' + $stage.description;
  } else if ($stage.description) {
    $payload.description = '' + $stage.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 have now completed the configuration and are ready to move on to Test our Update Scenario.