Introduction
In a joint partnership with SAP, Itemfield provides the so called SAP Conversion Agent by Itemfield. It enables data conversions from unstructured and semi-structured data formats into XML, e.g. from ASCII, EBCDIC, MS Word, MS Excel, PDF, HL7, EDIFACT etc.
The Conversion Agent consists of the Conversion Agent Studio, and the Conversion Agent Engine. Former one is for designing and configuring transformations that can consist of parsers, serializers, mappers, or transformers. Once your tranformation is done, you deploy it as a Conversion Agent service. The services are run by the Conversion Agent Engine what is the runtime environment of the Conversion Agent system.
In general, there are two possibilities to integrate the SAP Conversion Agent with SAP XI, either by a module within the SAP XI Adapter Framework, or via the Conversion Agent Java API. Both approaches are shown here.
Prerequisites
The SAP Conversion Agent by Itemfield has been shipped since SAP XI3.0 SP14. For a complete list of platforms that are supported, please refer to SAP Note 894815.
However, the Java API should be supported prior to SAP XI3.0 SP14.
How to integrate using SAP XI Adapter Framework Module
After you deployed your transformation as service, you can call it from a module within any adapter that runs on top of the SAP XI Adapter Framework. You can call the service either at sender or receiver side.
In the SAP XI Integration Directory, create a communication channel, choose an adapter type, and maintain the appropriate parameters. Change to tab Module to define a local Enterprise Bean. Maintain localejbs/sap.com/com.sap.nw.cm.xi/CMTransformBean as module name, and set the parameter TransformationName to the service that you deployed.
How to integrate using Conversion Agent Java API
Let's assume you need to call the transformation service while sending a message to XI. Furthermore, you intend to use a transport protocol that does not require a sender agreement, or strictly speaking does not allow to maintain a module within a sender communication channel, e.g. when using plain http or XI protocol. In that case, the module approach above can't be applied.
Alternatively, you can call the transformation service within a mapping via the Conversion Agent Java API. The Java API is exposed by the CM_JavaApi.sda J2EE library as part of the SAP Conversion Agent software package, see below.
Define a Java class that implements the Java interface com.sap.aii.mapping.api.StreamTransformation. It contains two methods: public void execute to run the mapping, and public void setParameter to access message header data during runtime. Import packages com.sap.aii.mapping.api, and com.itemfield.contentmaster. Call the transformation service by establishing a Conversion Agent parser engine session, as shown in the code below.
package com.sap.rig.apa; import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; import java.util.Map; import com.itemfield.contentmaster.*; import com.sap.aii.mapping.api.*; public class callConversionAgent implements StreamTransformation { private Map myParam; public void setParameter(Map param) { myParam = param; } public void execute(InputStream in, OutputStream out) throws StreamTransformationException { // get header data String senderInterface = (String)myParam.get(StreamTransformationConstants.INTERFACE); // get CA service name String caService = new String(); if (senderInterface.equalsIgnoreCase("account_detail_req_ob")) { caService = "EBCDIC2XML"; else if (senderInterface.equalsIgnoreCase("account_detail_resp_ob")) { caService = "XML2EBCDIC"; } byte[] inbyte = null; try { // convert InputStream into byte stream int bufsize = in.available(); inbyte = new byte[bufsize]; in.read(inbyte); // convert byte stream into InputBuffer InputBuffer inbuf = new InputBuffer(inbyte); OutputBuffer outbuf = new OutputBuffer(); // build the CA parser engine session ParserEngineSession session = new ParserEngineSession(caService, inbuf, outbuf); try { session.exec(); } // convert OutputBuffer into byte stream byte[] outbyte = outbuf.toByteArray(); // convert byte stream into OutputStream out.write(outbyte); } } }
------------------------------------------------------------------------------------------------------------------------------------
package com.sap.rig.apa;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.Map;
import com.itemfield.contentmaster.*;
import com.sap.aii.mapping.api.*;
public class callConversionAgent implements StreamTransformation {
private Map myParam;
public void setParameter(Map param) {
myParam = param;
}
public void execute(InputStream in, OutputStream out)
throws StreamTransformationException {
// get header data
String senderInterface = (String)myParam.get(StreamTransformationConstants.INTERFACE);
// get CA service name
String caService = new String();
if (senderInterface.equalsIgnoreCase("account_detail_req_ob")) {
caService = "EBCDIC2XML";
else if (senderInterface.equalsIgnoreCase("account_detail_resp_ob")) {
caService = "XML2EBCDIC";
}
byte[] inbyte = null;
try {
// convert InputStream into byte stream
int bufsize = in.available();
inbyte = new byte[bufsize];
in.read(inbyte);
// convert byte stream into InputBuffer
InputBuffer inbuf = new InputBuffer(inbyte);
OutputBuffer outbuf = new OutputBuffer();
// build the CA parser engine session
ParserEngineSession session = new ParserEngineSession(caService, inbuf, outbuf);
try {
session.exec();
}
// convert OutputBuffer into byte stream
byte[] outbyte = outbuf.toByteArray();
// convert byte stream into OutputStream
out.write(outbyte);
}
}
}
------------------------------------------------------------------------------------------------------------------------------------
Create a .jar, and import the same to the Integration Repository.
Create an Interface Mapping, and choose the appropriate Java Class as mapping program.
For more details about the SAP Conversion Agent including installation guidelines, please refer to SAP Service Marketplace, and navigate to → Media Library → Documentation → Conversion Agent Documentation. The SAP Conversion Agent software can be downloaded under SAP Software Distribution Center → Download → Support Packages and Patches → Entry by Application Group → SAP NetWeaver → SAP NETWEAVER → SAP NETWEAVER 04 → Entry by Component → Process Integration (PI/XI) → NW 04 CONVERSION AGENT 1.0.
