sap conversion agent by itemfield - help.sap.com · conversion agent studio is the design and...

SAP Conversion Agent byItemfield

Conversion Agent Studioin Eclipse

Version 4

Legal Notice

Conversion Agent Studio in Eclipse

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

Conversion Agent Studio in Eclipse Contents

i

Contents

1. Overview ...........................................................................................1Overview of Conversion Agent .............................................................................................................. 1Overview of the Eclipse Platform...........................................................................................................2

Workbench ...................................................................................................................................... 3Projects ...........................................................................................................................................3Workspace ...................................................................................................................................... 3Perspectives ....................................................................................................................................4Views ...............................................................................................................................................4Editors ............................................................................................................................................. 4

2. Using the Eclipse Workbench .........................................................6Opening the Workbench........................................................................................................................ 6

Displaying the Conversion Agent Perspective ................................................................................ 6Layout of the Conversion Agent Perspective ..................................................................................6

Main Menu............................................................................................................................................. 7File Menu......................................................................................................................................... 7Edit Menu ........................................................................................................................................ 7Navigate Menu ................................................................................................................................ 8Search Menu ................................................................................................................................... 8Project Menu ................................................................................................................................... 8Run Menu ........................................................................................................................................ 9IntelliScript Menu .............................................................................................................................9Window Menu................................................................................................................................ 10Help Menu .....................................................................................................................................11

Toolbars...............................................................................................................................................11Main Toolbar .................................................................................................................................11Shortcut Bar ..................................................................................................................................13View Toolbar .................................................................................................................................13

Views and Editors................................................................................................................................ 13Changing the Size of a View or Editor...........................................................................................13

Keyboard Shortcuts .............................................................................................................................14


ii

3. Working with Projects ....................................................................15Creating a Project................................................................................................................................ 15Storage Location of Projects ...............................................................................................................16

Default Workspace ........................................................................................................................ 17Storing Projects Outside the Workspace Folder ...........................................................................17Determining the Storage Location of a Project.............................................................................. 17Moving the Workspace..................................................................................................................18Opening Multiple Workspaces....................................................................................................... 18

Project Files .........................................................................................................................................18Startup When Projects Already Exist................................................................................................... 19

Editing an Existing Project .............................................................................................................19Removing a Project .......................................................................................................................19Making a Project Active ................................................................................................................. 20

Importing an Existing Project...............................................................................................................20Running a Project ................................................................................................................................ 20Deploying a Project .............................................................................................................................22

4. Using the Conversion Agent Views...............................................23Working with Views .............................................................................................................................23

View Menus................................................................................................................................... 23View Toolbars................................................................................................................................ 23

Conversion Agent Explorer View.........................................................................................................24Component View .................................................................................................................................25IntelliScript Assistant View...................................................................................................................25Tasks View .......................................................................................................................................... 26Help View ............................................................................................................................................27Events View.........................................................................................................................................27Binary Source View .............................................................................................................................28Schema View....................................................................................................................................... 29Repository View................................................................................................................................... 29

5. Using the IntelliScript Editor..........................................................30Creating or Adding a TGP Script File ..................................................................................................30Opening an IntelliScript Editor .............................................................................................................31

Editor Layout .................................................................................................................................31Display Modes of the Example Pane ............................................................................................ 31Finding Anchors in the Panes ....................................................................................................... 33

Components and Properties ................................................................................................................33


iii

Editing..................................................................................................................................................35Basic Procedure for Editing: Select-Enter-Assign-Enter ............................................................... 35Copy and Paste.............................................................................................................................36Drag and Drop ............................................................................................................................... 36Find and Replace ..........................................................................................................................37Inserting a Component in the IntelliScript......................................................................................37Deleting a Component...................................................................................................................37Editing the Properties of a Component .........................................................................................37Inserting Tabs, Newlines, and Other Special Characters..............................................................38Defining a Global Component ....................................................................................................... 38Viewing Help about a Component .................................................................................................39IntelliScript Icons ...........................................................................................................................39

Guided Mode....................................................................................................................................... 40Activating Guided Mode ................................................................................................................40

Pop-Up Menus of the IntelliScript Editor..............................................................................................41Saving the IntelliScript .........................................................................................................................42Customizing the Conversion Agent Component List...........................................................................42

6. Conversion Agent Studio Preferences .........................................44Displaying the Preferences..................................................................................................................44General Conversion Agent Preferences..............................................................................................44Conversion Agent Event Preferences .................................................................................................45XSD Editor Preference ........................................................................................................................ 46

Index....................................................................................................47

Conversion Agent Studio in Eclipse 1. Overview

1

Overview

Conversion Agent Studio is the design and configuration environment of the SAPConversion Agent system. Using Conversion Agent Studio, you can implementtransformations that operate on any kind of data.

Conversion Agent Studio integrates into the Eclipse platform as an Eclipse plug-inmodule. The Eclipse platform provides a versatile development environment, inwhich you can configure and deploy Conversion Agent projects. You can use theConversion Agent projects either in conjunction with other projects that youdevelop in Eclipse, or independently of Eclipse.

This manual explains how to use Conversion Agent Studio in the Eclipseenvironment. It provides instructions for using the Eclipse windows and interfaceto create, edit, and manage your Conversion Agent projects.

Except for a brief overview, this manual does not explain the logical concepts ofConversion Agent, or how the Conversion Agent data transformations work. Forthat information, please consult the books Getting Started with Conversion Agent andthe Conversion Agent Studio User's Guide.

This book describes only the Eclipse features that are used in Conversion Agent. For anexplanation of the other Eclipse features, please read the Eclipse online help.

Overview of Conversion Agent

Conversion Agent is a system for implementing and running data transformations. Itsupports four main types of transformation components:

ParsersComponents that convert source documents, which can be in any format, toXML.

SerializersComponents that convert XML documents to output documents, which can bein any format.

TransformersComponents that modify data. The input and output can be in any format.

1


2

MappersComponents that convert XML documents to a different XML structure orschema.

In addition to these main transformation components, Conversion Agent offers alarge number of additional components that you can use to build projects. Amongthese are:

AnchorsComponents that define how Conversion Agent should search for the datawithin a document, what data it should extract from the document, and whereit should store the extracted data in the output.

ActionsComponents that perform operations on the data, such as concatenatingstrings, computing sums, or querying a database for additional data.

FormatsComponents that define the overall format of documents, such as the delimitersand processors that Conversion Agent should use to interpret the documents.

When you construct a Conversion Agent data transformation, you configure it inmodular fashion from these and other components. The components are arrangedin a hierarchy or tree structure, which defines how the components process andtransform the data.

Overview of the Eclipse Platform

