NetSuite connector advanced in Jitterbit Design Studio

Introduction

This page covers troubleshooting tips, how-tos, and advanced functionality related to NetSuite integrations.

Troubleshooting and how-tos

This section describes issues and workarounds to common issues experienced with NetSuite integrations and provides information on NetSuite changes that may affect your integration.

NetSuite account-specific WSDL URL

During configuration of a NetSuite endpoint, you must supply an account-specific WSDL URL in the WSDL Download URL field. This section shows how to obtain this URL by finding the NetSuite account-specific domain and then using the account-specific domain in the WSDL URL.

Finding the NetSuite account-specific domain

These steps must be performed by a NetSuite Administrator or other user with the Set Up Company permission:

1. Log in to the NetSuite instance.

2. Go to Setup > Company > Company Information (or search for Company Information).

3. On the Company Information page, go to the Company URLs sub-tab. The account-specific domain is under the SuiteTalk (SOAP and REST Web Services) heading:

   

For more information, see URLs for Account-Specific Domains.

Constructing the WSDL URL

Once you have obtained the account-specific domain, use it to construct the WSDL URL:

• https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2024_2_0/netsuite.wsdl
• https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2024_1_0/netsuite.wsdl
• https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2023_2_0/netsuite.wsdl
• https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2023_1_0/netsuite.wsdl
• https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2022_2_0/netsuite.wsdl
• https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2022_1_0/netsuite.wsdl

During configuration of a NetSuite endpoint, enter this account-specific WSDL URL in the WSDL Download URL field.

Information about which Jitterbit agent versions are required for use with the above WSDL versions is provided in Prerequisites on the NetSuite connector endpoint page.

Change the WSDL version

Periodically upgrading the WSDL version used by your NetSuite endpoint in order to always be using a fully supported version is a recommended good practice. The steps below outline the best way to make the change, ensuring a seamless upgrade.

1. Create a new endpoint.

2. For each NetSuite operation, swap the old endpoint with the new one.

3. Refresh the function.

4. Refresh the transformations.

5. Repeat steps 2 to 4 for each NetSuite operation.

NetSuite data center error

Due to changes made by NetSuite, some WSDL URL formats that were previously allowed are no longer accepted, including generic WSDL URLs and data center-specific URLs. Jitterbit recommends always using an account-specific WSDL URL.

A NetSuite endpoint may have previously been tested successfully, but now fails with this error:

Connector Error: Error getting the data center URL.

Caused by: org.jitterbit.integration.server.engine.connector.exception.NetSuiteWebServiceRuntimeException: FaultString:

In this account, you must use account-specific domains with this SOAP web services endpoint. You can use the SOAP getDataCenterUrls operation to obtain the correct domain. Or, go to Setup > Company > Company Information in the NetSuite UI. Your domains are listed on the Company URLs tab.

In some circumstances, this error may appear:

You are not requesting the correct data center for your company.

These errors may result from using an incorrect WSDL Download URL in the configuration of a NetSuite connection. Due to changes made by NetSuite, some WSDL URL formats that were previously allowed are no longer accepted, including generic WSDL URLs and data center-specific URLs. For example:

• Generic WSDL URL: https://webservices.netsuite.com/wsdl/v2024_2_0/netsuite.wsdl
• Data Center-Specific WSDL URL: https://webservices.na3.netsuite.com/wsdl/v2024_2_0/netsuite.wsdl

To resolve, change the WSDL URL to use an account-specific domain:

• Account-Specific WSDL URL: https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2024_2_0/netsuite.wsdl

For instructions on finding the NetSuite account-specific domain and then using the account-specific domain in the WSDL URL, see NetSuite account-specific WSDL URL.

NetSuite two-factor authentication (TFA or 2FA)

Those using NetSuite two-factor authentication (TFA or 2FA) should not use the single sign-on (SSO) authentication type when configuring your NetSuite endpoint in Jitterbit. Doing so may cause your NetSuite endpoint to fail. Instead it is recommended for these users to enable token-based authentication (TBA) on your NetSuite account and set up your NetSuite endpoint in Jitterbit accordingly.

NetSuite sandbox WSDL URL

As of January 2018, NetSuite uses the same URL for both their production and sandbox domain. For Design Studio and Agent versions 9.2 and higher, no action is required for Jitterbit users with existing NetSuite endpoints configured for the sandbox domain, as long as the sandbox has been refreshed since this change.

The NetSuite account number is now used to determine whether the account is in production or sandbox. For example, the account ID may be appended with _SB1, _SB2, etc. Because NetSuite no longer uses a separate sandbox URL, and sandbox is now indicated by account ID, the Sandbox checkbox has been removed in Design Studio versions 9.2 and higher.

If your NetSuite sandbox has not been refreshed since these NetSuite changes were implemented, you may need to use a sandbox-specific WSDL URL.

Permissions error for TBA

If you receive an INSUFFICIENT_PERMISSION error upon running operations using a NetSuite endpoint configured with token-based authentication (TBA), you may need to use a different role for generating the access tokens or add permissions to the role you are currently using. In this case, the testing of the endpoint appears successful, but upon runtime of the operation the exception occurs.

To resolve, while generating access tokens, make sure to generate them on either a Full Access or Administrator role or make sure the appropriate permissions are allowed for the role.

Unexpected error for TBA

If you receive an UNEXPECTED_ERROR error upon testing the connection to a NetSuite endpoint configured with token-based authentication (TBA), it is recommended to check to make sure you are using the correct WSDL URL. The error will contain the following text:

FaultString: An unexpected error has occurred. Technical Support has been alerted to this problem.

