How to call a NetSuite RESTlet web service

Document created by Adam Arrowsmith Employee on May 24, 2016Last modified by Adam Arrowsmith Employee on Oct 21, 2016
Version 4Show Document
  • View in full screen mode

This article describes how to call a NetSuite RESTlet web service using the HTTP Client Connector.

 

 

Use Case

NetSuite RESTlets allow you to develop custom RESTful web services from your NetSuite account developed using SuiteScript. RESTlets are an alternative to the standard SuiteTalk SOAP-based APIs. They use JSON payloads and can be used to create services optimized for specific use case such as an item inventory lookup or account balance query without the overhead of retrieving the entire record. The also provide an opportunity to execute logic such as multiple lookups/actions on the server side vs. making multiple round trip calls from AtomSphere.

 

Connecting to RESTlets uses the generic HTTP Client Connector, not the NetSuite Connector. RESTlets can GET, POST, PUT, and DELETE data with NetSuite. The examples used below only use GET and POST methods.

 

You can authenticate to RESTlets via Token Based Authentication (TBA) or NLAuth. TBA is the authentication approach recommended by NetSuite since the 2015.2 release.

 

This article focuses on the AtomSphere process and HTTP Client Connector configuration required and considerations for invoking RESTlets. It does not intend to provide RESTlet design or SuiteScripting guidance. For more details on developing RESTlets and working with SuiteScript, please visit the NetSuite Help Center.

 

 

Approach

Creating RESTlets requires SuiteScript development skills and a strong understanding of the NetSuite data model as well as your NetSuite account's configuration and customizations.

 

  1. Develop the SuiteScript for the RESTlet service and load the file into NetSuite.
  2. Create a Script record referencing the file and defining the HTTP methods that correspond to the JavaScript functions.
  3. Deploy the Script record (NetSuite).
  4. Determine whether you will use Token Based Authentication or NLAuth. If TBA, create the necessary Integration application and Access Token in NetSuite.
  5. Use the HTTP Client Connector and parameterize the connection and operation parameters use for any RESTlet script.

 

Implementation

 

RESTlet Script

Below is a trivial "Hello world" RESTlet script that provides functions to retrieve a single record and create a single record. This is borrowed from the examples provided in the NetSuite Help Center.

 

  1. Develop the SuiteScript file.
  2. Save on your local computer.

 

Example RESTlet script:

function helloWorld(datain)
{
    return 'Greetings DemoUser from NetSuite RESTlet Land!';
}

function getRecord(datain)
{
    nlapiLogExecution('DEBUG','recordtype='+datain.recordtype);
    nlapiLogExecution('DEBUG','id='+datain.id);


    return nlapiLoadRecord(datain.recordtype, datain.id); // e.g recordtype="customer", id="769"
}

// Create a standard NetSuite record
function createRecord(datain)
{
    var err = new Object();
  
    // Validate if mandatory record type is set in the request
    if (!datain.recordtype)
    {
        err.status = "failed";
        err.message= "missing recordtype";
        return err;
    }
  
    var record = nlapiCreateRecord(datain.recordtype);
  
    for (var fieldname in datain)
    {
     if (datain.hasOwnProperty(fieldname))
     {
         if (fieldname != 'recordtype' && fieldname != 'id')
         {
             var value = datain[fieldname];
             if (value && typeof value != 'object') // ignore other type of parameters
             {
                 record.setFieldValue(fieldname, value);
             }
         }
     }
    }
    var recordId = nlapiSubmitRecord(record);
    nlapiLogExecution('DEBUG','id='+recordId);
  
    var nlobj = nlapiLoadRecord(datain.recordtype,recordId);
    return nlobj;
}

 

NetSuite RESTlet Configuration

  1. You must enable Client SuiteScript, Server SuiteScript, and Web Services in your NetSuite account. Go to Setup > Company > Enable Features > SuiteCloud.
  2. Create a new Script and upload the script file created above. Go to Customization > Scripting > Scripts > New.
  3. Select RESTlet as the Script Type then enter a Name, select the Script File, and copy-paste the script's function name for the Get Function and Post Function names. In this example, getRecord and createRecord, respectively. Click Save.
    • IMPORTANT Note the newly created script internal ID in the URL. You will need this for the connector configuration.
  4. Click Deploy Script.
  5. Choose Status=Testing or Released and Log Level. Under the Audience subtab select the Role(s) that should be allowed to call this script. You should coordinate this with the roles you've associated with web services users. Click Save.
  6. IMPORTANT On the confirmation screen note the External URL value. The base URL and script and deploy querystring parameters will be used in the connector configuration.

 

HTTP Client Connector Configuration

The idea is to create a generic HTTP Client connection and operation components that is parameterized and reused for any RESTlet script.

 

