B2Bi 1.4.0 AMTrixMigrationGuide AllOS En

15 October 2010

MIGRATION GUIDE

Axway B2Bi Version 1.4

from AMTrix 4.4.3

Copyright © 2010 Axway Software S.A.

All rights reserved.

This documentation describes the following Axway software:

Axway B2Bi.

No part of this publication may be reproduced, transmitted, stored in a retrieval system, or translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise,

without the prior written permission of the copyright owner, Axway Software S.A.

This document, provided for informational purposes only, may be subject to significant modification. The descriptions and

information in this document may not necessarily accurately represent or reflect the current or planned functions of this product. Axway Software S.A. may change this publication, the product described herein, or both. These changes will be

incorporated in new versions of this document. Axway Software S.A. does not warrant that this document is error free.

Axway Software S.A. recognizes the rights of the holders of all trademarks used in its publications..

The documentation may provide hyperlinks to third-party web sites or access to third-party content. Links and access to

these sites are provided for your convenience only. Axway Software S.A. does not control, endorse or guarantee content found in such sites. Axway Software S.A. is not responsible for any content, associated links, resources or services

associated with a third-party site.

Axway Software S.A. shall not be liable for any loss or damage of any sort associated with your use of third-party content.

Migration Guide Preface 3

Preface 3

Preface

D I S C L A I M E R

This guide assists you in migrating data from AMTrix to the Axway B2Bi solution. Because

these two products do not have the same data structure, it may not be possible to migrate all data.

The Migration Tool runs AMTrix code through the B2Bi integration engine (Synchrony

Integrator), wrapped inside a Message Builder Component (MBC). Any Message Builder version 5 (MB5) statements that are not changed by the tool, must be changed manually.

The Migration Tool is useful only when you have large or a large number of Programming Tool

maps that need to be converted in a short amount of time. Alternatively, you can migrate to Mapping Services Maps and MBC's.

The AMTrix Programming Tool map source code can be very large (thousands of lines of code).

If a change is needed at a future date, it will be very difficult to go through all the lines of code. This will be the case, for example, if a file structure change is required or if something

needs to be remapped. It is better to manually remap the Programming Tool maps in Mapping Services.

P U R P O S E O F T H I S M A N U A L

This guide describes how to migrate the following AMTrix 4.4.3 elements to Axway B2Bi:

AMTrix Programming Tool maps

Datamapper maps

Partner profiles and agreements

This documentation sometimes refers you to the AMTrix, Gateway Interchange or Integrator documentation.

W H O S H O U L D R E A D T H I S M A N U A L

This guide is intended for users who wish to migrate from AMTrix 4.4.3 to Axway B2Bi.

A S S U M E D K N O W L E D G E

In this guide, we assume that you have a good understanding of:

Synchrony Integrator V3

Synchrony Gateway Interchange

AMTrix

To learn about Integrations and Creator MBCs, refer to the Synchrony Integrator

documentation.

Migration Guide Preface 4

Preface 4

R E L A T E D D O C U M E N T A T I O N

Axway B2Bi is accompanied by a complete set of documentation, covering all aspects of using

the solution. These documents include the following:

Implementation Guide

Gateway Interchange Admin Guide

Application Interfaces Guide

Migration from Gateway Interchange Guide

Release Notes

All Axway B2Bi documentation is available from the Axway Support website: https://support.axway.com

https://support.axway.com/

Migration Guide Contents 5

Contents

1 Prerequisites 8

1.1 Axway B2Bi prerequisites 8

1.1.1 General 8 1.1.2 Migrating DPS Programs 8

2 Migrating DPS programs 9

2.1 Migration concepts 9

2.1.1 Initial considerations 9

2.2 Migration tools 10

2.2.1 Migration development environment 11 2.2.2 Using the Migration Cross Compiler 11 2.2.3 The Migration Cross Compiler configuration file 13 2.2.4 Starting the Migration Cross Compiler 13 2.2.5 Compiling the maps 13

2.3 Updating old programs 14

2.3.1 Overview 14 2.3.2 Updating DPS programs 14 2.3.3 Updating loadable programs 16 2.3.4 Summary of program changes 19

2.4 Example: migrating a DPS program 20

2.4.1 Sample code 20 2.4.2 Prerequisites 21 2.4.3 Example step 1: Using the Migration Cross Compiler 21 2.4.4 Example step 2: Making changes for the migration 22 2.4.5 Example step 3: Manually changing the template 23 2.4.6 Example step 4: Generating the migrated map 24 2.4.7 Example step 5: Registering the migrated map in Axway B2Bi 24 2.4.8 Example step 6: Using the migrated map in Axway B2Bi 24

3 Migrating Datamapper maps 26

3.1 About Datamapper maps 26

3.2 Migrating AMTrix XML Datamapper Maps 26

3.3 Importing application pickups 27

3.4 Upgrading XML Version 1 Datamapper Maps 27

3.5 Migration procedure for Datamapper maps 27

3.6 Supported PGM statements in B2Bi 28

3.7 In case of problems… 28

4 Migrating Partners and Agreements 29


4.1 Agreements to Integrations 29

4.1.1 Flow-related migration restrictions 29 4.1.2 Additional migration restrictions 30

4.2 Retrieving an AMTrix configuration 30

4.2.1 Running amtrixcfg2xml.x4 30 4.2.2 amtrixcfg2xml.x4 program arguments 30

4.3 Converting the AMTrix configuration to B2Bi configuration 31

4.3.1 Setting the enviroment 31 4.3.2 Running the migration program 31 4.3.3 Results of the migration program execution 33 4.3.4 Step-by-step procedure 36

4.4 Importing Application Pickups 37

4.5 Importing Communities and Partners 37

4.6 Migrating partners 38

4.6.1 Mapping AMTrix local partner to Gateway Interchange Community 38 4.6.2 Mapping AMTrix remote partner to Gateway Interchange Partner 38

4.7 Migrating agreements 39

4.7.1 General migration restrictions 39 4.7.2 Inbound EDIFACT Envelope Agreement, IEE 40 4.7.3 Outbound EDIFACT Envelope Agreement, OEE 41 4.7.4 Outbound EDIFACT Document Agreement, OED 42 4.7.5 Inbound EDIFACT Gateway Agreement, IEG 42 4.7.6 X12 Envelope Agreements IXE, IXD, OXE, OXD, IXG 43 4.7.7 In-house Agreement, INH 43 4.7.8 In-house Gateway Agreement, INHG 44 4.7.9 Native Agreement, NAT 45 4.7.10 Native Agreements: Analysis 46

4.8 Migrating the map conversion programs 49

5 Migrating AMTrix In-house detectors 50

5.1 Overview of the migration 50

5.2 Attribute descriptions 51

6 Migrating AMTrix programs 53

7 Appendix 55

7.1 AMTmig attributes 55

7.1.1 Attributes 55 7.1.2 GetAMTmigAttributes 56 7.1.3 SetAMTmigAttributes 56

7.2 Translated commands 56

7.2.1 Program arguments 56 7.2.2 RECEIVE and SEND 56 7.2.3 AMTRIX module 58 7.2.4 TRANSFER module 59 7.2.5 PGM module 60

7.3 Migration interface 62


7.3.1 Description of migration interface 62 7.3.2 New functions and statements 63

Migration Guide Prerequisites 8

1 Prerequisites

I N T H I S C H A P T E R

This chapter describes the prerequisites for migrating from AMTrix 4.4.3 to Axway B2Bi 1.4.

1.1 Axway B2Bi prerequisites

1.1.1 General

Before migrating, start the Integrator tasks in the Axway B2Bi user interface, to register

the migrated map.

From the System Management page:

1. Click the tab Subsystem.

2. Click Start.

3. Click Ok.

1.1.2 Migrating DPS Programs

Copy the DPS or loadable program to be migrated to the migration directory:

%CORE_ROOT%\solutions\b2bx\migration\dps

Then, copy the migration directory: %CORE_ROOT%\solutions\b2bx\migration

Into: %CORE_LOCAL%

Migration Guide Migrating DPS programs 9

2 Migrating DPS programs


This chapter introduces the task of migrating AMTrix map programs to Axway B2Bi and explains some of the concepts related to migration.

The main task in the migrating from AMTrix to Axway B2Bi is to migrate Message Builder programs, which are mainly maps, to Synchrony Integrator. If these maps were

created with Datamapper, it is very easy to regenerate and recompile them in Integrator. However, if they were created using the AMTrix Programming Tool, or if

they were handwritten, it is not possible to simply recompile them in Integrator.

In AMTrix, loadable maps and DPS programs have a special structure with special

sections for communication with the AMTrix system. The same is true for Message Builder Components (MBC) in Integrator. But the structure of these two map types is

completely different due to fundamental differences between Integrator and AMTrix. For

example, in Integrator there are no DPS programs running permanently, all maps and programs are loadable programs. Also, AMTrix is based on Message Builder Language

version 5 (MB5) while Integrator uses Message Builder Language version 6 (MB6).

Because of the different operating concepts, many statements in AMTrix are not

available in Integrator:

Integrator has no router (and no routing information like sender, recipient and

message type)

Integrator has no Optional Data – instead it has Attributes, which work differently

The modules that are frequently used: AMTRIX, PGM and TRANSFER are not

available in Integrator

2.1 Migration concepts

2.1.1 Initial considerations

The following questions and answers should help explain the migration concept that has been developed.

AMTrix is running on MB5 and Integrator is running on MB6. Can we simply recompile the code with the MB6 compiler?

No. In this case, the AMTrix libraries are not available in Integrator. It is necessary to have a special compiler environment for these old programs, which include old AMTrix

libraries.

If we have this type of environment and recompile the old programs, what can we do with them?

We cannot load them into Integrator, so we cannot use them. The structure of these programs is very different from the postulated structure of MBCs. On one hand,

modules and routines for inter-communication are missing. On the other hand, the


programs contain a lot of routines to communicate with the AMTrix environment (for example, the router), which are not available in Integrator.

Can we load the old programs into an MBC so that it runs inside of it?

This is possible. In the beginning, an MBC was created which simply called the old MB6

recompiled AMTrix programs. The problem was that the old AMTrix programs did the

conversion but nothing more. All routines of the AMTRIX and TRANSFER modules were

doing nothing or resulted in errors.

Can we simulate an AMTrix environment inside the Caller MBC to make sure that most of the old functions and statements work in the expected way?

This constitutes a major part of the migration task. To do this it is necessary to rewrite the libraries and build up a communication interface from the Caller MBC (AMTrix

Migration Caller MBC) to the old program. For example, the optional data does not exist any longer and has to be translated into attributes in Integrator.

Some statements do not work anymore or do nothing because they make no sense. Most statements and functions work internally, but in a different way.

For example, you can read and write optional data using the AMTRIX routines but the

optional data does not exist any more, the changed values are be translated into

Integrator attributes. Or you can send a file using the TRANSFER routines but the file

will only be marked to send. The sending itself is done by the Caller MBC. On the other hand, it is not possible to jump between routing sequences by addressing a new sender,

recipient and message type because this information no longer exists in the Integrator integration, so this has to be configured in the integration itself.

Does this mean that we have to rewrite all maps and how much work or time

must we invest?

Some statements and functions should no longer be used. For example, an EXIT would

stop the whole Processing Engine. There are also statements which should be checked to see if they are used in the right way. Frequently-used environment variables (like

AMTRIX_DATA which is now CORE_DATA) are not available anymore.

To make the task easier, we have created a Cross Compiler. This tool analyzes the code

and provides information and warnings if something should be changed, and it performs

certain changes itself (for example it replaces the AMTrix environment variables with the Integrator environment variables). You receive a list of items from the Cross

Compiler that you should validate.

Additionally, there is a modest amount of work to do on each program. This includes

creating one new include file. In sum, there is not a lot of work to do to migrate these old maps and programs.

2.2 Migration tools

A caller template, AMTMigMap.s4, is compiled with the old (changed) map code. The

result is a normal creator MBC that may use the whole Integrator environment. The

migrated maps are MBCs themselves and do not need to be recompiled when another map needs more data from the HME environment.

This section describes the following Migration tools and explains how to install them as well as how to use them:

The migration development environment: the environment that is used to

recompile old programs. This environment contains compatibility libraries that enable the use of old programs in Synchrony Integrator.