This error may occur for a number of reasons; however, it is known that this error results from having an incorrect WSDL URL when using Agents that are version 9.2 to 9.5. In Agents version 9.6 and higher, error messaging text more accurately describes the issue.

NetSuite TLS compatibility upgrade

Information about using TLS 1.2 encryption is provided in NetSuite TLS compatibility upgrade.

NetSuite concurrency governance

On August 18, 2017, Netsuite introduced "Concurrency Governance" in its 2017.2 release. If you use web services and/or RESTlets, learn more about how this could affect your integration under NetSuite 2017.2 concurrency governance.

NetSuite saved search limitations

When using NetSuite saved search, if you are trying to search on objects that have more than 1,000 saved searches, it may appear in Jitterbit Studio as if there are no saved searches available on the object. In this case, the saved search dropdown in Jitterbit Studio will not be populated with any saved searches. This is due to a NetSuite-imposed 1,000-record limit on API requests.

Confirmation of limitation

To confirm the issue is with the NetSuite limitation, you can check the Web Services Usage Log within your NetSuite instance. For an error of this type, the log will have an entry similar to the following:

<platformCore:code>MAX_RCRDS_EXCEEDED</platformCore:code>
<platformCore:message>The maximum number ( 1000 ) of records allowed for a READ operation has been exceeded.</platformCore:message>

Workaround to limitation

As a workaround, it is recommended to clean up NetSuite saved searches that are no longer being used to reduce the number of saved searches to fewer than 1,000. After the number of searches is reduced, you will be able to select a saved search from the dropdown in Jitterbit Studio.

An alternative to reducing the number of saved searches is to execute the saved search via SOAP, referencing the saved search by ID. Note that this alternative does not make use of the NetSuite connector and may result in issues when migrating environments.

Advanced functionality

This section provides information on features in Jitterbit that enable you to get more out of your NetSuite integration.

Using NetSuite functions

NetSuite-specific functions available in Formula Builder under Functions > Connector Functions are listed below. For more information on how to use these functions, see Connector functions.

• NetSuiteGetSelectValue: Retrieves the picklist values for a field from NetSuite.
• NetSuiteGetServerTime: Gets the server time from NetSuite.
• NetSuiteLogin: Gets the session from NetSuite.

Using the asynchronous setting

By default, API calls to NetSuite run synchronously; i.e. after a request is made the connection is kept open. If some requests time out during a synchronous poll, you may want turn on the asynchronous setting. With this setting, after the request is submitted, Jitterbit will poll periodically to see if that request is finished. This is most useful with large amounts of data.

To turn on the asynchronous option, set $jitterbit.netsuite.async=true in a script that is, for example, at the beginning of the operation or within the operation chain (see Creating a script). For additional information, see NetSuite documentation on Synchronous Versus Asynchronous Request Processing.

Passing null values to custom fields

A limitation of the NetSuite API is that you cannot pass NULL or blank (empty string) values to custom fields in NetSuite.

According to NetSuite's documentation on CustomFieldList, custom fields can be set to NULL by submitting the field in NetSuite's nullFieldList.

In Design Studio, you will not see nullFieldList as a field or option.

Instead, you can pass NULL or blank (empty string) values to custom fields by mapping the source field to both the externalId and name fields of a target field.

Using NetSuite custom segments

Custom segments on both standard and custom NetSuite objects are supported for the NetSuite Connector Create, Update, GetList, Upsert, and Search activities using a NetSuite endpoint with a NetSuite WSDL that is version 2016.2 or higher. You must be using version 9.4 or higher of both Design Studio and Agents to use this feature.

While configuring any of the activity types listed above, you will see each custom segment displayed in the NetSuite response or request structure:

Once the activity is used in a transformation, you will be able to map from or to any of those custom segments, just as you do for other fields. Custom segments are located under a node called customFieldList that is present within its respective object node.

Limitation

In a NetSuite advanced search, custom segments of the type List/Record as defined in NetSuite are not supported. However, note that the Multiple Select type is supported in a NetSuite advanced search. To determine what type is being used, check the Type defined within NetSuite on your Custom Segment:

This limitation does not apply to other types of NetSuite activities; that is, both the List/Record and Multiple Select types are supported within Create, Update, GetList, Upsert, Basic search, Expanded search, and Saved search activities.

Using NetSuite transaction search by status

When searching for NetSuite transactions based on a specific status, you will need to specify the correct search filter value that corresponds with the desired status. You can determine the corresponding search filter value as provided in the table below.

For example, if you want search criteria to limit the Item Fulfilment records to only ones where the Ship Status = Shipped, instead of using the enum for Shipped (_shipped), you would actually need to use the a value of ItemShip:C as provided in table below. Similar translations apply to a variety of NetSuite objects.

Source: http://blog.prolecto.com/2013/08/30/netsuite-searchfilter-transaction-internal-status-list/

Design patterns

The following design patterns may be useful for NetSuite integrations:

• Capturing data changes with an API Manager API or HTTP endpoint

• Capturing data changes with file sources

• Capturing data changes with source field values

• Capture data changes with table or file changes

• Capturing data changes with timestamp-based queries

• Creating single- or multiple-record output

• Creating transformation iterator dynamically

• Harmony best practices

• Linking source or target records using shared IDs

• Looking up data during runtime

• Looking up data using a dictionary

• Persisting data for later processing using Temporary Storage

• Persisting inbound data for later processing

• Processing target records conditionally

• Running next operations conditionally using operation chains

• Set up a team collaboration project

• Set up alerting, logging, and error handling

• Updating multiple targets from a single source record

• Upserting Clarizen data with a chain of operations