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:
-
Log in to the NetSuite instance.
-
Go to Setup > Company > Company Information (or search for Company Information).
-
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.
-
Create a new endpoint.
-
For each NetSuite operation, swap the old endpoint with the new one.
-
Refresh the function.
-
Refresh the transformations.
-
Repeat steps 2 to 4 for each NetSuite operation.
Note
Even though it is possible to simply edit the WSDL URL of an existing endpoint and reconfigure the existing activities, this is a discouraged practice. In such a scenario, no validity errors are reported and it is possible to deploy the project, inadvertently overwriting successful operations with ones that fail at runtime due to the WSDL mismatches within schemas.
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.
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.
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.
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.
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 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.
Status | SearchFilter |
---|---|
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: