Discovering and Viewing Integration Interfaces and Services

Overview

In addition to browsing and viewing integration interfaces from Oracle Integration Repository, users who have the Integration Developer role can generate SOAP web services for selected interfaces.

To better understand these design-time tasks and the structures of WSDL and WADL elements, this chapter includes the following topics:

• Searching and Viewing Integration Interfaces

• Reviewing Interface Details

• Generating SOAP Web Services

• Reviewing WSDL Element Details

• Reviewing WADL Element Details

• Understanding SOAP Messages

• Understanding REST Messages

Searching and Viewing Integration Interfaces

Browsing the Integration Interfaces

There are many ways to locate and view integration interfaces resided in Oracle Integration Repository. You can browse the interfaces by selecting either one of the following selections from the View By drop-down list:

• Product Family

• Interface Type

• Standard

After the selection, expand the tree node in one of these views to see a list of the available interfaces.

For more information on how to browse the interfaces, see Browsing the Integration Interfaces, Oracle E-Business Suite Integrated SOA Gateway User's Guide.

Searching the Integration Interfaces

To search for an integration interface, click Search to access the main Search page. Click the Show More Search Options link in the Search page to display more search fields. For example, the Scope field has Private to Application, Internal to Oracle, Public, and All drop-down values for your selection. If 'All' is selected from the Scope field, then all integration interfaces including public, private to application, and internal to Oracle interfaces will be listed in the results region.

Note: Integration analysts only have 'All' (default) and 'Public' list of values displayed from the Scope drop-down list, and only Public integration interfaces will be retrieved as the search result even if the default value 'All' is selected in the Scope field.

For detailed information on Public, Private to Application, and Internal to Oracle, see Scope, Oracle E-Business Suite Integrated SOA Gateway User's Guide.

Searching for Deployed Web Services

To locate deployed services for concurrent programs, for example, select 'Concurrent Program' in the Interface field first, then click the Show More Search Options link, and then select 'Deployed' in the Web Service Status field. After you perform the search, all deployed concurrent programs are retrieved and shown as the search results..

Searching for Java Bean Services, Application Module Services, and Security Services

Java Bean Services, Application Module Services, and Security Services are all specialized Java classes and are categorized as a subtype of Java interfaces and displayed in the Integration Repository under the Java interface type.

Search Page for Application Module Services

To easily locate these interfaces or services through the Search page, click the Show More Search Options link to display more search fields. Enter the following key search values along with any product family or scope if needed as the search criteria:

• Category: Interface Subtype

• Category Value: 'Java APIs for Forms', 'Java Bean Services', 'Application Module Services', or 'Security Services'

Note: Although you can search and locate Java APIs for Forms interfaces, they are not serviceable interfaces and cannot be exposed as SOAP services. If you are planning to use this type of interfaces as web services, you are advised to use alternate serviceable interfaces, such as PL/SQL and Business Service Objects interfaces, which can be deployed as web services. Refer to My Oracle Support Knowledge Document 966982.1 for the suggested alternatives to the existing Java APIs for Forms interfaces.

To view the interface or service details, click the interface or service name link that you want to view from the search result region. The interface details page is displayed. For more information on interface details, see Reviewing Interface Details.

Searching for Custom Integration Interfaces

Once annotated custom interface definitions are successfully uploaded to the Integration Repository, they are merged into the interface types to which they belong and displayed together with Oracle seeded interfaces from the Integration Repository browser window. Interface Source 'Custom' is used to categorize those custom integration interfaces, in contrast to Interface Source 'Oracle' for Oracle seeded interfaces in Oracle E-Business Suite.

To locate custom integration interfaces, first click the Show More Search Options link to display more search fields.

Search Page for Custom Integration Interfaces

Next, select 'Custom' from the Interface Source drop-down list along with any interface type, product family, or scope if needed as the search criteria.

For more information on each search field in the Search page, see Searching for an Integration Interface, Oracle E-Business Suite Integrated SOA Gateway User's Guide.

To search for all integration interface types:

1. Log in to Oracle E-Business Suite as a user who has the Integration Developer role.

   Select the Integrated SOA Gateway responsibility from the navigation menu. Select the Integration Repository link to open the repository browser.

2. Click Search to open the main Search page.

3. Enter appropriate search information such as product family, product, interface type, or business entity.

4. Click the Show More Search Options link to display more search options.

   • To search custom integration interfaces, select 'Custom' in the Interface Source field.

   • To search Java Bean Services, Application Module Services, or Security Services, select 'Interface Subtype' in the Category field and select 'Java Bean Services', 'Application Module Services' or 'Security Services' in the Category Value field.

5. To view deployed integration interfaces, select 'Deployed' from the Web Service Status field drop-down list.

6. To view all integration interfaces, select 'All' from the Scope field. All integration interfaces including Public, Internal to Oracle, and Private to Application are displayed in the results region.

7. To view different scopes of integration interfaces, select 'Public', 'Internal to Oracle', or 'Private to Application' from the Scope drop-down list respectively.

8. Click Go to run the search. All interfaces that match your search criteria are displayed.

9. Select an interface from the search result to view the interface details.

Reviewing Interface Details

To view a selected interface details, click the interface name link that you want to view after performing a search. The interface details page appears allowing you to view the interface general information, full description, source information, and the interface methods (or procedures and functions) region.

Additionally, the web service information if it's available can be displayed in the SOAP Web Service tab, REST Web Service tab, or Web Service region depending on the selected interface type.

Note: In this release, only PL/SQL APIs, Concurrent Programs, and Business Service Objects can be exposed as both SOAP and REST services. Java Bean Services, Application Module Services, Open Interface Tables, and Open Interface Views can be exposed as REST services only.

For more information on SOAP-based services, see Common Information on SOAP Web Services, Oracle E-Business Suite Integrated SOA Gateway User's Guide.

For more information on REST-based services, see Common Information on REST Web Services, Oracle E-Business Suite Integrated SOA Gateway User's Guide.

Once SOAP or REST web services are deployed, they can be invoked at runtime. For information on how to invoke these services, refer to each individual chapter described later in this book for details.

Generating SOAP Web Services

Users who have the Integration Developer role can transform interface definitions into SOAP web services represented in WSDL description.

Selecting Desired Interaction Patterns from the Interaction Pattern Table

SOAP services can be generated with the support for synchronous or asynchronous interaction pattern, or both synchronous and asynchronous patterns to meet your needs.

Before generating a service, an integration administrator or integration developer must select at least one interaction pattern in the Interaction Pattern table for the selected interface or specific methods contained in the interface: This can be achieved at the method level for one or more methods or at the interface level for all methods.

Important: In this release, asynchronous operation is supported only in PL/SQL interfaces in enabling SOAP-based services.

• For XML Gateway and Concurrent Program interface types

  Each interface contains only one method and it can only be service enabled synchronously by default; therefore, the Interaction Pattern table is neither displayed in the Web Service region for XML Gateway interfaces nor the SOAP Web Service tab for Concurrent Program interfaces.

• For Business Service Object interface type

  Each interface may contain more than one method; therefore, only the Synchronous column is displayed in the Interaction Pattern table for method selection.

By default, none of the interaction pattern would be selected. However, if your system is upgraded from a previous release, for backward compatibility, 'synchronous' pattern is selected for all the methods contained in a service.

Generating Services

In the SOAP Web Service tab (or the Web Service region for an XML Gateway interface), after selecting interaction patterns for an interface, the developer can click Generate to generate a web service represented in WSDL with the selected interaction patterns.

SOAP Web Service Tab for a Business Service Object Interface

After Service Generation

Once a service has been successfully generated, the selected interaction patterns are displayed in the table. Although this table is still editable, any changes to the interaction pattern will be applied only after the service regeneration.

You can expand the interface name node to display all the methods contained in the interface.

After the service has been successfully generated, the SOAP service status is changed from 'Not Generated' to 'Generated' indicating that the selected interface has WSDL description available, but it has not yet been deployed.

Important: If service generation is still in progress, then 'Generating' is displayed as the SOAP service status.

Click the View WSDL link to view the generated WSDL code. For more information about WSDL, see: Reviewing WSDL Element Details.

Regenerating Web Services

If the interface definition is changed or the selected interaction pattern information is modified, the web service can be regenerated by clicking Regenerate. Upon regeneration, the service definition along with interaction pattern information will also be changed to reflect the changes done in the interface. You need to modify its web service clients based on the new service definition.

If interface definition is not changed, then regenerating the service would not change the service definition. You can continue to use the existing web service clients with the new service definition.

For more information on generating SOAP services, see Generating SOAP Web Services, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Reviewing WSDL Element Details

If an interface is exposed as a web service, the corresponding WSDL file is displayed in the interface details page.

Clicking the View WSDL link to launch a new window containing the associate WSDL document. This XML-based document describes the selected web service and how the service can be used.

For example, click the deployed View WSDL link for the PL/SQL: Invoice Creation from the interface details page, the WSDL document appears.

Deployed SOAP Service WSDL Description

Note: The http://<hostname>:<port>/soa-infra/services/default/<sid>_PLSQL_AR_INVOICE_API_PUB/AR_INVOICE_API_PUB_Service?wsdl address in the new window has the exact WSDL URL information that appeared in the interface details page. You can copy and use this address directly in any of the web service clients, such as in a BPEL process during a partner link creation.

WSDL Document Structure

A WSDL document is simply a set of definitions. There is a definitions element at the root, and definitions inside. The definitions element defines the set of services that the web service offers.

The definitions element often contains an optional TargetNamespace property, a convention of XML schema that enables the WSDL document to refer to itself.

For example, the definitions element in the WSDL document for the Invoice Creation API (AR_INVOICE_API_PUB) appears:

<definitions name="AR_INVOICE_API_PUB" targetNamespace="http://xmlns.oracle.com/apps/ar/soaprovider/plsql/ar_invoice_api_pub/"/>

This element specifies numerous namespaces that will be used throughout the remainder of the document.

In addition to the definitions element, web services are defined using the following six major elements:

• Types: It provides data type definitions used to describe the messages exchanged.

• Message: It represents an abstract definition of the data being transmitted.

• PortType: It is a set of abstract operations. Each operation refers to an input message and output message.

• Binding: It specifies concrete protocol and data format specifications for the operations and messages defined by a particular portType.

• Port: It specifies an address for a binding, thus defining a single communication endpoint.

• Service: It is used to aggregate a set of related ports.

The following diagram illustrates the relationship of the basic parts of WSDL:

Types

The types element contains all data types used in all method calls described in the WSDL. It can be used to specify the XML Schema (xsd:schema) that is used to describe the structure of a WSDL Part.

The structure of this Types element can be like:

<definitions...>
        <types>
                <xsd:schema.../>*
   </types>
</definitions>

For example, the Invoice Creation Web service contains the following two functions:

• CREATE_INVOICE

• CREATE_SINGLE_INVOICE

Each function is described in the data type definition. WSDL prefers the use of XSD as the type of system mechanism to define the types in a message schema. As a result, the message schema location of the CREATE_INVOICE function with the synchronous operation pattern is defined in the APPS_ISG_XX_AR_INVOICE_API_PUB-24CREATE_INV.xsd, and with the asynchronous pattern is defined in the CREATE_INVOICE_ASYNCH.xsd. The message schema location of the CREATE_SINGLE_INVOICE function with the synchronous operation pattern is defined in the APPS_ISG_XX_AR_INVOICE_API_PUB-24CREATE_SIN.xsd, and with the asynchronous pattern is defined in the CREATE_SINGLE_INVOICE_ASYNCH.xsd.

Note: For a generated service that has not yet been deployed, the abstract WSDL description displays a temporary location for the schema location (such as <include schemaLocation="http://<hostname>:<port>/isgctx/isgapp/plsql/ar_invoice_api_pub/APPS_ISG_XX_AR_INVOICE_API_PUB-24CREATE_INV.xsd" />).

For a deployed service, a physical location of service endpoint where the service is hosted in soa-infra is displayed instead as shown here:

<types>
  <schema elementFormDefault="qualified" 
   targetNamespace="http://xmlns.oracle.com/apps/ar/soaprovider/plsql/ar_invoice_api_pub/create_invoice/">
    <include schemaLocation="http://<soa_suite_hostname>:<port>/soa-infra/services/default/<jndi_name>_PLSQL_AR_INVOICE_API_PUB/AR_INVOICE_API_PUB_Service?XSD=xsd/APPS_ISG_XX_AR_INVOICE_API_PUB-24CREATE_INV.xsd" />
  </schema>
          <schema elementFormDefault="qualified" 
                targetNamespace="http://xmlns.oracle.com/apps/ar/soaprovider/plsql/ar_invoice_api_pub/create_single_invoice/">
                <include schemaLocation="http://<soa_suite_hostname>:<port>/soa-infra/services/default/<jndi_name>_PLSQL_AR_INVOICE_API_PUB/AR_INVOICE_API_PUB_Service?XSD=xsd/APPS_ISG_XX_AR_INVOICE_API_PUB-24CREATE_SIN.xsd"/> 
  </schema>
  <schema elementFormDefault="qualified" 
    targetNamespace="http://xmlns.oracle.com/apps/ar/soaprovider/plsql/ar_invoice_api_pub/">
    <element name="SOAHeader">
     ...
    </element>
  </schema>
   <schema elementFormDefault="qualified" 
   targetNamespace="http://xmlns.oracle.com/apps/ar/soaprovider/plsql/ar_invoice_api_pub/create_invoice/">
    <include schemaLocation="http://<soa_suite_hostname>:<port>/soa-infra/services/default/<jndi_name>_PLSQL_AR_INVOICE_API_PUB/AR_INVOICE_API_PUB_Service?XSD=xsd/APPS_ISG_XX_AR_INVOICE_API_PUB-24CREATE_INV.xsd" />
  </schema>
          <schema elementFormDefault="qualified" 
                targetNamespace="http://xmlns.oracle.com/apps/ar/soaprovider/plsql/ar_invoice_api_pub/create_single_invoice/">
                <include schemaLocation="http://<soa_suite_hostname>:<port>/soa-infra/services/default/<jndi_name>_PLSQL_AR_INVOICE_API_PUB/AR_INVOICE_API_PUB_Service?XSD=xsd/APPS_ISG_XX_AR_INVOICE_API_PUB-24CREATE_SIN.xsd"/> 
  </schema>
  <schema elementFormDefault="qualified" 
   targetNamespace="http://xmlns.oracle.com/apps/ar/soaprovider/plsql/ar_invoice_api_pub/create_invoice_asynch">
    <include schemaLocation="http://<soa_suite_hostname>:<port>/soa-infra/services/default/<jndi_name>_PLSQL_AR_INVOICE_API_PUB/AR_INVOICE_API_PUB_Service?XSD=xsd/CREATE_INVOICE_ASYNCH.xsd" />
  </schema>
          <schema elementFormDefault="qualified" 
                targetNamespace="http://xmlns.oracle.com/apps/ar/soaprovider/plsql/ar_invoice_api_pub/create_single_invoice_asynch/">
                <include schemaLocation="http://<soa_suite_hostname>:<port>/soa-infra/services/default/<jndi_name>_PLSQL_AR_INVOICE_API_PUB/AR_INVOICE_API_PUB_Service?XSD=xsd/CREATE_SINGLE_INVOICE_ASYNCH.xsd"/> 
  </schema>
