1. SOAP Web Services for Common Features
  2. find Operation

find Operation

The find operation retrieves the service data objects that meet the specified search criteria in the request payload. Use this operation to retrieve a subset of attributes for business objects that consist of entities with many attributes or many service data objects.

You can control the following for the top-level entity and the descendant service data objects:

  • Fetch start and size

  • Filter criteria

  • Sort order

  • List of attributes to include or exclude

Operation Signature

The request payload for the find operation accepts two parameters that control the behavior of the operation. For the definition of the FindCriteria and FindControl types, see Sample BC4JService.xsd.

<element name="findSalesLead">
    <complexType>
        <sequence>
            <element name="findCriteria" type="ns0:FindCriteria"/>
            <element name="findControl" type="ns0:FindControl"/>
        </sequence>
    </complexType>
</element>

Request Payload Parameters

The parameters of the find request payload give extensive control over the search criteria. This figure shows the parameters of the find operation.

find Operation Parameters

This table lists the elements of the request payload and provides a brief description for each element.

Parameter Description
attribute Holds the case sensitive name of the object attribute to filter. All the attributes can be queried.
childFindCriteria Specifies the fetch start, fetch size, filter, sort, and selection criteria for a child service data object that is specified in childAttrName. The childFindCriteria can be nested within another childFindCriteria in order to apply a fetch start, fetch size, and filter, sort and selection criteria to the child and descendants of the top-level object.
conjunction Defines how the search conditions are evaluated in relation to each other. Valid values are And, Or, Not, AndNot, and OrNot. These values are case sensitive.
excludeAttribute Indicates whether the attributes specified by findAttribute elements are not included in the response payload. The default option is false. To reduce the size of the find operation response payload, use excludeAttribute in combination with findAttribute to return only the required elements.
fetchStart Indicates which objects to fetch and which index to fetch from. This is a zero-based index, and the default value is 0. If the value is set to 0, the result set begins with the first row of the data set. If the value is set to 99, the result set begins with the 100th row of the data set.
fetchSize Specifies the maximum number of top-level objects to retrieve. A fetchSize of -1, which is the default value, retrieves all rows up to the maximum fetchSize that meet the search criteria starting from fetchStart. Valid maximum value for fetchSize is 500 rows unless overridden in the service implementation. If fetchSize value is greater than the number of remaining rows, only the remaining rows are returned.
filter Contains the search criteria, which includes the conjunction, group and nested elements. If a filter is not specified, all the rows are retrieved.
Note: Don't use a formular type field in the filter criteria.
findAttribute Specifies the subset of attributes to be retrieved for which the filter criteria are satisfied. If the subset is not specified, all the attributes are fetched. If you want to include the child object in the result set, you must include it in the subset.
findControl Not used in the current release.
findCriteria Contains fetch size, search criteria, sort criteria, and content inclusion or exclusion information for all the service data object levels.
group Contains a set of runtime search conditions for one or more attributes. The group element includes the conjunction, upperCaseCompare, and item elements.
item Contains one run time search condition for an attribute. The item element includes the conjunction, upperCaseCompare, attribute, operator, value, and nested elements.
nested Defines search criteria for child and descendant entities to determine whether the top-level entity must be included in the result. For example, return a parent object if it contains child entities that meet the criteria.
operator Holds the case-sensitive operation to apply to attributes and values. See list of operators.
sortOrder Specifies the sorting order of the result set by setting zero or more sortAttribute child elements. If more than one sortAttribute elements are specified, the sort is based on the order of these elements.
sortAttribute Contains an attribute name and a boolean value to indicate whether the attribute value must be sorted in a descending order. The default sort order is ascending.
upperCaseCompare Indicates whether this is a case insensitive search. The default option is false.
value Holds the attribute filter criteria that can include:

  • An asterisk (*) to match zero or more characters

  • A question mark (?) to match a a single character

