Oracle NetSuite Integration Guide

Audience

This document is directed to customers and prospective customers interested in using Tenfold in an Oracle NetSuite environment. Those who will perform the procedures described in this guide should have a basic level of familiarity with NetSuite APIs, NetSuite administration, general networking, and Tenfold.

Goals

The goal of this document is to provide knowledge, reference, and procedural information necessary to configure a proposed NetSuite/Tenfold integration.

This document is NOT intended as a specific system or network design document. If further clarification is needed, consult with your Tenfold Customer Success Manager (CSM) and/or Tenfold Support Engineer (TSE).

Terminology

To ensure a common frame of reference, this guide uses the following terms in conjunction with this NetSuite integration:

• Application Programming Interface (API): A set of clearly defined methods of communication used by Tenfold for reading and writing data.
• RESTlet: NetSuite scripts that interact with HTTP data following representational state transfer principles. RESTlets extend the SuiteScript API to allow Tenfold to integrate with NetSuite and improve performance.
• Tenfold Cloud: A set of Web Services that receives events from the telephony system and takes further action such as querying and saving to the CRM.
• Tenfold API User: This is the Tenfold Dedicated NetSuite Employee we create in the steps of this Implementation to interact with the Tenfold Cloud.
• Tenfold User Interface (UI): The Tenfold Product/Application Agents will be using. There are Chrome Browser and Desktop versions that can be used with the NetSuite Integration.
• Role: A defined access configuration that can be assigned to users/employees. This is the first thing we will create in Implementation and will set the permissions our Tenfold API user needs in order to interact with any of the NetSuite Entities or Records the Tenfold User Interface will be working with.
• Web Service Preferences: (Also known as SOAP Web Services) An object access protocol we can use to link the Tenfold API User and Role to its respective Role ID and Account ID. We suggest dedicating a Role and Employee to the Tenfold Integration as using a regular Admin User will complicate concurrency calls, notifications, and deliver excessive permissions that Tenfold may not need.
• OAuth: (Also known as Token Based Authentication) This is a way to connect NetSuite and Tenfold with an access token that is refreshed using a Client ID and Secret. This is preferred so no sensitive access data like login credentials need to be used.

Customer responsibilities

You are responsible for supplying connectivity to NetSuite, and for obtaining and loading any licensing required by NetSuite. You are also responsible for configuring NetSuite to support the Tenfold integration. Responsibilities for NetSuite management include, but are not limited to: Maintaining a customized Role and dedicated Employee/User in NetSuite with the minimum amount of permissions required to interact with NetSuite Objects outlined in your contract, sustaining a Web Service ID committed to the mentioned Role & Employee, also maintaining the RESTlet script deployments.

Integration overview

NetSuite requirements

Connection

• Accessible via TCP port 443 (https) to Tenfold Cloud
• Dedicated Service Account (i.e. API User)

Required version

NetSuite 2020.1 or higher

Other considerations

If using a highly custom built release of NetSuite, please consult with Tenfold to understand supportability.

Installation and configuration steps summary

1. Make the NetSuite role.
2. Make the NetSuite employee.
3. Make the Web Service Preferences RoleID for both.
4. Install and deploy the Tenfold RESTlets.
5. Integrate with the Tenfold Dashboard using employee credentials.
6. Create the OAuth integration client.
7. Integrate with the Tenfold Dashboard with token-based authentication.

Installation requirements

* More information on obtaining your Account ID and Role ID can be found at:

https://jcurvesolutions1.zendesk.com/hc/en-us/articles/209987966-Finding-your-NetSuite-Account-Number

https://searchspring.zendesk.com/hc/en-us/articles/201185029-Where-do-I-find-my-NetSuite-account-Role-ID-

Installation process

Step 1: Provision an integration user in NetSuite for API Connection

This section provides the procedural steps to set up token-based authentication in NetSuite to provide a secure connection from Tenfold to NetSuite.

• Enable Token-Based Authentication in the account. Go to Setup > Company > Enable Features and then navigate to the SuiteCloud subtab. Enable the required features as shown:

• Create a designated integration user (Setup > Users/Roles > Users > New) named "Tenfold Integration".
• Create an integration record. An integration record is required for authentication before it can connect with a token. A new integration should be used. Create it by navigating to Setup > Integration > Manage Integrations > New and complete the following:
  • Set the name to "Tenfold Integration" and select Token-Based Authentication. If you already have an integration record for Tenfold Integration, you can reuse it by editing the integration and selecting Token-Based Authentication.
  • Copy the Consumer Key and Consumer secret values. You will use these later in the user role configuration. 
    • Important: The Consumer Key and Consumer Secret values display only once, so it is very important that you copy them before going to another page.