</types> 

In addition to message schema locations and schema elements that help to define web messages, the Types element can take complex data type as input.

For example, the Responsibility, Responsibility Application, Security Group, NLS Language, and Organization ID complex types listed under the "SOAHeader" as shown below are used in passing values to set the application context during the service invocation.

...
<schema elementFormDefault="qualified" 
 targetNamespace="http://xmlns.oracle.com/apps/ar/soaprovider/plsql/ar_invoice_api_pub/">
                        <element name="SOAHeader">
                                <complexType>
                                        <sequence> 
                                                <element name="Responsibility" minOccurs="0" type="string"/>
                        <element name="RespApplication" minOccurs="0" type="string"/>
                        <element name="SecurityGroup" minOccurs="0" type="string"/>
                        <element name="NLSLanguage" minOccurs="0" type="string"/>
               <element name="Org_Id" minOccurs="0" type="string" />
                                </sequence>
                                </complexType>
                </element>
        </schema>
...

Message

The Message element defines the name of the message. It consists of one or more Part elements, which describe the content of a message using Element or Type attributes.

Parts describe the logical abstract content of a message. A binding may reference the name of a part in order to specify binding-specific information about the part.

The structure of this element can be like:

<definitions...>
        <message name="nmtoken"> *
                <part name="nmtoken" element="qname"? type="qname"? />   
        </message>
</definitions>

A typical document-style web service could have a header and body part in the input message and output message as well. For example, the Message element for the Invoice Creation Web service appears:

<message name="CREATE_INVOICE_Input_Msg">
        <part name="header" element="tns:SOAHeader"/> 
   <part name="body" element="tns1:InputParameters"/> 
</message>
<message name="CREATE_INVOICE_Output_Msg">
   <part name="body" element="tns1:OutputParameters"/> 
</message>
<message name="CREATE_SINGLE_INVOICE_Input_Msg">
        <part name="header" element="tns:SOAHeader"/> 
   <part name="body" element="tns2:InputParameters"/> 
</message>
<message name="CREATE_SINGLE_INVOICE_Output_Msg">
        <part name="body" element="tns2:InputParameters"/> 
</message>
<message name="CREATE_INVOICE_ASYNCH_Input_Msg">
        <part name="header" element="tns:SOAHeader"/> 
   <part name="body" element="tns1:InputParameters"/> 
</message>
<message name="CREATE_SINGLE_INVOICE_ASYNCH_Input_Msg">
        <part name="header" element="tns:SOAHeader"/> 
   <part name="body" element="tns2:InputParameters"/> 
</message>
<message name="CREATE_INVOICE_ASYNCH_Output_Msg">
   <part name="body" element="tns1:OutputParameters"/> 
</message>
<message name="CREATE_SINGLE_INVOICE_ASYNCH_Output_Msg">
        <part name="body" element="tns2:InputParameters"/> 
</message>

Each message defined by the associated schema includes input message and output message parts. For example, the Invoice Creation Web service has two functions:

• CREATE_INVOICE

  The input message of this function is defined by CREATE_INVOICE_Input_Msg for the synchronous operation pattern and CREATE_INVOICE_ASYNCH_Input_Msg for the asynchronous pattern.

  The output message of this function which gives its result is defined by CREATE_INVOICE_Output_Msg for the synchronous operation pattern and CREATE_INVOICE_ASYNCH_Output_Msg for the asynchronous pattern.

  The schema of input and output messages is defined in the APPS_ISG_XX_AR_INVOICE_API_PUB-24CREATE_INV.xsd for the synchronous pattern, and in the CREATE_INVOICE_ASYNCH.xsd for the asynchronous pattern.

• CREATE_SINGLE_INVOICE

  The input message of this function is defined by CREATE_SINGLE_INVOICE_Input_Msg for the synchronous operation pattern and CREATE_SINGLE_INVOICE_ASYNCH_Input_Msg for the asynchronous pattern.

  The output message of this function which gives its result is defined by CREATE_SINGLE_INVOICE_Output_Msg for the synchronous operation pattern and CREATE_SINGLE_INVOICE_ASYNCH_Output_Msg for the asynchronous pattern.

  The schema of input and output messages is defined in the APPS_ISG_XX_AR_INVOICE_API_PUB-24CREATE_SIN.xsd for the synchronous pattern, and in the CREATE_SINGLE_INVOICE_ASYNCH.xsd for the asynchronous pattern.

The value of body part of each message will be set as SOAP body; the value of header part will be set in the SOAP header which is required for web service authorization.

For more information, see Understanding Web Service Input Message Parts.

PortType

The portType element combines multiple message elements to form a complete one-way or round-trip operation supported by a web service.

For example, a portType element can combine one request (input message element) message and one response (output message element) message into a Synchronous Request - Response operation, most commonly used in SOAP services.

If it is for one-way operation, then the operation would contain an Input element only.

The structure of this element can be like:

<wsdl:definitions...>
        <wsdl:portType name="nmtoken">*
                <operation name="nmtoken"/> 
                        <wsdl:input name="nmtoken"? message="qname">?  
                                </wsdl:input>
                                <wsdl:output name="nmtoken"? message="qname">?  
                                </wsdl:output>
                                <wsdl:fault name="nmtoken"? message="qname">? 
                                </wsdl:fault>
                        </wsdl:operation> 
        </wsdl:portype>
</wsdl:definitions>

Note: An optional Fault element can be used for error handling in both request-response and solicit response operation models. This feature is not supported in this release.

In this Invoice Creation Web service example, corresponding to the above two functions, AR_INVOICE_API_PUB_PortType has the following two operations:

• CREATE_INVOICE

  • Input: CREATE_INVOICE_Input_Msg

  • Output: CREATE_INVOICE_Output_Msg

• CREATE_SINGLE_INVOICE

  • Input: CREATE_SINGLE_INVOICE_Input_Msg

  • Output: CREATE_SINGLE_INVOICE_Output_Msg

For the Synchronous Request-Response operation pattern, input and output messages appear as follows:

<portType name="AR_INVOICE_API_PUB_PortType">
                <operation name="CREATE_INVOICE"> 
                <input name="tns:CREATE_INVOICE_Input_Msg" /> 
                                <output name="tns:CREATE_INVOICE_Output_Msg" />   
                        </operation> 
                        <operation name="CREATE_SINGLE_INVOICE"> 
                <input name="tns:CREATE_SINGLE_INVOICE_Input_Msg" /> 
                                <output name="tns:CREATE_SINGLE_INVOICE_Output_Msg" />   
                        </operation>
</portype>

For the Asynchronous Request-Response operation pattern, to distinguish it from the rest of operations generated synchronously, ASYNCH appears in both input and output (response) messages.

For example, if the 'CREATE_INVOICE' operation is generated asynchronously, ASYNCH appears specifically for the 'CREATE_INVOICE' operation in both input and output (response) messages.

...
<portType name="AR_INVOICE_API_PUB_PortType">
   <operation name="CREATE_INVOICE_ASYNCH">
     <input name="tns:CREATE_INVOICE_Input_Msg"/>
   </operation>
</portType>
<portType name="AR_INVOICE_API_PUB_Callback_PortType">
   <operation name="CREATE_INVOICE_ASYNCH_RESPONSE">
     <input name="tns:CREATE_INVOICE_Output_Msg"/>
   </operation>
</portType>
<portType name="AR_INVOICE_API_PUB_CallBack_PortType>
   <operation name="CREATE_INVOICE_ASYNCH_RESPONSE">
     <input message="tns:CREATE_INVOICE_ASYNCH_Output_Msg"/>
   </operation>
   <operation name="CREATE_SINGLE_INVOICE_ASYNCH_RESPONSE">
     <input message="tns:CREATE_SINGLE_INVOICE_ASYNCH_Output_Msg"/>
   </operation>
</portType>

Binding

A binding defines message format and protocol details for operations and messages defined by a particular portType. It provides specific details on how a portType operation will actually be transmitted over the Web.

A port defines an individual endpoint by specifying a single address for a binding.

The structure of this element can be like:

<wsdl:definitions...>
        <wsdl:binding name="nmtoken" type="qname">*
        <wsdl:operation name="nmtoken"/> 
                <wsdl:input> ?
        </wsdl:input>
                        <wsdl:output>?  
                        </wsdl:output>
                        <wsdl:fault name="nmtoken"? message="qname">? 
                        </wsdl:fault>
                </wsdl:operation> 
        </wsdl:binding>
</wsdl:definitions>

In the same example, the binding element as shown below describes the SOAP binding for PortType AR_INVOICE_API_PUB_PortType.

<binding name="AR_INVOICE_API_PUB_Binding" type="tns:AR_INVOICE_API_PUB_PortType">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> 
     <wsp:PolicyReference URI="#wss_username_token_service_policy" wsdl:required="false"/>
     <operation name="CREATE_INVOICE"> 
                        <soap:ooperation soapAction="CREATE_INVOICE" /> 
                        <input>
                                        <soap:header message="tns:CREATE_INVOICE_Input_Msg" part="header" use="literal" />
                                        <soap:body parts="body" use="literal" /> 
                </input>
                        <output>
                                        <soap:body use="literal" /> 
                        </output>                   
                        </operation> 
                        <operation name="CREATE_SINGLE_INVOICE"> 
                <soap:operation soapAction="CREATE_SINGLE_INVOICE" /> 
                                <input>
                                        <soap:header message="tns:CREATE_SINGLE_INVOICE_Input_Msg" part="header" use="literal" />
                                        <soap:body parts="body" use="literal" /> 
                        </input>
                                <output>
                                        <soap:body use="literal" /> 
                                </output>                   
                        </operation>
      <operation name="CREATE_INVOICE_ASYNCH"> 
                <soap:operation soapAction="CREATE_INVOICE_ASYNCH" /> 
                                <input>
                                        <soap:header message="tns:CREATE_INVOICE_ASYNCH_Input_Msg" part="header" use="literal"/>
                                        <soap:body parts="body" use="literal" /> 
                        </input>                    
                        </operation>
      <operation name="CREATE_SINGLE_INVOICE_ASYNCH"> 
                <soap:operation soapAction="CREATE_SINGLE_INVOICE_ASYNCH" /> 
                                <input>
                                        <soap:header message="tns:CREATE_SINGLE_INVOICE_ASYNCH_Input_Msg" part="header" use="literal"/>
                                        <soap:body parts="body" use="literal" /> 
                        </input>                    
                        </operation>    
        </binding

For Asynchronous Request-Response operation pattern, the binding element as shown below describes the SOAP binding for PortType AR_INVOICE_API_PUB_CallBack_PortType:

<binding name="AR_INVOICE_API_PUB_CallBack_Binding" type="tns:AR_INVOICE_API_PUB_CallBack_PortType">
 <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
   <operation name="CREATE_INVOICE_ASYNCH_RESPONSE">
     <soap:operation soapAction="CREATE_INVOICE_ASYNCH_RESPONSE"/> 
       <input>
         <soap:body use="literal" namespace="http://xmlns.oracle.com/apps/ar/soaprovider/plsql/ar_invoice_api_pub/CREATE_INVOICE_ASYNCH"/> 
       </input>
     </operation>
     <operation name="CREATE_SINGLE_INVOICE_ASYNCH_RESPONSE">
     <soap:operation soapAction="CREATE_SINGLE_INVOICE_ASYNCH_RESPONSE"/> 
       <input>
         <soap:body use="literal" namespace="http://xmlns.oracle.com/apps/ar/soaprovider/plsql/ar_invoice_api_pub/CREATE_SINGLE_INVOICE_ASYNCH"/>       
       </input>
     </operation>
</binding>

The binding is always document style for SOAP over HTTP binding. It also defines the content of SOAP header and SOAP body.

Note: Because it is a document-style service (style="document"), the request and response messages will consist of simply XML documents, instead of using the wrapper elements required for the remote procedure call (RPC-style) web service. The transport attribute indicates the transport of the SOAP messages is through SOAP HTTP.

The soap:operation element indicates the binding of a specific operation (such as CREATE_INVOICE) to a specific SOAP implementation. The soapAction attribute specifies that the SOAPAction HTTP header is used for identifying the service.

The soap:header element allows header to be defined that is transmitted inside the Header element of the SOAP Envelope. The SOAHeader comprises of Responsibility, RespApplication, SecurityGroup, NLSLanguage, and Org_Id complex types within the Types element.

