SAP Conversion Agent by Itemfield · c:\Documents and Settings\\Application Data\SAP\...

$Page 1: SAP Conversion Agent by Itemfield · c:\Documents and Settings\\Application Data\SAP\ ConversionAgent\4.0\CMReports Component Selection and Setup Types At the prompt,$
SAP Conversion Agent byItemfield

Conversion AgentAdministrator's Guide

Version 4 for Microsoft Windows

Legal Notice

Conversion Agent Administrator's Guide

Copyright © 2004-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: 4 for Microsoft WindowsDate: June 2006

Conversion Agent Administrator's Guide Contents

i

Contents

1. Overview ...........................................................................................1Additional Administration Information ....................................................................................................1

2. Installation ........................................................................................2System Requirements ........................................................................................................................... 2

Platform ...........................................................................................................................................2Java Runtime Environment ............................................................................................................. 2Third-Party Applications ..................................................................................................................3

If You are Upgrading from a Previous Version ......................................................................................4Installation Instructions .......................................................................................................................... 4

Setup Options.................................................................................................................................. 5Configuring In-Process or Out-of-Process Invocation..................................................................... 6Registration and Licensing .............................................................................................................. 8

Uninstalling .......................................................................................................................................... 10User Privileges ....................................................................................................................................10Testing the Installation.........................................................................................................................11Troubleshooting................................................................................................................................... 12

Java Heap Size .............................................................................................................................12Log Files........................................................................................................................................13Asian Fonts ................................................................................................................................... 13

3. Upgrading Conversion Agent Projects.........................................14When Is Upgrading Necessary?.......................................................................................................... 14Terminology.........................................................................................................................................14Upgrading an Individual Project...........................................................................................................15Syntax Conversion Tool ......................................................................................................................15

Before Running the Tool: Organize Your Projects ........................................................................16Running the Syntax Conversion Tool............................................................................................ 16Running from the Command Line .................................................................................................17

Upgrade Issues ................................................................................................................................... 18Modified Components ...................................................................................................................19Modified Namespace for Variables ............................................................................................... 19Unsupported File and Directory Names ........................................................................................ 19Features that Are Not Upgraded Correctly ....................................................................................19XSD Schemas ............................................................................................................................... 20Additional Upgrade Issues ............................................................................................................20

Conversion Agent Administrator's Guide Contents

ii

4. Configuration Editor.......................................................................21Backing Up the Configuration File ....................................................................................................... 21Using the Configuration Editor.............................................................................................................21Configuration Settings .........................................................................................................................22

Index....................................................................................................23

Conversion Agent Administrator's Guide 1. Overview

1

Overview

This book explains how to administer Conversion Agent on Microsoft Windowsplatforms. It covers subjects such as:

Installing the Conversion Agent software

Upgrading Conversion Agent projects from previous versions

Configuring Conversion Agent

Additional Administration Information

Some of the information in this book, such as how to use the Configuration Editor,is also applicable to Conversion Agent versions for Unix-based operating systems.For detailed information about the Unix versions, see the book Conversion Agent forUnix.

1

Conversion Agent Administrator's Guide 2. Installation

2

Installation

This chapter explains how to install and register Conversion Agent on a MicrosoftWindows platform.

System Requirements

To install the Conversion Agent software, your computer should meet thefollowing minimum requirements.

Platform

Microsoft Windows 2000, XP Professional, or 2003 Server (32-bit edition).

Microsoft Internet Explorer, version 6.0 or higher.

(For Conversion Agent Studio) Microsoft .NET Framework, version 1.1 orhigher. If you do not already have this, the Conversion Agent setup installs it.

At least 128 MB of RAM.

For a Conversion Agent Engine installation running production Conversion Agentservices, we recommend at least 512 MB of RAM and a CPU speed of at least 1GHz.

The Conversion Agent Engine and Studio software require approximately 200 MBof disk space.

If you plan to install the optional Conversion Agent libraries (such as those forHL7, several EDI versions, HIPAA, AL3, and SWIFT), you should reserveadditional space. Each library may require up to a few hundred megabytes.

Java Runtime Environment

A Sun Java 2 Runtime Environment, version 1.4.2_9, must be installed on thecomputer. You can use the JRE that is installed with Conversion Agent, or you candownload a JRE from http://www.sun.com.

2

http://www.sun.com/


3

If You Have Multiple JRE Versions

The setup prompts you to select a JRE version to use when you run ConversionAgent. If you have multiple JRE versions, you should select a single version thatyou will use with Conversion Agent.