The Migration Cross Compiler: helps find and exchange commands that must be changed or that are no longer available in old programs.

2.2.1 Migration development environment

To compile AMTrix programs for Integrator, you need a special compilation environment. This environment is an add-on to the Integrator development

environment. It contains additional include and library files that are used to make AMTrix functions and statements available under Integrator.

The old programs still have AMTrix functions and statements that the Integrator system cannot understand. Under Integrator, you cannot compile these programs because not

all of the AMTrix specific statements are available. The migration environment is an

addition to your Integrator development environment that provides all of the old AMTrix

statements, for example TRANSFER.ReceiveFile and TRANSFER.SendFile.

When a program is compiled, the compiler searches for the include and library files in

the directories specified by the environment variables EDI_INCLUDE and EDI_LIB. For

the migration development environment these environment variables get new values so that they point to the Migration include and library files. Now if a program is compiled

the compiler first looks at the migration files and takes them.

If you now call the compiler it first searches in the migration libraries to find the statements you are using. If it cannot find a statement or function in the migration

environment it searches in the Integrator environment.

This is only needed for the migration, so we set up command and shell windows

(pgmMigration.bat and pgmMigration.sh) where the programs can be compiled and

tested and where some AMTrix system environment variables can be set, for example

to test database access. So the Integrator environment is still available too.

The archive where we can find the migration directory and its related lib and include

files has the following structure:

%CORE_SOLUTIONS%

+---4edi

| +---include Contains the compatibility include files

| +---lib Contains the compatibility libraries

| +---pgm

| +---mcc.x4

| +---HBLIB.x4

+-/b2bx/migration/dps

| +---pgmMigration.bat Command window in which you type

migration commands (r4edi, c4edi)

| +---mcc.ini Configuration file for mcc.x4

| +---AMTmigMap.s4 Template file

The Migration Cross Compiler (mcc)

2.2.2 Using the Migration Cross Compiler

When using the AMTrix Migration Caller, there are some old statements which should not be used and some statements which have to be replaced by new compatibility

statements. There are also some statements that should be checked to see if they still

work as required.

For example, you should not use the statement SLEEP or EXIT anymore. And, EXIT

should be replaced by a THROW statement because an exit would stop the Integrator

Processing Engine.


If a program runs as a DPS under AMTrix, an EXIT would only stop the single DPS

program and the Process Manager would restart the program again because each DPS

runs as a single system task. But now the programs are loadable and run in the Integrator Processing Engine.

The statements RECEIVE and SEND do not exist anymore because under AMTrix these

statements were built- in statements and are not available under Integrator. Built-in means that they are coded in the interpreter itself and not as a Message Builder library.

They now are replaced by Message Builder library statements RECEIVE_STRING and

SEND_STRING or RECEIVE_FILE and SEND_FILE. For more information, refer to RECEIVE

and SEND in the Translated commands chapter.

Another example is the SQL Statements which have to be checked if they still work. If

they are using the AMTrix configuration tables they may not work any more. The same

is true of the function UNIQUE_ID.

If a program uses the AMTrix environment variables such as $AMTRIX or $AMTRIX_DATA

these variables have to be replaced by the $CORE variables.

To do all this work manually would take a lot of time to find and replace the old

commands. The Migration Cross Compiler can help you.

The Migration Cross Compiler takes old source, checks it, produces a report and replaces some critical statements, functions and environment variables. For example,

the SEND statement is replaced by the new one, or, the $AMTRIX environment variables

are replaced by the $CORE variables.

An example report from the Migration Cross Compiler:

Report of Converting:

==========================================================================

Line No S/D: Message:

--------------------------------------------------------------------------

2426/ 2429 INFO: FUNCTION declared -> REMOVE_BLANKS_AND_DOTS

2441/ 2444 INFO: FUNCTION declared -> SPECIAL_DOS_TO_ANSI

2485/ 2488 INFO: FUNCTION declared -> EAN_TO_ERZEUGNISNUMMER

2494/ 2497 WARNING: DATABASE Statement found. May not work!

2512/ 2515 WARNING: EXEC Statement found. May not work!


3331/ 3339 INFO: d_EDIFile.LogDebug replaced by PGM.logDEBUGFile!

3338/ 3346 INFO: STATEMENT declared -> ProcessInterchange

3608/ 3616 INFO: Import variable "AMTRIX_DB" is not set under TSIB!









The report provides the line numbers of the source, the destination code and gives

information or warnings.


2.2.3 The Migration Cross Compiler configuration file

To control the behavior of the Migration Cross Compiler you can edit the configuration

file called mcc.ini. When the Migration Cross Compiler is started, it first reads the

configuration file from the current directory.

The following options are available:

Option Description

CheckOnly=0 This parameter states that the Cross Compiler gives no output

file. But it creates a log file about all items found.

FormatCode=0 If this option is set to 1 (true), the Cross Compiler tries to

reformat the code. In this case, the Indent option has to be set to

a value greater than zero.

Indent=3 Sets the indent of the code, if you have set the option

FormatCode to true.

DelPragma=1 Comments out all PRAGMA statement lines which redefine the line

numbers and source code name. This is useful if you want to get

the exact line number while compiling the code.

ListStatements=0 If this option is set to true, all used functions and statements are listed.

BraceNL Option used in convert.s4h to trigger the insertion of a New Line

(Line Feed) to the output BEFORE an opening brace " { "

Example configuration file:

CheckOnly=0

FormatCode=1

Indent=2

BraceNL=1

DelPragma=1

ListStatements=1

2.2.4 Starting the Migration Cross Compiler

To start the Migration Cross Compiler, use the following command:

r4edi mcc.x4 <input file> <output file>.s4m <log file>

input file is the source file you want to cross compile

output file is the result of the cross compiling

log file is the log of the cross compiling

If the option CheckOnly is set to true, the output file can be left out so that the call

command is:

r4edi mcc.x4 <input file> <log file>

2.2.5 Compiling the maps

There is a migration template (AMTmigMap.s4), which must be used to migrate

Programming Tool maps. The template has to be copied and renamed to the map


name. In this template, the variable parts with “XXXXX” have to be changed to <map-name>.

INCLUDE "XXXXX_XIB.s4m" ONCE;

. . .

. . .

To compile the map, use the following command:

c4edi -T -o <map-name>.x4 <map-name>.s4

The compiled map can now be used in the Axway B2Bi configuration, just like any other

MBC. Refer to the Axway B2Bi Implementation Guide.

2.3 Updating old programs

This section describes the changes required to old AMTrix programs.

2.3.1 Overview

There are two types of program in AMTrix: DPS and loadable programs. Both types of program have to be changed. They need the Communication Interface to the Caller

MBC. The reason for this is that the Caller MBC needs an entry point which is an interface statement that has to be defined in the old program and which transfers

information to and from the old program. This new interface statement calls the map statements in loadable maps.

For DPS programs the main program has to be changed to become a statement so that

the interface statement can call the main program.

The interface statement is placed in an include file so that you only include a new file

and the map is ready to communicate with the Caller MBC.

2.3.2 Updating DPS programs

Usually DPS (Data Processing Stage) programs are constructed by using a main

program which is embedded in an endless loop. This endless loop has to be removed because the program now will be called once for each conversion by the Caller MBC.


A new procedure has to be added which calls the old main program. And this means that the old main program has to become a statement (as the figure above shows).

The following example is typical DPS code as generated by the Designer.

# initialization statements e.g. importing or setting variables

INCLUDE"pgmmodule2.s4"

IMPORT "AMTRIX_DB" INTO $AmtrixDB;

TRUNCATE ON;

WHILE 1 { # main loop

$PGM_Exception="";

TRANSFER.ReceiveFile; # Receive and open input file

OPEN FILE INPUT $EdiFile TEXT;

TRANSFER.GetInfo 0 SOURCE $Source DESTINATION $Destination SUB $DestSub ;

TRANSFER.CreateFile; # Create and open output file

# conversion statements

TRANSFER.SendFile;

TRANSFER.DeleteFile;

IF $PGM_Forever=PGM.$False {

IF PGM.InterchangeCount()>0 { IF PGM.InterchangeCount()+1>$PGM_MaxIC {

BREAK; }}

}

} # Main loop

This code has to be changed in the following way:

INCLUDE "migrationDPS.s4" ONCE;

INCLUDE"pgmmodule2.s4"

DECLARE MODULE INTERFACE MBC_GENERICPROPERTYSTAGE {}

DECLARE STATEMENT OLD_MAIN {

# initialization statements e.g. importing or setting variables

IMPORT "AMTRIX_DB" INTO $AmtrixDB;

TRUNCATE ON;

# -> WHILE 1 { # main loop has to be commented out or deleted

$PGM_Exception="";

TRANSFER.ReceiveFile; # Receive and open input file

OPEN FILE INPUT $EdiFile TEXT;

TRANSFER.GetInfo 0 SOURCE $Source DESTINATION $Destination SUB $DestSub ;

TRANSFER.CreateFile; # Create and open output file

# conversion statements

TRANSFER.SendFile;


/*

-> the BREAK statement also has to be commented out or deleted because


it breaks the endless loop

IF $PGM_Forever=PGM.$False {

IF PGM.InterchangeCount()>0 { IF PGM.InterchangeCount()+1>$PGM_MaxIC {

BREAK; }}

}

*/

RETURN; # return of statement OLD_MAIN!

} # End of Main loop is now end of statement OLD_MAIN

The first step is to include the interface statement. For DPS programs you only include

the file migrationDPS.s4 to do this. It should be placed before pgmmodule2.s4

because it defines variables the PGM module needs.

The second step is to force the inclusion of the interface MBC_GENERICPROPERTYSTAGE().

The parameters that are needed by the migrated program will show up when you add a

new processing step in the Axway B2Bi interface.

The third step is to change the entire main program to a statement called OLD_MAIN.

This means that the initialization part and the part inside the endless loop (WHILE 1)

must be included in one statement. The name of this statement is important because it

is called from the interface statement, which is defined in the include file.

The final step is to delete the endless loop. The program is called for each conversion and does not have to wait for a new conversion, like it did running as a DPS under

AMTrix. Therefore, the main endless loop has to be deleted. At the end of the main

program there may be IF statements which would, in some cases, break the endless

loop. Delete these IF statements.

Note: The new main statement must have a RETURN at the end.

2.3.3 Updating loadable programs

Loadable programs which are generated with the AMTrix Designer tool also have a

special structure which makes it very easy to change them. In most cases it is enough

to include the file migrationLoadable.s4.

Here is a code example:

DECLARE $PGM_SOURCE=SOURCEFILE() CONSTANT STRING;

/*

* Constant declarations

*/

DECLARE $True=1 CONSTANT INTEGER;

DECLARE $False=0 CONSTANT INTEGER;

DECLARE $EDI="EDI" CONSTANT STRING;

DECLARE $File="File" CONSTANT STRING;

DECLARE $SupportedInterfacesFromEdi[] = {"CONVERTER_FROMEDI_PROG"}

CONSTANT STRING;

DECLARE $SupportedInterfacesFile[] = {"CONVERTER_FILETOFILE_PROG"}

CONSTANT STRING;

DECLARE $SupportedInterfacesToEDI[] = {"CONVERTER_TOEDI_PROG"} CONSTANT

STRING;


/*

* Global declarations

*/

DECLARE $Input STRING;

DECLARE $Output STRING;

DECLARE $PGM_Exception STRING;

INCLUDE "error.s4h" ONCE;

INCLUDE "sysinfo.s4h" ONCE;

INCLUDE "amtrix.s4h";

INCLUDE "pgmmodule2.s4" ONCE;

INCLUDE "FILE_IN.s4t";

INCLUDE "FILE_OUT.s4t";

/*------------------------------------------------------------------------

Statement for primary initialize type of conversion.

------------------------------------------------------------------------*/

DECLARE STATEMENT InitConversion {

SetupConversionTypeFileToFile;

PGM.SetUpSeparators;

# - Prepare debugging

PGM.DisableDebug; # No debug

# - Prepare for EDI input

PGM.DisableCodeVerification; # No codes are checked

RETURN;

}

/*------------------------------------------------------------------------

The conversion

------------------------------------------------------------------------*/

