Integration Hub – API Customization

Scripts can now be used to retrieve files on an SFTP server, process the files and import the data. 

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.

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.
  • 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.

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. Enable the job by clicking the Enable toggle switch until it is blue and On.
    4. Type a Description.
    5. 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.
    6. 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.
    7. Download the script by clicking on the download button on the right of the script name. 
    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 Save & Close.
  3. Delete a job:
    1. Click the job’s Action menu (three horizontal dots)
    2. Select Delete.

Supported Modules

Only the following supported modules can be used:

New modules have been added: fs (for manipulating files), ssh2 (for manipulating files on external servers), and xlsx (for manipulating Microsoft Excel files).

const https = require("https");
const http = require("http");
const xlsx = require("xlsx");
const fs = require("fs");
const ssh2 = require('ssh2');
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

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:

Var = LastRunDate

let run = function (args) {

LastRunDate = args.lastRunDateUtc;
//code
//code
}

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’);

Things to Avoid

Do not use While loops.

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

 

Back to the top arrow

Was this article helpful?

4 found this helpful.