The soap:body element enables you to specify the details of the input and output messages for a specific operation.

Service

The service element defines the web service. It consists of one or more Port elements. A port defines an individual endpoint by specifying a single address for a binding.

The service binding is commonly created using SOAP.

The structure of this element can be like:

<wsdl:definitions...>
        <wsdl:service name="nmtoken">*
                <wsdl:port name="nmtoken" binding="qname"> *
        </wsdl:port>      
        </wsdl:service>
</wsdl:definitions>

For a deployed service, the Service element AR_INVOICE_API_PUB_Service defines a physical location of service endpoint where the service is hosted in soa-infra for the portType AR_INVOICE_API_PUB_PortType.

<service name="AR_INVOICE_API_PUB_Service">
                <port name="AR_INVOICE_API_PUB_Port" binding="tns:AR_INVOICE_API_PUB_Binding">
                        <soap:address location="http://<soa_suite_hostname>:<port>/soa-infra/services/default/<jndi_name>_PLSQL_AR_INVOICE_API_PUB/AR_INVOICE_API_PUB_Service/"/>
                </port>
        </service>

Note: For a generated service that has not yet been deployed, 'Not_Deployed' is shown in the soap:address location element (such as <soap:address location="#NOT_DEPLOYED#"/>).

Reviewing WADL Element Details

If an interface is exposed as a REST service, you can view the corresponding WADL description in a separate window.

Take a concurrent program interface called "Transaction Layout Definition" (ECRDTLD) as an example to explain the WADL elements. To view the associated WADL information, click View WADL link in the REST Web Service tab of the interface details page. The WADL document appears.

WADL Document Structure

WADL (Web Application Description Language) is designed to provide a machine processable description of HTTP-based web applications.

The application element forms the root of a WADL description. It may contain the following elements:

• Grammars: This element serves as a container for definitions of data exchanged during the implementation of the protocol described by the WADL document.

• Resources: This element serves as a container for all the included child resource elements provided by the application.

<?xml version="1.0" encoding="UTF-8" standalone="no" ?> 
<application xmlns:tns="http://xmlns.oracle.com/apps/ec/soaprovider/concurrentprogram/rest/ecrdtld/" xmlns="http://wadl.dev.java.net/2009/02" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:tns1="http://xmlns.oracle.com/apps/ec/concurrentprogram/rest/ec/ecrdtld/" name="ECRDTLD" 
targetNamespace="http://xmlns.oracle.com/apps/ec/soaprovider/concurrentprogram/rest/ecrdtld/">
        <grammars>
...
        </grammars>
   <resources base="http://<hostname>:<port>/webservices/rest/ec/">
                ...
        </resources
</application>

Grammars

This element acts as a container for definitions of data exchanged during the implementation of the protocol described by the WADL document. The Include element is often referenced to allow the definitions of one or more data format descriptions to be included.

     <grammars>
                <include xmlns="http://www.w3.org/2001/XMLSchema" href="http://<hostname>:<port>/webservices/rest/ec/?XSD=ECRDTLD_SYNCH_TYPEDEF.xsd" /> 
        </grammars>

In this example, the included service operation with the support for synchronous pattern ECRDTLD_SYNCH_TYPEDEF is referenced in the Include element.

ec highlighted here is the service alias name entered earlier prior to the service deployment. Once the service has been successfully deployed, the specified alias name (ec) becomes part of the service endpoint in the WADL and namespaces in the XSDs.

Resources

The resources element represents the resource information provided by the Web application. It includes a base attribute that provides the base URI for each included child resource identifier.

For example, each child resource element represents a specific service operation (such as ecrdtld) contained in the selected interface.

     <resources base="http://<hostname>:<port>/webservices/rest/ec/">
                <resource path="/ecrdtld/">
                        ...
                </resource>
        </resources>

Resource

The resources element may contain a set of resource elements; each resource element represents a REST service operation. In this example, "ecrdtld" is included a child resource element.

Each resource element can include the following child elements:

• Method: This element describes the input to and output from an HTTP protocol method that can be applied to the resource.

  POST is the only supported method for Concurrent Program REST services; POST and GET are the supported methods for PL/SQL APIs, Java Bean Services, Application Module Services, and Business Service Object REST services.

  For Open Interfaces, the supported methods are determined based on the direction of the interface. For open interface tables with Inbound direction, all four HTTP methods (GET, POST, PUT, and DELETE) are supported. Otherwise, only GET is supported for open interface tables with Outbound direction and open interface views.

• Request: This element describes the input to be included when applying an HTTP method to a resource.

  Element mediaType indicates the supported media type, such as XML and JSON, for the input parameters.

• Response: This element describes the output results from performing an HTTP method on a resource.

  The supported media types for the output results are XML and JSON.

     <resources base="http://<hostname>:<port>/webservices/rest/ec/">
                <resource path="/ecrdtld/">
                        <method id="ECRDTLD" name="POST">
                                <request>
                                        <representation mediaType="application/xml" type="ECRDTLD_InputParameters" /> 
                                        <representation mediaType="application/json" type="ECRDTLD_InputParameters" /> 
                                </request>
                                <response>
                                        <representation mediaType="application/xml" type="ECRDTLD_OutputParameters" /> 
                                        <representation mediaType="application/json" type="ECRDTLD_OutputParameters" /> 
                                </response>
                        </method>
                </resource>
        </resources>

In this example, input request and output response messages are all supported with the XML and JSON formats when applying the HTTP method POST for the resource element ecrdtld.

If the deployed REST service is an interface type of PL/SQL, Business Service Object, Java Bean Services, or Application Module Services, then both GET and POST can be shown as the supported methods in the REST service operation. For example, the following WADL description shows two of many methods contained in the "Rest Service Locator" interface. The addGrant method is implemented with the POST HTTP method, and the getOperations method is assisted with the GET HTTP method.

     <resources base="http://<hostname>:<port>/webservices/rest/locator/">
                <resource path="/addGrant/">
                        <method id="addGrant" name="POST">
                                <request>
                                        <representation mediaType="application/xml" type="tns1:addGrant_InputParameters" /> 
                                        <representation mediaType="application/json" type="tns1:addGrant_InputParameters" /> 
                                </request>
                        <response>
                                        <representation mediaType="application/xml" type="tns1:addGrant_OutputParameters" /> 
                                        <representation mediaType="application/json" type="tns1:addGrant_OutputParameters" /> 
                                </response>
                        </method>
                </resource>
...
                <resource path="/getOperations/{irepClassName}/">
                  <param name="irepClassName" style="template" required="true" type="xsd:string"/>
                        <method id="getOperations" name="GET">
                                <request>
                                        <param name="ctx_responsibility" type="xsd:string" style="query" required="false" />
              <param name="ctx_respapplication" type="xsd:string" style="query" required="false" />
                                        <param name="ctx_securitygroup" type="xsd:string" style="query" required="false" />
                                        <param name="ctx_nlslanguage" type="xsd:string" style="query" required="false" />
                                        <param name="ctx_orgid" type="xsd:int" style="query" required="false" />
                                </request>
                        <response>
                                        <representation mediaType="application/xml" type="tns3:getOperations_OutputParameters" /> 
                                        <representation mediaType="application/json" type="tns3:getOperations_OutputParameters" /> 
                                </response>
                        </method>
                </resource>
</resources>

The GET method of the above example contains the path variable and application context information if required for the service invocation:

Note: Path variables and context parameters are applicable only for the HTTP GET method.

• {irepClassName} is a path variable for "getOperations" operation as specified below:

  <resource path="/getOperations/{irepClassName}/">

  The path variable is defined using the <param> tag after the <resource> tag and before the <method> tag. A service client will replace the path variable with actual value at runtime when the HTTP GET method is invoked.

  For example, if the value of the irepClassName is ''PLSQL:FND_PROFILE", then "PLSQL:FND_PROFILE" should be passed in the HTTP URL for this request. The URL on which the HTTP GET will be performed is: http://<hostname>:<port>/webservices/rest/locator/getOperations/PLSQL:FND_PROFILE

  Path variables are identified by inline annotation @rep:key_param in the Java API source file. For the annotation guidelines on Java Bean Services, see Annotations for Java Bean Services. For more Application Module Services annotation guidelines, see Annotations for Application Module Services.

• Context parameters are predefined parameters required for initializing Oracle E-Business Suite application context. These parameters including ctx_responsibility, ctx_respapplication, ctx_securitygroup, ctx_nlslanguage, and ctx_orgid are applicable only for the HTTP GET method and DELETE method (as shown in the following example for open interface table). These parameters are passed as query strings, along with the request payload query strings in the RESTHeader element.

Control parameters are predefined query parameters that may be used for a resource or collection resource. For example, use the offset and limit parameters to limit the number of records returned and for pagination.

offset=<number>&limit=<number>

• offset=0&limit5

  This returns the first 5 records of response after record 0. That is the 1st, 2nd, 3rd, 4th, and 5th records.

• offset=2&limit4

  This returns the first 4 records of response after record 2. That is the 3rd, 4th, 5th and 6th records.

• http://<hostname>:<port>/webservices/rest/empinfo/getAllReports/?offset=0&limit=5

  This returns the first 5 employees reporting to a logged in user in hierarchical order.

If the deployed REST service is an open interface table with Inbound direction, then the service operation table displays all four HTTP methods. In the following WADL example for the AR Autoinvoice (associated concurrent program internal name RAXMTR) open interface table, the RA_INTERFACE_LINES_ALL operation is implemented with all four HTTP methods, and the associated concurrent program SUBMIT_CP_RAXMTR is implemented with the POST method.

     <resources base="http://<hostname>:<port>/webservices/rest/autoinvoice/">
  <resource path ="RA_INTERFACE_LINES_ALL/"> 
        <method id="RA_INTERFACE_LINES_ALL_get" name="GET">
                <request>
                                <param name="ctx_responsibility" type="xsd:string" style="query" required="false"/>
                <param name="ctx_respapplication" type="xsd:string" style="query" required="false" />
                                <param name="ctx_securitygroup" type="xsd:string" style="query" required="false" />
                                <param name="ctx_nlslanguage" type="xsd:string" style="query" required="false" />
                                <param name="ctx_orgid" type="xsd:int" style="query" required="false" />
                                <param name="select" type="xsd:string" style="query" required="false"/>
                                <param name="filter" type="xsd:string" style="query" required="false"/>
                                <param name="sort" type="xsd:string" style="query" required="false"/>
                                <param name="offset" type="xsd:string" style="query" required="false"/>
                                <param name="limit" type="xsd:string" style="query" required="false"/>
                        </request>
                        <response>
                                <representation mediaType="application/xml" type="tns1:RA_INTERFACE_LINES_ALL_Output"/> 
                                <representation mediaType="application/json" type="tns1:RA_INTERFACE_LINES_ALL_Output" />
                                <representation mediaType="text/csv" type="tns1:RA_INTERFACE_LINES_ALL_Output"/> 
                        </response>
        </method>
        <method id="RA_INTERFACE_LINES_ALL_post" name="POST">
                   <request>
                                <representation mediaType="application/xml" type="tns1:RA_INTERFACE_LINES_ALL_Input"/> 
                                <representation mediaType="application/json" type="tns1:RA_INTERFACE_LINES_ALL_Input" />
                                <representation mediaType="text/csv" type="tns1:RA_INTERFACE_LINES_ALL_Input"/>
                        </request>
                        <response>
                                <representation mediaType="application/xml" type="tns1:RA_INTERFACE_LINES_ALL_Output"/> 
                                <representation mediaType="application/json" type="tns1:RA_INTERFACE_LINES_ALL_Output" />
                                <representation mediaType="text/csv" type="tns1:RA_INTERFACE_LINES_ALL_Output"/> 
                        </response>
        </method>
        <method id="RA_INTERFACE_LINES_ALL_put" name="PUT">
                   <request>
                                <representation mediaType="application/xml" type="tns1:RA_INTERFACE_LINES_ALL_Input"/> 
                                <representation mediaType="application/json" type="tns1:RA_INTERFACE_LINES_ALL_Input" />
                                <representation mediaType="text/csv" type="tns1:RA_INTERFACE_LINES_ALL_Input"/>
                        </request>
                        <response>
                                <representation mediaType="application/xml" type="tns1:RA_INTERFACE_LINES_ALL_Output"/> 
                                <representation mediaType="application/json" type="tns1:RA_INTERFACE_LINES_ALL_Output" />
                                <representation mediaType="text/csv" type="tns1:RA_INTERFACE_LINES_ALL_Output"/> 
                        </response>
        </method>
        <method id="RA_INTERFACE_LINES_ALL_delete" name="DELETE">
                   <request>
                                <param name="ctx_responsibility" type="xsd:string" style="query" required="false"/>
                <param name="ctx_respapplication" type="xsd:string" style="query" required="false" />
                                <param name="ctx_securitygroup" type="xsd:string" style="query" required="false" />
                                <param name="ctx_nlslanguage" type="xsd:string" style="query" required="false" />
                                <param name="ctx_orgid" type="xsd:int" style="query" required="false" />
                                <param name="filter" type="xsd:string" style="query" required="false"/>
                        </request>
                        <response>
                                <representation mediaType="application/xml" type="tns1:RA_INTERFACE_LINES_ALL_Output"/> 
                                <representation mediaType="application/json" type="tns1:RA_INTERFACE_LINES_ALL_Output" />
                                <representation mediaType="text/csv" type="tns1:RA_INTERFACE_LINES_ALL_Output"/> 
                        </response>
        </method>
</resource>

• Each open interface table name contained in the selected open interface "AR Autoinvoice" is displayed in one resource entry (<resource path>) with the selected HTTP methods. In this example, table name RA_INTERFACE_LINES_ALL with the four selected methods (GET, POST, PUT, and DELETE) is contained in one resource entry, and the associated concurrent program SUBMIT_CP_RAXMTR with POST is contained in another resource entry.