DECLARE STATEMENT ProcessInterchange {

TRY {

PGM.OpenInput;

PGM.OpenOutput;

Conversion statements

}

CATCH $exc

WHEN OTHERS { $PGM_Exception=$exc; }

# - Error handling ---------------------------------------

IF $PGM_Exception<>"" {

$PGM_Exception=""; # ignore error

}

IF $PGM_Exception<>"" { THROW $PGM_Exception; }

RETURN;

} # end of ProcessInterchange

Now there are some statements generated by the Designer tool which are usually never

touched by the programmer and which are only listed here (without the statement body):

DECLARE STATEMENT SetupConversionTypeEDIToEDI


DECLARE STATEMENT SetupConversionTypeEDIToFile

DECLARE STATEMENT SetupConversionTypeFileToFile

DECLARE STATEMENT SetupConversionTypeFileToEDI

DECLARE STATEMENT MODULE_INIT

DECLARE STATEMENT GetInterfaceInfo

DECLARE STATEMENT Init IN $Debug StoreSocket IN $socket

DECLARE STATEMENT Terminate

DECLARE STATEMENT GetProgramInfo

DECLARE STATEMENT ConvertFromEDIDocument

DECLARE STATEMENT ConvertFileToFile

DECLARE STATEMENT ConvertToEDIDocument

Note the last four statements in this example: GetProgramInfo and the three Convert

routines. The first Convert routine specifies the type of conversion (from EDI, to EDI or

In-house conversion). The right conversion routine for this type must be called. These conversion statements set some conditions for the program and then call the

ProcessInterchange statement in the first part of the code.

Now we need one statement which is doing just this and this is done by the

communication entry point statement. This statement is defined in the include file

migrationLoadable.s4. Add this include file to the source immediately before

pgmmodule2.s4:

...

INCLUDE "migrationLoadable.s4" ONCE;


INCLUDE "FILE_IN.s4t";

INCLUDE "FILE_OUT.s4t";

...



2.3.4 Summary of program changes

A communication entry point for the AMTrix Migration Caller communicates with the old

map program. This is a statement called Mig21_Conversion which is declared in the

AMTrix Migration Caller MBC as an external statement and has to be defined in the called map as an external usable statement.

This is done by including the migration include file.

In old DPS programs the include file migrationDPS.s4 is used and here the migration

statement calls the OLD_MAIN statement which has to be created in the old DPS

program.

In loadable maps the include file migrationLoadable.s4 is used and here the

migration statement first calls the GetProgramInfo statement to find out which type of

conversion program it is and then it calls the right conversion statement.

There may also be statements in the old programs which are not valid any more or

which may result in problems. These statements and functions have to be found and changed. To help you make these changes, use the Migration Cross Compiler (described

in the Migration tools chapter).


2.4 Example: migrating a DPS program

This section describes how to migrate a DPS program using a simple program as an example.

2.4.1 Sample code

/*------------------------------------------------------------------------

program: filter.s4

Filter program: filters all records which do not start with Argument 1

Call: r4edi filter.x4 <prefix>

Example: r4edi filter.x4 CUST -> only records which starts with CUST will

be used

------------------------------------------------------------------------*/

INCLUDE "error.s4h";


DECLARE $TxtBuffer STRING;

DECLARE $NumLines INTEGER;

DECLARE $StrFilter STRING;

DECLARE $LenFilter INTEGER;

IF NOT ARGUMENTCOUNT() {

LOG "Please enter the argument" TYPE "ERROR";

EXIT 1;

}

$StrFilter = ARGUMENT(1);

$LenFilter = STRLEN($StrFilter);

WHILE 1 {

TRANSFER.ReceiveFile;

TRANSFER.CreateFile;

$NumLines = 0;

READ $TxtBuffer UNTIL "\n";

WHILE $error <> $error_ReadEndOfFile {

IF STRLEN($TxtBuffer) >= $LenFilter {

IF STRMID($TxtBuffer,1,$LenFilter) = $StrFilter {

$NumLines = $NumLines + 1;

PRINT $TxtBuffer & "\n";

}

}


}

TRANSFER.SendFile;


LOG "Processed lines: " & $NumLines TYPE "INFO";

}


This program reads a file line-by-line and writes only those lines that begin with a special prefix. The prefix is given to the program by the first program argument.

2.4.2 Prerequisites

Copy the migration directory %CORE_ROOT%\solutions\b2bx\migration\dps into %CORE_LOCAL%

2.4.3 Example step 1: Using the Migration Cross Compiler

The first step is to run the program through the Migration Cross Compiler and look at

the result.

Enter the command:

r4edi mcc.x4 filter.s4 filter.s4m filter.log

The Migration Cross Compiler generates a report:

Report of Converting:

==========================================================================

Line No S/D: Message:

--------------------------------------------------------------------------

14/ 14 CHECK: ARGUMENTCOUNT: replaced by DSG_MIG21.ARGCOUNT()!

16/ 16 CHECK: EXIT found. This command should not be used and be

replaced by 'THROW'!

18/ 18 CHECK: ARGUMENT: replaced by DSG_MIG21.GETARG()!

Look at the program and find out what needs to be changed:

/*------------------------------------------------------------------------




be used

------------------------------------------------------------------------*/







IF NOT DSG_MIG21.ArgCount() {


/* EXIT 1; (Statement should be replaced by THROW) */ THROW"EXECUTE";

}

$StrFilter = DSG_MIG21.GetArg(1);


WHILE 1 {




$NumLines = 0;







}

}


}

TRANSFER.SendFile;



}

The Migration Cross Compiler has changed three lines and replaced the statements as

stated in the report. The arguments now come from the Migration Caller and the normal

argument statements have to be replaced. ARGUMENTCOUNT, for example, would get the

number arguments from the Integrator Processing Engine because it takes the information from the system. But, we need the arguments from the Migration Caller.

The EXIT statement would now stop the whole system process which is the Integrator

Processing Engine. This has to be replaced by something different and the best thing to

use is a THROW statement.

For more information, refer to the Translated commands and Migration interface sections in the Appendix.

2.4.4 Example step 2: Making changes for the migration

In the next step we have to make changes for the migration. This means that we have to put the migration include files and create a statement out of the main program:

The result might look like this:

/*------------------------------------------------------------------------




be used

------------------------------------------------------------------------*/



INCLUDE "migrationDPS.s4";









IF NOT DSG_MIG21.ArgCount() {


/* EXIT 1; (Statement should be replaced by THROW) */ THROW"EXECUTE";

}

$StrFilter = DSG_MIG21.GetArg(1);




$NumLines = 0;







}

}


}

TRANSFER.SendFile;



RETURN;

}

We have to put the include file migrationDPS.s4 before the pgmmodule2.s4 because

the include file pgmmodule2.s4 is not there yet, we should put it there now. As

described before, we also declare the interface MBC_GENERICPROPERTYSTAGE(). The

parameters that are needed by the migrated program will show up when you add a new processing step in the Axway B2Bi interface.

We encapsulate the entire main program in a new statement called OLD_MAIN. Whether

you also include the declarations of the variables or not is not very important in this

example. However, it may be important if you use them in other statements too. In that case global variables should stay global.

2.4.5 Example step 3: Manually changing the template

1. Rename the template file AMTMigMap.s4 to filter.s4.

2. Replace the XXXXX fields in this template file by filter which is the name of the


module program that results after running the Migration Cross Compiler.

3. Add the following lines at the top of the source file:

INCLUDE "migrationDPS.s4";


After the INCLUDE file declaration, add this line to force the inclusion of the generic

property stage module. This way, the parameters that are needed by the migrated program will show up when you add a new processing step in the Axway B2Bi

interface.

DECLARE MODULE INTERFACE MBC_GENERICPROPERTYSTAGE { }

4. Remove the main WHILE loop.

5. Encapsulate the entire old main program in the statement: DECLARE STATEMENT OLD_MAIN { }

6. Add RETURN; at the end of the statement.

2.4.5.1 Note: For a loadable program

Add the following lines at the top of the source file:

INCLUDE "migrationLoadable.s4" ONCE;


After the INCLUDE file declaration add this line to force the inclusion of the generic

property stage module.

DECLARE MODULE INTERFACE MBC_GENERICPROPERTYSTAGE { }

2.4.6 Example step 4: Generating the migrated map

To generate the migrated map, enter: c4edi filter.s4

2.4.7 Example step 5: Registering the migrated map in Axway B2Bi

The migrated map can be used in Axway B2Bi through the B2BX Migration Tools. Depending on its function, it may be configured as a pre-processing step, a map, or a

post-processing step.

To register the MBC in the B2Bi integration engine (Integrator), copy the MBC to the

directory %CORE_LOCAL%/4edi/component.

2.4.8 Example step 6: Using the migrated map in Axway B2Bi

Depending on the type of the migrated map, configure the MBC to be pre-processing,

map, or post-processing:

1. Log in to the Axway B2Bi user interface as Administrator.

2. From the toolbar, click Trading partners, select the partner in question.

3. Select the Messaging profile icon from the partner view.

4. Pick the task Manage processing steps and click Add a processing step.

5. Complete the fields:

The Processing step name

Select the Type of processing step


Select your migrated program in the component field

6. Fill in the necessary arguments (refer to the Attributes section in the Appendix).

Migration Guide Migrating Datamapper maps 26

3 Migrating Datamapper maps


This chapter describes how to migrate DataMapper maps from AMTrix to Axway B2Bi.

3.1 About Datamapper maps

AMTrix Datamapper maps need to be archived in Datamapper builder. The archives

then need to be copied to the Integrator server and opened.

If the map is quite simple, it can be rebuilt in Integrator.

If the map is fairly complex then it will have message builder code in the links and also

in the main code. Any code referencing AMTrix APIs will fail the build process. These APIs must be replaced with appropriate Integrator APIs.

In AMTrix there are 10 different main code templates. In Integrator there are only two main code templates. The table below shows AMTrix main codes and the equivalents in

Integrator.

AMTrix main code Integrator main code

DMcompatible.mc DMnormal.mc

DMcompatibleDPS.mc DMnormal.mc

DMcompatibleDPSMultiple.mc DMnormal.mc

DMcompatibleDPSSingle.mc DMnormal.mc

DMcompatibleMultiple.mc DMnormal.mc

DMcompatibleSingle.mc DMnormal.mc

DMnormal.mc DMnormal.mc

DMnormalDPS.mc DMnormal.mc

DMobject.mc DMobject.mc

DMobjectDPS.mc DMobject.mc

3.2 Migrating AMTrix XML Datamapper Maps

The AMTrix XML Connector 1 and AMTrix XML Connector 2 are almost completely

different in both the development and runtime environments. In AMTrix XML Version 1 you were forced to build any XML maps as an “object map” and also had to have the

CDP runtime environment installed to run the map.

Axway B2Bi only supports automatic migration of Data mapper maps based on the

AMTrix XML version 2.


3.3 Importing application pickups

New file

Pickups.map: Contains a list of AMTrix CSE receive components which are to be

converted into B2Bi pickups. This file is used by the user to define if a AMTrix receive component is to be added in the B2Bi system as an Application pickup or an pickup on

the Community.

3.4 Upgrading XML Version 1 Datamapper Maps

Old XML Version 1 maps can be made to work in B2BX by just rebuilding them first in

the DM Client and secondly in DM Builder, this without having to redo any mappings. If your old map had an XML input that was validated against a DTD, you will have to do

additional changes to get the same level of validation as previously.

One of the main differences between the AMTrix XML version 1 and version 2 is the

validation. In version 1 the validation was during runtime made against the DTD/XDR. In version 2 the validation information needed during runtime is extracted at the

Metadata retrieval and stored in the ADF, the XML code generator is then using this to build in the validation information in the conversion program. This means that you need

to recreate old ADFs containing XML objects, updating the XML parts using the new XML

2 Metadata retriever. If the new ADF has no structural changes there will be no need to redo any of the mappings.

Old maps that contain XML parts, which have been built “by hand”, that is, not using the XML Metadata retriever in the Metadata Browser, will have to be redone to get the

proper validation. Creating a new ADF using the Meta Data Browser and a DTD to recreate the XML part of the ADF should do this.

If you are forced to rebuild your map and the map only consist of an input document and an output document, you should consider redoing the map as a “normal map” and

