3 Using APIs

Creating a New BPEL Project

The first configuration task is to create a new BPEL project. This section describes how to create a new BPEL project.

To create a new BPEL project:

1. Open BPEL Designer.

2. From the File menu, select New. The New Gallery dialog box is displayed.

3. Select All Items from the Filter By list. This displays a list of available categories.

4. Expand the General node, and then select Projects.

5. Select BPEL Process Project from the Items list, as shown in Figure 3-1.

   Figure 3-1 Creating a New BPEL Process Project

   
   Description of "Figure 3-1 Creating a New BPEL Process Project"
   
   

6. Click OK. The BPEL Process Project dialog box is displayed.

7. In the BPEL Process Name field, enter a descriptive name. For example, InsertShipNotice.

8. From the Template list, select Empty BPEL Process. Keep the default selection for Use Default in the Project Content section, as shown in Figure 3-2.

   Figure 3-2 Specifying a Name for the New BPEL Process Project

   
   Description of "Figure 3-2 Specifying a Name for the New BPEL Process Project"
   
   

9. Click OK. An empty BPEL process, with the necessary source files including bpel.xml, InsertShipNotice.xml, and InsertShipNotice.wsdl is created. Figure 3-3 shows the new BPEL process.

   Figure 3-3 New BPEL Process

   
   Description of "Figure 3-3 New BPEL Process"
   
   

Adding a New Partner Link

The next task is to add a partner link to the BPEL process. This section describes how to create an OracleAS adapter for the application service by adding a partner link to your BPEL process. A BPEL partner link defines the link name, type, and the role of the BPEL process that interacts with the partner service.

To add a partner link:

1. Drag and drop PartnerLink into the border area of the process diagram. The Create Partner Link dialog box is displayed.

2. Click Define Adapter Service in the WSDL Settings section. The Adapter Configuration Wizard is displayed.

3. Click Next. The Adapter Type dialog box is displayed.

4. Select Oracle Applications to specify the adapter you want to configure, as shown in Figure 3-4.

   Figure 3-4 Selecting OracleAS Adapter for Oracle Applications

   
   Description of "Figure 3-4 Selecting OracleAS Adapter for Oracle Applications"
   
   

5. Click Next. The Service Name dialog box is displayed.

6. Enter the following information:

   1. In the Service Name field, enter a service name.

   2. In the Description field, enter a description for the service. This is an optional field. The Service Name dialog box is displayed, as shown in Figure 3-5.

      Figure 3-5 Specifying the Service Name and Description

      
      Description of "Figure 3-5 Specifying the Service Name and Description"
      
      

7. Click Next. The Service Connection dialog box is displayed.

8. Enter the JNDI (Java Naming and Directory Interface) name in the Database Server JNDI Name field. The JNDI name acts as a placeholder for the connection used when your service is deployed to the BPEL server. This enables you to use different databases for development and later for production.

   
   

   See Also: Oracle Application Server Adapter Concepts for understanding JNDI concepts.

   
   

   Figure 3-6 shows how to create a new database connection.

   Figure 3-6 Creating a New Database Connection

   
   Description of "Figure 3-6 Creating a New Database Connection"
   
   

9. Click New to define a database connection. The Create Database Connection Wizard is displayed.

   
   

   Note: You need to connect to the database where Oracle Applications is running.

   
   

10. Click Next. The Type dialog box is displayed, as shown in Figure 3-7.

11. Enter the following information in the Type dialog box:

    1. In the Connection Name field, specify a unique name for the database connection.

    2. From the Connection Type list, select the type of connection for your database.

       Figure 3-7 Specifying a Name and Type for the Database Connection

       
       Description of "Figure 3-7 Specifying a Name and Type for the Database Connection"
       
       

12. Click Next. The Authentication dialog box is displayed.

13. Enter the following information:

    1. In the UserName field, specify a unique name for the database connection.

    2. In the Password field, specify a password for the database connection.

14. Click Next. The Connection dialog box is displayed.

