Advanced Searches in SOAP Web Services

Advanced searching in SOAP web services provides users with the ability to:

• Perform a search that references an existing saved search. See Reference Existing Saved Searches.

• Perform a search that references an existing saved search, and then overrides existing search return columns with new search return columns. See Specify Search Criteria and Search Return Columns.

• Perform a search that references an existing saved search, and then provides additional search filter criteria (on top of the criteria already specified in the saved search). See Specify Search Criteria and Search Return Columns.

• Perform a search that specifies search criteria and search result columns. See Specify Search Criteria and Search Return Columns.

The SOAP web services API includes advanced search objects for all records that have an existing search interface. To see which objects are used to execute advanced searches, see SOAP Objects used in Advanced Searches

For advanced search code samples, see Advanced Search Code Samples.

In case you encounter duplicate or missing search results, ensure your search references an existing saved search in which the results are sorted by Internal ID. For more information about defining the sorting of the results, see Defining a Saved Search.

The following is an XSD snippet of the listRel XSD. This sample provides a high-level overview of advanced search objects and their relationship to the basic search object < Record > Search. In this sample, the objects Customer SearchAdvanced, Customer SearchRow, and Customer SearchRowBasic (not shown in sample) are considered to be advanced search objects in the SOAP web services API.

Reference Existing Saved Searches

Advanced search in SOAP web services lets you reference an existing saved search. Returning saved searches provides you with access to data that otherwise could not be returned in SOAP web services. For example, advanced search lets you return saved searches that include formula filters (in the search criteria) or expressions.

When working with saved searches, two questions come to mind for SOAP web services users:

• Reasons to Reference an Existing Saved Search

• How to Reference an Existing Saved Search

Reasons to Reference an Existing Saved Search

The following use cases illustrate possible scenarios for referencing a saved search:

• You want to return only a subset of data from a record (in other words, data that is specified through the saved search's return columns).

• Your integration application processes a set of records that are identified in a saved search. Periodically, users change the criteria of the search. By referencing a saved search ID, your code can reference their saved search. Developers do not have to change and re-test code every time the search criteria changes.

• You have a complex search that compiles data from many different records. You can create a saved search in the NetSuite UI, and then reference this search in SOAP web services rather than try to code the search in SOAP web services.

• You want to reference an existing saved search based on Leads, for example. You can return all the data provided in this search, and then define additional criteria for the search response. For example, you can return a Leads saved search and then provide additional criteria that returns the leads from this search created with today's date. In other words, if you reference a saved search and add any filter criteria to the search request, the additional criteria will be conjunctive with the saved search criteria.

How to Reference an Existing Saved Search

First you must obtain the saved search ID. You can do so through the UI by going to Lists > Search > Saved Searches. The saved search ID appears in the ID column.

You can also use the getSavedSearch operation to programmatically retrieve a list of saved search IDs for a specific record type. Note that this operation does nothing more than return a list of saved search IDs on a per-record-type basis (for example, all saved search IDs for the customer record type).

You can then use the search() operation, along with the < Record > SearchAdvanced object to return the details of the saved search. The following is a example that shows how to instantiate the CustomerSearchAdvanced object and specify a savedSearchId to return.

          // create search object
CustomerSearchAdvanced customerSearch = new CustomerSearchAdvanced();
 
//set saved search id
customerSearch.savedSearchId="100";
 
// perform the search
NetSuiteService nss = new NetSuiteService(); 
SearchResult result = nss.search(customerSearch); 

        

For more detailed samples, see Advanced Search Code Samples.

Usage Notes

• Only one saved search can be referenced as part of the search call.

• If you reference a saved search that contains search functions, you will get the results back. However, you cannot create an advanced search that uses search functions. Creating a search in SOAP web services that uses search functions is not currently supported.

• If you reference a saved search for which you do not have permission, the exception is ignored and fields have no value (are not in the SOAP response at all).

• If you reference a saved search that contains summary results, you will get the following error:

  We cannot return search columns for summary saved search < saved search ID >

Specify Search Criteria and Search Return Columns

Similar to a basic search, an advanced search allows you search against a specific record type using the fields on that record as search filters. In addition, you can also specify a set of search return columns or joined columns to return.

This kind of advanced search is useful for retrieving only the record data you need rather than the contents of an entire record.

Advanced searches work well, for example, for users who may have a mobile client that needs to display only the name, phone number, and email address of their sales rep contact. Rather than returning all of the data on a contact record, users can create an advanced search that pulls only the relevant information. They are no longer required to download the entire record.

For advanced search code samples that show how to specify both search criteria and search return columns, see Advanced Search Code Samples.

Search Return Columns

The following figures show the UI equivalent of an advanced search that includes search return columns.

1. First, specify the basic search criteria on the Criteria subtab (in this example all customers that have a company name starting with the letter A).

   

2. Next, click the Results subtab to define the search return columns. When your search is executed, your search response will return only the company name, phone, and contact name of all customers whose company starts with the letter A.

   

The following figure shows the results of the search. Only the relevant data are returned.

SOAP Objects used in Advanced Searches

The following summarizes the objects used in different types of advanced searches. For additional details, see Advanced Search Objects Explained and Advanced Search Code Samples.

• To perform a search that specifies search filter criteria and search result columns, use:

  1. < Record > Search

  2. < Record > SearchBasic

  3. < Record > SearchRow

  4. < Record > SearchRowBasic

• To perform a search that references an existing saved search, use:

  < Record > SearchAdvanced

• To perform a search that references an existing saved search, and then overrides existing search return columns with new search return columns, use:

  1. < Record > SearchAdvanced

  2. < Record > SearchRow

  3. < Record > SearchRowBasic

• To perform a search that references an existing saved search, and then provides additional search filter criteria (that is in addition to the criteria already specified in the saved search), use:

  1. < Record > SearchAdvanced

  2. < Record > Search

  3. < Record > SearchBasic

Advanced Search Objects Explained

The < Record >SearchAdvanced object contains:

• a criteria element - references the < Record > Search object through which you specify standard search field criteria. (See Basic Searches in SOAP Web Services for details on the < Record >Search object.)

• a columns element - references the < Record > SearchRow object through which you specify a set of search result columns to return in the response.

• a savedSearchId attribute - references the saved search internal ID (for example, 57, 99, 63).

• a savedSearchScriptId attribute - references a custom saved search ID (for example, customsearch_mySpecialSearch).

The XSD sample below shows the CustomerSearchAdvanced object:

          <complexType name=" CustomerSearchAdvanced ">
   <complexContent>
      <extension base="platformCore:SearchRecord">
         <sequence>
            <element name=" criteria " type="listRel:CustomerSearch" minOccurs="0"/>
            <element name=" columns " type="listRel:CustomerSearchRow" minOccurs="0"/>
            </sequence>
            <attribute name=" savedSearchId " type="xsd:string"/>
            <attribute name=" savedSearchScriptId " type="xsd:string"/>
         </extension> 

        

The < Record >SearchRow object contains:

• a basic element - references the < Record > SearchRowBasic object, which specifies available search return columns and column joins for that record type.

• <xxx>Join elements - references the < Record > SearchRowBasic object, which specifies search return columns and column joins for the associated record type.

The XSD below shows a snippet of the CustomerSearchRow object:

          <complexType name=" CustomerSearchRow ">
   <complexContent>
      <extension base="platformCore:SearchRow">
           <sequence>
             <element name=" basic " type="platformCommon:CustomerSearchRowBasic"
               minOccurs="0"/>
             <element name=" callJoin " type="platformCommon:PhoneCallSearchRowBasic"
            minOccurs="0"/>
             <element name=" campaignResponseJoin "type="platformCommon:CampaignSearchRowBasic"
            minOccurs="0"/>
         <element name=" caseJoin " type="platformCommon:SupportCaseSearchRowBasic"
            minOccurs="0"/>
            ......
          </sequence>
      </extension>
   </complexContent>
</complexType> 

        

The < Record >SearchRowBasic object contains:

• search result column elements - use to define specific column names in your response.

The next snippet shows the CustomerSearchRowBasic object, which, like ALL < Record > SearchRowBasic objects, resides in the platformCommon XSD. This object lists all available search return columns for the Customer record.

          <complexType name=" CustomerSearchRowBasic ">
        <sequence>
            <element name=" accountNumber " type="platformCore: SearchColumnStringField " minOccurs="0"
      maxOccurs="unbounded"/>
            <element name=" address " type="platformCore: SearchColumnStringField " minOccurs="0"
      maxOccurs="unbounded"/>
            <element name=" addressee " type="platformCore: SearchColumnStringField " minOccurs="0"
      maxOccurs="unbounded"/>
            <element name=" addressLabel " type="platformCore: SearchColumnStringField " minOccurs="0"
      maxOccurs="unbounded"/>
           ...

        </sequence>
    </complexType> 

        

Note that all search return columns reference SearchColumn< xxx >Field objects. See Search Column Custom XML Schema Types for definitions of each search column object.

The default value for returnSearchColumns is TRUE.

           <complexType name="SearchPreferences">
 <sequence>
  <element name="bodyFieldsOnly" minOccurs="0" type="xsd:boolean" default="true"/>
  <element name=" returnSearchColumns " minOccurs="0" type="xsd:boolean"
      default="true"/>
  <element name="pageSize" minOccurs="0" type="xsd:int"/>
 </sequence>
</complexType> 

        

General Notices