not building it as an “object map”. In XML Connector version 1 you where forced to do

an “object map” but this is not the case for the new versions were it is possible to build a “normal map”.

3.5 Migration procedure for Datamapper maps

Migrate Datamapper maps as follows:

1. Create an archive using Datamapper builder in the AMTrix installation.

2. Move the archive to the Integrator installation.

3. Open the archive with Datamapper builder.

4. Open the map in Datamapper client, verify the AMTrix specific functions and upate accordingly.

5. Recompile, test and register the map.


3.6 Supported PGM statements in B2Bi

In AMTrix, Datamapper maps run in the context defined by the agreement. In this

context, certain parameters may be set by the user.

In some cases these parameters are retrieved and used during runtime by a

Datamapper-based conversion program. This is made possible using PGM.get calls.

Currently, in B2Bi these calls are automatically migrated. The only change that is required in addition to the usual migration steps, is to add the following line to the

beginning of the main code:

PGM.Initialize $SessionId

MessageId $MessageId;

When the migrated map is registered and used in a B2Bi Document Profile, the

parameters that were used in AMTrix are "converted" into Document Profile attributes.

These attributes have the prefix B2BIBDOC. For example, the attribute File Syntax is

migrated to B2BIDOC_FileSyntax. File Type will be migrated to B2BiPGM_FileSyntax,

and so on.

3.7 In case of problems…

You may encounter problems if libraries are used in the main code or link code which

does not exist in the Integrator installation. This results in compilation errors that need

to be corrected.

Migration Guide Migrating Partners and Agreements 29

4 Migrating Partners and Agreements


This chapter describes agreements to integrations and provides the procedures to migrate

partners and agreements from AMTrix 4.4.3 to Axway B2Bi.

4.1 Agreements to Integrations

The principal objective of the B2Bi AMTrix migration program is to migrate AMTrix B2B

EDI flows between a remote and a local partner. The architecture of the B2Bi Solution system architecture is in some parts different from the AMTrix system. One main

difference is the message flow exchange with partners and the back-end systems. In the B2Bi system the message flow to and from remote partners is done through

Interchange Pickups and Deliveries. The message flow with the backend system is done through Application Pickups and Deliveries running on integration engine (Integrator).

In AMTrix there is not really any difference in the messages flow from partners and from back-end systems.

4.1.1 Flow-related migration restrictions

The following restrictions apply to migrations that are executed with the automated

migration tool. Any agreements not handled by the tool can still be manually migrated into B2Bi integrations.

A local AMTrix partner is treated as a Gateway Interchange Community.

A remote AMTrix partner is treated as a Gateway Interchange Partner.

AMTrix Agreements having both sender and recipient set to a remote partner are not

migrated.

AMTrix Agreements having both sender and recipient set to a local partner are not

migrated.

INH and Native agreements having the sender set to a remote partner are treated as

Inbound Agreements.

INH and Native agreements having the sender set to a local partner are treated as

Gateway Interchange Outbound Agreements.

The CSE send node defined in the routing part of an inbound agreement is treated as

a Gateway Interchange Application Delivery.

The CSE send node defined in the routing part of an outbound agreement is treated

as a Gateway Interchange Partner Exchange Delivery.


4.1.2 Additional migration restrictions

User-added DPS programs attached to the AMTrix internal processing are not handled.

Low-level AMTrix CSE server protocol configuration details as X.25, ISDN, and so

on, are not fully migrated.

Customer developed CSEs will not be migrated by the migration program. These

CSEs can be migrated manually by using B2Bi Custom Application Deliveries and Custom Application Pickups.

For additional information about Custom Application Deliveries and Pickups, refer to

the Axway B2Bi Gateway Interchange Administrator’s Guide, available on the

Axway B2Bi Server Core DVD.

4.2 Retrieving an AMTrix configuration

To migrate partners and agreements from AMTrix to Axway B2Bi you execute a program

that exports all AMTrix partners and agreements to an XML file. This program is named

amtrixcfg2xml.x4. It is installed on the B2Bi server, in one of two directories:

For all platforms except AS400

$CORE_SOLUTIONS/b2bx/migration/amtrixcfgexport/all

For AS400

$CORE_SOLUTIONS/b2bx/migration/amtrixcfgexport/os400-as400

The program can be placed anywhere on the same machine as the AMTrix installation.

The AMTrix store server must be running. Note: On Windows, the AMTrix store server runs as a service.

4.2.1 Running amtrixcfg2xml.x4

You must execute the program with r4edi version MB6. On AMTrix you find the MB6

r4edi in $AMTRIX/mb6/bin.

On the AMTrix machine, execute the command: amtrixcfg2xml.x4.

4.2.2 amtrixcfg2xml.x4 program arguments

This section provides the starting arguments for the amtrixcfg2xml.x4 program.

$AMTRIX/mb6/bin/r4edi amtrixcfg2xml.x4 [-?] [-d] [-f xml-file] [-p store

server port] [-a store server password] [-b dbOpenString]

Argument Description

? Show command syntax and exit.

l Local partner name. Read configuration for this partner, including

related remote partners and agreements.

f Output file. Default amtrixconfig.xml.

p Port to store server. As a default the $AMTRIX_PORT_PREFIX &

"store" are used.


a Password for access to store server. As default the password in

$AMTRIX_DATA/config/serverpasswd will be used.

b Database open string. For example, user/password@instance. The

default is $AMTRIX_DB.

If the program is executed in a user environment, no options have to be set We recommend using the –l option, for example, to export one local partner and

all its related partners and agreements

Move the created XML file to the machine where Axway B2Bi is installed

4.3 Converting the AMTrix configuration to B2Bi configuration

4.3.1 Setting the enviroment

Log in to the B2Bi environment as the user that installed the B2Bi software. At the command prompt / shell, set the environment by running the command:

For Windows

%CORE_LOCAL%\bin\core_setup

For Unix/Linux

$CORE_LOCAL/bin/core_setup

4.3.2 Running the migration program

Go to the directory %CORE_ROOT%\solutions\4edi\pgm and run the command to start

the migration program:

r4edi b2bx_cnvAmtrix2GI.x4 –f <path_to_the_exported_xml_file> -o

<output_directory>

Where:

-f = the reference to the exported AMTrix XML file

-o = output directory path. This is where the migration program creates directories and

files.

For each created community, the program creates a zip file that contains:

The community configuration

The configuration of its related partners

This zip file can be imported into Gateway Interchange.

You can use the following additional options with this command.

Option Description

[-A prefix] Any document agreement parameters are be added to the corresponding B2Bi document profile as attributes. By default the created attribute names are prefixed with "B2BIDOC_". With this option the prefix can be changed or removed. Use the value "NONE" if no prefix is to be added.

[-B prefix] Enables migration of AMTrix partner parameters to B2Bi community/partner attributes. The given prefix is added to the attribute names. Use the value "NONE" if no prefix is to be added.

[-a ] Automatically generate EBM XML messaging profiles.

This option enables the automatic generation of EBM XML messaging

mailto:user/password@instance


profiles for inbound and outbound EBM XML flows.

[-b ] Automatically generate EBM VDA messaging profiles.

This option enables the automatic generation of EBM VDA messaging profiles for inbound and outbound EBM VDA flows.

[-e envpgm] EBM XML enveloper program name.

Use this option only if you have deployed the EBM XML enveloper map in Integrator.

If the standard enveloper is used the name is MAPSERVICE.B2BXEBM.B2BXEnveloper

[-g ] Disable the retrieval of the conversion program configuration.

If you select this option, the migration program will not try to retrieve conversion program details from Integrator.

[-h ] Disable migration of AMTrix In-house agreements.

[-i ] Add the message flow direction and the community name in created messaging profile name. It is recommended to use this option if the migrated AMTrix system has multiple local partners defined.

[-j ] EBM option used in conjuction with the options -a -b.

Disable the check that there are none of the following:

- Outbound Edifact Document agreement - Outbound X12Document agreement - In-house agreements

Which have identical document parameter sets used for document matching. This concerns the following parameters:

- FileSyntax

- FileVersion

- FileType

- SenderId1

- RecipientId1

[-n] Disable creation of zip files.

[-q] Disable creation of community routing identifiers.

This option is useful when you have an AMTrix system containing multiple local partners using the same EDI addresses. Local AMTrix partners are migrated into Communities and a Community can't have a routing identifier already defined on another Community. By using this option the routing id is not set by the migration program and the import of the Communities will be possible.

Note that this does not solve the initial problem. After importing, the problem of clashing EDI addresses still must be resolved.

[-r ] Disable creation of partner routing identifiers.

This option is useful when you have an AMTrix system containing multiple remote partners using the same EDI addresses. Local AMTrix partners are migrated into partners and a partner can't have a routing identifier already defined on another partner. By using this option the routing id is not set by the migration program, so the import of the partners will be possible.

Note that this does not solve the initial problem,. After importing, the problem of clashing partner EDI addresses still must be resolved.

[-s ] EDIFACT syntax version.


If an Edifact Inbound envelope agreement doesn't contain the syntax version, the syntax version given by this option is used. If not set, the default syntax version is 3.

[-t ] Disable migration of AMTrix Native agreements.

[-u ] Disable migration of AMTrix In-house Gateway agreements.

[-x ] When AMTrix In-house agreements are migrated into In-house or XML Messaging profiles, the messaging profile identifiers used are, by default, the partner names. With this option it is possible to instruct the migration program to use the agreement parameters "SenderId1" and RecipientId1" instead.

[-y ] Disable creation of routing identifiers for inbound In-house or XML messaging profiles.

4.3.3 Results of the migration program execution

The migration program creates the following file structure in the directory specified in

the –o option.

outputdir

| |- MigrationSummary.txt

| |- Programs.map

|

|- EdifactSyntaxVersion.map |

|- ConversionProgramsInput.map |

|- Agreement.map |

|- Partner.map |- DocumentServiceProfile.xml

|

|- AllApplicationPickups.xml |

|- Pickups.map |

|- Community-'communityName'

| |- Community-'communityName'.xml

|

|- Community-'communityName'.zip |

|- partners |

|- Partner-'partnerName1'.xml |

|- Partner-'partnerName2'.xml |

|- Partner-'partnerName3'.xml

Details of the output files:

MigrationSummary.txt: Any problems encountered during the migration are

written to this file

Programs.map: Contains a list of all AMtrix conversion and DPS programs that were found during the migration process. In this file the user has to add the


corresponding programs that are to be used in the B2Bi solution.

Example Programs.map content:

#

# 'AMTrix program' = 'Axway B2Bi program'

#

EDIFACT_D96A_DELFOR.x4=

EDIFACT_D97A_DELJIT.x4=

VDA_4905.x4=

ODETTE_V3R1_DELINS.x4=

To be able to create a complete configuration, you must create processing steps

which correspond to the processing done in AMTrix. This means that the old AMTrix

programs have to be recreated or rebuilt.

When the equivalent programs have been created and deployed (or registered) in Integrator, the Programs.map file should be edited and updated with the new

conversion program names, as in the following example:

#

# 'AMTrix program' = 'Axway B2Bi program'

#

EDIFACT_D96A_DELFOR.x4=MAPSERVICE.DELFOR_D96A.Edi2Xml_D96A_DELFOR

EDIFACT_D97A_DELJIT.x4=MAPSERVICE.DELJIT_D97A.Edi2Xml_D97A_DELJIT

VDA_4905.x4=B2BX Application/VDA4905Map

ODETTE_V3R1_DELINS.x4=B2BX Application/OdetteV3R1_DELINS

After you have edited the Programs.map, you can execute the migration program again. The migration program can then correlate the old AMTrix program names

with the new programs and retrieve the configuration data needed to create the appropriate processing steps and document services.

EdifactSyntaxVersion.map

When you create an EDIFACT messaging profile in Axway B2Bi, you must set the

syntax version of the inbound EDIFACT Interchange. In an AMTrix configuration, the EDIFACT syntax version is often not defined in the

Inbound Edifact Envelope agreement. If the syntax version is missing in the agreement, the migration program sets it

to the default version. This value is either “3” or the value given by the start option –s.

During the execution of the migration program, the names of any agreements that do not have the syntax version set, are written to the EdifactSyntaxVersion.map

file.

