Integration Record Overview

The integration record enhances your ability to manage and monitor SOAP web services requests sent to your NetSuite account. This capability is particularly useful if you have more than one application that sends requests. For example, your sales department may use one application to send data about new customers. Your HR department may use a different application to update employee records. Each application can be represented by a separate integration record.

For more details, see the following sections:

Benefits of the Integration Record
Application IDs
Endpoint Requirements
Ownership of Integration Records

Benefits of the Integration Record

When you use integration records to represent all of your external applications, you can do any of the following:

View details about each application – Each integration record shows details such as the application’s name and description.
Block an application – You can use an integration record to block SOAP web services requests from the corresponding application. However, if you are using the 2015.1 or an earlier endpoint, be aware that some requests may be handled by the Default Web Services Integrations record, which has its own configuration options. For details, see Blocking SOAP Web Services Requests.
Select permitted authentication methods for an application – When you create an integration record, you can permit the application to authenticate through user credentials, token-based authentication, or both. Note that when a request authenticates through user credentials, the request must also include an application ID, if you want the application’s requests to be tracked by the appropriate integration record. (For details, see Application IDs.) Additionally, be aware that the permitted authentication methods vary depending on which endpoint the request uses. For details, see Endpoint Requirements.

Important:
As of the 2020.2 SOAP web services endpoint, authentication through request-level credentials is not supported. The Passport complex type is not supported. If you attempt to authenticate through request-level credentials in SOAP web services 2020.2 and later endpoints, the web services request is not processed, and an error message is returned. You must ensure that SOAP web services integrations created with 2020.2 and later SOAP web services endpoints use TBA. Authentication through user credentials continues to be supported in integrations that use SOAP web services 2020.1 and earlier endpoints. For more information, see Token-based Authentication and Web Services.
Distribute an integration record – You can bundle an integration record and make it available for installation in other NetSuite accounts. You can also configure a record so that it can be automatically installed in other accounts. For details, see Distributing Integration Records.
View an execution log specific to each application – When you create and use an integration record for each application, that record’s SOAP Web Services Execution Log lets you view only those requests sent by that application. If you are not using unique integration records for each application, you can view all requests together by using the log at Setup > Integration > SOAP Web Services Usage Log. Note that in the case of RESTlets, the execution log only contains data about RESTlets that use token-based authentication.
View a list of all your applications – You can view a list of all your applications at Setup > Integration > Manage Integrations.

Application IDs

Every integration record has a unique application ID. This ID, a 32-character universally unique identifier, is generated when you create the record. The ID is displayed on the integration record in the Application ID field. However, application ID values are displayed only in the NetSuite account where they were created. So, if an integration record was created by a partner and distributed, that record’s application ID is not visible to the partner’s customers when they view the installed record in their own accounts.

In some cases, your SOAP web services requests are required to include an application ID. However, if your request uses token-based authentication, you must omit an application ID.

Use the following guidelines:

Requests that authenticate through user credentials are required to include an application ID, if the request uses the 2015.2 endpoint or later. (For details, see Endpoint Requirements.) If the request uses the 2015.1 endpoint or earlier, an application ID is optional.
Application IDs should not be included in outbound SSO calls, regardless of which endpoint is being used.
If a request uses token-based authentication, you must not include an application ID, regardless of which endpoint you are using. If you include an application ID with a request that uses TBA, the request fails.

Although application IDs are considered identifiers and not authentication credentials, application IDs should nevertheless be considered confidential.

Important:

Some customers may have application IDs that were provided to them by NetSuite Customer Support prior to 2015.2. These older IDs must not be used with the 2015.2 or a later WSDL. Older application IDs are permitted only in requests that use the 2015.1 WSDL or earlier. These requests are logged as part of the Default Web Services Integrations record’s SOAP Web Services Execution Log.

If older application IDs are included in requests that use the 2015.2 or a later WSDL, the requests are denied.

You can identify an old application ID by its length. Old application IDs have a maximum of nine digits. By contrast, new applications IDs are 32-character UUIDs.

Endpoint Requirements

You can use integration records in conjunction with any supported endpoint. However, different requirements exist, depending on your endpoint.

2015.1 and Earlier

If you use the 2015.1 endpoint or earlier, be aware of the following:

You have the option of letting some or all of your requests be tracked by a single integration record called Default Web Services Integrations. This record requires little maintenance, if any. The Default record was automatically created when your account was upgraded to 2015.2 or subsequently, when you enabled the Web Services feature. The behavior of this record is slightly different from the behavior of integration records that you create. For details on this record, see Default Web Services Integrations Record.
Token-based authentication is not supported. If you want a request to be tracked by a specific integration record (other than the Default record), it must authenticate through user credentials and include an application ID. For more details about application IDs, see Application IDs.

2015.2 and Later

If you upgrade to the 2015.2 or a later endpoint, all SOAP web services requests must be associated with an integration record other than the default record. That is, each request must include, either explicitly or implicitly, one of the following types of information:

The application ID that was generated when the integration record was created, in conjunction with valid user credentials. For more details about application IDs, see Application IDs. If you use the login or ssoLogin operation, the application ID can be sent one time per session. For details, see Using Application ID with the Login and ssoLogin Operations.
Token-based authentication details. For details on updating your code to authenticate this way, see Token-Based Authentication Details.

Note:

Only one SOAP web services operation does not require authentication, nor any information identifying the application. It is the getDataCenterUrls.

2016.2 and Later

NetSuite 2016.2 includes two new permissions that make it possible for users other than administrators to view and manage integration records.

The List type Integration Applications permission provides view access to the Integrations list page.

The Full level of the Setup type Integration Application permission provides the ability to view, edit, and create integration records. This permission also provides access to the Integration field on the SOAP Web Services Operations search.

For details about SOAP web services searches, Searching for SOAP Web Services Log Information.

Ownership of Integration Records

When you create an integration record, it is automatically available to you in your NetSuite account. Your NetSuite account is considered to be the owner of the integration record, and the record is fully editable by administrators in your account.

You can also install records in your account that were created elsewhere, as follows:

Installed records can be installed as part of a bundle.
In some cases, integration records can also be auto-installed. With this approach, a record is automatically installed when a request is sent that references the record’s application ID. Auto-installation is supported both for integration records that are configured to permit token-based authentication and authentication through user credentials.

Important:

As of 2019.1, when calling the Issue Token endpoint, an Integration record is created and automatically installed in your account. The Require Approval during Auto-Installation of Integration preference affects whether this new record is automatically enabled. You can manage the preference at Setup > Integration > Integration Management > SOAP Web Services Preferences. If the box for the Require Approval during Auto-Installation of Integration preference is not checked (set to false) the State field on the new application is automatically set to Enabled, and all requests are permitted. However, if the box is checked (set to true) the State field on the new integration record is set to Waiting for Approval. In the latter case, you must manually edit the record and set the State to Enabled. Until you set the state to Enabled, all requests sent by that application are blocked.

Records that are installed through either of these methods are not fully editable, because they are considered to be owned by a different NetSuite account. On such records, you can make changes to only two fields: the Note field and the State field. All other fields on these records, including the permitted authentication options and the Description field, can be changed only by an authorized user in the account that owns the records. When the owner makes changes, they are pushed automatically to your account. These changes are not reflected in the system notes that appear in your account.

For more information about creating integration records, see Creating an Integration Record. For more details about distributing integration records, see Distributing Integration Records.

Benefits of the Integration Record

Application IDs

Endpoint Requirements

2015.1 and Earlier

2015.2 and Later

2016.2 and Later

Ownership of Integration Records

Related Topics