Creating and Using Custom Integration Interfaces

Overview

Custom integration interfaces and services can be viewed and displayed through the Integration Repository browser window along with Oracle seeded interfaces in Oracle E-Business Suite.

Integration developers create and annotate custom integration interfaces based on the Integration Repository annotation standards for the supported interface types including XML Gateway Map, Business Event, PL/SQL, Concurrent Program, Business Service Object, Java Bean Services, Application Module Services, Java APIs, and Composite Service - BPEL type.

Note: Please note that custom interface types of EDI, Open Interface Tables, Open Interface Views, and Java APIs for Forms interfaces are not supported in this release.

Oracle Integration Repository currently does not support the creation of custom Product Family and custom Business Entity.

Once these custom interfaces are annotated, integration administrators use a standalone design-time tool to validate these annotated source files against the annotation standards. After validation, a loader file is generated and then uploaded to the Integration Repository through backend processing. These custom interfaces are displayed based on the interface types to which they belong and displayed together with Oracle seeded ones from the Integration Repository user interface.

For custom integration interfaces of interface types

If a custom interface created for a supported interface type has been uploaded to Oracle Integration Repository, to use this custom interface, an integration administrator should first create necessary security grants, and then generate and deploy the web service to the application server if the custom interface type can be service enabled. Thus, the deployed service can be exposed to customers through a service provider and invoked through any of the web service clients or orchestration tools.

For custom composite services - BPEL type

If a custom interface is needed for a composite service - BPEL type, an integration developer will first create a composite service by orchestrating discrete native services into a meaningful process flow using BPEL process component in Oracle JDeveloper 10g. Based on the annotation standards specifically for composite service, the integration developer will then annotate the composite service - BPEL type. Similar to custom interfaces of other interface types, appropriate validation on the BPEL project JAR file is required before it can be uploaded to the Integration Repository.

To have a better understanding of how to create custom interfaces as well as how to use custom interfaces as web services, the following topics are discussed in this chapter:

Creating Custom Integration Interfaces

The following topics are discussed in this section:

Creating Custom Integration Interfaces of Native Interface Types

Custom interface definitions can be created and annotated for almost all interface types. With appropriate validation, if no error occurred, the validated custom definition sources compiled in a generated iLDT file can be uploaded to Oracle Integration Repository through backend processing.

Note: Custom interface types of EDI, Open Interface Tables, and Open Interface Views are not supported in this release.

Oracle Integration Repository currently does not support the creation of custom Product Family and custom Business Entity.

Enabling Custom Integration Interfaces

The custom interface design and service enablement process flow can be illustrated in the following diagram:

Custom Integration Interfaces Development Process Flow

the picture is described in the document text

  1. Users who have the Integration Developer role annotate custom integration interface definition based on the Integration Repository annotation standards for the supported interface types.

    See: Creating and Annotating Custom Integration Interfaces.

    Note: For custom PL/SQL APIs (simple data types only) that are created with a custom schema, you can publish such custom APIs in Oracle Integration Repository. Additionally, perform the following tasks for such APIs with a custom schema:

    1. Grant access to APPS schema.

      1. Connect to a custom schema as EBS_SYSTEM if your instance is on AD and TXK Delta 13 release update packs (RUPs) or later, or as SYSTEM if your instance is on an earlier AD and TXK RUP:

        sqlplus '/ as EBS_SYSTEM'

        Note: The R12.AD.C.Delta.13 and R12.TXK.C.Delta.13 RUPs introduce the EBS_SYSTEM schema. If you are running Release Update Packs for AD and TXK Delta 13 or later, database privileges are granted to the Oracle E-Business Suite administration account, EBS_SYSTEM. Only the minimally required database privileges required to run Oracle E-Business Suite are granted to APPS by EBS_SYSTEM. For more information, refer to:

        • Document 2755875.1, Oracle E-Business Suite Release 12.2 System Schema Migration

        • Document 2758993.1, Managing Database Privileges in Oracle E-Business Suite Release 12.2 (Running adgrants.sql)

      2. Use the following command to grant access:

        GRANT EXECUTE on <custom_schema>.<custom_package> TO APPS;

    2. Create a synonym for the custom stored procedure.

      1. Connect to APPS schema using the following command:

        sqlplus <APPS Username>
Enter password: password

      2. Use the following command to create a synonym:

        CREATE SYNONYM <custom_package> FOR <custom_schema>.<custom_package>;

  2. Users who have the Integration Administrator role validate the annotated custom interface definitions against the annotation standards. This validation is performed by running the Integration Repository Parser (IREP Parser), a design-time tool, to read the annotated files and then generate an Integration Repository loader file (iLDT ) if no error occurred.

    For information on how to generate and upload the iLDT files, see Generating and Uploading iLDT Files.

  3. Users who have the Integration Administrator role upload the generated iLDT file to Oracle Integration Repository.

    See: Uploading ILDT Files to Integration Repository, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

  4. (Optional) Users who have the Integration Administrator role can delete the custom interfaces if needed.

    Before starting to use a custom integration interface from the Integration Repository, users who have the Integration Administrator role can delete the custom interface if it is not yet generated or deployed as a web service. The administrators can first locate the custom interface from the Integration Repository user interface, and then click Delete Interface in the Overview tab of the custom interface details page.

    If a custom interface has been generated or deployed, it must be reset or undeployed to its initial state before it can be deleted. See: Deleting Custom Integration Interfaces, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

  5. All users can view the uploaded custom interfaces from the Integration Repository user interface.

  6. (Optional) Users who have the Integration Administrator role then create necessary security grants for the custom integration interfaces if needed.

    This is achieved by first locating the custom interface from the Integration Repository, and then selecting methods contained in the selected custom interface before clicking Create Grant. The Create Grants page is displayed where the administrators can grant the selected method access permissions to a user, user group, or all users. See: Creating Security Grants, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

  7. (Optional) Users who have the Integration Administrator role can generate web services if the custom interfaces can be service enabled.

    This is achieved by first locating the custom interface, and then specifying the interaction pattern either at the interface level or the method level before clicking Generate in the selected custom interface details page. See: Generating Custom SOAP Web Services, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

  8. (Optional) Users who have the Integration Administrator role deploy the web services from Oracle Integration Repository to the application server.

    To deploy the generated SOAP web services, the administrators must first select one authentication type (Username Token or SAML Token) for each selected web service and then click Deploy in the selected interface details page. This deploys the generated service with 'Active' state to Oracle SOA Suite where Oracle E-Business Suite services can be exposed as standard web services for service invocation at runtime. See: Deploying and Undeploying Custom SOAP Web Services, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

    If the custom interfaces can be exposed as REST services, the administrators must enter a unique service alias for each selected custom interface and specify the desired service operations before deploying the service. Additionally, the administrators need to specify HTTP methods for the service operations contained in the selected interface if it is an interface type of PL/SQL, Java Bean Services, Application Module Services, or Business Service Object.

    Note: Although open interface tables and open interface views can be exposed as REST services, custom open interface tables and custom open interface views are not supported in this release.

    See: Deploying Custom REST Web Services, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Custom Integration Interface Annotation Example

Once a custom integration definition of a specific interface type is created, an integration developer must properly annotate the custom file based on the Integration Repository annotation standards so that the custom interface can be displayed with appropriate description from the browser interface.

For example, the integration developer can create a Supplier Ship and Debit Request custom interface using PL/SQL API. This custom PL/SQL API package specification file (zz_sdrequest_s.pls) can be as follows:

set verify off
whenever sqlerror exit failure rollback;
WHENEVER OSERROR EXIT FAILURE ROLLBACK;

create or replace package ZZ_SDREQUEST as
/* $Header: zz_sdrequest_s.pls $ */

-- Custom procedure to create single supplier ship and debit request

procedure ZZ_CREATE_SDREQUEST (   
CP_API_VERSION_NUMBER  IN    NUMBER,   
CP_INIT_MSG_LIST  IN    VARCHAR2 := FND_API.G_FALSE,   
CP_COMMIT  IN    VARCHAR2 := FND_API.G_FALSE,   
CP_VALIDATION_LEVEL  IN    NUMBER := FND_API.G_VALID_LEVEL_FULL,   
CX_RETURN_STATUS  OUT    VARCHAR2,   
CX_MSG_COUNT  OUT    NUMBER,   
CX_MSG_DATA  OUT    VARCHAR2,   
CP_SDR_HDR_REC  IN    OZF_SD_REQUEST_PUB.SDR_HDR_REC_TYPE,   
CP_SDR_LINES_REC  IN    OZF_SD_REQUEST_PUB.SDR_lines_rec_type,   
CP_SDR_CUST_REC  IN    OZF_SD_REQUEST_PUB.SDR_cust_rec_type,   
CP_SDR_BILLTO_REC  IN    OZF_SD_REQUEST_PUB.SDR_cust_rec_type,   
CX_REQUEST_HEADER_ID  OUT    NUMBER 
)
; 
end ZZ_SDREQUEST;       