EdifactSyntaxVersion.map content example:

#

# 'AMTrix agreement' = 'Edifact Syntax Version'

#

Inbound Envelope_AxwayEDI=

Inbound Envelope_60692=

Inbound Envelope_250111=


You can update this file with the correct syntax version, and then re-execute the migration program. EDIFACT messaging profiles with the correct syntax version set

will be created.

Updated file example:

#

# 'AMTrix agreement' = 'Edifact Syntax Version' #

Inbound Envelope_AxwayEDI=4 Inbound Envelope_60692=2

Inbound Envelope_250111=2

ConversionProgramsInput.map: Contains a list of all AMtrix conversion

programs which the migration program needs to know the input format of. In this file the user has to add if the programs are expecting a XML or an In-house

document.

Agreement.map: Contains a list of all AMtrix agreements found during the migration

process. This file can be used to disable the migration of an agreement.

Partner.map: Contains a list of all local and remote AMTrix partners found. This file can be used to disable the migration of specific partners.

DocumentServiceProfile.xml: Contains the definition of B2bi Document services, Processing steps and Application Deliveries.

AllApplicationPickups.xml: Contains the definition of B2bi Application Pickups.

Pickups.map: Contains a list of AMTrix CSE receive components which are to be

converted into B2Bi pickups. This file is used by the user to define if an AMTrix receive component is to be added in the B2Bi system as an Application pickup or an

pickup on the Community.

Example Pickups.map extract:

#

# This file is used to define how AMTrix CSE receive objects are to be

migrated to B2Bi pickups.

# Syntax:

# AMTrixCseReceiveObjectName=ApplicationPickup | CommunityName

# - Use the constant "ApplicationPickup" if an application pickup is

to be created.

# - Use the name of a community if a partner delivery exchange is to

be created.

#

FTP - Local pickup=ApplicationPickup

EMAIL- Inbound from partner=MANUFACTURER-X

Community-[communityName].xml

Community-[communityName].zip

Partner-[partnerName1-n].xml


For each AMTrix local partner, a community directory is created. In the community directory you find a xml file defining the community and a

partners directory containing xml files defining all the related partners. You will also find a zip file, this zip file contains the compressed community and

partner xml files and this is the file which is to be imported into Gateway Interchange.

[protocolType]_Pickups

For example, FTP_Pickup, EMAIL_Pickups,…

These directories contain the protocol-specific application pickups. There is one XML

file per pickup. By comparison, the AllApplicationPickups.xml file contains all

the pickups defined in these directories. If you do not want to import all pickups at

once, you can import them one by one, using the single pickup import files found in

the [protocolType]_Pickups directories. The XML files in these directories are named

using the name of the corresponding AMTrix CSE component.

4.3.4 Step-by-step procedure

1) Run amtrixcfg2xml.x4 on your AMTrix, as described in chapter 4.2.

2) Move the created file to your B2Bi installation.

3) Create a migration directory, where the created migration files will be created.

4) Run b2bx_cnvAmtrix2GI.x4. Don't forget to run Integrator core_setup first.

5) Look in the Programs.map file. This file contains all programs that must be

migrated.

6) Migrate the programs and register/deploy them on the B2bi Server. Add the new names to the Program.map file.

7) Run b2bx_cnvAmtrix2GI.x4.

8) Check the migrationSummary.txt file, and try to correct problems by using the

files:

o Agreement.map

o EdifactSyntaxVersion.map

o ConversionsProgramsInputFormat.map

o b2bx_cnvAmtrix2GI.x4 start option -q can be used to disable creation of

community routing identifiers. After the migration import has been done, the user can decide which routing ID's to use, and add them

o b2bx_cnvAmtrix2GI.x4 start option -r can be used to disable creation of partner

routing identifiers. After the migration import has been done, the user can decide which routing id's to use, and add them.

9) Repeat this procedure from step 7 until no errors appear in the

migrationSummary.txt, or you reach an acceptable migration result

10) If you are migrating Native AMTrix agreements the Integrator system needs to

have the B2BI_AMTRIX_MIGRATION environment variable set.

To do this, edit the Integrator $CORE_ROOT/config/environment.dat file. At the

end of the file add the line:

B2BI_AMTRIX_MIGRATION=1

Then save the file and restart Integrator.

11) If the AMTrix configuration contains FTP and/or EMAIL CSE parts, the


FTP/EMAIL pluggable transport part needs to be installed. To do this:

Copy the file $CORE_SOLUTION/b2bx/migration/gi/b2bx.migrationpluggabletransport.ja

r to the directory

[GatewayInterchangeInstallDirectory]/build/corelib/integration/b2bx.

Make a backup of the file

[GatewayInterchangeInstallDirectory]/build/conf/pluggabletransports.

xml, so that this can be reinstalled when the FTP/EMAIL pluggable transport is

no longer needed.

Copy the file $CORE_SOLUTION/b2bx/migration/gi/pluggabletransports.xml

to the [Gateway Interchange install directory]/build/conf directory.

Then Restart Gateway Interchange.

12) Import the created migration result into Interchange, as described in the following chapters.

4.4 Importing Application Pickups

The migration program converts AMTrix CSE receive components into B2Bi Application Pickups. That is, if the AMTrix component has been defined as an Application Pickup in

the file pickups.map file. All the created application pickup definitions are put in the

AllApplicationPickups.xml file. You can also find each pickup defined in single files in

the [protocolType]_Pickups directories.

To import the pickups into Interchange, use the following commands:

First execute

> cd %CORE_SOLUTIONS%\java\lib

Then to import all application pickups, use the command:

> java -jar b2bi.giaddconfiguration.jar -t SetApplicationExtensionProfile

-f pathToYourMigrationDirectory\AllApplicationPickups.xml

Or to import a single pickup, use the command:

> java -jar b2bi.giaddconfiguration.jar -t SetApplicationExtensionProfile

-f pathToYourMigrationDirectory\ProtocolType_Pickup\[pickupName].xml

4.5 Importing Communities and Partners

Before importing a community and its partners, you must import the Document services, Processing steps and Application/Partner deliveries into Interchange.

These elements are defined in the DocumentServiceProfile.xml file created by the migration

program. To import into Interchange, use the following commands:

> cd %CORE_SOLUTIONS%\java\lib

> java -jar b2bi.giaddconfiguration.jar -t SetDocumentService -f

pathToYourMigrationDirectory\DocumentServiceProfile.xml

Gateway Interchange contains functions that enable you to back up a community and all of its related partners. The backup file is a compressed file that you can re-import if

you need to restore the community.


The zip file created by the migration program, described in the previous chapter, is a backup file of this type, which you can similarly import. To import, in the B2Bi interface select:

Trading Configuration >

Manage trading configuration > Add a Community >

Import a backed-up CI5 community and its partners in a compressed file >

Then browse and select the zip file.

No password is required for this import.

4.6 Migrating partners

4.6.1 Mapping AMTrix local partner to Gateway Interchange Community

For each local partner in the AMTrix configuration file a GI Community is created.

Name: The same as for the local partner.

Routing Ids:

An EDI address of an AMTrix local partner will only be migrated to a Community Routing

ID if it is used in a migrated AMTrix agreement.

You can use the -q or -y option of the migration program to disable the creation of

Community Routing IDs.

The migration program does not generate Routing IDS from AMTrix Native agreements since it does not have sufficient information to create them.

If multiple Routing IDs are created, the migration program has no way of know which one should be set as the default Routing ID. Therefore, after completing the import

routine, you must select a default Routing ID.

The ebXML party ID type in the routing Id is not set.

Contact name:

Phone number:

E-mail address: Mapped from the first Contact Person entry in the local partner

definition.

4.6.2 Mapping AMTrix remote partner to Gateway Interchange Partner

For each local partner in the AMTrix configuration file, a GI Community is created.

Name: The same as for the local partner.

Routing Ids:

An EDI address of an AMTrix remote partner will only be migrated to a Partner Routing

ID, if it is used in a migrated agreement.

You can use the -r or -y option of the migration to disable the creation of the Partner

Routing IDs.


The migration program does not generate Routing IDS from AMTrix Native agreements since it does not have sufficient information to create them.

If multiple Routing IDs are created, the migration program has no way of know which one should be set as the default Routing ID. Therefore, after completing the import

routine, you must select a default Routing ID.

The ebXML party ID type in the routing Id is not set.

Contact name:

Phone number:

E-mail address: Mapped from the first Contact Person entry in the remote partner

definition.

4.7 Migrating agreements

IEE AMTrix Inbound EDIFACT Envelope Agreement

IEA AMTrix Inbound EDIFACT Acknowledgement Agreement

IED AMTrix Inbound EDIFACT Document Agreement

IEG AMTrix Inbound EDIFACT Gateway Agreement

OEE AMTrix Outbound EDIFACT Envelope Agreement

OED AMTrix Outbound EDIFACT Document Agreement INH AMTrix In-house Agreement INHG AMTrix In-house Gateway Agreement

IXE AMTrix Inbound X12 Envelope Agreement

IXA AMTrix Inbound X12 Acknowledgement Agreement

IXG AMTrix Inbound X12 Gateway Agreement

IXD AMTrix Inbound X12 Document Agreement

OXE AMTrix Outbound X12 Envelope Agreement

OXD AMTrix Outbound X12 Document Agreement NAT AMTrix Native Agreement

EMP GI EDIFACT Messaging Profile

XMP GI X12 Messaging Profile

DP GI Document Profile DS GI Document Service

4.7.1 General migration restrictions

A local AMTrix partner is treated as a GI Community.

A remote AMTrix partner is treated as a GI Partner.

Agreements having both sender and recipient set to a remote partner are not migrated.

Agreements having both sender and recipient set to a local partner are not

migrated.

INH and Native agreements having the sender set to a remote partner are treated

as inbound agreements.

INH and Native agreements having the sender set to a local partner are treated as outbound agreements.

The CSE send node defined in the routing part of an inbound agreement is treated


as an application delivery.

The CSE send node defined in the routing part of an outbound agreement is treated as a partner exchange delivery.

4.7.2 Inbound EDIFACT Envelope Agreement, IEE

For each IEE, at least one Edifact Messaging Profile (Edifact MP) is created.

If multiple IEDs use the same IEE and they do not have the same message version and release, one Edifact MP is created for each version and release pair

EMP Name: AMTrixAgreementName [ - messageVersionAndRelease Syntax Level

SyntaxVersion ]

Where:

[ - messageVersionAndRelease Syntax Level SyntaxVersion ] is optional. It is

only added if the IEE/IED agreements result in multiple Edifact messaging profiles.

syntaxVersion is taken from the IEE/Criteria/UNB S001-0002

messageVersionAndRelease are taken from the IED which uses the IEE

messageVersion is taken from the IED/Criteria/UNH S009-0052

messageRelease is taken from the IED/Criteria/UNH S009-0054

If any of these values are missing in the IEE and IED, a generic EDIFACT Messaging profile is created.

Edifact MP Name: AMTrixAgreementName [ - GENERIC ]

Where:

[ - GENERIC ] is optional. It is only added if the IEE/IED agreements is resulting

in multiple messaging profiles.

For each IED referencing the particular IEE, a DS and a DP are created and put into the Edifact MP.

4.7.2.1 Created Document Service, DS, parameters

DS name:

Set to DocumentType DocumentFormat DocumentStandard ConversionProgramName

[IED RoutingSequenceName]'

Where:

[IED RoutingSequenceName] is optional. It is only set if the routing sequence

referenced in the IED contains any customer DPS.

Initial processing step: The IED/Conversion/FormatConversionProgram can be found in the migration file

Programs.map . The user-added processing step is chosen as the DS Initial processing step.

Additional document processing: If the routing sequence referenced in the IED contains any customer-added DPSs, the


DPSs are added. The processing step names are taken from the migration file Programs.map.

Additional post envelope processing: Not set.

Additional post transfer processing: Not set.

Deliver to partner: Not selected.

Deliver to application:

Selected and the application delivery is set.

4.7.2.2 Created Document Profile, DP, parameters

DP name:

Set to the IED name.

DocumentService:

The DS created through the IED is selected.

Use a messaging profile for enveloping of map output:

Not selected

Document Profile Attributes:

Taken from the IED Parameters. Attribute names are given the prefix “B2BIDOC_".

