Skip to main content

Xurrent

All Xurrent functions automatically retry failed requests based on the rules described here.

addApprover​

Add approver person with id "personId" to the approval Task with id "taskId". Both parameters are mandatory. There is no check if the task is a approval task.

addApprover(taskId, personId, [account]);

Example:

let taskId = 172;
let personId = 123;
addApprover(taskId, personId);

addNote​

add the note "new text" to module "requests" on the element with the id request.id.

addNote(module, id, text, [account]);

Example:

addNote("requests", request.id, "new text");

checkExportState​

check the state of an export that was started with initExport

checkExportState(token, account_name);

Example:

let account_name = "wdc";
let result = initExport("organizations", account_name);

let state_result = null;

for (let counter = 0; counter < 50; counter++) {
  state_result = checkExportState(result.token, account_name);

  log(`state result ${counter} : `, state_result);
  if (state_result.state == "done" || state_result.state == "error") {
    break;
  }
  sleep(2000);
}

let final_results = loadFileToString(state_result.url);

log("final_results", final_results);
let list = csvToObjectList(final_results);
log("list", list);

checkImportState​

check the state of an import that was started with import_csv

checkImportState(token, account_name);

Example:

let account_name = "wdc";
let upload_csv = "Source,Source ID,Name,Disabled";
let upload_lines = [];

for (let x = 1; x < 20; x++) {
  upload_lines.push(`wdc-import,import_org_sourceID${x},import org name${x},1`);
}

upload_csv = upload_csv + "\n" + upload_lines.join("\n");

let result = import_csv("organizations", upload_csv, account_name);
log("result", result);

let state_result = null;

for (let counter = 0; counter < 50; counter++) {
  state_result = checkImportState(result.token, account_name);

  log(`state result ${counter} : `, state_result);
  if (state_result.state == "done" || state_result.state == "error") {
    break;
  }
  sleep(2000);
}

let final_results = loadFileToString(state_result.logfile);

log("final_results", final_results);

create​

Create a new element in Xurrent.

create(module, data, [account]);

Example 1:

let result = create("workflows", {
  template_id: 13,
  manager_id: 147995,
});

Create a workflow with the workflow template with ID 13 and with manager with person ID 147995 The new element is accessible by result variable.

Example 2:

let result = create("workflows", {
  member_id: 147995,
  workflow_type: "application_workflow",
  justification: "correction",
  subject: "by Xurrent script",
});

Create a workflow using the given field values. The new element is accessible by result variable.

Example 3:

let docDefinition = {
  content: "Very important document",
};

let pdfBuffer = create_pdf(docDefinition);

let pdfAttachment = {
  content: pdfBuffer,
  length: pdfBuffer.length,
  fileName: "Document.pdf",
};

let result = create(
  "requests",
  {
    note: "PDF Document upload",
    status: "assigned",
    template_id: 13,
    attachments: [pdfAttachment],
  },
  "account-name",
);

Create request with attachment pdf.

customFieldsToObject​

Converts a list of custom fields to a plain object.

The first parameter can be either a Xurrent object with a custom_fields attribute, or an array of custom fields with id and value attributes.

The result is at least an empty object.

let plain_custom_data = customFieldsToObject(custom_fields);

Example 1: Convert list of custom fields to object.

let plain_custom_data = customFieldsToObject([
  { id: "email_1", value: "a@b.com" },
  { id: "priority", value: "high" },
]);
// Result: { email_1: 'a@b.com', priority: 'high' }

Example 2: Convert Xurrent object with custom fields to object.

let plain_custom_data = customFieldsToObject(request);

objectToCustomFields​

Converts a plain object into a custom_fields array with id and value attributes.

The result is at least an empty array.

let custom_fields = objectToCustomFields(plain_custom_data);

Example 1: Convert plain object to list of custom fields.

let custom_fields = objectToCustomFields({ email_1: "a@b.com", priority: "high" });
// Result: [
//   { id: 'email_1', value: 'a@b.com' },
//   { id: 'priority', value: 'high' }
// ]

getCustomFieldsValue​

Returns the value of the custom field with the given id. If there is no such custom field, or if its value is null, returns the default value, or null if no default value is given.

The first parameter can be either a Xurrent object with a custom_fields attribute, or an array of custom fields with id and value attributes.

let value = getCustomFieldsValue(custom_fields, 'id')
let value = getCustomFieldsValue(custom_fields, 'id', 123);

Example 1: Return value of email_1 custom field.

let value = getCustomFieldsValue(request.custom_fields, "email_1");