/
commit;
exit;

Based on the PL/SQL API annotation standards, the integration developer must annotate the Supplier Ship and Debit Request custom package specification file by adding the annotation information specifically in the following places:

Please note that you only need to annotate the custom package specification file, but not the package body file. For information on how to annotate custom interfaces for the interface types supported by Oracle Integration Repository, see Integration Repository Annotation Standards and Oracle Application Framework Developer's Guide, available from My Oracle Support Knowledge Document 1315485.1.

set verify off
whenever sqlerror exit failure rollback;
WHENEVER OSERROR EXIT FAILURE ROLLBACK;

create or replace package ZZ_SDREQUEST as
/* $Header: zz_sdrequest_s.pls $ */
/*#
* This custom PL/SQL package can be used to create supplier ship and debit request for single product.  
* @rep:scope public
* @rep:product OZF
* @rep:displayname Single ship and debit request 
* @rep:category BUSINESS_ENTITY OZF_SSD_REQUEST
*/

-- Custom procedure to create single supplier ship and debit request

procedure ZZ_CREATE_SDREQUEST (   
CP_API_VERSION_NUMBER  IN    NUMBER,   
CP_INIT_MSG_LIST  IN    VARCHAR2 := FND_API.G_FALSE,   
CP_COMMIT  IN    VARCHAR2 := FND_API.G_FALSE,   
CP_VALIDATION_LEVEL  IN    NUMBER := FND_API.G_VALID_LEVEL_FULL,   
CX_RETURN_STATUS  OUT    VARCHAR2,   
CX_MSG_COUNT  OUT    NUMBER,   
CX_MSG_DATA  OUT    VARCHAR2,   
CP_SDR_HDR_REC  IN    OZF_SD_REQUEST_PUB.SDR_HDR_REC_TYPE,   
CP_SDR_LINES_REC  IN    OZF_SD_REQUEST_PUB.SDR_lines_rec_type,   
CP_SDR_CUST_REC  IN    OZF_SD_REQUEST_PUB.SDR_cust_rec_type,   
CP_SDR_BILLTO_REC  IN    OZF_SD_REQUEST_PUB.SDR_cust_rec_type,   
CX_REQUEST_HEADER_ID  OUT    NUMBER 
)
/*# 
* Use this procedure to create single supplier ship and debit request 
* @param CP_API_VERSION_NUMBER Version of the custom API 
* @param CP_INIT_MSG_LIST Flag to initialize the message stack 
* @param CP_COMMIT Indicates Flag to commit within the program 
* @param CP_VALIDATION_LEVEL Indicates the level of the validation 
* @param CX_RETURN_STATUS Indicates the status of the program 
* @param CX_MSG_COUNT Provides the number of the messages returned by the program 
* @param CX_MSG_DATA Returns messages by the program 
* @param CP_SDR_HDR_REC Contains details of the new Ship Debit Request to be created 
* @param CP_SDR_LINES_REC Contains the product line information for the new Ship Debit Request 
* @param CP_SDR_CUST_REC Contains the Customer information for the new Ship Debit Request 
* @param CP_SDR_BILLTO_REC Contains the Bill-to information for the new Ship Debit Request 
* @param CX_REQUEST_HEADER_ID Returns the id of the new Ship Debit Request created 
* @rep:displayname Create ship and debit request 
* @rep:category BUSINESS_ENTITY OZF_SSD_REQUEST 
* @rep:scope public 
* @rep:lifecycle active 
*/
; 
end ZZ_SDREQUEST;       

/
commit;
exit;

Generating and Uploading iLDT Files

Once annotated custom integration interface definitions are created, these annotated source files need to be validated against the annotation standards before they can be uploaded to Oracle Integration Repository. This validation is performed by running the Integration Repository Parser (IREP Parser), a design-time tool, to read the annotated files and then generate an Integration Repository loader file (iLDT ) if no error occurred.

Note: Please note that Integration Repository Parser does not support the integration interfaces registered under custom applications.

It is currently tested and certified for Linux, Unix, Oracle Solaris on SPARC, HP-UX Itanium, and IBM AIX on Power Systems.

Microsoft Windows platform is currently not supported in this release.

Once an iLDT file is generated, an integration administrator can upload the generated file to Oracle Integration Repository where the custom interfaces can be exposed to all users.

For information on how to set up and use the Integration Repository Parser to generate the iLDT file as well as how to upload the generated file to the repository, see:

Viewing Custom Interfaces and Performing Administrative Tasks

Searching and Viewing Custom Interfaces

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

To search for custom integration interfaces, you can use either one of the following ways:

After you perform the search, all matched custom integration interfaces will be displayed. For more information on how to search and view custom integration interfaces, see Searching Custom Integration Interfaces, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide and Viewing Custom Integration Interfaces, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Performing Administrative Tasks

Once custom integration interfaces have been successfully uploaded and displayed from the Integration Repository user interface, an integration administrator can perform the same administrative tasks on these custom interfaces as they are for the native integration interfaces. These administrative tasks including creating security grants for newly created custom interfaces if needed, generating web services, deploying web services, and managing services throughout the entire deployment life cycle. See Administering Custom Integration Interfaces and Services, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

For information on how to use custom integration interfaces as web services, see Using Custom Integration Interfaces as Web Services.

Creating Custom Composite Services - BPEL

Integration developers can create new composite services by orchestrating discrete web services into meaningful business processes using BPEL language. With appropriate annotation specifically for the composite service - BPEL type and validation against the annotation standards, if no error occurred, an iLDT file can be generated for the validated composite service BPEL project. The generated iLDT file can then be uploaded to the Integration Repository through backend processing.

Creating Custom Composite Services

The following diagram illustrates the custom integration interface design flow for composite service - BPEL type:

the picture is described in the document text

  1. An integration developer orchestrates a composite service using BPEL process component in Oracle JDeveloper 10g.

  2. An integration developer annotates the composite service based on the Integration Repository annotation standards specifically for the composite service - BPEL type.

    See: Creating and Annotating Custom Composite Services - BPEL.

  3. An integration developer creates a JAR file of the composite service - BPEL project.

  4. An integration administrator unzips the JAR file first and then validates the annotated custom interface definitions against the annotation standards specifically for composite services - BPEL. This validation is performed by running the Integration Repository Parser to read the annotated files and then generate an Integration Repository loader file (iLDT) if no error occurred.

  5. An integration administrator uploads the generated iLDT file to Oracle Integration Repository through backend processing.

    See: Generating and Uploading iLDT Files.

    After the upload, verify the custom composite service - BPEL from the Integration Repository user interface.

Once custom integration interface definitions have been successfully uploaded and displayed from the Integration Repository browser, the integration administrator and the integration developer can download the composite services - BPEL for modification if needed. For information on how to download composite services - BPEL, see Viewing and Downloading Custom Composite Services - BPEL.

A Custom Composite Service Annotation Example

The key essence of creating custom integration interfaces relies on properly explanation of the new interface feature or definition. When a custom composite service - BPEL definition is created, an integration developer must properly annotate the custom source file based on the Integration Repository annotation standards so that the source file can be displayed with appropriate description from the browser interface.

For example, a Create Invoice composite - BPEL project is created. To annotate the composite service, open the *.bpel file in text editor and place the annotation within the comments section in the beginning of the file as highlighted here:

//////////////////////////////////////////////////////////////
Oracle JDeveloper BPEL Designer 
  
  Created: Tue Oct 30 17:10:13 IST 2007
  Author:  <username>
  Purpose: Synchronous BPEL Process
 /*#
  * This is a bpel file for creating invoice.
  * @rep:scope public
  * @rep:displayname Create Invoice
  * @rep:lifecycle active
  * @rep:product PO 
  * @rep:compatibility S
  * @rep:interface oracle.apps.po.CreateInvoice
  * @rep:category BUSINESS_ENTITY INVOICE 
  */
  
//////////////////////////////////////////////////////////////

