sap conversion agent by itemfield...sap conversion agent by itemfield deploying and using conversion...

SAP Conversion Agent byItemfield

Deploying and UsingConversion Agent

Conversion Agent 4

Legal Notice

Deploying and Using Conversion Agent

Copyright © 2005-2006 Itemfield Inc. All rights reserved.

Itemfield may have patents, patent applications, trademarks, copyrights, or other intellectual propertyrights covering subject matter in this document. Except as expressly provided in any written licenseagreement from Itemfield, the furnishing of this document does not give you any license to thesepatents, trademarks, copyrights, or other intellectual property.

The information in this document is subject to change without notice. Complying with all applicablecopyright laws is the responsibility of the user. No part of this document may be reproduced ortransmitted in any form or by any means, electronic or mechanical, for any purpose, without theexpress written permission of Itemfield Inc.

SAP AGhttp://www.sap.com

Publication Information:

Version: 4Date: September 2006


Contents

Overview ...............................................................................................1Conversion Agent Concepts ..................................................................................................................1How to Use Conversion Agent in SAP XI.............................................................................................. 2Usage Scenarios ................................................................................................................................... 3

Single Computer.............................................................................................................................. 3Separate Development Computer and Production Servers ............................................................ 3

Deploying Conversion Agent...............................................................4System Requirements ........................................................................................................................... 4Deployment Procedure .......................................................................................................................... 5Installing Conversion Agent without SAP XI or PCK ............................................................................. 8Testing the Conversion Agent Installation .............................................................................................8

Using Conversion Agent in SAP XI .....................................................9Configuring Data Transformations in Conversion Agent ....................................................................... 9

Procedure for Deploying Conversion Agent Services ..................................................................... 9Configuring a SAP XI Communication Channel ..................................................................................10

Calling the Conversion Agent Java API............................................11

Remote Support Interface..................................................................11Using the Remote Support Interface ................................................................................................... 12Limiting the Download Size of the Event Log ......................................................................................12

Accessibility Features........................................................................13Creating a Data Transformation .......................................................................................................... 13Deploying a Conversion Agent Service ............................................................................................... 14Running a Conversion Agent Service..................................................................................................15


1

Overview

Conversion Agent provides powerful data transformation capabilities to SAPNetWeaver and seamlessly integrates into SAP XI.: SAP XI integration"

You can use Conversion Agent to transform data from any format to any otherformat. The Conversion Agent process module integrates into the SAP XI AdapterFramework (SAP XI AF) and with the SAP NetWeaver partner connectivity kit(PCK). It lets you use the data-transformation capabilities within any adaptersupplied with SXP XI or PCK.

This document explains how to install Conversion Agent within SAP NetWeaverand how to use Conversion Agent data transformations in SAP XI or PCK.

For brevity, this document refers mainly to SAP XI. With minor variations, theinstructions apply also to PCK.

Conversion Agent Concepts

This section introduces, very briefly, some of the Conversion Agent concepts andterms that are used in this book. For a complete introduction, please see the bookGetting Started with Conversion Agent.

Types of Data TransformationsConversion Agent supports four main types of data transformations:

Parsers, which convert any data format to XML

Serializers, which convert XML to any format

Mappers, which converts XML to XML

Transformers, which modify the data in any format

For example, you can use a Conversion Agent parser to transform binary or textinputs to XML. The inputs can contain structured, semi-structured, or unstructureddata.

Similarly, you can use a Conversion Agent serializer to transform XML to otherdata formats. By combining a parser and a serializer, you can use ConversionAgent to transform any data format to any other data format, via XML.


2

Conversion Agent Architecture

Conversion Agent has three main software components:

Conversion Agent Studio is the design environment, where you can configuredata transformations.

Conversion Agent Engine is the runtime environment, where the datatransformations are executed.

The Conversion Agent process module integrates into SAP XI or PCK. The processmodule activates Conversion Agent Engine, letting you run datatransformations within XI or PCK adapters.

In addition to these components, there are many optional components, such as:

Libraries, which contain predefined parsers, serializers, and schemas forworking with standard communication and messaging protocols.

Document processors, which you can use to preprocess the input data prior to adata transformation.

