Overview
The following operations allow you to work with fetching. Click an operation name to see details on how to use it.
For a sample proxy service that illustrates how to work with fetching, see Sample configuration.
Operation | Description |
---|---|
Returns a list of records. | |
getCustomizationId | Retrieves the internalIds, externalIds, and scriptIds of all custom objects of a specified type. |
getDataCenterUrls | Used for dynamic discovery of data-center-specific URLs for partner applications' access to NetSuite. |
getItemAvailability | Retrieves the inventory availability. |
getList | Returns one or more records. |
getSelectValue | Retrieves valid values for a given recordRef field. |
search | Searches for specific records. |
Operation details
This section provides details on the operations.
Retrieving a list of records
The getAll
operation is used to retrieve a list of all records of the specified type. Records that support the getAll
operation are listed in GetAllRecordType, as defined in the platformCoreType system constants XSD file.
You must use the getAll
operation instead of the search
operation to retrieve state values. The getAll
operation will return all states, not just the legal ones for your default country. Also note that the country and state must match on the address.
<netsuite.getAll> <record>{$ctx:record}</record> </netsuite.getAll>
Properties
records:
The required record element to be retrieved.
Sample request
Following is a sample SOAP request that can be handled by the getAll
operation.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="wso2.connector.netsuite.getall"> <soapenv:Header></soapenv:Header> <soapenv:Body> <urn:apiUrl>https://webservices.na1.netsuite.com/services/NetSuitePort_2014_1</urn:apiUrl> <urn:warningAsError>true</urn:warningAsError> <urn:disableMandatoryCustomFieldValidation>false</urn:disableMandatoryCustomFieldValidation> <urn:disableSystemNotesForCustomFields>true</urn:disableSystemNotesForCustomFields> <urn:ignoreReadOnlyFields>true</urn:ignoreReadOnlyFields> <urn:partnerId></urn:partnerId> <urn:applicationId></urn:applicationId> <urn:email>user@gmail.com</urn:email> <urn:password>123</urn:password> <urn:account>TVTDRV1193710</urn:account> <urn:roleInternalId></urn:roleInternalId> <urn:roleExternalId></urn:roleExternalId> <urn:roleType></urn:roleType> <urn:roleName></urn:roleName> <urn:record> <platformMsgs:record recordType="state" xmlns:platformMsgs="urn:messages_2014_1.platform.webservices.netsuite.com"/> </urn:record> </soapenv:Body> </soapenv:Envelope>
Retrieving customization ID
When integrating with NetSuite through Web services, in many cases, you will want to know which custom objects exist in an account. You might also want to obtain metadata for these custom objects so that your application can handle any business logic that is specific to the account.
To learn which custom objects exist in an account, use the getCustomizationId
operation to retrieve the internalId
, externalId
, and scriptId
of all custom objects of a specified type. These types, enumerated in CustomizationType
, include the following. The CustomizationType
object is defined in the coreTypes XSD.
crmCustomField
customList
customRecordType
entityCustomField
itemCustomField
itemOptionCustomField
otherCustomField
transactionBodyCustomField
transactionColumnCustomField
Once the IDs are returned, you can pass the ID value(s) to the getList
operation to obtain metadata for specific custom objects (see Using getList with getCustomizationId for more details). If you are returning large sets of metadata, the getCustomizationId
operation allows you to add pagination to break your response into multiple pieces.
To see the UI equivalent of a NetSuite custom object, go to Customization > Lists, Records, and Fields > [custom object type]. For information on working with each object type in Web services, see SuiteBuilder Overview. For a more general understanding of the NetSuite customization model, see SuiteBuilder (Customization).
Normally, you cannot add or update the
internalId
of a NetSuite object. Custom objects are an exception to this rule. You can specify the ID on add, but you cannot update the ID thereafter. Also note that theinternalId
for custom objects can be set to any unique alphanumeric string up to 30 characters long. This string cannot include any spaces, but it can include underscores ( _ ).
<netsuite.getCustomizationId> <customizationType>{$ctx:customizationType}</customizationType> <includeInactives>{$ctx:includeInactives}</includeInactives> </netsuite.getCustomizationId>
Properties
customizationType:
Any of the custom object types enumerated inCustomizationType
.includeInactives:
A value of "true" or "false" is required. A value of "false" means no inactive custom objects are returned in the response. A value of "true" means that both active and inactive custom objects are returned in the response.
Sample request
Following is a sample SOAP request that can be handled by the getCustomizationId
operation.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="wso2.connector.netsuite.getcustomizationid"> <soapenv:Header/> <soapenv:Body> <urn:apiUrl>https://webservices.na1.netsuite.com/services/NetSuitePort_2014_1</urn:apiUrl> <urn:warningAsError/> <urn:disableMandatoryCustomFieldValidation/> <urn:disableSystemNotesForCustomFields/> <urn:ignoreReadOnlyFields/> <urn:partnerId/> <urn:applicationId/> <urn:email>user@gmail.com</urn:email> <urn:password>123</urn:password> <urn:account>TVTDRV1193710</urn:account> <urn:roleInternalId/> <urn:roleExternalId/> <urn:roleType/> <urn:roleName/> <urn:customizationIdReferece > <customizationType getCustomizationType="customRecordType"/> <includeInactives>false</includeInactives> </urn:customizationIdReferece> </soapenv:Body> </soapenv:Envelope>
Retrieving data center URLs
The getDataCenterUrls
operation supports dynamic discovery of the correct URLs for external client access to NetSuite. This discovery is required because NetSuite began hosting new customer accounts in multiple data centers. Each data center has a different domain, so the domain to be used for external client access depends upon the data center hosting each NetSuite account.
This operation supports discovery of the following domains:
restDomain
-https://rest.netsuite.com
orhttps://rest.na1.netsuite.com
(used for RESTlet access)systemDomain
-https://system.netsuite.com
orhttps://system.na1.netsuite.com
webservicesDomain
-https://webservices.netsuite.com
orhttps://webservices.na1.netsuite.com
If you are building an integration for a single customer, you can use this operation to determine the correct URL for that particular customer. If you are building a partner application, you need to incorporate this operation into your application logic so that it can dynamically determine the correct URL for NetSuite access across multiple NetSuite customers.
<netsuite.getDataCenterUrls> <accountRef>{$ctx:accountRef}</accountRef> </netsuite.getDataCenterUrls>
Properties
accountRef:
The details of the account.
Sample request
Following is a sample SOAP request that can be handled by the getDataCenterUrls
operation.
<?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="wso2.connector.netsuite.getdatacenterurls"> <soapenv:Header> </soapenv:Header> <soapenv:Body> <urn:apiUrl>https://webservices.na1.netsuite.com/services/NetSuitePort_2014_1</urn:apiUrl> <urn:warningAsError></urn:warningAsError> <urn:disableMandatoryCustomFieldValidation></urn:disableMandatoryCustomFieldValidation> <urn:disableSystemNotesForCustomFields></urn:disableSystemNotesForCustomFields> <urn:ignoreReadOnlyFields></urn:ignoreReadOnlyFields> <urn:partnerId></urn:partnerId> <urn:applicationId></urn:applicationId> <urn:email>user@gmail.com</urn:email> <urn:password>123</urn:password> <urn:account>TVTDRV11937101</urn:account> <urn:roleInternalId></urn:roleInternalId> <urn:roleExternalId></urn:roleExternalId> <urn:roleType></urn:roleType> <urn:roleName></urn:roleName> <urn:accountRef> <account>TSTDRV11937101</account> </urn:accountRef> </soapenv:Body> </soapenv:Envelope>
Retrieving item availability
The getItemAvailability
operation can be used to retrieve the inventory availability for a given list of items. You can filter the returned list using a lastQtyAvailableChange
filter. If set, only items with a quantity of available changes recorded as of this date are returned. If the Multi-Location Inventory feature is enabled, this operation returns results for all locations. For locations that do not have any items available, only location IDs and names are listed in results.
This operation supports up to 10,000 records. If this limit is exceeded, an error is returned.
<netsuite.getItemAvailability> <itemAvailabilityFilter>{$ctx:itemAvailabilityFilter}</itemAvailabilityFilter> </netsuite.getItemAvailability>
Properties
itemAvailabilityFilter:
Holds details about the item in which the availability data should be retrieved.item:
References an existing item record in NetSuite.lastQtyAvailableChange:
If set, only items with a quantity of available changes recorded as of the specified date are returned.
Sample request
Following is a sample SOAP request that can be handled by the getItemAvailability
operation.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="wso2.connector.netsuite.getitemavailability"> <soapenv:Header></soapenv:Header> <soapenv:Body> <urn:apiUrl>https://webservices.na1.netsuite.com/services/NetSuitePort_2014_1</urn:apiUrl> <urn:warningAsError>true</urn:warningAsError> <urn:disableMandatoryCustomFieldValidation>false</urn:disableMandatoryCustomFieldValidation> <urn:disableSystemNotesForCustomFields>true</urn:disableSystemNotesForCustomFields> <urn:ignoreReadOnlyFields>true</urn:ignoreReadOnlyFields> <urn:partnerId></urn:partnerId> <urn:applicationId></urn:applicationId> <urn:email>user@gmail.com</urn:email> <urn:password>123</urn:password> <urn:account>TVTDRV1193710</urn:account> <urn:roleInternalId></urn:roleInternalId> <urn:roleExternalId></urn:roleExternalId> <urn:roleType></urn:roleType> <urn:roleName></urn:roleName> <urn:itemAvailabilityFilter> <platformMsgs:itemAvailabilityFilter xmlns:platformMsgs="urn:messages_2014_1.platform.webservices.netsuite.com" xmlns:platformCore="urn:core_2014_1.platform.webservices.netsuite.com"> <platformCore:item> <!--Zero or more repetitions:--> <platformCore:recordRef internalId="387" type="inventoryItem"> <!--Optional:--> <platformCore:name></platformCore:name> </platformCore:recordRef> </platformCore:item> <!--Optional:--> <!--if the date is not specified--> <platformCore:lastQtyAvailableChange>2014-04-20T16:09:55.000-07:00</platformCore:lastQtyAvailableChange> </platformMsgs:itemAvailabilityFilter> </urn:itemAvailabilityFilter> </soapenv:Body> </soapenv:Envelope>
Retrieving one or more records
The getList
operation is used to retrieve a list of one or more records by providing the unique IDs that identify those records. If there are multiple IDs provided, they can belong to either the same record type or different record types. For example, it is possible to retrieve a customer and a contact within a single request using this operation.
If some of the provided IDs are invalid, the request is still processed for the valid IDs and the response will contain a warning that indicates that some of the IDs were invalid.
<netsuite.getList> <recordRef>{$ctx:recordRef}</recordRef> </netsuite.getList>
Properties
recordRef:
An array ofrecordRef
objects that specify the IDs of the records to be retrieved.
Sample request
Following is a sample SOAP request that can be handled by the getList
operation.
<?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="wso2.connector.netsuite.getlist"> <soapenv:Header></soapenv:Header> <soapenv:Body> <urn:apiUrl>https://webservices.na1.netsuite.com/services/NetSuitePort_2014_1</urn:apiUrl> <urn:warningAsError></urn:warningAsError> <urn:disableMandatoryCustomFieldValidation></urn:disableMandatoryCustomFieldValidation> <urn:disableSystemNotesForCustomFields></urn:disableSystemNotesForCustomFields> <urn:ignoreReadOnlyFields></urn:ignoreReadOnlyFields> <urn:partnerId></urn:partnerId> <urn:applicationId></urn:applicationId> <urn:email>user@gmail.com</urn:email> <urn:password>123</urn:password> <urn:account>TVTDRV1193710</urn:account> <urn:roleInternalId></urn:roleInternalId> <urn:roleExternalId></urn:roleExternalId> <urn:roleType></urn:roleType> <urn:roleName></urn:roleName> <urn:recordRef> <RecordRef internalId="2857" type="customer" xsi:type="platformCore:RecordRef" xmlns:platformCore="urn:core_2014_1.platform.webservices.netsuite.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/> <RecordRef internalId="3451" type="customer" xsi:type="platformCore:RecordRef" xmlns:platformCore="urn:core_2014_1.platform.webservices.netsuite.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/> </urn:recordRef> </soapenv:Body> </soapenv:Envelope>
Retrieving a selected value
The getSelectValue
operation can be used to retrieve valid select options for a given RecordRef, CustomRecordRef, or enumerated static field. This is useful if you are writing an application UI that needs to mimic NetSuite UI logic, if the referenced record type is not yet exposed in SuiteTalk, or when the logged-in user's role does not have permission to the instances of the referenced record type. A call to getSelectValue
may return different results for the same field for different roles.
The getSelectValue
operation can be used on standard body fields and custom body fields. It can also be used on sublist fields that appear on both standard and custom records. The getSelectValue
operation will not return the following values: "" , (blank), -1, -New-, -2, -Custom-.
If you reference a field or a select value that is renamed in future versions of NetSuite, your requests will still be handled, but a warning will be returned. Also, when working with this operation, be aware of any special permissions applied to a field. For example, a permission error will be thrown if you attempt to get select values on a field that has been disabled on a form.
<netsuite.getSelectValue> <selectValue>{$ctx:selectValue}</selectValue> <pageIndex>{$ctx:pageIndex}</pageIndex> </netsuite.getSelectValue>
Properties
selectValue:
The valid selection options for a givenRecordRef
,CustomRecordRef
, or enumerated static field.pageIndex:
The pagination value.
Sample request
Following is a sample SOAP request that can be handled by the getSelectValue
operation.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="wso2.connector.netsuite.getselectvalue"> <soapenv:Header></soapenv:Header> <soapenv:Body> <urn:apiUrl>https://webservices.na1.netsuite.com/services/NetSuitePort_2014_1</urn:apiUrl> <urn:warningAsError></urn:warningAsError> <urn:disableMandatoryCustomFieldValidation></urn:disableMandatoryCustomFieldValidation> <urn:disableSystemNotesForCustomFields></urn:disableSystemNotesForCustomFields> <urn:ignoreReadOnlyFields></urn:ignoreReadOnlyFields> <urn:partnerId></urn:partnerId> <urn:applicationId></urn:applicationId> <urn:email>user@gmail.com</urn:email> <urn:password>123</urn:password> <urn:account>TVTDRV1193710</urn:account> <urn:roleInternalId></urn:roleInternalId> <urn:roleExternalId></urn:roleExternalId> <urn:roleType></urn:roleType> <urn:roleName></urn:roleName> <urn:selectValue> <fieldDescription xmlns:platformCore="urn:core_2014_1.platform.webservices.netsuite.com"> <platformCore:recordType>salesOrder</platformCore:recordType> <platformCore:sublist>itemList</platformCore:sublist> <platformCore:field>item</platformCore:field> <platformCore:filterByValueList> <platformCore:filterBy> <platformCore:field>entity</platformCore:field> <platformCore:internalId>8</platformCore:internalId> </platformCore:filterBy> </platformCore:filterByValueList> </fieldDescription> <pageIndex>1</pageIndex> </urn:selectValue> </soapenv:Body> </soapenv:Envelope>
Searching for records
The search
operation is used to execute a search on a specific record type based on a set of criteria. You can search by defining search filter fields on the record, joined fields on an associated record, or search return columns or joined search return columns from an associated record. The results of the search can be complete records or a select set of fields specified through search return columns.
You can also use the search
operation to return an existing saved search. You cannot use the search
operation to retrieve state values. Instead, use the getAll operation to retrieve all state values in the system. The getAll
operation will return all states, not just the legal ones for your default country. Also note that the country and state must match on the address.
Use the search
operation to execute the following types of searches:
Basic search — Execute a search on a record type based on search filter fields that are specific to that type. See Basic Searches in Web Services.
Joined search — Execute a search on a record type based on search filter fields on an associated record type. See Joined Searches in Web Services.
Advanced search — Execute a search on a record type in which you specify search filter fields and search return columns or joined search columns. Using advanced search, you can also return an existing saved search. See Advanced Searches in Web Services.
Remove the following parameters in the init
operation before executing the search
operation: warningAsError
, disableSystemNotesForCustomFields
, ignoreReadOnlyFields
, and disableMandatoryCustomFieldValidation
. For example:
<netsuite.init> <apiUrl>{$ctx:apiUrl}</apiUrl> <roleInternalId>{$ctx:roleInternalId}</roleInternalId> <partnerId>{$ctx:partnerId}</partnerId> <applicationId>{$ctx:applicationId}</applicationId> <roleName>{$ctx:roleName}</roleName> <password>{$ctx:password}</password> <roleExternalId>{$ctx:roleExternalId}</roleExternalId> <email>{$ctx:email}</email> <account>{$ctx:account}</account> <roleType>{$ctx:roleType}</roleType> </netsuite.init>
Following is the syntax of the search
operation:
<netsuite.search> <bodyFieldsOnly>{$ctx:bodyFieldsOnly}</bodyFieldsOnly> <returnSearchColumns>{$ctx:returnSearchColumns}</returnSearchColumns> <pageSize>{$ctx:pageSize}</pageSize> <searchRecord>{$ctx:searchRecord}</searchRecord> </netsuite.search>
Properties
bodyFieldsOnly:
Defaults to "true" and indicates that the information in the body fields of the record is returned.returnSearchColumns:
Defaults to "true" meaning that only search columns will be returned in your search.pageSize:
Preferred pagination integer value.searchRecord:
The record or records that need to be searched for.
Sample request
Following is a sample SOAP request that can be handled by the search
operation.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="wso2.connector.netsuite.search"> <soapenv:Header></soapenv:Header> <soapenv:Body> <urn:apiUrl>https://webservices.na1.netsuite.com/services/NetSuitePort_2014_1</urn:apiUrl> <urn:bodyFieldsOnly>true</urn:bodyFieldsOnly> <urn:returnSearchColumns>true</urn:returnSearchColumns> <urn:pageSize></urn:pageSize> <urn:partnerId></urn:partnerId> <urn:applicationId></urn:applicationId> <urn:email>user@gmail.com</urn:email> <urn:password>123</urn:password> <urn:account>TVTDRV1193710</urn:account> <urn:roleInternalId></urn:roleInternalId> <urn:roleExternalId></urn:roleExternalId> <urn:roleType></urn:roleType> <urn:roleName></urn:roleName> <urn:searchRecord> <platformMsgs:searchRecord xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns1:EmployeeSearch" xmlns:ns1="urn:employees_2014_1.lists.webservices.netsuite.com" xmlns:platformMsgs="urn:messages_2014_1.platform.webservices.netsuite.com" xmlns:platformCore="urn:core_2014_1.platform.webservices.netsuite.com"> <basic> <email operator="contains" xsi:type="platformCore:SearchStringField"> <searchValue>.com</searchValue> </email> </basic> </platformMsgs:searchRecord> </urn:searchRecord> </soapenv:Body> </soapenv:Envelope>
Sample configuration
Following is a sample proxy service that illustrates how to connect to NetSuite with the init
operation and use the getAll
operation. The sample request for this proxy can be found in getAll sample request. You can use this sample as a template for using other operations in this category.
<?xml version="1.0" encoding="UTF-8"?> <proxy xmlns="http://ws.apache.org/ns/synapse" name="netsuite_getAll" transports="https,http" statistics="disable" trace="disable" startOnLoad="true"> <target> <inSequence onError="faultHandlerSeq"> <property xmlns:ns="wso2.connector.netsuite.getall" name="apiUrl" expression="//ns:apiUrl/text()"/> <property xmlns:ns="wso2.connector.netsuite.getall" name="warningAsError" expression="//ns:warningAsError/text()"/> <property xmlns:ns="wso2.connector.netsuite.getall" name="disableMandatoryCustomFieldValidation" expression="//ns:disableMandatoryCustomFieldValidation/text()"/> <property xmlns:ns="wso2.connector.netsuite.getall" name="disableSystemNotesForCustomFields" expression="//ns:disableSystemNotesForCustomFields/text()"/> <property xmlns:ns="wso2.connector.netsuite.getall" name="ignoreReadOnlyFields" expression="//ns:ignoreReadOnlyFields/text()"/> <property xmlns:ns="wso2.connector.netsuite.getall" name="partnerId" expression="//ns:partnerId/text()"/> <property xmlns:ns="wso2.connector.netsuite.getall" name="applicationId" expression="//ns:applicationId/text()"/> <property xmlns:ns="wso2.connector.netsuite.getall" name="email" expression="//ns:email/text()"/> <property xmlns:ns="wso2.connector.netsuite.getall" name="password" expression="//ns:password/text()"/> <property xmlns:ns="wso2.connector.netsuite.getall" name="account" expression="//ns:account/text()"/> <property xmlns:ns="wso2.connector.netsuite.getall" name="roleInternalId" expression="//ns:roleInternalId/text()"/> <property xmlns:ns="wso2.connector.netsuite.getall" name="roleExternalId" expression="//ns:roleExternalId/text()"/> <property xmlns:ns="wso2.connector.netsuite.getall" name="roleType" expression="//ns:roleType/text()"/> <property xmlns:ns="wso2.connector.netsuite.getall" name="roleName" expression="//ns:roleName/text()"/> <property xmlns:ns="wso2.connector.netsuite.getall" name="record" expression="//ns:record/*"/> <netsuite.init> <apiUrl>{$ctx:apiUrl}</apiUrl> <warningAsError>{$ctx:warningAsError}</warningAsError> <disableSystemNotesForCustomFields>{$ctx:disableSystemNotesForCustomFields}</disableSystemNotesForCustomFields> <ignoreReadOnlyFields>{$ctx:ignoreReadOnlyFields}</ignoreReadOnlyFields> <disableMandatoryCustomFieldValidation> {$ctx:disableMandatoryCustomFieldValidation} </disableMandatoryCustomFieldValidation> <roleInternalId>{$ctx:roleInternalId}</roleInternalId> <partnerId>{$ctx:partnerId}</partnerId> <applicationId>{$ctx:applicationId}</applicationId> <roleName>{$ctx:roleName}</roleName> <password>{$ctx:password}</password> <roleExternalId>{$ctx:roleExternalId}</roleExternalId> <email>{$ctx:email}</email> <account>{$ctx:account}</account> <roleType>{$ctx:roleType}</roleType> </netsuite.init> <netsuite.getAll> <record>{$ctx:record}</record> </netsuite.getAll> <respond/> </inSequence> <outSequence> <send/> </outSequence> </target> <description/> </proxy>