SuiteScript hooks overview

What are hooks and how are they used in a flow?

A flow in integrator.io is mainly composed of sources and destinations. One type of source, an export, fetches data from the source applications, then breaks it into smaller pages before passing it in to the next step in the flow, such as an import. Imports process the pages coming in, then send the data into the target system. Exports and imports have different types of hooks, each of which contain a request and response contract that must be used while implementing the hook.

Hooks are custom code (functions) that can run at different stages during the execution of a flow to modify the behavior of export and import processes. You can think of them as events from integrator.io that are consumed during the flow to allow custom processing. You can use a hook to run a stack or script in integrator.io, or you can use a SuiteScript hook.

What are SuiteScript hooks and what SuiteScript versions are supported?

SuiteScript hooks are special hooks that can run within NetSuite on a RESTlet. They can leverage the full capabilities of SuiteScript for both imports and exports. SuiteScript hooks generally share the same contract as integrator.io hooks, mentioned here. 

Can I use both a SuiteScript hook and an integrator.io script-based hook?

Yes, you can use both of these hooks in conjunction.

What SuiteScript versions are supported?

Currently, integrator.io supports and recommends hooks to be written in SuiteScript 2.0 because this is the latest SuiteScript major version. While integrator.io also supports SuiteScript 1.0, Netsuite is not making any updates to SuiteScript 1.0 and has recommended moving to SuiteScript 2.0. Note that your export, import, and hook should use the same SuiteScript version in flows. So check your export or import and write your hook using the appropriate NetSuite version.

How do I create a SuiteScript hook?

To configure a SuiteScript, you can create a script file in the NetSuite file cabinet.

1. Click the hook icon on your export or import.
2. In the Hooks panel, choose Script (unless you are using a Stack)
3. In the SuiteScript Hooks section, provide the Function and the File Internal ID for the SuiteScript hook you are linking to.

   /* Example of a preSend function using SuiteScript 2.0
   
   define(["N/search"],
       function (NSearch) {
   
           var preSendFunction = function (options) {
               _.each(options.data, function (salesOrder, index) {
                   var lookupfieldValue = NSearch.lookupFields({
                       type: 'customer',
                       id: salesOrder.entity.internalid,
                       columns: 'email'
                   });
                   salesOrder.customerEmail = lookupfieldValue['email']
               })
   
               return {
                   data: options.data,
                   errors: options.errors
               }
           }
   
           return {
               preSendFunction: preSendFunction
           }
       });
   

What types of SuiteScript hooks are there?

Exports

There is only one NetSuite SuiteScript hook in integrator.io for exports, the preSend hook. It's available for both types of NetSuite exports, including Scheduled (batch exports based on a Saved Search) and RealTime (single record export sent when triggered). 

preSend

This hook executes after the data is collected, before being sent from NetSuite to integrator.io for each page. It is similar to preSavePage hooks with the same contract. integrator.io-based preSavePage hooks are triggered after the preSend hook.

A user can use this hook in various ways, such as:

• Attaching more data by running searches in NetSuite via SuiteScript 
• Modifying/creating NetSuite records before they are exported

Imports

There are three hook types available for NetSuite imports: preMap, postMap, and postSubmit. The contract of these hooks are exactly the same as the integrator.io-based hooks. Mappings for NetSuite imports happen inside NetSuite for better performance, thus the integrator.io postMap hook is not available for NetSuite. 

What order are the SuiteScript hooks for imports run in?

SuiteScript hooks for imports are run in the following order: preMap (integrator.io) > preMap (NetSuite) > postMap (NetSuite) > postSubmit (NetSuite) > postSubmit (integrator.io)

What are best practices for writing SuiteScript hooks?

Governance and time limits

SuiteScript hooks run on RESTlets, so they follow the same NetSuite governance limits. This governance is shared with the integrator.io execution as well, so make sure that you plan how many governance points (the number of API operations allowed) your hooks will consume.

What should I do

• If an Import hook is invoked with one record, a NetSuite RESTlet has 5000 governance points, integrator.io will also consume points for all the lookups and creating/submitting the record in NetSuite 
• If you are running out of points, try adjusting your flow a bit. For example, if you have complicated logic for your NetSuite import and your hooks are consuming a lot of points, you can reduce the pageSize of the corresponding export to have less data passed to the hook for each page.
• In addition to the limits NetSuite puts on points (number of API operations allowed), it also puts a limit on execution time. There is a 5 minute time limit for a RESTlet, so while writing a hook, make sure that all the processing in your hooks is completed within the time limit.

What JavaScript libraries can I use?

integrator.io allows you to attach a single file for a hook. You can build common libraries and build closures into a single file to share common utils across hooks. To make it easier to write clean code, the Underscore.js javascript library is available when the hooks are invoked in NetSuite.

Where can I view logs for my SuiteScript hook?

To view your logs, go to to Customization>Scripting>Scripts, then search for the RESTlet name: Celigo Realtime Import Restlet Runner (type Restlet to bring it up faster).