UI Extension Javascript API

To interact with the standard form fields from the Javascript of a UI extension, Xurrent offers the UI Extension Javascript API.

All API calls start with ITRP. For example, the API call ITRP.field('note').val(); can be used to get the current value of the Note field of the Request form.

Get initial values

It is possible to get the initial values of a record when it is opened in edit mode. For example, to make the Attachment field required when a request is edited that has the status Assigned, use the following:

JavaScript
if (ITRP.record.initialValues.get('status') === 'assigned') {
  ITRP.field('attachment').required();
}

The general form of this API call is ITRP.record.initialValues.get('field'). The fields that are available depend on the type of the record that the UI extension is linked to, and are the same as those listed in the Collection Fields section of the respective API:

Note: some of the fields are references, such as the team to which a Request is assigned. You can access the reference attributes (usually id and name / subject) by passing both the name of the reference and the name of the attribute to the API, for example: ITRP.record.initialValues.get('team', 'name').

Distinguish new and existing records

To find out whether the user is adding a new record, use the following:

JavaScript
// Possible values: true and false
var new_record = ITRP.record.new;
if (new_record) { /* ... */ }

Distinguish Self Service and Specialist view

To find out whether the user is using Self Service or the Specialist view, use the following:

JavaScript
// Possible values: 'self_service' and 'full_ui'
if (ITRP.context === 'self_service') { /* ... */ }

A practical example of this can be found in Advanced UI Extension Examples.

Interact with form fields in Self Service

The Javascript API offers various functions to interact with the built-in form fields of Xurrent records. For each type of record and each field, the available functions are listed below. Refer to Functions for descriptions and brief examples of these functions.

Requests

Note that the fields Subject and Asset can only be interacted with when the user is registering a new request.

The field Asset can only be interacted with when the user is registering a request based on a template with the option Asset selection in Self Service enabled.

Tasks

Project Tasks

Interact with form fields in the Specialist view

The Javascript API offers various functions to interact with the form fields of records that are available in the Specialist view. For each type of record and each field, the available functions are listed below. Refer to Functions for descriptions and brief examples of these functions.

Requests

Tasks

Project Tasks

Problems

Configuration Items

Risks

Knowledge articles

Functions

required

Use this function to make a field optional or required.

JavaScript
ITRP.field('note').required(); // Make the Note field required
ITRP.field('note').required(true); // Make the Note field required
ITRP.field('note').required(false); // Make the Note field optional

readonly

Use this function to make a field readonly or read/write.

JavaScript
ITRP.field('severity').readonly(); // Make the Severity field readonly
ITRP.field('severity').readonly(true); // Make the Severity field readonly
ITRP.field('severity').readonly(false); // Make the Severity field read/write

val

Use this function to get or set the value of a field.

JavaScript
// Get the value of the Subject field:
var value = ITRP.field('subject').val();

// Set the value of the Subject field to 'New subject':
ITRP.field('subject').val('New subject');

// Clear the value of the Subject field:
ITRP.field('subject').val('');

// Fill a rich text field with HTML:
ITRP.field('note').val({ html: 'This is <b>bold</b> text.' });

data

Use this function to get additional attributes of a field.

JavaScript
var si_details = ITRP.field('service_instance').data('item');
var si_id = si_details.id; // ID of service instance, same as: ITRP.field('service_instance').val()
var si_name = si_details.name; // Name of service instance
var service_id = si_details.service.id; // ID of service related to service instance
var service_name = si_details.service.name; // Name of service related to service instance

show

Use this function to make a hidden field visible.

JavaScript
ITRP.field('note').show(); // Show the note field

hide

Use this function to hide a field.

JavaScript
ITRP.field('note').hide(); // Hide the note field

toggle

Use this function to toggle the visibility of a field.

JavaScript
ITRP.field('note').toggle(true); // Show the note field
ITRP.field('note').toggle(false); // Hide the note field

size

Use this function to get the number of attached files.

JavaScript
var size = ITRP.field('attachment').size();
if (size < 2) { /* ... */ }

placeholder

Use this function to set the placeholder of the note field.

JavaScript
ITRP.field('note').placeholder('Describe your request here…');

on

Use this function to attach an event handler to a field. It is based on the jQuery on() function and takes two required parameters:

JavaScript
// Make the Remarks field required 
// when the Status is changed to 'In Production'
ITRP.field('status').on('change', function() {
  var status = ITRP.field('status').val();
  ITRP.field('remarks').required(status === 'in_production');
});

off

Use this function to remove an event handler from a field. It is based on the jQuery off() function and takes two required parameters:

JavaScript
var set_remarks_value = function() {
  if (ITRP.field('status').val() === 'being_repaired') {
    ITRP.field('remarks').val('Describe what needs to be repaired:');
    // Make sure that the value of the remarks field is only filled in 
    // the first time the status is set to 'Being Repaired':
    ITRP.field('status').off('change', set_remarks_value);
  }
};

ITRP.field('status').on('change', set_remarks_value);

trigger

Use this function to manually trigger an event. It is based on the jQuery trigger() function and takes one parameter:

JavaScript
// Do something when the user changes the status field to another value:
ITRP.field('status').on('change', function() { /* do something ... */ });

// Make sure that the action defined above is also performed 
// when the form is initially displayed:
ITRP.field('status').trigger('change');


