NetSuite Integration Series: Part 1: Using User Event Scripts for real time integration using Integration Cloud

Introduction

Every time a customer is created in System X, it should trigger an integration which creates the customer in System Y as well.

 

This is a very common requirement, and different applications address it differently. For example, Oracle Sales Cloud (OSC) and E-Business Suite (EBS) provide business events; Commerce Cloud has WebHooks. You subscribe to these events or register a webhook and a message is received, which may be used to trigger an integration. In this article, I will demonstrate how the same can be achieved in NetSuite and Oracle Integration Cloud (OIC).

 

Note: To follow the post, basic knowledge of NetSuite, OIC, OSC and JavaScript will be helpful, but not necessary.

Detailed Article

The high level steps involved are:

 

  • Create an OIC Integration which exposes a REST endpoint, transforms the incoming request payload, and invokes OSC to create an Account.
  • Create a UserEvent SuiteScript which gets triggered after a customer record is committed in NetSuite database. It invokes the OIC REST endpoint and passes the necessary payload
  • Create a script record and associate it with the Customer. This sets the link between the customer save action and the script we created

Create an OIC Integration

In Integration Cloud, create a REST connection:

Search and Choose the REST adapter

01_ChoseRestAdapter

 

 

 

 

 

 

Provide a Name for the adapter and choose Role = Trigger. Click Create

02_NN_Customer_Rest_Connection

 

 

 

 

 

 

 

OIC shows a message confirming the connection was successfully created. Click Test to complete the creation flow.

03_NN_Customer_Rest_Connection_Test

 

 

 

OIC shows a message confirming the connection was successfully tested. Save and Close to come out of the Create Connection wizard.

04_NN_Customer_Rest_Connection_Test_Success

 

 

Similarly, create a connection to Oracle Sales Cloud. For details on the steps, please refer to this post.

 

Now, we will create an integration which will expose a REST Endpoint and will transform the data received from the REST endpoint to Oracle Sales Cloud format and invoke a createAccount operation to create an Account.

In the integrations page, click on create and select “Map Data” pattern. This pattern is useful for simple integrations. For complex integrations “Orchestration” pattern is usually more appropriate.

05_CreateNetSuiteToSalesCloudIntegration

 

 

 

 

 

 

Provide a Name for the integration and click Create

06_NameNetSuiteToSalesCloudIntegration

 

 

 

 

 

 

 

OIC shows a message confirming the integration was created. Search the REST connection we created earlier and drop it in the Trigger portion of the canvas.

07_NetSuiteToSalesCloudIntegration_DropTrigger

 

 

 

 

The “Configure Oracle REST Endpoint” wizard opens up. Provide a name for the endpoint. Also set the Relative Resource URI for the REST Endpoint. In this case, we set it to “/customer”. Set Action = POST and checkmark “Configure a Request Payload for this endpoint”.

08_NetSuiteToSalesCloudIntegration_ConfigureTrigger01

 

 

 

 

 

 

 

 

 

In the next screen, Under Select the request payload format, click JSON Sample. Select JSON for the type of payload. At this point, you can chose to upload a file containing sample JSON payload, or enter it inline in the wizard. Since this is a simple payload, you can click on inline

09_NetSuiteToSalesCloudIntegration_ConfigureTrigger02

 

 

 

 

 

 

 

 

In Request Sample Json Payload screen, enter a payload. This is the payload that this endpoint will expect and the fields become available for mapping in the ICS integration.

For this example we are using only a single mandatory field, Customer Name (in NetSuite) to OrganizationName (in OSC), so you can enter the following JSON payload:

{
     "customerName" : "customerName"
}

Only the field names matter as they are referenced in the mapping. The value can be entered arbitrarily.

10_NetSuiteToSalesCloudIntegration_ConfigureTrigger03

 

 

 

 

 

 

 

Click OK and Next to view the summary. Make sure the information is correct and click Done.

11_NetSuiteToSalesCloudIntegration_ConfigureTrigger04

 

 

 

 

 

 

Now that we have our triggered configured, we will configure the Target. Target of this integration is Oracle Sales Cloud. Search and Select the newly create OSC connection, and drop it under Invoke

12_NetSuiteToSalesCloudIntegration_DropSalesCloudInvoke

 

 

 

 

Provide an appropriate name for the endpoint.

13_NetSuiteToSalesCloudIntegration_ConfigureSalesCloudInvoke01

 

 

 

 

 

Make the following selections

Business Object = Account: Account Service

Operation = createAccount

14_NetSuiteToSalesCloudIntegration_ConfigureSalesCloudInvoke02

 

 

 

 

 

 

 

The next step is to create a mapping which transforms the incoming payload into an OSC payload. Click on “Click Below to Create Map” and then add a mapping by clicking on the “+” icon

15_NetSuiteToSalesCloudIntegration_CreateMap

 

 

 

 

The mapping editor opens. Drag the customerName field from Source to OrganizationName field on the target. For address, we will use hard-coded values.

16_NetSuiteToSalesCloudIntegration_Mappings

 

 

 

The next step is to add a tracking field. Use the only available field customerName and save the integration.

17_NetSuiteToSalesCloudIntegration_Tracking

 

 

 

 

Now our integration is complete and is ready to be activated. Click on the toggle to open Activate Integration dialog.

18_NetSuiteToSalesCloudIntegration_ActivateIntegration

 

 