Example 2: Return value of email_1 custom field out of Xurrent request.

let value = getCustomFieldsValue(request, "email_1");

Example 3: Return value of email_1 custom field, or default value dummy@test.com if not set.

let value = getCustomFieldsValue(request, "email_1", "dummy@test.com");

setCustomFieldsValue​

Sets the custom field with the given id to the given value. If the custom field does not yet exist, it is added to the list.

The first parameter can be either a Xurrent object with a custom_fields attribute, or an array of custom fields with id and value attributes.

setCustomFieldsValue(custom_fields, 'id', value);

Example 1: Set the value of the email_1 custom field on a Xurrent request.

setCustomFieldsValue(request, "email_1", "new@example.com");

Example 2: Fetch request, update custom field priority to high and update request in Xurrent.

let request = fetch("requests", 1234);
setCustomFieldsValue(request, "priority", "high");
update("requests", request.id, { custom_fields: request.custom_fields });

hasCustomFieldId​

Checks if a custom field with the given id exists.

Also returns true if the custom field exists and its value is null.

The first parameter can be either a Xurrent object with a custom_fields attribute, or an array of custom fields with id and value attributes.

let exists = hasCustomFieldId(custom_fields, 'id');

Example 1: Update email_1 custom field on a Xurrent request, but only if such a custom field exists.

if (hasCustomFieldId(request, "email_1")) {
  setCustomFieldsValue(request, "email_1", "new@example.com");
}

deleteItrp​

Deletes a Xurrent record. Account name is optional and defaults to the account that triggered the package.

const recordType = "cis";
const endpoint = ciId + "/ci_relations/" + ciRelationId;
const account_name = "wdc";
deleteItrp(recordType, endpoint, account_name);

exportPromise​

initiate an export and return a promise

exportPromise(type, account_name);

Example:

let account_name = "wdc";
let promise = exportPromise("organizations", account_name);
let result = waitForPromise(promise);

log("result", result);
log("promise", promise);
log("promise.content", promise.content);

fetch​

Fetch data from Xurrent Module if id is known

let result = fetch("module_name", element_id, [account]);

Example 1: fetch workflow with id 123

let workflow = fetch("workflows", 123);

Example 2: fetch organization with id 123

let organization = fetch("organizations", 123);

Example 3: fetch person with id 123

let person = fetch("people", 123);

Example 4: fetch request with id 123

let request = fetch("requests", 123);

Example 4: fetch task with id 123

let task = fetch("tasks", 123);

Example 5: fetch a configuration item with id 1 from the active predefined filter

let activeCi = fetch("cis/active", 1);

fetchAll​

Fetch all elements of a module.

!IMPORTANT! Avoid this for mass data like requests, tasks, workflows, audit entries, ...

let results = fetchAll("module_name", [account]);

Example 1: get all workflow templates

let allWorkflowTemplates = fetchAll("workflow_templates");

for (let template of allWorkflowTemplates) {
  log("Template : ", template.subject);
}

Example 2: get all configuration items from the active predefined filter

let activeCis = fetchAll("cis/active");

fetchFilter​

Fetch data from Xurrent Module with URL filter.

let results = fetchFilter("module_name", filter_value, [account]);

Example 1: Filter workflow templates by subject

let filter = "subject=" + encodeURI("Standard Purchase without Approval");
let elements = fetchFilter("workflow_templates", filter);
for (let item of elements) {
  log("item", item);
}

Example 2: Filter configuration items in the active predefined filter by name

let activeCisNamedFoo = fetchFilter("cis/active", "name=foo");

import_csv​

Start import of csv data

import_csv(entity, csv_data, account_name, [uploaded_file_name]);

import_csv returns a token that can be checked with checkImportState.

In Xurrent the import state can be viewed in system logs - import state.

Example:

let account_name = "wdc";
let upload_csv = "Source,Source ID,Name,Disabled";
let upload_lines = [];

for (let x = 1; x < 20; x++) {
  upload_lines.push(`wdc-import,import_org_sourceID${x},import org name${x},1`);
}

upload_csv = upload_csv + "\n" + upload_lines.join("\n");

let result = import_csv("organizations", upload_csv, account_name, "uploaded.csv");
log("result", result);

let state_result = null;

for (let counter = 0; counter < 50; counter++) {
  state_result = checkImportState(result.token, account_name);

  log(`state result ${counter} : `, state_result);
  if (state_result.state == "done" || state_result.state == "error") {
    break;
  }
  sleep(2000);
}

