Batch eWay Intelligent Adapter User’s Guide

SeeBeyond Proprietary and Confidential

PkMS eWay Intelligent Adapter User’s Guide

Release 5.0

Draft Version: SeeBeyond Internal Use Only

PkMS eWay Intelligent Adapter User’s Guide 2 SeeBeyond Proprietary and Confidential

The information contained in this document is subject to change and is updated periodically to reflect changes to the applicable software. Although every effort has been made to ensure the accuracy of this document, SeeBeyond Technology Corporation (SeeBeyond) assumes no responsibility for any errors that may appear herein. The software described in this document is furnished under a License Agreement and may be used or copied only in accordance with the terms of such License Agreement. Printing, copying, or reproducing this document in any fashion is prohibited except in accordance with the License Agreement. The contents of this document are designated as being confidential and proprietary; are considered to be trade secrets of SeeBeyond; and may be used only in accordance with the License Agreement, as protected and enforceable by law. SeeBeyond assumes no responsibility for the use or reliability of its software on platforms that are not supported by SeeBeyond.

SeeBeyond, e*Gate, and e*Way are the registered trademarks of SeeBeyond Technology Corporation in the United States and select foreign countries; the SeeBeyond logo, e*Insight, and e*Xchange are trademarks of SeeBeyond Technology Corporation. The absence of a trademark from this list does not constitute a waiver of SeeBeyond Technology Corporation's intellectual property rights concerning that trademark. This document may contain references to other company, brand, and product names. These company, brand, and product names are used herein for identification purposes only and may be the trademarks of their respective owners.

© 2003 by SeeBeyond Technology Corporation. All Rights Reserved. This work is protected as an unpublished work under the copyright laws.

This work is confidential and proprietary information of SeeBeyond and must be maintained in strict confidence.

Version 20031014231805.

Contents


Contents

Chapter 1

Introduction 5Contents of This Guide 5

Writing Conventions 6Additional Conventions 6

Supporting Documents 7

SeeBeyond Web Site 7

Chapter 2

About the PkMS eWay 8Overview 8

PkMS eWay OTDs 8

Supported Platforms 9

System Requirements 9

Chapter 3

Installing the PkMS eWay 10Installing the PkMS eWay 10

After Installation 11

Chapter 4

Using the PkMS eWay 12Converting XML or DTD Input with the PkMS eWay 12

Building a PkMS XSD to DTD Conversion 12Creating the Connectivity Map 13Creating the PkMS Project and OTD 13Creating the Collaboration Definition 15Creating the Business Logic for The Collaboration Definition 17

Getting the Input Data 17

Contents


Unmarshaling From String 18Mapping the Data 19Marshaling to String 19

Binding the Collaboration Definition and eWays 20Deploying the Project 21

Building a PkMS DTD to XSD Conversion 21Creating the Connectivity Map 21Creating the PkMS Project and OTD 22Creating the Collaboration Definition 24Creating the Business Logic for The Collaboration Definition 24

Getting the Input Data 25Unmarshaling From String 25Mapping the Data 26Marshaling to String 26

Binding the Collaboration Definition and eWays 27Deploying the Project 28

Writing The Output to a File 28

Working with The PkMS eWay Sample 29Importing the Sample Project 29

Index 30

Chapter 1

Introduction

This user’s guide describes how to configure and operate the PkMS eWay Intelligent Adapter, referred to as the PkMS eWay throughout the rest of this document. This document provides information on implementing the PkMS eWay in a typical eGate Integrator environment.

In This Chapter

! Contents of This Guide on page 5

! Writing Conventions on page 6

! Supporting Documents on page 7

! SeeBeyond Web Site on page 7

1.1 Contents of This GuideThis guide contains the following information:

! Chapter 2, “About the PkMS eWay” on page 8 provides an overview of the PkMS eWay.

! Chapter 3, “Installing the PkMS eWay” on page 10 provides an overview of the PkMS eWay.

! Chapter 4, “Using the PkMS eWay” on page 12 describes how to build a PkMS eWay Project.

Message Server Reference Guide 5 SeeBeyond Proprietary and Confidential

Chapter 1 Section 1.2Introduction Writing Conventions

1.2 Writing ConventionsThe following writing conventions are observed throughout this document.

Additional Conventions

Windows Systems

For the purposes of this guide, references to “Windows” will apply to Microsoft Windows Server 2003, Windows XP, and Windows 2000.

Path Name Separator

This guide uses the backslash (“\“) as the separator within path names. If you are working on a UNIX system, please make the appropriate substitutions.

