Open Navigation

Netsuite

services to help manage business finances, operations, and customer relations
On This Page

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.

add-auth


Setting up an Integration


The first step is to obtain the Application ID. For this, an integration record needs to be created if one is not already set up by your NetSuite admin.

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

netsuite-homepage

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

netsuite-new-form

On the Integration form, provide a name, and make sure that the "USER CREDENTIALS" checkbox under Authentication is checked. Then save the integration.

On the Integrations page, you should see your newly created integration, along with an associated Application ID: note this ID value as this is required on tray.

netsuite-integrations


Account ID and Role


The next step is to obtain your Account ID and a relevant role.

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-prefs

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

netsuite-account-id

On the same page, a row/record under "Concurrency Governance" with the fields "Name", "Web Services Default Role" and "ID", should either already exist, or you will need to add one. If you need to add one, ensure a role with necessary permissions and access is selected; for further guidance on this, seek advice from your NetSuite administrator. From this record, the "ID" at the end needs to be noted, as this is the "Role" ID required for the NetSuite authentication on tray.



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.

This guide describes how to interact with NetSuite records by making reference to a template that we have prepared for you. You will be asked to select your NetSuite authentication or to create a new one. Once the setup is complete, do not select RUN WORKFLOW NOW. Select EDIT WORKFLOW (ADVANCED).

2-netsuite-edit-workflow

This will open a small workflow that will give you an example for each of the next sections:

2-netsuite-workflow-diagram

You can install this template here

Add a Record

Adding a record requires two parameters to be set about the record followed by any number of fields.

First, let's take a look at the record parameters:

  • Type
  • Namespace

2-record-parameter

Type

You will usually find the record type you wish to add through the NetSuite UI. Record types are things like "Customer", "Lead", or "Employee".

2-netsuite-record-type

A comprehensive list of record types can be found using the NetSuite Records Browser.

Namespace

NetSuite requires a namespace to be set, too.

You need to find the namespace for your record type. Look up your record type using the Netsuite Schema Browser.

Note the namespace for your record type.

2-netsuite-namespace

You'll then need to look up the alias for that namespace in Table 1 at the end of this guide.

Select this alias from the dropdown in Tray.

2-namespace-dropdown

You can then select a number of fields to add to the record. The available fields can be found in the NetSuite Records Browser.

Note the "Type" column in the Records Browser. Some fields have more complex types which will need to be accounted for in the field object in Tray. See, for example, the subsidiary field which has its own definition. Clicking on "RecordRef" gives information about the object structure for this field. You can see in this example how this maps to the relevant structure in Tray.

2-netsuite-recordref


2-netsuite-recordref


2-tray-recordref-dropdown

Get a Record

Getting records requires a Record Type and an Internal ID. Both of these can be found from the NetSuite UI - but it is more likely that you will get the Internal ID from elsewhere in Tray. For example, it can be found in the output whenever you add a record.

2-tray-output-get-record

A comprehensive list of record types can be found using the NetSuite Records Browser.

Note that when getting a record the Record Type must be set in lower case.

2-tray-dropdown-get-record

Update a Record

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

2-tray-update-record

Search Records

Searching requires two parameters to be set about the record being searched for, followed by any number of search criteria.

Record Parameters

There are two require record parameters:

  • Type
  • Namespace

2-tray-search-records

Type

You will usually find the record type you wish to search for through the NetSuite UI. Record types are things like "Customer", "Lead", or "Employee".

2-netsuite-list-types

Look up your record type using the Netsuite Schema Browser.

2-netsuite-schema-browser

Scroll to the bottom of the page and look for the Related Searches section.

2-netsuite-related-searches

Enter your type as the first of these search names. This is usually your type with the suffix "Search" (e.g. CustomerSeach, ContactSearch)

Alternatively, by clicking the Search tab you can view a list of all possible searches. Only the simplest kind, suffixed with just "Search", are available within Tray.

2-netsuite-list-searches

Namespace

NetSuite requires a namespace to be set, too.

You need to find the namespace for your record type. Note that this is the namespace for your search type (e.g. CustomerSearch), not your type (e.g. Customer). Look up your record type using the Netsuite Schema Browser.

Note the namespace for your record type

2-netsuite-record-type-namespace

You'll then need to look up the namespace alias in Table 1 at the end of this document.

Select this alias from the dropdown in Tray.

2-tray-namespace-dropdown

Search Criteria

This is where you define your search. The structure here is very specific. When creating new searches you will need to copy this object structure carefully.

In our example we're going to search for a customer by their email. To understand which fields can be searched by you can use the Netsuite Schema Browser. From the page for your search select the Basic type.