The selected JRE does not need to be defined in the PATH. (In rare instances, theConversion Agent Java document processors may require that the JRE be definedin the PATH for proper operation.)

If necessary, you can use the Configuration Editor to change the selected JREfollowing the installation.

If You Plan to Use the Conversion Agent Java API

If you use the Conversion Agent Java API to activate a Conversion Agent service,any Java components of the service run on the JRE that is used by the external Javaapplication.

For consistency of operation, we recommend that this be the same JRE as the onethat you configured within Conversion Agent. In any event, it must be a JREversion that Conversion Agent supports.

Third-Party Applications

You can use Conversion Agent with documents that are generated by a largenumber of third-party applications. The following applications are among thosethat are currently supported.

Please contact SAP support for information about other applications, file formats,or versions.

Microsoft Office ApplicationsTo help you parse Microsoft Office documents (Word, Excel, or PowerPoint),Conversion Agent offers several document processors, which convert thedocuments to a format such as text, HTML, RTF, or XML. Office versions 97 andhigher are supported.

The text, HTML, and RTF processors require that the Office application be installedon the Conversion Agent computer. The XML processors do not require the Officeapplication.

For detailed information, see the Parsers chapter in the Conversion Agent StudioUser's Guide.

Acrobat and COBOL Support

Conversion Agent contains built-in support for the Adobe Acrobat (PDF) formatand for COBOL data formats. You do not need to install any Acrobat or COBOLsoftware to process these file types.


4

If You are Upgrading from a Previous Version

From Version 4.0.2 or EarlierIf you are upgrading from Conversion Agent version 4.0.2 or earlier, you mustuninstall your existing version before installing the new version.

From Version 4.0.3 or Higher

If you are upgrading from Conversion Agent version 4.0.3 or higher, or if you areinstalling a Conversion Agent service pack, you do not need to uninstall beforeinstalling the new version.

Before starting the upgrade, you must shut down all applications that useConversion Agent. Otherwise, the setup cannot replace certain files, and theupgrade may fail.

Upgrading Multiple Components and ComputersThe setup requires that you upgrade all the Conversion Agent componentstogether to the same release number. This includes:

Conversion Agent Engine and Studio

Any other optional Conversion Agent components

We recommend that you upgrade all Conversion Agent computers in yourorganization at the same time. This avoids any possible version conflicts betweenprojects that you develop on one computer and run on another computer.

Upgrading Projects

To upgrade your existing Conversion Agent projects and run them in the newversion, see Chapter 3, Upgrading Conversion Agent Projects.

Installation Instructions

To install the Conversion Agent software:

1. If your organization has a site license for Conversion Agent, make sure thatyou have the license key. The setup wizard will prompt you to enter the key.

2. Log on as a user with administrative privileges for the local computer.

3. Execute the Setup.exe file.

The installer opens an InstallShield wizard. Please be patient; it may take ashort time to open the wizard.

4. You are prompted to select the language of the setup displays.

This sets the language for the setup wizard and the default language for theConversion Agent user interface. Following installation, you can change theuser-interface language in the Conversion Agent Configuration Editor.


5

5. Follow the on-screen instructions to complete the setup. For an explanation ofthe options, see Setup Options below.

6. If you are running an upgrade setup from a previous Conversion Agent 4release, the setup may prompt you to upgrade your existing ConversionAgent services. For more information, see Chapter 3, Upgrading ConversionAgent Projects.

7. Depending on your Conversion Agent version, the setup may prompt you toregister the software and install a license file. Follow the on-screen instructionsto complete the registration. For further information, see the section onRegistration and Licensing below.

8. By default, Conversion Agent Engine runs in the process of the callingapplication on Windows platforms. Optionally, you can configure it to runout-of-process. For instructions, see Configuring In-Process or Out-of-ProcessInvocation below.

Setup Options

The setup options vary, depending on the components in your installationpackage. The following paragraphs describe the options when you install the mainConversion Agent components.

Site LicenseIf you have a site license, enter the license key at the prompt.

Folder and File LocationsThe setup prompts for the following folder or file locations.

You may accept the default locations, or you may browse to locations that youprefer. Following the installation, you can change the locations (except for theinstallation location) by using the Configuration Editor (see Chapter 4,Configuration Editor).

Conversion Agent PathThe Conversion Agent installation folder. The default is c:\ProgramFiles\SAP\ConversionAgent.

JRE LocationThe location of the Java Runtime Environment that you will use withConversion Agent. The default is a JRE that the setup installs in theConversion Agent folder. Optionally, you can browse to another JRE, which isalready installed on your computer (see Java Runtime Environment above).

