Cloud Documentation
Advanced Search


Getting Started with Web Services
Close Window

Table of Contents

Show All | Collapse

3 Understanding a Business Object Service

This section describes a business object service, the artifacts in the service interface, and datatypes and operations which are common to these services.

Because the business object services are implemented using the Oracle Application Development Framework (ADF) framework, the datatypes, service interface, and standard operations across the business object services are similar.

Topics:

About Business Objects

The business object which the service implements is composed of a hierarchy of service data objects, also known as Oracle Application Development Framework (ADF) service data objects. Each service data object is a logical entity that contains a collection of attributes, also referred to as service data object attributes.

As an example, the Opportunity Service is defined on the Opportunity business object. The Opportunity business object is comprised of many service data objects such as Opportunity Contact and Opportunity Lead. The following diagram shows the service data objects as rectangles and relationships between the entities as lines. The Opportunity entity is the top level entity and has many child entities such as Opportunity Contact, Opportunity Lead and Opportunity Revenue. It has one grandchild entity, Note Descriptive Flexfields

The Opportunity service data object contains attributes that describe the object. OptyNumber, PartyName, AccountNumber, and OpportunityContact are examples of attributes defined on the Opportunity service data object. The attributes may have a built-in data type such as long and string, or may have a complex data type that corresponds to another service data object. For more information on the datatypes for service data object attributes, see About Datatypes.

Relationships between service data objects and entities

About Service Interface Artifacts

Topics

The service interface is defined in three artifacts:

  • Service WSDL. The WSDL contains the standard WSDL elements and annotations which describe the service metadata, display name and service, operation and operation payload elements.

  • Service XSD. The request and response payload types are defined in a separate XSD with the same name as the WSDL but with the .xsd prefix.

  • Service Data Object XSDs. Each service data object has one XSD which defines the entity as a complex type and the attributes are elements in the complex type. The XSD additionally includes annotations for the entity display name and entity and attribute descriptions.

Service WSDL

The service WSDL follows the standard structure of the WSDL document. For more information about the WSDL specification, see http://www.w3.org/TR/wsdl.

  • Namespace declarations

  • WSDL documentation which includes the display name, description, operation name, description and request and response payload element descriptions

  • Partner link definition

  • Security policy definition

  • Type definition through imports of XSDs

  • Message definition

  • Port type and operation definition

  • Binding definition

  • Service definition

As an example, the Opportunity Service interface is defined in the OpportunityService.wsdl.

Service XSD

The basic structure of the service XSD is:

  • Namespace declarations.

  • Imports and includes of other service data object XSDs on which it has dependencies.

  • Definition of the elements of the request and response payloads for synchronous and asynchronous versions for all service operations. Note that the element names start with the operation names and the suffix determines whether it is a request or response, and synchronous or asynchronous payload elements.

The following is an excerpt from the OpportunityService.xsd. For more information about the XML Schema specification, refer to http://www.w3.org/XML/Schema.html.

<schema 
xmlns:ns0="http://xmlns.oracle.com/apps/sales/opptyMgmt/opportunities/opportunityService/"
xmlns:ns1="http://xmlns.oracle.com/apps/scm/productModel/deleteGroups/publicModel/
" xmlns:ns2="http://xmlns.oracle.com/adf/svc/types/"
xmlns:ns3="http://xmlns.oracle.com/apps/sales/opptyMgmt/revenues/revenueService/"
xmlns:tns="http://xmlns.oracle.com/apps/sales/opptyMgmt/opportunities/opportunityService/types/"
xmlns="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
targetNamespace="http://xmlns.oracle.com/apps/sales/opptyMgmt/opportunities/opportunityService/types/">
    <import namespace="http://xmlns.oracle.com/adf/svc/types/" 
schemaLocation="https://crm-your-cloud-hostname:port/opptyMgmtOpportunities/OpportunityService?XSD=/META-INF/wsdl/BC4JService.xsd"/>
    <import namespace="http://xmlns.oracle.com/sales/opptyMgmt/revenues/revenueService/"
schemaLocation="https://crm-your-cloud-hostname:port/opptyMgmtOpportunities/OpportunityService?XSD=/oracle/apps/sales/opptyMgmt/revenues/revenueService/Revenue.xsd"/>
    <import namespace="http://xmlns.oracle.com/adf/svc/types/" schemaLocation="https://crm-your-cloud-hostname:port/opptyMgmtOpportunities/OpportunityService?XSD=/META-INF/wsdl/BC4JServiceCS.xsd"/>
    <import namespace="http://xmlns.oracle.com/apps/scm/productModel/deleteGroups/publicModel/" 
schemaLocation="https://crm-your-cloud-hostname:port/opptyMgmtOpportunities/OpportunityService?XSD=/oracle/apps/scm/productModel/deleteGroups/publicModel/DeleteEntity.xsd"/>
    ...
    <element name="getOpportunity">
        <complexType>
           <sequence>
               <element name="optyId" type="long"/>
           </sequence>
        </complexType>
    </element>
    <element name="getOpportunityResponse">
        <complexType>
           <sequence>
               <element name="result" type="ns0:Opportunity"/>
           </sequence>
        </complexType>
    </element>
    ...
    <element name="getOpportunityAsync">
        <complexType>
           <sequence>
               <element name="optyId" type="long"/>
           </sequence>
        </complexType>
    </element>
    <element name="getOpportunityAsyncResponse">
        <complexType>
           <sequence>
               <element name="result" type="ns0:Opportunity"/>
           </sequence>
        </complexType>
    </element>
    ...
</schema>

Service Data Object XSDs

The service data objects and their attributes are described in an XSD which is part of the service interface. Each entity has its own XSD. For example, the Opportunity entity is defined in Opportunity.xsd, the Opportunity Contact is defined in the OpportunityContact.xsd, and the Opportunity Lead is defined in OpportunityLead.xsd. Each service data object is uniquely defined by a QName.

The basic structure of the XSD corresponding to a service data object is:

  • Namespace declarations.

  • Imports and includes of other XSDs on which it has dependencies.

  • Schema documentation which includes the display name, description and name and description of the service data object attributes.

  • Definition of derived types. For example, when service warnings are enabled in the service implementation a wrapper type is defined.

  • Definition of the service data object which is a complex type. The service data object attributes are defined as elements in the complex type.

  • Definition of the element which has a type set to the complex type.

The following is the excerpt from the Opportunity.xsd.

<xsd:schema xmlns:ns0="http://xmlns.oracle.com/adf/svc/types/"
xmlns:ns1="http://xmlns.oracle.com/apps/sales/opptyMgmt/revenues/revenueService/" 
xmlns:ns2="http://xmlns.oracle.com/apps/crmCommon/notes/noteService" 
xmlns:ns3="http://xmlns.oracle.com/oracle/apps/sales/opptyMgmt/revenues/revenueService/" 
xmlns:ns4="http://xmlns.oracle.com/apps/crmCommon/activities/activitiesService/" 
xmlns:sdo="commonj.sdo" xmlns:sdoJava="commonj.sdo/java" 
xmlns:sdoXML="commonj.sdo/xml" 
xmlns="http://xmlns.oracle.com/apps/sales/opptyMgmt/opportunities/opportunityService/" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
targetNamespace="http://xmlns.oracle.com/apps/sales/opptyMgmt/opportunities/opportunityService/"
sdoJava:package="oracle.apps.sales.opptyMgmt.opportunities.opportunityService">
   <xsd:annotation>
       <xsd:documentation xmlns:oer="http://xmlns.oracle.com/oer">
           <name>Opportunity</name>
           <description>An opportunity is used by a sales organization to track 
           information about a potential sale such as the sales account, key
           contacts, product interests, and potential revenues.
           </description>
           <oer:attributes>
           <oer:attribute name="BudgetAvailableDate" description="Date when 
           the budget will be available."/>
           <oer:attribute name="BudgetedFlag" description="Indicates if the 
           opportunity sales account has its budget approved for the potential 
           purchase."/>
           <oer:attribute name="PrimaryOrganizationId" description="Identifier 
           of the business unit to which this opportunity belongs."/>
           </oer:attributes>
       </xsd:documentation>
   </xsd:annotation>
   <xsd:import namespace="http://xmlns.oracle.com/adf/svc/types/"
   schemaLocation="https://crm-your-cloud-hostname:port/opptyMgmtOpportunities/
   OpportunityService?XSD=/META-INF/wsdl/BC4JService.xsd"/>
   <xsd:import namespace="http://xmlns.oracle.com/apps/sales/opptyMgmt/revenues/revenueService/"
   schemaLocation="https://crm-your-cloud-hostname:port/opptyMgmtOpportunities/
   OpportunityService?XSD=/oracle/apps/sales/opptyMgmt/revenues/revenueService/Revenue.xsd"/>
   ...
   <xsd:complexType name="Opportunity">
       <xsd:annotation>
           <xsd:appinfo source="http://xmlns.oracle.com/adf/svc/metadata/">
               <key xmlns="http://xmlns.oracle.com/adf/svc/metadata/">
                   <attribute>OptyId</attribute>
               </key>
           </xsd:appinfo>
       </xsd:annotation>
       <xsd:sequence>
           <xsd:element name="BudgetAvailableDate" type="ns0:date-Date" 
           minOccurs="0" nillable="true"/>
           <xsd:element name="BudgetedFlag" type="xsd:boolean" minOccurs="0" 
           nillable="true"/>
           <xsd:element name="PrimaryOrganizationId" type="xsd:long" minOccurs="0" 
           sdoXML:dataType="sdoJava:LongObject"/>
           ...
       </xsd:sequence>
   </xsd:complexType>
   <xsd:element name="opportunity" type="Opportunity"/>
</xsd:schema>

About Datatypes

Topics

The datatype of the service operation payload elements and service data object attributes can be one of these types:

  1. Built-in datatypes

  2. Complex types defined by Oracle Fusion Middleware, such as Application Development Framework (ADF)

  3. Complex types defined by Oracle Fusion Applications which are effectively service data objects

Built-In Datatypes

This section describes the built-in datatypes of service operation payload elements and service data object attributes as they are represented in the service XSD and service data object XSDs. These built-in datatypes are defined in the http://www.w3.org/2001/XMLSchema namespace.

  • anyType: Service operation payload elements and service data object attributes are strongly typed. There are a few exceptions. anyType is used as the service operation parameter type for the custom business object services such as the Marketing Custom Business Object service which processes custom business objects defined in Application Composer.

  • boolean

  • byte

  • decimal

  • double

  • float

  • int

  • integer

  • long

  • short

  • string

The hexBinary, dateTime, time and date built-in datatypes are not used in the business object interface. Complex types defined by Oracle Fusion Middleware are used in place of those datatypes.

Complex Datatypes Defined by Oracle Fusion Middleware

The datatypes described in this section are complex datatypes which are defined by Oracle Fusion Middleware. With the exception of AmountType and MeasureType, they are used as datatypes for service operation payload elements and service data object attributes. AmountType and MeasureType are only used in service data object attributes.

