Netsuite

Prerequisites

To enable REST Web Services and the SuiteAnalytics Workbook features, head over to the 'Setup' tab, then 'Company' and in the 'Setup Tasks' category click on 'Enable Features'.

Now select the 'SuiteCloud' tab, scroll down to the 'Manage Authentication' section and check the 'TOKEN-BASED AUTHENTICATION' option. To use the feature, you must accept the SuiteCloud Terms of Service.

On the same 'Enable Features' page, select the 'Analytics' tab and scroll down to the 'SuiteAnalytics Workbook' section and check the 'SUITEANALYTICS WORKBOOK' option.

Now click 'Save' to enable your chosen features.

To enable permissions for those features, head over to the 'Setup' tab, then 'Users/Roles' and in the 'User Management' category click on 'Manage Roles'.

Either create a new role, or edit an existing role that you want to enable permissions for.

On the 'Role' page select the 'Permissions' tab and then the 'Setup' sub-tab. Add permissions for 'Log in using Access Tokens' and 'REST Web Services'.

Now select the 'Reports' sub-tab and add permission for 'SuiteAnalytics Workbook' to the role.

Now click 'save' to enable those permissions on the role.

You have now completed the pre-requisite steps to creating an authentication for a user.

With filtering:

This operation requires that users align the fields data type with the correct comparator.

For Example, Strings require 'CONTAINS', 'IS', etc, but will not work with 'EQUAL TO'. Use the NetSuite REST API Browser to determine which field types are relevant to your use case.

Follow the SuiteTalk REST Web Services PDF (see: Record collection filtering chapter) to learn about the allowed filters for each criteria.

Note that if users are 'filtering' any transaction type record, they will need to apply the 'Find Transactions' permission to the role of the authenticated under.

Creating sublists

Sublists contain a list of references to other records. Sublists are fields that in the NetSuit documentation are presented as collections.

The metadata schema for this field can also be seen in the output of 'List record fields'. We can notice that the schema for sublists will always be of this type:

    "line": {
        "type": "object",
        "properties": {
            ...
            "items": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        ...
                        "startDate": {
                            "title": "Start Date",
                            "type": "string",
                            "format": "date",
                            "nullable": true
                        },
                        "credit": {
                            "title": "Credit",
                            "type": "number",
                            "format": "double",
                            "nullable": true
                        },
                        "debit": {
                            "title": "Debit",
                            "type": "number",
                            "format": "double",
                            "nullable": true
                        },                      
                        "account": {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "title": "Internal Id",
                                    "type": "string"
                                },
                                ...
                            }
                        },
                    },
                ...
                }
            }
        },
        ...
    },

Image from NetSuite documentation on how to create a sublist.

As you can notice, the field name (in this case line) is a type object that has an 'items array', which contains all the fields we need to add in order to create a Journal Entry. For this particular case (of a Journal Entry), two accounts have to be added in the properties panel and to get an ID and debit and credit to go with it, like in the example below.

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.

From here, click on "New", which will bring up an 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

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

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

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.

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.

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\':

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

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.

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.

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.

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\':

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