12 Managing Callouts

This chapter describes how to create and use Java callouts, which transform the formats of messages exchanged between the host and remote trading partners. You can use callouts to invoke an XSLT style sheet, and any Java program in general.

This chapter contains the following topics:

Introduction to Callouts
Creating a Callout
Including a Callout in an Agreement
Implementing a Callout

12.1 Introduction to Callouts

Callouts are used in environments in which a host trading partner application does not use the same message format as the remote trading partner. For example, a remote trading partner sends a RosettaNet XML-formatted purchase order request to a host trading partner, as shown in Figure 12-1.

Figure 12-1 A Purchase Order Example: Using Callouts for Differently Formatted XML Messages

Description of "Figure 12-1 A Purchase Order Example: Using Callouts for Differently Formatted XML Messages"

In this example, the host application of the host trading partner is an Oracle E-Business Suite application that does not use RosettaNet XML-formatted messages. To enable communication between these two different formats, you create two callouts, as follows:

One callout, callout_inbound, for example, transforms the RosettaNet XML-formatted purchase order request into an Oracle E-Business Suite XML format understood by the Oracle E-Business Suite application. The Oracle E-Business Suite application, in turn, responds to the request message with a purchase order acceptance message in Oracle E-Business Suite XML format.
The other callout, callout_outbound, for example, transforms the Oracle E-Business Suite XML format back into a RosettaNet XML-formatted message for the remote trading partner.

These two callouts are then associated with the two agreements created for this exchange, as follows:

Include callout_outbound in the agreement for the outbound message, that is, the agreement for the initiating purchase order request.
Include callout_inbound in the agreement for the inbound message, that is, the agreement for the responding purchase order acceptance.

Because a document definition is a component of an agreement, a callout is associated with a specific document definition.

This purchase order example depicts a simple association of one callout to one agreement. In reality, however, the same callout can be included in many different agreements by changing the value of one or more callout parameters. See Figure 12-2 for where you add parameters and Table 12-2 for a list of parameter attributes.

12.1.1 Creating a Callout Library JAR File

If the callout JAR file provided with Oracle B2B is not sufficient for your needs, you can create your own callout JAR file outside of Oracle B2B, following the standards described in the Oracle Fusion Middleware B2B Callout Java API Reference. Use the Configuration tab of the Administration link to specify the directory location of this external JAR file. It is recommended that you create an external JAR file for your callouts; do not bundle your callouts with b2b.jar.

Note:

MySampleCallout is a restricted keyword and should not be used. It is already packaged into b2b.jar.

12.2 Creating a Callout

To create a callout, provide callout details—the implementation class name and library name—and callout parameters, as shown in Figure 12-2.

Figure 12-2 Creating a Callout

Description of "Figure 12-2 Creating a Callout"

You can create multiple callouts with the same name if you assign them different implementation names. You cannot delete a callout that is included in an agreement.

Table 12-1 lists the callout details that you provide.

Table 12-1 Callout Details

Field	Description
*Implementation Class	Enter the class file name without `.class`. Note: Oracle B2B includes a predefined class file named XSLTCalloutImpl that you can use for XML-to-XML transformations.
*Library Name	Enter the JAR file name that has the callout implementation classes. Note: If you specify one or more of your own callout JAR files, you must specify the directory location. Use the Configuration tab from the Administration link. The directory location for the default `b2b.jar` file included with Oracle B2B does not need to be specified. See "Setting Configuration Parameters" for information on specifying the callout directory for your own callout JAR files. Description of the illustration bb_calloutdir1.gif
Description	Enter a description.
Timeout (seconds)	Enter the time limit in which to process the callout.

Callout parameters are similar in concept to global variables to which you can assign local values that are applicable only to a specific callout use. Or, you can create a callout parameter and assign it a default value that is applicable to all callout uses. Changes to callout parameters for an existing callout affect all agreements that use that callout.

Table 12-2 lists the optional callout parameter attributes.

Table 12-2 Callout Parameter Attributes