15. Enter the following information:

    1. From the Driver list, select Thin.

    2. In the Host Name field, specify the host name for the database connection.

    3. In the JDBC Port field, specify the port number for the database connection.

    4. In the SID field, specify the unique SID value for the database connection.

       The Connection dialog box is displayed, as shown in Figure 3-8.

       Figure 3-8 Specifying Connection Details for the New Database

       
       Description of "Figure 3-8 Specifying Connection Details for the New Database"
       
       

16. Click Next. The Test dialog box is displayed.

17. Click Test Connection to determine whether the specified information establishes a connection with the database.

18. Click Next. The Service Connection dialog box is displayed, providing a summary of your database connection.

19. Click Finish to complete the process of creating a new database connection.

    Once you have completed creating a new connection for the service, you can add an API by browsing through the list of APIs available in Oracle Applications.

20. Click Next. The Application Interface dialog box is displayed, as shown in Figure 3-9.

    
    

    Note: If you are connecting to a pre-11.5.10 Oracle Applications instance, then you would be required to select the interface to Oracle Applications data. Select Tables/Views/APIs/Concurrent Programs to proceed.

    
    

    Figure 3-9 Adding the Database Objects

    
    Description of "Figure 3-9 Adding the Database Objects"
    
    

21. Click Get Object to open the Oracle Applications Module Browser. Figure 3-10 shows the Oracle Applications Module Browser.

    Figure 3-10 Specifying the API

    
    Description of "Figure 3-10 Specifying the API"
    
    

    Oracle Applications Module Browser includes the various product families that are available in Oracle Applications. For example, the Marketing Suite or the Order Management Suite are product families in Oracle Applications. The product families contain the individual products. For example, the Order Management Suite contains the Shipping Execution Common product. The product contains the business entities associated with the product. For example, the Shipping Execution Common product contains the Delivery entity. Business entities contain the various application modules that are exposed for integration. These modules are grouped according to the interface they provide. APIs can be found under the PLSQL category.

    
    

    Note: In the 11.5.10 instance the Module Browser displays only the public APIs that are exposed to the integration repository. Whereas, in the pre-11.5.10 instance the Module Browser displays all the APIs that are available in the package.

    
    

22. Select the required API. The signature of that given API is displayed.

23. click OK. You can select only one API for each adapter service. Figure 3-11 shows that the API has been added.

    
    

    Note: Use the Search option to quickly find the required objects. Enter the required database object name in the Object Name field and select APIs. And then, click Search to retrieve the required database objects. When searching for an API, enter the package name, and not the procedure name. In contrast, when using the DB Adapter Wizard, the user must enter the name of the API while searching.

    
    

    Figure 3-11 Adding the API

    
    Description of "Figure 3-11 Adding the API"
    
    

24. Click Next, and then click Finish to complete the process of configuring OracleAS Adapter for Oracle Applications. The wizard generates the WSDL file corresponding to the XML schema. This WSDL file is now available for the partner link.

25. Click OK. The partner link is created with the required WSDL settings.

    After adding and configuring the partner link, the next task is to configure the BPEL process.

Describing Wrapper APIs

The Adapter Configuration wizard generates a wrapper API when an API has arguments the data types of which are: PL/SQL Boolean, PL/SQL Table, or PL/SQL Record. For generating the wrapper API, Oracle JPublisher is automatically invoked in the background. When a wrapper API is created, besides the WSDL and XSD files, two SQL files are created: one for creating the wrapper API, and necessary datatypes and another for deleting it. The two SQL files are saved in the same directory where the WSDL and XSD files are stored, and are available in the Project view.

The following is a sample code of an API that would require a wrapper to be generated:

package pkg is    type rec is record (...);    type tbl is table of .. index by ..;    procedure proc(r rec, t tbl, b boolean);end;

If the preceding API is selected in the wizard, then a wrapper API will be created, and loaded into the database. This wrapper API will be used instead of the originally selected API. For this reason, the content of the WSDL and XSD files represent the wrapper procedure, not the procedure originally selected.

The following are the types that will be created for the wrapper API:

• Object type for PL/SQL RECORD