-->
<process name="CreateInvoice">
                        targetNamespace="http://xmlns.oracle.com/CreateInvoice"
                xmlns="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
                        xmlns:bpws="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
         xmlns:xp20="http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20"
         xmlns:ns4="http://xmlns.oracle.com/pcbpel/adapter/file/ReadPayload/"
         xmlns:ldap="http://schemas.oracle.com/xpath/extension/ldap"
         xmlns:xsd="http://www.w3.org/2001/XMLSchema"
         xmlns:ns5="http://xmlns.oracle.com/bpel/workflow/xpath"
         xmlns:client="http://xmlns.oracle.com/CreateInvoice"
         xmlns:ns6="http://xmlns.oracle.com/bpel/services/IdentityService/xpath"
         xmlns:ora="http://schemas.oracle.com/xpath/extension"
         xmlns:ns1="http://xmlns.oracle.com/soaprovider/plsql/AR_INVOICE_API_PUB_2108/CREATE_SINGLE_INVOICE_1037895/"
         xmlns:ns3="http://xmlns.oracle.com/soaprovider/plsql/AR_INVOICE_API_PUB_2108/APPS/BPEL_CREATE_SINGLE_INVOICE_1037895/AR_INVOICE_API_PUB-24CREATE_INV/"
         xmlns:ns2="http://xmlns.oracle.com/pcbpel/adapter/appscontext/"
         xmlns:bpelx="http://schemas.oracle.com/bpel/extension"
                        xmlns:orcl="http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc">

  <!--
/////////////////////////////////////////////////////////////////////
PARTNERLINKS                                                      
      List of services participating in this BPEL process  
/////////////////////////////////////////////////////////////////////
-->
<partnerLinks>
        <!--
                The 'client' role represents the requester of this service. It is 
      used for callback. The location and correlation information associated
      with the client role are automatically set using WS-Addressing.
    -->
    <partnerLink name="client" partnerLinkType="client:CreateInvoice"
                 myRole="CreateInvoiceProvider"/>
    <partnerLink name="CREATE_SINGLE_INVOICE_1037895"
                 partnerRole="CREATE_SINGLE_INVOICE_1037895_ptt_Role"
                 partnerLinkType="ns1:CREATE_SINGLE_INVOICE_1037895_ptt_PL"/>
    <parnterLink name="ReadPayload" partnerRole="SynchRead_role"
                 partnerLinkType="ns4:SynchRead_plt"/>
</partnerLinks>
<!--
/////////////////////////////////////////////////////////////////////
VARIABLES                                                        
      List of messages and XML documents used within this BPEL process  
/////////////////////////////////////////////////////////////////////
-->
<variables>
<!--Reference to the message passed as input during initiation-->
         <variable name="inputVariable"
              messageType="client:CreateInvoiceRequestMessage"/>
<!--Reference to the message that will be returned to the requester-->
    <variable name="outputVariable"
              messageType="client:CreateInvoiceResponseMessage"/>
    <variable name="Invoke_1_CREATE_SINGLE_INVOICE_1037895_InputVariable"
              messageType="ns1:Request"/>
    <variable name="Invoke_1_CREATE_SINGLE_INVOICE_1037895_OutputVariable"
              messageType="ns1:Response"/>
    <variable name="Invoke_2_SynchRead_InputVariable"
              messageType="ns4:Empty_msg"/>
    <variable name="Invoke_2_SynchRead_OutputVariable"
              messageType="ns4:InputParameters_msg"/>
</variables>
<!--
/////////////////////////////////////////////////////////////////////
ORCHESTRATION LOGIC                                               
     Set of activities coordinating the flow of messages across the    
     services integrated within this business process 
/////////////////////////////////////////////////////////////////////
-->
<sequence name="main">
    <!--Receive input from requestor. (Note: This maps to operation defined in CreateInvoice.wsdl)-->
         <receive name="receiveInput" partnerLink="client"
             portType="client:CreateInvoice" operation="process"
             variable="inputVariable" createInstance="yes"/>
    <!--Generate reply to synchronous request-->
    <assign name="SetHeader">
      <copy>
        <from expression="''operations'">
        <to variable="Invoke_1_CREATE_SINGLE_INVOICE_1037895_InputVariable"
            part="header"
            query="/ns1:SOAHeader/ns2:ProcedureHeaderType/ns2:Username"/>
      </copy>
      <copy>
        <from expression="''Receivables, Vision Operations (USA)'">
        <to variable="Invoke_1_CREATE_SINGLE_INVOICE_1037895_InputVariable"
            part="header"
            query="/ns1:SOAHeader/ns2:ProcedureHeaderType/ns2:Responsibility"/>
      </copy>
      <copy>
        <from expression="''204'">
        <to variable="Invoke_1_CREATE_SINGLE_INVOICE_1037895_InputVariable"
            part="header"
            query="/ns1:SOAHeader/ns2:ProcedureHeaderType/ns2:ORG_ID"/>
      </copy>
      <copy>
        <from expression="''Receivables, Vision Operations (USA)'">
        <to variable="Invoke_1_CREATE_SINGLE_INVOICE_1037895_InputVariable"
            part="header"
            query="/ns1:SOAHeader/ns1:SecurityHeader/ns1:ResponsibilityName"/>
      </copy>
   </assign>
   <invoke name="InvokeReadPayload" partnerLink="ReadPayload"
            portType="ns4:SynchRead_ptt" operation="SynchRead"
            inputVariable="Invoke_2_SynchRead_InputVariable"
            outputVariable="Invoke_2_SynchRead_OutputVariable"/>
   <assign name="SetPayload">
      <copy>
        <from variable="Invoke_2_SynchRead_OutputVariable"
              part="InputParameters" query="/ns3:InputParameters"/>
        Invoke_1_CREATE_SINGLE_INVOICE_1037895_InputVariable"
        part="body" query="/ns1:SOARequest/ns3:InputParameters"/>
      </copy>
   </assign>
   <assign name="SetDate">
      <copy>
        <from expression="xp20:current-date()">
        <to to variable="Invoke_1_CREATE_SINGLE_INVOICE_1037895_InputVariable"
            part="body"
            query="/ns1:SOARequest/ns3:InputParameters/ns3:P_TRX_HEADER_TBL/ns3:P_TRX_HEADER_TBL_ITEM/ns3:TRX_DATE"/>
      </copy>
   </assign>
   <invoke name="Invoke_1" partnerLink="CREATE_SINGLE_INVOICE_1037895"
            portType="ns1:CREATE_SINGLE_INVOICE_1037895_ptt"
            operation="CREATE_SINGLE_INVOICE_1037895"
            inputVariable="Invoke_1_CREATE_SINGLE_INVOICE_1037895_InputVariable"
            outputVariable="Invoke_1_CREATE_SINGLE_INVOICE_1037895_OutputVariable"/>
   <assign name="AssignResult">
      <copy>
        <from variable="Invoke_1_CREATE_SINGLE_INVOICE_1037895_OutputVariable"
              part="body"
              query="/ns1:SOAResponse/ns3:OutputParameters/ns3:X_MSG_DATA"/>
        <to variable="outputVariable" part="payload"
            query="/client:CreateInvoiceProcessResponse/client:result"/>
      </copy>
   </assign>
   <reply name="replyOutput" partnerLink="client"
           portType="client:CreateInvoice" operation="process"
           variable="outputVariable"/>
 </sequence>
</process>

For more information on how to annotate composite service - BPEL type, see Composite Service - BPEL Annotations.

Generating and Uploading iLDT Files

Once annotated custom composite services - BPEL have been created, these annotated source files need to be validated against the annotation standards specifically for composite service - BPEL type before they can be uploaded to Oracle Integration Repository. This validation is performed by running the Integration Repository Parser (IREP Parser), a design-time tool, to read the annotated files and then generate an Integration Repository loader file (iLDT ) if no error occurred.

Note: Please note that Integration Repository Parser does not support the integration interfaces registered under custom applications.

It is currently tested and certified for Linux, Unix, Oracle Solaris on SPARC, HP-UX Itanium, and IBM AIX on Power Systems.

Microsoft Windows platform is currently not supported in this release.

Once an iLDT file has been successfully generated, an integration administrator can upload the generated file to Oracle Integration Repository where the custom interfaces can be exposed to all users.

For information on how to set up and use the Integration Repository Parser to generate an iLDT file as well as how to upload the generated iLDT file, see:

Viewing and Downloading Custom Composite Services - BPEL

