Architektur

How to use Oracle MFT Callouts

Oracle Managed File Transfer (MFT) provides several functionalities aimed to manage and coordinate the transfer of files in a SOA environment. A file transfer in MFT involves three elements: a source, a target and a transfer. The source is the entity from which the file originates and the target is the destination of the file. The transfer defines the transmission of a file between a source and one or multiple targets. Similar as with B2B, MFT allows the definition of custom actions – also called callouts – that can be executed during the transfer flow. These custom actions can be defined at the source and will be executed right after the file is received and processed by MFT. They can also be defined at the transfer and will be executed before sending the file to the target or after the target received the file successfully. The following example will show how to define source and transfer processing actions. Here is a list of the steps that are required in order to implement an MFT callout:

  • Callout development
  • Callout definition file
  • Callout registration
  • Callout attachment

Callout development

As mentioned above, callouts can be defined at three different stages. The first stage is right after the file is received in MFT. This type of callouts are attached directly to the MFT source. The second stage is right before sending the file to the target and the third stage is when the message was transferred to the target. This last two type of callouts are attached to the MFT transfer component. Figure 1 shows these callouts in the transfer process.

MFT Callouts

Figure 1: Callouts

The source processing callout and the target pre-processing callout have to implement the PreCalloutPlugin interface whereas the target post-processing callout has to implement the PostCalloutPlugin. The main difference between these two interfaces is that the PreCalloutPlugin defines methods that can be overridden in order to alter the contents of the file being transferred while the PostCalloutPlugin only provides read access to the message.

There are three libraries (jar files) that need to be referenced in order to compile and execute the callouts: oracle.mft.client.jar, oracle.mft.bc.jar and Core-12.1.1.0.jar. These libraries can be found inside the <MFT_HOME>/modules directory.

Accessing the message requires different objects depending on the type of the callout. The source processing action can access the message by casting it to an oracle.tip.mft.bean.SourceMessage. Target pre-transfer callouts need to cast the message to oracle.tip.mft.bean.Instance and Post-transfer callout need to cast the message to a oracle.tip.mft.bean.TargetMessage. All this objects implement the MFTMessage interface that provides access to the metadata values of the message. Here are some samples that show how to access the message at the different stages:

Source processing action:
  • public PluginOutput process(PluginContext pluginContext, InputStream inputStream, Map<String, String> map) {
    • String directory= pluginContext.getCustomPropertyMap().get(„directory.path“);
    • String correlationFlowId= pluginContext.getCustomPropertyMap().get(„correlationFlowId“);
    • String eCID= pluginContext.getCustomPropertyMap().get(„ECID“);
    • SourceMessage message= (SourceMessage)pluginContext.getMessage();
    • String sourceName=message.getSourceName();
    • String contentIdentifier=message.getContentIdentifier();
    • String docType=message.getDocumentType();
    • String fileName=message.getFileName();
    • String senderUserName=message.getSenderUserName();
    • String sourceEndpointRef=message.getSourceEndpointRef();
    • String sourceType=message.getSourceType().toString();
    • return new PluginOutput();
  • }
Target pre-processing action:
  • public PluginOutput process(PluginContext pluginContext, InputStream inputStream, Map<String, String> map) {
    • String directory= pluginContext.getCustomPropertyMap().get(„directory.path „);
    • String correlationFlowId= pluginContext.getCustomPropertyMap().get(„correlationFlowId“);
    • String transformedFileName= pluginContext.getCustomPropertyMap().get(„transformedTargetFileName „);
    • String eCID= pluginContext.getCustomPropertyMap().get(„ECID“);
    • Instance message= (Instance)pluginContext.getMessage();
    • System.out.println(message.getTargetName());
    • return new PluginOutput();
  • }