• The WADL description for the open interface view contains only one resource entry with the GET method only. There is no concurrent program SUBMIT_CP_<internal name of the concurrent program> associated with the open interface view.

Understanding SOAP Messages

SOAP (Simple Object Access Protocol) is a lightweight, XML-based protocol specification for exchanging structured information in the implementation of web services in computer networks. For example, a web service provider receives SOAP requests from web service clients to invoke web services and also sends the corresponding SOAP responses out to the clients.

SOAP Message Structure

SOAP messages are contained in one of the SOAP components called Envelope. The SOAP envelop defines an overall framework for describing what is in a message, who should deal with it, and whether it is optional or mandatory. It consists of the following elements:

• Header (Optional)

  An envelope element can optionally have a Header element. If an envelope contains a Header element, it must contain no more than one, and it must appear as the first child of the envelope. The first level child elements of the Header element are called Header Blocks.

  Header blocks can be used in the following mechanisms:

  • It can be used to attach security related information targeted at a specific recipient.

    For more information, see SOAP Security Header.

  • It can be used to set the application context values required for services.

    For more information, see SOAP Header for Application Context.

  • It can be used to populate mandatory header variables for XML Gateway inbound transactions to be completed successfully.

    For more information, see SOA Header for XML Gateway Messages.

• Body

  Every envelope element must contain exactly one Body element that holds the message. Immediate child elements of the Body element are called Body Blocks or Parts.

• Attachment (Optional)

  A SOAP message can carry multiple attachments and these attachments can be of any type including text, binary, image, and so on.

The following diagram depicts the structure of a SOAP message.

SOAP Message Structure

A skeleton of a SOAP message can be like:

<xml version="1.0">
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:Header>
...
</soap:Header>

<soap:Body>
...
   <soap:Fault>
    ...
   </soap:Fault>
</soap:Body>

</soap:Envelope>

SOAP Security Header

When a SOAP request message is received through Oracle SOA Suite for the deployed SOA Composites in an Oracle WebLogic managed server, the SOAP message is authenticated by a JAAS (Java Authentication and Authorization Service) based login module for Oracle E-Business Suite.

A SOAP message is authenticated using either the UsernameToken or SAML Token security model which has been identified earlier for a service before being deployed. The selected authentication information is embedded in the wsse:security Web Security header.

UsernameToken-based SOAP Security Header

A UsernameToken-based SOAP header should include the following wsse:security section:

<soapenv:Header>
<http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
soapenv:mustUnderstand="1">
        <wsse:UsernameToken>
                <wsse:Username>Username</wsse:Username>
                <wsse:Password>Password</wsse:Password>
        </wsse:UsernameToken>
</wsse:Security>

</soapenv:Header>

Note: When the <wsse:security> header includes a mustUnderstand="1" attribute, then the receiver must generate a fault if it is unable to interpret or process security tokens contained the <wsse:security> header block according to the corresponding WS SOAP message security token profiles.

See A Sample Fault SOAP Response.

A typical WS-Security header in a SOAP request can be like:

<soapenv:Header>
<http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
soapenv:mustUnderstand="1">
        <wsse:UsernameToken>
                <wsse:Username>myUser</wsse:Username>
                <wsse:Password 
                Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</wsse:Password>
        </wsse:UsernameToken>
</wsse:Security>

</soapenv:Header>

The UsernameToken-based security includes UsernameToken profile which provides user name and password information in the web service security header. User name is a clear text; password is the most sensitive part of the UsernameToken profile. In this security model, the supported password type is plain text password (or PasswordText).

Note: The PasswordText password type is the password written in clear text. SOAP requests invoking the web services should include the security header consisting of a user name and plain text password. The password received as part of the SOAP request at runtime will be validated against the encrypted password stored in Oracle E-Business Suite. After validation, the plain text password from the SOAP request will be discarded.

The user name and password in the SOAP Header of a SOAP message will be passed to authenticate web services. The user name and password discussed here in wsse:security is the Oracle E-Business Suite user name and password (or the user name and password created through the Users window in defining an application user).

Passing security header elements, along with the SOAP request, is essential to the success of invoking Oracle E-Business Suite web services.

If these security header values are not passed, the web service will not be authenticated and the invocation of the service will be failed.

For detailed instructions on how to pass the security header when invoking an Oracle E-Business Suite web service, see Configuring Web Service Policies.

SAML Token-based SOAP Security Header

Security Assertion Markup Language (SAML) is an XML-based standard for exchanging authentication and authorization data between security domains, that is, between an identity provider and a service provider.

When a web application invokes a service that uses SAML as its authentication mechanism, this SOAP request message containing or referencing SAML assertions is received through Oracle SOA Suite and passed on to a JAAS based login module for Oracle E-Business Suite for authentication based on the wsse:security Web Security headers. As part of the validation and processing of the assertions, the receiver or login module for Oracle E-Business Suite must establish the relationship among the subject, claims of the referenced SAML assertions, and the entity providing the evidence to satisfy the confirmation method defined for the statements.

A trusted entity uses the sender-vouches confirmation method to ensure that it is acting on behalf of the subject of SAML statements attributed with a sender-vouches SubjectConfirmation element.

The following SOAP example describes a trusted entity that uses the sender-vouches subject confirmation method with an associated <ds:Signature> element to establish its identity and to assert that it has sent the message body on behalf of the subject(s):

<soapenv:Envelope
xmlns:fnd="http://xmlns.oracle.com/apps/fnd/soaprovider/plsql/fnd_user_pkg/" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
 <soapenv:Header>
  <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
    <ds:Signature Id="Signature-xxxxxxxx" xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <ds:SignedInfo>
    <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
    <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
    <ds:Reference URI="#id-xxxxxxxx">
    <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
    </ds:Transforms>
    <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
    <ds:DigestValue>xxx/xxxxxxxxxxxxxxxxxxxxx/xx</ds:DigestValue>
    </ds:Reference>
    </ds:SignedInfo>
    <ds:SignatureValue>
    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/
xxxxxxxxxxxxxxxxxx
   </ds:SignatureValue>
   <ds:KeyInfo Id="KeyId-xxxxxxx">
        <wsse:SecurityTokenReference wsu:Id="STRId-xxxxxxx" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"><wsse:KeyIdentifier 
   EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary" 
   ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509SubjectKeyIdentifier">ADoNKKuduSTKTwi7jqEzCxwD7JU=</wsse:KeyIdentifier></wsse:SecurityTokenReference>
  </ds:KeyInfo></ds:Signature>
  <Assertion AssertionID="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" IssueInstant="2010-02-27T17:26:21.241Z" Issuer="www.oracle.com" MajorVersion="1" MinorVersion="1" xmlns="urn:oasis:names:tc:SAML:1.0:assertion" xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion" xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><Conditions NotBefore="2010-02-27T17:26:21.241Z" NotOnOrAfter="2011-02-27T17:26:21.241Z"/>
    <AuthenticationStatement AuthenticationInstant="2010-02-27T17:26:21.241Z" AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password">
       <Subject>
         <NameIdentifier Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
          NameQualifier="notRelevant">SYSADMIN</NameQualifier>
         <SubjectConfirmation>
    <ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:sender-vouches</ConfirmationMethod>    
         </SubjectConfirmation>
       </Subject>
   </AuthenticationStatement>
  </Assertion>
 </wsse:Security>


     <fnd:SOAHeader>
        <!--Optional:-->
        <fnd:Responsibility>UMX</fnd:Responsibility>
        <!--Optional:-->
        <fnd:RespApplication>FND</fnd:RespApplication>

     </fnd:SOAHeader>
   </soapenv:Header>

  <soapenv:Body wsu:Id="id-xxxxxxx" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <tes:InputParameters xmlns:tes="http://xmlns.oracle.com/apps/fnd/soaprovider/plsql/fnd_user_pkg/testusername/">
       <!--Optional:-->
       <tes:X_USER_NAME>username</tes:X_USER_NAME>
    </tes:InputParameters>
 </soapenv:Body>
</soapenv:Envelope>

Note: SAML Token-based security can be used to authenticate users in both Single Sign-On (SSO) and non-SSO enabled environments. The format of the NameIdentifier in the SAML assertion indicates if the user has been authenticated against LDAP (for SSO users) or the Oracle E-Business Suite FND_USER table (for non-SSO users).

The SAML assertion in the above SOAP message is for a non-SSO enabled environment. If the user name in the NameIdentifier tag is of the form of LDAP DN as shown below, then the user name is verified in the registered OID for SSO users.

<NameIdentifier Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" 
                                 NameQualifier="notRelevant">orclApplicationCommonName=PROD1,cn=EBusiness,cn=Products,cn=OracleContext,dc=us,dc=oracle,dc=com</NameIdentifier>

For more information about the SAML Token sender-vouches based security, see SAML Sender-Vouches Token Based Security, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

SOAP Header for Application Context

Application context contains many crucial elements that are used to pass values that may be required in Oracle E-Business Suite. For example, the context header information is required for an API transaction or a concurrent program in order for an Oracle E-Business Suite user that has sufficient privileges to run the program.

Application Context in SOAHeader Part of a SOAP Request

These context header elements defined in SOAHeader part of a SOAP request for PL/SQL and Concurrent Program services are:

• Responsibility

  It is the Oracle E-Business Suite application responsibility information. It accepts responsibility_key (such as SYSTEM_ADMINISTRATOR) as its value.

• RespApplication

  It is the responsibility application short name information. It accepts Application Short Name (such as FND) as its value.

• SecurityGroup

  It accepts Security Group Key (such as STANDARD) as its value.

• NLSLanguage (optional)

  It is an optional parameter to be passed in SOAHeader part of a SOAP request for PL/SQL and Concurrent Program services.

  If the NLS Language element is specified, SOAP requests can be consumed in the language passed. All corresponding SOAP responses and error messages can also be returned in the same language. If no language is identified, then the default language of the user will be used.

• Org_Id (optional for PL/SQL and Concurrent Program services)

  It is an optional parameter to be passed in SOAHeader part of a SOAP request for PL/SQL and Concurrent Program services. If a service invocation is dependent on any particular organization, then you must pass the Org_Id element of that SOAP request.

The following SOAP message shows the SOAHeader part printed in bold:

<soapenv:Header>
<http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
soapenv:mustUnderstand="1">
        <wsse:UsernameToken>
                <wsse:Username>sysadmin</wsse:Username>
                <wsse:Password 
                Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</wsse:Password>
        </wsse:UsernameToken>
</wsse:Security>

<ozf:SOAHeader>
        <ozf:Responsibility>OZF_USER</ozf:Responsibility>
        <ozf:RespApplication>OZF</ozf:RespApplication>
        <ozf:SecurityGroup>STANDARD</ozf:SecurityGroup>
        <ozf:NLSLanguage>AMERICAN</ozf:NLSLanguage>
        <ozf:Org_Id>204</ozf:Org_Id>
</ozf:SOAHeader>
</soapenv:Header>

Application Context in ServiceBean_Header Part of a SOAP Request

These context header elements defined in ServiceBean_Header part of a SOAP request for a Business Service Object service are:

• RESPONSIBILITY_NAME

  It is the Oracle E-Business Suite application responsibility information. It can accept both the name (Responsibility_Name, such as System Administrator) and the key (in the format of {key}responsibility_key, such as {key}SYSTEM_ADMINISTRATOR) as its values.

• RESPONSIBILITY_APPL_NAME

  It is the responsibility application short name information. It accepts Application Short Name (such as FND) as its value.

• SECURITY_GROUP_NAME

  It accepts Security Group Key (such as STANDARD) as its value.

• NLSLanguage (optional)

  It is an optional parameter to be passed in ServiceBean_Header part of a SOAP request for a Business Service Object service.

  If the NLS Language element is specified (such as AMERICAN), SOAP requests can be consumed in the language passed. All corresponding SOAP responses and error messages can also be returned in the same language. If no language is identified, then the default language of the user will be used.

• Org_Id (optional)

  It is an optional parameter to be passed in ServiceBean_Header part of a SOAP request for a Business Service Object service.

  If a service invocation is dependent on any particular organization, then you must pass the Org_Id element of that SOAP request.

The following SOAP request example includes the ServiceBean_Header part printed in bold for a business service object service:

<soapenv:Envelope xmlns:ser="http://xmlns.oracle.com/apps/fnd/ServiceBean"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://xmlns.oracle.com/apps/fnd/rep/ws">
  <soapenv:Header>
   <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
   <wsse:UsernameToken wsu:Id="UsernameToken-22948433" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
      <wsse:Username>sysadmin</wsse:Username>
      <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</wsse:Password>
    </wsse:UsernameToken>
   </wsse:Security>
  <ser:ServiceBean_Header>
    <ser:RESPONSIBILITY_NAME>System Administrator</ser:RESPONSIBILITY_NAME>
    <ser:RESPONSIBILITY_APPL_NAME>sysadmin</ser:RESPONSIBILITY_APPL_NAME>
    <ser:SECURITY_GROUP_NAME>standard</ser:SECURITY_GROUP_NAME>
    <ser:NLS_LANGUAGE>american</ser:NLS_LANGUAGE>
    <ser:ORG_ID>202</ser:ORG_ID>
  </ser:ServiceBean_Header>
 </soapenv:Header>
 <soapenv:Body>
   <ws:IntegrationRepositoryService_GetInterfaceByType>
     <interfaceType>XMLGATEWAY</interfaceType>
   </ws:IntegrationRepositoryService_GetInterfaceByType>
  </soapenv:Body>
</soapenv:Envelope>

SOA Header for XML Gateway Messages

In Oracle XML Gateway, each trading partner is configured with Oracle E-Business Suite users. Only these authorized users defined in the Trading Partner Setup form are allowed to perform XML transactions. External clients can pass such usernames in the <USERNAME> and <PASSWORD> elements defined within the <ECX:SOAHeader> element (or <XMLGateway_Header> element for generic XML Gateway services) in the SOAP body. These username parameters are validated by Oracle XML Gateway against the username defined in the trading partner setup before initiating a transaction.

