Open Navigation

Netsuite

services to help manage business finances, operations, and customer relations

Overview



In this guide we'll describe how to work with NetSuite to authenticate Tray's NetSuite connector.

This guide assumes you already have access with a username/email and password.


Setting up an Authentication


In this guide we'll describe how to work with NetSuite to authenticate Tray's NetSuite connector.

This guide assumes you already have access with a username/email and password. Authentication Requirements

In order to authenticate tray's NetSuite connector, the following fields are required:

  • Account ID
  • Token ID
  • Token secret
  • Consumer key
  • Consumer secret

netsuite-auth

Setting up an Integration

On the NetSuite homepage, click on "Setup", then "Integration" and finally "Manage Integrations". This will bring you to the Integrations Page.

netsuite-manage-integrations

From here, click on "New", which will bring up an Integration form.

netsuite-integration-form

In the Integration form, provide a name, and make sure that the "TOKEN-BASED AUTHENTICATION" checkbox under Authentication is checked. Also ensure that the "TBA: AUTHORIZATION FLOW" and "USER CREDENTIALS" boxes are unchecked, and then save the integration.

Once you press save, your Consumer key and Consumer secret will be displayed - be sure to copy these somewhere safe as you won't be able to access them again.

Enabling token based authentication

From the menu, select Setup > Company > Enable Features. In the SuiteCloud tab, scroll down to the Manage Authentication section.

Ensure the "Token Based Authentication" is enabled, then save.

Creating and assigning a token role

In the search bar of your netsuite instance search for "page:role", then choose "New Role".

Enter a name for this role, then scroll down at the bottom of the page.

Navigate to Permissions > Setup and add the following permissions:

  • User Access Token: Full

  • Access Token Management: Full

  • Web Services: Full

As well as adding these permissions, you will need to let this role view all subsidiaries to be able to view all records in your netsuite instance. Under the second section title Subsidiary Restrictions, you will need to edit the settings so that All is selected rather than User subsidiary.

You might need to add additional permissions depending on the operation that you need to perform. In that case, the connector output will contain the instructions to do it. Keep in mind that it can take up to a couple of hours for netsuite to propagate your changes.

Click save. You can now assign this role to an existing employee.

Search for "page:employees" and find the employee, then click on Edit.

Navigate to Access > Roles and add the token role that you just created. Ensure the Give Access box is checked, also found in Access > Roles. If it has not already been checked, you will also need to choose at least one of the password creation options in the same section.

Creating access tokens

In the search bar of your netsuite instance search for "page:tokens", then choose "New Access Token".

Select the application and the role previously created, then press save and note the Token ID and Token Secret.

Obtaining the Account ID

The next step is to obtain your Account ID.

On the NetSuite homepage, click on "Setup", then "Integration" and finally "Web Services Preferences". This will bring you to the Web Services Preferences Page

netsuite-web-services-prefs

On this page, under "Primary Information", the required "Account ID" should be immediately visible; note this value.

netsuite-show-account-id

On the same page, a row/record with the fields "Name", "Web Services Default Role" and "ID", should either already exist, or you will need to add one. Either way, ensure a role with necessary permissions and access is selected; see the new role creation guide on the previous section.

You can now authenticate with Netsuite on Tray, using your Account ID, Token ID, Token secret, Consumer Key and Consumer Secret.

Displaying internal IDs

To help you interact with custom fields and records in netsuite, it is helpful to show internal IDs for fields in the interface. To do this, navigate to Home > Set Preferences > General Tab > Set Defaults, and ensure the box for Show Internal IDs is checked.



How to use this guide


In this guide we'll describe how to work with NetSuite using Tray's NetSuite connector.

You will need to have already set up your NetSuite authentication.

The netsuite connector is designed to be generic, so relies on knowledge of the schema to build the input. Hence you will need to have the netsuite schema browser open alongside your Tray workflow.

In Tray, the Name property refers to the field name in the schema browser.

Whenever a field has subfields, the type of the Value property in the input panel should be set to 'Array', to allow multiple subfields to be added. Otherwise the type of Value will be 'String'.

Finally, Attributes is always of 'Object' type, and contains key-value pairs corresponding to a field's attributes.

The value of a Namespace in Tray is an alias of the namespace shown in Netsuite. For example, here the alias of urn:relationships.lists.webservices.netsuite.com is listRel. You can find a dictionary of netsuite namespaces and their alias in Tray in Appendix 1 at the bottom of this 'Basic Usage' tab.

Once you have authenticated you can add a sequence of Netsuite steps to your workflow, we will take you through how to set up each one, using the Contact entity as an example.

Get a Record

Netsuite schema browser page: RecordType

Tray.io operation: Get record

Getting records requires a Record Type and an Internal ID.