Field	Description
Name	Enter a parameter name.
Type	Select from Integer, Float, String, Boolean, or Date types. The format for the Date type is MM/DD/YYYY. Note: Changing a type can invalidate the parameter default value.
Value	Enter a value. If Encrypted is set to True, then this value is encrypted.
Mandatory	Select True or False.
Encrypted	Select True or False.
Description	Enter an optional description.

After you create a callout, it is available to include in an agreement. See "Including a Callout in an Agreement" for more information. If you change a callout after it is deployed with an agreement, a server restart is required.

To create a callout:

Click Administration, and then Callout.
In the Callout section, click Add.
Enter a name for the callout.
Enter callout details, as described in Table 12-1.
(Optional) Click Add in the Parameters section.
Enter a parameter name and attributes, as described in Table 12-2.
Click Save.

You can edit the details, parameters, or parameter values at any time, but not the callout name.

12.3 Including a Callout in an Agreement

After you create a callout, it is available to include in an agreement, as shown in Figure 12-3.

Figure 12-3 Specifying a Callout in an Agreement

Description of "Figure 12-3 Specifying a Callout in an Agreement"

To include a callout in an agreement:

Click Partners.
Click an agreement name.
Select a callout.
Click Save.

To update the value of a callout parameter for a specific agreement:

Click Partners.
Click an agreement name.
Select a callout.
Click Callout Details.
Enter a value for the parameter name.

Description of the illustration bb_callouts3.gif
Click OK.

12.4 Implementing a Callout

Example 12-1 shows how an incoming XML document is transformed to another XML document. The directory structure is oracle.tip.callout.

Example 12-1 Code Example of an XML-to-XML Transformation

import java.io.*;
import java.net.*;
import java.util.*;
import oracle.xml.parser.v2.*;
import oracle.tip.b2b.callout.Callout;
import oracle.tip.b2b.callout.CalloutMessage;
import oracle.tip.b2b.callout.CalloutContext;
import oracle.tip.b2b.callout.exception.*;
 
/**
 * This sample callout transforms the incoming XML document
 * to another XML document. It also shows how to generate
 * Functional Ack and Error message.
 */
public class XSLTCalloutImpl implements Callout {  
   public void execute(CalloutContext context,
                       List input,
                       List output)
               throws CalloutDomainException, CalloutSystemException {
     try {
 
      // (1) Retrieve the callout properties from CalloutContext
      String xsltFile     = context.getStringProperty("xsltFile");
 
      // (2) Get the input callout message
      CalloutMessage cmIn = (CalloutMessage)input.get(0);
 
      // (3) Process the message
      // instantiate a stylesheet
      URL xslURL = new URL("file://" + xsltFile);     
      XSLProcessor processor = new XSLProcessor();
      XSLStylesheet xsl = processor.newXSLStylesheet(xslURL);
 
      // parser input XML content
      DOMParser parser = new DOMParser();
      parser.setPreserveWhitespace(true);  
      parser.parse(new StringReader(cmIn.getBodyAsString()));
      XMLDocument xml = parser.getDocument();
      processor.showWarnings(true);
      processor.setErrorStream(System.err);
 
      // Transform the document
      StringWriter strWriter = new  StringWriter();
      processor.processXSL(xsl, xml, new PrintWriter(strWriter));
 
      // (4) Create a output callout message
      // create a callout output message
      CalloutMessage cmOut =
          new CalloutMessage(strWriter.getBuffer().toString());
      strWriter.close();
 
// create Functional Ack callout message
// this is an optional step
CalloutMessage fa = new CalloutMessage(/*set FA payload here*/);
fa.setParameter("functional_ack", "true");
//setting your own doctype and revision
//set the doc type name and revision as defined in b2b ui
fa.setParameter("doctype_name", "fa");
fa.setParameter("doctype_revision", "1.0");
 
// create Error callout message
// this is an optional step
CalloutMessage err = new CalloutMessage(/* set the payload that causes this
error */);
err.setParameter("error_message", "true");
err.setParameter("error_desc", "set the error desc");

      output.add(cmOut);
      output.add(fa);
      output.add(err);

      //(5) Throw an exception, if any
    } catch (Exception e) {
      throw new CalloutDomainException(e);
    }
  }
}