Conversion Agent ServicesAfter you configure a data transformation in Conversion Agent Studio, you candeploy it as a Conversion Agent service. This lets Conversion Agent Engine accessthe data transformation and execute it."

Below in this book, we describe two ways to run Conversion Agent services:

By using the Conversion Agent process module for SAP XI (see UsingConversion Agent in SAP XI)

By calling the Conversion Agent Java API (see Calling the Conversion Agent JavaAPI)

In the Conversion Agent Engine Developer's Guide, you can learn about several otherways to run the services, such as:

By using the CM_console command-line interface

By calling the COM, C, or C++ APIs

By using the Conversion Agent CGI interface

How to Use Conversion Agent in SAP XI

The basic procedure for integrating Conversion Agent with SAP XI is as follows:

1. Deploy Conversion Agent in SAP NetWeaver and install the ConversionAgent software (see Deploying Conversion Agent below).

2. Use the Conversion Agent Studio development environment to create datatransformations such as parsers, serializers, mappers, or transformers.


3

To learn how to do this, we recommend that you read Getting Started withConversion Agent and perform the tutorial exercises. For detailed information,see the Conversion Agent Studio User's Guide.

3. In Conversion Agent Studio, deploy the data transformations as ConversionAgent services, which Conversion Agent Engine can run (see Procedure forDeploying Conversion Agent Services).

4. Configure and run SAP XI communication channels that use the ConversionAgent process module to run data transformations (see Using Conversion Agentin SAP XI below).

Usage Scenarios

You can use Conversion Agent:

On a single computer, where you develop and run data transformations

or

On separate development and production computers

The former scenario is suitable for relatively light use or non-critical applications.For large-scale, critical applications, the latter scenario is appropriate.

Single Computer

To use Conversion Agent on the same computer both to develop and to run datatransformations, you should configure the computer as follows:

Windows operating system

SAP XI server or SAP NetWeaver PCK

Conversion Agent Studio and Engine, installed on the computer and deployedin SAP NetWeaver (see Deployment Procedure)

This configuration lets you perform the following operations, all on the samecomputer:

Design and configure Conversion Agent data transformations

Test the data transformations within Conversion Agent

Deploy the data transformations as Conversion Agent services

Run the services in SAP XI or PCK

Separate Development Computer and Production Servers

If you plan to use separate development and production computers, follow theseguidelines.


4

Development Computer

The recommended development environment is identical to the Single Computer ,described above.

Alternatively, the development computer can be a Windows system where youinstall Conversion Agent Studio and Engine, omitting SAP XI or PCK. To test theConversion Agent services, you can deploy the services to another computerwhere SAP XI or PCK is installed.

Production ComputersAfter you develop and test a Conversion Agent service, you can deploy the servicefrom the development computer to one or more production servers. Each servershould be configured as follows:

Windows or a Unix-type operating system

SAP XI Server or PCK

Conversion Agent Engine, installed on the computer and deployed in SAPNetWeaver (see Deployment Procedure)

Conversion Agent Studio is not required on a production server (although you canoptionally install it if the server is Windows-based).

Deploying Conversion Agent

This section explains how to deploy Conversion Agent. You must do this onlyonce, before you can use Conversion Agent services.

System Requirements

Supported Operating Systems

You can install Conversion Agent Engine on the following operating systems:

Microsoft Windows

Unix-type systems:

- Sun Solaris- IBM AIX- SUSE or Red Hat Linux- Hewlett-Packard HP-UX


5

You can install Conversion Agent Studio only on Microsoft Windows.

For the detailed system requirements, see the Conversion Agent Administrator'sGuide.

Supported SAP Integration EnvironmentsTo use the Conversion Agent process module, you also need:

SAP XI or PCK, version SP14 or higher

Deployment Procedure

The following procedure deploys Conversion Agent on a computer that runs SAP XI orPCK. To deploy Conversion Agent on a development computer without SAP XI or PCK,see Installing Conversion Agent without SAP XI or PCK below.

Deploying in SAP NetWeaverTo deploy Conversion Agent in SAP NetWeaver, perform the following steps.

1. Open the SAP Software Deployment Manager (SDM) and connect to the SDMserver.

2. Display the Deployment tab of the SDM.

3. Click the button to Add SCA/SDA to Deployment List.

