5 Working with Callouts

This chapter describes how to create and use Java callouts in Oracle SOA Suite for healthcare integration. Oracle SOA Suite for healthcare integration provides most functionality required to build healthcare composites using various configurations available in the Oracle Healthcare console. However, you can use Java callouts to extend configurations, or add additional functionality written in Java. For example, you can use Java callout to programmatically handle non-standard delimiters in HL7 messages. Java callouts can also be used to write PGP Encryption/Decryption logic.

This chapter contains the following topics:

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 follows
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.

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.

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

Example - 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);
      }
   }
}

Transport callouts can also be used for PGP encryption and decryption. The Java callout can encrypt HL7 messages being sent to an external system or endpoint. On the receiver side, a Java callout can decrypt the received data.

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 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.

Document callouts can also be used to handle non-standard delimiters in HL7 messages. For example, if the receiver system sends HL7 messages using a non-standard "^" as a delimiter instead of the "|" that the healthcare composite expects, you can write a Java callout that converts the non-standard delimiters to standard delimiters.

5.3 Creating a Callout

To create a callout, provide callout details—the library name and the implementation class name—and callout parameters.

A callout is shown in Figure 5-4.

Note:

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

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 button (the plus sign) to display the Create Callout dialog box.
  4. Enter a name for the callout.

    (You might 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 need not 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 time-out value and optional parameters as shown in Figure 5-4.

Figure 5-4 Configuring Callouts

Description of Figure 5-4 follows
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 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 Securing Messages with PGP

Oracle B2B and Healthcare support message level security using PGP (Pretty Good Privacy). PGP combines features of both symmetric and public key cryptography. PGP creates a session key which is a onetime only, randomly-generated key for the text. The session key encrypts the plain text, and then the session key is then encrypted to the recipient’s public key. Decryption works in reverse.

You can use this functionality as a transport callout only in B2B and Healthcare, using the PGP callout jar provided. You must have the capability to create PGP keys.

Usage Scenario

Inbound: Oracle B2B/Healthcare receives Encrypted PGP messages from an external trading partner. As part of the message processing, the encrypted PGP message will be decrypted using the enterprise’s Private key. In case the PGP encrypted message contains the digital signature, the digital signature will be verified using the sender’s public key. Also, in case the PGP encrypted message contains the message digest, then as part of decryption, data integrity will be verified.

Outbound: Oracle B2B/Healthcare sends encrypted PGP messages to an external trading partner. As part of the processing, the message will be encrypted using PGP api’s using the external trading partner’s public key. During encryption, enterprise has the option to add the digital signature for message origin authentication and message digest for integrity check. For message signature, the Enterprise’s private key will be used.

Callout Parameters

The PGP callout needs the following callout parameters while configuring the callout:

  • publicKeyLocation

  • secretKeyLocation

  • password

  • direction

  • encryptionType

EncryptionType is used to specify the type of algorithm used for encryption. The table below lists the supported types and the integer values that must be provided to the callout. For example, to use the AES_256 algorithm, the callout parameter value for encryptionType would be 9.

EncryptionType Integer value

TRIPLE_DES

2

CAST5

3

BLOWFISH

4

DES

6

AES_128

7

AES_192

8

AES_256

9

TWOFISH

10

Figure 5-5 PGP Callout Parameters

Description of Figure 5-5 follows
Description of "Figure 5-5 PGP Callout Parameters"

5.5 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-6.

    Figure 5-6 Associating a Callout with an Endpoint

    Description of Figure 5-6 follows
    Description of "Figure 5-6 Associating a Callout with an Endpoint"
  3. Click Apply.