Skip to end of metadata
Go to start of metadata

Introduction

This page describes how to use NetSuite token-based authentication (TBA) by calling a RESTlet from a local file source in Jitterbit Harmony. Prior to configuring TBA in Jitterbit Harmony, see Jitterbit's recommendations for enabling TBA in NetSuite.

NOTE: Those using two-factor authentication (2FA or TFA) in NetSuite are required to use TBA with Jitterbit Harmony. Learn more in NetSuite 2018.2 Token-Based Authentication.

Calling a RESTlet from a local file source is one of several ways to use NetSuite TBA with Harmony. Other options include using the NetSuite Connector (recommended), calling a RESTlet from an HTTP source or target, or using a web service method:

While the NetSuite Connector is recommended, it may be preferred to call the RESTlet or use a web service method in some cases, such as for existing integrations that are already designed in this way, or where certain features are not available with the connector. No matter the method you use, authenticating using TBA is available in all of these. Note that the RESTlet method described on this page is available only with Private Agents.

To call a RESTlet to authenticate with NetSuite TBA using a local file source, these steps are recommended, as covered on this page:

  1. Associate the RunCommand Plugin
  2. Install Node.js
  3. Create the Node.js File
  4. Call the Node.js File in a Script
  5. Process the RESTlet Response
  6. Troubleshooting
TIP: For purposes of this documentation, the steps on this page correspond with the sample Jitterpak NS_Node_RESTlet_TBA (JPK).

Prerequisites

To use NetSuite TBA by calling a RESTlet from a local file source in Jitterbit Harmony, these criteria must be met:

  1. You must have the appropriate permissions role on your NetSuite account.
  2. You must be using SuiteTalk version 2015.2 or higher.
  3. You must have TBA enabled for your NetSuite account.

    TIP: For additional information, refer to the NetSuite documentation on Getting Started with Token-based Authentication (login to NetSuite required).

  4. You must be using a Jitterbit Harmony Private Agent (Linux or Windows) and have Node.js and npm installed (covered in the instructions below).

    WARNING: This method is not available for use with Cloud Agents, as it requires the use of local files and being able to run a command where the file is located.

Associate the RunCommand Plugin

The use of the RunCommand plugin is required in order to execute a Node.js file that will be created later. In order to use this plugin, you must first associate it with your Private Agent Group. This will make the plugin available on all Private Agents within the Private Agent Group.

To associate the plugin:

  1. Log in to the Harmony Portal and go to the Management Console. Then use the menu in the top left to navigate to Customizations > Plug-ins.
  2. In the table, locate the row "Jitterbit - Run Command." On the far right, use the Action dropdown to select Associate Agent Group.
  3. In the popup, select your Private Agent Group and click Save.
TIP: Detailed documentation on associating plugins is available in Customizations > Plug-ins.

Install Node.js

Node.js must be installed in order to run a file that will be created later to call the RESTlet from Jitterbit Harmony. The npm program, which is used to manage Node.js packages, is also required and is usually included with Node.js.

In this step, check whether Node.js and npm are installed on your Private Agent(s), and if they aren't, install them.

NOTE: Ubuntu 18.04 is used as an example below, although other supported Linux and Windows systems where your Private Agent(s) run may also be used.
  1. Check to see if Node.js is installed.

    $ node -v
  2. Check to see if npm is installed.

    $ npm -v
  3. If either command does not respond with a version, use these commands to install the application that is needed:

    $ sudo apt install nodejs
    $ sudo apt install npm
  4. Create a new directory that will be used later as the location of the NetSuite call and response. This can be changed to any desired location and will need to be provided later in your Jitterbit Harmony project.

    $ mkdir -p /opt/Jitterbit_projects/TBA_RESTlet/
  5. Navigate to the new directory.

    $ cd /opt/Jitterbit_projects/TBA_RESTlet/
  6. Install these required Node.js packages.

    $ npm install request
    $ npm install oauth-1.0a@1.0.1

Create the Node.js File

This is the file that you will need to call the RESTlet from Jitterbit Harmony.

In this step, create a new JavaScript outside of Jitterbit Harmony. To create a new file in Ubuntu 18.04, for example, using the name of the file used in the sample Jitterpak:

$ nano request.js

Inside the new JavaScript, paste the contents provided below. In the sample Jitterpak, the same contents are located in the script request.js for reference.

