UI Extension Javascript API
To interact with the standard form fields from the Javascript of a UI extension, 4me 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
- Distinguish new and existing records
- Distinguish Self Service and Specialist view
- Interact with form fields in Self Service
- Interact with form fields in the Specialist view
- Functions
- Access attributes of selected items in suggest fields
- Populate suggest fields
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:
- Requests
- Problems
- Workflows
- Tasks
- Projects
- Project Tasks
- Configuration Items
- Contracts
- Organizations
- Sites
- People
- Risks
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 4me 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
- Subject:
ITRP.field('subject')
-required
show
hide
toggle
val
- Note:
ITRP.field('note')
-required
show
hide
toggle
val
placeholder
- Attachments:
ITRP.field('attachment')
-required
show
hide
toggle
size
- Asset:
ITRP.field('asset')
-required
show
hide
toggle
val
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
- Attachments:
ITRP.field('attachment')
-required
show
hide
toggle
size
- Status:
ITRP.field('status')
-val
on
off
trigger
Project Tasks
- Attachments:
ITRP.field('attachment')
-required
show
hide
toggle
size
- Status:
ITRP.field('status')
-val
on
off
trigger
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
- Subject:
ITRP.field('subject')
-val
- Note:
ITRP.field('note')
-val
placeholder
- Attachments:
ITRP.field('attachment')
-required
show
hide
toggle
size
- Internal note:
ITRP.field('internal_note')
-val
- Internal attachments:
ITRP.field('internal_attachment')
-required
show
hide
toggle
size
- Configuration items:
ITRP.field('asset')
-required
- Status:
ITRP.field('status')
-val
on
off
trigger
Tasks
- Attachments:
ITRP.field('attachment')
-required
show
hide
toggle
size
- Status:
ITRP.field('status')
-val
on
off
trigger
- Configuration items:
ITRP.field('asset')
-required
Project Tasks
- Attachments:
ITRP.field('attachment')
-required
show
hide
toggle
size
- Status:
ITRP.field('status')
-val
on
off
trigger
Problems
- Attachments:
ITRP.field('attachment')
-required
show
hide
toggle
size
- Status:
ITRP.field('status')
-val
on
off
trigger
- Configuration items:
ITRP.field('asset')
-required
Configuration Items
- Status:
ITRP.field('status')
-val
on
off
trigger
- System ID:
ITRP.field('systemID')
-val
required
on
off
trigger
- Service:
ITRP.field('service')
-required
- Site:
ITRP.field('site')
-val
required
on
off
trigger
- Location:
ITRP.field('location')
-val
required
on
off
trigger
- Remarks:
ITRP.field('remarks')
-val
required
on
off
trigger
- Attachments:
ITRP.field('attachments')
-required
- Nr. of processors:
ITRP.field('nr_of_processors')
-val
required
on
off
trigger
- Nr. of cores:
ITRP.field('nr_of_cores')
-val
required
on
off
trigger
- Nr. of licenses:
ITRP.field('nr_of_licenses')
-val
required
on
off
trigger
- Service instances:
ITRP.field('service_instances')
-required
- Users:
ITRP.field('users')
-required
- Product:
ITRP.field('product')
-val
on
off
trigger
- Rule set:
ITRP.field('rule_set')
-val
(read only) - Configuration items:
ITRP.field('ci_relations')
-required
- Contracts:
ITRP.field('contracts')
-required
- Supplier:
ITRP.field('supplier')
-val
required
on
off
trigger
- Serial number:
ITRP.field('serial_nr')
-val
required
on
off
trigger
- Financial owner:
ITRP.field('financial_owner')
-val
required
on
off
trigger
- PO number:
ITRP.field('po_nr')
-val
required
on
off
trigger
- Asset ID:
ITRP.field('assetID')
-val
required
on
off
trigger
- Depreciation method:
ITRP.field('depreciation_method')
-val
required
on
off
trigger
- In use since:
ITRP.field('in_use_since')
-val
required
on
off
trigger
- Warranty expiry date:
ITRP.field('warranty_expiry_date')
-val
required
on
off
trigger
Risks
- Status:
ITRP.field('status')
-val
on
off
trigger
- Mitigation target:
ITRP.field('mitigation_target_at')
-val
required
readonly
show
hide
toggle
on
off
trigger
- Severity:
ITRP.field('severity')
-val
required
readonly
show
hide
toggle
on
off
trigger
- Closure reason:
ITRP.field('closure_reason')
-val
on
off
trigger
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.' });
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:
event type
: the type of event that should be handled, such aschange
,click
, orfocus
.handler function
: the function that should be called when events of the given event type occur.
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:
event type
: the type of event that should no longer be handled, such aschange
.handler function
: the handler function that was previously attached via theon
function. Note that this should be the same function.
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:
event type
: the type of event that should be triggered, such aschange
.
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-view-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 4me 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:
id
display_name
: this is the name or subject of the item as it is displayed on the screen. In some cases thedisplay_name
can be a combination of multiple attributes. For example, thedisplay_name
of a CI is a combination of the Label and Name attribute.reference
: only available for record types that have a Reference attribute, such as custom collection elements.
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 ... */ }
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-view-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 4me)
$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"] });