Once annotated custom composite service definitions have been successfully uploaded to the Integration Repository user interface, they are merged into the Composite Service BPEL type and displayed together with Oracle seeded interfaces. To easily distinguish custom composite services from Oracle seeded ones, Interface Source "Custom" is used to categorize those custom interfaces in contrast to Interface Source "Oracle" for Oracle seeded interfaces in Oracle E-Business Suite.

To search for custom composite services, from the Search page, click Show More Search Options to expand the search criteria. Select 'Custom' from the Interface Source drop-down list along with 'Composite Service' interface type, product family, or scope if needed as the search criteria. After you perform the search, all matched custom composite services will be displayed.

Downloading Custom Composite Services - BPEL

Similar to downloading native packaged composite services, integration administrators and integration developers can click Download Service in the composite service - BPEL interface details page to download the relevant custom composite files aggregated in a .JAR file to their local directories.

For more information on how to search and download custom composite services - BPEL, see Downloading Composite Services - BPEL, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Creating Custom Business Events Using Workflow XML Loader

Oracle E-Business Suite Integrated SOA Gateway allows you to create custom business events in the Business Event System, download the events that you have created, annotate the event source codes, validate the source files, and then upload the files back to the event system using Workflow XML Loader.

The Workflow XML Loader is a command line utility that lets you upload and download XML definitions for Business Event System objects between a database and a flat file. When you download Business Event System object definitions from a database, Oracle Workflow saves the definitions as an XML file. When you upload object definitions to a database, Oracle Workflow loads the definitions from the source XML file into the Business Event System tables in the database, creating new definitions or updating existing definitions as necessary.

XML files uploaded or downloaded by the Workflow XML Loader should have the extension .wfx to identify them as Workflow object XML definitions.

Use the following steps to create custom business events:

  1. Locate and Download Business Events

  2. Annotate the XML Definition File

  3. Validate the Annotated Source File Using Integration Repository Parser

  4. Upload Annotated File to the Database

  5. Upload iLDT Files to Integration Repository

Step 1: Locating and Downloading Business Events

After creating custom business events in the Oracle Workflow Business Event System, you first locate them and then download them using Workflow XML Loader.

Events Page with Search and Results Regions

the picture is described in the document text

To download XML definitions for Business Event System objects between a database and a flat file, run the Workflow XML Loader by running Java against oracle.apps.fnd.wf.WFXload with the following command syntax:

jre oracle.apps.fnd.wf.WFXload -d{e} <user> <password> <connect string> <protocol> <language> <xml file> <object> {<key>} {<OWNER_TAG>} {<owner>}

For example, you can download either a single event or a group of events:

After successfully downloading the event XML definitions, open the .wfx file in any text editor. You will find the content of a wfdemoe.wfx file, for example, containing one event shown as follows:

<?xml version = '1.0' encoding = 'UTF-8'?>
...

<oracle.apps.wf.event.all.sync><ExternalElement>
<OraTranslatibility>
<XlatElement Name="WF_EVENTS">
<XladID>
<Key>NAME</Key>
</XladID>
<XlatElement Name="DISPLAY_EVENTS" MaxLen="80" Expansion="50"/>
<XladID>
<Key Type="CONSTANT">DISPLAY_EVENTS</Key>
</XladID>
<XlatElement Name="DESCRIPTION" MaxLen="2000" Expansion="50"/>
<XladID>
<Key Type="CONSTANT">DESCRIPTION</Key>
</XladID>
</XlatElement>
</OraTranslatibility>
</ExternalElement>
<WF_TABLE_DATA>
  <WF_EVENTS>
        <VERSION>1.0</VERSION>
                <GUID>#NEW</GUID>
                <NAME>abc.apps.wf.demo.event</NAME>
                <TYPE>EVENT</TYPE>
                <STATUS>ENABLED</STATUS>
                <GENERATE_FUNCTION/>
                <OWNER_MAME>Oracle Workflow</OWNER_MAME>
                <OWNER_TAG>FMD</OWNER_TAG>
                <CUSTOMIZATION_LEVEL>U</CUSTOMIZATION_LEVEL>
                <LICENSED_FLAG>Y</LICENSED_FLAG>
                <JAVA_GENERATE_FUNC/>
                <DISPLAY_NAME>Demo Business Event</DISPLAY_NAME>
                <DESCRIPTION>Business event created for annotation demo.</DESCRIPTION>
                <IREP_ANNOTATION>
/*# 
* Business event created for annotation demo.
* 
* @rep:scope public 
* @rep:displayname Demo Business Event 
* @rep:product FND 
* @rep:category BUSINESS_ENTITY 
*/
</IREP_ANNOTATION>
                </WF_EVENTS>
</WF_TABLE_DATA>
</oracle.apps.wf.event.all.sync>

The Workflow XML Loader automatically creates a template for integration repository annotation as highlighted in bold between <IREP_ANNOTATION> and </IREP_ANNOTATION>. This is where appropriate annotations need to be placed or modified for a business event based on the business event annotation standards.

To download business events XML definitions:

  1. Log in to Oracle E-Business Suite as a user who has the Workflow Administrator Web Applications responsibility. Select the Business Events link from the Navigator to open the Events page.

  2. Enter search criteria in the Search region to locate your business events.

  3. Change your directory to the same environment where your application is running.

    For example, if your application is running on seed100, then change your directory to seed100 where your business events exist.

    /slot/ems3404/appmgr/apps/apps_st/appl
. ./APPSseed100.env

  4. Download the events from the database using oracle.apps.fnd.wf.WFXload with the following syntax:

    jre oracle.apps.fnd.wf.WFXload -d{e} <user> <password> <connect string> <protocol> <language> <xml file> <object> {<key>} {<OWNER_TAG>} {<owner>}

  5. Open the .wfx file in any text editor and notice that one business event has been placed there.

Step 2: Annotating an XML Definition

After successfully downloading the XML definition file from a database, you should open the .wfx file containing one business event in any text editor and modify the annotation appropriately based on Integration Repository business event annotation standards.

The appropriate annotation includes:

Please note that the IREP properties should not be blank. For example, the Workflow XML Loader only adds the template for Business Entity as rep:category BUSINESS_ENTITY, but you should add an appropriate business entity to which the event belongs. Similarly, other @rep properties cannot be left blank either.

The following is a sample business event annotation for Oracle Workflow:

* Business Event created to demonstrate using WFXLoad to annotate Business Events. 
* 
* @rep:scope internal 
* @rep:displayname Demo Business Event 
* @rep:product OWF 
* @rep:lifecycle active 
* @rep:category BUSINESS_ENTITY WF_EVENT 
*/

Important: If you decide not to annotate or publish the event in Oracle Integration Repository, you should remove the annotation only but leave the following tags unchanged. Presence of these tags is an indication that the event was reviewed for annotation.

<IREP_ANNOTATION/>

or

<IREP_ANNOTATION></IREP_ANNOTATION>

If the Loader sees these empty tags, it interprets that the business event was reviewed for annotation and it does not need to be published to the Integration Repository. Next time, when the user downloads these events, the Loader will insert empty IREP_ANNOTATION tags as shown in the following example.

However, if you remove the entire IREP_ANNOTATION tags for the business event and upload it, then on subsequent download, the Loader will insert partially filled annotation template for the business event.

<WF_TABLE_DATA>
  <WF_EVENTS>
        <VERSION>1.0</VERSION>
                <GUID>#NEW</GUID>
                <NAME>oracle.apps.wf.demo.event.noannotate</NAME>
                <TYPE>EVENT</TYPE>
                <STATUS>ENABLED</STATUS>
                <GENERATE_FUNCTION/>
                <OWNER_MAME>Oracle Workflow</OWNER_MAME>
                <OWNER_TAG>FMD</OWNER_TAG>
                <CUSTOMIZATION_LEVEL>U</CUSTOMIZATION_LEVEL>
                <LICENSED_FLAG>Y</LICENSED_FLAG>
                <JAVA_GENERATE_FUNC/>
                <DISPLAY_NAME>Demo Business Event with no annotation</DISPLAY_NAME>
                <DESCRIPTION>Business second event created for annotation demo.</DESCRIPTION>
                <IREP_ANNOTATION>/*#
* Business event created for annotation demo.
*
* @rep:scope public
* @rep:displayname Demo Business Event
* @rep:product FND
* @rep:category BUSINESS_ENTITY
*/
</IREP_ANNOTATION>
  </WF_EVENTS>