The Record type field in Tray takes one of the values specified in the Value column in the schema browser.

The Internal ID field will be a unique identifier of a contact record in netsuite, which you can find by navigating to a contact in the interface and looking at its URL, for instance:

https://tstdrv1774461.app.netsuite.com/app/common/entity/contact.nl?id=9647

2-get-record-1

Delete a Record

Netsuite schema browser page: RecordType

Tray.io operation: Delete record

To delete a record, use the same input as the Get record operation. There is also the option to include a Deletion Reason Code and Deletion Reason Memo. These are optional fields useful for keeping track of how a record has come to be deleted.

You can find the list of valid Deletion Reason Codes from the NetSuite UI and going to Setup > Accounting > Accounting Lists.

Add a Record

Example netsuite schema browser page: Contact

Tray.io operation: Add record

Adding a record requires two parameters to be set describing the record, followed by any number of fields. The Namespace parameter takes the alias of the namespace shown in the schema browser, which can be found in Appendix 1 at the bottom of this 'Basic Usage' tab

When you have the schema browser open (see the link above), you will see all the fields available on the record that you can set in Tray.

2-add-record-1

Dealing with record references

In netsuite, fields often do not take a simple value, but refer to another entity. For example, contacts have a field called 'Company' which links to a customer. In the schema browser, you will see that the value of the 'Type' column for these fields is 'RecordRef', and requires the input to be slightly different.

2-add-record-2

Dealing with custom fields

When dealing with custom fields in netsuite, you need to know either the scriptId or internalId of the field. With the setting turned on for internal IDs, you can hover over fields in the interface and see their scriptId by clicking the question mark. For example, by clicking on the question mark for the field 'CUSTOM CONTACT FIELD' in the following, we see that the scriptId is 'custentity23':

2-add-record-3

Custom fields must be set within a field called 'customFieldList' according to the schema, which accepts a list of custom fields to set.

2-add-record-4

Update a Record

Example netsuite schema browser page: Contact

Tray.io operation: Update record

Updating a record works just like adding a record. You can follow the same instructions above with one exception - you must also provide an Internal ID - just like when you get a record.

2-tray-update-record

Search Records

Example netsuite schema browser page: ContactSearch

Tray.io operation: Search records

Schemas for searches are slightly different to that for create/update. To find the search schema associated with an entity, navigate to the schema for the entity itself, for example https://www.netsuite.com/help/helpcenter/en_US/srbrowser/Browser2016_1/schema/record/contact.html for Contact. Then at the bottom of the page, you will find a table titled 'Related Searches'. The first link is usually the main search schema page.

We will show a basic search for a contact based on the their 'entityId' here, but you can also perform search joins in Tray. Note you will have to make Search criteria an array for these more advanced searches.

The 'basic' field contains all the fields on the entity itself, and other fields at this level determine a search join to perform, for instance to return all customers related to a contact.

2-search-records-1

Appendix 1 - Table 1 (Namespace to Alias Mappings)

NamespaceNamespace Alias
urn:accounting.lists.webservices.netsuite.comlistAccounting
urn:bank.transactions.webservices.netsuite.comtransactiontransactionBank
urn:common.platform.webservices.netsuite.complatformCommon
urn:communication.general.webservices.netsuite.comgeneralCommunication
urn:core.platform.webservices.netsuite.complatformCore
urn:customers.transactions.webservices.netsuite.comtransactionCustomers
urn:customization.setup.webservices.netsuite.comsetupCustomization
urn:demandplanning.transactions.webservices.netsuite.comtransactionDemandplanning
urn:employees.lists.webservices.netsuite.comlistEmployees
urn:employees.transactions.webservices.netsuite.comtransactionEmployees
urn:faults.platform.webservices.netsuite.complatformFaults
urn:filecabinet.documents.webservices.netsuite.comdocumentFilecabinet
urn:financial.transactions.webservices.netsuite.comtransactionFinancial
urn:general.transactions.webservices.netsuite.comtransactionGeneral
urn:inventory.transactions.webservices.netsuite.comtransactionInventory
urn:marketing.lists.webservices.netsuite.comlistMarketing
urn:messages.platform.webservices.netsuite.complatformMsgs
urn:purchases.transactions.webservices.netsuite.comtransactionPurchases
urn:relationships.lists.webservices.netsuite.comlistRel
urn:sales.transactions.webservices.netsuite.comtransactionSales
urn:scheduling.activities.webservices.netsuite.comactivityScheduling
urn:supplychain.lists.webservices.netsuite.comlistSupplychain
urn:support.lists.webservices.netsuite.comlistSupport
urn:types.accounting.lists.webservices.netsuite.comlistAccountingTypes
urn:types.communication.general.webservices.netsuite.comgeneralCommunicationTypes
urn:types.customization.setup.webservices.netsuite.comsetupCustomizationTypes
urn:types.demandplanning.transactions.webservices.netsuite.comtransactionDemandplanningTypes
urn:types.employees.lists.webservices.netsuite.comlistEmployeesTypes
urn:types.filecabinet.documents.webservices.netsuite.comdocumentFilecabinetTypes
urn:types.inventory.transactions.webservices.netsuite.comtransactionInventoryTypes
urn:types.marketing.lists.webservices.netsuite.comlistMarketingTypes
urn:types.relationships.lists.webservices.netsuite.comlistRelTypes
urn:types.sales.transactions.webservices.netsuite.comtransactionSalesTypes
urn:types.scheduling.activities.webservices.netsuite.comactivitySchedulingTypes
urn:types.supplychain.lists.webservices.netsuite.comlistSupplychainTypes
urn:types.support.lists.webservices.netsuite.comlistSupportTypes
urn:types.website.lists.webservices.netsuite.comlistWebsiteTypes
urn:website.lists.webservices.netsuite.comlistWebsite