request.js
const request=require('request');
const OAuth=require('oauth-1.0a');
const fs=require('fs');

var args=process.argv;
var outputFile=args[2];

var accountID=args[3];
var token={
  public:args[6],
  secret:args[7]
};

var consumer={
  public:args[8],
  secret:args[9]
};

var restlet_url=args[4];

var oauth=OAuth({
  consumer:consumer,
  signature_method:'HMAC-SHA256',
  hash_function(base_string,key){
  return crypto.createHmac('sha256',key).update(base_string).digest('base64');
  }
});

var request_data={
  url:restlet_url,
  method:args[5],
};

var authorization=oauth.authorize(request_data,token);
var header=oauth.toHeader(authorization);
header.Authorization+=', realm="'+accountID+'"';
header['content-type']='application/json';

request({
  url:request_data.url,
  method:request_data.method,
  headers:header,
  json:{message:"this is the payload"}
},function(error,response,body){
  if(error){
    console.log(error);
  }else{
    console.log(body);
  }
  fs.writeFile(outputFile,body,function(err){
    if(err){return err;}
  });
});

Call the Node.js File in a Script

To use the Node.js file created in the previous step, set up a Jitterbit Script that sets TBA variables and calls the Node.js file using the RunCommand plugin.

  1. In Design Studio, create a new Jitterbit Script as a project item.
  2. Within the script, paste the contents below into the Jitterbit Script. In the sample Jitterpak, this script is named 01-Call_Node.js_File.

    NOTE: This script uses several project variables that are predefined in the sample Jitterpak to set the values needed for TBA and provide the local file location of the Node.js file and RESTlet response. Use these variables or provide values directly as obtained while enabling TBA in NetSuite
    01-Call_Node.js_File
    <trans>
    $nsAccountID=$NS_OrgID;
    $RESTletURL='https://'+$nsAccountID+'.restlets.api.netsuite.com/app/site/hosting/restlet.nl?script=999999&deploy=1';
    $httpMethod='GET';
    $tokenKey=$NS_tokenKey;
    $tokenSecret=$NS_tokenSecret;
    $consumerKey=$NS_consumerKey;
    $consumerSecret=$NS_consumerSecret;
    $nodeRESTletFile=$NS_RESTlet_Node_File;
    $nodeResponseFile=$NS_RESTlet_Node_Response;
    $Command='node';
    $Arguments=$nodeRESTletFile		    // arg[1]
               +" "+$nodeResponseFile	// arg[2]
               +" "+$nsAccountID		// arg[3]
               +" "+$RESTletURL		    // arg[4]
               +" "+$httpMethod		    // arg[5]
               +" "+$tokenKey			// arg[6]
               +" "+$tokenSecret		// arg[7]
               +" "+$consumerKey		// arg[8]
               +" "+$consumerSecret;	// arg[9]
    $response=RunPlugin("<TAG>plugin:http://www.jitterbit.com/plugins/pipeline/user/RunCommand</TAG>");
    if($response==1,
      WriteToOperationLog('success');
      RunOperation("<TAG>Operations/NS_Node_RESTlet_TBA/02-Process_RESTlet_Response</TAG>",true);
    );
    </trans>
  3. Create a script operation and place the Jitterbit Script within it. In the sample Jitterpak, the operation is called 01-Call_Node.js_File.
  4. To verify that you have successfully connected to NetSuite, test the operation to ensure you receive something back from the RESTlet.

Process the RESTlet Response

Now that the call to NetSuite is set up, you can then proceed with setting up the rest of your project using the response you receive back from the call.

  1. Create a local file source with the location on your Private Agent where you specified for the response to be written.
  2. Create a transformation operation that uses the local file source you just created containing the response from NetSuite. In the sample Jitterpak, the operation is called 02-Process_RESTlet_Response. The operation setup should look similar to that below.

  3. In the transformation, you can then use the NetSuite response however you would like, completing the mapping as usual. 

Troubleshooting

If the Node.js call does not appear to be working from Jitterbit Harmony, or if the files are not writing on the Agent, you may need to adjust the permissions of the folder with the NetSuite call and response. A simple test is to provide full access to everyone, and test the operation again. If that solves the problem you will need to adjust the directory permissions to allow the Jitterbit user/group access to read and write in the created folder.

If the RunCommand plugin returns errors, ensure that you have filled in all of the project variables with the necessary NetSuite information.

On This Page

Last updated:  Oct 26, 2018