Table 1 Writing Conventions

Text Convention Example

Button, file, icon, parameter, variable, method, menu, and object names.

Bold text ! Click OK to save and close.! From the File menu, select Exit.! Select the logicalhost.exe file.! Enter the timeout value.! Use the getClassName()

method.! Configure the Inbound File

eWay.

Command line arguments and code samples

Fixed font. Variables are shown in bold italic.

bootstrap -p password

Hypertext links Blue text For more information, see “Writing Conventions” on page 6.


Chapter 1 Section 1.3Introduction Supporting Documents

1.3 Supporting DocumentsThe following SeeBeyond documents provide additional information about the ICAN Suite:

! SeeBeyond Integrated Composite Application Network Suite Primer

! eGate Installation Guide

! eGate Integrator User’s Guide

! eGate Integrator Tutorial

! SeeBeyond ICAN Suite Deployment Guide

1.4 SeeBeyond Web SiteThe SeeBeyond Web site is a useful source for product news and technical support information at www.seebeyond.com.


http://www.seebeyond.com/

Chapter 2

About the PkMS eWay

This chapter provides a brief overview of operations and components, general features, and system requirements of the PkMS eWay.

In This Chapter

! Overview on page 8

! Supported Platforms on page 9

! System Requirements on page 9

2.1 OverviewAll eWays provide a communication bridge between the eGate environment and one or more external systems.

For details on using eGate and its user interface, see the eGate Integrator User’s Guide.

The PkMS eWay performs a variety of FTP and FTP-related operations depending on your specific needs, network environment, record-processing, file transfer, and external system requirements.

2.1.1. PkMS eWay OTDsThe PkMS eWay enables eGate to use an FTP connection to exchange data with other network hosts, for the purpose of receiving and delivering objects stored in files. The PkMS eWay provides Object Type Definitions (OTDs) to enable the creation of file transfer operations using FTP.

The PkMS eWay OTDs include an OTD for connecting to external FTP servers, a record-processing OTD, and a local file OTD. The record-processing OTD extracts records out of files, parse files into specific records, and define the content of files as records. The local file OTD picks up or puts data files to local file systems.

Note: The PkMS eWay supports standard FTP according to RFC-959.


Chapter 2 Section 2.2About the PkMS eWay Supported Platforms

2.2 Supported PlatformsThe PkMS eWay is available for the following platforms:

! Windows 2000 SP3

! Sun Solaris 8

2.3 System RequirementsThe system requirements for the PkMS eWay are the same as for eGate Integrator. For information, refer to the eGate Integrator Installation Guide. It is also helpful to review the Readme.txt for any additional requirements prior to installation. The Readme.txt is located on the installation CD-ROM.


Chapter 3

Installing the PkMS eWay

This chapter describes how to install the PkMS eWay.

In This Chapter

! “Installing the PkMS eWay” on page 10

! “After Installation” on page 11

3.1 Installing the PkMS eWayDuring the eGate Integrator installation process, the Enterprise Manager, a web-based application, is used to select and upload products as .sar files from the eGate installation CD-ROM to the Repository.

The installation process includes installing the following components:

! Installing the Repository

! Uploading products to the Repository

! Downloading components (such as Enterprise Designer and Logical Host)

! Viewing product information home pages

Follow the instructions for installing the eGate Integrator in the eGate Integrator Installation Guide, and include the following steps:

1 During the procedures for uploading files to the eGate Repository using the Enterprise Manager, after uploading the eGate.sar file, select and upload the following files:

" PkMSXMLSchemaLibrary.sar (to install the PkMS eWay)

" BatcheWay.sar (to install the Batch eWay)

" FileeWay.sar (to install the File eWay, used in the sample Project)

2 Click DOWNLOADS.

3 Click PKMS XSD ZIP WM OpenSystem V1 SP1. The File Download dialog box appears.

4 Save the file in any directory. This zip file contains the XSD files used when you create Collaboration Definitions.

5 Unzip the file.


Chapter 3 Section 3.2Installing the PkMS eWay After Installation

Figure 1 Download the PKMS XSD ZIP WM OpenSystem V1 SP1 .zip File

6 Continue installing the eGate Integrator as instructed in the eGate Integrator Installation Guide.

3.2 After InstallationOnce you have installed and configured the PkMS eWay, you must then incorporate it into a Project before it can perform its intended functions. See the eGate Integrator User’s Guide for more information on incorporating the eWay into an eGate Project.


Chapter 4

Using the PkMS eWay