4. Browse to the directory where you have stored the Conversion Agentinstallation package.

5. Select the Conversion Agent *.sca file. The file has a name beginning withSAPNWCM, for example, SAPNWCMvv_v.sca (where vv_v is a version number).

6. Follow the on-screen instructions to complete the deployment. During thedeployment, you are prompted to restart the SAP J2EE Application Server.

Continue with the following steps, depending on your operating system.

Installing the Conversion Agent Software on Windows

If you are deploying on a Microsoft Windows platform, continue with thefollowing instructions:

1. Find the Conversion Agent setup file, Setup.exe. It is located in theConversion Agent subdirectory of the SAP XI repository, for example:

c:\usr\sap\J2E\SYS\global\Conversion Agent\Setup.exe

2. Double-click the setup file and follow the on-screen prompts to complete theinstallation. For detailed instructions, see the Conversion Agent Administrator'sGuide.


6

Note: You must select the option to install the Conversion Agent Engine component. The other components, such as the Conversion Agent Studio design and configuration environment, are optional.

3. To ensure that your configuration changes take effect, you must restart the SAP J2EE Application Server. To do this, open the SAP Management Console, and stop and start the instance node. Alternatively, open a command prompt and run the following commands:

startsap.exe name=<SID> nr=<SYSNR> SAPDIAHOST=<host> stopsap.exe name=<SID> nr=<SYSNR> SAPDIAHOST=<host>

For example:

stopsap.exe name=J2E nr=01 SAPDIAHOST=my_host startsap.exe name=J2E nr=01 SAPDIAHOST=my_host

Installing the Conversion Agent Software on Unix If you are deploying on a Unix-type platform, continue with the following instructions.

Throughout the instructions, we use <INSTALL_DIR> to symbolize the Conversion Agent installation path (by default, /opt/SAP/ConversionAgent). You should substitute your value of the path.

1. Find the Conversion Agent setup file. The file has a name such as Setup_uuu.bin, where uuu is the name of the Unix flavor. It is located in the Conversion Agent subdirectory of the SAP XI repository, for example:

/usr/sap/J2E/SYS/global/Conversion Agent/Setup_linux.bin

2. Follow the Unix instructions in the Conversion Agent Administrator's Guide to run the setup file and complete the installation.

Be sure to perform the required post-installation steps, such as modifying your profile to load the Conversion Agent environment variables, which are described in the Conversion Agent Administrator's Guide. In brief:

If you use the sh, ksh, or bash shell, insert the following line in your .profile file:

. /<INSTALL_DIR>/setEnv.sh

If you use the csh or tcsh shell, insert the following line in your .login file:

source /<INSTALL_DIR>/setEnv.csh

You should then log out and log in, to ensure that your revised profile goes into effect.

3. You can configure Conversion Agent Engine to run either in-process or out-of-process. The default is in-process.

For further information, or if you need to change the setting, see Running In-Process or Out-of-Process in the Conversion Agent Administrator's Guide.


7

4. On Linux 32-bit platforms: If Conversion Agent Engine is configured to run in-process (which is the default), you must configure the JRE that Conversion Agent uses to be the same as that of the SAP J2EE server. To do this:

a. Edit the setEnv.sh or setEnv.csh file (see step 2 above). b. Change the CMJAVA_PATH definition to the path of the JRE that the J2EE

server uses. c. Log out and log in, to ensure that your revised setEnv.* file takes effect.

For example, suppose the SAP J2EE server uses the following JRE:

/usr/j2sdk1.4.2_09/jre/lib/i386/server

In the setEnv.sh or setEnv.csh file, you should set:

CMJAVA_PATH="/usr/j2sdk1.4.2_09/jre/lib/i386/server:/usr/ j2sdk1.4.2_09/jre/lib/i386"

5. You must then edit your startsap file, inserting a line that configures the Conversion Agent environment variables in the SAP system. The startsap file is located in a directory such as:

usr/sap/J2E/SYS/exe/run

At the top of the file, find the line that reads

#!/bin/sh

and insert the following bold-italic line:

#!/bin/sh . /<INSTALL_DIR>/setEnv.sh

Note: Installing a SAP XI or PCK service release or patch may overwrite the startsap file. After you install a service release, you may need to re-edit startsap.