To minimize performance impact, ensure that the values don't start with a wildcard; for example, use Foo* instead of *Foo.
Note: The default maximum value for fetch size is 500, unless specified otherwise in the documentation for a specific web service. A single query returns a maximum of 500 rows (objects) regardless of whether the fetchSize parameter in the find operation is set to -1 or a value greater than 500. If you need to fetch more than 500 objects, call the find operation multiple times with different fetchStart values, for example, 0, 500, 1000. This retrieves the results in batches of 500 objects, assuming that the fetch size is 500.

You must specify the childFindCriteria parameter to control the fetch size of a child attribute rowset.

This table lists the operators that can be specified for the operator parameter. Some of these operators may be disabled for specific service data object attributes. For such attributes, you can't use the disabled operators with the findCriteria parameter.

Operator Use for String Yes Use for Dates
= Yes Yes Yes
&amp Yes
&gt; Yes
&gt;= Yes Yes
&lt; Yes Yes
&lt;= Yes Yes
&lt;&gt; Yes Yes Yes
AFTER Yes
BEFORE Yes
BETWEEN Yes Yes Yes
CONTAINS Yes
DOESNOTCONTAIN Yes
ENDSWITH Yes
ISBLANK Yes Yes Yes
ISNOTBLANK Yes Yes Yes
NOTBETWEEN Yes Yes Yes
ONORAFTER Yes
ONORBEFORE Yes
STARTSWITH Yes

Example

This example shows a response payload declaration for the find operation.

<element name="findSalesLeadResponse">
    <complexType>
        <sequence>
            <element maxOccurs="unbounded" minOccurs="0" name="result" type="ns1:MklLead"/>
        </sequence>
    </complexType>
</element>

This example finds the Sales Lead object with LeadId equal to 300100041938883 and returns only a subset of attributes of the object.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns1:findSalesLead
xmlns:ns1="http://xmlns.oracle.com/apps/marketing/leadMgmt/leads/leadService/types/">
            <ns1:findCriteria xmlns:ns2="http://xmlns.oracle.com/adf/svc/types/">
                <ns2:filter>
                    <ns2:group>
                        <ns2:item>
                            <ns2:attribute>LeadId</ns2:attribute>
                            <ns2:operator>=</ns2:operator>
                            <ns2:value>300100041938883</ns2:value>
                        </ns2:item>
                    </ns2:group>
               </ns2:filter>
               <ns2:findAttribute>Name</ns2:findAttribute>
               <ns2:findAttribute>LeadId</ns2:findAttribute>
               <ns2:findAttribute>DealAmount</ns2:findAttribute>
            </ns1:findCriteria>
        </ns1:findLocation>
    </soap:Body>
</soap:Envelope>

The response payload returns only the Name, LeadId, and DealAmount attributes of the Sales Lead object.

<ns0:findSalesLeadResponse xmlns=""
xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ns0="http://xmlns.oracle.com/apps/marketing/leadMgmt/leads/leadService/types/" 
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <ns2:result xmlns:ns0="http://xmlns.oracle.com/adf/svc/types/" 
xmlns:ns1="http://xmlns.oracle.com/apps/marketing/leadMgmt/leads/leadService/"
xmlns:ns2="http://xmlns.oracle.com/apps/marketing/leadMgmt/leads/leadService/types/"
xmlns:ns3="http://xmlns.oracle.com/apps/crmCommon/notes/noteService"
xmlns:ns4="http://xmlns.oracle.com/oracle/apps/marketing/leadMgmt/leads/leadService/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns4:MklLead">
        <ns4:Name>Issaquah Imaging Innovations - Tablets</ns4:Name>
        <ns4:LeadId>300100041938883</ns4:LeadId>
        <ns1:Value>
        <ns4:DealAmount currencyCode="USD" 
xmlns:tns="http://xmlns.oracle.com/adf/svc/errors/">100000</ns4:DealAmount>
    </ns2:result>>
</ns0:findSalesLeadResponse><ns0:findLocationResponse xmlns=""

Related Operations

To retrieve all the attributes of a service data object, use the get operation. This operation is useful when you don't have complex query requirements.

Related Topics
  • Standard CRUD Operations
  • create Operation
  • delete Operation
  • get Operation
  • find by additional predefined search criteria Operation
  • update Operation
  • merge Operation
  • process Operation