2-netsuite-search-basic

This gives you a list of all of the fields that can be used in your search criteria:

2-netsuite-search-basic-results

Looking at this list we can see that we can search by email. Here is the example from the template showing what our final query will look like. We'll now discuss how to construct each part of this query.

2-netsuite-final-list

First, the "Name" field will always be the same as the "Namespace" field suffixed with ":basic":

2-netsuite-name-field

Next we define that we want to do a search by the email field. Find the namespace from the "CustomerSearchBasic" page and look up its alias in Table 1 at the end of this document.

2-netsuite-find-email-namespace

We enter the namespace alias and the field here, separated by a semi-colon:

2-netsuite-email-field

Next, select the type for the email field. It'll open a page called "SearchStringField":

2-netsuite-select-searchstringfield

Look up the alias for this namespace in Table 1 at the end of this document. Create the input for the name by concatenating the alias with the field name, separated by a semi-colon. The value is the text string you wish to search:

2-netsuite-alias-lookup-email


2-netsuite-serachvalue-field

Finally, we need to add a couple of attributes. We know that we need to add these because they appeared on the "SearchStringField" page:

2-netsuite-select-searchstringfield-operator

Opening this operator gives us the information we need to fill in the attributes section. Look up the namespace alias from Table 1 at the end of this document. Together with the name of the operator and the name "SearchStringField" these form the output for the final part of the query.

2-netsuite-alias-searchstringfield-operator


2-netsuite-operator-field

Delete a Record

Deleting records requires a Record Type and an Internal ID. Both of these can be found from the NetSuite UI - but it is more likely that you will get the Internal ID from elsewhere in Tray. For example, it can be found in the output whenever you add a record:

2-netsuite-debug-get-internal-id

A comprehensive list of record types can be found using the NetSuite Records Browser.

Note that when deleting a record the Record Type must be set in lower case.

2-netsuite-insert-internal-id

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.

2-netsuite-accounting-lists

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

This walkthrough will, using an example, explain how to construct the input for the Search records operation in the NetSuite connector, although the construction methodology will be applicable to other pertinent operations.

In essence, the construction method configures the JSON objects in such a way that can be translated into XML, as required by NetSuite (SOAP) requests.

Additionally, please reference NetSuit's Help Centre, in particular the SuiteTalk (Web Services) Platform Guide (in particular, Web Services Operations) and SuiteTalk (Web Services) Records Guide sections, as they will indicate and guide how to form the inputs as XML.

Search Records

The aim of this example: find customers whose email ends with "gmail.com".

It should be noted that the NetSuite connector predefines some of the JSON that are generic and always required in each requests. For the Search records operation in particular, this can be referenced to a Basic Search example, where the XML up to is already generated. i.e:

<platformmsgs:search xmlns="urn:messages_2017_1.platform.webservices.netsuite.com">
<searchRecord xsi:type="recordRef:..." xmlns:recordref="...">
...
</searchRecord>
</platformmsgs:search>

Search record type and Search record type xmlns

The first and second fields, Search record type and Search record type xmlns required in the properties panel, fill in the <searchRecord xsi:type="..." xmlns:recordRef="..."> parts of the XML body, (while the Search Criteria field fills the rest of the XML input onwards).

Since the aim of the example is to find Customers, the Customer entity needs to be referenced here. This can be found under the Records Guide, in Entities: Customer. According to the documentation here, it is noted that the Customer entity is defined under listRel, pointing to the Relationships XSD. In this schema document, it can be found that in order to search Customers, that listRel:CustomerSearch (found in correspondence to contactSearch) is needed.

Now, in order to accommodate any type of search, it is necessary for the Search records operation to remain generic; in order to facilitate this, a generic pointer, recordRef, has been used to point to the xmlns. Therefore in this example, it should be considered that listRel has been swapped for recordRef (as a pointer to the schema). It follows then that the values for the fields Search record type and Search record type xmlns are CustomerSearch and urn:relationships_2017_1.lists.webservices.netsuite.com respectively, forming the respective XML element:

<searchRecord xsi:type="recordRef:CustomerSearch" xmlns:recordRef="urn:relationships_2017_1.lists.webservices.netsuite.com.">
...
<searchRecord />

3-netsuite-field-search-record-type

Search Criteria

From here on, for the Search Criteria field, the entire XML must be created in a JSON format, which will follow the construction methodology outlined in the first stage (tab) of this guide.

