Connecting to NetSuite

SuiteTalk vs SuiteQL

SuiteTalk is the older SOAP based service we use to communicate with NetSuite. It has broad support for a lot of entities and full support for insert/update/delete. However, the tools offered for selecting data are fairly weak, which yields very poor performance during a SELECT. There is not a great way to join tables. Grouping and aggregating data is unavailable with this API, which means to support them they must be done entirely client side.

SuiteQL is the newer API. It offers a SQL like method of communicating with the service, which allows for more rich join support, as well as group by and aggregations. It also fully supports retrieving only the columns you want to select. This makes it much more performant for selecting data vs SuiteTalk. However, it only supports selecting data.

You may specify which API to connect to by setting Schema. It is recommended to use SuiteQL if you are just retrieving data, and SuiteTalk if you need to both retrieve and modify. Please be aware that each API has different available connection options as described below.

Setting a Metadata Folder

When connecting to SuiteTalk, it is recommended but not required to specify the NetsuiteMetadataFolder. The Netsuite Metadata Folder is a folder on disk where NetSuite metadata files will be stored. If you do not specify one, a folder location will be selected automatically. To ensure fast load times when listing metadata about tables, it is best to set this property.

NetSuite Web Services Permissions

The adapter communicates with NetSuite through the NetSuite Web services. This means that any connecting user must have permissions on the specified AccountId to connect through NetSuite Web services. Please see the Permission Configurations for greater details on required and optional permissions.

Create or edit a role for Web services permissions

• Log into NetSuite and under Setup go to User/Roles -> Manage Roles -> New. Alternatively, edit an existing role.
• Click Permissions -> Setup and add the "SOAP Web Services" and "REST Web Services" permissions.
• Add other permissions that are needed for interacting with various entities and transactions.
• Under Setup, go to User/Roles -> Manage Users and select the user.
• On the Access tab, add the newly created role and save the user.

Authenticating to NetSuite

Basic

Note: This section is only applicable to SuiteTalk. SuiteQL requires OAuth or Token Authentication.

As of 2020.2, NetSuite will no longer support user / password connections. While the NetSuite Adapter will continue to support User/Password connections for Version set to values lower than 2020.2, it is recommended that all customers migrate to OAuth and Token Based Authentication mechanisms described below. Set the AuthScheme to Basic to support user / password credentials, but also be aware that due its removal in newer versions, you must also manually specify a lower Version to use it.

Token Based Authentication

Token Based Authentication or TBA may be used with either SuiteTalk or the SuiteQL Schema. Set the AuthScheme to Token to support TBA. Token Based Authentication is performed by creating the OAuthClientId, OAuthClientSecret, OAuthAccessToken and OAuthAccessTokenSecret directly within the NetSuite UI by an administrator with permissions to do so. See Creating an Access Token in NetSuite for further details on this process.

OAuth

To support OAuth, set the AuthScheme to OAuth. NetSuite offers two forms of OAuth authentication: 1.0, and 2.0. Token Based Authentication is actually just OAuth 1.0 with the OAuthAccessToken and OAuthAccessTokenSecret created within the NetSuite UI instead of at runtime. OAuth 1.0 is available for both SuiteTalk and SuiteQL. OAuth 2.0 is only available to SuiteQL. For this reason, OAuthVersion defaults to empty, meaning that if you set Schema to SuiteTalk, OAuth 1.0 will be used, and if you set Schema to SuiteQL, OAuth 2.0 will be used. This can be overridden by explicitly setting the OAuthVersion connection property, which may be desireable if switching between SuiteTalk and SuiteQL, or for users upgrading from a previous version where only OAuth 1.0 was supported for SuiteQL.

Be aware that even though you may change the OAuthVersion, OAuth 2.0 is not available on SuiteTalk even if you set it with Schema set to SuiteTalk since the API does not support it.

Please see Using OAuth Authentication for details on how to connect via OAuth.

Concurrent Requests

NetSuite allows only a certain amount of concurrent requests per account, which is configurable per integration connection (generally defaulting to 5). If the maximum, concurrent requests are currently in use when another one is attempted to be used, an error stating "Only one request may be made against a session at a time" may be thrown on the next connection. The NetSuite Adapter will attempt to account for this and stagger additional requests so as not to exceed the concurrent request limit. But it is not always possible to do this correctly if the account is being connected to from multiple machines or applications.

Asynchronous Services

Slow NetSuite response times extend to inserts, updates, and deletes as well.This can be especially noticeable when using batch processing. When inserting, updating, or deleting multiple records at a time, it may be worthwhile to set UseAsyncServices to true. This will cause the request to be processed asynchronously on NetSuite's end and a JobId will be returned in the Info#TEMP table. The JobId can be checked against the stored procedures CheckJobStatus and GetJobResults for information about when the job is completed, if any errors occurred, and for the InternalIds for newly created entities.