4.7.3 Outbound EDIFACT Envelope Agreement, OEE

For each OEE that is referenced by at least one OED, one EdifactMessagingProfile

(Edifact MP) is created.

Only the generic EDIFACT Messaging Profile is created because it is not possible to

establish the EDIFACT message version and release of the documents generated by the OED conversion programs.

Edifact MP Name: AMTrixAgreementName

For each OED that references the OEE, a corresponding In-house or XML MP is created.

This MP has a DP in which the 'Use a messaging profile for enveloping of map output'

parameter points to the EDIFACT Messaging Profile created through the OEE.

4.7.3.1 Edifact MP Identification parameters

All parameters in the MP Identification tab are taken from the corresponding fields in the

OEE Enveloping tab.

4.7.3.2 Edifact MP Inbound parameters

Next expected group control: Not set.

Sequence check on interchange control numbers: Not set.

Generate acknowledgement rule: Set to Never.

Acknowledgement Type: Not used.

Rejection rule: Not used.

4.7.3.3 Edifact MP Envelope parameters

All parameters in the MP Envelope tab are taken from the corresponding fields in the

OEE Enveloping tab.


4.7.4 Outbound EDIFACT Document Agreement, OED

To be able to migrate an OED agreement, the migration program needs to know the input document format of the document handled by the conversion program defined in

the OED.

Because of this, if the conversion program is expecting an XML or an In-house

document as input, the user has to update the ConversionProgramsInputFormat.map

migration file with the information. When the input format is known the migration

program creates either a XML or an In-house messaging profile.

XML/In-house MP Name: AMTrixAgreementName

4.7.4.1 XML/In-house MP Identification parameters

The Identification of the MP is set to AMTrix EDI Address values Address:SubAddress.

4.7.4.2 XML/In-house Document Service, DS, Parameters

DS name:

Set to DocumentType DocumentFormat DocumentStandard ConversionProgramName [OEE RoutingSequenceName]'

Where:

[OEE RoutingSequenceName] is optional. It is only set if the routing sequence OED

referenced in the OEE contains a customer DPS.

Initial processing step:

The IED/Conversion/FormatConversionProgram can be found in the migration

Programs.map file. The user-added processing step is chosen as the DS Initial

processing step.

Additional document processing: Not set.

Additional post envelopeprocessing:

If the routing sequence referenced in the OEE contains any customer-added DPSs, these are added. The processing step names are taken from the migration file

Programs.map.


Deliver to partner: Selected.

Deliver to application: Not set.

4.7.4.3 XML/In-house Document Profile, DP, parameters

DP name: DocumentType

DocumentService:

The DS created through the OED is selected.

Use a messaging profile for enveloping of map output:

The Edifact MP created through the OEE referenced by the OED is selected.


Taken from the OED Parameters. Attribute names are given the prefix "B2BIDOC_".

4.7.5 Inbound EDIFACT Gateway Agreement, IEG


For each IEG, one Gateway Edifact Messaging Profile (Edifact MP) is created.

Edifact MP Name: AMTrixAgreementName.

Because the EDIFACT version/release cannot be established, the MP standard is set to

'GATEWAY' A Gateway MP contains a DS and a DP.

4.7.5.1 Created Document Service, DS, parameters

DS name:

Set to GATEWAY EDIFACT ConversionProgramName [IEG RoutingSequenceName]'

Where:

[IEG RoutingSequenceName] is optional. It is only set if the routing sequence

referenced in the IEG contains a customer DPS.

Initial processing step: none.

Additional document processing: If the routing sequence referenced in the IEG contains any customer addded DPSs these will be added. The processing step names are taken from the migration file Programs.map.



Deliver to partner: Not selected.

Deliver to application: Selected and the application delivery set.

4.7.5.2 Created Document Profile, DP, parameters

DP name: Set to „GATEWAY'.

DocumentService:

The DS created through the IEG is selected.

Use a messaging profile for enveloping of map output: Not selected


Taken from the IEG Parameters. The attribute names are given the prefix "B2BIDOC_".

4.7.6 X12 Envelope Agreements IXE, IXD, OXE, OXD, IXG

All X12 Agreements are migrated in exactly the same way as the corresponding Edifact

Agreements.

4.7.7 In-house Agreement, INH

To be able to migrate an INH agreement, the migration program needs to know the

input document format of the document handled by the conversion program defined in

the INH.

If the conversion program is expecting a XML or a In-house document as input, the user

must update the migration ConversionProgramsInputFormat.map file with the

information.


If the input format is known, the migration program creates either a XML or an In-house messaging profile.

XML/In-house MP Name: AMTrixAgreementName

4.7.7.1 XML/In-house MP Identification parameters

By default the Identification of the MP is set to the partner name. By using the migration program

start option –x, the document agreement parameter 'SenderId1'/'RecipientId1' will be

used instead. The identification parameter of the MP is not really used, as the detection of the MP is done indirectly by the detection of the included DP.

4.7.7.2 XML/In-house Document Service, DS, parameters

DS name:

Set to 'DocumentType DocumentFormat DocumentStandard ConversionProgramName [INH

RoutingSequenceName]'

Where:

[INH RoutingSequenceName] is optional. It is only set if the routing sequence INH

contains a customer DPS.

Initial processing step:

The INH ConversionProgram can be found in the migration file Programs.map and the

user added processing step will be chosen as the DS Initail processing step.

Additional document processing:

If the routing sequence referenced in the INH contains any customer addded

DPSs these will be added. The processing step names are taken from the migration file Programs.map.



Deliver to partner: Selected if it's an outbound INH.

Deliver to application: Selected if it's an inbound INH.

4.7.7.3 XML/In-house Document Profile, DP, parameters


DocumentService:

The DS, created through the INH, is selected.

Use a messaging profile for enveloping of map output: Not set.


Taken from the INH Parameters. The attribute names are given the prefix "B2BIDOC_".

4.7.8 In-house Gateway Agreement, INHG

For each INHG agreement one In-house MP will be created.

In-house MP Name: AMTrixAgreementName

In-house MP Identification parameters

By default the Identification of the MP is set to the partner name. By using the migration program start option -x the document agreement parameter


'SenderId1'/'RecipientId1' will be used instead. The identification parameter of the MP is not really used, as the detection of the MP is done indirectly by the detection of the

included DP.

4.7.8.1 In-house Document Service, DS, parameters

DS name:

Set to GATEWAY INHOUSE [INHG RoutingSequenceName]'.

Where:

[INHG RoutingSequenceName] is optional. It is only set if the routing sequence INHG


Initial processing step: Not set.


If the routing sequence referenced in the INHG contains any customer-addded DPSs, the DPSs are be added. The processing step names are taken from the migration file

Programs.map.



Deliver to partner: Selected if it is an outbound INHG

Deliver to application: Selected if it is an inbound INHG

4.7.8.2 In-house Document Profile, DP, parameters

DP name: Set to 'GATEWAY'

DocumentService:

The DS, created through the INHG, is selected.



Taken from the INHG Parameters. Attribute names are given the prefix "B2BIDOC_".

4.7.9 Native Agreement, NATFor each NAT agreement one In-house MP is created. The

messaging standard is set to 'B2BI_AMT_NATIVE'.

In-house MP Name:

AMTrixAgreementName

4.7.9.1 In-house MP Identification, parameters

The Identification of the MP is set to the AMTrix EDI Address values Address:SubAddress.

4.7.9.2 In-house MP Document Service, DS, parameters

DS name:

Set to NATIVE INHOUSE [NAT RoutingSequenceName]'.

Where:

[NAT RoutingSequenceName] is optional. It is only set if the routing sequence NAT



Initial processing step: Not set.


If the routing sequence referenced in the NAT contains any customer-added DPSs,

these DPSs are added. The processing step names are taken from the migration file

Programs.map.



Deliver to partner: Selected if it's an outbound NAT agreement

Deliver to application: Selected if it's an inbound NAT agreement

4.7.9.3 In-house Document Profile, DP, parameters


DocumentService: The DS, created through the NAT, is selected.



Taken from the NAT Parameters. Attribute names are given the prefix "B2BIDOC_".

4.7.10 Native Agreements: Analysis

4.7.10.1 Overview

In AMTrix, you use the Analysis functionality to route received messages to a specific Native agreement. This functionality can also be enabled in the B2Bi solution. To do this

you set the environment variable B2BI_AMTRIX_MIGRATION. When you do this you

activate an optional Analysis dialog in the B2Bi pickup configuration.

You use this Analysis dialog to specify how to analyze a received message and retrieve the following classification values:

SourceAddress

SourceSubAddress

DestinationAddress

DestinationSubAddress

DocumetType

These values are then used by the Native document classifier to find an In-house

document profile/service to handle the message.

The Native classifier only searches for In-house type Messaging Profiles that have their

messaging standard set to B2BI_AMT_NATIVE.

SourceAddress and SourceSubAddress are concatenated into a colon-separated sender

identifier: SourceAddress:SourceSubAddress

SourceAddress and SourceSubAddress are concatenated into a colon-separated

recipient identifier: DestinationAddress:DestinationSubAddress

These two identifiers are used to identify a Messaging Profile.

For an inbound message:

The sender identifier is matched against the messaging profile Identifier


The recipient identifier is matched against the Community routing identifier defined in the messaging profile.

For an outbound message:

The recipient identifier is matched against the messaging profile Identifier

The sender identifier is matched against the Community routing identifier defined in

the messaging profile.

If a matching Native Messaging Profile is found, the DocumentType retrieved by the

Analyzer is matched against the Document Profile.

4.7.10.2 Configuring Analysis in B2Bi

It is relatively simple to configure Analysis in the B2Bi UI compared with AMTrix. You enter a single line describing the analysis.

Analysis syntax:

Analyse[:Analyse]*

Where Analyze can be one of the values:

EDIFACT

X12

TRADACOMS

TransferData

Other=<Method>[,<Method>]*

You can define more than one analysis type. When you have multiple analysis types and a message is received, each method in turn is applied to the message until one of the

types succeeds in analyzing the received message.

Example 1: Selecting EDIFACT, TRADACOMS

This analysis definition specifies that the Analyzer should first do an EDIFACT analysis and if that returns no results, it do an X12 analysis.

Example 2: Selecting TrasferData, Other=XTR

This analysis definition specifies that the Analyzer should first analyze TransferData and

then load the In-house analyzer with the method XTR.

4.7.10.3 EDIFACT analysis type

When you specify EDIFACT as the analysis type, the classifier value is retrieved from

the envelope of the received message.

EDIFACT/ODETTE Element Reference

Source Address UNB S002:0004

Source Sub Address UNB S002:0008

Destination Address UNB S003:0010

Destination Sub Address UNB S003:0014

Document Type UNH S009:0065 or UNB S0026

4.7.10.4 X12 analysis type

When you specify X12 as the analysis type, the classifier value is retrieved from the envelope of the received message.

X12 Element Reference

Source Address ISA06

Source Sub Address NONE


Destination Address ISA08

Destination Sub Address NONE

Document Type ST01

4.7.10.5 TRADACOMS analysis type

When you specify TRADACOMS as the analysis type, the classifier value is retrieved

from the envelope of the received message.

TRADACOMS Element Reference

Source Address STX FROM:Code, or FROM:Name if Code is blank

Source Sub Address STX FROM:Name , if Code is non-blank,

otherwise NONE

Destination Address STX UNTO:Code, or UNTO:Name if Code is blank

Destination Sub Address STX UNTO:Name, if Code is non-blank,

otherwise NONE

Document Type MHD TYPE:Type

4.7.10.6 TransferData analysis type

When you specify TransferData as the analysis type, the classifier value is derived from

protocol-specific attributes or from explicitly-defined values.

The TransferData is therefore specific for each receive protocol:

FTP, ALE, HTTP:

Explicit values are given in the Analysis UI configuration parameter named

TransferData.

TransferData syntax: Source:SourceSub:Destination:DestinationSub:MessageType

Email:

TransferData references Source Address Sender email address

Source Sub Address Not defined

Destination Address Recipient email address Destination Sub Address Not defined

Message Type Email subject

MQ:

TransferData references Source Address PutApplName field

Source Sub Address ApplIdentityData field

Destination Address NONE

Destination Sub Address NONE

