NetSuite
1 Connecting to NetSuite
1.1 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.
1.2 NetSuite Web Services Permissions
The provider 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.
Permissions may be configured for a role in NetSuite under Setup --> Users/Roles --> Manage Roles. This page contains two lists of permissions, first the most commonly required, and then other permissions for fuller support. Please be aware that it is not possible for us to provide an exhaustive list of permissions as NetSuite adds support for new entities and permissions with each version.
1.2.1 Most Commonly Required Permissions
Note: Most of the following permissions fall under the Permissions --> Setup section for a role.
Permission
Used For
Access Token Management
Allows users to create access tokens for Token Based Authentication.
Custom <type> Fields (VIEW)
Allows users to see custom fields of the given type. Used with IncludeCustomFieldColumns.
Custom Lists (VIEW)
Allows displaying metadata for custom list tables. Used with IncludeCustomListTables.
Custom Record Types (VIEW)
Allows displaying metadata for custom record tables. Used with IncludeCustomRecordTables.
Customer (VIEW)
Deleted Records (VIEW)
Used for retrieving information on deleted records.
Log in Using Access Tokens
Allows the user to log in to REST / SOAP services with a token.
REST Web Services
SOAP Web Services
All SOAP requests including when Schema is set to SuiteTalk (default), test connection, and some requests for custom fields.
SuiteAnalytics Workbook (VIEW)
Found under Permissions -> Reports. Required for SuiteQL access.
Other Custom Fields (VIEW)
Allows users to see custom fields of the "other" type. Used with IncludeCustomFieldColumns.
1.2.2 Other Permissions
Section
Permission
Used For (SuiteTalk Schema)
Used For (SuiteQL Schema)
Permissions => Custom Record
[Custom Record Name]
Access to the given custom record table
Access to the given custom record table
Permissions => Lists
Accounts
Access to the Account table
Access to the Account table
Permissions => Lists
Bins
Access to the Bin table
Access to the Bin table
Permissions => Lists
Calendar
Access to the CalendarEvent table along with the Events permission
Access to the CalendarEvent table along with the Events permission
Permissions => Lists
Cases
Access to the SupportCase table
Access to the SupportCase table
Permissions => Lists
Classes
Access to the Classification table
Access to the Classification table
Permissions => Lists
Contacts
Access to the Contact table
Access to the Contact table
Permissions => Lists
Currency
Access to the Currency table
Access to the Currency table
Permissions => Lists
Customers
Access to the Customer table
Access to the Customer table
Permissions => Lists
Departments
Access to the Department table
Access to the Department table
Permissions => Lists
Documents and Files
Access to the File and Folder tables
Access to the File table
Permissions => Lists
Employee Record
Access to the Employee tables
Access to the Employee table
Permissions => Lists
Events
Access to the CalendarEvent table along with the Calendars permission
Access to the CalendarEvent table along with the Calendars permission
Permissions => Lists
Items
Access to various Item tables such as DiscountItem, InventoryItem, NonInventoryItem, etc.
Access to the Item table
Permissions => Lists
Locations
Access to the Location table
Access to the Location table
Permissions => Lists
Phone Calls
Access to the PhoneCall table
Access to the PhoneCall table
Permissions => Lists
Project Tasks
Access to the ProjectTask table
Access to the ProjectTask table
Permissions => Lists
Subsidiaries
Access to the Subsidiary table
Access to the Subsidiary table
Permissions => Lists
Tasks
Access to the Task table
Access to the Task table
Permissions => Lists
Vendors
Access to the Vendor table
Access to the Vendor table
Permissions => Transactions
[Custom Transaction Name]
Access to retrieving data from the specific custom transaction via the special Transactions table
Access to retrieving data from the specific custom transaction type via the transaction table
Permissions => Transactions
Build Assemblies
Access to the AssemblyBuild table
Access the Build type from the Transaction table
Permissions => Transactions
CashSale
Access to the CashSale table
Access the CashSale type from the Transaction table
Permissions => Transactions
CashSaleRefund
Access to the CashRefund table
Access the CashRfnd type from the Transaction table
Permissions => Transactions
Charge
Access to the Charge table
Access the CardChrg type from the Transaction table
Permissions => Transactions
Check
Access to the Check table
Access the Check type from the Transaction table
Permissions => Transactions
Credit Memo
Access to the CreditMemo table
Access the Credit Memo type from the Transaction table
Permissions => Transactions
Deposit
Access to the Deposit table
Access the Deposit type from the Transaction table
Permissions => Transactions
Fulfill Orders
Access to the ItemFulfillments table
Access the Item Fulfillment type from the Transaction table
Permissions => Transactions
Invoice
Access to the Invoice table
Access the Invoice type from the Transaction table
Permissions => Transactions
Item Receipt
Access to the ItemReceipt table
Access the ItemRcpt type from the Transaction table
Permissions => Transactions
Opportunity
Access to the Opportunity table
Access the Opprtnty type from the Transaction table
Permissions => Transactions
Purchase Order
Access to the PurchaseOrder table
Access the PurchOrd type from the Transaction table
Permissions => Transactions
Sales Order
Access to the SalesOrder table
Access the SalesOrd type from the Transaction table
Permissions => Transactions
Transfer Order
Access to the TransferOrder table
Access the TrnfrOrd type from the Transaction table
Permissions => Transactions
Vendor Return Authorization
Access to the VendorReturnAuthorization table
Access the Vendor Return Authorization type from the Transaction table
Permissions => Transactions
Work Order
Access to the WorkOrder table
Access the WorkOrd type from the Transaction table
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.
2 Authenticating to NetSuite
2.1 Basic Authentication
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 connector 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.
2.2 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.
An older model that may still be used by admins is to simply create and assign a token directly in the NetSuite UI. Doing this will allow you to bypass the normal steps for generating an OAuth Access Token. This may be desireable if you would like to have more direct control over giving access, although it will always require manual steps to be taken in the UI each time. Instead, follow these steps to create a token in the UI:
In NetSuite, log in as an administrator role and navigate to Setup --> Company --> Enable Features --> SuiteCloud --> Manage Authentication. Make sure Token-Based Authentication and TBA: Authorization Flow are checked and save changes.
Navigate to Setup --> Integration --> Manage Integrations.
Create a new integration and select Token-Based Authentication.
When the integration is created, the Consumer Key and Consumer Secret displayed will map directly to the OAuthClientId and OAuthClientSecret connection properties. Write these down.
Create a token role by navigating to Setup --> User/Roles --> Manage Roles and either create a new role or edit an existing role.
Under Permissions --> Setup, the role must have the User Access Token: Full, Access Token Management: Full, and Web Services: Full permissions.
Add the role to a user under Lists --> Employees --> Employees. Select to edit an employee and add the new token role under Access --> Roles.
Navigate to Setup --> User/Roles --> Access Tokens and create a new access token. Select the application name as the integration that was created earlier, and the same user and role that were updated in the previous steps.
After creating the access token, a Token Id and Token Secret will be displayed. These map directly to the OAuthAccessToken and OAuthAccessTokenSecret. Write these down.
After creating the access token, a connection can now be made using the values obtained from the previous steps. Specify these connection properties at a minimum to connect:
AccountId specifying the account to connect to.
OAuthClientId the Consumer Key displayed when the application was created.
OAuthClientSecret the Consumer Secret displayed when the application was created.
OAuthAccessToken the Token Id when the access token was created.
OAuthAccessTokenSecret the Token Secret when the access token was created.
2.3 OAuth Authentication
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.
Register your NetSuite app on Setup --> Integrations --> Manage Integrations. Select the checkbox for each of Token-Based Authentication and TBA: Authorization Flow for OAuthVersion 1.0 support. Check the checkboxes for Authorization Code Grant, Restlets, and Rest Web Services for OAuthVersion 2.0 and set an appropriate Redirect URI. Then, obtain the following connection properties:
OAuthClientId: Set this to the Consumer Key assigned when you registered your app.
OAuthClientSecret: Set this to the Consumer Secret assigned when you registered your app.
CallbackURL: Set this to the Redirect URI defined when you registered your app such as http://localhost:33333. Note that this must be an exact match including any trailing '/' characters.
Set Callback URL to http://localhost:portnumber and set CallbackURL to match. You can specify any port available.
3 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 provider 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.
4 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.
5 PROPERTIES
The following are the connection properties for NetSuite_SuiteQL. Not all properties are required. Enter only property values pertaining to your installation. Several properties will be automatically initialized with the appRules defaults.
Property
Description
Authentication
AccountId
The company account your username is associated with on NetSuite.
AuthScheme
The type of authentication to use when connecting to NetSuite.
IncludeChildTables
A boolean indicating if child tables should be displayed.
NetsuiteMetadataFolder
A path to a directory to download metadata files from NetSuite. Set this for best performance.
Password
The password of the NetSuite user used to authenticate.
RoleId
The RoleId is the InternalId of the role that will be used to log in to NetSuite. Leave empty to use the user's default role.
User
The user of the NetSuite account used to authenticate.
Version
The version of the NetSuite API in usage. Defaults to 2020_2.
Caching
CacheTolerance
The tolerance for stale data in the cache specified in seconds when using AutoCache .
Firewall
FirewallPassword
A password used to authenticate to a proxy-based firewall.
FirewallPort
The TCP port for a proxy-based firewall.
FirewallServer
The name or IP address of a proxy-based firewall.
FirewallType
The protocol used by a proxy-based firewall.
FirewallUser
The user name to use to authenticate with a proxy-based firewall.
Logging
Logfile
A filepath which designates the name and location of the log file.
LogModules
Core modules to be included in the log file.
MaxLogFileCount
A string specifying the maximum file count of log files. When the limit is hit, a new log is created in the same folder with the date and time appended to the end and the oldest log file will be deleted.
MaxLogFileSize
A string specifying the maximum size in bytes for a log file (for example, 10 MB). When the limit is hit, a new log is created in the same folder with the date and time appended to the end.
Verbosity
The verbosity level that determines the amount of detail included in the log file.
Misc
AggregateColumnMode
Indicating how aggregate columns should be treated.
ApplicationId
As of version 2020.1, requests to NetSuite require an application ID.
ConnectionLifeTime
The maximum lifetime of a connection in seconds. Once the time has elapsed, the connection object is disposed.
ConnectionString
***
CustomFieldPermissions
A comma separated list of custom field permissions. Gives more control than IncludeCustomFieldColumns .
IncludeCustomFieldColumns
A boolean indicating if you would like to include custom field columns.
IncludeCustomListTables
A boolean indicating if you would like to use tables based on custom lists.
IncludeCustomRecordTables
A boolean indicating if you would like to use tables based on custom record types.
IncludeReferenceColumns
A comma separated list representing the columns to include when retrieving data from a field representing a record reference.
MaximumConcurrentSessions
The maximum number of concurrent sessions available for use in the connection.
MaxRows
Limits the number of rows returned rows when no aggregation or group by is used in the query. This helps avoid performance issues at design time.
Other
These hidden properties are used only in specific use cases.
Pagesize
The number of results to return per page from NetSuite.
PoolIdleTimeout
The allowed idle time for a connection before it is closed.
PoolMaxSize
The maximum connections in the pool.
PoolMinSize
The minimum number of connections in the pool.
PoolWaitTime
The max seconds to wait for an available connection.
PseudoColumns
This property indicates whether or not to include pseudo columns as columns to the table.
Readonly
You can use this property to enforce read-only access to NetSuite from the provider.
ReportDoublesAsDecimal
Indicates if doubles should be reported as decimal.
RequestMemorizedTransactions
A boolean indicating if you would like to request memorized transactions when retrieving transactions from NetSuite.
SSLServerCert
The certificate to be accepted from the server when connecting using TLS/SSL.
SupportEnhancedSQL
This property enhances SQL functionality beyond what can be supported through the API directly, by enabling in-memory client-side processing.
Timeout
The value in seconds until the timeout error is thrown, canceling the operation.
UseAsyncServices
A boolean indicating if you would like to use asynchronous services when inserting, updating, and deleting.
UseConnectionPooling
This property enables connection pooling.
UseInternalNamesForCustomizations
A boolean indicating if you would like to use internal names for customizations.
UserTimezoneOffset
Your user timezone offset as defined in your NetSuite preferences under Home --> Preferences --> Time Zone. Ex: -8:00.
UseSimpleNames
Boolean determining if simple names should be used for tables and columns.
UseUpserts
A boolean indicating if you would like to perform an upsert when an insert operation is used.
WebServiceHost
An optional override for the web service host such as webservices.na1.netsuite.com.
OAuth
AuthKey
The authentication secret used to request and obtain the OAuth Access Token.
AuthToken
The authentication token used to request and obtain the OAuth Access Token.
CallbackURL
The OAuth callback URL to return to when authenticating. This value must match the callback URL you specify in your app settings.
InitiateOAuth
Set this property to initiate the process to obtain or refresh the OAuth access token when you connect.
OAuthAccessToken
The access token for connecting using OAuth.
OAuthAccessTokenSecret
The OAuth access token secret for connecting using OAuth.
OAuthClientId
The client ID assigned when you register your application with an OAuth authorization server.
OAuthClientSecret
The client secret assigned when you register your application with an OAuth authorization server.
OAuthExpiresIn
The lifetime in seconds of the OAuth AccessToken.
OAuthSettingsLocation
The location of the settings file where OAuth values are saved when InitiateOAuth is set to GETANDREFRESH or REFRESH. Alternatively, this can be held in memory by specifying a value starting with memory://.
OAuthTokenTimestamp
The Unix epoch timestamp in milliseconds when the current Access Token was created.
OAuthVerifier
The verifier code returned from the OAuth authorization URL.
Proxy
ProxyAuthScheme
The authentication type to use to authenticate to the ProxyServer proxy.
ProxyAutoDetect
This indicates whether to use the system proxy settings or not. This takes precedence over other proxy settings, so you'll need to set ProxyAutoDetect to FALSE in order use custom proxy settings.
ProxyExceptions
A semicolon separated list of destination hostnames or IPs that are exempt from connecting through the ProxyServer .
ProxyPassword
A password to be used to authenticate to the ProxyServer proxy.
ProxyPort
The TCP port the ProxyServer proxy is running on.
ProxyServer
The hostname or IP address of a proxy to route HTTP traffic through.
ProxySSLType
The SSL type to use when connecting to the ProxyServer proxy.
ProxyUser
A user name to be used to authenticate to the ProxyServer proxy.
Schema
Schema
The type of schema to use.
Last updated