6. To ensure that the modified startsap takes effect, you must restart the SAP J2EE Application Server. To do this, open a command prompt and run the following commands:

stopsap J2EE startsap J2EE

Undeploying To undeploy Conversion Agent from SAP XI, use the Undeployment tab of the SAP Software Deployment Manager. Follow the on-screen instructions to undeploy the following components:

com.sap.nw.conversionagent com.sap.nw.cm.http


8

com.sap.nw.cm.j2eecom.sap.nw.cm.xi

You should then uninstall the Conversion Agent software from the computer. Forinstructions, see the Conversion Agent Administrator's Guide.

Installing Conversion Agent without SAP XI or PCK

Optionally, you can install Conversion Agent on a Windows-based developmentcomputer that does not run SAP XI or PCK (see the Usage Scenarios above). In thatcase, you can omit the full Deployment Procedure that is described above. Instead,you can install Conversion Agent as follows:

1. To obtain an appropriate setup file, browse to the SAP Conversion Agent byItemfield web site:

https://websmp105.sap-ag.de/~form/sapnet?_SHORTKEY=01100035870000669979&

2. Download the SAP Conversion Agent Studio Preview Version.

3. The download file is a self-extracting archive. Double-click the file to start theinstallation, and follow the on-screen instructions.

For details of the installation options, see the Conversion Agent Administrator'sGuide.

Testing the Conversion Agent Installation

To verify that Conversion Agent is installed correctly, you can perform thefollowing test:

1. Open a command prompt.

2. Enter the CM_console command, without any parameters.

3. CM_console should display a usage message such as the following:

Usage:CM_console Service name [Additional options]...

4. In the Conversion Agent setupTests subdirectory, there is a sample projectcalled TestCME. Copy the entire TestCME directory to the Conversion Agentrepository, which you defined during the setup (by default, the ConversionAgent ServiceDBdirectory). This makes TestCME available as a ConversionAgent service.

5. Enter the following command, which executes TestCME.

CM_console TestCME




9

The service performs a simple data transformation on a source document. Thefollowing result should be displayed:

<Result>Test Succeeded</Result>

For more information and troubleshooting instructions, see the Conversion AgentAdministrator's Guide.

Using Conversion Agent in SAP XI

After you deploy Conversion Agent, you are ready to run Conversion Agent datatransformations in SAP XI applications. There are two steps to do this:

1. In Conversion Agent Studio, configure a data transformation and deploy it asa Conversion Agent service.

2. In SAP XI, configure a communication channel, which contains an adapter thatuses the Conversion Agent process module. The process module runs theConversion Agent service.

Configuring Data Transformations in ConversionAgent

To configure and deploy a data transformation:

1. In Conversion Agent Studio, configure the data transformation that you wishto run. For instructions, see Getting Started with Conversion Agent and theConversion Agent Studio User's Guide.

2. Deploy the transformation as a Conversion Agent service. This letsConversion Agent Engine run the transformation (see Procedure for DeployingConversion Agent Services below).

Procedure for Deploying Conversion Agent Services

The first step in deploying a Conversion Agent service is to deploy to therepository on the Conversion Agent Studio computer. This lets the service run inConversion Agent Engine on the same computer.

There are some additional steps, which you must perform if you want to deploy tothe Conversion Agent repository on a remote computer. You should perform thesesteps, for example, if you want to run the service in SAP XI on a production server,where Conversion Agent Engine is installed but the Studio is not installed (seeUsage Scenarios above).


10

For additional information, see the chapter Deploying Conversion Agent Services inthe Conversion Agent Studio User's Guide.

Deploying on the Conversion Agent Studio Computer

To deploy a Conversion Agent service to the repository on the local computer:

1. Open the project in Conversion Agent Studio.

2. Choose the Project > Deploy command, and follow the on-screen instructions.

Deploying on a Remote Computer

To deploy a Conversion Agent service to the repository on a remote computer:

1. Deploy the service on the Conversion Agent Studio computer, as describedabove.

2. Copy the deployed project folder from the repository on the Conversion AgentStudio computer, to the repository on the remote computer.

You can determine the repository locations by opening the Conversion AgentConfiguration Editor. The path is in the setting:

CM Configuration/Directory services/File system/Base Path

The default location is the Conversion Agent ServiceDB subdirectory, on eachcomputer.

3. Conversion Agent Engine determines whether any services have been revisedby periodically examining (every 30 seconds) the timestamp of a file calledupdate.txt. This file exists in the repository root directory (by default, theServiceDB directory). The content of the file can be empty.

If this is the first time that you have deployed a service to the remoterepository, update.txt may not exist. If so, copy it from the local repository.

If update.txt exists, you should update its timestamp as follows.

On Windows: Open update.txt in Notepad and save it.

On Unix: Open a command prompt, change to the repository directory, andenter the following command.

touch update.txt

Re-Deploying

If you later edit the data transformation in Conversion Agent Studio, you mustdeploy it again by repeating the above procedure.

Configuring a SAP XI Communication Channel

To run a Conversion Agent service within a SAP XI communication channel:

1. Create a SAP XI scenario.


11

2. In the communication channel, define a CMTransformBean module (using itsJNDI name).

In the processing sequence, you must position CMTransformBean at the correctposition in the module chain. Usually, CMTransformBean should be thepenultimate module in the chain, for example, before CallSapAdapter. Thecorrect position may vary, depending on the adapter type and direction(sender or receiver channel).

For further information on where to position the module, browse tohttp://help.sap.com and display the Documentation tab. Follow the links to SAPNetWeaver > SAP NetWeaver '04 > English. In the documentation contents,expand the tree and display Process Integration > SAP ExchangeInfrastructure > Runtime > Connectivity > Adapters > Generic AdapterFunctions > Module Processor.

3. In the module configuration, set the TransformationName parameter to thename of a Conversion Agent service that you have deployed.

The input of the Conversion Agent service is the data supplied by the channel. Theservice sends its output back to the channel.

Please note that a communication channel can contain only a singleCMTransformBean.

Calling the Conversion Agent Java API

The CM_JavaApi.sda J2EE library exposes the Conversion Agent Java API. A SAPNetWeaver component can call the API to run Conversion Agent datatransformations.

For detailed information about the API, see the Conversion Agent Java API Referenceand the Conversion Agent Engine Developer's Guide.

Remote Support Interface

If Conversion Agent Engine encounters an error or failure while running a service,it generates an event log. You can view the event log in Conversion Agent Studioto diagnose the problem.

http://help.sap.com/


12

On SAP XI platforms, you can also use the remote support interface, which lets youview the event logs over an HTTP connection in a web browser. The display issimilar to that of Conversion Agent Studio. It lets you identify any errors thatoccurred and find the text that caused the errors in the input documents.

For more information about interpreting event logs, see the chapter on Testing andDebugging in the Conversion Agent Studio User's Guide. Also see the chapter EventLogs in the Conversion Agent Engine Developer's Guide.

Using the Remote Support Interface

To use the remote support interface:

1. In Microsoft Internet Explorer, version 6.0 or higher, browse to

http://HOST:PORT/CMViewer

where HOST is the host name or IP address where you installed the remotesupport interface, and PORT is the TCP port number. On NetWeaver 04, thePORT is 50<system_number>0. For example, if the server is callednw04.example.com and the SAP system number is 00, you should browse to

http://nw04.example.com:50000/CMViewer

2. On the home page, select one of the following options:

View Initialization EventsDisplays the Engine initialization log, which lets you diagnose installationproblems such as missing environment variables.

View Execution EventsDisplays the event log of a particular Conversion Agent service. Select thedate and the log.

3. The browser displays the log. You can click the view-source links to find thecause of the events in the source documents. For example, if you click on theview-source link of a Marker anchor, the remote support interface displays thesource document and highlights the Marker.

Limiting the Download Size of the Event Log

Event logs can be very large and can take a long time to download over a remoteconnection. In the Conversion Agent Configuration Editor, you can assign thefollowing parameters, which limit the download size and greatly improve theresponse time.

CM Configuration/Remote Support Interface/Event file size limitThe maximum log size in bytes.


13

If the event log exceeds this size, the remote support interface displays onlythe final portion of the log, where the error is most likely to be. The partial logdoes not contain view-source links. It may display some empty folders, whichyou can ignore.

