Skip to end of metadata
Go to start of metadata

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 (login to NetSuite required).

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/v2020_1_0/netsuite.wsdl
  • https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2019_2_0/netsuite.wsdl
  • https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2019_1_0/netsuite.wsdl
  • https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2018_2_0/netsuite.wsdl
  • https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2018_1_0/netsuite.wsdl
  • https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2017_2_0/netsuite.wsdl
  • https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2017_1_0/netsuite.wsdl
  • https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2016_2_0/netsuite.wsdl
  • https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2016_1_0/netsuite.wsdl
  • https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2015_2_0/netsuite.wsdl

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

Information about which Harmony Agent versions are required for use with the above WSDL versions is provided in Prerequisites on the NetSuite Connector Endpoint page.

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.

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/v2016_2_0/netsuite.wsdl
  • Data Center-Specific WSDL URL: https://webservices.na3.netsuite.com/wsdl/v2016_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/v2016_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.

NOTE: The SSO authentication type is being phased out by NetSuite, and it is now recommended for all users to use TBA.

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.

TIP: More information can be found in NetSuite's documentation About Sandbox Accounts on the NetSuite Domain (login to NetSuite required).

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.

TIP: Detailed instructions are available in NetSuite's documentation Getting Started with Token-based Authentication (login to NetSuite required).

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 (login to NetSuite required).

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 (login to NetSuite required), 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 CreateUpdateGetListUpsert, 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.

NOTE: If your custom segments are not being displayed, check to make sure your NetSuite user account being used in your NetSuite endpoint has the appropriate permissions to interact with the custom segment and object it is associated with.

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 CreateUpdateGetListUpsertBasic SearchExpanded 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.