</WF_TABLE_DATA>

For more information on Integration Repository Business Event Annotation Standards, see Business Event Annotations.

Step 3: Validating the Annotated Source File Using Integration Repository Parser

Integration Repository Parser is a standalone design-time tool. It can be run to validate the annotated custom interface definitions against the annotation standards and to generate an iLDT file if no error occurs.

After annotating the XML definition for a business event, run the standalone Integration Repository Parser (IREP Parser) using the following command syntax to validate whether the annotation in .wfx file is valid:

Command Syntax:

$IAS_ORACLE_HOME/perl/bin/perl $FND_TOP/bin/irep_parser.pl -g -v -username=<a fnd username> <product>:<relative path from product top>:<fileName>:<version>=<Complete File Path, if not in currect directory>

For example:

$IAS_ORACLE_HOME/perl/bin/perl $FND_TOP/bin/irep_parser.pl -g -v -username=sysadmin owf:patch/115/xml/US:wfdemoe.wfx:12.0=./wfdemoe.wfx

While running the parser, you should pay attention to any error messages on the console. Typically these errors would be due to incorrect annotation or some syntax errors in the annotated file. Ensure that the annotations are correct and the file has proper syntax.

If no error occurred in the annotated interface file, an iLDT (*.ildt) file would be generated. An integration administrator needs to upload the generated iLDT file to the Integration Repository where the custom business events can be exposed to all users. See Step 5: Uploading iLDT Files to Integration Repository.

Integration Repository Parser (irep_parser.pl)

The irep_parser is a design-time tool. It reads interface annotation documentation in program source files and validates it according to its file type. If the -generate flag is supplied (and other conditions met), then it will generate iLDT files. Any validation errors will be reported, usually along with file name and line number, like the result of grep -n.

Additionally, it can handle almost all types of application source files. While validating the annotated files against the annotation standards of supported interface types, if files that do not match will be ignored.

The parser will return an exit value of 0 if no errors occurred during processing. Otherwise, it will return a count of the number of files that had errors. Files with incomplete information for generation (class resolution) are considered errors only if the -generate flag is used.

However, before running the Integration Repository Parser, you need to install perl modules and apply necessary patches. For the setup information, see Setting Up and Using Integration Repository Parser, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

For information on the Integration Repository Parser (irep_parser.pl) usage details including supported file types and options, files specifications, and environment, see Integration Repository Parser (irep_parser.pl) Usage Details, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Step 4: Uploading Annotated File Back to a Database

After validating the annotated source file .wfx, upload the file back to the database where you downloaded it earlier so that the annotated file can be stored in the appropriate tables in business event system for future references.

Note: To view custom business events through the Integration Repository browser window, an integration administrator needs to upload the generated iLDT files to the Integration Repository. For information on uploading iLDT files, see Step 5: Uploading iLDT Files to Integration Repository.

The Workflow XML Loader lets you upload business event system XML definitions in either normal upload mode (-u) or force upload mode (-uf):

For more information on how to use Workflow XML Loader, see Using the Workflow XML Loader, Oracle Workflow Administrator's Guide.

Step 5: Uploading ILDT Files to Integration Repository

After the validation using the Integration Repository Parser, an iLDT file will be generated if no error occurred during the iLDT generation. In order for users to view the custom business events through the Integration Repository, an integration administrator needs to manually upload the generated iLDT file to the Integration Repository using FNDLOAD command.

$FND_TOP/bin/FNDLOAD <APPS username> 0 Y UPLOAD $fnd/patch/115/import/wfirep.lct <ildt file>
ORACLE Password:

For example,

FND_TOP/bin/FNDLOAD apps @instance_name 0 Y UPLOAD $FND_TOP/patch/115/import/wfirep.lct SOAIS_pls.ildt

ORACLE Password: password

For detailed information on how to upload the iLDT files, see Uploading ILDT Files to Integration Repository, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Viewing Custom Interfaces and Performing Administrative Tasks

Searching and Viewing Custom Interfaces

Annotated custom interface definitions, once they have been successfully uploaded, are merged into the interface types they belong to and displayed together with Oracle seeded interfaces from the Integration Repository browser window. To easily distinguish custom interface definitions from Oracle interfaces, the 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 search for custom integration interfaces, you can use either one of the following ways:

After you perform the search, all matched custom integration interfaces will be displayed. For more information on how to search and view custom integration interfaces, see Searching Custom Integration Interfaces, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide and Viewing Custom Integration Interfaces, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Performing Administrative Tasks

Once custom business events have been successfully uploaded and displayed from the Integration Repository browser window, an integration administrator can perform the same administrative tasks on these custom events as they are for the native events. These administrative tasks including creating security grants for newly created custom events if needed, and subscribing to custom business events. See Administering Custom Integration Interfaces and Services, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Using Custom Integration Interfaces as Web Services

Overview

With appropriate annotation and validation, a custom integration interface can be created for the interface type that Oracle Integration Repository supports. If the interface type that the custom interface belongs to can be service enabled, you can use the custom interface as a web service to update or retrieve data from Oracle E-Business Suite or perform other business transactions over the web.

For example, an integration developer can create a new or customized interface for Supplier Ship and Debit Request business entity using a PL/SQL API. Once the interface has been uploaded to Oracle Integration Repository, it will be displayed under the PL/SQL API interface type from the Integration Repository browser. To differentiate the custom interfaces from Oracle native packaged ones, all custom integration interfaces have Interface Source 'Custom' in contrast to Oracle seeded interfaces with Interface Source 'Oracle' when you view them from the repository.

To better understand how to use deployed custom interfaces as web services in fulfilling your business needs, detailed design-time and runtime tasks in creating and deploying a SOA composite application with BPEL process are discussed in this section. For the example described in the following sections, Oracle JDeveloper 11g (11.1.1.6.0) is used as a design-time tool to create the SOA composite application with BPEL process and Oracle SOA Suite 11g (11.1.1.6.0) is used for the process deployment.

Note: While using Oracle JDeveloper with other Oracle Fusion Middleware components (such as Oracle SOA Suite), to enable SOA technologies, you need to manually download Oracle SOA Suite Composite Editor, an Oracle JDeveloper extension for SOA technologies. For more information on installing additional Oracle Fusion Middleware design-time components, see the Oracle Fusion Middleware Installation Guide for Oracle JDeveloper.

Using Custom Interface WSDL in Creating a SOA Composite Application with BPEL Process at Design Time

SOA Composite Application with BPEL Process Scenario

This example uses a custom PL/SQL API ZZ_SDREQUEST to explain the BPEL process creation in a SOA Composite application.

When the request of creating a supplier ship and debit request is received, the request information including payload and request number will be read and passed to create a supplier ship and debit request. After the supplier ship and debit request for a product is created, the request number will then be returned to the requestor.

When the SOA composite application with BPEL process has been successfully invoked after deployment, a supplier ship and debit request is created in the Oracle E-Business Suite. The request number should be the same as the payload input value.

Prerequisites to Create a BPEL Process Using a Custom Web Service

Before performing design-time tasks for a custom interface exposed as a web service, you need to ensure the following tasks are in place:

Creating Security Grants for a Custom Interface

To be able to verify and use this custom interface, the administrator will first locate the custom interface (with 'Custom' interface source) from the repository, and then create security grants on the custom interface so that users with appropriate privileges can have access to the interface.

For example, the administrator can grant the custom API access privilege to a user with the Oracle Trade Management responsibility. After the invocation of this custom API, the user can log on to Oracle Trade Management and verify the supplier and debit request creation details.

For information on how to create security grants, see Creating Grants, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Deploying a Web Service Composite for a Custom Interface

An integration administrator or an integration developer must first create a web service for a selected custom interface, and then the administrator can deploy the custom service from Oracle Integration Repository to an Oracle SOA Suite WebLogic managed server.

For example, the following steps must be performed first before the integration developer creates a BPEL process by using the deployed WSDL:

  1. To generate a web service, the integration administrator or integration developer locates the interface definition first (such as a custom PL/SQL interface ZZ_SDREQUEST) and selects desired interaction pattern information from the Interaction Pattern table. This can be selected at the interface level or at the method level before clicking Generate in the interface details page.

    Once the service has been successfully generated, the Web Service Status field changed from 'Not Generated' to 'Generated' in the interface details page. For detailed instructions on how to generate a web service, see Generating SOAP Web Services, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

  2. To deploy a generated web service, the integration administrator selects one authentication type before clicking Deploy. The deployed service in Oracle SOA Suite is an active service and is ready to accept new SOAP requests.

    Once the service has been successfully deployed, the selected authentication type will be displayed along with 'Deployed' with 'Active' state in the Web Service Status field. For more information on securing web services with authentication type, see Managing Web Service Security, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

    For information on how to deploy a web service, see Deploying and Undeploying SOAP Web Services, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Searching and Recording a WSDL URL