• Nested table of the given type for PL/SQL TABLE. For example, the nested table of NUMBER.

• INTEGER substituted for PL/SQL BOOLEAN

The generated SQL file that creates the wrapper API also creates the required schema objects. The types of the wrapper APIs parameters will be that of the new schema object types. The wrapper package will contain conversion APIs to convert between the base PL/SQL type and the new schema object types.

The wrapper API is created in a package. This package is named XX_BPEL_SERVICE_NAME, as shown in Figure 3-12. SERVICE_NAME is the name of the service that you entered in step 6 of Adding a New Partner Link. If this package already exists, then the wizard prompts for a different package name, or to select a checkbox, to overwrite the existing package. Overwriting an existing package causes all APIs in the specified package to be lost. When the wizard creates a package for the wrapper, only one API, that is, the wrapper API, is contained in it.

The name of the wrapper API depends on whether the API that was originally selected is in a package or not. If the original API is a root-level API, that is, it does not belong in a package, then the name of the wrapper API will be, TOPLEVEL$ORIGINAL_API_NAME. If the originally selected API is in a package, then the name of the wrapper API will be, ORIGINAL_PACKAGE_NAME$ORIGINAL_API_NAME.

Wrapper APIs follow the naming convention of Oracle JPublisher. For example, if the original API was called CREATE_EMPLOYEE and was a root-level API, then the wrapper API would be named, TOPLEVEL$CREATE_EMPLOYEE. If the original API is in a package called EMPLOYEE, then the wrapper API would be named, EMPLOYEE$CREATE_EMPLOYEE.

Figure 3-12 Entering a Package Name for the Wrapper API

Description of "Figure 3-12 Entering a Package Name for the Wrapper API"

The Finish page is different when a wrapper API needs to be created, as shown in Figure 3-13. The Finish page informs you that a wrapper API is needed, and in addition, lists the name of the wrapper package, wrapper API, and the SQL files that will be created.

Figure 3-13 The Finish Page

Description of "Figure 3-13 The Finish Page"

Describing Parameters With DEFAULT Clause

You can declare parameters of a stored procedure with a default clause, that when, in the absence of the parameter from the invocation of the procedure, will supply a default value for that parameter. For example:

PROCEDURE addEmployee (name VARCHAR2, country VARCHAR2 DEFAULT 'US')

This procedure can be invoked in the following two different ways:

1. addEmployee ('John Smith')	// country => 'US'
2. addEmployee ('John Smith', 'France')	// country => 'France'

You can omit elements for parameters with default values in the instance XML. The procedure will be invoked without these parameters, allowing their default values to be used, as shown in the following example:

Input:              <db:InputParameters xmlns:db="…">                            <name>John Smith</name>               </db:InputParameters>Runtime Invocation:              BEGIN addEmployee (name=>?); END; // country => 'US'              orInput:              <db:InputParameters xmlns:db="…">                            <name>John Smith</name>                            <country>France</country>              </db:InputParameters>Runtime Invocation:              BEGIN addEmployee (name=>?, country=>?); END; // country => 'France'

The element in the XSD for parameters with a default clause is annotated with a special tag to indicate that the parameter has a default clause, as shown in the following example.

<element name=ÓcountryÓ … db:default=ÓtrueÓ …/>

This new functionality allows elements for parameters without a default clause also to be omitted in the instance XML. In these cases, the parameter is still included in the invocation of the stored procedure. A value of NULL is bound by default. The following is an example, where the country parameter did not have a default clause:

PROCEDURE addEmployee (name VARCHAR2, country VARCHAR2)

In prior release, BPEL PM 10.1.2, elements for both parameters were required in the instance XML. If an element was omitted, then it was presumed to have a default clause so the parameter would not be included in the invocation of the procedure. In this case, the missing parameter would result in a PL/SQL error stating that an incorrect number of arguments were passed to the procedure.

In the current BPEL PM release, the missing parameter will be included in the invocation of the procedure. A NULL value will be bound, as shown in the following example:

Input:               <db:InputParameters xmlns:db="…">               <name>John Smith</name>               </db:InputParameters>Runtime Invocation:               BEGIN addEmployee (name =>?, country=>?); END; // country => NULL

Even though the element for country was not provided in the instance XML, it still appears in the call to the procedure. In this case, country will be NULL.

PROCEDURE needsWrapper(isTrue BOOLEAN, value NUMBER DEFAULT 0)

TOPLEVEL$NEEDSWRAPPER (isTrue INTEGER, value NUMBER)

Input:        <db:InputParameters xmlns:db="…">        <isTrue>1</isTrue>        </db:InputParameters>Runtime Invocation:        BEGIN TOPLEVEL$NEEDSWRAPPER (isTrue =>?, value =>?); END; // value => NULL

Configuring the Invoke Activity

To configure the Invoke activity:

1. Drag Invoke from the Component palette and drop it at the location where you want to insert the invoke activity in your BPEL process, as shown in Figure 3-14.

   Figure 3-14 Dragging the Invoke Activity

   
   Description of "Figure 3-14 Dragging the Invoke Activity"
   
   

2. Double-click Invoke in the process map to open the Invoke dialog box. The General tab is selected by default. Figure 3-15 shows the Invoke dialog box.

   Figure 3-15 Configuring the Invoke Activity

   
   Description of "Figure 3-15 Configuring the Invoke Activity"
   
   

3. In the Partner Link box, select the partner link to invoke. This is the partner link that you configured in the previous section. The Operation is automatically selected.

4. Click the Create icon next to the Input Variable field. Enter a descriptive name for the variable in the Create Variable dialog box that appears. You can also accept the default name. Click OK. Figure 3-16 shows the Create Variable dialog box.

   Figure 3-16 Creating a Variable

   
   Description of "Figure 3-16 Creating a Variable"
   
   

5. Click the Create icon next to the Output Variable field. Enter a descriptive name for the variable in the Create Variable dialog box that appears. You can also accept the default name. Click OK.

6. In the Invoke dialog box, click Apply, and then click OK. The invoke activity is configured.

Configuring the Transform Activity

The Transform activity can be used to configure the parameters for the input and output variables. The Transform activity can also be used if variable values need to be transformed before updating them in Oracle Applications.

The following steps discuss configuring the Transform activity:

1. Drag and drop Transform into the process map window. The Transform activity should be placed in between Receive and Invoke. Figure 3-17 shows the process map window after the Transform activity has been added.

   Figure 3-17 Adding the Transform Activity

   
   Description of "Figure 3-17 Adding the Transform Activity"
   
   

2. Double-click Transform in the process map to open the Transform dialog box. The Transformation tab is selected by default. Figure 3-18 shows the Transform dialog box.

   Figure 3-18 Configuring the Transform Activity

   
   Description of "Figure 3-18 Configuring the Transform Activity"
   
   

3. Select the Source Variable and Target Variable from the respective boxes. Elements are mapped from the Source Variable to the Target Variable.

4. Select the Source Part of the variable from which to map elements. For example, the source part may be a payload schema consisting of a purchase order request.

5. Select the Target Part of the variable to which to map elements. For example, the target part may be a payload schema consisting of a purchase order acknowledgment.

6. Click the Create icon next to the Mapper File field to create a new transformation mapping file. Mapper File specifies the file in which you create the mappings using the XSLT Mapper Transformation tool.

7. The transformation mapping file is displayed. The Design view is displayed by default.

8. You can define the parameter values in the Design view. Drag a string function to the Design area. Connect the function to the appropriate parameter for which you want to define a value.

   
   

   Note: You can use an input parameter value from the source variable, transform it using a string function, and use it as the input parameter value for the target variable.

   
   

9. Double-click the icon for the function. The Edit Function dialog box is displayed. Figure 3-19 shows the Edit Function dialog box.

   Figure 3-19 Supplying the Function Parameters

   
   Description of "Figure 3-19 Supplying the Function Parameters"
   
   

10. Repeat steps 8 and 9 for all the parameters that you need to supply.