This chapter describes how to use the PkMS eWay to convert XML input to custom DTDs and vice versa. It also includes how to use the sample that comes with the PkMS eWay.

In This Chapter

! Converting XML or DTD Input with the PkMS eWay on page 12

! Working with The PkMS eWay Sample on page 29

4.1 Converting XML or DTD Input with the PkMS eWayThis section describes how to use the PkMS eWay to convert XML to custom DTDs and vice versa. As a quick start, the following list provide an overview of the steps taken:

1 Create custom data type definitions (DTDs).

2 Create an eGate Project if necessary.

3 Create a Connectivity Map with an inbound eWay, a Collaboration, and an outbound eWay.

4 Create an Object Type Definition (OTD).

5 Creating the Java Collaboration Definition and its business logic.

6 Bind the newly created Collaboration Definition to the service and connect the Collaboration to the eWays.

7 Configure the eWays if necessary.

8 Create an eGate Environment and Deployment Profile.

9 Deploy and run the Project.

4.2 Building a PkMS XSD to DTD ConversionThis section describes how to create a PkMS Project that receives XSD data from a File eWay, converts the data to DTD and FTPs it to an FTP server.

Cobol Copybook Converter User’s Guide 12 SeeBeyond Proprietary and Confidential

Chapter 4 Section 4.2Using the PkMS eWay Building a PkMS XSD to DTD Conversion

4.2.1. Creating the Connectivity MapThe procedure below describes how to create the Connectivity Map for the PkMS Project.

To create the Connectivity Map

1 In the Project Explorer tab of the Enterprise Designer, right-click the copybook conversion Project, click New, and click Connectivity Map. A blank Connectivity Map appears.

2 Click the eWay icon and click Scheduler.

3 Drag the Scheduler icon to the Connectivity Map to create the inbound eWay.

4 Drag the Service icon to the Connectivity Map.

5 Click the eWay icon and click the File External Application.

6 Drag the File eWay icon to the Connectivity Map to create the outbound eWay.

7 Click the eWay icon and click Batch FTP External Application.

8 Drag the Batch eWay icon to the Connectivity Map to create a second outbound eWay. The Connectivity Map looks similar to the figure below.

Figure 2 PkMS Connectivy Map—XSD to DTD

4.2.2. Creating the PkMS Project and OTDTo create the PkMS Project and OTD

1 In the Project Explorer tab of the Enterprise Designer, right-click the Repository and click New Project.

2 Right-click the new Project, click New, and click Object Type Definition. The New Object Type Definition wizard appears as shown below.



Figure 3 New Object Type Definition Wizard

3 Click XSD and click Next. The Select XSD Files page appears.

Figure 4 Selecting XSD Files

4 In the Look In box, browse to the location where you unzipped the PKMS XSD ZIP WM OpenSystem V1 SP1 zip file.

5 Double-click the XSD file to be used and click Next. The Select Document Elements page appears.



6 Click the elements and click Next. The Select OTD Options page appears.

7 Click Finish. The OTD Editor window displays the newly created OTD similar to the one below.

Figure 5 PkMS Inbound OTD

4.2.3. Creating the Collaboration DefinitionTo create the Collaboration Definition

1 In the Project Explorer of the Enterprise Designer, right-click the COBOL copybook conversion Project, click New and click Java Collaboration Definition. The Java Collaboration Definition wizard appears.

2 In the Collaboration Name box, enter the name for the Collaboration and click Next. The Select Operation page appears as shown below.



Figure 6 Selecting Collaboration Operations

3 Double-click SeeBeyond, eWays, File, FileClient, and click receive as shown below.

Figure 7 Selecting File Receive

4 Click Next.

5 Navigate and double-click the following files:

" SeeBeyond > eWays > File > FileClient

" SeeBeyond > eWays > File > BatcheWay > BatchFTP

" Projectname > ProjectOTDs



The Java Collaboration Definition wizard displays similar to the following:

Figure 8 Selecting OTDs

6 Click Finish. The Java Collaboration Editor window appears.

You can now create the business logic for the Collaboration as described below.

4.2.4. Creating the Business Logic for The Collaboration DefinitionOnce you have created the Collaboration Definition as described in the section above, you can create the business logic for the Collaboration. The business logic for a PkMS Collaboration consist of the following components;

1 Getting the Input Data on page 17

2 Unmarshaling From String on page 18

3 Mapping the Data on page 19

4 Marshaling to String on page 19

Getting the Input Data

The first step in the business logic is to handle the data when it comes into the Project. In this case, you unmarshal the data to String as described below.

To unmarshal text input format