Referring to the Relationships XSD once more, under the CustomerSearch complexType, a basic element can be found, with an attribute type="platformCommon:ContactSearchBasic". This basic part is needed in order to perform a query about a customer's email, since email is contained within the ContactSearchBasic definition, while the platformCommon part is a reference to the Common XSD, which is where further details on the ContactSearchBasic definition can be found, including email.

Viewing the Basic Search example code example once more, there are two things to note: the operator attribute and the platformCore:searchValue element. The operator attribute denotes the type of search/filter to perform, while the searchValue element, as implied, indicates the value to use in the search/filter. The valid operator values can be found in CoreTypes XSD, under SearchStringFieldOperator definition.

Finally, with all this information the Search Criteria field can be populated. It should be noted that listRel will need to be referenced, and therefore another reference to Relationships XSD will be needed. Additionally, a reference for platformCore:SearchStringField will also be needed, which can be referenced to the Core XSD

The JSON input for the Search Criteria field is as follows:

{
"name": "listRel:basic",
"attributes": {
"xmlns:platformCommon": "urn:common_2017_1.platform.webservices.netsuite.com",
"xmlns:listRel": "urn:relationships_2017_1.lists.webservices.netsuite.com"
},
"value": {
"name": "platformCommon:email",
"attributes": {
"operator": "contains",
"xsi:type": "platformCore:SearchStringField",
"xmlns:platformCore": "urn:core_2017_1.platform.webservices.netsuite.com"
},
"value": {
"name": "platformCore:searchValue",
"value": "gmail.com"
}
}
}

Note how in value field, another object with fields name, value, and attributes is needed, as described by the construction methodology mentioned previously.

3-netsuite-fields-search-criteria

Final Input

The final (JSON) input for this example should look like the following in the Input section of the logs:

{
"search_record_type": "CustomerSearch",
"search_record_type_xmlns": "urn:relationships_2017_1.lists.webservices.netsuite.com",
"search_criteria": {
"name": "listRel:basic",
"value": {
"name": "platformCommon:email",
"value": {
"name": "platformCore:searchValue",
"value": "gmail.com"
},
"attributes": {
"operator": "contains",
"xsi:type": "platformCore:SearchStringField",
"xmlns:platformCore": "urn:core_2017_1.platform.webservices.netsuite.com"
}
},
"attributes": {
"xmlns:listRel": "urn:relationships_2017_1.lists.webservices.netsuite.com",
"xmlns:platformCommon": "urn:common_2017_1.platform.webservices.netsuite.com"
}
},
"email": "co... <**--removed--**>",
"account": "TS... <**--removed--**>",
"password": "bT... <**--removed--**>",
"role": "<**--removed--**>"
}

Which produces the following compliant JSON:

{
"name": "searchRecord",
"attributes": {
"xsi:type": "recordRef:CustomerSearch",
"xmlns:recordRef": "urn:relationships_2017_1.lists.webservices.netsuite.com"
},
"value": {
"name": "listRel:basic",
"value": {
"name": "platformCommon:email",
"value": {
"name": "platformCore:searchValue",
"value": "gmail.com"
},
"attributes": {
"operator": "contains",
"xsi:type": "platformCore:SearchStringField",
"xmlns:platformCore": "urn:core_2017_1.platform.webservices.netsuite.com"
}
},
"attributes": {
"xmlns:listRel": "urn:relationships_2017_1.lists.webservices.netsuite.com",
"xmlns:platformCommon": "urn:common_2017_1.platform.webservices.netsuite.com"
}
}
}

and this finally transforms into the following XML:

<searchRecord xsi:type="recordRef:CustomerSearch" xmlns:recordref="urn:relationships_2017_1.lists.webservices.netsuite.com">
<listrel:basic xmlns:platformcommon="urn:common_2017_1.platform.webservices.netsuite.com" xmlns:listrel="urn:relationships_2017_1.lists.webservices.netsuite.com">
<platformcommon:email operator="contains" xsi:type="platformCore:SearchStringField" xmlns:platformcore="urn:core_2017_1.platform.webservices.netsuite.com">
<platformcore:searchvalue>gmail.com</platformcore:searchvalue>
</platformcommon:email>
</listrel:basic>
</searchRecord>

The rest of the necessary XML is generated by the connector before making the request to NetSuite.

NetSuite

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.ioname>
<contact>
<phone>+1-415-418-3570phone>
contact>
<otherInfo nil="true"/>
input>

Common Resources

NetSuite SuiteTalk platform help

For information on how SuitTalk 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 WSDLCore XSD: NetSuite Core XSDCore Type XSD: NetSuite CoreType XSDCommon XSD: NetSuite Common XSDRelationship 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
On This Page