Integration Hub – API Customization

Integration Hub – API Customization supports API-to-API and file-to-API integration using NodeJS scripts. Administrators can establish customized integration layers between their existing systems like Jira, Clarity, TFS, and Plutora, by uploading and scheduling scripts containing business rules for mapping fields and entity relationships.

Developers should see Use Cases And Sample Scripts For Integration Hub – API Customization.

*NEW* Seven more NPMs have been added.

Integration Hub – API Customization Grid View

The Integration Hub – API Customization grid displays the list of jobs, including the Job Name, Schedule, the last time it was run, and when it is due to run next.

The grid should refresh every minute. Click the refresh button (circled in the screenshot below) to make it refresh immediately.

Next Run messages mean:

  • A future time, such as In a few seconds: The scheduled job is about to run.
  • Running: Script is currently running.
    While a script is running, it can be stopped by clicking the Stop button.
  • Overdue: Something is blocking the script from running.
  • Paused: Script has been disabled using the Enable toggle switch.

Click View in the History column to open the script execution history pop up for that job, which contains information about every time the script has run.

Click View in the pop up to open the log file of that run.

Log files open in a new browser tab when clicked. If no log file tab opens, check whether you have pop up blocking software blocking them.

Scripts that have been stopped by clicking the Stop button will have Job process was terminated in their log file.

 

Manage Integration Hub – API Customization

Manage Integration Hub – API Customization:

  1. Go to Settings > Customization > Integration Hub – API.
  2. Add or edit a script:
    1. Add: Click + New.

      Edit: Click a script’s Job Name in the grid.
    2. Type Job Name. (Mandatory field.)
    3. Type a Description.
    4. Manage Parameters:
      Parameters allow easy configuration via the UI. Parameters can also be masked for security. See below in Script Syntax for how to reference parameters in a script.

      1. Click + parameters.
      2. Add or edit a parameter:
        1. Add: Click + new parameter.
          Edit: Click any field on an existing parameter.
        2. Type the Parameter Name.
        3. Click to select the Type of string:
          1. String: Shows the Value field.
          2. String (Masked): Masks the Value field with a dot for each character. Similar to a password field.
            Once String (Masked) has been selected and saved on a parameter, the value will never be displayed again. A masked parameter cannot be reverted to an unmasked parameter.
        4. Type the Values. This could be a password or clientID.
      3. Delete a parameter:
        1. Hover your mouse cursor over the parameter.
        2. Click the red X.
      4. Click Save & Close.
    5. Upload your script: (Mandatory field.)
      1. Click Upload New File.
        Maximum script duration is 30 minutes.
      2. Select the script. Only .js files can be used.
      3. Click Open.
        There is currently no way to edit a script. You must upload a new script (with a different name) instead.
    6. Download the script by clicking on the download button on the right of the script name. 
    7. Enable the job by clicking the Enable toggle switch until it is blue and On.
    8. Schedule the script:
      1. Select a Frequency: (Mandatory field.)
        1. Minute:
          1. Select the number of minutes from When. Minimum is five minutes. (Mandatory field.)
          2. Select the Start on date by clicking the calendar button. (Mandatory field.)
          3. Click Time to adjust the time.
        2. Hourly:
          1. Select the number of hours from When. (Mandatory field.)
          2. Select the Start on date by clicking the calendar button. (Mandatory field.)
          3. Click Time to adjust the time.
        3. Weekly:
          1. Select a day of the week from When. (Mandatory field.)
          2. Select the Start on date by clicking the calendar button. (Mandatory field.)
          3. Click Time to adjust the time.
        4. Monthly:
          1. Select the day of the month from When. (Mandatory field.)
          2. Select the Start on date by clicking the calendar button. (Mandatory field.)
          3. Click Time to adjust the time.
    9. Click:
      • Run & Close: To immediately run the script and close the pop up.
      • Save: To save but not close the pop up.
      • Save & Close: To save and close the pop up and let the script run (if it is enabled) when it is scheduled.
  3. Delete a job:
    1. Click the job’s Action menu (three horizontal dots)
    2. Select Delete.

 

Script Syntax

Supported Modules

*NEW* Seven more NPMs have been added.

Only the following supported NPMs can be used:

const AWS = require('aws-sdk');
const lodash = require("lodash");
const xml2js = require("xml2js");
const https = require("https");
const http = require("http");
const xlsx = require("xlsx");
const fs = require("fs");
const ssh2 = require('ssh2');
const csv = require('csvtojson');
const uuidv1 = require('uuid/v1');
const uuidv3 = require('uuid/v3');
const uuidv4 = require('uuid/v4');
const uuidv5 = require('uuid/v5');
const oauth = require('oauth');
var querystring = require('querystring');

More modules will be added in the future.

Running Node Scripts

To execute NodeJS scripts on the platform, wrap the run command in a module.exports

module.exports = {
run: run
};

Use a Promise

The exported run function must return a promise and can be async.

let run = function(){ 
return new Promise(function (resolve, reject) {

/// Code here

});

}

Use Parameters

Users can define parameters in the UI that can be referred to in the script. Parameters are passed into the main function in an object called arguments. The parameter names defined in the UI must exactly match your script and are case sensitive.

You can reference each parameter as follows, by first defining them as blank values in a variable, then reference them in the main run function:

let apiUrl = '';

var credentials = {
oauthUrl: '',
clientId: '',
clientSecret: '',
username: '',
password: ''
}

let run = function (args) {
credentials = {
oauthurl: args.arguments.oauthUrl,
clientId: args.arguments.clientId,
clientSecret: args.arguments.clientSecret,
username: args.arguments.username,
password: args.arguments.password
}
apiUrl = args.arguments.apiUrl;

The Date and Time of the Last Execution

If your job fails mid-execution, you may lose data. The new argument, LastSuccessfulRun, allows you to go back to the last time your job executed correctly and get data from that time.

The date and time of the last execution is always included in the args object. You can retrieve this value using the following code, in order to find the updates since the last run:

let run = function (args) {

    var LastRunDate = args.lastRunDateUtc;
    var LastSuccessfulRun = args.lastSuccessfulRunDateUtc;

}

Logging and Error Handling

Log files can be made more meaningful by using the following commands to label logs as warnings, errors, and so on.

Command Log Output Prefix
console.log(…args); [LOG]
console.info(…args); [INFO]
console.warn(…args); [WARN]
console.error(…args); [ERROR]
console.dir(…args); [DIR]
console.trace(…args);  [TRACE]

Log Format: [{DateTime}] [{Prefix}] – {args}

Example: [2018-07-10T02:46:01.798Z] [LOG] – Logging at interval: 1

 

Resolve and Reject

Failing a Job

To fail a job, the promise returned from the run function job should be rejected.

promise.reject(‘this is the fail message’);

Completing a Job

To complete a job, the promise returned from the run function job should be resolved.

promise.resolve(‘this is the success message’);

Reduce Data Loss

The argument, args.lastSuccessfulRunDateUtc, can reduce the chance of data loss by allowing scripts to go back to the last time they ran successfully.

 

Things to Avoid

Do not use While loops.

To avoid blocking calls, opt for async tasks when possible.

 

 

Back to the top arrow

Be the first to find out about new features. Subscribe to the Release Notes email. Subscribe Now

Was this article helpful?

4 found this helpful.