CM Configuration/Remote Support Interface/Event file buffer sizeThe size of the final portion, in bytes.

This is the size that the remote support interface displays, if the event logexceeds the maximum file size.

CM Configuration/Remote Support Interface/Show Input SourceIf true, the display contains view-source links.

CM Configuration/Remote Support Interface/Source Fragment Buffer SizeThe maximum size of the source document display, in bytes.

If a source document exceeds this size, the remote support interface displaysonly a portion of the document, centered on the text that caused the event.

Accessibility Features

For the benefit of users who have visual disabilities, Conversion Agent providescommand-line and text-editor capabilities for:

Creating and editing a data transformation

Deploying a data transformation as a Conversion Agent service

Running a Conversion Agent service in Conversion Agent Engine

Creating a Data Transformation

As an alternative to using Conversion Agent Studio to create and configure datatransformations, you can perform these operations in a command-line editor or inany text editor.

Project Files

The following paragraphs describe the files that are required in most ConversionAgent projects. You can find sample projects, which illustrate the required files, inthe Conversion Agent tutorials\Solutions to Exercises directory.


14

CMW configuration fileThis is a text file, having a *.cmw extension, which contains the mainconfiguration information of a project. There is a single CMW file in eachproject. The file contains information such as:

The Conversion Agent syntax versionThe instance to execute (the startup component, which is defined in a TGP

file and which Conversion Agent should activate when it runs the project).The names of TGP and XSD files in the project.Other project properties, such as encoding and authorization information.

TGP script fileThis is a text file, having a *.tgp extension, where you can configure thecomponents that execute a data transformation. A project must contain at leastone TGP file.

For information about the components that you can insert in a TGP file, see theConversion Agent Studio User's Guide.

XSD schema fileThis is text file, having an *.xsd extension, which defines the XML structuresused in a data transformation. Parser, serializer, and mapper projects requireat least one XSD file.

Example source fileThis is a file having any format, which serves as an example of the documentsthat the data transformation will process. Most parser projects require anexample source file.

In addition to the above files, the project directory can contain test documents orany other desired files.

Deploying a Conversion Agent Service

After you configure a data transformation, you should deploy it as a ConversionAgent service. This allows the data transformation to run in Conversion AgentEngine.

As an alternative to deploying a service in Conversion Agent Studio, you can opena command prompt and enter the following syntax:

CMDeploy.bat <repository_path> <cmw_path> <service_name>

The CMDeploy.bat file is located in the Conversion Agent bin directory.

Here, <repository_path> is the location of the Conversion Agent repository, whereservices are stored. The <cmw_path> is the path of the CMW file of the project thatyou are deploying, and the <service_name> is a name for the deployed service. Ifthe directory names contain spaces, you must type them by using their MS-DOS8.3 names.


15

For example, if the repository is in the default location c:\Program Files\SAP\ConversionAgent\ServiceDB, and the project is at c:\Projects\MyProject, you canenter:

CMDeploy.bat c:\Program Files\SAP\ConversionAgent\ServiceDBc:\Projects\MyProject MyProject

Running a Conversion Agent Service

Command-Line InterfaceYou can run a Conversion Agent service by opening a command prompt andrunning the CM_console command:

CM_console <service_name> <options>

For example, suppose that the MyProject service runs a parser. If you want to runthe service on a source document called Source.txt1, and to store the output inOutput1.xml, you can enter:

CM_console MyProject -f"c:\temp\Source1.txt" -o"c:\temp\Output1.xml"

For a complete explanation of the CM_console syntax and options, see theConversion Agent Engine Developer's Guide.

Other Ways to Run ServicesYou can also run Conversion Agent services by:

Programming a Java or COM application that calls the Conversion Agent API(see the Conversion Agent Engine Developer's Guide and the API references)

Using the Conversion Agent CGI interface (see the Conversion Agent EngineDeveloper's Guide)

Using the CMTransformBean within SAP XI (see Using Conversion Agent in SAPXI above)

Error LogsIf a Conversion Agent service encounters an error, it generates a log file. The log isa *.cme file, which you can view in any text editor. For information, see theConversion Agent Engine Developer's Guide.

sap conversion agent by itemfield...sap conversion agent by itemfield deploying and using conversion...

Documents