Therefore, for XML Gateway interface type, the authorization check is performed at both the trading partner level, as well as on the username passed in the wsse:security header in the SOAP request. For information on trading partner setup and how to associate users with trading partners, see Oracle XML Gateway User's Guide.

The following code snippet shows the SOAHeader element within a SOAP request for an XML Gateway inbound message:

<soapenv: Envelope xmlns:ecx="http://xmlns.oracle.com/apps/ecx/soaprovider/xmlgateway/ecx__cbodi/" 
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:sys="http://xmlns.oracle.com/xdb/SYSTEM">
  <soapenv:Header>
         <wsse:Security soapenv:mustUnderstand="1" 
     xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
        <wsse:UsernameToken wsu:Id="UsernameToken-10586449" 
      xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
                        <wsse:Username>SYSADMIN</wsse:Username>
         <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</wsse:Password>
                </wsse:UsernameToken>
    </wsse:Security>
    <ecx:SOAHeader> 
     <sys:ECXMSG>
                <MESSAGE_TYPE></MESSAGE_TYPE>
                <MESSAGE_STANDARD></MESSAGE_STANDARD>
                <TRANSACTION_TYPE></TRANSACTION_TYPE>
                <TRANSACTION_SUBTYPE></TRANSACTION_SUBTYPE>
                <DOCUMENT_NUMBER></DOCUMENT_NUMBER>
                        <PARTYID></PARTYID>
                <PARTY_SITE_ID></PARTY_SITE_ID>
                        <PARTY_TYPE></PARTY_TYPE>
                        <PROTOCOL_TYPE></PROTOCOL_TYPE>
                        <PROTOCOL_ADDRESS></PROTOCOL_ADDRESS>
                        <USERNAME></USERNAME>
                        <PASSWORD></PASSWORD>
                        <ATTRIBUTE1></ATTRIBUTE1>
                        <ATTRIBUTE2></ATTRIBUTE2>
                        <ATTRIBUTE3></ATTRIBUTE3>
                        <ATTRIBUTE4></ATTRIBUTE4>
                        <ATTRIBUTE5></ATTRIBUTE5>
                </sys:ECXMSG>
   </ecx:SOAHeader>
 </soapenv:Header>

XML Gateway header parameters defined in the SOAHeader element (or XMLGateway_Header element for generic XML Gateway services) within a SOAP request are described in the following table:

XMLGateway Header Information in SOAHeader Element within a SOAP Request

Attribute	Description
MESSAGE_TYPE	Payload message format. This defaults to XML. Oracle XML Gateway currently supports only XML.
MESSAGE_STANDARD	Message format standard as displayed in the Define Transactions form and entered in the Define XML Standards form. This defaults to OAG. The message standard entered for an inbound XML document must be the same as the message standard in the trading partner setup.
TRANSACTION_TYPE	External Transaction Type for the business document from the Trading Partner table. The transaction type for an inbound XML document must be the same as the transaction type defined in the Trading Partner form.
TRANSACTION_SUBTYPE	External Transaction Subtype for the business document from the Trading Partner table. The transaction subtype for an inbound XML document must be the same as the transaction subtype defined in the Trading Partner form.
DOCUMENT_NUMBER	The document identifier used to identify the transaction, such as a purchase order or invoice number. This field is not used by the XML Gateway, but it may be passed on inbound messages.
PROTOCOL_TYPE	Transmission Protocol is defined in the Trading Partner table.
PROTOCOL_ADDRESS	Transmission address is defined in the Trading Partner table.
USERNAME	USERNAME is defined in the Trading Partner table.
PASSWORD	The password associated with the USERNAME is defined in the Trading Partner table.
PARTY_SITE_ID	The party site identifier for an inbound XML document must be the same as the Source Trading Partner location defined in the Trading Partner form.
ATTRIBUTE1	This parameter may be defined by the base application.
ATTRIBUTE2	This parameter may be defined by the base application.
ATTRIBUTE3	For outbound messages, this field has the value from the Destination Trading Partner Location Code in the Trading Partner table. For inbound messages, the presence of this value generates another XML message that is sent to the trading partner identified in the Destination Trading Partner Location Code in the Trading Partner table. This value must be recognized by the hub to forward the XML message to the final recipient of the XML Message. Note: For more information, see Destination Trading Partner Location Code in the Oracle XML Gateway User's Guide.
ATTRIBUTE4	This parameter may be defined by the base application.
ATTRIBUTE5	This parameter may be defined by the base application.

Note: The PARTYID and PARTY_TYPE parameters are not used.

The following code snippet shows the XMLGateway_Header element within a SOAP request for a generic XML Gateway service:

<soap:Envelope>
  <soap:Header>
...
   <ns1:XMLGateway_Header 
      xmlns:ns1="http://xmlns.oracle.com/apps/fnd/XMLGateway
      soapenv:mustUnderstand="0">
     <ns1:MESSAGE_TYPE>XML</ns1:MESSAGE_TYPE>
     <ns1:MESSAGE_STANDARD>OAG</ns1:MESSAGE_STANDARD>
     <ns1:TRANSACTION_TYPE>PO</ns1:TRANSACTION_TYPE>
     <ns1:TRANSACTION_SUBTYPE>PROCESS</ns1:TRANSACTION_SUBTYPE>
     <ns1:DOCUMENT_NUMBER>123</ns1:DOCUMENT_NUMBER>
     <ns1:PARTY_SITE_ID>4444</ns1:PARTY_SITE_ID>
   </ns1:XMLGateway_Header>
 </soap:Header>
...
</soap:Envelope>

The following table describes the XML Gateway header information in XMLGateway_Header part of a SOAP request:

XMLGateway_Header Part of a SOAP Request

Parameter Name	Description
MESSAGE_TYPE	Payload message format. This defaults to XML. Oracle XML Gateway currently supports only XML.
MESSAGE_STANDARD	Message format standard as displayed in the Define Transactions form and entered in the Define XML Standards form. This defaults to OAG. The message standard entered for an inbound XML document must be the same as the message standard in the trading partner setup.
TRANSACTION_TYPE	External Transaction Type for the business document from the Trading Partner table. The transaction type for an inbound XML document must be the same as the transaction type defined in the Trading Partner form.
TRANSACTION_SUBTYPE	External Transaction Subtype for the business document from the Trading Partner table. The transaction subtype for an inbound XML document must be the same as the transaction subtype defined in the Trading Partner form.
DOCUMENT_NUMBER	The document identifier used to identify the transaction, such as a purchase order or invoice number. This parameter is not used by the XML Gateway, but it may be passed on inbound messages.
PARTY_SITE_ID	The party site identifier for an inbound XML document must be the same as the Source Trading Partner location defined in the Trading Partner form.

Examples of SOAP Messages

To better understand SOAP request and response messages received through Oracle SOA Suite, the following sample SOAP messages are described in this section:

For information about synchronous SOAP messages, see:

• A Sample Synchronous SOAP Request

• A Sample Synchronous SOAP Response

• A Sample Fault Synchronous SOAP Response

For information about asynchronous SOAP messages, see:

• A Sample Asynchronous SOAP Request

• A Sample Asynchronous SOAP Response

• A Sample Fault Asynchronous SOAP Response

A Sample Synchronous SOAP Request

The following example shows a synchronous SOAP request for a PL/SQL service:

<soapenv:Envelope xmlns:ser="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" 
xmlns:ozf="http://xmlns.oracle.com/apps/ozf/soaprovider/plsql/ozf_sd_request_pub/" 
xmlns:cre="http://xmlns.oracle.com/apps/ozf/soaprovider/plsql/ozf_sd_request_pub/create_sd_request/">
  <soapenv:Header>
        <wsse:Security soapenv:mustUnderstand="1">
    <wsse:UsernameToken>
                <wsse:Username>trademgr</wsse:Username>
                <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</wsse:Password>
         </wsse:UsernameToken>
   </wsse:Security>
   <ozf:SOAHeader>
        <ozf:Responsibility>OZF_USER</ozf:Responsibility>
        <ozf:RespApplication>OZF</ozf:RespApplication>
        <ozf:SecurityGroupE>STANDARD</ozf:SecurityGroup>
        <ozf:NLSLanguage>AMERICAN</ozf:NLSLanguage>
        <ozf:Org_Id>204</ozf:Org_Id>
        </ozf:SOAHeader>
 </soapenv:Header>
 <soapenv:Body>
   <cre:InputParameters>
                <cre:P_API_VERSION_NUMBER>1.0</cre:P_API_VERSION_NUMBER>
                <cre:P_INIT_MSG_LIST>T</cre:P_INIT_MSG_LIST>
           <cre:P_COMMIT>F</cre:P_COMMIT>
                <cre:P_VALIDATION_LEVEL>100</cre:P_VALIDATION_LEVEL>
      <cre:P_SDR_HDR_REC>
        <cre:REQUEST_NUMBER>SDR-CREATE-A1</cre:REQUEST_NUMBER>
        <cre:REQUEST_START_DATE>2008-08-18T12:00:00</cre:REQUEST_START_DATE>
                  <cre:REQUEST_END_DATE>2008-10-18T12:00:00</cre:REQUEST_END_DATE>>
        <cre:USER_STATUS_ID>1701</cre:USER_STATUS_ID>
        <cre:REQUEST_OUTCOME>IN_PROGRESS</cre:REQUEST_OUTCOME>
        <cre:REQUEST_CURRENCY_CODE>USD</cre:REQUEST_CURRENCY_CODE>
        <cre:SUPPLIER_ID>601</cre:SUPPLIER_ID>
        <cre:SUPPLIER_SITE_ID>1415</cre:SUPPLIER_SITE_ID>
        <cre:REQUESTOR_ID>100001499</cre:REQUESTOR_ID>
                  <cre:ASSIGNEE_RESOURCE_ID>100001499</cre:ASSIGNEE_RESOURCE_ID>
                  <cre:ORG_ID>204</cre:ORG_ID>
                  <cre:ACCRUAL_TYPE>SUPPLIER</cre:ACCRUAL_TYPE>
                  <cre:REQUEST_DESCRIPTION>Create</cre:REQUEST_DESCRIPTION>

       <cre:SUPPLIER_CONTACT_EMAIL_ADDRESS>[e-mail]</cre:SUPPLIER_CONTACT_EMAIL_ADDRESS>
       <cre:SUPPLIER_CONTACT_PHONE_NUMBER>2255</cre:SUPPLIER_CONTACT_PHONE_NUMBER>
         <cre:REQUEST_TYPE_SETUP_ID>400</cre:REQUEST_TYPE_SETUP_ID>
       <cre:REQUEST_BASIS>Y</cre:REQUEST_BASIS>
       <cre:USER_ID>1002795</cre:USER_ID>
   </cre:P_SDR_HDR_REC>
   <cre:P_SDR_LINES_TBL>
     <cre:P_SDR_LINES_TBL_ITEM>
       <cre:PRODUCT_CONTEXT>PRODUCT</cre:PRODUCT_CONTEXT>
       ...
     </cre:P_SDR_LINES_TBL_ITEM>
   </cre:P_SDR_LINES_TBL>
   <cre:P_SDR_CUST_TBL>
     ...
   </cre:P_SDR_CUST_TBL>
  </cre:InputParameters>>
</soapenv:Body>
</soapenv:Envelope>

A Sample Synchronous SOAP Response

The following example shows a synchronous SOAP response for a PL/SQL service:

<env:Envelope xmlns:env=""http://schemas.xmlsoap.org/soap/envelope/">
 <env:Header/>
  <env:Body>
    <OutputParameters xmlns="http://xmlns.oracle.com/apps/ozf/soaprovider/plsql/ozf_sd_request_pub/create_sd_request/">
     <X_RETURN_STATUS>S</X_RETURN_STATUS>
     <X_MSG_COUNT>23</X_MSG_COUNT>
     <X_MSG_DATA xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
     <X_REQUEST_HEADER_ID>162</X_REQUEST_HEADER_ID>
   </OutputParameters>
  </env:Body>
</env:Envelope>

A Sample Fault Synchronous SOAP Response

The SOAP Fault element is used to carry error and status information within a SOAP message.

For example, the following fault synchronous response message indicates that the service is not deployed:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
 <env:Header/>
  <env:Body>
         <Fault xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
      <faultcode xmlns="">SOAP-ENV:Server</faultcode>
      <faultstring xmlns="">Service is not deployed.</faultstring>
   </env:Fault>
 </env:Body>
</env:Envelope>

A Sample Asynchronous SOAP Request

The following example shows an asynchronous SOAP request for CREATE_SD_REQUEST_ASYNCH operation contained in a PL/SQL service OZF_SD_REQUEST_PUB:

<soapenv:Envelope "http://xmlns.oracle.com/isg/ozf_sd_request_pub/CREATE_SD_REQUEST_ASYNCH" xmlns:cre1="http://xmlns.oracle.com/apps/ozf/soaprovider/plsql/ozf_sd_request_pub/create_sd_request/" xmlns:ozf="http://xmlns.oracle.com/apps/ozf/soaprovider/plsql/ozf_sd_request_pub/" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">  
 <soapenv:Header>
        <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
    <wsse:UsernameToken wsu:Id="UsernameToken-3" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
                <wsse:Username>trademgr</wsse:Username>
                <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</wsse:Password>
                <wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">JtcpwUGEcUyy09YgwaPzSA==</wsse:Nonce>
                <wsu:Created>2011-09-21T08:17:10.656Z</wsu:Created>
         </wsse:UsernameToken>
   </wsse:Security>
   <ozf:SOAHeader>
                        <!--Optional:--> 
                <ozf:Responsibility>OZF_USER</ozf:Responsibility>
                <!--Optional:--> 
                        <ozf:RespApplication>OZF</ozf:RespApplication>
                <!--Optional:--> 
                        <ozf:SecurityGroupE>STANDARD</ozf:SecurityGroup>
                <!--Optional:--> 
                        <ozf:NLSLanguage>AMERICAN</ozf:NLSLanguage>
                <!--Optional:--> 
                        <ozf:Org_Id>204</ozf:Org_Id>
        </ozf:SOAHeader>
 </soapenv:Header>
 <soapenv:Body>
   <cre:InputParameters>
                <cre:P_API_VERSION_NUMBER>1.0</cre:P_API_VERSION_NUMBER>
                <cre:P_INIT_MSG_LIST>T</cre:P_INIT_MSG_LIST>
           <cre:P_COMMIT>F</cre:P_COMMIT>
                <cre:P_VALIDATION_LEVEL>100</cre:P_VALIDATION_LEVEL>
      <cre:P_SDR_HDR_REC>
        <cre1:REQUEST_NUMBER>SDR-CREATE-BPEL001</cre1:REQUEST_NUMBER>
        <cre1:REQUEST_START_DATE>2011-08-18T12:00:00</cre1:REQUEST_START_DATE>
                  <cre1:REQUEST_END_DATE>2012-10-18T12:00:00</cre1:REQUEST_END_DATE>>
        <cre1:USER_STATUS_ID>1712</cre1:USER_STATUS_ID>
        <cre1:REQUEST_OUTCOME>IN_PROGRESS</cre1:REQUEST_OUTCOME>
        <cre1:REQUEST_CURRENCY_CODE>USD</cre1:REQUEST_CURRENCY_CODE>
        <cre1:SUPPLIER_ID>1718</cre1:SUPPLIER_ID>
        <cre1:SUPPLIER_SITE_ID>2854</cre1:SUPPLIER_SITE_ID>
        <cre1:REQUESTOR_ID>100001499</cre1:REQUESTOR_ID>
                  <cre1:ASSIGNEE_RESOURCE_ID>100001499</cre1:ASSIGNEE_RESOURCE_ID>
                  <cre1:ORG_ID>204</cre1:ORG_ID>
                  <cre1:ACCRUAL_TYPE>SUPPLIER</cre1:ACCRUAL_TYPE>
                  <cre1:REQUEST_DESCRIPTION>Create</cre1:REQUEST_DESCRIPTION>

       <cre1:SUPPLIER_CONTACT_EMAIL_ADDRESS>[e-mail]</cre1:SUPPLIER_CONTACT_EMAIL_ADDRESS>
       <cre1:SUPPLIER_CONTACT_PHONE_NUMBER>2255</cre1:SUPPLIER_CONTACT_PHONE_NUMBER>
         <cre1:REQUEST_TYPE_SETUP_ID>400</cre1:REQUEST_TYPE_SETUP_ID>
       <cre1:REQUEST_BASIS>Y</cre1:REQUEST_BASIS>
       <cre1:USER_ID>1002795</cre1:USER_ID>
   </cre:P_SDR_HDR_REC>
   <cre:P_SDR_LINES_TBL>
     <cre1:P_SDR_LINES_TBL_ITEM>
       <cre1:PRODUCT_CONTEXT>PRODUCT</cre:PRODUCT_CONTEXT>
       <cre1:INVENTORY_ITEM_ID>149</cre1:INVENTORY_ITEM_ID>
                 <cre1:ITEM_UOM>Ea</cre1:ITEM_UOM>
                 <cre1:REQUESTED_DISCOUNT_TYPE>%</cre1:REQUESTED_DISCOUNT_TYPE>
                 <cre1:REQUESTED_DISCOUNT_VALUE>15.5</cre1:REQUESTED_DISCOUNT_VALUE>
                 <!--<cre1:COST_BASIS>200</cre1:COST_BASIS>-->
                 <cre1:MAX_QTY>200<cre1:MAX_QTY>
                 <cre1:DESIGN_WIN>200</cre1:DESIGN_WIN>
                 <cre1:APPROVED_DISCOUNT_TYPE>%</cre1:APPROVED_DISCOUNT_TYPE>
                 <cre1:APPROVED_DISCOUNT_VALUE>15.5</cre1:APPROVED_DISCOUNT_VALUE>
                 <cre1:APPROVED_MAX_QTY>200</cre1:APPROVED_MAX_QTY>
                 <cre1:VENDOR_APPROVED_FLAG>Y</cre1:VENDOR_APPROVED_FLAG>
                 <cre1:PRODUCT_COST_CURRENCY>USD</cre1:PRODUCT_COST_CURRENCY>
                 <cre1:END_CUSTOMER_CURRENCY>USD</cre1:END_CUSTOMER_CURRENCY>
          </cre1:P_SDR_LINES_TBL_ITEM>
        </cre:P_SDR_LINES_TBL> 
   <cre:P_SDR_CUST_TBL>
          <cre1:P_SDR_CUST_TBL_ITEM>
                 <cre1:CUST_ACCOUNT_ID>1290</cre1:CUST_ACCOUNT_ID>
                 <cre1:PARTY_ID>1290</cre1:PARTY_ID>
                 <cre1:SITE_USE_ID>10479</cre1:SITE_USE_ID>
                 <cre1:CUST_USAGE_CODE>BILL_TO</cre1:CUST_USAGE_CODE>
                 <cre1:END_CUSTOMER_FLAG>N</cre1:END_CUSTOMER_FLAG>
         </cre1:P_SDR_CUST_TBL_ITEM>
         <cre1:P_SDR_CUST_TBL_ITEM>
                 <cre1:CUST_ACCOUNT_ID>1287</cre1:CUST_ACCOUNT_ID>
                 <cre1:PARTY_ID>1287</cre1:PARTY_ID>
                 <cre1:SITE_USE_ID>1418</cre1:SITE_USE_ID>
                 <cre1:CUST_USAGE_CODE>CUSTOMER</cre1:CUST_USAGE_CODE>
                 <cre1:END_CUSTOMER_FLAG>Y</cre1:END_CUSTOMER_FLAG>
         </cre1:P_SDR_CUST_TBL_ITEM>
   </cre:P_SDR_CUST_TBL>
  </cre:InputParameters>>
</soapenv:Body>
</soapenv:Envelope>

A Sample Asynchronous SOAP Response

The following example shows asynchronous response for CREATE_SD_REQUEST_ASYNCH operation contained in a PL/SQL service OZF_SD_REQUEST_PUB:

<?xml version="1.0" encoding="UTF-8" ?>
<outputParameters 
xmlns:client="http://xmlns.oracle.com/isg/ozf_sd_request_pub/CREATE_SD_REQUEST_ASYNCH" 
xmlns:wsa="http://www.w3.org/2005/08/addressing" 
xmlns="http://xmlns.oracle.com/isg/ozf_sd_request_pub/CREATE_SD_REQUEST_ASYNCH">
<OutputParameters 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns="http://xmlns.oracle.com/apps/ozf/soaprovider/plsql/ozf_sd_request_pub/create_sd_request/">
     <X_RETURN_STATUS>S</X_RETURN_STATUS>
     <X_MSG_COUNT>23</X_MSG_COUNT>
     <X_MSG_DATA xsi:nil="true"/>
     <X_REQUEST_HEADER_ID>31</X_REQUEST_HEADER_ID>
   </OutputParameters>
</outputParameters>

A Sample Fault Asynchronous SOAP Response

For example, the following sample shows the asynchronous response message for incorrect header from soapUI:

<?xml version="1.0" encoding="UTF-8" ?>
<outputParameters 
xmlns:client="http://xmlns.oracle.com/isg/ozf_sd_request_pub/CREATE_SD_REQUEST_ASYNCH" 
xmlns:wsa="http://www.w3.org/2005/08/addressing" 
xmlns="http://xmlns.oracle.com/isg/ozf_sd_request_pub/CREATE_SD_REQUEST_ASYNCH">
<OutputParameters 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns="http://xmlns.oracle.com/apps/ozf/soaprovider/plsql/ozf_sd_request_pub/create_sd_request/">
     <X_RETURN_STATUS>E</X_RETURN_STATUS>
     <X_MSG_COUNT>1</X_MSG_COUNT>
     <X_MSG_DATA>The Organization Id provided is invalid, please provide a valid Organization Id.</X_MSG_DATA>
     <X_REQUEST_HEADER_ID xsi:nil="true"/>
        </OutputParameters>
</outputParameters>

Understanding REST Messages

Based on REST architecture, the REST message uses HTTP header and supported methods to create, update, fetch, or delete Oracle E-Business Suite data through a service provider.

Supporting XML and JSON Message Formats

Unlike SOAP message completely based on XML format, REST messages can process both XML and non-XML formats such as JSON.

Note: Only Jackson JSON format is supported in this release. Other JSON formats, like Google GSON are not supported.

• XML, like HTML, organizes information by nesting angle-bracketed tag pairs (< or >).

• Compared to XML, JSON is light weight with faster parsing results. It is a simple text-based message format that is often used with REST services.

  It uses curly brackets ({ or }) to hierarchically structure information.

REST Message Structure

A REST request is a simple HTTP request which includes the following elements:

• Header

  This element defines the operating parameters of an HTTP transaction.

  REST service user credentials can be passed in HTTP header. For more information on REST service security, see REST Security Header.

• Body

  This element defines the main messages or resources.

  The 'RESTHeader' element can be included in HTTP body to set the application context values if they are required in invoking the REST service.

  For more information on setting application context, see REST Header for Application Context.

The following diagram depicts the structure of a REST message:

REST Security Header

User credentials must be authenticated based on either one of the following methods:

• HTTP Basic Authentication

  In this security model, username and password should be provided as input data in HTTP header as part of the REST request message. When the REST service receives the request, the user credentials (username and password) will be routed to LoginModule for authentication and authorization. The LoginModule in turn extracts the credentials from HTTP header, authenticates user against Oracle E-Business Suite user table, and establishes the identity for the authenticated user.

  If user credentials are validated and the application context required for the REST service to be invoked can be initialized, the REST service can be invoked.

  For more information about HTTP Basic Authentication security, see HTTP Basic Authentication, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

• Token Based Authentication

  Instead of passing an associated password for the user, a security token can be passed as user credentials in place of password.

  When a user tries to log on to a server with multiple requests, instead of authenticating the user each time with username and password, a unique access token (such as Oracle E-Business Suite session ID) may be sent along with username in HTTP header. Oracle E-Business Suite session ID can be obtained by making call to Login service. The LoginModule will interpret and extract the token from the HTTP header, and validate the subject or username with token in the subsequent requests for authentication.

  If user credentials are validated and the application context required for the REST service to be invoked can be initialized, the service can be invoked.

  For more information on setting application context, see REST Header for Application Context.

  For more information about token based security, see Token Based Authentication, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

REST Header for Application Context

Some Oracle E-Business Suite APIs require application context values to be passed before they can be invoked. These context values including Responsibility, RespApplication. SecurityGroup, NLSLanguage, and Org_Id may be included in the RESTHeader element as part of the HTTP body.

Optional Context Values in Token Based Security

Context header values are optional. If the context values are not passed while using token based security, the previously passed values will be used. If context values are passed, newly passed values will override the ones set previously for the given token.

The following REST message in XML format shows the RESTHeader element printed in bold:

<?xml version = '1.0' encoding = 'UTF-8'?>
<TESTUSERNAME_Input xmlns="http://xmlns.oracle.com/apps/fnd/rest/FndUserSvc/testusername/">
           <RESTHeader xmlns="http://xmlns.oracle.com/apps/fnd/rest/FndUserSvc/header">
                        <Responsibility>SYSTEM_ADMINISTRATOR</Responsibility>
        <RespApplication></RespApplication>
        <SecurityGroup></SecurityGroup>
        <NLSLanguage>AMERICAN</NLSLanguage>
        <Org_Id>/Org_Id>
    </RESTHeader>
    <InputParameters>
                        <X_USER_NAME>sysadmin</X_USER_NAME>
    </InputParameters>
</TESTUSERNAME_Input>

Optional Language Parameters

Similar to the <NLSLanguage> parameter to set the language preference, an ISO language parameter <Language> provides an alternative way to send the language preference in RFC 5646 format in the REST Header to set the session language, in case web service clients are unaware of the <NLSLanguage> parameter used in Oracle E-Business Suite.

Note: The <Language> parameter is used for REST services only.

For example, German language in standard RFC 5646 format is de-DE or de. Set the language to "German" through the <Language> parameter:

<Language>de-DE</Language> or <Language>de</Language>

Please note that the <NLSLanguage> and <Language> parameters are both optional. The <NLSLanguage> parameter takes precedence over the <Language> parameter if the <NLSLanguage> parameter value (such as <NLSLanguage>GERMAN</NLSLanguage>) is passed and valid.

• If the <NLSLanguage> value is not provided, then:

  • If the <Language> parameter is passed with a valid value, then the <Language> value will be used.

  • If the <Language> parameter is passed with an invalid value, then an error message would be returned.

    For example, if de-DE is passed as the <Language> value, but German is not an enabled or installed Oracle E-Business Suite language, then an error appears indicating that the language is not installed.

• If the <NLSLanguage> value is invalid or not installed, then an error message would be returned.

Only when both <NLSLanguage> and <Language> values are not provided, the Accept-Language header (such as Accept-Language = de-DE) from the HTTP Header will be considered. If the Accept-Language header is not passed or the passed value is invalid or not installed, then user's default language will be used.

Constructing Payload from WADL Description

Based on the resources information in a WADL description, you can compile an input payload before invoking a REST service.

Use the following steps to compile an input payload:

1. In the Integration Repository, search and locate the deployed REST service that you want to use.