StatusSearchFilter
 Cash Sale:Unapproved Payment CashSale:A
 Cash Sale:Not Deposited CashSale:B
 Cash Sale:Deposited CashSale:C
 Check:Voided Check:V
 Check:Online Bill Pay Pending Accounting Approval Check:Z
 Commission:Pending Payment Commissn:A
 Commission:Overpaid Commissn:O
 Commission:Pending Accounting Approval Commissn:P
 Commission:Rejected by Accounting Commissn:R
 Commission:Paid in Full Commissn:X
 Statement Charge:Open CustChrg:A
 Statement Charge:Paid In Full CustChrg:B
 Credit Memo:Open CustCred:A
 Credit Memo:Fully Applied CustCred:B
 Customer Deposit:Not Deposited CustDep:A
 Customer Deposit:Deposited CustDep:B
 Customer Deposit:Fully Applied CustDep:C
 Invoice:Open CustInvc:A
 Invoice:Paid In Full CustInvc:B
 Payment:Unapproved Payment CustPymt:A
 Payment:Not Deposited CustPymt:B
 Payment:Deposited CustPymt:C
 Customer Refund:Voided CustRfnd:V
 Quote:Open Estimate:A
 Quote:Processed Estimate:B
 Quote:Closed Estimate:C
 Quote:Voided Estimate:V
 Quote:Expired Estimate:X
 Expense Report:In Progress ExpRept:A
 Expense Report:Pending Supervisor Approval ExpRept:B
 Expense Report:Pending Accounting Approval ExpRept:C
 Expense Report:Rejected by Supervisor ExpRept:D
 Expense Report:Rejected by Accounting ExpRept:E
 Expense Report:Approved by Accounting ExpRept:F
 Expense Report:Approved (Overridden) by Accounting ExpRept:G
 Expense Report:Rejected (Overridden) by Accounting ExpRept:H
 Expense Report:Paid In Full ExpRept:I
 Inventory Count:Open InvCount:A
 Inventory Count:Started InvCount:B
 Inventory Count:Completed/Pending Approval InvCount:C
 Inventory Count:Approved InvCount:D
 Item Fulfillment:Picked ItemShip:A
 Item Fulfillment:Packed ItemShip:B
 Item Fulfillment:Shipped ItemShip:C
 Journal:Pending Approval Journal:A
 Journal:Approved for Posting Journal:B
 Payroll Liability Check:Voided LiabPymt:V
 Opportunity:In Progress Opprtnty:A
 Opportunity:Issued Estimate Opprtnty:B
 Opportunity:Closed – Won Opprtnty:C
 Opportunity:Closed – Lost Opprtnty:D
 Paycheck:Undefined Paycheck:A
 Paycheck:Pending Tax Calculation Paycheck:C
 Paycheck:Pending Commitment Paycheck:D
 Paycheck:Committed Paycheck:F
 Paycheck:Preview Paycheck:P
 Paycheck:Reversed Paycheck:R
 Purchase Order:Pending Supervisor Approval PurchOrd:A
 Purchase Order:Pending Receipt PurchOrd:B
 Purchase Order:Rejected by Supervisor PurchOrd:C
 Purchase Order:Partially Received PurchOrd:D
 Purchase Order:Pending Billing/Partially Received PurchOrd:E
 Purchase Order:Pending Bill PurchOrd:F
 Purchase Order:Fully Billed PurchOrd:G
 Purchase Order:Closed PurchOrd:H
 Return Authorization:Pending Approval RtnAuth:A
 Return Authorization:Pending Receipt RtnAuth:B
 Return Authorization:Cancelled RtnAuth:C
 Return Authorization:Partially Received RtnAuth:D
 Return Authorization:Pending Refund/Partially Received RtnAuth:E
 Return Authorization:Pending Refund RtnAuth:F
 Return Authorization:Refunded RtnAuth:G
 Return Authorization:Closed RtnAuth:H
 Sales Order:Pending Approval SalesOrd:A
 Sales Order:Pending Fulfillment SalesOrd:B
 Sales Order:Cancelled SalesOrd:C
 Sales Order:Partially Fulfilled SalesOrd:D
 Sales Order:Pending Billing/Partially Fulfilled SalesOrd:E
 Sales Order:Pending Billing SalesOrd:F
 Sales Order:Billed SalesOrd:G
 Sales Order:Closed SalesOrd:H
 Tax Liability Cheque:Voided TaxLiab:V
 Sales Tax Payment:Voided TaxPymt:V
 Sales Tax Payment:Online Bill Pay Pending Accounting Approval TaxPymt:Z
 Tegata Payable:Endorsed TegPybl:E
 Tegata Payable:Issued TegPybl:I
 Tegata Payable:Paid TegPybl:P
 Tegata Receivables:Collected TegRcvbl:C
 Tegata Receivables:Discounted TegRcvbl:D
 Tegata Receivables:Endorsed TegRcvbl:E
 Tegata Receivables:Holding TegRcvbl:H
 Transfer Order:Pending Approval TrnfrOrd:A
 Transfer Order:Pending Fulfillment TrnfrOrd:B
 Transfer Order:Rejected TrnfrOrd:C
 Transfer Order:Partially Fulfilled TrnfrOrd:D
 Transfer Order:Pending Receipt/Partially Fulfilled TrnfrOrd:E
 Transfer Order:Pending Receipt TrnfrOrd:F
 Transfer Order:Received TrnfrOrd:G
 Transfer Order:Closed TrnfrOrd:H
 Vendor Return Authorization:Pending Approval VendAuth:A
 Vendor Return Authorization:Pending Return VendAuth:B
 Vendor Return Authorization:Cancelled VendAuth:C
 Vendor Return Authorization:Partially Returned VendAuth:D
 Vendor Return Authorization:Pending Credit/Partially Returned VendAuth:E
 Vendor Return Authorization:Pending Credit VendAuth:F
 Vendor Return Authorization:Credited VendAuth:G
 Vendor Return Authorization:Closed VendAuth:H
 Bill:Open VendBill:A
 Bill:Paid In Full VendBill:B
 Bill:Cancelled VendBill:C
 Bill:Pending Approval VendBill:D
 Bill:Rejected VendBill:E
 Cash Payment:Voided VendPymt:V
 Cash Payment:Online Bill Pay Pending Accounting Approval VendPymt:Z
 Work Order:Pending Build WorkOrd:B
 Work Order:Cancelled WorkOrd:C
 Work Order:In Process WorkOrd:D
 Work Order:Built WorkOrd:G
 Work Order:Closed WorkOrd:H

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:

On This Page

Related Topics

Last updated:  Aug 13, 2020