Eclipse is an open platform for tool integration, which is developed andmaintained by the Eclipse Foundation (http://www.eclipse.org). It provides aframework that simplifies the creating, integrating and utilizing of software tools.The tools—such as Conversion Agent Studio—operate as plug-ins in the Eclipseenvironment.

http://www.eclipse.org/


3

The basic elements of the Eclipse environment are the Workbench, projects,workspace, perspectives, views, and editors. The following paragraphs explain themeaning of these terms.

Workbench

The Workbench is the Eclipse desktop development environment. The Workbenchwindow lets you create, edit, test, and deploy Conversion Agent datatransformations.

Projects

You perform all work in a framework called a project. A project is stored in aspecified folder, although certain project files can also exist outside the folder.

Workspace

The workspace is the location where Eclipse stores a set of projects. When you openthe Workbench, all the projects in the current workspace are displayed. It ispossible to edit multiple projects belonging to the same workspace concurrently.

The Conversion Agent workspace is the workspace where Eclipse stores ConversionAgent projects. By default, there is a single Conversion Agent workspace, which is:

My Documents\SAP\ConversionAgent\4.0\workspace

Optionally, it is possible to create more than one workspace. For example, youmight have a workspace for your Conversion Agent projects, and another for othertypes of Eclipse projects. You might also have multiple workspaces for differentsets of Conversion Agent projects. Only one workspace can be open at a time in asingle Workbench, but it is possible to open multiple Workbenches.


4

Perspectives

The Workbench defines one or more perspectives. A perspective is the layout of theWorkbench window. Typically, a perspective comprises an editor area and severalviews. The editor and views may be associated with a set of menus and toolbars.

Each perspective provides a set of capabilities for accomplishing a specific type oftask, or for working with a specific type of resources. In this book, we describe theConversion Agent perspective, which is the set of editors and views forConversion Agent projects.

Views

A view is a window within the Workbench, which displays data.

Generally speaking, a view lets you observe the project data, as opposed to aneditor, which lets you modify the data. A view may let you set options or performcertain pre-defined operations, but it does not let you edit the data freely.

Views are typically used to navigate through a project, open an editor, or displayproperties of an object that is selected in an editor. For example, the ConversionAgent Explorer view displays all of your projects and the files associated withthem.

A view can have a pop-up menu, which you can display by right-clicking insidethe view. A view can also have a drop-down menu, which you can display byclicking an icon at the right end of the title bar.

Some views have their own toolbars, which are displayed at right of the view title.The buttons on the toolbar affect the items within the view.

Typically, the operations that you perform in a view are performed and savedimmediately. You do not need to click the Save command or icon explicitly. Anexception is if the view operation affects the content of an editor. In that case, youmust save the project to make the operation permanent.

Editors

An editor is a window within the Workbench, which lets you create and modify thecontent of a project. An editor differs from a view in that it lets you modify thedata freely; a view constrains you to a few pre-defined operations.

Different editors are associated with different types of files. In Conversion Agent,there is an IntelliScript editor for TGP script files, which define the hierarchy ofcomponents in a data transformation. You can open an editor by double-clicking afile in the Conversion Agent Explorer view, or by double-clicking a component inthe Component view.

Any number of editors can be open at once, but only one can be active at a time.The main Workbench menu and toolbar display the commands and operationsthat are applicable to the active editor.


5

Tabs in the editor area indicate the names of files or resources that are currentlyopen for editing. An asterisk (*) on the tab indicates that the editor has unsavedchanges. You must choose the Save command or click the Save button to save thechanges.

Conversion Agent IntelliScript editor, for TGP script files

Conversion Agent Studio in Eclipse 2. Using the Eclipse Workbench

6

Using the Eclipse Workbench

The Eclipse Workbench is the environment in which you develop ConversionAgent projects. This chapter describes the Workbench tools that are available foruse in Conversion Agent, such as the menus, toolbars, and windows.

Opening the Workbench

To open the Eclipse Workbench for Conversion Agent, choose SAP ConversionAgent > Conversion Agent Studio for Eclipse on the Start menu.

Displaying the Conversion Agent Perspective

When you open Conversion Agent Studio, you should display the ConversionAgent perspective. The perspective provides the views and editors that you needto configure Conversion Agent projects.

If the perspective is not currently displayed, choose Window > Open Perspective >Conversion Agent Studio Authoring on the Eclipse menu.

Resetting the PerspectiveIf you have altered the perspective (for example, by opening and closing windowsor by moving the windows), you can reset the default perspective. To do this,choose Windows > Reset Perspective on the Eclipse menu.

Layout of the Conversion Agent Perspective

When you first display the Conversion Agent perspective, the following windowsare displayed:

Conversion Agent Explorer view

Component view

Events view

Editor area

The Component view and the Events view are stacked with other views. You canselect the desired view by clicking the tabs on the bottom of the view.

2


7

Main Menu

The following paragraphs describe the commands on the Eclipse main menu thatare used in Conversion Agent.

Some commands may be dimmed and disabled depending on the current editingoperation. Some commands are displayed only when a specific editor is active.

File Menu

NewCreates a new project or component.

The Project and Other options display the New Project wizard, where you cancreate Conversion Agent projects of various types. For an explanation, seeChapter 3, Working with Projects .

The Parser or Serializer options let you create a parser or serializer component,within an already existing project.

CloseCloses the active editor.

Close AllCloses all editors.

SaveSaves the active project file.

PrintPrints the content of the active editor.

ImportLets you import an existing Conversion Agent project into the workspace. Forinstructions, see Importing an Existing Project in Chapter 3, Working withProjects.

PropertiesLets you set the properties of a project that is selected in the Conversion AgentExplorer. For information, see Project Properties in the Conversion Agent StudioUser's Guide.

ExitExits Eclipse.

Edit Menu

UndoCancels the last editing operation.

RedoRedoes the last operation, which you canceled with Undo.


8

Cut, Copy, Paste, DeleteLets you copy and delete the selected content in the active editor.

Select AllSelects the entire content of the active editor.

Find/ReplaceFind and replace text in the active editor.

Navigate Menu

The commands in this menu are part of the Eclipse Platform, but have no specificapplications in Conversion Agent Studio.

Search Menu

The commands in this menu are part of the Eclipse Platform, but have no specificapplications in the Conversion Agent Studio.

Project Menu

ValidateValidates the integrity of the project scripts. For example, the commandverifies that the data holders used in a project are defined in the XSD schema.

DeployDeploys a project by placing it in the Conversion Agent repository.Conversion Agent Engine can then run the project as a Conversion Agentservice. For information, see Deploying Conversion Agent Services in theConversion Agent Studio User's Guide.

PropertiesLets you set the properties of a project that is displayed in an IntelliScripteditor. For information, see Project Properties in the Conversion Agent StudioUser's Guide.

RunLets you define the startup component, which Conversion Agent shouldactivate when you run the project. The startup component can be any parser,serializer, mapper, or globally-defined transformer in the project.

Optionally, after you define the component, you can click the Run button torun the project.

Run <Project Name>Runs the project.

You must define a startup component (either by using the Run command orby right-clicking the component and choosing Set as Startup Component)before using this command.


9

Run Menu

RunRuns the data transformation.

The dialog box lets you define the startup component, which ConversionAgent should activate when you run the project. The startup component canbe any parser, serializer, mapper, or globally-defined transformer in theproject.

Then, click the Run button to execute the data transformation.

Run <Component Name>Runs the data transformation.

You must define a startup component (either by using the Run command orby right-clicking the component and choosing Set as Startup Component)before using this command.

IntelliScript Menu

This menu is displayed when the IntelliScript editor is active. This editor is themain location where you can configure a data transformation, such as a parser or aserializer.

InsertInserts a component such as a Parser, Serializer, Variable, Marker, Content,Mapper, or RepeatingGroup.

Test DocumentTemporarily switches the display in the example pane to a different sourcefile, instead of the example source.

If you are testing a parser, you can then choose the IntelliScript > MarkExample command. This runs the parser and color-codes the anchors that theparser finds in the source document. You can use this feature to test the parserconfiguration.

Open Example SourceOpens the example source file, which you use to configure and test a datatransformation.

Learn the Example AutomaticallyEnables the automatic color coding in the example pane. When you configurea parser, Conversion Agent automatically highlights the anchors in theexample.

Learn ExampleColor-codes the anchors in the example pane in the learn-example style. In thisstyle, the colors label the specific locations that Conversion Agent uses todefine the anchors.


10

Mark ExampleRuns the selected parser, and color-codes the anchors in the example pane inthe mark-example style. In this style, the colors label all instances of an anchorthat the parser found in the example.

Stop Learning or Marking the ExampleStops the color-coding operation. If the example is very long, you can use thisoption to halt the color display and speed up the response.

IntelliScriptDisplays the IntelliScript pane only. This pane is where you define a datatransformation.

BothDisplays both the IntelliScript and example panes.

ExampleDisplays the example pane only.

Guided ModeActivates the guided mode, which can help you configure the IntelliScripteasily (see Guided Mode in Chapter 5, Using the IntelliScript Editor).

Window Menu

This menu lets you display perspectives and views.

Open PerspectiveDisplays a specified perspective. For Conversion Agent projects, you shouldopen the Conversion Agent Studio Authoring perspective.

Show ViewDisplays a specified view.

Show Editors/Hide EditorsDisplays or hides the open editors.

Save Perspective AsLets you save a customized perspective under a user-defined name.

Reset PerspectiveResets the current perspective to its default layout.

Switch to EditorSwitches to one of the open editors.

You can also switch editors by clicking the tabs at the top of the editor area.

PreferencesLets you specify display preferences. For details, see Chapter 6, ConversionAgent Studio Preferences.


11

Help Menu

Use this menu to display information about Conversion Agent or about Eclipse.The commands relevant to Conversion Agent are:

WelcomeLets you display the Welcome pages for the Eclipse platform, for ConversionAgent Studio, or for other Eclipse plug-ins that you may have installed. TheWelcome pages provide introductory operating instructions and guide you tolearn more about the application.

Help ContentsDisplays the Eclipse documentation.

Conversion Agent HelpUnder this command, there are options to:

Display the Conversion Agent documentation libraryContact SAP supportRegister the Conversion Agent software

About Conversion Agent StudioDisplays information about your Conversion Agent Studio version.

Toolbars

This section describes the toolbars that are available when you display theConversion Agent perspective.

Main Toolbar

The main toolbar, also known as the Workbench toolbar, is displayed at the top ofthe Workbench window, directly beneath the menu. The buttons displayed on thistoolbar depend on the active perspective and editor.

Some of the buttons on the main toolbar are specific to Conversion Agent, whileothers are provided by the Eclipse platform. In the following paragraphs, weexplain only how the buttons are used in Conversion Agent.

Main Toolbar When the IntelliScript Editor is ActiveThe IntelliScript editor is the main location where you can configure a datatransformation, such as a parser or a serializer. When the IntelliScript editor isactive, the following toolbar is displayed. The left side of the toolbar displays thestandard Eclipse buttons. The right side displays buttons that are specific to theIntelliScript.


12

The following paragraphs describe the toolbar buttons that are used in ConversionAgent.

NewThe New button displays the New Project wizard, where you can createprojects of various types. For an explanation, see Chapter 3, Working withProjects.

The drop-down arrow, immediately to the right of the New button, offersseveral options for new projects or components. The Project and Other optionsare similar to the New button. The Parser or Serializer options let you create aparser or serializer component, within an already existing project.

SaveSaves your editing.

PrintPrints the content of the active editor.

Show IntelliScript pane onlyDisplays the IntelliScript pane only.

Show both IntelliScript and example panesDisplays both the IntelliScript and example panes.

Show example pane onlyDisplays the example pane only.

Activate guiding focus and tips within IntelliScriptActivates the guided mode, which can help you configure the IntelliScripteasily (see Guided Mode in Chapter 5, Using the IntelliScript Editor).

Insert a new Parser in the scriptInserts a new Parser component in the IntelliScript.

Insert a new Serializer in the scriptInserts a new Serializer component in the IntelliScript.

Insert a new Mapper in the scriptInserts a new Mapper component in the IntelliScript.

Insert a new Variable in the scriptInserts a new Variable in the IntelliScript.

Insert a new Marker in the scriptInserts a new Marker anchor in the IntelliScript.

Insert a new Content in the scriptInserts a new Content anchor in the IntelliScript.

Insert a new Repeating Group in the scriptInserts a new RepeatingGroup anchor in the IntelliScript.


13

Learn the example automatically whenever script changesEnables the automatic color coding in the example pane. When you defineanchors in the IntelliScript, Conversion Agent automatically highlights thecorresponding location in the example.

Learn the example according to the current scriptColor-codes the anchors in the example pane in the learn-example style. In thisstyle, the colors label the specific locations that Conversion Agent uses todefine the anchors.

Mark the entire example according to the current scriptRuns the selected parser, and color-codes the anchors in the example pane inthe mark-example style. In this style, the colors label all instances of an anchorthat the parser found in the example.

Stop learning or marking the exampleStops the color-coding operation. If the example is very long, you can use thisoption to halt the color display and speed up the response.

Shortcut Bar

At the far left of the Workbench is the shortcut bar. You can use this toolbar toopen and switch between perspectives, such as the Conversion Agent perspective.

View Toolbar

Some views contain their own toolbars. For an explanation of these toolbars, seeChapter 4, Using the Conversion Agent Views.

Views and Editors

For an explanation of the views and editors that are available in the ConversionAgent perspective, see:

Chapter 4, Using the Conversion Agent Views

Chapter 5, Using the IntelliScript Editor

Changing the Size of a View or Editor

You can change the size of a view or editor window by dragging its borders.

To maximize a view or editor, double-click its title bar. To restore the window to itsoriginal size, right-click the title bar and choose Restore.

To move a window to a new docking position, drag its title bar. Eclipse does notpermit you to dock windows in certain locations. For example, you can dock aview over another view, but not over an editor. For further instructions, open the


14

Eclipse help and navigate to the contents entry Workbench User's Guide > Tasks >Working with Views and Editor > Moving and Docking Views.

Keyboard Shortcuts

You can run some of the Conversion Agent commands by pressing keyboardshortcuts, instead of clicking the menus or the toolbars.

The shortcut keys are displayed on the menus. For example, the Run menuindicates that the F5 key runs a project.

Conversion Agent Studio in Eclipse 3. Working with Projects

15

Working with Projects

A Conversion Agent project contains the files and resources that are necessary toperform one or more data transformations. In Conversion Agent Studio, you cancreate, configure, and deploy projects.

Each project is associated with a specific folder on your disk. Most of the projectfiles are stored in the folder, but a few files, such as the example source document,may be stored in other locations.

Creating a Project

To create a new Conversion Agent project:

1. On the menu, choose the File > New > Project command.

2. In the left pane of the New Project wizard, select the Conversion Agent option.

3. In the right pane, select one of the following Conversion Agent project types:

Blank ProjectThis option creates an unconfigured project. After you create the project,you can use the IntelliScript editor and the other Conversion Agent tools toconfigure any type of data transformation.

A blank project is recommended for experienced Conversion Agent users. Itis the most flexible project type, but the wizard does not guide you throughthe project configuration steps.

Parser ProjectThis option creates a project that contains a parser. The wizard guides youthrough the basic parser configuration. For example, it prompts you todefine an example source and to select an XSD schema.

After you complete the wizard, you should edit the IntelliScript and addcomponents such as anchors and actions.

For complete instructions, see the chapter on Parsers in the Conversion AgentStudio User's Guide.

Library ProjectThis option imports a project from a Conversion Agent library. The wizardcreates a copy of the project, which you can then edit according to yourneeds.

3


16

For more information, see the manual Using and Generating Conversion AgentLibraries.

Serializer ProjectThis option creates create a project that contains a serializer. The wizardguides you through the basic serializer configuration. For example, itprompts you to select an XSD schema.

After you complete the wizard, you should edit the IntelliScript and addcomponents such as serialization anchors and actions.

For complete instructions, see the chapter on Serializers in the ConversionAgent Studio User's Guide.

Import ProjectThis option generates a Conversion Agent project from an existing COBOLdata definition (copy book). The project contains a parser, a serializer, andan XSD schema that work with COBOL data conforming to the definition.

For information about this feature, see the document Processing COBOLData in Conversion Agent.

Note: Do not use this option to import an existing Conversion Agent project.For that purpose, use the File > Import command.

4. On the next page, enter the following information:

Project nameAn identifier for the project.

Project contentsThe storage location of the project folder (see Storage Location of Projectsbelow).

5. On the succeeding wizard pages, enter the requested project configurationoptions. The options depend on the type of project that you have selected.

6. When you complete the wizard, the project folder is created on your disk, andthe project files are displayed in the Conversion Agent Explorer view.

Storage Location of Projects

By default, Conversion Agent Studio stores all projects in the Eclipse workspacefolder.

While you work in Eclipse, you do not need to know the project location. Eclipsemanages the projects and files automatically. You may wish to ascertain the projectlocation, however, for purposes such as the following:

To back up your Conversion Agent projects

To store a file that is not managed by Eclipse, such as a test document or aproject design specification

You can move the workspace location if desired.


17

The following paragraphs are a summary of how to perform these tasks. For moreinformation, see the Eclipse help, under the topic Workbench User's Guide > Tasks >Running Eclipse.

Default Workspace

The default location of the Eclipse workspace for Conversion Agent projects is thefollowing:

My Documents\SAP\ConversionAgent\4.0\workspace

Storing Projects Outside the Workspace Folder

The New Project wizard allows you to create a project either in the workspacefolder or outside it.

In either case, Eclipse considers the project as belonging to the workspace. If youclose and re-open Conversion Agent Studio, the project continues to be displayedin the Conversion Agent Explorer. You can edit and run projects that are storedoutside the workspace folder, in exactly the same way as projects that are stored inthe workspace folder.

Determining the Storage Location of a Project

You can determine the storage location of a project by any of the followingmethods:

In the Conversion Agent Explorer

1. In the Conversion Agent Explorer view, select the project.

2. On the menu, choose File > Properties.

3. The Info page of the properties window displays the location.

In an IntelliScript Editor1. While editing a TGP script file in the IntelliScript editor, choose Project >

Properties.


In the Eclipse Navigator1. On the menu, choose Windows > Show View > Other.

2. Expand the Basic category and open the Navigator view.

3. In the Navigator, right-click the desired project or file and choose Properties.



18

Moving the Workspace

You can move the Conversion Agent Studio workspace location by the followingprocedure. You might do this, for example, if other users need to access theworkspace, and they don't have permission for your default workspace location.

1. Close Conversion Agent Studio.

2. Open the Conversion Agent Configuration Editor, and edit the followingsetting:

CM Configuration/CM Studio/Eclipse/Workspace

3. Open Conversion Agent Studio. If the new workspace folder does not exist, itis created.

4. On the menu, choose Window > Open Perspective > Conversion Agent StudioAuthoring.

5. Optionally, import the projects from your old workspace to the new one (seeImporting an Existing Project below).

Opening Multiple Workspaces

You cannot open two workspaces concurrently in a single instance of the EclipseWorkbench. You can open two Workbenches that are configured with differentworkspaces, however.

Project Files

The main file types used in Conversion Agent projects are as follows:

Main project fileA *.cmw file that contains the main project information. The name of this file isthe name of the project.

Example source documentsExamples of the input documents that you want a data transformation toprocess.

Script filesOne or more *.tgp files, which define the data transformations that the projectcan perform.

XSD schema filesOne or more *.xsd files, which define the XML structures that the projectsupports.

Results filesFiles created as a result of the running of the project, such as output and logfiles.


19

Filenames

To ensure cross-platform compatibility, the names of project directories and files(*.cmw , *.tgp , *xsd, example source, etc.) must contain only English letters (A-Z, a-z), numerals (0-9), spaces, and the following symbols:

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

Displaying a File

Under each project, the Conversion Agent Explorer displays categories for theabove file types, such as:

ExamplesScriptsXSDResults

To display any of the files, double-click its name in the Conversion Agent Explorer.

Startup When Projects Already Exist

When you open Eclipse after one or more projects have been created, theWorkbench looks the way it did when you last closed it. The existing projectsremain available in the Conversion Agent Explorer view.

Editing an Existing Project

To open and edit an existing project:

1. In the Conversion Agent Explorer, expand the tree under the project.

2. Double-click the file that you wish to view or edit, such as a TGP script file, orright-click and choose Open.

You can also edit a project by double-clicking a component in the Componentview.

Removing a Project

To remove a project from the workspace, right-click its name in the ConversionAgent Explorer, and choose Remove.

You are prompted to delete the project folder from the disk. If you do not delete,the project is removed from the workspace, but you can import it if you want touse the project later.


20

Making a Project Active

When you select a project in the Conversion Agent Explorer view, the projectbecomes active. The other views display information about the active project.

Importing an Existing Project

You can import a project that exists outside the current Eclipse workspace. To dothis:

1. On the menu, choose File > Import.

2. On the first page of the wizard, select the option to import an ExistingConversion Agent Project into Workspace.

3. On the next page, browse to the *.cmw file of the existing project.

4. On the next page, enter a name for the imported project (by default, the sameas the name of the existing project).

5. Click the Finish button.

6. If the existing project was created in an earlier Conversion Agent version, youare prompted to upgrade the imported copy. Click OK to continue.

7. The system copies the project into the Conversion Agent workspace folder.When the import is complete, the imported copy is displayed in theConversion Agent Explorer. You can edit and run the project in the same wayas projects that you create from scratch in the workspace.

Note that the import procedure copies the essential project files, such as the CMW,TGP, XSD, and example-source files. It may fail to copy additional files, such astest documents, which you have stored in the project folder. You should copy suchfiles manually.

There is no link between the original project and the imported copy. If you edit theimported copy, the original project is unchanged.

If the project already belongs to another Eclipse workspace or was created in Eclipse, thereis an alternative import procedure. In step 2, select the option to import Existing Projectinto Workspace. This adds the original project, in its existing location, to the currentworkspace. It does not create a copy of the project.

Running a Project

To test a project, you can run it in Conversion Agent Studio. The steps are asfollows:

1. Set the startup component of the project. This is a top-level component—aparser, serializer, mapper, or transformer—which the project should activate.


21

You can do this in any of the following ways:

- In the IntelliScript editor, right-click the component and choose Set asStartup Component, or

- In the Component view, right-click the component and choose Set asStartup Component, or

- On the menu, choose Run > Run. In the dialog box, select the startupcomponent.

2. Optionally, in the Run > Run command, you can click the Details button andset the initial values of the variables in your project.

The initial values that you assign in this way are used when you test theproject in Conversion Agent Studio. They have no effect when you laterdeploy the project as a Conversion Agent service.

For more information, see Data Holders in the Conversion Agent Studio User'sGuide.

3. To run the component, choose:

- Run > Run, or- Run > Run <StartupComponentName>, where <StartupComponentName>

is the name of the startup component.

Viewing the Results

To view the output of a project, double-click the appropriate file in the Resultscategory of the Conversion Agent Explorer view.

For example, the output of a parser is an XML file. To view the output, find theXML file in the Results category, and double-click its name. Conversion Agentopens the file in a Microsoft Internet Explorer window.

If you are using Windows XP SP2 or higher, Internet Explorer may display a warningabout active content in the XML results file. You can safely ignore the warning.


22

Deploying a Project

When you deploy a project, it is copied to the Conversion Agent repository.Conversion Agent Engine can then run the project as a Conversion Agent service.

To deploy a project, choose the Project > Deploy command on the menu. For moreinformation, see the chapter on Deploying Conversion Agent Services in theConversion Agent User's Guide.

Conversion Agent Studio in Eclipse 4. Using the Conversion Agent Views

23

Using the Conversion Agent Views

The Conversion Agent views give you various presentations of projectinformation. You can use the views for purposes such as:

Examining the files and components of a project

Opening a file in an editor

Examining the events that occur when your run a project

Recording tasks that you need to perform

Reading the online help about a component

Working with Views

To display the Conversion Agent views, open the Conversion Agent perspective.

By default, the views are displayed on the left side and the bottom of theWorkbench. Many of the views are stacked; to select among the views, click thetabs on the bottom.

View Menus

If you right-click a view, a pop-up menu is displayed. The menu offers commandsthat are appropriate for the particular view or for the item that you have selected inthe view.

Some of the commands in the pop-up menus are identical to those on the mainmenu or on the toolbar. Others are not available elsewhere.

Some views also have a second, drop-down menu. You can display this menu byclicking the an arrow at the upper right of the view title.

View Toolbars

Some views have a small toolbar, which is located either to the right of the viewtitle or just below the title. The toolbar buttons perform operations that areappropriate for the view.

4


24

Conversion Agent Explorer View

By default, the Conversion Agent Explorer view is displayed at upper left of theWorkbench. The view lists all the Conversion Agent projects and files that exist inthe workspace. You can open a file in an editor by double-clicking its name.

For an explanation of the file types, see Project Files in Chapter 3, Working withProjects.

Pop-Up MenuIf you right-click in the Conversion Agent Explorer view, a pop-up menu with thefollowing functions is displayed:

NewCreates a new script (*.tgp) or schema (*.xsd) file.

OpenOpens the selected project or file.

When you open a project, you can edit the files in it.

When you open a file, it is displayed in an editor (the same as double-clickingthe file).

RenameRenames the selected script (*.tgp) file.

Add FileAdds an existing file, of a specified type, to the project. The file is copied intothe project folder.

RemoveRemoves the selected project or file from the workspace. There is an option todelete the project or file from the disk.

Reload XSDsReloads the XSD schemas. If you edit a schema, you should reload to be surethat the project works with the latest schema version.

Create Example XMLGenerates an XML example that conforms to an XSD schema. The exampleillustrates the XML structure that is defined by the schema.

Close ProjectCloses the current project and all the views and editors associated with it. Youcannot edit the files in the project until you re-open it.


25

Component View

By default, the Component view is stacked with the IntelliScript Assistant view atthe lower left corner of the Workbench. You can switch between the views byclicking the tabs at the bottom.

The view displays all of the top-level components that are defined in the project.You can edit a component by double-clicking its name.

The following types of components are displayed in this view:

Parsers

Serializers

Mappers

Transformers

Variables

Any other components that are defined at the top (global) level of theIntelliScript

Pop-Up Menu

If you right-click in the Component view, a pop-up menu with the followingfunctions is displayed:

DeleteDeletes the selected component.

RenameRenames the selected component.

Go toHighlights the selected component in the IntelliScript editor.

Set as Startup ComponentSelects the component that will be activated when you run this project.

IntelliScript Assistant View

By default, the IntelliScript Assistant view is stacked with the Component view, inthe lower left corner of the Workbench.

The IntelliScript Assistant presents the same options as the IntelliScript, but in adialog-box format. The view is recommended mainly for new Conversion Agentusers, who may not yet be familiar with the IntelliScript.

For example, if you select a Content anchor in an IntelliScript editor, theIntelliScript Assistant displays the most important properties of the anchor.


26

The IntelliScript Assistant is active only for a few Conversion Agent components,such as Content, Marker, and RepeatingGroup anchors. Even for these components,it is active only when certain properties of the components are selected. For anyother components, the view is blank.

Toolbar

The toolbar of the IntelliScript assistant displays the following buttons:

Move focus to the next componentSelects the next component of the IntelliScript, which the view allows you toedit (the next Marker, Content, or RepeatingGroup anchor).

Move focus to the previous componentSelects the previous component of the IntelliScript, which the view allows youto edit.

Drill into the focused componentMoves to a nested level of the IntelliScript tree, selecting the first componentthat the view allows you to edit. For example, if a Parser component iscurrently selected, the button moves the selection to an anchor that is nestedwithin the Parser.

Drill out of the focused componentMoves to the parent level of the IntelliScript tree.

Remove the focused componentDeletes the currently selected component from the IntelliScript.

Apply changes to the IntelliScriptApplies the editing that you perform in the IntelliScript Assistant to theIntelliScript. (If you forget to click this button, Conversion Agent prompts youto apply the editing when you select another component.)

Drop-Down Menu

The drop-down menu of the IntelliScript Assistant lets you create a Marker,Content, or RepeatingGroup anchor, which is inserted in the IntelliScript.

Tasks View

The Tasks view is stacked with several other views, at the bottom right of theWorkbench below the editor area.

Conversion Agent uses this view to display errors and warnings in the projectconfiguration. For example, it may display XSD syntax errors. You can double-click an error to find it in the editor.

You can also type your own entries in the Tasks view. You can use this feature torecord and track project development tasks.


27

Pop-Up Menu

You can use the pop-up menu of the Tasks view to create or manage tasks. Forexample, you can add a task row that reminds you to add a feature to a project.

Use the Properties command on this menu to get additional information about atask.

Drop-Down MenuThe drop-down menu of the Tasks view lets you sort or filter the tasks that aredisplayed.

Help View

The Help view is stacked with several other views, at the bottom right of theWorkbench below the editor area.

The view displays context-sensitive online help for the items that you select in theIntelliScript editor. For example, when you select a Marker anchor in theIntelliScript, the Help view displays a help topic describing the Marker anchor.

You can display the Help view by selecting its tab, or by pressing F1 while you arein the editor.

The Help view displays only the topics that are relevant to the current editor. To display thecomplete Conversion Agent documentation library, use the commands on the Help menu.

ToolbarNavigate help back

Returns to the previously displayed help topic.

Events View

The Events view is stacked with several other views, at the bottom right of theWorkbench below the editor area.

The view displays the events that occur when you run a project. For example, ifyou run a parser project, the view displays an event for each anchor that the parserfound.

If you double-click an event in the right pane, Conversion Agent highlights thecause of the event in the IntelliScript and the example source. For example, if youdouble-click the event for a Content anchor, Conversion Agent highlights the textthat the anchor retrieved.

For an explanation of the events, see the chapter on Running and Testing Projects inthe Conversion Agent Studio User's Guide.


28

Configuring the Events Display

You can configure the event types that Conversion Agent Studio displays and theway in which it highlights failures. For instructions, see the event preferences inChapter 6, Conversion Agent Studio Preferences.

Pop-Up Menu

A menu with the following functions is displayed when you right-click in theEvents view.

Open PageOpens the source document, which caused an event. You can do this toinvestigate the cause of an error.

FindFinds an event containing the specified text.

Find NextFinds the next occurrence of the specified text, after using the Find command.

Auto ExpandExpands the events tree completely.

Reload Project EventsReloads the events of the current project. This is useful after you have openedanother event log by using the Open Events File command.

Split Horizontally, Split VerticallyThe event log is split into a navigation pane and an event pane. Thesecommands control whether the split is horizontal or vertical.

Binary Source View

The Binary Source view is stacked with several other views, at the bottom right ofthe Workbench below the editor area.

The view displays the content of the example pane in a hexadecimalrepresentation. When you select data in this view, the corresponding data isselected in the Source pane, and vice versa. This is useful, for example, if you needto parse control characters, such as tabs or line breaks.

Binary Source view


29

Schema View

The Schema view is stacked with several other views, at the bottom right of theWorkbench below the editor area.

The view displays the namespaces and data holders (XML elements, XMLattributes, and variables) that are defined in the project. You can drag and dropfrom the example source to the Schema view to define Content anchors. For moreinformation, see the chapters on Data Holders and Anchors in the Conversion AgentStudio User's Guide.

Schema view

Repository View

The Repository view lists the Conversion Agent services that have been deployedon the computer. For more information, see Deploying Conversion Agent Services inthe Conversion Agent Studio User's Guide.

Pop-Up MenuA menu with the following functions is displayed when you right-click in theRepository view.

RemoveUndeploys the service, by removing it from the repository.

PropertiesDisplays the service properties.

RefreshRefreshes the service display.

Conversion Agent Studio in Eclipse 5. Using the IntelliScript Editor

30

Using the IntelliScript Editor

The IntelliScript editor is the main location where you can configure a datatransformation. In this editor, you can define parsers, serializers, mappers,transformers, and their nested components.

The IntelliScript has a tree structure. The top, global level of the tree typicallydisplays the runnable components—the parsers, serializers, mappers, andtransformers, which you can set as the startup components that Conversion Agentshould activate when you run the project. You can also define other components atthe global level, and use them at other locations in the project.

Nested within the global components, you can define components such as anchorsand actions. You can click the + or - symbols to display the nested levels.

The following sections provide some basic instructions for editing the IntelliScript.For worked-out examples and tutorials, see Getting Started with Conversion Agent.

Creating or Adding a TGP Script File

In the IntelliScript editor, you can edit a Conversion Agent script (*.tgp) file.

By default, most projects have a single script file. Optionally, you can insertadditional script files. This can help you organize a project by defining differentcomponents (parsers, serializers, etc.) in different files. You can edit multiple scriptfiles concurrently by opening them in different IntelliScript editor windows.

The components that you define in each script file are available throughout theproject. For example, a parser that is defined in one script file can call a secondaryparser that is defined in another script file, within the same project.

To create a script file, right-click the Scripts node of the project in the ConversionAgent Explorer, and choose New > Script. Optionally, you can type a name for thefile, overwriting the default name.

To add an existing script file to a project, right-click the Scripts node and chooseAdd File. Conversion Agent copies the file into the project folder; you can use ormodify the copy in your project, without affecting the original.

To rename an existing script file, right-click the file in the Conversion AgentExplorer, and choose Rename.

5


31

Opening an IntelliScript Editor

The IntelliScript editor displays the content of a script (*.tgp) file. To open anIntelliScript editor, double-click the script file in the Conversion Agent Explorerview.

You can also open an IntelliScript editor by double-clicking a component in theComponents view. This opens the script file where the component is defined.

Editor Layout

The IntelliScript editor has two panes:

The left pane, called the IntelliScript pane, displays the IntelliScript. This iswhere you define the data transformation.

The right pane, called the example pane, displays the example source documentof a parser. You can use this pane to define a parser by a select-and-clickprocedure. For instructions, see Getting Started with Conversion Agent.

You cannot edit the example source document in Conversion Agent Studio. Thepurpose of the example-source display is to help define a parser.

Optionally, you can display or hide either of the panes. To do this, use the toolbarbuttons or the corresponding commands on the IntelliScript menu.

IntelliScript pane on left, example pane on right

Display Modes of the Example Pane

Depending on the document type, the example pane may have one, two, or threetabs, which display the example source in different modes.

Source tabDisplays the text of the document.


32

Tree tabDisplays the code of an HTML or XML source document in an indented treerepresentation. For a complex document, the tree representation may be easierto use than the Source tab.

Browser tabDisplays a document in an Internet Explorer view. This tab is useful, forexample, to view the formatted appearance of an HTML, PDF, or MicrosoftOffice document.

To view a Microsoft Office document on the Browser tab, you must close allother instances of the Office application. For example, if you attempt to open aMicrosoft Word source document in Conversion Agent, while yousimultaneously have Word open on your computer, Conversion Agentdisplays a warning message. To solve the problem, close Word and re-openthe source document in Conversion Agent.

The Browser tab displays Microsoft Office documents with the viewingoptions that you have set in the Office application. For example, if you haveconfigured your copy of Word to display hidden text and formatting marks,the Browser tab displays them.

If you configure the example source with a document processor, the Browsertab displays the original document, not the processed document (see thechapter on Document Processors in the Conversion Agent Studio User's Guide). Ifthe tab fails to display the document, check that the appropriate InternetExplorer plug-in is installed and properly configured. For example, to displaya PDF document, the Adobe Reader plug-in must be installed.

ExamplesThe following figures illustrate the same section of a Microsoft Word sourcedocument, configured with the WordToHtml document processor, on all three tabs.

Source tab


33

Tree tab

Browser tab

Finding Anchors in the Panes

When you edit a parser, it is easy to find the corresponding anchors in theIntelliScript and example panes.

Right-click an anchor in the IntelliScript, and choose View Marking. This findsthe anchor in the example pane.

Select an anchor in the example pane. The anchor is automatically selected inthe IntelliScript.

Components and Properties

The IntelliScript displays two kinds of items: components and properties. Thenames of the components and properties are displayed in different colors.


34

Blue names are components; dark red names are properties

ComponentsThese are the items that you can insert and delete in the IntelliScript tree. Someexamples of components are parsers, serializers, anchors, actions, andtransformers.

PropertiesThese are lines that you can edit, but you cannot insert or delete (except byinserting or deleting a component that contains them). Some examples ofproperties are example_source property of a parser or the search property of amarker anchor.

There are two kinds of properties:

Basic propertiesProperties that are important in most uses of the component. You usually needto assign these properties to use the component.

When you expand the tree under a component, the basic properties areimmediately visible.

Advanced propertiesProperties that you often do not need to assign to use the component. Theproperties may have default values that you usually don't need to change, orthe properties may implement options that you often don't need to use.

To keep the display simple, the IntelliScript does not show the advancedproperties immediately when you expand the tree. To display them, click theAdvanced Properties Filter icon (>>) at the right of the component name. Theadvanced properties are displayed in a lighter shade of gray than the basicproperties.

To hide the advanced properties, click the Advanced Properties Filter icon(<<) again.


35

If you assign a non-default value to an advanced property, it is not hiddenwhen you click the << button. This helps you remember that you haveassigned the property.

Note that these properties are called advanced only because you don't alwaysneed to use them. They are not more difficult to use, dangerous to use, orrestricted in any other way. If you need to assign an advanced property, feelfree to do so.

IntelliScript showing basic properties. Click >> to display advanced properties.

IntelliScript showing basic and advanced properties. Click << to hide theadvanced properties.

Editing

To edit the IntelliScript, follow the procedures described in this section.

Basic Procedure for Editing: Select-Enter-Assign-Enter

The basic procedure for editing the IntelliScript is the following:

1. Click the mouse to select the component or property that you want to edit.

2. Press the Enter key to enter the editing mode. (In most locations, you can alsodouble-click instead of pressing Enter.)

3. Enter the component name or the property value.

4. Press the Enter key again to complete the editing operation.

If you remember this simple procedure, you will find it easy to edit any line of theIntelliScript. The following pictures illustrate the procedure.


36

1. Select the location that you want to edit.

2. Press the Enter key. This puts you in the editing mode.

3. Enter the property value.

4. Press the Enter key again. The property value is displayed.

Copy and Paste

You can copy and paste components in the IntelliScript.

To copy multiple components simultaneously, press the Control or Shift key whileyou select with the mouse. The components must all be at the same level of nestingin the IntelliScript.

You can paste components only in locations where they make sense. For example,you can paste anchor components under a parser but not under a serializer (whichrequires serialization anchors instead of regular anchors).

Drag and Drop

You can move components from one location to another by dragging with themouse. For example, you can use this method to alter the sequence of anchorswithin a parser.

To move multiple components, press the Control or Shift key while you select withthe mouse. Release the Control or Shift key, and then drag with the mouse.

To copy the selected components (instead of moving them), hold the Shift keydown while you drag.


37

Find and Replace

To find or replace text in the IntelliScript, choose the Edit > Find/Replacecommand on the menu.

Inserting a Component in the IntelliScript

Under many components, the IntelliScript displays a horizontal line (usuallybearing a label such as contains), an arrow, and a three-dots symbol (...). You caninsert nested components at the three-dots symbol.

A Group component, containing a line, arrow, and three-dots symbol. You cannest components within the Group, at the three dots.

To do this, select the three-dots, and press the Enter key.

This opens a drop-down list, which displays the components that you arepermitted to add at the location. You can choose a component from the list.Alternatively, you can start typing the component name; the name auto-completesafter you type the first few letters.

Press Enter again to complete the insertion.

Deleting a Component

You can delete a component by selecting it and pressing the Delete key.

Editing the Properties of a Component

To assign a property, select its value and press Enter. Depending on the type ofproperty, a text box, a drop-down list, or a dialog box may be displayed. Type orselect the desired property value.


38

Press Enter again to complete the assignment.

Inserting Tabs, Newlines, and Other Special Characters

When you assign a textual property, you can insert special characters by typingtheir ASCII codes.

To do this:

1. Press Ctrl+a. A small dot is displayed, indicating that the property value is asequence of ASCII codes.

2. Type the three-digit ASCII code. For example, you can type:

ASCII code Character

009 tab

010 linefeed

013 carriage return

3. To enter a string of ASCII codes, repeat steps 1 and 2.

After you press Enter, the IntelliScript displays a tab as a « symbol. It displaysother characters as their ASCII character codes.

Entering ASCII codes

Resulting IntelliScript display

Defining a Global Component

You can insert components in either a global or local scope:

Global scopeThe component is defined at the top level of the IntelliScript. It can be accessedor used at any location in the project.

Local scopeThe component is defined at a nested level of the IntelliScript. It can beaccessed or used only at the particular nested location.

Most Conversion Agent components can be either global or local.


39

For example, anchors are usually defined locally. You might define an anchor as aglobal component, however, if you want to use the same anchor configuration inseveral parsers or several times in the same parser. In each desired location, youcan reference the globally-defined anchor by its identifier.

The following illustration is an example. A marker anchor is defined at the globallevel and assigned the identifier MyMarker.

A marker anchor defined at the global level of the IntelliScript

A parser can then use MyMarker, instead of repeating the configuration of themarker anchor every time it is needed. You can select MyMarker from the drop-down list at the appropriate location within the parser, or you can drag MyMarker tothe location.

The globally-defined marker is used within a parser.

Naming RestrictionsThe names that you assign to IntelliScript components must contain only Englishcharacters (A-Z, a-z), numerals (0-9), and underscores ( _ ). They must begin with aletter. They can be up to 127 characters long.

Viewing Help about a Component

You can view the online help topics describing a component or property while youedit the IntelliScript.

To do this, display the Help view and select the component or property. The helpscrolls automatically to the location describing the selected item.

IntelliScript Icons

The IntelliScript displays each component types with a characteristic icon. Forreference purposes, the following is a partial list of the most common icons that areused in the IntelliScript.


40

Icon Component

Parser

Serializer

Mapper

Transformer

Marker anchor

Content anchorContentSerializer serialization anchor

Group anchor

RepeatingGroup anchor

StringSerializer serialization anchor

Other anchors

Actions

Handle

Key

Default icon, used when there is no specificicon for a component

Guided Mode

Guided mode is a feature that guides you through the process of creating anchors.When guided mode is active, and you define a string in the example source as ananchor, the required properties are automatically displayed for you, together withexplanatory tip.

You can proceed through a logical sequence of fields by pressing the Enter keyrepeatedly. The screen tips explain the correct usage of each property.

Activating Guided Mode

To activate Guided mode, click the icon on the main toolbar, or choose theIntelliScript > Guide Mode command on the menu.


41

Pop-Up Menus of the IntelliScript Editor

IntelliScript PaneIf you right-click in the IntelliScript pane, a pop-up menu with the followingfunctions is displayed:

View MarkingFinds an anchor in the example source.

Select an anchor in the IntelliScript, and click View Marking in the menu.Conversion Agent highlights the corresponding text in the example pane.

Set as Setup ComponentDefines the selected component as the startup component, which ConversionAgent should activate when you run the project.

This command is available only for runnable components—parsers,serializers, mappers, or globally-defined transformers.

Cut, Copy, Paste, Insert, DeleteLets you copy, delete, or insert components in the IntelliScript.

Make Optional, Make MandatorySelects or deselects the optional property of a component. If a component isoptional, a failure of the component does not cause its parent component tofail. For more information, see Effect of Failure Events in the chapter aboutRunning and Testing Projects in the Conversion Agent Studio User's Guide.

Enable, DisableDeselects or selects the disabled property of a component. A disabledcomponent is ignored. This feature is useful, for example, to disable acomponent temporarily for testing and debugging.

Script Mode, Intelli ModeThe Intelli mode displays the IntelliScript in a readable, graphicalrepresentation. This is the mode illustrated throughout this book and the otherConversion Agent documentation.

The Script mode displays the raw content of the *.tgp file. This mode isintended for troubleshooting only, under the guidance of SAP support.

The following commands are available only when a parser is selected:

Open Example SourceOpens the example source file of the parser.

Create SerializerCreates a serializer from a parser. The serializer and the parser performinverse data transformations.

Example PaneIf you right-click the example pane of the IntelliScript editor, a pop-up menu withthe following functions is displayed.


42

CopyCopies a string to the clipboard.

Insert MarkerDefines the selected text as a Marker anchor. The anchor is displayed in theIntelliScript.

Insert ContentDefines the selected text as a Content anchor. The anchor is displayed in theIntelliScript.

Insert Offset ContentDefines the selected location as a Content anchor. The anchor is displayed inthe IntelliScript.

Insert RepeatingGroupDefines the selected text as the separator of a RepeatingGroup anchor. Theanchor is displayed in the IntelliScript.

View InstanceFind the selected anchor in the IntelliScript.

FindFinds a string in the example source document.

Logical EncodingIf the example source contains text in a right-to-left language, such as Hebrewor Arabic, this command switches the display from left-to-right to right-to-left.

Line WrapWraps long lines.

Save Source AsSaves the example source in a specified location, under a specified name.

Saving the IntelliScript

If an asterisk (*) is displayed on the title tab of the IntelliScript editor, the editor hasunsaved changes. If you attempt to close the editor or exit the Workbench withunsaved changes, you are prompted to save.

Customizing the Conversion Agent Component List

You can add custom components to the drop-down list of components that isdisplayed in the IntelliScript editor. You can customize the component list of asingle project, or the global component list that is displayed in all projects.

You might do this, for example, with a custom document processor or action thatyou develop (see the chapters on Document Processors and Actions in the Conversion


43

Agent Studio User's Guide). If you plan to use the custom component repeatedly,this can be easier than configuring the component repeatedly in each location.

A custom component that you add to the drop-down list has the sameconfiguration in every location where you use it. You cannot re-assign itsproperties, except by editing the global definition.

Customizing the Component List in a Single ProjectTo customize the component list in a single project, see Defining a Global Componentabove.

Customizing the Component List in All Projects

To customize the component list of all projects:

1. In any project, right-click the Scripts node of the Conversion Agent Explorerand choose New > Script. This creates a new *.tgp script file.

2. Double-click the new *.tgp file to open it in an IntelliScript editor.

3. Define the component that you want to add to the component list, at theglobal level of the *.tgp file (see Defining a Global Component). Assign anidentifier to the component, and configure it as required.

For example, if the component is an ExternalPreProcessor, configure it to usea particular custom DLL to perform the preprocessing operation.

4. Save the *.tgp file.

5. Copy the *.tgp file to the autoInclude\user subfolder of the ConversionAgent installation folder.

6. If Conversion Agent Studio is currently open, close and re-open it.

Conversion Agent Studio then displays the identifier in the drop-down componentlist of all projects.

You must also copy the *.tgp file to the autoInclude\user folder of any computer whereyou run Conversion Agent Engine. This makes the component available to ConversionAgent Engine at runtime.

Conversion Agent Studio in Eclipse 6. Conversion Agent Studio Preferences

44

Conversion Agent Studio Preferences

The Preferences window lets you set options for how Conversion Agent Studioshould work on the Eclipse platform. The preferences affect only the behavior ofConversion Agent Studio. They have no effect on the how a project runs inConversion Agent Engine.

This chapter describes only the preferences that are specific to Conversion Agent Studio.For an explanation of the other preferences, see the Eclipse online help.

Displaying the Preferences

To display the Conversion Agent preferences:

1. On the Eclipse menu, choose Window > Preferences.

2. In the left pane, select the appropriate page, such as Conversion Agent orConversion Agent Events.

3. In the right pane, set the options for each preference.

General Conversion Agent Preferences

On the Conversion Agent page of the Preferences window, you can set thefollowing preferences:

LoggingLogging

If selected, Conversion Agent Studio saves a record of its operations in a logfile. The log is intended for troubleshooting use by SAP support.

Log filenameThe path to the log file.

6


45

Auto SaveAuto save

If selected, Conversion Agent Studio saves a backup of your TGP script files,at regular intervals while you edit them.

The backups are saved in the project folder and have a *.tgp.bak extension.Under normal conditions, Conversion Agent Studio deletes the backups whenyou finish editing. In case of a system failure during editing, ConversionAgent Studio offers to restore the *.tgp.bak files when you re-open theproject.

Background save interval (minutes)The interval between auto saves.

IntelliScriptHighlight focused instance

If selected, and you select a property of a component in the IntelliScript, theentire component is highlighted. This mode can help clarify a complexIntelliScript display.

Guided modeThis preference selects whether the guided mode is enabled by default, whenyou open a new IntelliScript editor.

Changing the preference has no effect on an IntelliScript editor that is alreadyopen. To enable or disable the guided mode in an open editor, use the toolbarbutton or the command on the IntelliScript menu.

For more information, see Guided Mode in Chapter 5, Using the IntelliScriptEditor.

Conversion Agent Event Preferences

On the Conversion Agent Events page of the Preferences window, you canconfigure the display in the Events view.

The preferences have no effect on the content of the event log. To configure the logcontents, see Project Properties in the Conversion Agent Studio User's Guide.

FiltersLets you display or hide notifications (information events), warnings, andfailures.

Display fieldLets you display the name of the parser, the URL or path of the sourcedocument, and the time.

View typeSets the style of the event displays. The available styles are:


46

Style Description

Flat The events are displayed in an un-indented list.

Tree Displays the events in a tree.

Tree with recursive parsersas siblings

Same as tree, except that the iterations of recursive parsersare displayed as siblings.

Propagate all eventsIf checked, the Events window propagates all the events to parent levels of thenavigation tree. This lets you see which branches of the tree contain failures orwarnings, even before you expand the tree. Note that some events such asfatal errors are propagated by default.

Filter selected events, Propagate selected eventsLets you select individual event types, which should be filtered or propagated.

XSD Editor Preference

You can set the editor that you would like Eclipse to display when you open anXSD schema file from the Conversion Agent Explorer.

1. On the menu, choose Window > Preferences.

2. In the left pane of the Preferences window, expand the tree to displayWorkbench/File Associations.

3. In the upper right pane, select the *.xsd file type.

4. In the lower right pane, select the desired editor.

- To use a simple text viewer, select Extension Point Schema Editor.- To use an external XSD editor, click the Add button and browse to the

program file.

5. Click the Default button to make your selection the default XSD editor.

Conversion Agent Studio in Eclipse Index

47

Index

B

Binary view, 28Browser tab

example pane, 32Microsoft Office documents, 32

C

Component view, 25components

customizing drop-down list, 42in IntelliScript, 33

Conversion Agent Explorer view, 24Conversion Agent Studio

overview, 1Conversion Agent Studio Authoring

perspective, 6Conversion Agent Studio preferences, 44

D

documentationonline, 27

drop-down listcustomizing components, 42

E

Eclipse platformeditors, 4overview, 2perspectives, 4projects, 3views, 4Workbench, 3, 6

Edit menu, 7editors

Eclipse, 4IntelliScript, 30

eventsdisplay preferences, 45

Events view, 27

F

File menu, 7filenames

naming restrictions, 19files

Conversion Agent project, 18

G

global componentscustomizing drop-down list, 42

guided mode, 40enabling by default, 45

H

helpabout IntelliScript, 27displaying Conversion Agent, 11displaying Eclipse, 11

Help menu, 11Help view, 27

I

iconsIntelliScript, 39

identifiersIntelliScript, 39

importing projectsto Eclipse workspace, 20

IntelliScriptcustomizing drop-down list, 42icons used in, 39naming restrictions, 39

IntelliScript Assistant view, 25IntelliScript editing, 35IntelliScript editor

components and properties, 33IntelliScript Editor, 30

guided mode, 40IntelliScript menu, 9


48

K

keyboard shortcuts, 14

M

menuEdit, 7File, 7Help, 11IntelliScript, 9main Eclipse, 7Navigate, 8Project, 8Run, 9Search, 8Window, 10

Microsoft Office documentsviewing in Source pane, 32

N

namesIntelliScript, 39project files, 19

Navigate menu, 8

O

optional propertyselecting on menu, 41

P

perspectiveConversion Agent Studio Authoring, 6

perspectivesEclipse, 4

preferencesConversion Agent Studio, 44

Project menu, 8projects

creating, 15creating new, 7, 12deleting, 19deploying, 22Eclipse, 3files, 18importing existing to workspace, 20opening, 19running, 20selecting active, 20storage location of, 16, 17storing outside workspace, 17

propertiesin IntelliScript, 33

R

Repository view, 29Run menu, 9

S

schema editorsetting preference, 46

Schema view, 29script files

creating or adding, 30multiple, 30renaming, 30

Search menu, 8services

deploying Conversion Agent, 22shortcut bar, 13Source tab

example pane, 31support

contacting, 11

T

Tasks view, 26TGP files

creating or adding, 30toolbars

main, 11Tree tab

example pane, 32

V

viewEvents, 27

views, 23Binary, 28Component, 25Conversion Agent Explorer, 24Eclipse, 4Help, 27IntelliScript Assistant, 25Repository, 29Schema, 29Tasks, 26

W

Welcome pagedisplaying, 11

Window menu, 10wizards

New Project, 15Workbench

Eclipse, 3, 6


49

workspacedefault, 17Eclipse, 3location of, 16moving, 18storing projects outside, 17

workspacesopening multiple, 18

X

XSD editorsetting preference, 46