Conversion Agent Repository PathThis is the folder where you will deploy Conversion Agent services forexecution by Conversion Agent Engine. The default location is c:\ProgramFiles\SAP\ConversionAgent\ServiceDB.


6

Conversion Agent Log PathThe location where Conversion Agent Engine stores its log files. The default is:

c:\Documents and Settings\<USER>\Application Data\SAP\ConversionAgent\4.0\CMReports

Component Selection and Setup Types

At the prompt, choose which components to install, and if you would like to do atypical or custom installation. Depending on the components in your setuppackage, there may be options for components such as:

Engine(Required) Installs Conversion Agent Engine, which is the runtime componentthat executes Conversion Agent services.

Eclipse Development EnvironmentInstalls Conversion Agent Studio for Eclipse. This is a design andconfiguration environment where you can create Conversion Agent projects.

Later in the setup, you are prompted to use Conversion Agent Studio eitherwith an existing IBM Eclipse installation, or to install a new, standalone copyof Eclipse. The option to use the existing copy of Eclipse is appropriate ifEclipse version 2.1.2 or 2.1.3 is already installed on the computer, and youwish to use Conversion Agent Studio in it. Otherwise, you should select thestandalone option, which installs a copy of Eclipse 2.1.3.

Document ProcessorsInstalls a set of document processors, which you can use in datatransformations.

LibrariesInstalls the Conversion Agent project libraries. The libraries containpredefined parsers, serializers, and XSD schemas, which you can use withprotocols such as HL7, several EDI versions, HIPAA, AL3, and SWIFT.

Configuring In-Process or Out-of-Process Invocation

By default on Windows platforms, Conversion Agent Engine runs in the process ofthe calling application. Optionally, you can configure it to run out-of-process.

Out-of-process invocation requires the use of Conversion Agent Server. Theadvantage of doing this is that an Engine failure is less likely to disrupt the callingapplication. A disadvantage is that some of the APIs may be unavailable whenrunning out-of-process. Also, running in-process may give faster performance thanout-of-process. For detailed information, including the API support, see thechapter on Conversion Agent Server in the Conversion Agent Engine Developer's Guide.

Conversion Agent supports 32-bit Windows environments. The Server does not support64-bit applications on Windows (as opposed to Unix, where it supports 64 bits).


7

Configuration

To select in-process or out-of-process invocation, follow this procedure:

1. On the Start menu, open the Conversion Agent Configuration Editor.

2. In the left pane, expand the tree to display the following node:

CM Configuration/CM Engine

3. In the right pane, edit the following setting. If the setting is not displayed,right-click the CM Engine node and add it.

InvocationSelect the value InProc for in-process invocation.

Select Server for out-of-process invocation. This causes requests toConversion Agent Engine to be routed via Conversion Agent Server. Foreach client process (that is, for each process that submits requests), theServer starts an independent Conversion Agent Engine process.

4. Optionally, edit the settings under the following node:

CM Configuration/CM Engine/CM Server

These settings have an effect only if you have set Invocation = Server. If thesettings are not displayed, right-click the CM Server node and add them.

Server PathLeave this setting blank. It is unnecessary on Windows platforms.

Thread pool sizeThe maximum number of Conversion Agent Engine threads, which can runclient requests concurrently, per process. If the number of client requestsexceeds the number of available threads, the Server queues the requestsuntil a thread is available. The default is 4.

Thread Stack SizeThe stack size, in kilobytes, that the Server allocates to each thread. Thedefault is 1024.

Init EngineIf the value of this parameter is OnDemand , the Server starts the Engine whenthe client application first issues a request. If the value is OnStartup, theServer starts the Engine when the client application is loaded. The default isOnDemand.

Number of retries, Restart timeoutIn the event that a client process receives no response from the Server, itattempts a Server restart. These parameters control the restart behavior:

The Number of retries is the maximum number of permitted restarts, andthe Restart timeout is the time interval in seconds. If the number ofrequired restarts exceeds the specified value, within the time interval, theclient process ceases all further attempts.


8

The default values are Number of retries = 4 and Restart timeout = 900.This means that if the client process needs to restart the server more than 4times in 900 seconds, it ceases the attempts.

This behavior is regardless of the number of successful requests during thetimeout period. In the above example, if the client process successfullycommunicates with the server 100 times during the 900-second interval, butit fails 5 times, it ceases further attempts.

The behavior is per client process. If there are multiple client processes, theneach of them is permitted 4 restarts during the timeout interval.