• Set up the role. Token-based authentication is a per-user authentication and requires certain permissions in NetSuite. You can use an existing role or create a new role. 
  • Access Token Management: Users with this permission can create, assign, and manage tokens for any user in the company. Users with this permission cannot use token-based authentication to log in to the NetSuite UI.
  • Login using Access Tokens: Users with this permission can manage their own tokens using the Manage Access Tokens link in the Settings portlet, and they can log in using a token.
  • User Access Tokens: Users with only this permission can log in using a token, that is, they can use tokens to call a RESTlet, but cannot manage tokens or access pages where tokens are managed.

Permissions requirements

The NetSuite Role that is provisioned for the integration user will require access to specific Lists in NetSuite to ensure a working solution, and that specific actions can be taken via the different series of API calls. The following Lists should be provided “FULL” access to the provisioned role.

NOTE: if delete access is problematic from a security standpoint you should be able to utilize “EDIT” access instead for the Role and Employee Permissions.

Lists

• Accounts†
• Contacts*
• Cases†
• Companies*
• Customers*
• Phone Calls*
• Tasks*
• Employees*
• Employee Record*
• Perform Search*

Transactions

• Find Transaction*
• Opportunity*
• Quote†
• Estimate†

Setup

• SOAP Web Services†
• REST Web Services†
• User Access Tokens†

*Always required

†Usually required, but can depend on Netsuite configuration

Step 2: Create an Access Token for the Integration record, User, and Role

With the integration record created and proper role assigned, a token can be created for authentication.

To create a token:

1. Log in as the integration user with the token authentication role.
2. Click the Manage Access Tokens link available on the home dashboard under Settings, or go to Setup > Users/Roles > Access Token > New.

After completing the above steps, you can use the Consumer Key, Consumer Secret, Token ID, and Token Secret in the Tenfold Dashboard to setup your CRM Connection.

Using multiple subsidiaries

If you have more than one subsidiary where objects and documents are stored, you may also need to make sure the API user’s role is given access to all subsidiaries. This can be done by checking the box that says “All” in the Accessible Subsidiaries section.

If this setting is not enabled, items may be missing from Tenfold search results. If instead your team will only need one subsidiary, you can utilize the User Subsidiary after making sure any objects that will be managed in the Tenfold UI are within the Employee we use to sync’s subsidiary.

Step 3: RESTlet setup

In this step you will provision and deploy the Tenfold RESTlet scripts within your NetSuite environment. The completion of this process will allow for you to configure the script endpoints within the Tenfold system, and greatly improve performance for both read and write operations in NetSuite.

Upload the RESTlet scripts to NetSuite

• Download the NetSuite RESTlet scripts. You can download the NetSuite RESTlet scripts from the following URL: https://storage.googleapis.com/tenfold-netsuite-restlet/tenfold-oracle-netsuite-restlet.zip (there is no need to extract this folder; that will be handled by Netsuite)
• After downloading the scripts, navigate to Documents > Files > SuiteScripts in NetSuite.

• Click Advanced Add. Under "Zip Archive to Add,” click Choose File and select the tenfold-oracle-netsuite-restlet.zip file that you just downloaded.
• After selecting the “Unzip Files” and the “Overwrite Files With Same Name” checkboxes, click the Add & New button to create a new folder titled “tenfold-restlet.” 

• The upload will take a moment.
• Navigate back to Documents > Files > SuiteScripts to verify the new folder has been created. Make sure that load.js, endpoint.js, search.js, and upsert.js are included in the folder. Also check for netsuite_toolkit.js as we will need this for each Script Deployment later.

Set up the RESTlet endpoints

• You will now generate four RESTlet endpoints corresponding to each of the following uploaded files: load.js, search.js, upsert.js, and endpoint.js. NOTE: there are other scripts in the RESTlet download, but only these four require endpoints.
  • Navigate to Customization > Scripting > Scripts > New.

• Click the down arrow in the “Script File” field and select List. Within the "-All-" dropdown, select SuiteScripts - tenfold-restlet.
• Select the script you are setting up, and then click Create Script Record.

• Click RESTlet on the “Select 1.0 Script Type” page.