1 Expand BatchFTP_1, right-click Client, and click Select a method to call. A list of methods appears.

2 Click get(). The get box appears as shown below.



Figure 9 Getting Input Data

Unmarshaling From String


3 Right-click the custom conversion OTD, click Select a method to call, and click unmarshalFromString(). The unmarshalFromString box appears.

4 Click the Call New Contructor button. The Call New Contructor dialog box appears.

5 Enter string and press ENTER. The list of string constructs appears as shown below.

Figure 10 Calling a New Constructor

6 Click java.lang.string(byte[] bytes) and click OK.

7 Drag Payload under Client to byte[] bytes in the java.lang.string box.



8 Drag result (String) to in (String) as shown below.

Figure 11 Unmarshaling the Input Data

Mapping the Data

Map the input data to the output data.

Marshaling to String

To marshal data as strings to an output destination

1 Right-click the custom OTD to be marshaled, click Select a method to call, and click marshalToString(). The marshalToString box appears.

2 Drag Result (String) to Text under FileClient_1 as shown below.



Figure 12 Marshaling Data to String

4.2.5. Binding the Collaboration Definition and eWaysOnce you have created the Collaboration and its business logic as described in the section above, you can bind the new Collaboration Definition to the Service, and then connect the Collaboration to the eWays.

To bind the Collaboration Definition and eWays

1 From the Project Explorer of the Enterprise Designer, drag the newly created Collaboration Definition to the Service in the Connectivity Map as shown below.

Figure 13 Binding the Collaboration Definition and Service

2 Double-click the Service icon. The Service1 window appears.

3 Drag the Scheduler service to the Scheduler eWay.

4 Drag the BatchFTP service to the Batch eWay.

5 Drag the FileClient service to the File eWay. The binding windows looks similar to the figure below.


Chapter 4 Section 4.3Using the PkMS eWay Building a PkMS DTD to XSD Conversion

Figure 14 Connecting the Collaboration to the eWays

6 Close the Service1 window and click Save.

4.2.6. Deploying the ProjectOnce you have completed the Connectivity Map binding, you must do the following to finish the Project:

1 Configure the eWays as described in the eWay documentation.

2 Create an Environment and Deployment Profile and run the Project as described in the eGate Integrator User’s Guide.

4.3 Building a PkMS DTD to XSD ConversionThis section describes how to create a PkMS Project that receives DTD data and converts the data to XSD.

4.3.1. Creating the Connectivity MapThe procedure below describes how to create the Connectivity Map for the PkMS Project.



To create the Connectivity Map

1 In the Project Explorer tab of the Enterprise Designer, right-click the copybook conversion Project, click New, and click Connectivity Map. A blank Connectivity Map appears.

2 Click the eWay icon and click the File External Application.

3 Drag the File eWay icon to the Connectivity Map to create the outbound eWay.

4 Drag the Service icon to the Connectivity Map.

5 Click the eWay icon and click Batch FTP External Application.

6 Drag the Batch eWay icon to the Connectivity Map to create a second outbound eWay. The Connectivity Map looks similar to the figure below.

Figure 15 PkMS Connectivy Map—DTD to XSD

4.3.2. Creating the PkMS Project and OTDTo create the PkMS Project and OTD

1 In the Project Explorer tab of the Enterprise Designer, right-click the Repository and click New Project.

2 Right-click the new Project, click New, and click Object Type Definition. The New Object Type Definition wizard appears as shown below.



Figure 16 New Object Type Definition Wizard

3 Click DTD and click Next. The Select DTD Files page appears.

Figure 17 Selecting DTD Files

4 In the Look In box, browse to the location where the custom DTDs reside.

5 Double-click the DTD file to be used and click Finish. The OTD Editor window displays the newly created OTD



4.3.3. Creating the Collaboration DefinitionTo create the Collaboration Definition

1 In the Project Explorer of the Enterprise Designer, right-click the COBOL copybook conversion Project, click New and click Java Collaboration Definition. The Java Collaboration Definition wizard appears.

2 In the Collaboration Name box, enter the name for the Collaboration and click Next. The Select Operation page appears as shown below.

Figure 18 Selecting Collaboration Operations

3 Double-click ?

4 Click Next.

5 Navigate and double-click the following files:

" SeeBeyond > eWays > File > BatcheWay > BatchFTP

" Projectname > ProjectOTDs

6 Click Finish. The Java Collaboration Editor window appears.

You can now create the business logic for the Collaboration as described below.

4.3.4. Creating the Business Logic for The Collaboration DefinitionOnce you have created the Collaboration Definition as described in the section above, you can create the business logic for the Collaboration. The business logic for a PkMS Collaboration consist of the following components;