2. Click the View WADL link in the REST Web Service tab. The following WADL description appears:

   <xml version="1.0" encoding="UTF-8" standalone="no" ?> 
   <application xmlns:tns="http://xmlns.oracle.com/apps/fnd/soaprovider/plsql/rest/fnd_user_pkg/" xmlns="http://wadl.dev.java.net/2009/02" xmlns:tns1="http://xmlns.oracle.com/apps/fnd/rest/FndUserSvc/testusername/" name="FND_USER_PKG"
   targetNamespace="http://xmlns.oracle.com/apps/fnd/soaprovider/plsql/rest/fnd_user_pkg/">
   <grammars>
                   <include xmlns="http://www.w3.org/2001/XMLSchema" href="https://<hostname>:<port>/webservices/rest/FndUserSvc/?XSD=TESTUSERNAME_SYNCH_TYPEDEF.xsd" /> 
   </grammars>
           <resources base="http://<hostname>:<port>/webservices/rest/FndUserSvc/">
                   <resource path="/testusername/">
                           <method id="GET" name="POST">
                                   <request>
                                           <representation mediaType="application/xml" type="tns1:InputParameters" /> 
                                           <representation mediaType="application/json" type="tns1:InputParameters" /> 
                                   </request>
                                   <response>
                                           <representation mediaType="application/xml" type="tns1:OutputParameters" /> 
                                           <representation mediaType="application/json" type="tns1:OutputParameters" /> 
                                   </response>
                           </method>
                   </resource>
           </resources>
   </application>
   

3. Locate the schema information (.XSD) for the Test User Name (TESTUSERNAME) service operation from the WADL description. The XSD for the operation TESTUSERNAME in the WADL would be:

   http://<hostname>:<port>/webservices/rest/FndUserSvc/?XSD=TESTUSERNAME_SYNCH_TYPEDEF.xsd

   Note: The schema information for the service operation can also be constructed by concatenating the values of the following elements from the WADL description:

   • <resources base="http://<hostname>:<port>/webservices/rest/FndUserSvc/">

   • <resource path="/testusername/">

4. Construct the payload of the service by using any XSD to XML conversion tools to get the payload information.

Once the payload is compiled, it can be used to invoke the TESTUSERNAME REST service operation. The request, response, and fault messages with both the XML and JSON formats are listed in the following table:

	REST Messages with the XML and JSON Formats
Input Payload (Request Message)	XML-based REST Message <?xml version="1.0" encoding="UTF-8" ?> <TESTUSERNAME_Input xmlns="http://xmlns.oracle.com/apps/fnd/rest/FndUserSvc/testusername/"> <RESTHeader xmlns="http://xmlns.oracle.com/apps/fnd/rest/FndUserSvc/header"> <Responsibility>SYSTEM_ADMINISTRATOR</Responsibility> <RespApplication></RespApplication> <SecurityGroupE></SecurityGroup> <NLSLanguage></NLSLanguage> <Org_Id></Org_Id> </RESTHeader> <InputParameters> <X_USER_NAME>sysadmin</X_USER_NAME> </InputParameters> </TESTUSERNAME_Input> JSON-based REST Message {"TESTUSERNAME_Input":{ "@xmlns":"http://xmlns.oracle.com/apps/fnd/rest/FndUserSvc/testusername/", "RESTHeader":{ "@xmlns":"http://xmlns.oracle.com/apps/fnd/rest/FndUserSvc/header", "Responsibility":"SYSTEM_ADMINISTRATOR", "RespApplication":"SYSADMIN", "SecurityGroup":"STANDARD", "NLSLanguage":"AMERICAN", "Org_Id":"202" }, "InputParameters":{ "X_USER_NAME":"operations" } }}
Response	XML-based REST Message <?xml version="1.0" encoding="UTF-8" standalone="no"?> <OutputParameters xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://xmlns.oracle.com/apps/fnd/rest/FndUserSvc/testusername/"> <X_USER_NAME>2</X_USER_NAME> </OutputParameters> JSON-based REST Message { "OutputParameters" : { "@xmlns:xsi" : "http://www.w3.org/2001/XMLSchema-instance", "@xmlns" : "http://xmlns.oracle.com/apps/fnd/rest/fndGlobalSvc/user_id/", "TESTUSERNAME" : "2" } }
Error Response	XML-based REST Message <ISGServiceFault> <Code>IRepAccessError</Code> <Message>This is a sample Fault Message. Message will vary depending on fault condition</Message> <Resolution>Check the server logs for details</Resolution> <ServiceDetails> <ServiceName>FndUserSvc</ServiceName> <OperationName>testusername</OperationName> <InstanceId>0</InstanceId> </ServiceDetails> </ISGServiceFault> JSON-based REST Message { "ISGServiceFault": { "Code": "IRepAccessError", "Message": "Sample Fault Message. Will vary depending on fault condition", "Resolution": "Check the server logs for details", "ServiceDetails": { "ServiceName": "FndUserSvc", "OperationName": "testusername", "InstanceId": "0" } } }

For more examples of REST messages used in OZF_SD_REQUEST_PUB service invocation, see Examples of REST Messages.

Examples of REST Messages

To better understand REST request and response messages received through Oracle E-Business Suite, the following sample REST messages are described in this section:

• A Sample XML-based REST Request

• A Sample JSON-based REST Request

• A Sample XML-based REST Response

• A Sample JSON-based REST Response

• Samples of XML-based Fault Responses

A Sample XML-based REST Request

This section includes sample REST requests to create a ship and debit request using a PL/SQL service, and requests to update, insert, and delete data in an open interface table.

• A synchronous request for a PL/SQL service

  The following example shows a synchronous XML-based REST request for a PL/SQL service (OZF_SD_REQUEST_PUB API):

  <?xml version="1.0" encoding="UTF-8" ?>
  <CREATE_SD_REQUEST_Input xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://xmlns.oracle.com/apps/ozf/rest/ozfsdrequestpubsvc/create_sd_request/xsd/OZF_SD_REQUEST_PUB_CREATEREQUEST.xsd"
        xmlns="http://xmlns.oracle.com/apps/ozf/rest/ozfsdrequestpubsvc/create_sd_request/">
          <RESTHeader xmlns="http://xmlns.oracle.com/apps/fnd/rest/ozfsdrequestpubsvc/header">
          <Responsibility>SYSTEM_ADMINISTRATOR</Responsibility>
          <RespApplication></RespApplication>
          <SecurityGroupE></SecurityGroup>
          <NLSLanguage></NLSLanguage>
          <Org_Id></Org_Id>
          </RESTHeader>
    <InputParameters>
                  <P_API_VERSION_NUMBER>1.0</P_API_VERSION_NUMBER>
                  <P_INIT_MSG_LIST>T</P_INIT_MSG_LIST>
             <P_COMMIT>F</P_COMMIT>
                  <P_VALIDATION_LEVEL>100</P_VALIDATION_LEVEL>
        <P_SDR_HDR_REC>
          <REQUEST_NUMBER>SDR-CREATE-BPEL1</REQUEST_NUMBER>
          <REQUEST_START_DATE>2008-08-18T12:00:00</REQUEST_START_DATE>
                    <REQUEST_END_DATE>2008-10-18T12:00:00</REQUEST_END_DATE>>
          <USER_STATUS_ID>1701</USER_STATUS_ID>
          <REQUEST_OUTCOME>IN_PROGRESS</REQUEST_OUTCOME>
          <REQUEST_CURRENCY_CODE>USD</EQUEST_CURRENCY_CODE>
                          <SUPPLIER_ID>601</SUPPLIER_ID>
                          <SUPPLIER_SITE_ID>1415</SUPPLIER_SITE_ID>
                  <REQUESTOR_ID>xxxxxxxxx</REQUESTOR_ID>
                                  <ASSIGNEE_RESOURCE_ID>xxxxxxxxx</ASSIGNEE_RESOURCE_ID>
                                  <ORG_ID>204</ORG_ID>
                                  <ACCRUAL_TYPE>SUPPLIER</ACCRUAL_TYPE>
                                  <REQUEST_DESCRIPTION>Create</REQUEST_DESCRIPTION>
                                  <SUPPLIER_CONTACT_EMAIL_ADDRESS>[e-mail]</SUPPLIER_CONTACT_EMAIL_ADDRESS>
                  <SUPPLIER_CONTACT_PHONE_NUMBER>2255</SUPPLIER_CONTACT_PHONE_NUMBER>
                          <REQUEST_TYPE_SETUP_ID>400</REQUEST_TYPE_SETUP_ID>
                  <REQUEST_BASIS>Y</REQUEST_BASIS>
                  <USER_ID>xxxxxxx</USER_ID>
     </P_SDR_HDR_REC>
     <P_SDR_LINES_TBL>
       <P_SDR_LINES_TBL_ITEM>
          <PRODUCT_CONTEXT>PRODUCT</PRODUCT_CONTEXT>
                                  <INVENTORY_ITEM_ID>2155</INVENTORY_ITEM_ID>
                                  <ITEM_UOM>Ea</ITEM_UOM>
                                  <REQUESTED_DISCOUNT_TYPE>%</REQUESTED_DISCOUNT_TYPE>
                                  <REQUESTED_DISCOUNT_VALUE>20</REQUESTED_DISCOUNT_VALUE>
                                  <COST_BASIS>200</COST_BASIS>
                                  <MAX_QTY>200</MAX_QTY>
                                  <DESIGN_WIN>200</DESIGN_WIN>
                                  <APPROVED_DISCOUNT_TYPE>%</APPROVED_DISCOUNT_TYPE>
                                  <APPROVED_DISCOUNT_VALUE>20</APPROVED_DISCOUNT_VALUE>
                                  <APPROVED_MAX_QTY>200</APPROVED_MAX_QTY>
                                  <VENDOR_APPROVED_FLAG>Y</VENDOR_APPROVED_FLAG>
                                  <PRODUCT_COST_CURRENCY>USD</PRODUCT_COST_CURRENCY>
                                  <END_CUSTOMER_CURRENCY>USD</END_CUSTOMER_CURRENCY>
       </P_SDR_LINES_TBL_ITEM>
     </P_SDR_LINES_TBL>
     <P_SDR_CUST_TBL>
                  <P_SDR_CUST_TBL_ITEM>
                          <CUST_ACCOUNT_ID>1290</CUST_ACCOUNT_ID>
                          <PARTY_ID>1290</PARTY_ID>
                          <SITE_USE_ID>10479</SITE_USE_ID>
                          <CUST_USAGE_CODE>BILL_TO</CUST_USAGE_CODE>
                          <END_CUSTOMER_FLAG>N</END_CUSTOMER_FLAG>
                  </P_SDR_CUST_TBL_ITEM>    
                  <P_SDR_CUST_TBL_ITEM>
                          <CUST_ACCOUNT_ID>1287</CUST_ACCOUNT_ID>
                          <PARTY_ID>1287</PARTY_ID>
                          <SITE_USE_ID>1418</SITE_USE_ID>
                          <CUST_USAGE_CODE>CUSTOMER</CUST_USAGE_CODE>
                          <END_CUSTOMER_FLAG>Y</END_CUSTOMER_FLAG>
                  </P_SDR_CUST_TBL_ITEM>
     </P_SDR_CUST_TBL>
    </InputParameters>
  </CREATE_SD_REQUEST_Input>
  

• A request for updating records in an Open Interface Table

  The following example shows a request message to update (PUT HTTP method) the open interface table RA_INTERFACE_LINES_ALL contained in the "AR Autoinvoice" Open Interface (RAXMTR) with Inbound direction:

  In this example, the HTTP request consists of more than one Update requests. The response message for each Update request should include status, message, and number of records updated. This request also includes Select; therefore, the response message returns values for the provided columns, INTERFACE_LINE_ID and BATCH_SOURCE_NAME in the Select statement.

       PUT http://host:port/webservices/rest/autoinvoice/RA_INTERFACE_LINES_ALL
          Content-Type: application/xml
          
          <?xml version="1.0" encoding="UTF-8" ?>
  <RA_INTERFACE_LINES_ALL_Input xmlns="http://xmlns.oracle.com/apps/ar/rest/autoinvoice/RA_INTERFACE_LINES_ALL">
                  <RESTHeader xmlns="http://xmlns.oracle.com/apps/fnd/rest/header">
                          <Responsibility>RECEIVABLES_VISION_OPERATIONS</Responsibility>
          <RespApplication>AR</RespApplication>
          <SecurityGroupE>STANDARD</SecurityGroup>
          <NLSLanguage>AMERICAN</NLSLanguage>
          <Org_Id>204</Org_Id>
          </RESTHeader>
                  <Select>INTERFACE_LINE_ID, BATCH_SOURCE_NAME</Select>
                  <InputParameters>
                          <Update>
                          <Filter>BATCH_SOURCE_NAME==ICS-01;ERROR_FLAG==T;QUANTITY=le=100</Filter>
                          <RA_INTERFACE_LINES_ALL_REC>
                                  <REQUEST_ID></REQUEST_ID>
                                  <ERROR_FLAG />
                                  <PROCESS_FLAG>0</PROCESS_FLAG>
                          </Update>
                          <Update>
                          <Filter>BATCH_SOURCE_NAME==ICS-01;ERROR_FLAG==T;QUANTITY=gt=100</Filter>
                          <RA_INTERFACE_LINES_ALL_REC>
                                  <PROCESS_FLAG>4</PROCESS_FLAG>
                          </RA_INTERFACE_LINES_ALL_REC>
                          </Update>
                  </InputParameters>
  </RA_INTERFACE_LINES_ALL_Input>
  