• Name the script “Tenfold <script name>” based on the script you are making (Tenfold Endpoint, Tenfold Load, Tenfold Search, or Tenfold Upsert).

• In the “POST FUNCTION” field, input “<script name>PostHandler.” The corresponding names are shown below. Under “Libraries,” include netsuite_toolkit.js for each of the four scripts. 

• Click Save and then Deploy Script. Set up the deployment in the following page as follows: “Status - Released” , “Departments - Admin”, and “Employees - All” Then, click Save. If you are unsure about any of these “Audience” Settings, just go with the option with the most visibility to the NetSuite Objects we will be interacting with. If All is an option go with that for the broadest Audience Scope.

• After deploying, copy the “External URL” for the script. This will be used to configure the CRM settings of the Tenfold Dashboard. This is also accessible from Customization > Scripting > Script Deployments.

• Repeat the steps above to create endpoints for the remaining three scripts and copy the “External URL” of each script to a location you can reference later before proceeding to the next section.

Step 4: Tenfold Dashboard setup

This section outlines the procedural steps in connecting Tenfold Web Services to your NetSuite environment via the CRM configuration portal in the Tenfold dashboard. Both the API user and RESTlet endpoints will be provided within a single setup pane.

1. Navigate to your Tenfold dashboard at https://dashboard.tenfold.com.
2. Click Company Settings in the top navigation.
3. In the sub-navigation, click CRM.
4. Select “Oracle NetSuite” as your CRM.
5. Select Token from the Authentication Type list.
6. Expand the Advanced Options section and enter the following information into the form:
   • Integration record authentication tokens — Consumer Key & Consumer Secret
   • Integration user authentication tokens — Token ID & Token Secret
   • Account ID (Found before “.app.netsuite.com” in your NetSuite URL )
   • Role ID (Found on the Web Services Preferences Page; its the ID of our Role and Employee, usually 3-4 digits)
   • Environment (Are you using a Sandbox or a Production instance of NetSuite?)
   • RESTlet endpoints (created these with the script deployments)
     • Load Endpoint
     • Search Endpoint
     • Upsert Endpoint
     • Main Endpoint (corresponds to endpoint.js)
7. Click Save.

When you click Save, Tenfold tests the connection and displays a success message if the information provided is correct. If the success message does not display, check the Advanced Options in the following steps.

Other Advanced Options Menu Options

Related User As Sales Rep: Attach the Tenfold UI user to any Record they create with Tenfold as the Sales Rep. Note all objects Tenfold makes will have the Tenfold API User as the creator.

Enable Open Details in Edit Mode: When the Tenfold UI opens a NetSuite tab, enable this setting to have it open with field edits available.

Default Company: If you're having issues saving notes to Contacts, check that there is a default Company set for Contacts that don’t have an Account. NetSuite requires Accounts to save a Calls to Contacts.

Date Format & Time Format: You must have the same format for both of these fields as for the NetSuite Instance we are integrating with. You can inspect the current NetSuite Date and Time Formatting value in user's preferences https://system.netsuite.com/app/center/userprefs.nl.

Related user as sales rep: Used by the "Create Record" function. When a new record is created, the current user is assigned to this record as a Sales Representative.

System Region: Is used when there is a need of working with a specific NetSuite Data Center.

Favour Concurrent Netsuite API calls: This can limit the amount of time it takes to look things up in NetSuite. Leave disabled until you notice any lag on CRM queries, but this is much faster than performing CRM requests with Tenfold sequentially.

Batch Size For Search: Defaults to 1000 but can range from 1 to 5000.

Appendix

NetSuite fields

The tables below outline the out-of-the-box entities and respective fields that the core Tenfold integration will interact with. Read and/or write permissions for additional fields, both standard and custom, may be required for your specific Tenfold deployment. Note If we did select a Subsidiary for the Employee and Role we created for this integration we need to make sure any of the below Entities, Modules, and Records are available to that Subsidiary. If your team’s workflow requires a similar, but different field set from this Appendix make sure to notify your Tenfold Support Engineer and provide the same permissions for your teams Field Set (example: We use Agents instead of Employees; make sure the Agent email, entityid, firstname, lastname, and phone fields have read access).

Table 1. User

Table 2. Customer, Lead, Prospect

Table 3. Contact

Table 4. Phone Call

Table 5. Task

Table 6. Opportunity

Table 7. SupportCase