let final_results = loadFileToString(state_result.logfile);

log("final_results", final_results);

initExport​

Export data from the platform.

initExport(data_type, account_name);

Example:

let account_name = "wdc";
let result = initExport("organizations", account_name);

let state_result = null;

for (let counter = 0; counter < 50; counter++) {
  state_result = checkExportState(result.token, account_name);

  log(`state result ${counter} : `, state_result);
  if (state_result.state == "done" || state_result.state == "error") {
    break;
  }
  sleep(2000);
}

let final_results = loadFileToString(state_result.url);

log("final_results", final_results);
let list = csvToObjectList(final_results);
log("list", list);

isUserTokenValidInAccount​

Checks if the user API token is valid in the given Xurrent account.

isUserTokenValidInAccount(token, account_name);

Link two modules in Xurrent.

link(from_module_name, from_element_id, to_module_name, to_element_id, [account]);

Example :

let workflowId = 172;
let requestId = 123;
link("workflows", workflowId, "requests", requestId);

mergeAudit​

Merges audit information into the given Xurrent object.

mergeAudit(xurrent_object);
mergeAudit(xurrent_object, audit_line_id);

This can be used for any Xurrent record type (request, workflow, task, ...) that has audit entries. This command adds audit_... attributes to the given Xurrent object:

  • obj.audit_id
  • obj.audit_user
  • obj.audit_action
  • obj.audit_created_at

In addition, for each field 5 additional attributes are added that contain audit information about the field:

  • obj.audit_is_changed_...: true if the field was changed
  • obj.audit_old_...: contains the value before the change
  • obj.audit_new_...: contains the value after the change
  • obj.audit_unchanged_...: contains a value ONLY if value is not changed
  • obj.audit_changed_...: contains a value ONLY if value is changed

E.g. for the request.status field following fields are added:

  • request.audit_is_changed_status
  • request.audit_old_status
  • request.audit_new_status
  • request.audit_unchanged_status
  • request.audit_changed_status

If the audit_line_id parameter is given, the audit information is taken from that specific audit entry.

Otherwise, if the given Xurrent object is the one that triggered the package execution via a webhook, then the audit information is taken from the audit line specified in the payload[audit_line_id] attribute of the [webhook payload](https://developer.xurrent.com/v1/webhooks/#webhook-contents.

Otherwise, the audit information is taken from the most recent audit entry of that Xurrent object.

Example :

const request = fetch("requests", 1234);
mergeAudit(request);
log("request", request);

update​

Update Xurrent objects.

let result = update(module_name, element_id, data, [account]);

Example 1:

let workflow_id = 173;

let result = update("workflows", workflow_id, {
  subject: "new subject text",
});

Example 2:

let request_id = 173;

let result = update("requests", request_id, {
  subject: "new subject text",
});

Example 3:

Create a PDF document and update request.

let request_id = 173;

let docDefinition = {
  content: "Very important document",
};

let pdfBuffer = create_pdf(docDefinition);

let pdfAttachment = {
  content: pdfBuffer,
  length: pdfBuffer.length,
  fileName: "Document.pdf",
};

update("requests", request_id, {
  note: "PDF Document upload",
  attachments: [pdfAttachment],
});

Example 4:

Create a PDF document and update custom field in request.

let request_id = 173;

let docDefinition = {
  content: "Very important document",
};

let pdfBuffer = create_pdf(docDefinition);

let pdfAttachment = {
  content: pdfBuffer,
  length: pdfBuffer.length,
  fileName: "Report.pdf",

  custom_field_id: "report",
};

update("requests", request_id, {
  note: "PDF Document upload",
  custom_fields_attachments: [pdfAttachment],
});

Example 5:

Save loaded attachment as note inline attachment

let uri = "https://www.path_to_png_image.png";

let att_buffer = loadFromUri(uri, "buffer");
let inline_file_name = "INLINE_FILE_NAME.png";

let inline_file_obj = {
  inline: true,
  filename: inline_file_name,
  content: att_buffer.content,
};

let note_text = `inline pic:\n![](${inline_file_name})\nAfter inline pic`;

let request_id = 1234567890;

update(
  "requests",
  request_id,
  {
    note: note_text,
    attachments: [inline_file],
  },
  account,
);

waitForPromise​

wait for a promise initiated by an exportPromise call

waitForPromise(promise);

Example:

let account_name = "wdc";
let promise = exportPromise("organizations", account_name);
let result = waitForPromise(promise);

log("result", result);
log("promise", promise);
log("promise.content", promise.content);