Appendix II - Further Documentation

NetSuite Basic Search Docs

NetSuite Schema Browser

NetSuite Help Centre

Advanced Searching

Example netsuite schema browser page: ContactSearchAdvanced

Tray.io operation: Search records

You can access the advanced search schema by going to a record type's schema, for instance the Contact schema (Contact) and scrolling down to 'Related Searches', then clicking on 'ContactSearchAdvanced'.

It may be desirable to only select certain fields to be returned, especially if performing a join, in order to reduce the data throughput in a workflow. With an advanced search, we define all the fields we wish netsuite to return, as well as the criteria to filter the results.

3-advanced-search-1

Creating Custom Records

Netsuite schema browser page: CustomRecord

Tray.io operation: Add record

Custom records are entities that are non-standard in netsuite. For instance, on the contact record we have created a custom record called 'Tray user':

3-create-custom-record-1

By clicking on a custom record in the interface, such as 'Example name' in the above, on the resulting page you can see the internalId of the record type and the record itself:

https://tstdrv1774461.app.netsuite.com/app/common/custom/custrecordentry.nl?recType=476id=704

3-create-custom-record-2

NetSuite primarily deals in XML, but tray.io has taken steps to standardise our NetSuite connector such that it works using JSON. However, in order for NetSuite to process requests correctly, the input still requires a translation back to XML. Therefore, we have implemented a way to translate JSON back to XML, but this requires the JSON object to be in a certain format.

Format: The object has 3 fields: name (required), value, and attributes.

  • The name field can only be a string which defines the XML property name.
  • The value field can either be a string, another object with the same three fields, or an array of objects with the same three fields.
  • The attributes field is an object which accepts any key/value pair (which has to be a string).
{
"name": "string (required)",
"value": "string|object|array",
"attributes": {
"key": "string"
}
}

Example JSON/input:

{
"name": "input",
"value": [
{
"name": "name",
"value": "tray.io"
},
{
"name": "contact",
"value": {
"name": "phone",
"value": "+1-415-418-3570"
}
}
{
"name": "otherInfo",
"attributes": {
"nil": "true"
}
}
],
"attributes": {
"type": "generic"
}
}

translates to:

<input type="generic">
<name>tray.io</name>
<contact>
<phone>+1-415-418-3570</phone>
</contact>
<otherInfo nil="true"/>
</input>

Common Resources

NetSuite SuiteTalk platform help

For information on how SuiteTalk works, login into your NetSuite account, and proceed:

Help Centre -> SuiteCloud -> SuiteTalk ->

  • SuiteTalk (Web Services) Platform Guide - use this section to understand the how the SuiteTalk API works and what each request requires.
    • Web Services Operations -> [relevant operation]
  • SuiteTalk (Web Services) Records Guide - use this section to understand how the data is represented, constructed, and related.

NetSuite/SuiteTalk WSDL and Schema definitions

WSDL: NetSuite WSDL
Core XSD: NetSuite Core XSD
Core Type XSD: NetSuite CoreType XSD
Common XSD: NetSuite Common XSD
Relationship XSD: NetSuite Relationship XSD

Schema and Records Browser: Browser

NetSuite/SuiteTalk operation/request cross-reference

Operation (tray.io)Request endpoint (SuiteTalk)
Add recordadd
Batch add recordsaddList
Batch delete recordsdeleteList
Batch get recordsgetList
Batch update recordsupdateList
Batch upsert recordsupsertList
Delete recorddelete
Get recordget
List recordsgetAll
Search recordssearch and Basic Searches
Search records more (by pagination)searchMoreWithId
Update recordupdate
Upsert recorddelete
Was this article helpful?
Yes
No