Using Token Based Authentication

  1. Create a new HTTP Client Connection with the following configuration.
    • URL = Base URL from External URL in the Script Deployment above. For example, https://rest.na1.netsuite.com/app/site/hosting. The remainder of the URL path will be constructed in the Operation component.
    • Authentication Type = OAuth. Obtain the Consumer Key, Consumer Secret, Access Token, and Token Secret following these instructions.
    • Realm = NetSuite Account ID (Setup > Integration > Web Services Preferences).
  2. Create a new HTTP Client Operation with the following configuration.
    • Connector Action = Get or Send depending on the nature of desired action
    • Request and Response Profiles = leave blank because this operation will be reused for any record type
    • Content Type = application/json
    • HTTP Method = GET for retrieving single records; POST for all other actions including queries
    • Request Headers:
      • Content-Type = application/json (GET operation only)
    • Resource Path - Concatenate the remaining pieces of the External URL in the Script Deployment above. Use replacement variables for for the script ID, deployment ID, and querystring parameters to allow the values to be specified using dynamic document properties within the process. Note the replacement variable names used here are arbitrary.

 

Using NLAuth Authentication

  1. Create a new HTTP Client Connection with the following configuration.
    • URL = Base URL from External URL in the Script Deployment above. For example, https://rest.na1.netsuite.com/app/site/hosting. The remainder of the URL path will be constructed in the Operation component.
    • Authentication Type = None (this will be specified in the operation)
  2. Create a new HTTP Client Operation with the following configuration.
    • Connector Action = Get or Send depending on the nature of desired action
    • Request and Response Profiles = leave blank because this operation will be reused for any record type
    • Content Type = application/json
    • HTTP Method = GET for retrieving single records; POST for all other actions including queries
    • Request Headers - Use replacement variable for Authorization to allow the value to be specified using dynamic document properties within the process.
      • Authorization = leave blank, Is replacement variable=true
      • Content-Type = application/json (GET operation only)
    • Resource Path - Concatenate the remaining pieces of the External URL in the Script Deployment above. Use replacement variables for for the script ID, deployment ID, and querystring parameters to allow the values to be specified using dynamic document properties within the process. Note the replacement variable names used here are arbitrary.

     

    Process Configuration

     

    To call the getRecord RESTlet

     

     

        1. Start shape - No Data.
        2. Set Properties shape to set dynamic document properties for the specific RESTlet parameters defined as replacement variables in the HTTP Client operation. Note the property names must match exactly. Obtain the script and deploy IDs from the NetSuite Deployment record above.
          1. HTTP_PATH_SCRIPT_ID = 54
          2. HTTP_PATH_DEPLOY_ID = 7
          3. HTTP_PATH_PARAMS = &recordtype=invoice&id=305 (the parameters will vary depending on your RESTlet's design)
        3. If using TBA, skip this step. Otherwise if using NLAuth, use a second Set Properties shape to set a dynamic document property for the common NLAuth header defined as replacement variable in the HTTP Client operation. Using a second shape more easily allows for reuse with different scripts. Again the property name must match exactly. Obtain the NetSuite account, user, and password from your NetSuite account.
        4. HTTP Client Connector shape. Select the connection and GET operation created above. IMPORTANT Do NOT configure values on Connector shape Parameters tab!
        5. Inspect and handle the connector response as desired. If the operation is configured with Return HTTP Errors=false, the connector will automatically detect technical/connection failures. However you will likely need to inspect the response to check for functional success according to the design of your RESTlet's response.

     

    To call the createRecord RESTlet

     

     

        1. Prepare the request JSON as needed, typically using a Map shape.
        2. Set Properties shape for the RESTlet parameters, same as for the GET above. Note that because it is a POST call there will likely not be a HTTP_PATH_PARAMS property (however this can vary based on your RESTlet design).
        3. Similar to the GET example above, if using TBA, skip this step. Otherwise use a second Set Properties shape for the NLAuth header.
        4. HTTP Client Connector shape with the same connection and POST operation created above. IMPORTANT Again do NOT configure values on Connector shape Parameters tab!
        5. Inspect and handle the connector response as desired, same as above. Note that upon creating or updating a new record, it is common design practice for the RESTlet to return the newly created/updated record ID.

     

    Usage Considerations

      • To facilitate re-usability, consider putting the NLAuth Set Properties, connector call, and response handling shapes in a subprocess (data passthrough).
      • To facilitate maintenance consider setting the NLAuth values (account number, user, and password) and script and deploy IDs with a Process Property component that can be extended and configured per environment without having to modify and redeploy the underlying process.
      • During initial development, execute the process once with known criteria and capture the JSON response. Save this example file and use to import a new JSON Profile for mapping, etc.
      • It is possible to develop a generic "create record" RESTlet that can create any type of record.
      • To view RESTlet execution logs, go to the Deployment record. You will NOT use the SuiteTalk Web Services Usage Logs. Visit the NetSuite Help Center for more information on debugging and monitoring RESTlet executions.
      • RESTlet calls are governed by the same API limits as SuiteTalk calls with respect to concurrency and request rates. You still must obtain a SuiteCloud Plus license from NetSuite to make more than one call at a time for a given Integration application.
    3 people found this helpful

    Attachments

      Outcomes