These complex datatypes are defined in two XML schema files: BC4JService.xsd and BC4JServiceCS.xsd. For BC4JService.xsd schema, see Sample BC4JService.xsd. To view the BC4JService.xsd and BC4JServiceCS.xsd schema on a cloud instance, follow the instructions in About Operations to replace the tokens in the following URLs:

  • For all complex type definitions except ProcessData, reference:

    https://atf_server:PortNumber/fndAppCoreServices/ServiceCatalogService?XSD=/META-INF/wsdl/BC4JService.xsd
    
  • For ProcessData type definition only, reference:

    https://atf_server:PortNumber/fndAppCoreServices/ServiceCatalogService?XSD=/META-INF/wsdl/BC4JServiceCS.xsd
    

The following table lists the commonly used complex types defined by Oracle Fusion Middleware. This is not an exhaustive list.

Complex Type QName Description

{http://xmlns.oracle.com/adf/svc/types/}AmountType

Service data object attributes which contain a value corresponding to an amount or price in a particular currency is of this type. They typically have names that end in Amount or Price.

The attributes of this type captures both the currency and the amount in the currency.

{http://xmlns.oracle.com/adf/svc/types/}base64Binary-DataHandler

Type that stores BLOBs and CLOBs.

{http://xmlns.oracle.com/adf/svc/types/}date-Date

Type that stores dates.

{http://xmlns.oracle.com/adf/svc/types/}dateTime-Timestamp

Type that stores timestamps.

{http://xmlns.oracle.com/adf/svc/types/}FindControl

Type for one of the find operation parameters. This is not being used in the current release and is intended for future use.

{http://xmlns.oracle.com/adf/svc/types/}FindCriteria

Type for one of the find operation parameters that controls the fetch start, fetch size, search criteria, sort order, and attribute inclusion or exclusion.

Details on using this data are provided in find Operation.

{http://xmlns.oracle.com/adf/svc/types/}MeasureType

Service data object attributes that contain a value corresponding to a quantity in a specified unit of measure. They typically have names that end in Measure or Quantity.

The attributes of this type capture both the quantity and the unit of measure

{http://xmlns.oracle.com/adf/svc/types/}MethodResult

Type that stores zero or more service warning messages. When service warnings are enabled on the underlying service data object implementation, this is the return object type of the delete operation.

{http://xmlns.oracle.com/adf/svc/types/}ObjAttrHints

Type of getDfltObjAttrHints return value that is effectively a name-value pair of (1) name, plural name and description of the service data object; and (2) UI hints for the service data object attributes.

{http://xmlns.oracle.com/adf/svc/types/}ProcessControl

Type of one of the process and processCS operation parameters that controls the amount of data to return in the response payload and whether partial failure is allowed.

{http://xmlns.oracle.com/adf/svc/types/}ProcessData

Type of one of the processCS operation parameters.

{http://xmlns.oracle.com/adf/svc/types/}StringResult

Type of return parameter for custom service operations that returns multiple string return values and warning messages. This type is used only when service warnings are enabled.


Complex Types Defined by Oracle Fusion Applications

There are several complex datatypes defined by Oracle Fusion Applications:

  • Service data objects. These are defined as an element which is a complex type composed of a sequence of elements. The service data object attributes are defined as the elements in the complex type. Opportunity, Opportunity Lead, and Opportunity Contact are examples of service data objects defined on the Opportunity Service. For more information about the definition of the Opportunity service data object, see Service Data Object XSDs.

  • Complex types related to the service data objects and extend the {http://xmlns.oracle.com/adf/svc/types/}MethodResult type. This type is defined for service data objects which have been designed with service warnings enabled, and can contain both service data object and warning messages. For more information, see the example in the topic: create Operation.

About Operations

Topics

This section covers the standard operations that may be exposed on the service. In addition to the standard operations, the service may expose custom operations which have signatures and behaviors that are unique to that service.

Message Pattern

All operations exposed on the business object service have both the synchronous and asynchronous versions defined. For conciseness, the service documentation only includes the definition for the synchronous message pattern. The behavior and request and response payloads are the same for both synchronous and asynchronous operations.

The naming convention for the asynchronous operation is:

  • The asynchronous operation name is the synchronous operation name appended with Async

  • The callback name is the synchronous operation name appended with AsyncResponse

Using the Opportunity Service as an example, here are the synchronous and asynchronous create operation names:

  • Synchronous create operation name: createOpportunity

  • Asynchronous create operation name: createOpportunityAsync

  • Asynchronous create operation callback name: createOpportunityAsyncResponse

Standard CRUD Operations

This section covers basic information about the standard create, read, update, and delete (CRUD) operation behavior, interface, examples, and related operations. This table lists all of the operations with a brief description.

Operation Method Name Operation Description

create Operation

createServiceDataObjectName

Creates a service data object and its descendants.

delete Operation

deleteServiceDataObjectName

Deletes a business object.

get Operation

getServiceDataObjectName

Gets a single business object by primary key.

find Operation

findServiceDataObjectName

Finds and returns a list of business objects which meet the search criteria specified by the caller.

find by additional pre-defined search criteria

findServiceDataObjectName><SearchCriteriaName

Finds and returns a list of business objects which meet the search criteria specified by the caller and the additional pre-defined search criteria.

update Operation

updateServiceDataObjectName

Updates a business object.

merge Operation

mergeServiceDataObjectName

Updates a business object if it exists, otherwise creates a new business object.

process Operation

processServiceDataObjectName

Performs a create, update, delete, or merge operation on a list of business objects. The specified operation is applied to all objects in the given list.

Process Change Summary

processCSServiceDataObjectName

Performs a create, update, or delete operation on a list of business objects. Different operations may be applied to different objects.


create Operation

The create operation validates and creates the business object passed in the request payload. The business object includes the top-level object entity as well as the descendant object entities.

The create operation handles the following service data object attribute values in the request payload:

Request Payload Element Handling in Create Operation

The service data object attribute is not included in the request payload. This is the absent element case.

If it has a default value defined, the default value will be set on the new row.

The service data object attribute is included in the payload and has an empty element. For example: <attributeName/> and <attributeName></attributeName>

If the attribute is nillable, then this is treated as a nil.

If the attribute is not nillable, then this is treated as nil and is an invalid input

The service data object attribute value is included in the payload and has a nil value. For example: <attributeName xsi:nil="true">

If the attribute is nillable, then this is treated as a nil.

If the attribute is not nillable, then this is treated as nil and is an invalid input

The service data object attribute is included in the payload and is not an empty element, and non-nil value.

The service data object attribute value is set to the specified value.


Topics

Operation Signature

Using the LocationService as an example, the following is the signature of the create operation. It accepts the business object to be defined. In this case, the operation request payload is named createLocation and the business object it defines is a location object with the type Location.

<element name="createLocation">
     <complexType>
         <sequence>
            <element name="location" type="ns1:Location"/>
         </sequence>
     </complexType>
</element>

After successfully creating the business object, the create operation returns the newly defined business object in the response payload. Because the underlying service data object in the LocationService has service warnings enabled, the createLocation operation may return service warnings which could be generated during object creation in addition to the location object. The datatype that stores both pieces of information is LocationResult. The LocationResult type is basically a wrapper which allows the result of Location type to be returned in addition to warning messages.

<element name="createLocationResponse">
     <complexType>
         <sequence>
            <element name="result" type="ns1:LocationResult"/>/>
         </sequence>
     </complexType>
</element>

The LocationResult type extends the MethodResult type. For the definition of the MethodResult type, see Sample BC4JService.xsd. The maxOccurs is set to unbounded instead of 1, the reason being that the same type is used for the find and process operations, described in a later section, which return multiple objects.

<xsd:complexType name="LocationResult">
    <xsd:complexContent>
         <xsd:extension base="ns0:MethodResult">
             <xsd:sequence>
                 <xsd:element name="Value" type="Location" minOccurs="0" 
                 maxOccurs="unbounded"/>
             </xsd:sequence>
         </xsd:extension>
    </xsd:complexContent>
</xsd:complexType>

For services that do not have service warnings enabled, the response payload returns the business object itself. For example, the createOpportunity operation defined on the OpportunityService has a request and response payload that accepts and returns the opportunity object which is of type Opportunity.

<element name="createOpportunity">
    <complexType>
        <sequence>
            <element name="opportunity" type="ns0:Opportunity"/>
        </sequence>
    </complexType>
</element>

<element name="createOpportunityResponse">
    <complexType>
        <sequence>
            <element name="result" type="ns0:Opportunity"/>
        </sequence>
    </complexType>
</element> 

Example

The following XML fragment is an example request payload for the createLocation operation defined on the http://xmlns.oracle.com/apps/cdm/foundation/parties/locationService/applicationModule/}LocationService. It creates a location for 1 Oracle Parkway, Redwood Shores, CA 94065, US by using the AMS module, which is a module registered as a lookup code for the HZ_CREATED_BY_MODULES lookup type.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns1:createLocation 
        xmlns:ns1="http://xmlns.oracle.com/apps/cdm/foundation/parties/
        locationService/applicationModule/types/">
            <ns1:location
            xmlns:ns2="http://xmlns.oracle.com/apps/cdm/foundation/parties/
            locationService/">
                <ns2:Address1>1 Oracle Parkway</ns2:Address1>
                <ns2:City>Redwood Shores</ns2:City>
                <ns2:State>CA</ns2:State>
                <ns2:Country>US</ns2:Country>
                <ns2:PostalCode>94065</ns2:PostalCode>
                <ns2:CreatedByModule>AMS</ns2:CreatedByModule>
            </ns1:location>
        </ns1:createLocation>
    </soap:Body>
</soap:Envelope>

The following XML fragment is returned in the response payload by the previous example request. It contains the complete definition of the newly created location business object.

<ns0:createLocationResponse xmlns=""
xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ns0="http://xmlns.oracle.com/apps/cdm/foundation/parties/locationService/
applicationModule/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/cdm/foundation/parties/locationService/" 
xmlns:ns2="http://xmlns.oracle.com/apps/cdm/foundation/parties/locationService/
applicationModule/types/"
xmlns:ns3="http://xmlns.oracle.com/apps/cdm/foundation/parties/partyService/"
xmlns:ns4="http://xmlns.oracle.com/apps/cdm/foundation/parties/flex/location/" 
xmlns:tns="http://xmlns.oracle.com/adf/svc/errors/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:type="ns1:LocationResult">
      <ns1:Value>
         <ns1:LocationId>300100039119119</ns1:LocationId>
         <ns1:LastUpdateDate>2014-04-22T23:43:17.153-07:00</ns1:LastUpdateDate>
         <ns1:LastUpdatedBy>SALES_ADMIN</ns1:LastUpdatedBy>
         <ns1:CreationDate>2014-04-22T23:43:17.001-07:00</ns1:CreationDate>
         <ns1:CreatedBy>SALES_ADMIN</ns1:CreatedBy>
         <ns1:LastUpdateLogin>F7B103E144504B3CE0433A90F50A0448
         </ns1:LastUpdateLogin>
         <ns1:RequestId xsi:nil="true"/>
         <ns1:OrigSystem xsi:nil="true"/>
         <ns1:OrigSystemReference>300100039119119</ns1:OrigSystemReference>
         <ns1:Country>US</ns1:Country>
         <ns1:Address1>1 Oracle Parkway</ns1:Address1>
         <ns1:Address2 xsi:nil="true"/>
         <ns1:Address3 xsi:nil="true"/>
         <ns1:Address4 xsi:nil="true"/>
         <ns1:City>Redwood Shores</ns1:City>
         <ns1:PostalCode>94065</ns1:PostalCode>
         <ns1:State>CA</ns1:State>
         <ns1:Province xsi:nil="true"/>
         <ns1:County xsi:nil="true"/>
         <ns1:AddressStyle xsi:nil="true"/>
         <ns1:ValidatedFlag>false</ns1:ValidatedFlag>
         <ns1:AddressLinesPhonetic xsi:nil="true"/>
         <ns1:PostalPlus4Code xsi:nil="true"/>
         <ns1:Position xsi:nil="true"/>
         <ns1:LocationDirections xsi:nil="true"/>
         <ns1:AddressEffectiveDate xsi:nil="true"/>
         <ns1:AddressExpirationDate xsi:nil="true"/>
         <ns1:ClliCode xsi:nil="true"/>
         <ns1:Language xsi:nil="true"/>
         <ns1:ShortDescription xsi:nil="true"/>
         <ns1:Description xsi:nil="true"/>
         <ns1:SalesTaxGeocode xsi:nil="true"/>
         <ns1:SalesTaxInsideCityLimits>1</ns1:SalesTaxInsideCityLimits>
         <ns1:FaLocationId xsi:nil="true"/>
         <ns1:ObjectVersionNumber>1</ns1:ObjectVersionNumber>
         <ns1:CreatedByModule>AMS</ns1:CreatedByModule>
         <ns1:GeometryStatusCode>DIRTY</ns1:GeometryStatusCode>
         <ns1:ValidationStatusCode xsi:nil="true"/>
         <ns1:DateValidated xsi:nil="true"/>
         <ns1:DoNotValidateFlag xsi:nil="true"/>
         <ns1:Comments xsi:nil="true"/>
         <ns1:HouseType xsi:nil="true"/>
         <ns1:EffectiveDate>2014-04-22</ns1:EffectiveDate>
         <ns1:AddrElementAttribute1 xsi:nil="true"/>
         <ns1:AddrElementAttribute2 xsi:nil="true"/>
         <ns1:AddrElementAttribute3 xsi:nil="true"/>
         <ns1:AddrElementAttribute4 xsi:nil="true"/>
         <ns1:AddrElementAttribute5 xsi:nil="true"/>
         <ns1:Building xsi:nil="true"/>
         <ns1:FloorNumber xsi:nil="true"/>
         <ns1:StatusFlag>true</ns1:StatusFlag>
         <ns1:InternalFlag>false</ns1:InternalFlag>
         <ns1:TimezoneCode xsi:nil="true"/>
         <ns1:Latitude xsi:nil="true"/>
         <ns1:Longitude xsi:nil="true"/>
         <ns1:Distance xsi:nil="true"/>
       </ns1:Value>
   </ns2:result>
</ns0:createLocationResponse>

Related Options

The create operation is used to create a completely new business object and cannot be used to create a new child object on an existing parent entity. Use the merge operation to create a new child on an existing parent entity.

Consider using the process operation to create many objects in a single request. As discussed in a later section, the process operation allows the caller to control whether the response has no value returned, the response has just the primary keys or the response has the entire object. Additionally, consider using the process operation when the business object being created is large and when the values in the response payload are not needed.

delete Operation

The delete operation deletes existing rows in the top-level service data object, and depending on the business object requirements may delete the children and descendant entities. The delete may be a hard delete (for example, row is deleted from database table) or a soft delete (for example, status on row is updated to indicate that it is deleted) depending on the requirements of the business object. For more information about the delete operation defined on a particular service, see the operation descriptions in OER.

If it functionally makes sense to delete child or descendant entities independently of the top-level entity, the service may expose additional delete operations on the other child entities. For example, the Opportunity Service exposes a deleteOpportunity operation as well as a deleteOpportunityCompetitor, deleteOpportunityRevenue and other delete operations on the child entities.

Topics

Operation Signature

Here is the signature of the deleteLocation operation for the LocationService. It accepts the location business object to be deleted. Note that while the deleteLocation operation accepts a Location object as the input parameter, the attributes in the object do not need to be populated. Only the primary key or alternate key attributes are required.

<element name="deleteLocation">
    <complexType>
        <sequence>
            <element name="location" type="ns1:Location"/>
        </sequence>
    </complexType>
</element>

The operation returns the successfully updated object. Because the LocationService has service warnings enabled, this operation returns MethodResult instead of an empty payload. For the definition of the MethodResult type. see Sample BC4JService.xsd.

<element name="deleteLocationResponse">
    <complexType>
        <sequence>
            <element name="location" type="ns0:MethodResult"/>
        </sequence>
    </complexType>
</element>

Example

This example deletes the Location with internal identifier 300100032959874.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns1:deleteLocation 
        xmlns:ns1="http://xmlns.oracle.com/apps/cdm/foundation/parties/
        locationService/applicationModule/types/">
            <ns1:location 
            xmlns:ns2="http://xmlns.oracle.com/apps/cdm/foundation/parties
            locationService/">
                <ns2:LocationId>300100032959874</ns2:LocationId>
            </ns1:location>
        </ns1:deleteLocation>
    </soap:Body>
</soap:Envelope>

The deleteLocation completes and the response payload does not contain any service warning messages.

<ns0:deleteLocationResponse xmlns="" 
xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ns0="http://xmlns.oracle.com/apps/cdm/foundation/parties/locationService/
applicationModule/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/cdm/foundation/parties/ 
    locationService/"
    xmlns:ns2="http://xmlns.oracle.com/apps/cdm/foundation/parties/location
    Service/applicationModule/types/"
    xmlns:tns="http://xmlns.oracle.com/adf/svc/errors/" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:type="ns0:MethodResult"/>
</ns0:deleteLocationResponse>

For the Location business object, the deleteLocation is implemented as a soft delete. Invoking the getLocation after the deleteLocation call shows that the location has a StatusFlag attribute set to false, which indicates that the location is deleted.

Related Operations

The process operation can be used to perform the delete operations on a list of business objects passed in the request payload. When deleting many objects in bulk, consider using process.

get Operation

The get operation accepts the primary key for the business object in the request payload and returns the entire corresponding business object in the response payload. If the business object is composite business object, then the get operation will return all attributes for the service data objects as well as its child and descendant object entities. This operation assumes that the caller knows the internal id for the business object to be queried.

Topics

Operation Signature

The following definition shows the get operation interface for the Location Service. The operation takes in the location internal identifier which has a type Long.

<element name="getLocation">
    <complexType>
        <sequence>
            <element name="locationId" type="long"/>
        </sequence>
    </complexType>
</element>

It returns the information for the corresponding location business object which has a type Location.

<element name="getLocationResponse">
    <complexType>
        <sequence>
            <element name="result" type="ns1:Location"/>
        </sequence>
    </complexType>
</element>

Example

In this example, we retrieve the location with the internal identifier 2623. The request payload looks like the following:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns1:getLocation 
        xmlns:ns1="http://xmlns.oracle.com/apps/cdm/foundation/parties/
        locationService/applicationModule/types/">
            <ns1:location
            xmlns:ns2="http://xmlns.oracle.com/apps/cdm/foundation/parties
            locationService/">
                <ns1:locationId>2623</ns1:locationId>
            </ns1:location>
        </ns1:createLocation>
    </soap:Body>
</soap:Envelope>

The response payload looks like the following example. The result element contains the location business object with the internal identifier 2623. The location business object is composed of two entities with the Location as the top level entity and the Location Profile as the child entity. The get operation response payload includes all attributes of the business object.

<ns0:getLocationResponse xmlns=""
xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ns0="http://xmlns.oracle.com/apps/cdm/foundation/parties/locationService/
applicationModule/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/cdm/foundation/parties/
    locationService/" 
    xmlns:ns2="http://xmlns.oracle.com/apps/cdm/foundation/parties/
    locationService/applicationModule/types/"
    xmlns:ns3="http://xmlns.oracle.com/apps/cdm/foundation/parties/
    partyService/"
    xmlns:ns4="http://xmlns.oracle.com/apps/cdm/foundation/parties/
    flex/location/" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:type="ns1:LocationResult">
         <ns1:LocationId>2623</ns1:LocationId>
         <ns1:LastUpdateDate>2007-04-20T00:32:07.0-07:00</ns1:LastUpdateDate>
         <ns1:LastUpdatedBy>1001773</ns1:LastUpdatedBy>
         <ns1:CreationDate>2001-07-27T12:12:09.0-07:00</ns1:CreationDate>
         <ns1:CreatedBy>1318</ns1:CreatedBy>
         <ns1:LastUpdateLogin>3205711</ns1:LastUpdateLogin>
         <ns1:RequestId>3385811</ns1:RequestId>
         <ns1:OrigSystem xsi:nil="true"/>
         <ns1:OrigSystemReference>2623</ns1:OrigSystemReference>
         <ns1:Country>US</ns1:Country>
         <ns1:Address1>1 Oracle Parkway</ns1:Address1>
         <ns1:Address2 xsi:nil="true"/>
         <ns1:Address3 xsi:nil="true"/>
         <ns1:Address4 xsi:nil="true"/>
         <ns1:City>REDWOOD CITY</ns1:City>
         <ns1:PostalCode>94065</ns1:PostalCode>
         <ns1:State>CA</ns1:State>
         <ns1:Province xsi:nil="true"/>
         <ns1:County>SAN MATEO</ns1:County>
         <ns1:AddressStyle>USA</ns1:AddressStyle>
         <ns1:ValidatedFlag>false</ns1:ValidatedFlag>
         <ns1:AddressLinesPhonetic xsi:nil="true"/>
         <ns1:PostalPlus4Code xsi:nil="true"/>
         <ns1:Position xsi:nil="true"/>
         <ns1:LocationDirections xsi:nil="true"/>
         <ns1:AddressEffectiveDate xsi:nil="true"/>
         <ns1:AddressExpirationDate xsi:nil="true"/>
         <ns1:ClliCode xsi:nil="true"/>
         <ns1:Language xsi:nil="true"/>
         <ns1:ShortDescription xsi:nil="true"/>
         <ns1:Description xsi:nil="true"/>
         <ns1:SalesTaxGeocode xsi:nil="true"/>
         <ns1:SalesTaxInsideCityLimits>1</ns1:SalesTaxInsideCityLimits>
         <ns1:FaLocationId xsi:nil="true"/>
         <ns1:ObjectVersionNumber>1</ns1:ObjectVersionNumber>
         <ns1:CreatedByModule xsi:nil="true"/>
         <ns1:GeometryStatusCode>GOOD</ns1:GeometryStatusCode>
         <ns1:ValidationStatusCode xsi:nil="true"/>
         <ns1:DateValidated xsi:nil="true"/>
         <ns1:DoNotValidateFlag xsi:nil="true"/>
         <ns1:Comments xsi:nil="true"/>
         <ns1:HouseType xsi:nil="true"/>
         <ns1:EffectiveDate>2014-03-24</ns1:EffectiveDate>
         <ns1:AddrElementAttribute1 xsi:nil="true"/>
         <ns1:AddrElementAttribute2 xsi:nil="true"/>
         <ns1:AddrElementAttribute3 xsi:nil="true"/>
         <ns1:AddrElementAttribute4 xsi:nil="true"/>
         <ns1:AddrElementAttribute5 xsi:nil="true"/>
         <ns1:Building xsi:nil="true"/>
         <ns1:FloorNumber xsi:nil="true"/>
         <ns1:StatusFlag>true</ns1:StatusFlag>
         <ns1:InternalFlag>false</ns1:InternalFlag>
         <ns1:TimezoneCode xsi:nil="true"/>
         <ns1:Latitude xsi:nil="true"/>
         <ns1:Longitude xsi:nil="true"/>
         <ns1:Distance xsi:nil="true"/>
         <ns1:LocationProfile>
             <ns1:LocationProfileId>1667806</ns1:LocationProfileId>
             <ns1:LocationId>2623</ns1:LocationId>
             <ns1:EffectiveStartDate>2007-04-18</ns1:EffectiveStartDate>
             <ns1:EffectiveEndDate>4712-12-31</ns1:EffectiveEndDate>
             <ns1:ValidationSstFlag>true</ns1:ValidationSstFlag>
             <ns1:ValidationStatusCode xsi:nil="true"/>
             <ns1:DateValidated xsi:nil="true"/>
             <ns1:Address1>500 Oracle Pkwy</ns1:Address1>
             <ns1:Address2 xsi:nil="true"/>
             <ns1:Address3 xsi:nil="true"/>
             <ns1:Address4 xsi:nil="true"/>
             <ns1:City>REDWOOD CITY</ns1:City>
             <ns1:PostalCode>94065</ns1:PostalCode>
             <ns1:County>SAN MATEO</ns1:County>
             <ns1:Country>US</ns1:Country>
             <ns1:ObjectVersionNumber>1</ns1:ObjectVersionNumber>
             <ns1:LastUpdateDate>2007-04-18T08:53:31.0-07:00</ns1:LastUpdateDate>
             <ns1:LastUpdatedBy>1318</ns1:LastUpdatedBy>
             <ns1:LastUpdateLogin>-1</ns1:LastUpdateLogin>
             <ns1:CreationDate>2007-04-18T08:53:31.0-07:00</ns1:CreationDate>
             <ns1:CreatedBy>1318</ns1:CreatedBy>
             <ns1:RequestId xsi:nil="true"/>
             <ns1:State>CA</ns1:State>
             <ns1:Province xsi:nil="true"/>
             <ns1:EffectiveSequence>1</ns1:EffectiveSequence>
             <ns1:EffectiveLatestChange>Y</ns1:EffectiveLatestChange>
             <ns1:AddrElementAttribute1 xsi:nil="true"/>
             <ns1:AddrElementAttribute2 xsi:nil="true"/
             <ns1:AddrElementAttribute3 xsi:nil="true"/>
             <ns1:AddrElementAttribute4 xsi:nil="true"/>
             <ns1:AddrElementAttribute5 xsi:nil="true"/>
             <ns1:Building xsi:nil="true"/>
             <ns1:FloorNumber xsi:nil="true"/>
        </ns1:LocationProfile>
        <ns1:LocationInformation>
            <ns4:LocationId>2623</ns4:LocationId>
            <ns4:__FLEX_Context xsi:nil="true"/>
            <ns4:_FLEX_NumOfSegments>0</ns4:_FLEX_NumOfSegments>
       </ns1:Value>
   </ns2:result>
</ns0:createLocationResponse>

Related Operations

The find operation also retrieves business object information, but provides richer functionality allowing the caller to specify a fetch start, fetch size, search criteria, business object attributes to include or exclude, and sort order. Use the find operation when a more complex search criteria is required, when the business object is large and only a small subset of attributes need to be retrieved, or when any of the service data objects have more children than the default fetch size which is set to 500.

find Operation

The find operation retrieves the objects that meet the specified search criteria. All of the following can be controlled at the top-level entity as well as all descendant service data objects.

  • Fetch start and size

  • Filter criteria

  • Sort order

  • List of attributes to either include or exclude

Topics

Operation Signature

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

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

While the find operation gives the caller extensive control over the query, the request payload can be difficult to understand. To explain the request payload parameters, this section starts by graphically representing the elements in the payload and describing them at a high level. The next subsection walks through several examples that demonstrate the behavior of the request payload elements.

This illustration represents the parameters for the find operation.

Description of find_op.gif follows
Description of the illustration find_op.gif

This table briefly describes each element in the find operation payload.

Parameter Description

attribute

Case sensitive name of the object attribute to filter. All 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. Note that 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 search conditions are evaluated in relation to each other. The valid, case sensitive values are: And, Or, Not, AndNot, OrNot.

excludeAttribute

Indicates whether the attributes specified by findAttribute elements are not included in the response payload. The default is false.

Tip: To reduce the size of the find operation response payload, use excludeAttribute in combination with findAttribute to only return the required elements.

fetchStart

This zero-based index indicates which objects at what index to fetch from. The default is 0. If the value is 0 the result set begins with the first row of the data set. If the value is 99 the result set begins with the 100th row of the data set.

fetchSize

The maximum number of top-level objects to retrieve. A fetchSize of -1, the default value, retrieves all rows up to the default maximum fetchSize that meet the search criteria starting from fetchStart. The default maximum fetchSize is 500 rows unless overridden in the service implementation. If fetchSize is greater than the number of remaining rows, only the remaining rows are returned.

filter

This structure contains the search criteria. If no filter is specified, then no filters are applied and all rows are retrieved. The filter element includes the conjunction, group and nested elements.

findAttribute

Specifies the subset of attributes to retrieve when the search/filter criteria is satisfied. When none is specified, all attributes are fetched. A child object is an attribute of the parent object and should be included in the findAttribute if you want to include the child object in the result set.

findControl

Not used in the current release.

findCriteria

This top-level parameter contains fetch size, search criteria, sort criteria, and content inclusion or exclusion information for all 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 runtime search condition for an attribute. The item element includes the conjunction, upperCaseCompare, attribute, operator, value and nested elements.

nested

Allows you to define a search criteria on child and descendant entities to determine whether the top-level entity is included in the search result. For example, return a parent object if it contains children that meet some criteria.

operator

Case sensitive operation to apply to attribute and value. See the table below for the list of operations

sortOrder

Contains directives for sorting the result set in ascending or descending order. This is specified by a zero (0) or more sortAttribute child elements. If there is more than one sortAttribute specified, then the sort is based on the order of the sortAttribute elements.

  • sortAttribute: Contains an attribute name and a boolean value to indicate whether the attribute value should be sorted in a descending order. By default, the values are ascending.

upperCaseCompare

Indicates whether this is a case insensitive search. The default is false.

The conjunction element defines how search conditions are evaluated in relation to each other. The valid, case sensitive values are: And, Or, Not, AndNot, OrNot

value

The attribute filter criteria can include wildcards "*" and "?". The wildcard "*" matches zero (0) or more characters. The wildcard "?" matches a single character. To minimize performance impact, ensure that the value does not start with a wildcard (for example, "Foo*" instead of "*Foo").


Note:

Unless otherwise noted in the documentation for a specific web service, Oracle Fusion Applications in Oracle Applications Cloud Services has a default maximum fetch size of 500. This means a maximum of 500 rows (objects) can be returned in a single query regardless of whether the fetchSize parameter in the find operation is set to -1 or a value greater than 500. If fetching more than 500 objects is required, then the find operation must be called multiple times with different fetchStart values (for example, 0, 500, 1000) to retrieve the results in batches of 500 objects, assuming the fetch size is 500.

The childFindCriteria parameter must be specified in order to control the fetchSize of a child attribute rowset.

This table lists operations that can be specified for the operator parameter. Note that some of the operators listed in the table may be disabled for specific service data object attributes. If an operator is disabled, it cannot be used with the specific service data object attribute in the findCriteria parameter.

Operation Name Use for String? Use for Numbers? Use for Dates?

=

Yes

Yes

Yes

>

Yes

Yes

 

>=

Yes

Yes

 

<

Yes

Yes

 

<=

Yes

Yes

 

<>

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

   

Here is the declaration for the find operation response payload. Because the LocationService has service warnings enabled, this operation returns the LocationResult type instead of Location. The LocationResult type is a wrapper that allows both the Location object and warning messages to be returned in the response payload.

<element name="findLocationResponse">
    <complexType>
        <sequence>
            <element name="result" type="ns1:LocationResult"/>
        </sequence>
    </complexType>
</element>

Example for Returning a Subset of Attributes in Parent Service Data Object

This example gets the location object with LocationId equal to 958 and only returns the City, State, Province, Country and LocationId attributes for that object. Use this pattern instead of the get operation if you only need to retrieve a subset of the attributes. This is useful particularly when you have business objects with entities with many attributes and business objects composed of many service data objects.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns1:findLocation 
        xmlns:ns1="http://xmlns.oracle.com/apps/cdm/foundation/parties/
        locationService/applicationModule/types/">
            <ns1:findCriteria xmlns:ns2="http://xmlns.oracle.com/adf/svc/types/">
                <ns2:filter>
                    <ns2:group>
                        <ns2:item>
                            <ns2:attribute>LocationId</ns2:attribute>
                            <ns2:operator>=</ns2:operator>
                            <ns2:value>958</ns2:value>
                        </ns2:item>
                    </ns2:group>
               </ns2:filter>
               <ns2:findAttribute>City</ns2:findAttribute>
               <ns2:findAttribute>State</ns2:findAttribute>
               <ns2:findAttribute>Province</ns2:findAttribute>
               <ns2:findAttribute>Country</ns2:findAttribute>
               <ns2:findAttribute>LocationId</ns2:findAttribute>
            </ns1:findCriteria>
        </ns1:findLocation>
    </soap:Body>
</soap:Envelope>

The response payload for the above find looks like the following example. The child object LocationProfile was not included in the response payload because it was not included as a value of a findAttribute element.

<ns0:findLocationResponse xmlns=""
xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ns0="http://xmlns.oracle.com/apps/cdm/foundation/parties/locationService/
applicationModule/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/cdm/foundation/parties/locationService/" 
    xmlns:ns2="http://xmlns.oracle.com/apps/cdm/foundation/parties/locationService/
    applicationModule/types/"
    xmlns:ns3="http://xmlns.oracle.com/apps/cdm/foundation/parties/partyService/" 
    xmlns:ns4="http://xmlns.oracle.com/apps/cdm/foundation/parties/flex/location/" 
    xmlns:tns="http://xmlns.oracle.com/adf/svc/errors/" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:type="ns1:LocationResult">
        <ns1:Value>
            <ns1:LocationId>958</ns1:LocationId>
            <ns1:Country>US</ns1:Country>
            <ns1:City>St. Charles</ns1:City>
            <ns1:State>AR</ns1:State>
            <ns1:Province xsi:nil="true"/>
        </ns1:Value>
    </ns2:result>
</ns0:findLocationResponse>

Example for Returning a Subset of Attributes in Child Service Data Object

To include the entire LocationProfile child object in the response, add a new findAttribute element containing LocationProfile as the value to the request payload as shown in this example. This request payload will select the location with location internal identifier set to 958 and return the City, State, Province, Country, LocationId and all attributes in the LocationProfile child object.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns1:findLocation 
        xmlns:ns1="http://xmlns.oracle.com/apps/cdm/foundation/parties/
        locationService/applicationModule/types/">
            <ns1:findCriteria xmlns:ns2="http://xmlns.oracle.com/adf/svc/types/">
                <ns2:filter>
                    <ns2:group>
                        <ns2:item>
                            <ns2:attribute>LocationId</ns2:attribute>
                            <ns2:operator>=</ns2:operator>
                            <ns2:value>958</ns2:value>
                        </ns2:item>
                    </ns2:group>
                </ns2:filter>
                <ns2:findAttribute>City</ns2:findAttribute>
                <ns2:findAttribute>State</ns2:findAttribute>
                <ns2:findAttribute>Province</ns2:findAttribute>
                <ns2:findAttribute>Country</ns2:findAttribute>
                <ns2:findAttribute>LocationId</ns2:findAttribute>
                <ns2:findAttribute>LocationProfile</ns2:findAttribute>
            </ns1:findCriteria>
        </ns1:findLocation>
    </soap:Body>
</soap:Envelope>

To include only a subset of the elements in LocationProfile, use the childFindAttribute element and specify the elements in the LocationProfile using the findAttribute element. This example returns only the LocationProfileId, EffectiveStartDate, and EffectiveEndDate of the LocationProfile, and the childFindCriteria and corresponding findAttributes:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns1:findLocation 
        xmlns:ns1="http://xmlns.oracle.com/apps/cdm/foundation/parties/locationService/
        applicationModule/types/">
            <ns1:findCriteria xmlns:ns2="http://xmlns.oracle.com/adf/svc/types/">
                <ns2:filter>
                    <ns2:group>
                        <ns2:item>
                            <ns2:attribute>LocationId</ns2:attribute>
                            <ns2:operator>=</ns2:operator>
                            <ns2:value>958</ns2:value>
                        </ns2:item>
                    </ns2:group>
                </ns2:filter>
                <ns2:findAttribute>City</ns2:findAttribute>
                <ns2:findAttribute>State</ns2:findAttribute>
                <ns2:findAttribute>Province</ns2:findAttribute>
                <ns2:findAttribute>Country</ns2:findAttribute>
                <ns2:findAttribute>LocationId</ns2:findAttribute>
                <ns2:findAttribute>LocationProfile</ns2:findAttribute>
                <ns2:childFindCriteria>
                    <ns2:findAttribute>LocationProfileId</ns2:findAttribute>
                    <ns2:findAttribute>EffectiveStartDate</ns2:findAttribute>
                    <ns2:findAttribute>EffectiveEndDate</ns2:findAttribute>
                    <ns2:childAttrName>LocationProfile</ns2:childAttrName>
                </ns2:childFindCriteria>
            </ns1:findCriteria>
        </ns1:findLocation>
    </soap:Body>
</soap:Envelope>

The response payload to the request:

<ns0:findLocationResponse xmlns="" 
xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ns0="http://xmlns.oracle.com/apps/cdm/foundation/parties/locationService/
applicationModule/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/cdm/foundation/parties/locationService/" 
    xmlns:ns2="http://xmlns.oracle.com/apps/cdm/foundation/parties/locationService/
    applicationModule/types/" 
    xmlns:ns3="http://xmlns.oracle.com/apps/cdm/foundation/parties/partyService/" 
    xmlns:ns4="http://xmlns.oracle.com/apps/cdm/foundation/parties/flex/location/" 
    xmlns:tns="http://xmlns.oracle.com/adf/svc/errors/" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:type="ns1:LocationResult">
        <ns1:Value>
            <ns1:LocationId>958</ns1:LocationId>
            <ns1:Country>US</ns1:Country>
            <ns1:City>St. Charles</ns1:City>
            <ns1:State>AR</ns1:State>
            <ns1:Province xsi:nil="true"/>
            <ns1:LocationProfile>
                <ns1:LocationProfileId>10035</ns1:LocationProfileId>
                <ns1:EffectiveStartDate>2004-02-23</ns1:EffectiveStartDate>
                <ns1:EffectiveEndDate>4712-12-31</ns1:EffectiveEndDate>
            </ns1:LocationProfile>
        </ns1:Value>
    </ns2:result>
</ns0:findLocationResponse>

Example with a Complex Search Criteria at Parent Level

This next example demonstrates how to search for locations that have Country set to US and State set to AK in the Location object, and return the PostalCode, City, State, Province, Country, and LocationId.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns1:findLocation 
        xmlns:ns1="http://xmlns.oracle.com/apps/cdm/foundation/parties/
        locationService/applicationModule/types/">
            <ns1:findCriteria xmlns:ns2="http://xmlns.oracle.com/adf/svc/types/">
                <ns2:fetchStart>0</ns2:fetchStart>
                <ns2:fetchSize>500</ns2:fetchSize>
                <ns2:filter>
                    <ns2:group>
                        <ns2:item>
                            <ns2:conjunction>And</ns2:conjunction>
                            <ns2:attribute>Country</ns2:attribute>
                            <ns2:operator>=</ns2:operator>
                            <ns2:value>US</ns2:value>
                        </ns2:item>
                        <ns2:item>
                            <ns2:conjunction>And</ns2:conjunction>
                            <ns2:attribute>State</ns2:attribute>
                            <ns2:operator>=</ns2:operator>
                            <ns2:value>AK</ns2:value>
                        </ns2:item>
                    </ns2:group>
                </ns2:filter>
                <ns2:findAttribute>PostalCode</ns2:findAttribute>
                <ns2:findAttribute>City</ns2:findAttribute>
                <ns2:findAttribute>State</ns2:findAttribute>
                <ns2:findAttribute>Province</ns2:findAttribute>
                <ns2:findAttribute>Country</ns2:findAttribute>
                <ns2:findAttribute>LocationId</ns2:findAttribute>
            </ns1:findCriteria>
        </ns1:findLocation>
    </soap:Body>
</soap:Envelope>

The response payload contains:

<ns0:findLocationResponse xmlns="" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns0="http://xmlns.oracle.com/apps/cdm/foundation/parties/locationService/applicationModule/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/cdm/foundation/parties/locationService/" 
    xmlns:ns2="http://xmlns.oracle.com/apps/cdm/foundation/parties/locationService/
    applicationModule/types/"
    xmlns:ns3="http://xmlns.oracle.com/apps/cdm/foundation/parties/partyService/"
    xmlns:ns4="http://xmlns.oracle.com/apps/cdm/foundation/parties/flex/location/"
    xmlns:tns="http://xmlns.oracle.com/adf/svc/errors/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns1:LocationResult">
        <ns1:Value>
            <ns1:LocationId>999997516465004</ns1:LocationId>
            <ns1:Country>US</ns1:Country>
            <ns1:City>JUNEAU</ns1:City>
            <ns1:PostalCode>99801-7814</ns1:PostalCode>
            <ns1:State>AK</ns1:State>
            <ns1:Province xsi:nil="true"/>
        </ns1:Value>
        <ns1:Value>
            <ns1:LocationId>999997516000512</ns1:LocationId>
            <ns1:Country>US</ns1:Country>
            <ns1:City>KOTZEBUE</ns1:City>
            <ns1:PostalCode>99752</ns1:PostalCode>
            <ns1:State>AK</ns1:State>
            <ns1:Province xsi:nil="true"/>
        </ns1:Value>
        <ns1:Value>
            <ns1:LocationId>999997518214847</ns1:LocationId>
            <ns1:Country>US</ns1:Country>
            <ns1:City>ANCHORAGE</ns1:City>
            <ns1:PostalCode>99518-1074</ns1:PostalCode>
            <ns1:State>AK</ns1:State>
            <ns1:Province xsi:nil="true"/>
        </ns1:Value>
        ...

Example with Search Criteria with Dependency on Child Data

This example shows how to select parent objects based on criteria applied to the child level. The example payload finds all locations that are in the United States, in the state of Alaska, and have an effective date of 1950-04-12 or later in the LocationProfile child object entity. The LocationId and Country attributes in the Location object, and the EffectiveStartDate and LocationId attributes in the LocationProfile child object are returned.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
    <ns1:findLocation
        xmlns:ns1="http://xmlns.oracle.com/apps/cdm/foundation/parties/
        locationService/applicationModule/types/">
        <ns1:findCriteria xmlns:ns2="http://xmlns.oracle.com/adf/svc/types/">
            <ns2:fetchStart>0</ns2:fetchStart>
            <ns2:fetchSize>500</ns2:fetchSize>
                <ns2:filter>
                    <ns2:group>
                        <ns2:item>
                            <ns2:attribute>Country</ns2:attribute>
                            <ns2:operator>=</ns2:operator>
                            <ns2:value>US</ns2:value>
                        </ns2:item>
                        <ns2:item>
                            <ns2:conjunction>And</ns2:conjunction>
                            <ns2:attribute>State</ns2:attribute>
                            <ns2:operator>=</ns2:operator>
                            <ns2:value>AK</ns2:value>
                        </ns2:item>
                        <ns2:item>
                            <ns2:conjunction>And</ns2:conjunction>
                            <ns2:attribute>LocationProfile</ns2:attribute>
                            <ns2:nested>
                                <ns2:group>
                                    <ns2:item>
                                        <ns2:attribute>EffectiveStartDate</ns2:attribute>
                                        <ns2:operator>ONORAFTER</ns2:operator>
                                        <ns2:value>1950-04-12</ns2:value>
                                    </ns2:item>
                                </ns2:group>
                            </ns2:nested>
                        </ns2:item>
                    </ns2:group>
                </ns2:filter>
                <ns2:findAttribute>LocationId</ns2:findAttribute>
                <ns2:findAttribute>Country</ns2:findAttribute>
                <ns2:findAttribute>State</ns2:findAttribute>
                <ns2:findAttribute>LocationProfile</ns2:findAttribute>
                <ns2:childFindCriteria>
                    <ns2:findAttribute>EffectiveStartDate</ns2:findAttribute>
                    <ns2:findAttribute>LocationProfileId</ns2:findAttribute>
                    <ns2:childAttrName>LocationProfile</ns2:childAttrName>
                </ns2:childFindCriteria>
            </ns1:findCriteria>
        </ns1:findLocation>
    </soap:Body>
</soap:Envelope>

Example with Search Criteria at Child Level

This example shows how to apply a search criteria at parent and child levels. This example payload will select the first 500 locations in the United States and in the state of Alaska. It will return the PostalCode, City, State, Province, Country, and LocationId attributes for the Location object, as well as the Country, FloorNumber, City, State, Province, and EffectiveStartDate attributes for the LocationProfile if the LocationProfile has an effective start date on or after 1950-04-12.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns1:findLocation 
        xmlns:ns1="http://xmlns.oracle.com/apps/cdm/foundation/parties/
        locationService/applicationModule/types/">
            <ns1:findCriteria xmlns:ns2="http://xmlns.oracle.com/adf/svc/types/">
                <ns2:fetchStart>0</ns2:fetchStart>
                <ns2:fetchSize>500</ns2:fetchSize>
                <ns2:filter>
                    <ns2:group>
                        <ns2:item>
                            <ns2:attribute>Country</ns2:attribute>
                            <ns2:operator>=</ns2:operator>
                            <ns2:value>US</ns2:value>
                        </ns2:item>
                        <ns2:item>
                            <ns2:conjunction>And</ns2:conjunction>
                            <ns2:attribute>State</ns2:attribute> 
                            <ns2:operator>=</ns2:operator>
                            <ns2:value>AK</ns2:value> 
                        </ns2:item>
                    </ns2:group>
                </ns2:filter>
                <ns2:findAttribute>PostalCode</ns2:findAttribute>
                <ns2:findAttribute>City</ns2:findAttribute>
                <ns2:findAttribute>State</ns2:findAttribute>
                <ns2:findAttribute>Province</ns2:findAttribute>
                <ns2:findAttribute>Country</ns2:findAttribute>
                <ns2:findAttribute>LocationId</ns2:findAttribute>
                <ns2:findAttribute>LocationProfile</ns2:findAttribute>
                <ns2:childFindCriteria>
                    <ns2:filter>
                        <ns2:group>
                            <ns2:item>
                                <ns2:attribute>EffectiveStartDate</ns2:attribute>
                                <ns2:operator>ONORAFTER</ns2:operator>
                                <ns2:value>1950-04-12</ns2:value>
                            </ns2:item>
                        </ns2:group>
                    </ns2:filter>
                    <ns2:findAttribute>Country</ns2:findAttribute>
                    <ns2:findAttribute>FloorNumber</ns2:findAttribute>
                    <ns2:findAttribute>City</ns2:findAttribute>
                    <ns2:findAttribute>State</ns2:findAttribute>
                    <ns2:findAttribute>Province</ns2:findAttribute>
                    <ns2:findAttribute>EffectiveStartDate</ns2:findAttribute>
                    <ns2:childAttrName>LocationProfile</ns2:childAttrName>
                </ns2:childFindCriteria>
            </ns1:findCriteria>
        </ns1:findLocation>
    </soap:Body>
</soap:Envelope>

Example with Sort Order

This example shows how to order the search results. The sample payload finds location objects in the United States and in the state of Alaska, sorts them by PostalCode in ascending order and City in descending order, and returns PostalCode, City, State, Province, Country and LocationId attributes in the Location object.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns1:findLocation 
        xmlns:ns1="http://xmlns.oracle.com/apps/cdm/foundation/parties/
        locationService/applicationModule/types/">
            <ns1:findCriteria xmlns:ns2="http://xmlns.oracle.com/adf/svc/types/">
                <ns2:fetchStart>0</ns2:fetchStart>
                <ns2:fetchSize>500</ns2:fetchSize>
                <ns2:filter>
                    <ns2:group>
                        <ns2:item>
                            <ns2:conjunction>And</ns2:conjunction>
                            <ns2:attribute>Country</ns2:attribute>
                            <ns2:operator>=</ns2:operator>
                            <ns2:value>US</ns2:value>
                        </ns2:item>
                        <ns2:item>
                            <ns2:conjunction>And</ns2:conjunction>
                            <ns2:attribute>State</ns2:attribute>
                            <ns2:operator>=</ns2:operator>
                            <ns2:value>AK</ns2:value>
                        </ns2:item>
                    </ns2:group>
                </ns2:filter>
                <ns2:sortOrder>
                    <ns2:sortAttribute>
                        <ns2:name>PostalCode</ns2:name>
                    </ns2:sortAttribute>
                    <ns2:sortAttribute>
                        <ns2:name>City</ns2:name>
                        <ns2:descending>true</ns2:descending>
                    </ns2:sortAttribute>
                </ns2:sortOrder>  
                <ns2:findAttribute>PostalCode</ns2:findAttribute>
                <ns2:findAttribute>City</ns2:findAttribute>
                <ns2:findAttribute>State</ns2:findAttribute>
                <ns2:findAttribute>Province</ns2:findAttribute>
                <ns2:findAttribute>Country</ns2:findAttribute>
                <ns2:findAttribute>LocationId</ns2:findAttribute>
            </ns1:findCriteria>
        </ns1:findLocation>
    </soap:Body>
</soap:Envelope>

Related Operations

The get operation provides a subset of the functionality offered by the find operation. Consider using find instead of get for complex query criteria requirements. Additionally, consider using find instead of get when only a few attributes must be retrieved from service data objects with large numbers of attributes, or the business object is composed of many service data objects.

Find by view criteria operations may be exposed on the service.

find by additional pre-defined search criteria

The find by additional pre-defined search criteria operations are similar to the find operations, but these have an additional pre-defined criteria applied to the find criteria specified by the caller. The find by view criteria operations are typically exposed on the service interface for frequently-performed searches. Instead of requiring the caller to construct the complex payloads for the find operation, the caller can invoke these operations. The predefined criteria may refer to no bind variables or multiple bind variables. If the criteria references a bind variable, the bind variables are exposed as parameters in the find by additional pre-defined search criteria request payloads and callers can pass in the appropriate values. For information on the pre-defined criteria and the bind variables exposed as parameters, see the operation and parameter descriptions in OER.

Here are examples of find by view criteria operations:

  • getLocationByOriginalSystemReference operation defined on the LocationService. This operation allows the caller to search for locations based on the source system where the location definition originated.

  • findExportBatchesByJobId operation defined on the BulkExportService. This operation finds batch information corresponding to a JobId.

Operation Signature

The signature for the find by additional pre-defined search criteria operation is similar to the find operation and includes additional parameters that correspond to bind variables in the view criteria.

This example is for the getLocationByOriginalSystemReference operation defined on the LocationService. Although the name of the operation starts with "get", it is actually a find operation with additional pre-defined search criteria based on the implementation. In addition to the findCriteria and findControl parameters, the operation takes in the bindOrigSystem and bindOrigSystemReference parameters which correspond to a unique original system code and original system reference identifiers.

<element name="getLocationByOriginalSystemReference">
    <complexType>
        <sequence>
            <element name="findCriteria" type="ns0:FindCriteria"/>
            <element name="bindOrigSystem" type="string"/>
            <element name="bindOrigSystemReference" type="string"/>
            <element name="findControl" type="ns0:FindControl"/>
        </sequence>
    </complexType>
</element>

update Operation

The update operation updates existing rows in the top-level service data object as well as child and descendant entities. The rows must exist prior to the update, otherwise an exception is thrown. If updating a subset of service data object attributes, it is sufficient to pass in the primary key or alternate key, and the values to update in the service data object in the request payload. It is not necessary to pass in all attribute values in the service data object in the update request payload.

The update operation handles the following service data object attribute values in the request payload.

Request Payload Element Handling in Update Operation

The service data object attribute is not included in the request payload. This is the absent element case.

The service data object attribute value is not updated.

The service data object attribute is included in the payload and has an empty element value. For example: <attributeName/> and <attributeName></attributeName>.

If the attribute is nillable, then the attribute value is not updated.

If the attribute is not nillable, then this is treated as a nil and is an invalid input.

The service data object attribute value is included in the payload and has a nil value. For example: <attributeName xsi:nil="true">

If the attribute is nillable, then the attribute value is updated to nil.

If the attribute is not nillable, then this is treated as a nil and is an invalid input.

The service data object attribute is included in the payload and has a not empty element, not empty string and non-nil value

The service data object attribute value is updated to the specified value.


Topics

Operation Signature

This is the signature of the updateLocation operation for the LocationService. It accepts the location business object to be defined.

<element name="updateLocation">
    <complexType>
        <sequence>
            <element name="location" type="ns1:Location"/>
        </sequence>
    </complexType>
</element>

After successfully defining the location business object, the operation returns the successfully updated object. Because the LocationService has service warnings enabled, this operation returns LocationResult instead of Location. The LocationResult type is essentially a wrapper that allows the result of Location type to be returned in addition to warning messages.

<element name="updateLocationResponse">
    <complexType>
        <sequence>
            <element name="location" type="ns1:LocationResult"/>
        </sequence>
    </complexType>
</element>

Example

In this example, the second line in the address captured in the Address2 attribute of the location with internal identifier 300100032959874 is set to Suite 1300.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns1:updateLocation 
        xmlns:ns1="http://xmlns.oracle.com/apps/cdm/foundation/parties/
        locationService/applicationModule/types/">
            <ns1:location 
            xmlns:ns2="http://xmlns.oracle.com/apps/cdm/foundation/parties/
            locationService/">
                <ns2:LocationId>300100039119119</ns2:LocationId>
                <ns2:Address2>Suite 1300</ns2:Address2>
            </ns1:location>
        </ns1:updateLocation>
    </soap:Body>
</soap:Envelope>

The response payload reflects the newly updated attribute in the location business object.

Related Operations

The process operation can be used to perform the update as well as control whether the response payload is empty, contains only the primary key or the entire payload. Consider using the process operation to do the update when the business object is large or when the business object in the response payload is not required.

The merge operation can be used to update existing rows as well as create new rows. In comparison, the update operation can update existing rows, but will raise an exception when updating a row which does not exist. Use merge when a new child or descendant object entity must be created on an existing business object. Additionally, use merge when there are requirements to create the object if it does not exist or update the object if it exists.

The delete operation defined at the appropriate service data object level must be used to delete a row. The update operation does not delete rows in the service data object.

merge Operation

The merge operation performs an upsert which means it updates the service data object if it exists, and creates a new service data object if it does not exist. This upsert behavior occurs at all levels of the service data object. For example, to add a new child entity to an existing top-level entity, the merge operation would need to be used. The create and update operations defined at the top-level entity cannot be used. Think of create operation as creating the entire new object and the update operation only updating existing rows in the object.

Topics

Operation Signature

Here is the signature of the mergeLocation operation for the LocationService. It accepts the location business object to be created or updated.

<element name="mergeLocation">
    <complexType>
        <sequence>
            <element name="location" type="ns1:Location"/>
        </sequence>
    </complexType>
</element>

On successfully creating or updating the location business object, the operation returns the successfully created or updated object. Because the LocationService has service warnings enabled, this operation returns LocationResult instead of Location. The LocationResult type is essentially a wrapper that allows the result of Location type to be returned in addition to warning messages.

<element name="mergeLocationResponse">
    <complexType>
        <sequence>
            <element name="location" type="ns1:LocationResult"/>
        </sequence>
    </complexType>
</element>

Example

The following request payload uses merge to update the Address2 attribute to Suite 900 on the location object with the internal identifier 300100037792255.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns1:mergeLocation 
        xmlns:ns1="http://xmlns.oracle.com/apps/cdm/foundation/parties/
        locationService/applicationModule/types/">
            <ns1:location 
            xmlns:ns2="http://xmlns.oracle.com/apps/cdm/foundation
            /parties/locationService/">
                <ns2:LocationId>300100039119119</ns2:LocationId>
                <ns2:Address2>Suite 900</ns2:Address2>
            </ns1:location>
        </ns1:mergeLocation>
    </soap:Body>
</soap:Envelope>

The response payload contains information on the updated Location object. There are no service warnings reported for this operation invocation.

Related Operations

The process operation can be used to perform the merge as well as control whether the response payload is empty, contains only the primary key, or contains the entire payload. Consider using the process operation to do the merge when the business object is large or when the business object in the response payload is not required.

As discussed in the beginning of this section, the create and update operations can be used in some scenarios. Which operation you use will depend on your use case.

process Operation

The process operation performs a create, update, delete, or merge operation on the list of business objects of the same type in the request payload. It performs the same operation on all objects and cannot do a create for one, delete on another in the same call. For details on the behavior, see the create, update, delete, and merge sections in this guide. This operation is typically used for bulk processing.

The processControl parameter controls the following behaviors of the operation:

  1. Level of detail in the response payload: This parameter controls whether the response payload returns an empty payload, payload of primary keys, or payload with the complete service data object definitions. Use the first two options to improve performance. The first option eliminates the fetch and reduces the size of the response payload. The second option reduces the size of the response payload.

  2. Level of detail in the error message: This parameter controls whether the error message contains just the primary key of the corresponding service data object which failed, or all attributes of the service data object which failed. Returning no object information is a valid option, but it may not make sense to use for this parameter.

  3. Partial failure control: This parameter is available only if it is enabled at design time on the service. If this is enabled at design time and at runtime using the process request payload parameter, then the successfully completed changes are committed while the ones with errors are returned as errors. If this is not enabled, the operation either complete successfully for all service data objects in the request payload or completes without any processing when an error occurs.

Topics

Operation Signature

Here is the signature of the processLocation operation for the LocationService:

  • The name of the operation to be performed on the business objects in the request payload is specified in the changeOperation parameter, which is one of the following values. The value is case sensitive.

    • Create

    • Update

    • Merge

    • Delete

  • The list of business objects on which to perform the changeOperation.

  • The parameters to control the behavior of the operation, which include:

    • The response payload details and error message details. The returnMode and exceptionReturnMode elements can be set to one of three values: Full to return the entire object, Key to return only the primary key, and None to return nothing.

    • Whether partial failure mode is enabled. If set to true, then partial failure mode is enabled. Otherwise, it is disabled. The default is false.

The request payload has the following signature. For the definition of ProcessControl type, see Sample BC4JService.xsd.

<element name="processLocation">
    <complexType>
        <sequence>
            <element name="changeOperation" type="string"/>
            <element name="location" type="ns1:Location" minOccurs="0" maxOccurs="unbounded"/>
            <element name="processControl" type="ns0:ProcessControl"/>
        </sequence>
    </complexType>
</element>

After successfully completing the process operation, the operation returns the values according to the ProcessControl settings.

<element name="processLocationResponse">
    <complexType>
        <sequence>
            <element name="result" type="ns1:LocationResult"/>
        </sequence>
    </complexType>
</element>

Example

This example is the request payload for the processLocation to create two new Location objects for United States and Mexico by the AMS module, and return only the primary keys in the response payload and disable partial failure.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns1:processLocation 
        xmlns:ns1="http://xmlns.oracle.com/apps/cdm/foundation/parties/
        locationService/applicationModule/types/">
            <ns1:changeOperation>Create</ns1:changeOperation>
            <ns1:location xmlns:ns2="http://xmlns.oracle.com/apps/cdm/foundation/
            parties/locationService/">
                <ns2:Address1>1 Oracle Parkway</ns2:Address1>
                <ns2:Address2>Suite 900</ns2:Address2>
                <ns2:City>Redwood Shores</ns2:City>
                <ns2:State>CA</ns2:State>
                <ns2:Country>US</ns2:Country>
                <ns2:PostalCode>94065</ns2:PostalCode>
                <ns2:CreatedByModule>AMS</ns2:CreatedByModule>
            </ns1:location>
            <ns1:location 
            xmlns:ns2="http://xmlns.oracle.com/apps/cdm/foundation/parties/locationService/">
                <ns2:Address1>1 Oracle Parkway</ns2:Address1>
                <ns2:Address2>Suite 1300</ns2:Address2>
                <ns2:City>Redwood Shores</ns2:City>
                <ns2:State>CA</ns2:State>
                <ns2:Country>US</ns2:Country>
                <ns2:PostalCode>94065</ns2:PostalCode>
                <ns2:CreatedByModule>AMS</ns2:CreatedByModule>
            </ns1:location>
            <ns1:processControl xmlns:ns2="http://xmlns.oracle.com/adf/svc/types/">
                <ns2:returnMode>Key</ns2:returnMode>
                <ns2:exceptionReturnMode>Key</ns2:exceptionReturnMode>
                <ns2:partialFailureAllowed>false</ns2:partialFailureAllowed>
            </ns1:processControl>
        </ns1:processLocation>
    </soap:Body>
</soap:Envelope>

The response payload contains the primary keys for the newly created Location objects.

<ns0:processLocationResponse xmlns="" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns0="http://xmlns.oracle.com/apps/cdm/foundation/parties/locationService/applicationModule/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/cdm/foundation/parties/locationService/"
   xmlns:ns2="http://xmlns.oracle.com/apps/cdm/foundation/parties/locationService/applicationModule/types/"
   xmlns:ns3="http://xmlns.oracle.com/apps/cdm/foundation/parties/partyService/"
   xmlns:ns4="http://xmlns.oracle.com/apps/cdm/foundation/parties/flex/location/"
   xmlns:tns="http://xmlns.oracle.com/adf/svc/errors/"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns1:LocationResult">
      <ns1:Value>
         <ns1:LocationId>300100039124966</ns1:LocationId>
      </ns1:Value>
      <ns1:Value>
         <ns1:LocationId>300100039124967</ns1:LocationId>
      </ns1:Value>
   </ns2:result>
</ns0:processLocationResponse>

If the ProcessLocation parameter were set to ReturnMode equal to None, the response payload would look like this:

<ns0:processLocationResponse xmlns="" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ns0="http://xmlns.oracle.com/apps/cdm/foundation/parties/locationService/applicationModule/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/cdm/foundation/parties/locationService/"
   xmlns:ns2="http://xmlns.oracle.com/apps/cdm/foundation/parties/locationService/applicationModule/types/"
   xmlns:ns3="http://xmlns.oracle.com/apps/cdm/foundation/parties/partyService/"
   xmlns:ns4="http://xmlns.oracle.com/apps/cdm/foundation/parties/flex/location/"
   xmlns:tns="http://xmlns.oracle.com/adf/svc/errors/"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns1:LocationResult">
      <ns1:Value/>
      <ns1:Value/>
   </ns2:result>
</ns0:processLocationResponse>

Related Operations

Refer to the create, update, merge and delete operations for performing those operations on a single business object. The advantage of using the process operation over the create, update, and merge operations is the ability to control the values in the payload for performance optimizations.

The processCS operation can be used to perform the same changes.

Standard Metadata Operations

This section provides basic information about the standard metadata operation behavior, interface, examples and related operations.

Operation Method Name Operation Description

getServiceLastUpdateTime

getServiceLastUpdateTime

Returns the last date and time when the service was updated.

getEntityList

getEntityList

Returns list of service data objects defined on the service interface.

Get UI Control Hints

getDfltObjAttrHints

Returns the UI hints for a given service data object and its attributes.


getServiceLastUpdateTime Operation

This operation returns the last time when the service WSDL, service XSD, or business object XSD's were updated. Schema updates occur when customizations at runtime are performed using the Application Composer and flexfields. Additionally, schema are updated when an enterprise application is redeployed as part of an upgrade to a major release or application of a patch bundle regardless of whether there is an actual change in the WSDL or XSD. The last update time is in ISO 8601 format.

This operation may be useful for customers who generate service factory or JAX-WS proxy clients and want to determine whether to regenerate the client because of a change in the service interface.

Topics

Operation Signature

The getServiceLastUpdateTime operation does not accept any parameters.

<element name="getServiceLastUpdateTime">
    <complexType>
        <sequence/>
    </complexType>
</element>

The response payload contains the last update time. For the definition of dateTime-Timestamp type, see Sample BC4JService.xsd.

<element name="getServiceLastUpdateTimeResponse">
    <complexType>
        <sequence>
            <element name="result" type="ns0:dateTime-Timestamp"/>
        </sequence>
    </complexType>
</element>

Example

In this example, the getServiceLastUpdateTime operation is invoked on the Opportunity Service to determine when the service definition was last updated. The request payload looks like this:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns1:getServiceLastUpdateTime
        xmlns:ns1="http://xmlns.oracle.com/apps/sales/opptyMgmt/
        opportunities/opportunityService/types/"></ns1:getServiceLastUpdateTime>
    </soap:Body>
</soap:Envelope>

The response payload shows the service definition was last updated on March 21, 2014 at 5:10:09 PM PDT.

<ns0:getServiceLastUpdateTimeResponse xmlns="" 
xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns0="http://xmlns.oracle.com/apps/sales/opptyMgmt/opportunities/opportunityService/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">
    <result xmlns="http://xmlns.oracle.com/apps/sales/opptyMgmt/opportunities/
    opportunityService/types/">2014-03-21T17:10:09.218-07:00</result>
</ns0:getServiceLastUpdateTimeResponse>

Related Operations

There are no related operations.

getEntityList Operation

This operation is used to retrieve the list of service data objects defined on the business object service. Additionally, this operation, when defined on a business object service that implements a generic service interface, is used to retrieve information about custom objects defined in Application Composer. For example, invoking the getEntityList operation on the Sales Custom Business Object service returns the custom objects defined in the Sales application in Application Composer. Other business object services which implement a generic service interface include: Custom Common Business Object, Customer Custom Business Object, Marketing Custom Business Object, Sales Custom Business Object, Sales Lead Custom Business Object, and Sales Territory Custom Business Object.

For each service data object, the following information is included in the response payload:

  • QName. The fully qualified name of the corresponding XML Schema complex type representing the service data object.

  • Service view usage name for the service data object. This is an internal value in the application module that defines the service. This value can be passed as a parameter to the getDfltObjAttrHints operation to get UI hints for attributes in the service data object.

  • Object name for custom objects defined in Application Composer. This information is returned only when the operation is invoked on a business object service that implements a generic service interface.

  • Boolean values indicating whether create, update, merge, and delete operations can be performed directly on the service data object. The default value is false.

Topics

Operation Signature

The getEntityList operation request payload does not have any input parameters.

<element name="getEntityList">
    <complexType>
        <sequence/>
    </complexType>
</element>

The response payload contains information about the service data objects in this service definition. For the definition of ServiceViewInfo, see Sample BC4JService.xsd.

<element name="getEntityListResponse">
    <complexType>
        <sequence>
            <element maxOccurs="unbounded" minOccurs="0" 
            name="result" type="ns2:ServiceViewInfo"/>
        </sequence>
    </complexType>
</element>

Example

The following is a sample request payload for the getEntityList operation defined on the Opportunity Service.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns1:getEntityList
        xmlns:ns1="http://xmlns.oracle.com/apps/sales/opptyMgmt/
        opportunities/opportunityService/types/"></ns1:getEntityList>
    </soap:Body>
</soap:Envelope>

The sample response payload contains the information for all service data objects referenced in the Opportunity Service. For a given result, the typeName can be mapped to a corresponding service data object, and if canCreate, canUpdate, canMerge or canDelete is true, then a corresponding standard CRUD operation is exposed on the service interface to directly create, update, merge or delete on the service data object. Because this response is large, for purposes of an example payload only the first two result elements are displayed in this example.

<ns0:getEntityListResponse xmlns="" 
xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns0="http://xmlns.oracle.com/apps/sales/opptyMgmt/opportunities/opportunityService/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">
    <ns1:result xmlns:ns0="http://xmlns.oracle.com/adf/svc/types/"  
    xmlns:ns1="http://xmlns.oracle.com/apps/sales/opptyMgmt/opportunities/
    opportunityService/types/"
    xmlns:tns="http://xmlns.oracle.com/adf/svc/errors/" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns0:ServiceViewInfo">
        <ns0:name>Opportunity</ns0:name>
        <ns0:typeName>{http://xmlns.oracle.com/apps/sales/opptyMgmt/opportunities/
        opportunityService/}Opportunity</ns0:typeName>
        <ns0:canCreate>true</ns0:canCreate>
        <ns0:canUpdate>true</ns0:canUpdate>
        <ns0:canMerge>true</ns0:canMerge>
        <ns0:canDelete>true</ns0:canDelete>
    </ns1:result>
    <ns1:result xmlns:ns0="http://xmlns.oracle.com/adf/svc/types/" 
    xmlns:ns1="http://xmlns.oracle.com/apps/sales/opptyMgmt/opportunities/
    opportunityService/types/'
    xmlns:tns="http://xmlns.oracle.com/adf/svc/errors/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns0:ServiceViewInfo">
        <ns0:name>OpportunityCompetitorVO</ns0:name>  
        <ns0:typeName>{http://xmlns.oracle.com/apps/sales/opptyMgmt/opportunities/
        opportunityService/}OpportunityCompetitor</ns0:typeName>
        <ns0:canDelete>true</ns0:canDelete>
    </ns1:result>
    <ns1:result xmlns:ns0="http://xmlns.oracle.com/adf/svc/types/"
    xmlns:ns1="http://xmlns.oracle.com/apps/sales/opptyMgmt/opportunities/
    opportunityService/types/" xmlns:tns="http://xmlns.oracle.com/adf/svc/errors/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns0:ServiceViewInfo">
        <ns0:name>OpportunityContactVO</ns0:name>
        <ns0:typeName>{http://xmlns.oracle.com/apps/sales/opptyMgmt/opportunities/
        opportunityService/}OpportunityContact</ns0:typeName>
        <ns0:canDelete>true</ns0:canDelete>
   </ns1:result>
   …
</ns0:getEntityListResponse>

Related Operations

This operation is used in combination with the getDfltObjAttrHints operation to get the UI hints for all service data objects in the service definition. Pass the name element in the getEntityList response payload into the getDfltObjAttrHints request payload.

getDfltObjAttrHints Operation

This operation returns the labels for the service data objects and the label and UI hints for a given locale for the business object attributes which are part of the service definition. It includes the following information:

Level Key Value

Service data object

LABEL

Name of object (singular)

Service data object

LABEL_PLURAL

Name of object (plural)

Service data object attribute

LABEL_ResId

Expression to retrieve the key from the resource bundle


Topics

Prerequisite

Invoke the getEntityList operation defined on this service to retrieve the internal names of the service data objects which are part of the business object definition. The internal names are passed in as parameters to this operation.

Operation Signature

The operation accepts two parameters:

  1. viewName: This value corresponds to the service view usage name, an internal name for the service data object. Specify the value of the <name> element from the getEntityList response payload.

  2. localeName: This value is used when evaluating locale-based UI hints and is in the ISO 639-1 format.

This is the getDfltObjAttrHints request payload.

<element name="getDfltObjAttrHints">
    <complexType>
        <sequence>
            <element name="viewName" type="string"/>
            <element name="localeName" type="string"/>
        </sequence>
    </complexType>
</element>

The getDfltObjAttrHints response payload contains the label and UI hints for the object and object attributes in a name-value pair format. For the definition of ObjAttrHints type, see Sample BC4JService.xsd.

<element name="getDfltObjAttrHintsResponse">
    <complexType>
        <sequence>
            <element name="result" type="ns0:ObjAttrHints"/>
        </sequence>
    </complexType>
</element>

Example

This example request payload elements is requesting the label and UI hints for the service data object with the OpportunityContactVO service view usage name using the en locale.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns1:getDfltObjAttrHints
        xmlns:ns1="http://xmlns.oracle.com/apps/sales/
        opptyMgmt/opportunities/opportunityService/types/">
            <ns1:viewName>OpportunityContactVO</ns1:viewName>
            <ns1:localeName>en</ns1:localeName>
        </ns1:getDfltObjAttrHints>
    </soap:Body>
</soap:Envelope>

The response payload contains the service data object attribute information. Because this response is large, for purposes of an example payload only the object entity level and three of the attribute level hints are displayed here.

<ns0:getDfltObjAttrHintsResponse xmlns="" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ns0="http://xmlns.oracle.com/apps/sales/opptyMgmt/opportunities/opportunityService/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">
    <ns1:result xmlns:ns0="http://xmlns.oracle.com/adf/svc/types/"  
    xmlns:ns1="http://xmlns.oracle.com/apps/sales/opptyMgmt/opportunities/
    opportunityService/
    types/" xmlns:tns="http://xmlns.oracle.com/adf/svc/errors/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns0:ObjAttrHints">
        <ns0:objHint>
            <ns0:key>LABEL</ns0:key>
            <ns0:value>Opportunity Contact</ns0:value>
        </ns0:objHint>
        <ns0:objHint>
            <ns0:key>LABEL_PLURAL</ns0:key>
            <ns0:value>Opportunity Contacts</ns0:value>
        </ns0:objHint>
        <ns0:attrHints>
            <ns0:attrName>EmailPreferenceExistsFlag</ns0:attrName>
            <ns0:ctrlHint>
                <ns0:key>JboValueMapProperty</ns0:key>
                <ns0:value>oracle.jbo.valuemaps.BooleanYNPropertySet</ns0:value>
            </ns0:ctrlHint>
        </ns0:attrHints>
        <ns0:attrHints>
            <ns0:attrName>OrganizationPartyName</ns0:attrName>
            <ns0:ctrlHint>
                <ns0:key>LABEL_ResId</ns0:key>
                <ns0:value>${adfBundle['oracle.apps.sales.opptyMgmt.opportunities.resource.
                'ColAttr.Organization.OpportunityContactOrganization.OpptyMgmtOpportunities
                AttrBundle'OpportunityContactVO.OrganizationPartyName']}</ns0:value>
            </ns0:ctrlHint>
        </ns0:attrHints>
        <ns0:attrHints>
            <ns0:attrName>ObjectVersionNumber1</ns0:attrName>
            <ns0:ctrlHint>
                <ns0:key>ExtnEventActionProperty</ns0:key>
                <ns0:value>HideInFieldUpdate; HideInCreateTask; HideInEmailTemplate</ns0:value>
            </ns0:ctrlHint>
            <ns0:ctrlHint>
                <ns0:key>ATTR_INTERNAL_USE</ns0:key>
                <ns0:value>Y</ns0:value>
            </ns0:ctrlHint>
        </ns0:attrHints>
        …
    </ns1:result>
</ns0:getDfltObjAttrHintsResponse>

Related Operations

Before invoking getDfltObjAttrHints, first invoke the getEntityList operation to get the list of entities and their names, then pass the name as a request parameter to getDfltObjAttrHints.

Custom Operations

In addition to the standard CRUD operations, a business object service may expose other operations often referred to as custom operations. These operations are specific to the service and typically map to a business related operation. To find out more about the specific custom operation, review the descriptions of the operation and payload elements in OER.

Here are examples of custom operations:

  • The isSalesAccountUsedInOpportunity operation defined on the Opportunity Service determines whether a given sales account has any opportunities. It accepts the internal identifier for the sales account and returns a boolean value.

  • The convertToPartner operation defined on the Partner Service converts an organization to a partner. It accepts a party organization internal identifier and returns the newly converted partner object.

  • The renewProgramEnrollment operation defined on the Partner Program Enrollment Service renews an existing program enrollment. It accepts and returns the enrollment internal identifier.

Deriving the Business Object Service Endpoint and WSDL

This section describes how to derive the external virtual host and port for a tokenized service WSDL.

Service path from OER:

https://domainName_server:PortNumber/contextRoot/serviceName?WSDL

Opportunity Service example:

https://crm_server:PortNumber/opptyMgmtOpportunities/OpportunityService?WSDL

The topology information in the Topology Registration setup task contains the external virtual host and port for the domains and applications. The following procedure goes through the steps to derive the values using the Service Catalog Service WSDL URL as an example:

https://atf_server:PortNumber/fndAppCoreServices/ServiceCatalogService

Prerequisites

To access the Review Topology page, the ASM_REVIEW_TOPOLOGY_HIERARCHY_PRIV entitlement must be granted to the user's job role. The entitlement is granted to the ASM_APPLICATION_DEPLOYER_DUTY duty role, which is inherited by the duty roles ASM_APPLICATION_DEVELOPER_DUTY and ASM_APPLICATION_ADMIN_DUTY.

If the menu items and Tasks described in the following procedure are not available in your cloud instance, then it means your user account is missing the required role. Please contact your Cloud Instance Security Administrator for assistance.

Procedure

  1. Log in to the cloud instance.

  2. Click the Navigator icon in the global area in the top part of the window, then chose Setup and Maintenance under the Tools heading.

  3. Choose Review Topology under the Topology Registration section in the Tasks regional area on the left side of the window.

  4. Click the Detailed tab in the local area in the middle of the window.

    The tab shows the list of domains configured in the cloud instance.

    Description of domain_config.gif follows
    Description of the illustration domain_config.gif

  5. Map the token name in the service path value to the domain name in Topology Manager using this table.

    Token in Service Path Domain Name

    atf_server

    CommonDomain

    crm_server

    CRMDomain

    fin_server

    FinancialDomain

    hcm_server

    HCMDomain

    ic_server

    ICDomain

    prc_server

    ProcurementDomain

    prj_server

    ProjectsDomain

    scm_server

    SCMDomain


  6. Expand the domain name and select any external virtual host and port for the J2EE applications that are deployed on the domain. In the sample window, the values for this particular instance are fs-your-cloud-hostname and 443, respectively.

    Description of domain_values2.png follows
    Description of the illustration domain_values2.png

  7. Replace the domainName_server:PortNumber with the external virtual host and port identified in the previous step. For example:

    https://fs-your-cloud-hostname:port/fndAppCoreServices/ServiceCatalogService?wsdl
    
  8. Remove ?wsdl from the URL in the previous step to derive the ServiceCatalogService end point URL. Note that the service tester page has been disabled for this service. Navigating to the end point URL in a browser will result in a blank page.