Apart from the required tasks performed by the administrators, the integration developer needs to locate and record the deployed web service WSDL URL for the custom interface that needs to be orchestrated into a meaningful business process in Oracle JDeveloper.

This can be done by clicking the View WSDL link in the interface details page. Copy the WSDL URL from the new pop-up window. This URL will be used later in creating a partner link service in a BPEL process.

For information on how to search for an interface and view the interface details, see Searching and Viewing Integration Interfaces.

SOA Composite Application with BPEL Process Creation Flow

Based on the supplier and debit request creation scenario, the following design-time tasks are discussed in this chapter:

  1. Create a New SOA Composite Application with BPEL Process

    Use this step to create a new SOA composite application with BPEL process called ZZ_CreateSingle_ShipDebitRequest.bpel using an Synchronous BPEL Process template. This automatically creates two dummy activities - Receive and Reply - to receive input from a third party application and to reply output of the BPEL process to the request application.

  2. Create a Partner Link

    Use this step to create an invoice in Oracle E-Business Suite by using the Single Ship and Debit Request custom API ZZ_SDREQUEST exposed as a web service.

  3. Add a Partner Link for File Adapter

    Use this step to synchronously read input data details passed from the first Assign activity to create supplier ship and debit request.

  4. Add Invoke Activities

    Use this step to configure two Invoke activities in order to:

    • Point to the File Adapter to synchronously read input data details that is passed from the first Assign activity.

    • Point to the ZZ_SDREQUEST partner link to initiate the supplier ship and debit request creation with payload and request number details received from the Assign activities.

  5. Add Assign Activities

    Use this step to configure Assign activities in order to pass application context header variables, payload information and request number to appropriate Invoke activities to facilitate the single supplier ship and debit request creation. At the end, pass the request number to the request application through the dummy Reply activity.

For general information and how to create SOA composite applications using BPEL process service component, see the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite for details.

Creating a New SOA Composite Application with BPEL Process

Use this step to create a new SOA composite application that will contain various BPEL process activities.

To create a new SOA composite application with BPEL process:

  1. Open Oracle JDeveloper.

  2. Click New Application in the Application Navigator.

    The "Create SOA Application - Name your application" page is displayed.

  3. Enter an appropriate name for the application in the Application Name field and select SOA Application from the Application Template list.

    Click Next. The "Create SOA Application - Name your project" page is displayed.

  4. Enter an appropriate name for the project in the Project Name field, for example ZZ_CreateSingle_ShipDebitRequest.

  5. In the Project Technologies tab, select 'Web Services' and ensure that SOA is selected from the Available technology list to the Selected technology list.

    Click Next. The "Create SOA Application - Configure SOA settings" page is displayed.

  6. Select Composite With BPEL Process from the Composite Template list, and then click Finish. You have created a new application, and a SOA project. This automatically creates a SOA composite.

    The Create BPEL Process page is displayed.

  7. Leave the default BPEL 1.1 Specification selection unchanged. This creates a BPEL project that supports the BPEL 1.1 specification.

    Enter an appropriate name for the BPEL process in the Name field, for example ZZ_CreateSingle_ShipDebitRequest.

    Select Synchronous BPEL Process in the Template field.

    Select required from the Transaction drop-down list. Click OK.

    A synchronous BPEL process is created with the Receive and Reply activities. The required source files including bpel and wsdl, using the name you specified (for example, ZZ_CreateSingle_ShipDebitRequest.bpel and ZZ_CreateSingle_ShipDebitRequest.wsdl) and composite.xml are also generated.

    Note: Service Provider does not support service creation for PL/SQL stored procedures or packages which have '$' character in parameter type names. The presence of $ in the name would cause the XSD generation to fail.

  8. Navigate to SOA Content > Business Rules and double click the composite.xml to view the composite diagram.

    Double click on the ZZ_CreateSingle_ShipDebitRequest component to open the BPEL process.

Creating a Partner Link for the Web Service

Use this step to create a Partner Link called ZZ_CreateSD_Request.

To create a partner link for Single Ship and Debit Request web service:

  1. In Oracle JDeveloper, place your mouse in the Partner Links area and right click to select Create Partner Link... from the pull-down menu. Alternatively, you can drag and drop Partner Link from the BPEL Constructs list into the right Partner Link swim lane of the process diagram.

    The Create Partner Link window appears.

  2. Copy the WSDL URL corresponding to the custom service, ZZ_SDREQUEST, that you recorded earlier from the Integration Repository in the WSDL File field.

    Press the [Tab] key.

  3. A Partner Link Type message dialog box appears asking whether you want the system to create a new WSDL file that will by default create partner link types for you.

    Click Yes. You can manually enter the partner link name.

  4. Select the Partner Link Type and Partner Role values from the drop-down lists.

    Click Apply.

    The partner link is created with the required WSDL settings, and is represented in the BPEL process by a new icon in the border area of the process diagram.

  5. Click OK to complete the partner link configuration.

    The Partner Link ZZ_SDREQUEST is added to the Partner Links section in the BPEL process diagram.

Adding a Partner Link for File Adapter

Use this step to configure a BPEL process to read input payload.

