Settings for NetSuite

This topic describes how to set up a NetSuite connection for DataSync.

Important

Prior to setting up the connection, ensure that:

  • DataSync is installed in HTTPS.

  • You have a NetSuite account with Admin permissions.

NetSuite offers two API schemas for retrieving the data, SuiteQL and SuiteTalk. Each API has different available connection options as described below.

  • SuiteTalk: SuiteTalk is the older SOAP based service used to communicate with NetSuite. Grouping and aggregating data is unavailable with this API, which means to support them they must be done entirely client side. SuiteTalk supports full access to custom records, fields, and lists. Saved searches are supported both the SOAP API and through RESTLets.

  • SuiteQL: 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. However, it only supports selecting data. It is recommended to use SuiteQL if you are just retrieving data.

To configure a new connection

To fill out your DataSync connection properties, you need to create a custom NetSuite application in the NetSuite configuration interface. This will allow you to retrieve the properties needed in DataSync to establish a connection with NetSuite.

  1. Log into NetSuite.

  2. Open the Setup Manager and select the Integration menu > Manage Integrations.

  3. In the Integrations page, click New to create an integration.

  4. In the Integration page:

    1. Enter a name for your integration.

    2. Enter the number of concurrent sessions in the Concurrency Limit field. NetSuite allows up to a maximum of 5 concurrent sessions.

    3. Select the following options:

      • Token-Based Authentication

      • TBA: Issue token endpoint

      • TBA: Authorization Flow

  5. Open DataSync and create a new source connection for NetSuite.

    If you opt to use OAuth as authentication mode to connect to NetSuite, you need to retrieve the DataSync callback URL before creating your custom NetSuite application. Copy the Callback URL that was given to you.

  6. Go back to your NetSuite Integration page:

    1. Paste your Callback URL in the Callback URL and Redirect URI fields.

    2. Select the Authorization Code Grant and Public Client options.

    3. Set the OAuth 2.0 Consent Policy setting to Always Ask (recommended).

    4. Select your Scope. The Scope will allow you to retrieve the access and refresh token with OAuth. It is recommended to select RESTLETS and REST WEB SERVICES.

    5. Select the User Credentials option.

    6. Click Save.

  7. Once saved, NetSuite displays your Client ID, Client Secret, and Application ID. You can now finalize your DataSync connection.

    Note:  Save your Client ID and Client Secret in a file as they are only displayed once.

  8. Go back to DataSync:

    1. Fill out the connection properties. The connection properties change depending on the Authentication Mode.

    2. Click Save.

  9. You will be redirected to an authorization web page asking you to authorize OAuth. Click Continue and your connector will be authorized and ready to use.

NetSuite Connection Properties

Connection Properties Description
Description Enter a user given name to identify the connection in DataSync.
Schema

The NetSuite Schema that is being used. This will define the authentication to NetSuite. Available Schemas are SuiteQL (recommended) and SuiteTalk.

Note:  For SuiteTalk, Token Based Authentication should be used, in which case you need to create a token in the NetSuite interface. Make sure that you have the access permissions specified in the token role.
Account ID Enter your account ID. It can be found in NetSuite under Setup > Company > Company Information as an alphanumeric combination under Account ID.
Application ID Enter the Application ID that was given to you when you saved your application (see Step 7). It is recommended to always input it to ensure that you have the appropriate permissions. You can find your applications in NetSuite under Setup > Integration > Manage Integrations.
Scope

Specify the scope to obtain the initial access and refresh token with OAuth. Use the scope that you selected when you created your application. Values can be:

  • restlets,

  • rest_webservices, or

  • both separated by a space as restlets rest_webservices.
Authentication Mode

Select your authentication mode:

  • TokenBased (recommended for SuiteTalk)

  • OAuthHeadless

Callback URL This parameter appears when you select the OAuthHeadless authentication mode. Enter the callback URL that was given to you.
Client ID Client ID assigned when you register your application with an OAuth authorization server (see Step 7).
Client Secret Client password assigned when you register your application with an OAuth authorization server (see Step 7).
Access Token This parameter appears when you select the TokenBased authentication mode. It should be used with the SuiteTalk schema. The access token is used in place of your username and password. The access token protects your credentials by keeping them on the server.
Access Token Secret Password used with the Access Token to authenticate using TokenBased Authentication. It should be used with the SuiteTalk schema.
Row Scan Number of rows to scan when dynamically determining columns for the table. Row Scan must be equal or greater than 1 and less than 1000. It defaults to 50 for best performance.
Connection Timeout

Length of time in seconds to wait for a connection to the server before terminating the attempt and generating an error. In NetSuite, operations can take a very long time to return if retrieving data from child tables or retrieving data from a table with Aggregate Columns.

For instance, it could take more than 10 minutes to retrieve 1000 Sales Orders in a single request from NetSuite when AggregateColumnMode is set to ListAndRetrieve. Unfortunately, this is a limitation of the NetSuite Web Services with no known solution.

If you need to work with aggregate columns or child tables, it is recommended to set timeout to 0.
Include Child Tables

