5 Working with Callouts

This chapter describes how to create and use Java callouts in Oracle SOA Suite for healthcare integration. Java callouts transform the formats of messages exchanged between the host and remote endpoints. You can use callouts to invoke an XSLT style sheet and any Java program in general.

This chapter contains the following topics:

• Section 5.1, "Introduction to Callouts"

• Section 5.2, "Types of Callouts"

• Section 5.3, "Creating a Callout"

• Section 5.4, "Including a Callout in an Endpoint"

5.1 Introduction to Callouts

Callouts are used in environments in which a host endpoint does not use the same message format as the remote trading partner. In addition, callouts are used to customize header information in messages.

5.1.1 Creating a Callout Library JAR File

If the callout JAR file provided with Oracle SOA Suite for healthcare integration is not sufficient for your needs, you can create your own callout JAR file outside of Oracle SOA Suite for healthcare integration, following the standards described in the Oracle Fusion Middleware B2B Callout Java API Reference. You can specify the directory location of this external JAR file in the Callout Directory field that you can access from the Runtime link under Settings in the Administration tab of the Oracle SOA Suite for healthcare integration user interface as shown in Figure 5-1. It is recommended that you create an external JAR file for your callouts; do not bundle your callouts with b2b.jar.

Figure 5-1 Specifying the Callout Directory

Description of "Figure 5-1 Specifying the Callout Directory"

Note:

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

5.2 Types of Callouts

Oracle SOA Suite for healthcare integration provides two types of callouts:

• Transport Callouts

• Document Callouts

5.2.1 Transport Callouts

A transport callout is associated with an endpoint. For the inbound message, Oracle SOA Suite for healthcare integration invokes the transport callout immediately after it receives a message from the remote endpoint. For the outbound message, Oracle SOA Suite for healthcare integration invokes the transport callout immediately before it sends a message to the remote endpoint. Transport callouts can be selected in the endpoint configuration, as shown in Figure 5-2, and can be used with any supported protocol such as generic TCP and MLLP 1.0.

Figure 5-2 Transport Callouts

Description of "Figure 5-2 Transport Callouts"

You can use transport callouts to extract transport custom headers for inbound messages and set transport headers for outbound messages. Example 5-1 shows how to set and get the CUSTOM_HEADER property in the callout.

Example 5-1 Setting and Getting the CUSTOM_HEADER Property

import java.util.*;
import oracle.tip.b2b.callout.*;
import oracle.tip.b2b.callout.exception.*;

   public class SampleCallout implements Callout {
   public void execute(CalloutContext context,List input,List output)
               throws CalloutDomainException, CalloutSystemException {
     try {
      CalloutMessage cmIn = (CalloutMessage)input.get(0);
      String s =cmIn.getBodyAsString();

      //for getting the CUSTOM_HEADER
      Properties params =  (Properties)cmIn.getParameters();
      String customHeader = (String)params.get("CUSTOM_HEADER");

      //for setting the CUSTOM_HEADER
      CalloutMessage cmOut = new CalloutMessage(s);
      cmOut.setParameter("CUSTOM_HEADER", "your_value");
      output.add(cmOut);

      } catch (Exception e) {
      throw new CalloutDomainException(e);
      }
   }
}

See "Using a Transport Callout to Extract Custom Headers" in Oracle Fusion Middleware User's Guide for Oracle B2B for more information.

Transport callouts are created from the Configuration tab under Designer, as described in Section 5.3, "Creating a Callout." All transport callouts appear both in the Transport Callout list and in the Document Callout list in an endpoint page; therefore, it is available for selection. To avoid confusion, when you create a transport callout, provide a name that indicates its type so that you do not select it from the Document Callout list.

5.2.2 Document Callouts

Document callouts are used to enable communication between endpoints that do not use the same message format. For example, a remote endpoint sends a HL7 2.3.1 XML-formatted message to a host endpoint. The host endpoint uses HL7 2.5 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 remote message into a format understood by the host endpoint. The host endpoint, in turn, responds to the request message with a order acceptance message in HL7 2.5 XML format.

• The other callout, callout_outbound, for example, transforms the HL7 2.5 XML format back into an HL7 2.3.1 XML-formatted message for the remote endpoint.

These two callouts are then associated with the two endpoints, as follows:

• Associate callout_outbound in the endpoint for the outbound message, which is, the endpoint for the initiating message request.

• Associate callout_inbound in the endpoint for the inbound message, which is, the endpoint for the responding message acceptance.

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

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

5.3 Creating a Callout

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

Note:

To create a callout from an external callout library JAR file, see Section 5.1.1, "Creating a Callout Library JAR File."

Figure 5-3 Creating a Callout

Description of "Figure 5-3 Creating a Callout"

To create a callout:

1. Log on to the Oracle SOA Suite for healthcare integration user interface.

2. Click the Designer tab, Configuration, and then Callout.

3. Click the Create icon (the plus sign) to display the Create Callout dialog box.

4. Enter a name for the callout.

   (You may want to indicate if you are creating a transport callout in the name.)

5. Enter callout details, as described in Table 5-1.

6. Click OK.

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

Table 5-1 Callout Details

Field	Description
JAR file name	Select the library name that contains 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 Runtime link under Settings from the Administration link. The directory location for the default b2b.jar file included with Oracle Healthcare does not need to be specified. The callout library must be manually migrated from one environment to another. The Oracle SOA Suite for healthcare integration export/import feature does not migrate the callout library JAR.
Implementation Class	Select the implementation class name. Note: Oracle SOA Suite for healthcare integration includes a predefined class file named XSLTCalloutImpl that you can use for XML-to-XML transformations.

Note:

You cannot delete a callout that is included in an endpoint.

After creating the callout, you can configure it by specifying the timeout value and optional parameters as shown in Figure 5-4.

Figure 5-4 Configuring Callouts

Description of "Figure 5-4 Configuring Callouts"

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 endpoints that use that callout.

Table 5-2 lists the optional callout parameter attributes.

Table 5-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 endpoint. See Section 5.4, "Including a Callout in an Endpoint," for more information. If you change a callout after it is deployed with an endpoint, a server restart is required.

5.4 Including a Callout in an Endpoint

After you create a callout, it is available to include in an endpoint.

To include a callout in an endpoint:

1. From the Configuration tab, double-click an endpoint to open it.

2. Depending on the type of message (inbound or outbound), select the callout name from the Document Callout list under the Send or Receive section. as shown in Figure 5-5.

   Figure 5-5 Associating a Callout with an Endpoint

   
   Description of "Figure 5-5 Associating a Callout with an Endpoint"
   
   

3. Click Apply.