Message Type ApplOriginData field

4.7.10.7 Other analysis type

The Other analysis type is provided so that you can use your own analysis methods to

obtain classifier values. This analysis method is normally used to analyze your own in-house message formats.

Enter the name of your analysis method (or methods) in the Other field. If you enter

more than one method name, the names must be separated by commas.


Your analysis methods must be included in the B2BI_ANALYZE_OTHER.ReadInterchange

Message Builder statement. This statement is called to get the classification values.

To customize the B2BI_ANALYZE_OTHER MBC:

1. Copy the file $CORE_SOLUTIONS/4edi/pgm/b2bi_analyze_other.s4 to the

$CORE_LOCAL/4edi/pgm directory.

2. Edit the file b2bi_analyze_other.s4 in the $CORE_LOCAL/4edi/pgm directory.

3. Modify the INHOUSE_REVISION function to return the current revision number

followed by the customer suffix.

4. Modify the ReadInterchange statement.

5. Recompile the b2bi_analyze_other.s4 program in the $CORE_LOCAL/4edi/pgm

directory, using the command:

c4edi b2bi_analyze_other.s4

4.8 Migrating the map conversion programs

To be able to automatically get the conversion programs defined in the migrated

Document Profiles, assigned to a processing step, execute the following steps before

you import the Partner.

1. Use the B2BX migration tool to migrate all conversion programs that are used in IED and IXD agreements for a specific partner.

2. Register the programs on the Axway B2Bi server. 3. In the UI, use the Manage processing steps for partner.

4. Add all the conversion programs as map processing steps, and give the newly created processing step entries with exactly the same name as the conversion

program names found in the IED and IXD agreements, For example: paymul.x4.

After these steps, the partner profile can imported.

Migration Guide Migrating AMTrix In-house detectors 50

5 Migrating AMTrix In-house detectors


This chapter describes In-house detectors in AMTrix and in Axway B2Bi, and describes how to

create them in provides B2Bi.

5.1 Overview of the migration

In AMTrix, the role of an In-house detector is to read input messages and compare

detected criteria values against the corresponding parameters in a document agreement to obtain an agreement match.

In B2Bi the In-house/XML detector reads the input message and adds the detected criteria values to the attributes of detector. The detector attributes are used in the next

processing stage to find a matching document profile.

The migration tool migrates AMTrix document agreements to B2Bi document profiles

and adds any document agreement parameters as document profile attributes. By

default prefixes attribute values with the value B2BIDOC_. After migrating an In-house

agreement, you typically have a resulting document profile that contains an attribute

list similar to the following:

B2BIDOC_FileSyntax = XT

B2BIDOC_FileType = DELINS

B2BIDOC_FileVersion = 3

B2BIDOC_SenderId1 = 65892648569

B2BIDOC_RecipientId1 = 985694767

To create a B2Bi In-house/XML detector, you create a MBC (Message Builder

Component) that sets the detector attribute. Alternatively, you could build a map that creates the detector attribute.

An example detector MBC can be found in

$CORE_SOLUTIONS_LOCAL/examples/hierch/procmbc_exampledetector.s4h.

The following snippet shows the definitions of detector attributes that are found in this

file:

DECLARE PUBLIC RECORD B2BiDetector

{

DECLARE PUBLIC FIELD $MessageId STRING;

DECLARE PUBLIC FIELD $MessageFormat STRING;

DECLARE PUBLIC FIELD $MessageFormatVersion STRING;

DECLARE PUBLIC FIELD $SenderName STRING;

DECLARE PUBLIC FIELD $SenderMessagingProfileId STRING;

DECLARE PUBLIC FIELD $RecipientName STRING;

DECLARE PUBLIC FIELD $RecipientMessagingProfileId STRING;

DECLARE PUBLIC FIELD $TestFlag STRING;

DECLARE PUBLIC FIELD $DocumentType STRING;

DECLARE PUBLIC FIELD $DocumentAttribute[] RECORD

{

DECLARE PUBLIC FIELD $Name STRING;


DECLARE PUBLIC FIELD $Value STRING;

DECLARE PUBLIC FIELD $SkipIfEmptyOrAbsent STRING; /* true |

false */

}

DECLARE PUBLIC FIELD $Direction STRING;

}

The include file for this MBC is b2bi_detector.s4h which can be found in

$CORE_SOLUTIONS_LOCAL/4edi/include.

5.2 Attribute descriptions

$MessageId

Optional parameter to carry the application message identifier, which is used in logging.

$MessageFormat

Mandatory parameter, set to the value XML if it is an xml message or INHOUSE if it is an

in-house message.

$MessageFormarVersion

Parameter that identifies the messaging profile to be used. This is set to the name of

the messaging standard selected for the messaging profile.

It can be omitted if the $DocumentAttribute is used for detection. If the value is

known it, should be set, as it can improve detection performance.

$SenderName

Optional parameter, set to sender community/partner name. This value should be set if known, as it improves classification performance.

$SenderMessagingProfileId

Parameter that identifies the sender. Its value is set to the identification name defined

in the sending community/partner messaging profile ID.

It can be omitted if the $DocumentAttribute is used to do the detection. If the value is

known it should be set, as it can improve detection performance.

$RecipientName

Optional parameter, set to recipient community/partner name. Its value should be set if known, as it will improve detection performance.

$RecipientMessagingProfileId

Identifies the recipient partner. Its value is set to the identification name defined in the

receiving community/partner messaging profile ID.



known its hould be set, as it can improve detection performance.

$TestFlag

Optional parameter. If set it is matched against the test flag setting in the Messaging

profiles.

Valid values for indicating the test flag is set are T and 1.

$DocumentType

Identifies the document profile to be used. Its value is set to the document type selected for the document profile.


known it should be set, as it can improve detection performance..

$DocumentAttribute

Document detection attribute array. Add the values and names of the attribute that

should be used to find a document profile that has exactly the same attribute set.

$DocumentAttribute.$SkipIfEmptyOrAbsent can be used to specify that this attribute

should not be used for detection if it isn't present in the document profile or if the attribute value found in the document profile is empty.

Document attributes can be omitted if the $MessageFormarVersion, $SenderMessagingProfileId, $RecipientMessagingProfileId and $DocumentType

values are known and set

$Direction

Identifies the direction of the message and should be set if known. The value

"INBOUND" is set if the message is received from a partner. Itbis set to "OUTBOUND" if it is a message sent from the application side.

Migration Guide Migrating AMTrix programs 53

6 Migrating AMTrix programs


This chapter describes how to migrate AMTrix FTP and Email programs to a B2Bi environment using pluggable transport definitions in Axway B2Bi.

AMTrix and B2Bi are conceptually different in significant ways. For example, in AMTrix, transport definitions are completely detached from the concerned transport partners and applications. They can be used on either side of an exchange. In Axway B2Bi, protocol definitions for partners and applications can be distinguished separately.

Additionally, the protocols you implement in AMTrix have different options and different behavior than the native partner protocols in Axway B2Bi.

Axway B2Bi supports transport extensibility through pluggable transports for customized message consumption and production. This enables custom code to control message exchanges with any partner without changing the base code.

To ensure maximum backward compatibility for AMTrix customers and to facilitate the migration process, we have implemented the most frequently used AMTrix protocol definitions (FTP and EMAIL) in Axway B2Bi through these pluggable transport definitions. This gives you the ability to automatically convert your existing FTP and EMAIL CSE configuration from AMTrix into matching pluggable transport definitions in Axway B2Bi.

FTP/EMAIL CSE objects which are migrated into Partner deliveries and Community pickups, are created as pluggable transport deliveries and pickups.

In the Axway B2Bi UI the pluggable transport deliveries/pickups are named:

Migration FTP delivery

Migration EMAIL delivery

Migration FTP pickup

Migration EMAIL pickup

These deliveries and pickups are only visible in the UI if the pluggabletransport.xml and jar files

have been installed in Gateway Interchange. The installation of these components is described in the

Step-by-step procedure sub-chapter of this document.

Pluggable transport pickups and deliveries are configured as if they where communication objects in Gateway Interchange, but they are deployed as communication objects on the Integrator side. The

Migration Guide Migrating AMTrix programs 54

message flow to and from these objects is done only on the Integrator side, that is, flows are not passed through Gateway Interchange, so you cannot find messages, transported by these communication objects, using message tracker in Gateway Interchange. The messages can only be monitored through the Transaction search tool or in the Integrator Message log.

Migration Guide Appendix 55

7 Appendix


This appendix provides additional information you may need to refer to during the migration of AMTrix 4.4.3 map programs.

7.1 AMTmig attributes

This section describes the attributes you need to specify when migrating a program

from AMTrix to Synchrony Integrator or a program with an .x4 extension. This program

requires these AMTmig attributes to function with Integrator.

7.1.1 Attributes

The AMTmig attributes are defined in the template file AMTMigMap.s4.

Attribute Name "AMTmigCaller"

Attribute Record "AMTmigAttribute"

Attribute fields:

Arguments STRING List of arguments that you can set. In AMTrix it is

possible to give arguments to a DPS program if you

insert it into the AMTrix Process Manager. If you want to call old programs which are designed as a DPS and

expect arguments, you can enter them here. Note that the system environment variables are not available

here.

Sender STRING (optional)

If a program needs valid values for the sender, sender

sub address or the sender name, you can enter them here, separated by colons.

SenderSub STRING

SenderName STRING

Recipient STRING (optional)

If a program needs valid values for the recipient,

recipient sub address or the recipient name, you can

enter them here, separated by colons.

RecipientSub STRING

RecipientName STRING

AMTrix Document Type: This is the same as the Sender information.

Debug: means that the migrated map will write some debug information to the Trace Log.

LABEL 1-20: This is the same information as the Agreementparameter 1-20 in AMTrix.


7.1.2 GetAMTmigAttributes

The syntax for the GetAMTmigAttributes is:

Record = AMTmig_ATTRIBUTES.GetAMTmigAttributes(SessionId, MessageId)

7.1.3 SetAMTmigAttributes

The syntax for the SetAMTmigAttributes is:

AMTmig_ATTRIBUTES.SetAMTmigAttributes Record

SESSIONID SessionId

MESSAGEID MessageId

7.2 Translated commands

This section describes the new behavior of the old statements and functions.

7.2.1 Program arguments

The functions ARGUMENT and ARGUMENTCOUNT do not give values because the old

program now is called from the AMTrix Migration Caller MBC. The Caller MBC itself is

called by the Integrator system. So you have no program arguments like they could be set in the AMTrix Process Management. But DPS programs often need arguments. So

there is a possibility to give arguments in the Caller MBC for the old conversion program. In AMTrix each DPS was a separate system process, in Integrator each

loadable is called by the Integrator core and is not a separate process.

The Cross Compiler replaces the commands by new ones which take the program

arguments from the Caller MBC. These functions are described in the Migration interface

chapter.

Note that the system environment variables are not translated by the AMTrix Migration

Caller. This means that environment variables cannot be used as it was possible in the AMTrix Process Manager.

7.2.2 RECEIVE and SEND

The AMTrix statements RECEIVE and SEND are used for receiving and sending files to the AMTrix EDI router. These statements are built in commands of the MB5

compiler/interpreter which means that these statements can not be rewritten under MB5 (but under Integrator MB6). They do not strictly follow the MB conventions, which

means that they cannot be rewritten in the same syntax. But there are four new

statements which do the same.

7.2.2.1 The RECEIVE statement

The syntax for the AMTrix RECEIVE statement is:

RECEIVE {FILE | STRING} Msg TYPE MsgType SOURCE Source

[SUB SourceSub] DESTINATION Dest [SUB DestSub]

[OPTIONAL {FILE | STRING} Opt] [CHARSET CSet]

[SEQUENCE Seq] [LOGID LogID] [CONTROL Cntl] [NONBLOCKING];


For the meaning of these parameters and more details, refer to the AMTrix MB5 manual.

You can receive the message as a file (getting the file name from the system) or as a string (which contains the message). Furthermore you can get the optional data, the

routing address information and set to non-blocking.

Using the AMTrix Migration Caller MBC there is no routing data as we had before and we

do not need the directive NONBLOCKING as well. The routing information as Source,

Destination and Message Type comes from the AMTrix Migration Caller MBC configuration. It is not possible to use keywords as a switch (if one appears the other

cannot appear).