Target post-processing action:
  • public void process(PluginContext pluginContext, InputStream inputStream, Map<String, String> map) throws Exception {
    • pluginContext.getCustomPropertyMap().entrySet();
    • TargetMessage message= (TargetMessage)pluginContext.getMessage();
    • String targetName=message.getTargetName();
    • String protocol=message.getProtocol();
    • String fileName=message.getFileName();
    • String senderUserName=message.getSenderUserName();
    • String targetLabel=message.getTargetLabel();
    • String targetRefID=message.getTargetRefId();
    • String directory= pluginContext.getCustomPropertyMap().get(„directory.path „);
    • String correlationFlowId= pluginContext.getCustomPropertyMap().get(„correlationFlowId“);
    • String transformedFileName= pluginContext.getCustomPropertyMap().get(„transformedTargetFileName „);
    • String eCID= pluginContext.getCustomPropertyMap().get(„ECID“);
  • }

Callouts have to be packed in a jar file and copied into the callout destination folder. The default location of the folder is <DOMAIN_HOME>/mft/callouts. A jar can contain one or several callouts.

Callout definition file

Callouts are deployed into the MFT server by using a callout descriptor file. This file is an xml that defines the kind of callouts being deployed and their respective location.

Sample:
  • <?xml version=“1.0″ encoding=“UTF-8″?>
    • <mft:Callouts xmlns:mft=“http://xmlns.oracle.com/mft“ xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance“ xsi:schemaLocation=“http://xmlns.oracle.com/mftcallout.xsd „>
      • <mft:Callout description=“Pre transfer event generator“ helpText=“Pre transfer event generator“ groupName=“Source-pre“ timeout=“300″ implementationClass=“de.esentri.samples.mft.callouts.PreTransferEventSender“ libraryName=“pretransferCallout.jar“ name=“Pre transfer event generator“> </mft:Callout>
      • <mft:Callout description=“Pre transfer event generator“ helpText=“Pre transfer event generator“ groupName=“Source-pre“ timeout=“300″ implementationClass=“de.esentri.samples.mft.callouts.PreTransferEventSender“ libraryName=“pretransferCallout.jar“ name=“Pre transfer event generator“> </mft:Callout>
      • <mft:Callout description=“ pre transfer event generator“ helpText=“pre transfer event generator“ groupName=“Target-pre“ timeout=“300″ implementationClass=“de.esentri.samples.mft.callouts.PrePostTransferCallout“ libraryName=“preposttransfercallout.jar“ name=“pre transfer event generator“> </mft:Callout>
    • </mft:Callouts>

Callout registration

Callouts are installed into the MFT server by using WLST. Following steps show how to install the callouts. It is important to mention that jar(s) containing the callouts has to be copied into the MFT (as mentioned in step 1) before installing the callout.

  • cd <MFT_HOME>/common/bin
  • . ./setWlstEnv.sh
  • ./wlst.sh
  • wls:/offline> connect(‚weblogic‘,’welcome1′,’t3://localhost:7001′)
  • wls:/base_domain/serverConfig> crtCalls(‚/tmp/myCalloutDefinitionFile.xml) //myCalloutDefinitionFile.xml was the file defined in section 2

Callout attachment

Now that the callouts are registered in the MFT server, they can be attached to a source or to a transfer, depending on the “group” name that was used in the callout definition file. Callouts are attached using the MFT console

MFT Callouts: Sender

Figure 2: attaching the callout to a sender

MFT Callouts: transfer

Figure 3: Attaching callouts to the transfer

Bonus track: listing and deleting Callouts

MFT provides other WLST functions that can help administering the Callouts.

With listCallouts it is possible to list the actual active callouts:

wls:/base_domain/serverConfig> listCallouts()

The function deleteCallout, deletes a specific callout giving that it is not currently associated to a source or a transfer. Sample

deleteCallout(‚Post transfer event generator‘). It is important to mention that callouts that are currently active cannot be deleted. They have to be detached first in order to be eliminated from MFT.

References

http://docs.oracle.com/middleware/1213/mft/MFTUG/mftug_exts.htm#MFTUG670