The restarts refer only to the communication between the client process andthe Server. If Conversion Agent Engine returns an error response (forexample, due to invalid input data), the Server reports the error status to theclient, but the Server does not require a restart.

Registration and Licensing

Depending on your Conversion Agent version, you may be prompted to registerthe software or to provide licensing information. You can open Conversion AgentStudio and create projects without a license, but you cannot run datatransformations until you install a license.

If for any reason you did not register during the setup, you can register later. Onthe Start menu, choose SAP Conversion Agent > Registration. You can also use theRegistration option to renew a license or to expand the licensing terms.

Some vendors may provide other registration options or instructions. Please follow anyspecial registration instructions that you received with your copy of Conversion Agent.

Site LicenseA site license is a single license, which is valid for all computers in theorganization.

To obtain a site license, please contact your Conversion Agent vendor. You willneed to provide information such as maximum number of CPUs per computer.

The site license includes a license key and a License.cfg file. During the setup, youare prompted to enter the license key.

Following the setup, you must install a copy of the License.cfg file. See Installing aLicense.cfg File below.

Standalone License

A standalone license is a license to use Conversion Agent on a single computer.

If you plan to use a standalone license, the setup prompts you to register thesoftware. You must register separately on each computer where you installConversion Agent. Following the setup, you must install a License.cfg file, whichis specific for the computer.


9

At the prompt, select one of the following options:

Add license fileSelect this option if you already have a license file for your computer(License.cfg), and you want to use it.

Register nowSelect this option to obtain a standalone license file, which lets you runConversion Agent on a single computer.

Register laterRegister (and run Conversion Agent) later.

The registration procedure is as follows:

1. In the registration form, enter the following information:

Product TypeChoose CM Studio to register Conversion Agent Studio alone.

Choose CM Engine to register both Conversion Agent Studio and Engine.

Depending on the optional features that you installed, there may beadditional product-type options.

Number of CPUsThe number of processors in the computer.

Some CPUs, such as certain Intel Pentium 4 processors, use dual-core orhyperthreading technology. This may make a single physical CPU operateas multiple logical CPUs. If you have such a CPU, or if Conversion Agentprompts you for a multiple-CPU license on a computer where only onephysical CPU is installed, please notify SAP when you submit theregistration.

Company NameYour company's name.

E-mailThe email address where SAP should send the license file.

Phone No.Your telephone number.

ContactYour name.

2. Click the Register button, and submit the registration to the indicated location.

3. When you receive the License.cfg file, install it as described below.

Installing a License.cfg File

To install a License.cfg file on the computer:

1. Log on as a user with administrative privileges.

2. Open Conversion Agent Studio. A registration prompt is displayed.


10

3. Click the Add License File button, browse to the License.cfg file, and clickOpen. You can then use Conversion Agent.

Alternatively (for example, on a computer where Conversion Agent Studio is not installed),you can install License.cfg by copying it to the Conversion Agent installation folder.

After a Major Computer UpgradeA standalone License.cfg file is specific to a particular computer.

After a major computer upgrade, such as installing a new Windows version, thesystem may no longer recognize your License.cfg file. If that occurs, you shouldrepeat the registration procedure and install a new License.cfg file.

Changing the License TypeTo switch from a site license to a stand-alone license, or vice versa, you shoulduninstall Conversion Agent and install it again.

License Status

To determine whether you have a valid Conversion Agent license, open acommand prompt and enter the command

CM_console aaa