If this option is selected, tables will be displayed for all child lists of an entity.

For instance, the CashRefund table in the NetSuite development environment has a child list called ItemList. Therefore, a new table called CashRefund_ItemList will be displayed if this property is enabled. This can be useful for listing each item in the list in its own row. Due to the number of child collections, turning them on will cause the total table count to increase significantly by several hundred.

Include Custom Field Columns Selecting this option will cause custom fields to be displayed directly on tables as their own columns. However, it will cause lower performance when retrieving the table metadata information for the first time on an open connection. Table metadata is stored on the connection and cleared when the connection is closed.
Include Custom List Tables Selecting this option will cause custom list types to be included as their own tables. However, it will cause lower performance when retrieving the table metadata information for the first time on an open connection. Table metadata is stored on the connection and cleared when the connection is closed.
Include Custom Record Tables Selecting this option will cause custom record types to be included as their own tables. However, it will cause lower performance when retrieving the table metadata information for the first time on an open connection. Table metadata is stored on the connection and cleared when the connection is closed.
Aggregate Columns Aggregate columns are the columns that will appear on base tables which aggregate all the data contained within child collections. Selecting this option will cause aggregate columns to be listed and displayed. Child collections can be listed only with Include Child Tables enabled.
Additional Connection Properties These options can be manually added to the connection in case the user requires more customization.

To create a token in NetSuite

  1. Log into NetSuite with an administrator role and navigate to Setup > Company > Enable Features > SuiteCloud > Manage Authentication.

  2. Make sure the Token-Based Authentication and TBA: Authorization Flow options are selected and save changes.

  3. Navigate to Setup > Integration > Manage Integrations.

  4. Create a new integration and select Token-Based Authentication.

  5. Navigate to Setup > User/Roles > Manage Roles and create a new role or edit an existing role.

  6. Under Permissions > Setup, select the following permissions for the role:

    • User Access Token: Full

    • Access Token Management: Full

    • Web Services: Full

  7. Navigate to Lists > Employees > Employees and add the role to a user.

  8. Under Access > Roles, edit an employee and add the new token role.

  9. 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.

  10. After creating the access token, a Token ID and Token Secret will be displayed. These will map directly to the OAuthAccessToken and OAuthAccessTokenSecret. Write them down.

NetSuite Permissions

An Administrator account is required to establish a NetSuite Connection and extract the data for NetSuite. However, on some occasions permissions to access the data on certain tables might be missing. This is a list of the commonly required permissions to use the connector. Most of the following permissions fall under the Permissions menu for the specified role.

To access NetSuite permissions for the role:

  1. Go to Setup > User/Roles > Manage Roles.

  2. Select your desired role or create a new one.

  3. Click the Edit button within your role to edit the permissions for your connection.

  4. In the General section, select Core Administration Permissions to have most of the Administration permissions. For other permissions, View reflects the minimum level of permission needed for the specific permission.

  5. Click the Permissions tab and set the permissions as described in the table below.

  6. Some NetSuite settings require the Web Services permission.

    To activate the web services:

    1. Go into your role > Permissions > Setup.

    2. Add SOAP WEB SERVICES permission (for SuiteTalk) and REST WEB SERVICES (for SuiteQL).

  7. To retrieve custom tables you need to activate the Custom Table permission for the desired table.

    To activate the custom table permission:

    1. Go to your role > Permissions > Lists.

    2. Add the views or tables that you want to retrieve.

Permission Description
Reports tab
SuiteAnalytics Workbook (VIEW) Allows SuiteQL access.
Lists tab
Customer (VIEW) Used for testing the connection in RESTlets.
Setup tab
Access Token Management Allows users to create access tokens for TokenBased authentication.
Custom <type> Fields (VIEW)

Allows users to see custom fields of the given type, including:

  • Custom Column Fields

  • Custom Entity Fields

  • Custom Entry Fields

  • Custom Item Fields

  • Custom Transaction Fields

  • Custom Fields

This permission is used with Include Custom List Columns.
Other Custom Fields (VIEW) Allows users to see custom fields of the other type. This permission is used with Include Custom Field Columns.
Custom Lists (VIEW) Displays metadata for custom list tables. This permission is used with Include Custom List Tables.
Custom Record Types (VIEW) Displays metadata for custom record tables. This permission is used with Include Custom Record Tables.
Deleted Records (VIEW) Retrieves information on deleted records.
Log in Using Access Tokens Allows users to log in to REST / SOAP services with a token.
Log In using OAuth 2.0 Access Tokens Allows users to log in to REST services using OAuth 2.0.
REST Web Services REST requests are used for RESTLets support. REST Web Services are used when the schema is set to SuiteQL.
SOAP Web Services SOAP requests are used for testing connections and some requests are used for custom fields. SOAP Web Services are used when the schema is set to SuiteTalk (default).
User Access Tokens Allows users to have tokens created for them using either TokenBased or OAuthHeadless authentication.
Custom Record tab
[Custom Record Name]

Gives users access to the custom record table.