// The two statements above can also be combined, as follows.
// This is a common pattern when attaching an event handler.
ITRP.field('status').on('change', function() { 
  /* do something ... */ 
}).trigger('change');

Access attributes of selected items in suggest fields

When a custom field is a suggest field (for example a organization-suggest or a custom-suggest), calling .val() on the field returns the ID of the selected item. You may need something else to happen depending on the selected item. For example: another field should be shown only when a certain item was selected, as described in the Advanced UI Extension Examples. However, using the ID of the selected item in Javascript may not be desirable, because it makes it more difficult to synchronize UI Extensions between the Xurrent QA and Production environment.

To help with this use case, it is possible to access some of the attributes of the selected item.

When the suggest field allows the selection of a single value, use .data('item') to access these attributes.

When the suggest field allows the selection of multiple values, use .data('items') to get an array of selected items.

The following attributes of an item are available by default:

JavaScript
if ($color.data('item').reference === 'orange') { /* do something ... */ }

var is_orange = function(item) { return item.reference === 'orange'; };
if ($colors.data('items').filter(is_orange).length > 0) { /* do something ... */ }

Access attributes of selected items via metadata fields of custom views

In addition to the standard attributes listed in the previous section, custom-suggest fields can expose additional attributes of items by adding these attributes to the ‘Metadata fields’ field of the Custom View, that the custom-suggest is based on.

For example, suppose you have created a custom view on Configuration Items and added the field assetID and two custom fields called Battery Level and Cost Center to its Metadata fields. The custom field Cost Center refers to a custom collection element.

These metadata fields can then be accessed in the same way as the standard attributes described in the previous section:

JavaScript
var assetID = $my_ci.data('item').assetID;
var assetIDs = $my_cis.data('items').map(function(item) { return item.assetID; });

var batteryLevel = $my_ci.data('item').custom_fields['Battery Level'];
var batteryLevels = $my_cis.data('items').map(function(item) { return item.custom_fields['Battery Level']; });

var costCenter = $my_ci.data('item').custom_fields['Cost Center'];
var costCenterId = costCenter.id;
var costCenterName = costCenter.display_name;
var costCenterReference = costCenter.reference;

A practical example is included in the Advanced UI Extension Examples.

Warning: Be careful when exposing metadata fields containing sensitive information. Suppose a custom-suggest is included as a public custom field in a request template offered to end users. These end users will then be able to obtain the metadata fields of all possible values of the custom-suggest.

Data types

The representation of the exposed data depends on the data type of the metadata field.

Populate suggest fields

As explained in the previous paragraph, when a custom field is a suggest field (for example a organization-suggest or a custom-suggest), calling .val() on the field returns the ID of the selected item. To populate a suggest field with a value, you can also use the .val() function. The examples below illustrate how this works.

JavaScript
// Set the value of a suggest field based on the ID of a record:
// ('123456' is the ID of a person record in Xurrent)
$level_1_approver.val(123456);

// Set the value of a suggest field that allows multiple values:
$level_2_approvers.val([123456, 987654]);

// When the suggest field is a custom-suggest
// based on custom collection elements,
// you can also use the reference of the custom collection element:
$cost_center.val({ reference: "cost-center-a" });

// And if the custom-suggest allows multiple values:
$cost_centers.val({ reference: ["cost-center-a", "cost-center-b"] });

Other properties of the ITRP object

ITRP.$

You can use jQuery in the Javascript of UI Extensions. Access the jQuery API via ITRP.$.

Note that the Javascript of every new UI extension starts with the lines:

var $ = ITRP.$;
var $extension = $(this);

The $extension variable is then used to select fields of the UI extension, add event handlers, and so on:

$extension.find('#my_field').on('change', function() {
  ... 
});

ITRP.hasFormData() and ITRP.clearFormData()

The functions ITRP.hasFormData and ITRP.clearFormData are used to interact with all form elements in a given scope:

// hasData will be true if any form element in the $extension scope has a value 
var hasData = ITRP.hasFormData($extension);
if (hasData) {
  // Do something
}

var $my_button = $extension.find('#my_button');
$my_button.on('click', function() {
  // Clears all form elements in the $extension scope.
  ITRP.clearFormData($extension);
});

A practical example using both of these functions is given on the Advanced UI Extension Examples page.

The after-prefill hook

The after-prefill hook can be used to execute a JavaScript function that should run after all form elements have been prefilled when editing a record.

When editing an existing record with custom fields, Xurrent performs a few technical steps:

  1. Load the form HTML, including the HTML of the UI extension. At this point, all the UI extension form elements are present, but still empty.
  2. Load and execute the Xurrent JavaScript.
  3. Load and execute the JavaScript of the UI extension.
  4. Fill the form elements of the UI extension with the custom field values.
  5. Trigger the after-prefill hook.

The following JavaScript snippet illustrates this:

var $my_field = $extension.find('#my_field');

// This statement is executed in step 3
console.log("Value in step 3: " + $my_field.val());

ITRP.hooks.register('after-prefill', function() {
  // This statement is executed in step 5
  console.log("Value in step 5: " + $my_field.val());
});

Suppose that you are editing a request in which the custom field my_field has the value Test. The above snippet will then output the following lines to the developer console of the browser:

Value in step 3: 
Value in step 5: Test

Examples of the after-prefill hook can be found on the Advanced UI Extension Examples page.