1 Getting the Input Data on page 17

2 Unmarshaling From String on page 18



3 Mapping the Data on page 19

4 Marshaling to String on page 19

Getting the Input Data

The first step in the business logic is to handle the data when it comes into the Project. In this case, you unmarshal the data to String as described below.


1 Expand BatchFTP_1, right-click Client, and click Select a method to call. A list of methods appears.

2 Click get(). The get box appears as shown below.

Figure 19 Getting Input Data

Unmarshaling From String


3 Right-click the custom conversion OTD, click Select a method to call, and click unmarshalFromString(). The unmarshalFromString box appears.

4 Click the Call New Contructor button. The Call New Contructor dialog box appears.

5 Enter string and press ENTER. The list of string constructs appears as shown below.



Figure 20 Calling a New Constructor

6 Click java.lang.string(byte[] bytes) and click OK.

7 Drag Payload under Client to byte[] bytes in the java.lang.string box.

8 Drag result (String) to in (String) as shown below.

Figure 21 Unmarshaling the Input Data

Mapping the Data

Map the input data to the output data.

Marshaling to String

To marshal data as strings to an output destination

1 Right-click the custom OTD to be marshaled, click Select a method to call, and click marshalToString(). The marshalToString box appears.



2 Drag Result (String) to Text under FileClient_1 as shown below.

Figure 22 Marshaling Data to String

4.3.5. Binding the Collaboration Definition and eWaysOnce you have created the Collaboration and its business logic as described in the section above, you can bind the new Collaboration Definition to the Service, and then connect the Collaboration to the eWays.

To bind the Collaboration Definition and eWays

1 From the Project Explorer of the Enterprise Designer, drag the newly created Collaboration Definition to the Service in the Connectivity Map as shown below.

Figure 23 Binding the Collaboration Definition and Service

2 Double-click the Service icon. The Service1 window appears.

3 Drag the Scheduler service to the Scheduler eWay.

4 Drag the BatchFTP service to the Batch eWay.

5 Drag the FileClient service to the File eWay. The binding windows looks similar to the figure below.



Figure 24 Connecting the Collaboration to the eWays

6 Close the Service1 window and click Save.

4.3.6. Deploying the ProjectOnce you have completed the Connectivity Map binding, you must do the following to finish the Project:

1 Configure the eWays as described in the eWay documentation.

2 Create an Environment and Deployment Profile and run the Project as described in the eGate Integrator User’s Guide.

Writing The Output to a File

If you are using a File eWay for the output of the copybook conversion Project, you can use the method below to write the output to a file.

To write the output to a file

1 Right-click FileClient_1 in the input column, click Select a method to call, and click write().

2 Click Save.

3


Chapter 4 Section 4.4Using the PkMS eWay Working with The PkMS eWay Sample

4.4 Working with The PkMS eWay SamplePkMS eWay includes a sample that you can import to see how a PkMS conversion can be set up. The sample is provided as a zip file, PkMS_eWay_Sample.zip, on the installation CD-ROM. This zip file contains:

! A zip file with an exported Project that you can import (WM_Sample.zip)

! An input file

4.4.1. Importing the Sample ProjectThe installation CD-ROM includes a sample Project for the PkMS eWay. To import the Project into Enterprise Designer, follow the steps below.

To import the sample

1 Copy PkMS_eWay_Sample.zip from the samples directory on the installation CD-ROM to a temporary directory.

2 Unzip the file to the temporary directory.

3 In the Project Explorer tab of the Enterprise Designer, right-click the Repository and click Import Project. The Select File to Import dialog box appears.

4 Browse to the temporary directory.

5 Double-click WM_Sample.zip. The File Destination dialog box appears.

6 Click Import to a new Project, enter the name of the Project, and click OK.

7 When the import has successfully completed, right-click the Repository and click Refresh All from Repository.

The Project is now imported. Before you deploy and run the Project, do the following:

! Configure the eWays for the correct input and output directories. Refer to the eWay documention for more information.

! Create an Environment and Deployment Profile, and run the Project. Refer to the eGate Integrator User’s Guide for more information.


Index


Index

Cconventions

path name separator 6Windows 6

converting files 12

Ddocument

conventions 6document purpose and scope 5

Iimplementation 12

Oorganization of information, document 5

SSeeBeyond Web site 7supporting documents 7

Ttechnical support

SeeBeyond Web site 7

Uusing Cobol Copybook Converter 12

Wwriting conventions 6