In the activation dialog you can select Tracing options. For development, you can turn on the tracing options. However, enabling these options has a detrimental effect on performance, so chose them wisely in production.

19_NetSuiteToSalesCloudIntegration_ActivateIntegration02

 

 

 

 

 

 

 

 

Once the integration is activated the toggle turns green. Click on the “i” icon to get the endpoint URL.

20_NetSuiteToSalesCloudIntegration_EndPointURL

 

 

 

 

The endpoint URL points to the REST metadata resource which provides information about the REST endpoint. To invoke the REST endpoint, we will replace the metadata resource with “/customer” resource we had used during the configuration of the REST adapter.

Create a UserEvent SuiteScript:

Now let’s create a UserEvent script using SuiteScript which will invoke this integration and pass the required payload.

 

Here is a sample I used for this blog. I named this file sdr_ue_customer.js by following the convention:

sdr = my company acronym

ue = type of script, i.e., UserEvent

customer = name of the entity

/**
 * @NScriptType UserEventScript
 * @NAPIVersion 2.0 
 */
define(['N/https'],function(https) {
    
	return {
    	
    	// This function is called after the record 
    	// is committed in the database
        afterSubmit: function(context) {
        	
        	// Check if this event is for a new record
        	if (context.type == context.UserEventType.CREATE) {
        		var customer = context.newRecord;
        		var myCustomer = {};
        		
        		// Create the object which will be the payload. 
        		// In this example, only a single field is being copied 
        		myCustomer.customerName = customer.getField('companyname');
        		
        		// This is the ICS URL
        		var url = 'h<a href="https://&lt;ICS_Hostname&gt;/integration/flowapi/rest/CUSTOMERCREATENETSUITETOSALESCLO/v01/">ttps://&lt;ICS_Hostname&gt;/integration/flowapi/rest/CUSTOMERCREATENETSUITETOSALESCLO/v01/</a>customer';
        		
        		var myRequest = {};
        		
        		//Set up the required headers
        		myRequest.headers = {};
        		myRequest.headers["Authorization"] = 'Basic bmF2ZWVuLm5haGF0YUBvcmFjbGUuY29tOkF0ZWFtMTIzIw==';
        		myRequest.headers["Content-Type"] = 'application/json';
        		
        		// Configure the request URL and HTTP method
        		myRequest.method = "POST";
        		myRequest.url = url;
        		
        		//Set the request body. 
        		myRequest.body = JSON.stringify(myCustomer);
        		
        		// Invoke the ICS integration
        		var myResponse = https.post(myRequest);
        		log.debug('Response Code', myResponse.code);
        	
        	}
        }
    };  
    
});

The first 2 annotation specify this is a UserEventScript and it is using SuiteScript version 2.0.

The next line is a define block which returns an object with various handlers. Each script type has various handlers. We will return only the afterSubmit handler which is a function which will get executed after the record is committed to the database and a context object is passed to this function which contains the necessary details. In this function, we will use the newRecord property of the context object to get customer details; construct a payload based on the new record; configure an HTTPS request; and use the https module to invoke the ICS integration.

Create a Script Record:

Next step is to upload this file to the file cabinet. If you have eclipse and have configured it for NetSuite using the add-on, then you can simply right click and upload the file to NetSuite. In this example, we’ll do this manually. Login to NetSuite and navigate to Documents -> Files -> SuiteScripts

21_UploadSuiteScript01

 

 

 

 

Now, you can upload the file by clicking on Add File. As a best practice, you should upload files into various folders for ease of maintenance. You can create a folder by clicking on New Folder. I created a SuiteDreams folder for my files.

22_UploadSuiteScript02

 

 

 

Now we will create a script record. Navigate to Customization -> Scripting -> Scripts -> New.

23_CreateScriptRecord01

 

 

 

 

 

 

Choose the file we just uploaded and click Create Script Record

24_CreateScriptRecord

 

 

 

 

 

 

Provide the following information:

Main Section:

NAME = SuiteDreams UE Customer (A user friendly name of your choice)

ID = _sdr_ue_customer (it should start with an underscore to separate it from the prefix that NetSuite will automatically assign to this record)

DESCRIPTION = <A meaningful description>

Deployments SubTab:

APPLIES TO = Customer (the entity on which this script will be attached)

ID = _sdr_ue_customer (it should start with an underscore to separate it from the prefix that NetSuite will automatically assign to this record)

STATUS = Testing (This ensures that the script only gets triggered by the current user)

Click Save

 

25_CreateScriptRecord03

 

 

 

 

 

In the next screen, see the checkbox “AFTER SUBMIT FUNCTION” is automatically checked. This happened because the script had an afterSubmit handler.

26_CreateScriptRecord04

 

 

 

 

 

This completes the setup. Now when a new customer is created and saved in the database, NetSuite will trigger the afterSubmit function and pass it the script context, which contains the customer record. The script will parse the record, construct a payload and POST a message to the ICS endpoint. ICS will received the message, transform it to an OSC payload and create an account in OSC.

Create a new customer and Save the record

27_NetSuiteToSalesCloudIntegration_Test01

 

 

 

 

 

 

 

Go to Integration Cloud -> Monitoring -> Tracking. You will see an instance of the integration getting initiated.

28_NetSuiteToSalesCloudIntegration_Test02

 

 

Go to Sales Cloud, and you will see an account created there.

29_NetSuiteToSalesCloudIntegration_Test03

 

 

 

 

Voila! We can see the fruit of our labor!

Add Your Comment