• A request for inserting records in an Open Interface Table

  This example explains the sample request to insert (POST HTTP method) data in the same open interface table RA_INTERFACE_LINES_ALL contained in the same "AR Autoinvoice" (RAXMTR) with Inbound direction.

  This request consists of two records to be inserted in the selected column names, INTERFACE_LINE_ID and BATCH_SOURCE_NAME, as shown below in the Select parameter. Similar to the update sample request mentioned previously, the response message returns values for the same selected columns.

       PUT http://host:port/webservices/rest/autoinvoice/RA_INTERFACE_LINES_ALL
          Content-Type: application/xml
          
          <?xml version="1.0" encoding="UTF-8" ?>
  <RA_INTERFACE_LINES_ALL_Input xmlns="http://xmlns.oracle.com/apps/ar/rest/autoinvoice/RA_INTERFACE_LINES_ALL">
                  <RESTHeader xmlns="http://xmlns.oracle.com/apps/fnd/rest/header">
                          <Responsibility>RECEIVABLES_VISION_OPERATIONS</Responsibility>
          <RespApplication>AR</RespApplication>
          <SecurityGroupE>STANDARD</SecurityGroup>
          <NLSLanguage>AMERICAN</NLSLanguage>
          <Org_Id>204</Org_Id>
          </RESTHeader>
                  <Select>INTERFACE_LINE_ID, BATCH_SOURCE_NAME</Select>
                  <InputParameters>
                          <RA_INTERFACE_LINES_ALL_REC>
                                  <REQUEST_ID></REQUEST_ID>
                                  <BATCH_SOURCE_NAME>ICS-1</BATCH_SOURCE_NAME>
                                  <RELATED_TRX_NUMBER>101</RELATED_TRX_NUMBER>
            <INTERFACE_LINE_ID>11</INTERFACE_LINE_ID>
             ...
                          </RA_INTERFACE_LINES_ALL_REC>
                          <RA_INTERFACE_LINES_ALL_REC>
                   <REQUEST_ID></REQUEST_ID>
                                  <BATCH_SOURCE_NAME>ICS-1</BATCH_SOURCE_NAME>
                                  <RELATED_TRX_NUMBER>102</RELATED_TRX_NUMBER>        
            <INTERFACE_LINE_ID>12</INTERFACE_LINE_ID>
            ...
        </RA_INTERFACE_LINES_ALL_REC>
          </InputParameters>
  </RA_INTERFACE_LINES_ALL_Input>
  

• A request for deleting records in an Open Interface Table

  The same open interface table RA_INTERFACE_LINES_ALL contained in "AR Autoinvoice" (RAXMTR) is used in this sample request for a Delete operation (DELETE HTTP method). This operation should accept filter criteria as query parameter.

  For example, the following request should delete records in RA_INTERFACE_LINES_ALL if the records satisfy the condition ORG_ID = 204, TRX_DATE < 27/04/2016, and PROCESS_FLAG = 4.

  Note that the query is based on Feed Item Query Language (FIQL) or Resource Query Language (RQL).

  http://host:port/webservices/rest/autoinvoice/RA_INTERFACE_LINES_ALL? filter=ORG_ID==204;TRX_DATE=lt=2016-04-27T00:00:00.000%2B00:00;PROCESS_FLAG==4

  The response message includes Status, Message and Number of records deleted (DeleteCount).

A Sample JSON-based REST Request

The following example shows a synchronous JSON-based POST request for the same PL/SQL service (OZF_SD_REQUEST_PUB API):

Note: Only Jackson JSON format is supported in this release. Other JSON formats, like Google GSON are not supported.

{
  "CREATE_SD_REQUEST_Input": {
    "@xmlns": "http://xmlns.oracle.com/apps/ozf/rest/ozfsdrequestpubsvc/create_sd_request/",
    "RESTHeader": {
      "@xmlns": "http://xmlns.oracle.com/apps/fnd/rest/ozfsdrequestpubsvc/header",
      "Responsibility": "SYSTEM_ADMINISTRATOR"
    },
    "InputParameters": {
      "P_API_VERSION_NUMBER": "1.0",
      "P_INIT_MSG_LIST": "T",
      "P_COMMIT": "F",
      "P_VALIDATION_LEVEL": "100",
      "P_SDR_HDR_REC": {
        "REQUEST_NUMBER": "SDR-CREATE-BPEL1",
        "REQUEST_START_DATE": "2008-08-18T12:00:00",
        "REQUEST_END_DATE": "2008-10-18T12:00:00",
        "USER_STATUS_ID": "1701",
        "REQUEST_OUTCOME": "IN_PROGRESS",
        "REQUEST_CURRENCY_CODE": "USD",
        "SUPPLIER_ID": "601",
        "SUPPLIER_SITE_ID": "1415",
        "REQUESTOR_ID": "xxxxxxxxx",
        "ASSIGNEE_RESOURCE_ID": "xxxxxxxxx",
        "ORG_ID": "204",
        "ACCRUAL_TYPE": "SUPPLIER",
        "REQUEST_DESCRIPTION": "Create",
        "SUPPLIER_CONTACT_EMAIL_ADDRESS": "[e-mail]",
        "SUPPLIER_CONTACT_PHONE_NUMBER": "2255",
        "REQUEST_TYPE_SETUP_ID": "400",
        "REQUEST_BASIS": "Y",
        "USER_ID": "xxxxxxx"
      },
      "P_SDR_LINES_TBL": {
        "P_SDR_LINES_TBL_ITEM": {
          "PRODUCT_CONTEXT": "PRODUCT",
          "INVENTORY_ITEM_ID": "2155",
          "ITEM_UOM": "Ea",
          "REQUESTED_DISCOUNT_TYPE": "%",
          "REQUESTED_DISCOUNT_VALUE": "20",
          "COST_BASIS": "200",
          "MAX_QTY": "200",
          "DESIGN_WIN": "200",
          "APPROVED_DISCOUNT_TYPE": "%",
          "APPROVED_DISCOUNT_VALUE": "20",
          "APPROVED_MAX_QTY": "200",
          "VENDOR_APPROVED_FLAG": "Y",
          "PRODUCT_COST_CURRENCY": "USD",
          "END_CUSTOMER_CURRENCY": "USD"
        }
      },
      "P_SDR_CUST_TBL": {
        "P_SDR_CUST_TBL_ITEM": [
          {
            "CUST_ACCOUNT_ID": "1290",
            "PARTY_ID": "1290",
            "SITE_USE_ID": "10479",
            "CUST_USAGE_CODE": "BILL_TO",
            "END_CUSTOMER_FLAG": "N"
          },
          {
            "CUST_ACCOUNT_ID": "1287",
            "PARTY_ID": "1287",
            "SITE_USE_ID": "1418",
            "CUST_USAGE_CODE": "CUSTOMER",
            "END_CUSTOMER_FLAG": "Y"
          }
        ]
      }
    }
  }
}

The following example shows a JSON-based GET request for a Java Bean Service called REST Service Locator:

 Request Headers
            Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxx
            Accept: application/json
            Content-Language: en-US

Note: For GET requests, JSON is the default output response format. Use Accept header application/xml to receive response in XML format. If Content-Type header is sent in GET HTTP request, it will be ignored.

A Sample XML-based REST Response

The following example shows an XML-based REST response for the OZF_SD_REQUEST_PUB API service:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<OutputParameters 
xmlns:xsl=""http://www.w3.org/2001/XMLSchema-instance" xmlns="http://xmlns.oracle.com/apps/ozf/rest/ozfsdrequestpubsvc/create_sd_request/">
     <X_RETURN_STATUS>E</X_RETURN_STATUS>
     <X_MSG_COUNT>1</X_MSG_COUNT>>
          <X_MSG_DATA>The Organization Id provided is invalid, please provide a valid Organization Id.</X_MSG_DATA>
     <X_REQUEST_HEADER_IDxsi:nil="true"/>
</OutputParameters>

Additionally, the following example shows a response message for the HTTP request mentioned earlier for the open interface table "AR Autoinvoice". In response to the Update request for the INTERFACE_LINE_ID and BATCH_SOURCE_NAME columns in the RA_INTERFACE_LINES_ALL table, the response message includes status, message, and number of records updated (<UpdateCount>) for each Update request identified by Index in the order of occurrence in the request. When the update is successful, this response message also returns values for INTERFACE_LINE_ID and BATCH_SOURCE_NAME mentioned in the Select statement in the request.

<?xml version = '1.0' encoding = 'UTF-8'?>
<OutputParameters xmlns="http://xmlns.oracle.com/apps/ar/rest/autoinvoice/RA_INTERFACE_LINES_ALL">
 <Summary>
        <SuccessCount>5</SuccessCount>
        <ErrorCount>1</ErrorCount>
 </Summary>
 <Result>
   <Index>1</Index>
   <Status>SUCCESS</Status>
        <Message></Message>
        <UpdateCount>2</UpdateCount>
        <RA_INTERFACE_LINES_ALL_REC>
                <INTERFACE_LINE_ID>11</INTERFACE_LINE_ID>
                <BATCH_SOURCE_NAME>ICS-1</BATCH_SOURCE_NAME>
   </RA_INTERFACE_LINES_ALL_REC>
   <RA_INTERFACE_LINES_ALL_REC>
      <INTERFACE_LINE_ID>12</INTERFACE_LINE_ID>
                <BATCH_SOURCE_NAME>ICS-1</BATCH_SOURCE_NAME>
   </RA_INTERFACE_LINES_ALL_REC>
 </Output>
 <Output>
   <Index>2</Index>
   <Status>ERROR</Status>
        <Message>Invalid date .. </Message>
        <UpdateCount>0</UpdateCount>
   <RA_INTERFACE_LINES_ALL_REC>
 </Output>
 </Result>
</OutputParameters>

Similarly, for the request of inserting two records in the same open interface table RA_INTERFACE_LINES_ALL as described earlier, the response message returns values for the same selected columns INTERFACE_LINE_ID and BATCH_SOURCE_NAME as shown in the following:

<?xml version = '1.0' encoding = 'UTF-8'?>
<OutputParameters xmlns="http://xmlns.oracle.com/apps/ar/rest/autoinvoice/RA_INTERFACE_LINES_ALL">
 <Summary>
        <SuccessCount>15</SuccessCount>
        <ErrorCount>2</ErrorCount>
 </Summary>
 <Result>
  <Output>
    <Index>1</Index>
    <Status>SUCCESS</Status>
          <Message></Message>

         <RA_INTERFACE_LINES_ALL_REC>
                <INTERFACE_LINE_ID>11</INTERFACE_LINE_ID>
                <BATCH_SOURCE_NAME>ICS-1</BATCH_SOURCE_NAME>
    </RA_INTERFACE_LINES_ALL_REC>
   </Output>
   <Output>
    <Index>2</Index>
    <Status>ERROR</Status>
    <Message>Invalid date .. </Message>

   <RA_INTERFACE_LINES_ALL_REC>
      <INTERFACE_LINE_ID>12</INTERFACE_LINE_ID>
                <BATCH_SOURCE_NAME>ICS-1</BATCH_SOURCE_NAME>
   </RA_INTERFACE_LINES_ALL_REC>
 </Output>
 </Result>
</OutputParameters>

In response to the Delete request explained earlier, the response message includes Status, Message and Number of records being deleted (DeleteCount):

<?xml version = '1.0' encoding = 'UTF-8'?>
<OutputParameters xmlns="http://xmlns.oracle.com/apps/ar/rest/autoinvoice/RA_INTERFACE_LINES_ALL">
 <Result>
    <Status>SUCCESS</Status>
         <Message></Message>
    <DeleteCount>2</DeleteCount>
 </Result>
</OutputParameters>

A Sample JSON-based REST Response

The following example shows a JSON-based REST response for the OZF_SD_REQUEST_PUB API service with the POST method:

{
  "OutputParameters" : {
    "@xmlns:xsi" : "http://www.w3.org/2001/XMLSchema-instance",
    "@xmlns" : "http://xmlns.oracle.com/apps/ozf/rest/ozfsdrequestpubsvc/create_sd_request/",
    "X_RETURN_STATUS" : "E",
    "X_MSG_COUNT" : "1",
    "X_MSG_DATA" : "The Organization Id provided is invalid, please provide a valid Organization Id.",
    "X_REQUEST_HEADER_ID" : {
      "@xsi:nil" : "true"
    }
  }

The following example shows a JSON-based REST response for the REST Service Locator (getRestInterface service operation) service with the GET method:

{
 "OutputParameters" : {
  "EbsRestServiceBean" :  {
   "alternateAlias" : "plsql/PLSQL:FND_PROFILE",
   "serviceAlias" : "NotAnything",
   "serviceName" : "PLSQL:FND_PROFILE",
   "wadlUrl" : "http://<hostname>:<port>/webservices/rest/profile?WADL"
  } ,
  "ControlBean" :  {
   "fields" : null,
   "filter" : null,
   "limit" : null,
   "offset" : null
  }
 }
}

Note: The message payload used here is an example. You should use the actual definition of the service in XSD and WADL.

Samples of XML-based Fault Responses

The following sample shows the XML-based REST response message when XML is not well formed:

<ISGServiceFault>
        <Code>RequestParsingError</Code>
        <Message>SAXException in XmlRequestObject, while parsing XML request The request could not be parsed correctly</Message>
        <Resolution>This may be due to malformed construction of the payload or incorrectContent-Type header. Please check the wellformed-ness of payload, matching Content-Type header of the http request and retry.</Resolution>
        <ServiceDetails>
                <ServiceName>ozfsdrequestpubsvc</ServiceName>
                <OperationName>create_sd_request</OperationName>
                <InstanceId>0</InstanceId>
        </ServiceDetails> 
</ISGServiceFault>

The following sample shows the XML-based REST response message when RespApplication (Responsibility Application short name) is invalid:

<ISGServiceFault>
        <Code>InvalidResponsibilityApplicationShortCode</Code>
        <Message>Responsibility short code is invalid System error while processing the request</Message>
        <Resolution>Check the server logs for details</Resolution>
        <ServiceDetails>
                <ServiceName>ozfsdrequestpubsvc</ServiceName>
                <OperationName>get_text_number</OperationName>
                <InstanceId>0</InstanceId>
        </ServiceDetails> 
</ISGServiceFault>