where aaa is a placeholder for a Conversion Agent service name (the service aaadoesn't need to actually exist). If you do not have a valid license, the commanddisplays an error message such as license file has been corrupted or doesn't exist. Inthat case, you should follow the steps described above to obtain a license.

If you receive an error message such as invalid service 'aaa', you can ignore it. Thereason for the message is that the aaa service doesn't exist.

License Renewal

To renew a license, please contact SAP.

Uninstalling

To uninstall Conversion Agent, open the Add or Remove Programs option of theWindows Control Panel. Select the option to remove Conversion Agent 4.

User Privileges

In the Windows Control Panel, you should register the users who will useConversion Agent, and grant the appropriate privileges.


11

Administrators

Windows users who have administrative privileges can perform all ConversionAgent operations.

Limited UsersTypically, limited users do not have write permission for the Conversion Agentprogram folder. Therefore, they are subject to the following restrictions:

They cannot install or uninstall the Conversion Agent software.

They can generate a registration file (registration.txt), but they cannotinstall a license file (License.cfg).

They cannot deploy services to the default Conversion Agent repository. Youcan relax this restriction by moving the Conversion Agent repository toanother folder, where the users have write permission (see Chapter 4,Configuration Editor).

They cannot add custom components such as document processors ortransformers.

They can view the settings in the Conversion Agent Configuration Editor, butthey cannot change the setting values.

Testing the 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 folder ConversionAgent\setupTests, there is a sample ConversionAgent project called TestCME. Copy the entire TestCME directory to theConversion Agent repository, which you defined during the setup (by default,ConversionAgent\ServiceDB). This makes TestCME available as a ConversionAgent service.

5. Enter the following command, which executes TestCME.

CM_console TestCME

The service performs a simple data transformation on an HL7 sourcedocument. The following result should be displayed:

<Result>Test Succeeded</Result>


12

6. If you installed the document processors, you can test the installation byrunning an additional service called TestCMDP. The service converts an Excelspreadsheet file to XML. It uses the ExcelToXml document processor toperform an initial conversion stage.

To run the test, copy the folder

ConversionAgent\setupTests\TestCMDP

to the Conversion Agent repository. Then run the command:

CM_console TestCMDP

The output should be:

<Report><Name>John Doe</Name><Age>29</Age><Sex>Male</Sex><Report><Q Year="2000" Q="1">5</Q><Q Year="2000" Q="2">6</Q><Q Year="2000" Q="3">7</Q><Q Year="2000" Q="4">3</Q><Q Year="2001" Q="1">5</Q><Q Year="2001" Q="2">8</Q><Q Year="2001" Q="3">3</Q><Q Year="2001" Q="4">3</Q><Q Year="2002" Q="1">3</Q><Q Year="2002" Q="2">4</Q><Q Year="2002" Q="3">2</Q><Q Year="2002" Q="4">8</Q></Report></Report>

Troubleshooting

If you experience difficulty installing or running Conversion Agent, please checkthe following points.

Java Heap Size

If a Java component of Conversion Agent, such as a document processor that usesJava, fails to process very large documents, the problem may be an inadequate Javaheap size. You can control the heap size by this procedure:

1. Open the Conversion Agent Configuration Editor (see Chapter 4, ConfigurationEditor).

2. In the left pane, expand the tree to display:

CM Configuration/CM Engine


13

3. Right-click the CM Engine node and add JVM init parameters.

4. Assign a value of JVM init parameters such as Xmx512M, where 512 is the heapsize in megabytes.

You should define the JVM init parameters only if needed. Setting a large Javaheap size increases the Conversion Agent memory requirement.

Log Files

Conversion Agent generates several log files, which are useful for troubleshootingpurposes.

Installation Logs

The setup creates a set of logs in the ConversionAgent\Inst_logs folder. You canexamine the logs for any error messages.

Conversion Agent Studio LogBy default, Conversion Agent Studio keeps a log of its operations. To enable ordisable the log, and to determine the log location, open the Preferences window ofConversion Agent Studio.

Conversion Agent Studio Event Logs

When Conversion Agent Studio runs a data transformation, it saves an event logcalled Events.cme in the Results folder of the project. The log is displayed in theEvents view. For information, see the chapter on Running and Testing Projects in theConversion Agent Studio User's Guide.

Conversion Agent Engine Event LogsIf a failure occurs in a Conversion Agent service, Conversion Agent Engine createsan events log. You can view the log in the Event Viewer tool. For moreinformation, see the chapter on Event Logs in the Conversion Agent EngineDeveloper's Guide.

Asian Fonts

The Conversion Agent Studio views may fail to display Asian fonts correctly underWindows 2000. To correct the problem, open the Window > Preferences command,select the Workbench/Fonts node, and set the font for each view.

Conversion Agent Administrator's Guide 3. Upgrading Conversion Agent Projects

14

Upgrading Conversion Agent Projects

If you are upgrading from a previous Conversion Agent release, you may need toupgrade your existing projects and your deployed Conversion Agent services tothe current release.

The upgrade of projects from Conversion Agent version 3.1 or higher is fullyautomatic. You can upgrade an individual project by opening or importing it inConversion Agent Studio, or you can run a syntax conversion tool, which canupgrade all your projects or services together.

If you run an upgrade setup from a previous Conversion Agent 4 release, the setup promptsyou to upgrade your existing services. In other cases, you should perform the upgradeyourself, after you complete the setup.

When Is Upgrading Necessary?

Upgrading is necessary when the Conversion Agent Engine syntax version haschanged.

To determine the syntax version, open a command prompt and run the followingcommand:

CM_console -v

Terminology

In Conversion Agent 3.x and 4, the terms project, workspace, etc., are used inslightly different ways. To prevent confusion, we use the Conversion Agent 4terminology throughout the upgrade instructions, unless otherwise stated.

The following table presents the corresponding terms.

Conversion Agent 4 Conversion Agent 3.x Description

project workspace A directory containing a data-transformationconfiguration (a single CMW file, one or moreTGP script files, etc.)

3


15

Conversion Agent 4 Conversion Agent 3.x Description

workspace (no correspondingterm)

The default parent directory, where ConversionAgent Studio 4 stores projects

service service A project that has been made available to run inConversion Agent Engine

deploy publish Make a project available as a service

repository services databaselocation

The parent directory where Conversion Agentservices are stored

Upgrading an Individual Project

To upgrade an individual project, open or import it in Conversion Agent Studio.

You can do this by running the File > Import command. In the Import window,select the option to import an Existing Conversion Agent Project into Workspace.

Conversion Agent Studio prompts you to upgrade the project if necessary. Theupgrade is fully automatic.

Following the upgrade, you should test the project and confirm that it runscorrectly.

Upgrading a Service

You can upgrade the development copy of a project and re-deploy it as aConversion Agent service.

To do this, open or import the development copy in Conversion Agent Studio. Testthe project, and re-deploy it as a service.

Syntax Conversion Tool

You can use the Conversion Agent syntax conversion tool to upgrade multipleprojects and services quickly, in an automated operation. You can also use it toupgrade global TGP script files, which are stored in the Conversion AgentautoInclude\user directory. The following paragraphs explain the procedure.

The tool is fail-safe. It creates an automatic backup of your existing projects andfiles, prior to the upgrade. It creates a log file and reports any upgrade errors that itdetects. In case of an error, you can restore the backup, correct the problem, andrun the tool again.


16

Before Running the Tool: Organize Your Projects

The tool operates on projects or services that are stored in a single parent directory.It can operate on:

A Conversion Agent Studio version 4 workspace

A Conversion Agent 3.x services database location

A Conversion Agent 4 repository

Any other directory that contains Conversion Agent 3.x workspaces

Any other directory that contains Conversion Agent 4 projects

Within the parent directory, the projects must be at the top level of nesting, forexample:

Parent DirectoryProject1Project2Project3...

If your projects are not currently stored in a single parent directory, you can re-organize them before running the tool. Alternatively, you can run the toolseparately, on the individual parent directories.

The tool also operates on:

The Conversion Agent autoInclude\user directory, which contains globalTGP script files

Running the Syntax Conversion Tool

To run the syntax conversion tool:

1. In the Conversion Agent folder on the Start menu, choose Syntax ConversionTool. This opens a window with several tabs, where you can configure theupgrade.

2. At the bottom of the window, specify whether you are upgrading fromversion 3.x or 4.x.

3. On the Services tab, set the following options:

Source LocationThe parent directory containing the old projects, or the repositorycontaining the old services.

Target LocationThe parent directory where the tool should store the new projects, or therepository for the new services. If the target is the same as the source, theoriginal files are overwritten.


17

Note: If you are upgrading services, use the Configuration Editor to changethe repository location to the specified target (see Chapter 4, ConfigurationEditor). If you are upgrading development projects, use the File > Importcommand to open the projects for the first time in Conversion Agent Studio.

4. If you have any TGP files in the autoInclude\user directory, set the followingoptions on the AutoInclude tab:

Source LocationThe old autoInclude\user directory.

Target LocationThe new autoInclude\user directory.

5. Set the following options on the Result Files tab:

Backup LocationA location where the tool should back up your existing projects, prior toupgrade.

Error LocationA location where the tool should store any projects that it cannot upgradedue to an error.

Log LocationA location for the upgrade log.

6. Click the Start button. The tool reports its progress and results.

7. You can repeat steps 3, 5, and 6 on any additional parent directories thatcontain projects or services. For example, you may need to upgrade both aConversion Agent Studio workspace (where you store development projects)and a repository (where you store deployed services).

The AutoInclude options should be blank on the repeat runs. The AutoIncludefiles were already upgraded on the first run and do not need to be upgradedagain.

8. If the tool reports any errors, review the log to determine their cause, correctthem, and run the tool again.

9. Test the projects and services to confirm that they work correctly and that theirbehavior has not changed. For a discussion of the issues that may arise, seeUpgrade Issues below.

Running from the Command Line

Optionally, you can run the syntax conversion tool from the command line,without displaying the graphical user interface. To do this:

1. Open a command prompt, and change to the Conversion Agent bin directory.

2. Run the following command:

CMStart.exe -t CMConversion -console <additional switches>


18

The <additional switches> are listed in the following table.

Switch Description

-v (Required) Version from which you are upgrading (3 or 4).

-s (Required) Path of the source directory, containing projects or services.

-d (Optional) Path of the target directory. If you omit this switch, the tooloverwrites the existing directory.

-si (Required to upgrade global TGP files) Path of the sourceautoInclude\user directory.

-di (Optional) Path of the target autoInclude\user directory. If you omit thisswitch, the tool overwrites the existing directory.

-l (Optional) Path of the upgrade log file. The default isSyntaxConversionLog.txt , in the Conversion Agent directory.

-b (Optional) Path of the backup directory, where the tool backs up the originalprojects or services prior to the upgrade. The default is the value of the -sswitch concatenated with the suffix _OLD_Backup.

-e (Optional) Path of the error directory, where the tool stores any projects orservices that it cannot upgrade due to an error. The default is the value of the-s switch concatenated with the suffix _OLD_Failure.

Following each switch, leave a space and type the value. If a path containsspaces, you must enclose it in quotation marks. For example, the command

CMStart.exe -t CMConversion -console -v 4 -s "c:\Program Files\SAP\ConversionAgent\ServiceDB"

upgrades version 4 services in the default repository location.

3. The tool notifies you when the upgrade is complete. If there were errors, itprompts you to examine the log file.

4. If you are upgrading services, use the Configuration Editor to change therepository location to the target that you specified (see Chapter 4, ConfigurationEditor).

Upgrade Issues

The following paragraphs discuss some issues that you may encounter when youupgrade existing projects to the new Conversion Agent version.


19

Modified Components

In version 4, some of the Conversion Agent components that you can use in datatransformations have been revised, renamed, or replaced by new components.When you upgrade a project, Conversion Agent inserts the new componentsautomatically.

For a list of components that have been modified, see the document What's New inConversion Agent 4.

Modified Namespace for Variables

Starting in version 4.0.6, the namespace for variables has been changed towww.Local-Project.com/Variables. If you upgrade a project from version 4.0.5 orearlier, the Schema view and the project properties display both the old namespace(which is empty) and the new namespace (which contains your variables). This hasno effect on the operation of your project.

Unsupported File and Directory Names

In Conversion Agent 4, the names of project files and directories can containEnglish letters (A-Z, a-z), numerals (0-9), spaces, and the following symbols:

# % & + , - = @ [ ] _ { }

If a version 3.x project uses names that don't conform to this convention, theproject may fail to upgrade. If this occurs, change the names in version 3.x beforerunning the tool.

Features that Are Not Upgraded Correctly

The automatic upgrade tools successfully upgrade nearly all the Conversion Agentfeatures that existed in previous Conversion Agent versions.

Nonetheless, it is important that you test the data transformation following theupgrade. For example, you may find that an upgraded project containing theLocator component behaves slightly differently from the original version 3.2project, where the Locator component did not exist, and the analogousfunctionality was implemented in a different way.

In projects upgraded from version 4.0.4 and earlier, the behavior of theEnsureCondition and CalculateValue actions may change slightly, due to theintroduction of a new JavaScript processor. For details of the supported JavaScriptsyntax, see the EnsureCondition action in the Conversion Agent Studio User's Guide.

If you find that an upgraded project does not operate correctly, you can edit itsconfiguration in Conversion Agent Studio.


20

XSD Schemas

In Conversion Agent 3.1, the XML schema was defined in the TGP files of theproject. Starting in Conversion Agent 3.2, the XML schema is an XSD file.

When you upgrade a version 3.1 project to version 4, Conversion Agent Studiocreates an external XSD schema automatically. You should review the schema andconfirm that it meets your needs. You can edit the schema or create your ownschema, as required.

For information, see the Data Holders chapter of the Conversion Agent Studio User'sGuide.

Additional Upgrade Issues

If you have any additional questions about upgrading Conversion Agent projects,please contact SAP support.

Conversion Agent Administrator's Guide 4. Configuration Editor

21

Configuration Editor

Conversion Agent has a Configuration Editor, which lets you edit the basicparameters of a Conversion Agent installation.

Usually, you need to use the Configuration Editor only in the followingcircumstances:

If you need to change one of the folder locations that you configured duringthe setup, such as the JRE location or the Conversion Agent repositorylocation.

If instructed in the Conversion Agent documentation or by SAP support.

Backing Up the Configuration File

The Configuration Editor saves the configuration in a file called CMConfig.xml,which is located in the Conversion Agent installation folder.

Before you edit the configuration, we recommend that you save a backup copy ofCMConfig.xml. In the event of a problem, you can restore the backup.

The file CMConfig.bak is a backup of the original CMConfig.xml, which the setupprogram created when you installed Conversion Agent. Restoring CMConfig.bakreturns Conversion Agent to its original configuration.

Using the Configuration Editor

To open the Configuration Editor, on the Start menu, open SAP Conversion Agent> Configuration.

Some of the Configuration Editor settings are available in all Conversion Agentinstallations. Some additional settings may vary depending on the ConversionAgent version and on the optional components that you have installed.

Assigning the Settings

The editor has an Explorer type window. In the left pane, expand the tree andselect the desired setting. In the right pane, double-click to assign a setting value.

4

Conversion Agent Administrator's Guide 4. Configuration Editor

22

Some settings require that you type a value, whereas others offer a drop-down listor a browse option. If a setting has a gray background, it has a read-only value thatcannot be edited.

Some settings accept a table of values. For such settings, you can right-click to addor remove table rows.

Saving the Configuration FileClick the Save icon to save the edited settings. If you forget to save, theConfiguration Editor displays a reminder when you exit.

Configuration Settings

The following are the most common configuration settings that you may need toedit. You can assign these settings when you run the Conversion Agent setup. Ifnecessary, you can change the settings afterwards in the Configuration Editor.

CM Configuration/Directory services/File system/Base PathThe Conversion Agent repository location, where you store Conversion Agentservices that you deploy. The default location is:

c:\Program Files\SAP\ConversionAgent\ServiceDB

CM Configuration/CM Engine/JVM LocationThe location of the Java 2 Runtime Environment. The default is:

c:\Program Files\SAP\ConversionAgent\jre1.4\bin\client

You can change this setting if you want to use a different, supported JRE, or ifyou upgrade the JRE and you want Conversion Agent to use the new version.For a list of the supported JREs, see Java Runtime Environment in Chapter 2,Installation.

You should not uninstall the previous JRE until you have assigned and testedthe new setting, because the Configuration Editor itself requires a JRE.

CM Configuration/General/Reports directoryThe location where Conversion Agent saves event logs and certain other typesof reports. The default is:

c:\Documents and Settings\<USER>\Application Data\SAP\ConversionAgent\4.0\CMReports

There are many additional settings, which are described in the relevant locationsthroughout the Conversion Agent documentation.

Conversion Agent Administrator's Guide Index

23

Index

A

autoIncludeupgrading, 15

C

CMReportssetting log location, 22

Configuration EditorConversion Agent, 21using, 21

configuration filebacking up, 21

Conversion Agent Engineinstalling, 6

Conversion Agent repositorysetting location, 22

Conversion Agent Serveron Windows, 6

Conversion Agent servicesupgrading, 15

Conversion Agent Studioinstalling, 6

CPUsmultiple logical, 9

D

document processorsinstalling, 6

E

Eclipseinstalling, 6

event logssetting location, 22

Excelsystem requirements, 3

F

filenameseffect on upgrade, 19

fontsdisplaying Asian, 13

H

heap sizeJava, 12

I

in-process invocationon Windows, 6

installationConversion Agent, 2

invocationin- or out-of-process, 6

J

Javaheap size, 12

JRE locationchanging, 22

L

librariesinstalling, 6

licenseconfirming validity, 10site, 8standalone, 8

licensingConversion Agent, 5

limited usersrestrictions, 11

log fileslocation of, 13

logssetting location, 22

Conversion Agent Administrator's Guide Index

24

M

Microsoft Officesystem requirements, 3

N

namespacevariables, 19

O

out-of-process invocationon Windows, 6

P

PowerPointsystem requirements, 3

projectsupgrading, 15upgrading from previous version, 14

R

registrationConversion Agent, 9renewing, 10

reportssetting location, 22

S

schemasupgrading, 20

Serveron Windows, 6

servicesupgrading, 15

site license, 8standalone license, 8

syntax conversion tool, 15syntax version

Conversion Agent Engine, 14system requirements

Conversion Agent, 2

T

testingConversion Agent on Windows, 11

troubleshootingConversion Agent installation, 12

U

uninstallingConversion Agent, 10

upgradingConversion Agent versions, 4modified components, 19projects, 14selecting components for, 4services and projects, 15

usersprivileges, 10

V

variablesnamespace, 19

versionConversion Agent Engine syntax, 14

W

Wordsystem requirements, 3

Date post:	23-Mar-2020
Category:	Documents
Upload:	others
View:	18 times
Download:	0 times