So the new syntax is different. We have two statements: one for receiving files and one

for receiving strings:

RECEIVE_FILE MessageFile [TYPE MsgType]

[SOURCE Source][SUB SourceSub] [DESTINATION Dest] [SUB DestSub]

[CHARSET CSet] [SEQUENCE Seq] [LOGID LogID] [CONTROL Cntl];

RECEIVE_STRING MessageString [TYPE MsgType]

[SOURCE Source][SUB SourceSub] [DESTINATION Dest] [SUB DestSub]

[CHARSET CSet] [SEQUENCE Seq] [LOGID LogID] [CONTROL Cntl];

The syntax should be changed automatically using the Cross Compiler.

7.2.2.2 The SEND statement

For the send statement it is the same as for the receive statement. There are also two

statements, one for sending files and one for sending strings.

The old statement syntax is:

SEND {FILE | STRING} Msg TYPE MsgType SOURCE Source

[SUB SourceSub] DESTINATION Dest [SUB DestSub]

[OPTIONAL {FILE | STRING} Opt] [CHARSET CSet]

[SEQUENCE Seq] [LOGID LogID] [NOLOG];

The NOLOG directive is no longer available. The optional data is also no longer available. For more information and a detailed description about the parameters, refer

to the AMTrix Message Builder manual.

The new syntax is:

SEND_FILE MessageFile

[SOURCE Source] [SUB SourceSub] [DESTINATION Dest] [SUB DestSub]

[TYPE MsgType] [CHARSET cset] [SEQUENCE seq] [LOGID logid];

SEND_STRING MessageString

[SOURCE Source] [SUB SourceSub] [DESTINATION Dest] [SUB DestSub]

[TYPE MsgType] [CHARSET cset] [SEQUENCE seq] [LOGID logid];

If you change the routing information (Sender, Recipient, ...) in AMTrix the message is routed to another routing sequence. This is not possible in Integrator and the AMTrix

Migration Caller MBC does not support this. But if you change the routing information this will take effect to the indexes which are written to the Integrator Message Log.

The changes of the code should be made using the Cross Compiler.


7.2.3 AMTRIX module

The AMTRIX module contains the following methods:

FUNCTION AMTRIX.LogID()

STATEMENT AMTRIX.ReadOptionalData

STATEMENT AMTRIX.WriteOptionalData

7.2.3.1 Getting the Log ID

AMTRIX.LogID()

This function returns a new log ID. This is taken from the unique ID file label

IntLogRef. If a new message is created (for example in a message splitter) a new Log

ID is used and created by using this function. While using the Caller MBC it is not necessary to create a new Log ID and a new Log ID can not be routed to the Caller

MBC. In this case this function can be removed. The new Log ID is created by the Caller MBC anyway.

7.2.3.2 Optional data

The optional data can be manipulated with the following commands:

AMTrix.ReadOptionalData

AMTrix.WriteOptionalData

The optional data string in AMTrix has the construction of an EDIFACT string. This has changed now. It is a serialized record string. All manipulations of the string using the

STRxxx commands will not work any more.

AMTRIX.ReadOptionalData

The statement returns the optional data in an array but in the migration environment

the returned data is not as complete as it is done under AMTrix.

The following fields are filled:

FTP:

$FTP[$FTP_FileName] = Name of the transferred file

$FTP[$FTP_Server] = Host name or IP

$FTP[$FTP_User] = User

$FTP[$FTP_Account] = Account

$FTP[$FTP_Password] = Password

AMTRIX.WriteOptionalData

This statement sets the optional data for a transfer. Only the manipulation of the

following fields will take effect:

FTP:

$FTP[$FTP_FileName] = Name of the transferred file

$FTP[$FTP_Server] = Host name or IP

$FTP[$FTP_User] = User

$FTP[$FTP_Account] = Account

$FTP[$FTP_Password] = Password


7.2.4 TRANSFER module

This module is used in DPS programs. Because also loadable programs have to be

redesigned as DPS (simply done by including the migration include files) these statements are also used for loadable programs now. Most statements work but with a

slightly different behavior.

A usual DPS looks like the following construction:



# Converting the input file to the output file

TRANSFER.SendFile;


This will also run using the Caller MBC. It is also possible to send more than one output file so that it is possible to create a file splitter.

TRANSFER.CommitFile

This statement is used to release a file from the router. If you receive a file from the system and you do not want to send the file you can use this statement to stop the

process.

The Caller MBC will accept this and stop the file transfer for the output file. The result would be the same as in AMTrix.

Example code:


DECLARE $inFile STRING;

TRANSFER.ReceiveFile $inFile;

My_Zip $inFile; # routine which archives the file

TRANSFER.CommitFile;

RETURN;

}

TRANSFER.CreateFile

This statement creates a new output file. For each new output file this statement should

be called. In AMTrix it creates the file and opens it. Using the Caller MBC this statement does the same.

TRANSFER.DeleteFile

This statement deletes the input file. It should be called if the input file is not used any more. Otherwise the input file will still exist in the temporary directory. This statement

works the same like in AMTrix.

TRANSFER.GetInfo


Under Integrator there is no routing information like in AMTrix. If you use this statement it will return the values you have given to the Caller MBC in the

Configuration tab.

TRANSFER.IsFile()

The logic of the programs is that they receive one file from the Caller MBC, convert it

and send the file. After this they end and the Caller MBC takes the control again. In this context this function does not make sense any more. This function does return a 1 in

any case. Concerning the example in the AMTrix Designer manual, note that that you should not use an EXIT in Integrator.

TRANSFER.MoveFile

This statement moves a file to the given directory does a Commit File. It will work the

same using the Caller MBC.

TRANSFER.ReceiveFile

In AMTrix this statement gets the file from the router. Using the Caller MBC this

statement gets the information from the Caller environment like sender, recipient, message type and input file name. If the file name is not given this routine opens the

input file.

TRANSFER.SendFile

In AMTrix this statement sends the file to the router and this is done immediately. Using

the Caller MBC the output file is marked “finished and ready for sending”. After the conversion program returns to the Caller MBC the Caller will send all files which are

marked for sending. It will create a new logger ID for each send file and log the success into the document log. So it is not necessary to create a new log ID (as usual in AMTrix)

if you want to send more than one file.

TRANSFER.SendReport

This statement does not work in Integrator. The reason is the same as for

TRANSFER.SetInfo. This statement routes a report message to different routing

address. Now it should come up with a warning in the event log.

TRANSFER.SetInfo

Calling this statement should bring an error to the event log. Using the Caller MBC this

statement does not work any more. If you want to send files to another routing you should define it in your integration.

The reason is that there is no routing information in Integrator as you had in AMTrix and so there is no possibility to translate routing information and sequence number into

something in Integrator.

7.2.5 PGM module

7.2.5.1 PGM Open and Close Files

In loadable maps the following statements are used to open and close the input/output

files:

PGM.OpenInput, PGM.CloseInput, PGM.OpenOutput, PGM.CloseOutput


In AMTrix these statements have a different behavior if they are used in DPS programs or loadable maps. This is because in one case the map has to communicate with the

router (done by the TRANSFER module) and in the other case the map has to communicate with the inbound/outbound environment.

Using the Caller MBC there is only one communication interface. If the TRANSFER module is used and included the communication is done by the TRANSFER routines. If

the routines of the TRANSFER module are not used the PGM routines communicate with

the Caller interface.

7.2.5.2 PGM optional data

The PGM module has routines to get and set the optional data.

PGM.GetInputOptionalData(), PGM.SetOptionalData

In AMTrix the optional data is an EDIFACT-like string. Using the Caller the optional data

is a packed record string. To manipulate the optional data the AMTRIX statements should be use. It is strongly recommended not to manipulate the optional data string

manually by using the STR... routines.

7.2.5.3 PGM get Routing Information

PGM.GetAgreementId()

This function returns a fix value because there is not agreement any more. You should not use this function any more.

PGM.GetSourcePartner()

Now returns the Source you have given to the Caller configuration.

PGM.GetDestinationPartner()

Now returns the Destination you have given to the Caller configuration.

PGM.GetParameter(nn)

Now returns the Parameter you have given to the Caller configuration.

7.2.5.4 PGM User Data

The user data in AMTrix is written to the Document log. Using the Caller MBC it is

written to the Document log as well if the labels are defined under Integrator for the generic search.

7.2.5.5 PGM Error Handling

During the parsing of an EDI document, errors are registered automatically. But to set

up your own errors there are the statements:

PGM.AddError, PGM.AddErrorText

An error is registered, but the conversion goes straight forward. The created file will be

marked as “failed” and the entry in the document log will get a red icon which means an error.


7.3 Migration interface

This section describes the migration interface in more detail, explaining how it works and

describing the new statements and functions.

7.3.1 Description of migration interface

As described in the About migrating AMTrix map programs chapter, the Caller MBC takes the file from the Integrator environment and writes it to the disk as a temporary

file. Then it calls the old map which is doing the conversion and writes the output files. These output files are read by the Caller MBC and sent to Integrator.

If the Caller MBC is called by Integrator, it first prepares the environment for the conversion program (the old map program). This is done by filling up a record

(migration interface record) which contains the environment information. Some of this

information is the current log ID or the receive Attributes and the temporary written input file name. This record is a kind of communication memory area which is given to

the old map. The Caller MBC reads the input file from the Integrator environment and writes it to a temporary file.

After this it loads the old map (x4) so that this map runs in the same environment as

the Caller MBC and calls one public routine of the old map called MIG21_CONVERSION.

This function gets the interface record as a parameter and has full access to it. Now this

statement calls the conversion part of the old map and the map converts the input file and writes the output files.

This interface statement is defined it the migration include files which now are included

in the old maps (for example in the file migrationDPS.s4h).

Most routines like TRANSFER.SendFile have been rewritten and now use a new library

called DSG_MIG21. This library contains the communication routines to get and put

information from/to the interface record. For example the TRANSFER.SendFile fills the

information about a new output file to the interface record (using the DSG_MIG21

routines), for example the file name, the status (errors) or the changed optional data

for this file.

This means that, if a file is sent, the file is only noticed to send. This is a different to

AMTrix where a send command sends a file immediately.

After the old conversion program has finished its work it returns the extended interface

record to the Caller MBC. Now the Caller MBC reads the new values of the record

(mainly the list of output files) and sends the output files according to this information.


This also means that the output log IDs are created at this moment. And this is the

reason why the command AMTRIX.LogID does not make sense any more in the most

cases and why we have no access to the output log ID in the old map.

If the optional data was changed it interprets this information and creates new

Integrator Attributes for this. If there was an error it generates an error in the Message

Log. If the file is to send it sends the file otherwise it generates a stop for this file.

7.3.2 New functions and statements

On one hand the old modules acquired some new statements and on the other hand the

new migration library has some interesting statements which even allow the use of Integrator statements.

7.3.2.1 The TRANSFER module

If the TRANSFER module is used there are two new statements which can be used to

get the names of the current input and current output file.

TRANSFER.GetInputFileName()

After a TRANSFER.ReceiveFile is done this function returns the name of the received

input file.

TRANSFER.GetOutputFileName()

After a TRANSFER.CreateFile is done this function returns the name of the new output

file.

7.3.2.2 The Migration module DSG_MIG21

Arguments

To simulate program arguments as they are available for DPS programs in the AMTrix Process Manager, you have two new functions which take the arguments you have

given to the Caller MBC.

DSG_MIG21.ArgCount()

This function works like the function ARGUMENTCOUNT in DPS programs. The

ARGUMENTCOUNT function does still work but the results are the arguments of the

Integrator environment.

DSG_MIG21.GetArg()

This function works like the function GETARGUMENT in DPS programs and returns the

specified argument.

Message and Session IDs

Many functions and statements of the Integrator libraries need the Session ID and the Message ID. There are Message IDs for the input and for the output files but the output

files are not created at the moment the old Designer program is called. The input IDs are available and can be obtained using the following functions:

DSG_MIG21.GetSessionId()

This function returns the Session ID of the current session, the current conversion.

DSG_MIG21.GetMessageId()

This function returns the Message ID of the current input file.

Documents

B2Bi 1.4.0 AMTrixMigrationGuide AllOS En