To add a Partner Link for File Adapter to Read Payload:

  1. In Oracle JDeveloper, drag and drop the File Adapter service from the BPEL Services list into the right Partner Link swim lane of the process diagram. The Adapter Configuration wizard welcome page appears.

  2. Click Next. The Service Name dialog box appears.

  3. Enter a name for the file adapter service such as Read_Payload.

  4. Click Next. The Adapter Interface dialog box appears.

  5. Select the Define from operation and schema (specified later) radio button and click Next. The Operation dialog box appears.

  6. Specify the operation type, for example Synchronous Read File. This automatically populates the Operation Name field.

    Click Next to access the File Directories dialog box.

    File Directories Dialog

    the picture is described in the document text

  7. Select the Physical Path radio button and enter the physical path for incoming file directory information. For example, enter /usr/tmp/ as the directory name.

    Note: To be able to locate the file from the physical directory you specified here, you must first place the input payload file (such as Inputzzsdrequest.xml) to the specified directory.

    Alternatively, click Browse to locate the incoming file directory information.

    Click Next to open the File Name dialog box.

  8. Enter the name of the file for the synchronous read file operation. For example, enter Inputzzsdrequest.xml. Click Next. The Messages dialog box appears.

  9. Select Browse for schema file in front of the URL field.

    The Type Chooser window is displayed.

    Click the Import Schema Files button on the top right corner of the Type Chooser window.

    Enter the schema location for the service. Such as http://<soa_suite_hostname>:<port>/soa-infra/services/default/<jndi_name>_PLSQL_ZZ_SDREQUEST/ZZ_SDREQUEST_Service?XSD=xsd/APPS_XX_BPEL_ZZ_CREATE_SDREQUEST_RE_ZZ_SDREQUEST_ZZ_CREATE_SDREQU.xsd.

    Schema location for your service can be found from the service WSDL URL (for example, http://<soa_suite_hostname>:<port>/soa-infra/services/default/<jndi_name>_PLSQL_ZZ_SDREQUEST/ZZ_SDREQUEST_Service/?wsdl).

    Select the Copy to Project checkbox and click OK.

    The Localize Files window appears. Ensure the Maintain original directory structure for imported files checkbox is selected and click OK.

    The Imported Schema folder is automatically added to the Type Chooser window.

    Type Chooser Dialog

    the picture is described in the document text

    Expand the Imported Schemas folder and select InputParameters Message in the APPS_XX_BPEL_ZZ_CREATE_SDREQUEST_RE_ZZ_SDREQUEST_ZZ_CREATE_SDREQU.xsd. Click OK.

    The selected .xsd is displayed as URL, and the InputParameters is selected as Schema Element.

  10. Click Next and then Finish. The wizard generates the WSDL file corresponding to the partner link. The main Create Partner Link dialog box appears, specifying the new WSDL file Read_Payload.wsdl.

    Click Apply and OK to complete the configuration and create the partner link with the required WSDL settings for the File Adapter Service.

    The Read_Payload Partner Link appears in the BPEL process diagram:

  11. Under applications window, navigate to file ReadPayload_file.jca. Set value of property "DeleteFile" to "false".

Adding Invoke Activities

This step is to configure two Invoke activities:

To add an Invoke activity for the Read_Payload Partner Link:

  1. In Oracle JDeveloper, expand the BPEL Constructs from the Component Palette. Drag and drop the Invoke activity into the center swim lane of the process diagram, between the receiveInput and replyOutput activities.

  2. Link the Invoke activity to the Read_Payload service. The Invoke activity will send request data to the partner link. The Edit Invoke dialog box appears.

  3. Enter a name for the Invoke activity such as 'Invoke_Readpayload', and then click the Create icon next to the Input Variable field to create a new variable. The Create Variable dialog box appears.

    Create Variable Dialog

    the picture is described in the document text

  4. Enter a name for the variable such as 'Invoke_Readpayload_InputVariable' and select the Global Variable radio button. Click OK in the Create Variable dialog box.

    Click the Create icon next to the Output Variable field to create a new variable. The Create Variable dialog box appears.

    Enter a name for the output variable such as 'Invoke_Readpayload_OutputVariable' and select the Global Variable radio button. Click OK in the Create Variable dialog box.

    Click Apply and OK in the Edit Invoke dialog box to finish configuring the Invoke activity.

    The Invoke activity appears in the process diagram.

To add an Invoke activity for the ZZ_SDREQUEST Partner Link:

  1. In Oracle JDeveloper, expand the BPEL Constructs from the Component Palette. Drag and drop the Invoke activity into the center swim lane of the process diagram, after the first Invoke activity and the reployOutput activity.

  2. Link the Invoke activity to the ZZ_SDREQUEST service. The Invoke activity will send the request number to the partner link. The Edit Invoke dialog box appears.

  3. Enter a name for the Invoke activity such as 'Invoke_zzsdrequest'.

    Select the Operation as ZZ_CREATE_SDREQUEST.

  4. Click the Create icon next to the Input Variable field to create a new variable such as 'Invoke_zzsdrequest_InputVariable'. Select the Global Variable radio button and click OK in the Create Variable dialog box.

  5. Click the Create icon next to the Output Variable field to create a new variable such as 'Invoke_zzsdrequest_OutVariable'. Select the Global Variable radio button and click OK in the Create Variable dialog box. Click Apply and OK in the Edit Invoke dialog box to complete the Invoke activity creation.

    The Invoke activity appears in the process diagram.

Adding Assign Activities

This step is to configure four Assign activities:

  1. Set the application context information obtained from the dummy Receive activity. This information will be used in passing variables for SOAHeader elements of the SOAP request.

    Note: You need to populate certain variables in the BPEL process for SOAHeader elements to pass values that may be required to set application context during service invocation. These SOAHeader elements are Responsibility, RespApplication, SecurityGroup, NLSLanguage, and Org_Id.

  2. Pass the payload information to the Invoke_zzsdrequest Invoke activity.

  3. Pass the supplier ship and debit request number information to the Invoke_zzsdrequest Invoke activity.

  4. Pass the supplier ship and debit request number information to the dummy Reply activity as an output.

To add the first Assign activity to pass application context details to the Invoke_Readpayload Invoke activity:

  1. In Oracle JDeveloper, expand the BPEL Constructs from the Component Palette. Drag and drop the Assign activity into the center swim lane of the process diagram between the ReceiveInput activity and the first Invoke activity.

  2. Double-click the Assign activity to access the Edit Assign dialog box.

  3. Click the General tab to enter the name for the Assign activity, such as 'SetHeader'.

  4. Select the Copy Rules tab and expand the target trees:

    • Click the Expression icon to invoke the Expression Builder dialog.

      Enter '204' in the Expression box. Click OK. The Expression icon with the expression value ('204') appears in the center of the Edit Assign dialog, between the From and To navigation tree nodes.

    • In the To navigation tree, navigate to Variable > Process > Variables > Invoke_zzsdrequest_InputVariable >header> ns5:SOAHeader and select ns5:ORG_ID.

    Drag the Expression icon to connect to the target node (ns5:ORG_ID) that you just identified. This creates a line that connects the source and target nodes. The copy rule is displayed in the From and To sections at the bottom of the Edit Assign dialog box.

  5. Enter the second pair of parameters by clicking the Expression icon to invoke the Expression Builder dialog.

    • Enter 'TRADE_MANAGEMENT_USER' in the Expression box. Click OK. The Expression icon with the expression value appears in the center of the Edit Assign dialog, between the From and To navigation tree nodes.

    • In the To navigation tree, navigate to Variable > Process > Variables > Invoke_zzsdrequest_InputVariable >header > ns5:SOAHeader and select ns5:Responsibility.

    Drag the Expression icon to connect to the target node (ns5:Responsibility) that you just identified. This creates a line that connects the source and target nodes. The copy rule is displayed in the From and To sections at the bottom of the Edit Assign dialog box.

  6. Enter the third pair of parameters by clicking the Expression icon to invoke the Expression Builder dialog.

    • Enter 'OZF' in the Expression box. Click OK. The Expression icon with the expression value ('OZF') appears in the center of the Edit Assign dialog, between the From and To navigation tree nodes.

    • In the To navigation tree, navigate to Variable > Process > Variables > Invoke_zzsdrequest_InputVariable >header > ns5:SOAHeader and select ns5:RespApplication.

    Drag the Expression icon to connect to the target node (ns5:RespApplication) that you just identified. This creates a line that connects the source and target nodes. The copy rule is displayed in the From and To sections at the bottom of the Edit Assign dialog box.

  7. Enter the fourth pair of parameters by clicking the Expression icon to invoke the Expression Builder dialog.

    • Enter 'STANDARD' in the Expression box. Click OK. The Expression icon with the expression value ('STANDARD') appears in the center of the Edit Assign dialog, between the From and To navigation tree nodes.

    • In the To navigation tree, navigate to Variable > Process > Variables > Invoke_zzsdrequest_InputVariable >header > ns5:SOAHeader and select ns5:SecurityGroup.

    Drag the Expression icon to connect to the target node (ns5:SecurityGroup) that you just identified. This creates a line that connects the source and target nodes. The copy rule is displayed in the From and To sections at the bottom of the Edit Assign dialog box.

  8. Enter the fifth pair of parameters by clicking the Expression icon to invoke the Expression Builder dialog.

    • Enter 'AMERICAN' in the Expression box. Click OK. The Expression icon with the expression value ('AMERICAN') appears in the center of the Edit Assign dialog, between the From and To navigation tree nodes.

    • In the To navigation tree, navigate to Variable > Process > Variables > Invoke_zzsdrequest_InputVariable >header > ns5:SOAHeader and select ns5:NLSLanguage.

    Drag the Expression icon to connect to the target node (ns5:NLSLanguage) that you just identified. This creates a line that connects the source and target nodes. The copy rule is displayed in the From and To sections at the bottom of the Edit Assign dialog box.

  9. Click OK to complete the configuration of the Assign activity.

To enter the second Assign activity to pass payload information to the Invoke_zzsdrequest Invoke activity:

  1. Add the second Assign activity by dragging and dropping the Assign activity from the BPEL Constructs into the process diagram, between two Invoke activities.

  2. Repeat Step 2 to Step 3 described in creating the first Assign activity to add the second Assign activity called 'SetPayload'.

  3. Select the Copy Rules tab and expand the source and target trees:

    • In the From navigation tree, navigate to Variable > Process > Variables > Invoke_ReadPayload_OutVariable > ZZ_CreateSingle_ShipDebitRequestProcessRequest.

    • In the To navigation tree, navigate to Variable > Process > Variables > Invoke_zzsdrequest_InputVariable > body.

    Drag the source node (ZZ_CreateSingle_ShipDebitRequestProcessRequest) to connect to the target node (body) that you just identified. This creates a line that connects the source and target nodes. The copy rule is displayed in the From and To sections at the bottom of the Edit Assign dialog box.

  4. Click OK to complete the configuration of the Assign activity.

To enter the third Assign activity to pass the supplier ship and debit request number to the Invoke_zzsdrequest Invoke activity:

  1. Add the third Assign activity by dragging and dropping the Assign activity from the BPEL Constructs into the process diagram, between the second Assign activity and the Invoke_zzsdrequest Invoke activity.

  2. Repeat Step 2 to Step 3 described in creating the first Assign activity to add the third Assign activity called 'SetRequestNumber'.

  3. Select the Copy Rules tab and expand the source and target trees:

    • In the From navigation tree, navigate to Variable > Process > Variables > inputVariable > Payload > client:ZZ_CreateSingle_ShipDebitRequestProcessRequest > client:input.

    • In the To navigation tree, navigate to Variable > Process > Variables > Invoke_zzsdrequest_InputVariable > Body > ns3:InputParameters >ns3:CP_SDR_HDR_REC > ns3:REQUEST_NUMBER and select ns3:TRX_NUMBER.

    Drag the source node (client:input) to connect to the target node (ns3:TRX_NUMBER) that you just identified. This creates a line that connects the source and target nodes. The copy rule is displayed in the From and To sections at the bottom of the Edit Assign dialog box.

  4. Click OK in the Assign window to complete the configuration of the Assign activity.

To add the fourth Assign activity to reply back supplier ship and debit request number:

  1. Add the third Assign activity by dragging and dropping the Assign activity from the BPEL Constructs into the process diagram, between the Invoke_zzsdrequest Invoke and the ReplyOutput activities.

  2. Repeat Step 2 to Step 3 described in creating the first Assign activity to add the fourth Assign activity called 'SetRequestNumber'.

  3. Select the Copy Rules tab and expand the source and target trees:

    • In the From navigation tree, navigate to Variable > Process > Variables > Invoke_zzsdrequest_OutputVariable > body.

    • In the To navigation tree, navigate to Variable > Process > Variables > outputVariable > payload.

    Drag the source node (body) to connect to the target node (payload) that you just identified. This creates a line that connects the source and target nodes. The copy rule is displayed in the From and To sections at the bottom of the Edit Assign dialog box.

  4. Click OK in the Assign window to complete the configuration of the Assign activity.

Configuring Web Service Policies

Use the following steps to add security policies at design time:

  1. Navigate to SOA Content > Business Rules > composite.xml. Right click on the ZZ_SDREQUEST service and select "Configure WS Policies" from the drop-down list.

  2. The Configure SOA WS Policies dialog appears.

    In the Security section, click the Add icon (+). The Select Server Security Policies dialog appears.

    Select 'oracle/wss_username_token_service_policy' and click OK.

    The attached security policy is shown in the Security section.

  3. From the navigation menu, select View > Property Inspector to display the Property Inspector window for ZZ_SDREQUEST service component.

    In the Properties section, click the Add icon (+) for binding properties. The Create Property dialog appears.

    Enter 'oracle.webservices.auth.username' in the Name field and enter 'operations' as the value.

    Click OK.

  4. Use the same approach by clicking the Add icon (+) again in the Properties section for binding properties. Enter 'oracle.webservices.auth.password' in the Name field. Enter the associated password for user 'operations' in the Value field.

    Click OK.

    Both selected property names and values appear in the Properties section.

Deploying and Testing the SOA Composite with BPEL Process at Runtime

To invoke the synchronous custom service (ZZ_SDREQUEST) from the BPEL client contained in the SOA composite, the SOA composite needs to be deployed to the Oracle WebLogic managed server. This can be achieved using Oracle JDeveloper. Once the composite is deployed, it can be tested from the Oracle Enterprise Manager Fusion Middleware Control Console.

Prerequisites

Before deploying the SOA composite with BPEL process using Oracle JDeveloper, you must have established the connectivity between the design-time environment and the runtime server. For information on how to configure the necessary server connection, see Configuring Server Connection.

Note: If a local instance of the WebLogic Server is used, start the WebLogic Server by selecting Run > Start Server Instance from Oracle JDeveloper. Once the WebLogic Admin Server "DefaultServer" instance is successfully started, the <Server started in Running mode> and DefaultServer started message in the Running:DefaultServer and Messages logs should appear.

Perform the following runtime tasks:

  1. Deploy the SOA Composite Application with BPEL Process

  2. Test the SOA Composite Application with BPEL Process

Deploying the SOA Composite with BPEL Process

You must deploy the Create Single Supplier Ship and Debit Request BPEL process (ZZ_CreateSingle_ShipDebitRequest.bpel) contained in the SOA composite application that you created earlier before you can run it.

To deploy the SOA composite application:

  1. In the Applications Navigator of JDeveloper, select the ZZ_CreateSingle_ShipDebitRequest project.

  2. Right-click the project and select Deploy > [project name] > [serverConnection] from the menu.

    For example, you can select Deploy > ZZ_CreateSingle_ShipDebitRequest > SOAServer to deploy the process if you have the connection set up appropriately.

    Note: If this is the first time to set up the server connection, then the Deployment Action dialog appears. Select 'Deploy to Application Server' and click Next.

    In the Deploy Configuration dialog, ensure the following information is selected before clicking Next to add a new application server:

    • New Revision ID: 1.0

    • Mark composite revision as default: Select this checkbox.

    • Overwrite any existing composites with the same revision ID: Select this checkbox.

    The steps to create a new Oracle WebLogic Server connection from Oracle JDeveloper are covered in Configuring Server Connection.

  3. In the Select Server dialog, select 'soa-server1' that you have established the server connection earlier. Click Next.

  4. In the SOA Servers dialog, accept the default target SOA Server ('soa-server1') selection.

    Click Next and Finish.

  5. If you are deploying the composite for the first time from your Oracle JDeveloper session, the Authorization Request window appears. Enter the user name and corresponding password specified during the Oracle SOA Suite installation. Click OK.

  6. Deployment processing starts. Monitor deployment process and check for successful compilation in the SOA - Log window.

    Verify that the deployment is successful in the Deployment - Log window.

Testing the SOA Composite Application with BPEL Process

Once the BPEL process contained in the SOA composite application has been successfully deployed, you can manage and monitor the process from Oracle Enterprise Manager Fusion Middleware Control Console. For more information about Oracle SOA Suite, see the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite.

You can also test the process and the integration interface by manually initiating the process, and then log on to Oracle E-Business Suite to validate that the supplier ship and debit request is successfully created with the request number you specified.

To test the SOA composite application with BPEL process:

  1. Navigate to Oracle Enterprise Manager Fusion Middleware Control Console (http://<hostname>:<port>/em). The login page appears.

  2. Enter the user name and corresponding password specified during the installation. Click Login to log in to a farm. The composite (ShipNotice) you deployed is displayed in the Applications Navigation tree.

    You may need to select an appropriate target instance farm if there are multiple target Oracle Enterprise Manager Fusion Middleware Control Console farms.

  3. From the Farm navigation pane, expand the SOA >soa-infra node in the tree to navigate through the SOA Infrastructure home page and menu to access your deployed SOA composite applications running on soa-infra managed server.

    Click the ZZ_CreateSingle_ShipDebitRequest [1.0] link.

  4. In the ZZ_CreateSingle_ShipDebitRequest [1.0] home page, click Test.

  5. The Test Web Service page for initiating an instance appears. You can specify 'SD-Request1' as XML payload data to use in the Input Arguments section.

    Note: The Request Number entered here should be unique each time that you initiate the process because this number will be used as the Supplier Ship and Debit number across users in Oracle Trade Management.

    Click Test Web Service to initiate the process.

    The test results appear in the Response tab upon completion.

  6. Verifying SOAP Response in the Console

    In the Response tab page, click the Launch Message Flow Trace link to view the result of synchronous composite application. The Flow Trace page is displayed.

    In the Trace section, verify that all components have a Completed state indicating that the application is processed successfully.

    You can check the Faults section to see if any error occurred during the test.

  7. Click your BPEL service component instance link (such as ZZ_CreateSingle_ShipDebitRequest) to display the Instances page where you can view the invocation details of the BPEL activities in the Audit Trail tab.

    Click the Flow tab to check the BPEL process flow diagram. Click an activity of the process diagram to view the activity details and flow of the payload through the process.

  8. Double-click the Invoke_ZZ_CreateSingle_ShipDebitRequest icon from the process flow chart and click the View XML document link to open the XML file. This file records the Request ID that is returned for the transaction.

  9. Log in to Oracle E-Business Suite as trademgr user and then select the Oracle Trade Management User responsibility. Select the 'Supplier Ship and Debit' link from the navigation menu to open the Ship and Debit Overview window.

  10. Verify if the request number 'SD-Request1' that you entered in Step 5 appears in the list.

  11. Click the request number 'SD-Request' link. The Ship and Debit Request Details page is displayed allowing you to verify the request details.