Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
Axway B2Bi
Version 1.4
15 October 2010
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.
Preface
DISCLAIMER
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.
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.
This guide is intended for users who wish to migrate from AMTrix 4.4.3 to Axway B2Bi.
ASSUMED KNOWLEDGE
To learn about Integrations and Creator MBCs, refer to the Synchrony Integrator documentation.
Migration Guide
Preface
Pre
RELATED DOCUMENTATION
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
Migration Guide
Preface
Pre
Contents
8 8
8 8
9 9
9
Migration tools
2.2.1 2.2.2 2.2.3 2.2.4 2.2.5 Migration development environment Using the Migration Cross Compiler The Migration Cross Compiler configuration file Starting the Migration Cross Compiler Compiling the maps
10
11 11 13 13 13
2.3
14
14 14 16 19
2.4
20
20 21 21 22 23 24 24 24
Migrating Datamapper maps 3.1 3.2 3.3 3.4 3.5 3.6 3.7 About Datamapper maps Migrating AMTrix XML Datamapper Maps Importing application pickups Upgrading XML Version 1 Datamapper Maps Migration procedure for Datamapper maps Supported PGM statements in B2Bi In case of problems
26 26 26 27 27 27 28 28 29
Migration Guide
Contents
4.1
Agreements to Integrations
4.1.1 Flow-related migration restrictions 4.1.2 Additional migration restrictions
29
29 30
4.2
30
30 30
4.3
31
31 31 33 36
37 37 38
38 38
4.7
Migrating agreements
4.7.1 General migration restrictions 4.7.2 Inbound EDIFACT Envelope Agreement, IEE 4.7.3 Outbound EDIFACT Envelope Agreement, OEE 4.7.4 Outbound EDIFACT Document Agreement, OED 4.7.5 Inbound EDIFACT Gateway Agreement, IEG 4.7.6 X12 Envelope Agreements IXE, IXD, OXE, OXD, IXG 4.7.7 In-house Agreement, INH 4.7.8 In-house Gateway Agreement, INHG 4.7.9 Native Agreement, NAT 4.7.10 Native Agreements: Analysis
39
39 40 41 42 42 43 43 44 45 46
4.8 5
49 50 50 51 53 55 55
55 56 56
Migrating AMTrix In-house detectors 5.1 5.2 Overview of the migration Attribute descriptions
6 7
7.2
Translated commands
7.2.1 7.2.2 7.2.3 7.2.4 7.2.5 Program arguments RECEIVE and SEND AMTRIX module TRANSFER module PGM module
56
56 56 58 59 60
7.3
Migration interface
62
Migration Guide
Contents
62 63
Migration Guide
Contents
1 Prerequisites
IN THIS CHAPTER
This chapter describes the prerequisites for migrating from AMTrix 4.4.3 to Axway B2Bi 1.4.
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
Migration Guide
Prerequisites
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
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
Migration Guide
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.
Migration Guide
10
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
Command window in which you type migration commands (r4edi, c4edi) Configuration file for mcc.x4
2.2.2
Migration Guide
11
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! 2533/ 2536 WARNING: DATABASE 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! 3613/ 3621 WARNING: DATABASE Statement found. May not work! 3614/ 3622 WARNING: EXEC Statement found. May not work! 3618/ 3626 WARNING: EXEC Statement found. May not work! 3620/ 3628 WARNING: EXEC Statement found. May not work! 3621/ 3629 WARNING: DATABASE Statement found. May not work! 15411/ 15417 WARNING: DATABASE Statement found. May not work! 15417/ 15423 WARNING: EXEC Statement found. May not work! 15434/ 15440 WARNING: DATABASE Statement found. May not work!
The report provides the line numbers of the source, the destination code and gives information or warnings.
Migration Guide
12
2.2.3
Indent=3 DelPragma=1
ListStatements=0 BraceNL
2.2.4
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
Migration Guide
13
name. In this template, the variable parts with XXXXX have to be changed to <mapname>. 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.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
Migration Guide
14
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
Migration Guide
15
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!
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
Migration Guide
16
/* * 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
Migration Guide
17
DECLARE DECLARE DECLARE DECLARE DECLARE DECLARE DECLARE DECLARE DECLARE DECLARE DECLARE
STATEMENT STATEMENT STATEMENT STATEMENT STATEMENT STATEMENT STATEMENT STATEMENT STATEMENT STATEMENT STATEMENT
SetupConversionTypeEDIToFile SetupConversionTypeFileToFile SetupConversionTypeFileToEDI MODULE_INIT GetInterfaceInfo Init IN $Debug StoreSocket IN $socket Terminate GetProgramInfo ConvertFromEDIDocument ConvertFileToFile 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 INCLUDE INCLUDE INCLUDE ...
Migration Guide
18
2.3.4
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).
Migration Guide
19
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"; INCLUDE "amtrix.s4h"; DECLARE DECLARE DECLARE DECLARE $TxtBuffer STRING; $NumLines INTEGER; $StrFilter STRING; $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"; } } READ $TxtBuffer UNTIL "\n"; } TRANSFER.SendFile; TRANSFER.DeleteFile; LOG "Processed lines: " & $NumLines TYPE "INFO"; }
Migration Guide
20
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
IF NOT DSG_MIG21.ArgCount() { LOG "Please enter the argument" TYPE "ERROR"; /* EXIT 1; (Statement should be replaced by THROW) */ THROW"EXECUTE"; } $StrFilter = DSG_MIG21.GetArg(1); $LenFilter = STRLEN($StrFilter); WHILE 1 {
Migration Guide
21
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"; } } READ $TxtBuffer UNTIL "\n"; } TRANSFER.SendFile; TRANSFER.DeleteFile; LOG "Processed lines: " & $NumLines TYPE "INFO"; }
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
Migration Guide
22
DECLARE MODULE INTERFACE MBC_GENERICPROPERTYSTAGE {} DECLARE STATEMENT OLD_MAIN { DECLARE $TxtBuffer STRING; DECLARE $NumLines INTEGER; DECLARE $StrFilter STRING; DECLARE $LenFilter INTEGER; IF NOT DSG_MIG21.ArgCount() { LOG "Please enter the argument" TYPE "ERROR"; /* EXIT 1; (Statement should be replaced by THROW) */ THROW"EXECUTE"; } $StrFilter = DSG_MIG21.GetArg(1); $LenFilter = STRLEN($StrFilter); 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"; } } READ $TxtBuffer UNTIL "\n"; } TRANSFER.SendFile; TRANSFER.DeleteFile; LOG "Processed lines: " & $NumLines TYPE "INFO"; 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
Migration Guide
23
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"; INCLUDE "pgmmodule2.s4" ONCE; 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; INCLUDE "pgmmodule2.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
2.4.7
2.4.8
Migration Guide
24
Select your migrated program in the component field 6. Fill in the necessary arguments (refer to the Attributes section in the Appendix).
Migration Guide
25
This chapter describes how to migrate DataMapper maps from AMTrix to Axway B2Bi.
Migration Guide
26
Migration Guide
27
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.
Migration Guide
28
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.1
Migration Guide
29
4.1.2
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 Administrators Guide, available on the Axway B2Bi Server Core DVD.
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
Migration Guide
30
a b
Password for access to store server. As default the password in $AMTRIX_DATA/config/serverpasswd will be used. 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.2
This zip file can be imported into Gateway Interchange. You can use the following additional options with this command. Option [-A prefix] Description 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. 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. Automatically generate EBM XML messaging profiles. This option enables the automatic generation of EBM XML messaging
[-B prefix]
[-a ]
Migration Guide
31
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 ] [-i ] Disable migration of AMTrix In-house agreements. 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. 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] [-q] Disable creation of zip files. 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.
[-j ]
Migration Guide
32
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 ] [-u ] [-x ] Disable migration of AMTrix Native agreements. Disable migration of AMTrix In-house Gateway agreements. 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. Disable creation of routing identifiers for inbound In-house or XML messaging profiles.
[-y ]
4.3.3
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
Migration Guide
33
corresponding programs that are to be used in the B2Bi solution. Example Programs.map content:
# # '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=
Migration Guide
34
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
Migration Guide
35
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: Agreement.map 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
o o
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
Migration Guide
36
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.
Migration Guide
37
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.2
Migration Guide
38
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.1
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
Migration Guide
39
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
[ - 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
Migration Guide
40
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
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.
Migration Guide
41
4.7.4
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. Additional post transfer processing: Not set. 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. Document Profile Attributes: Taken from the OED Parameters. Attribute names are given the prefix "B2BIDOC_".
4.7.5
Migration Guide
42
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. 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 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 Document Profile Attributes: Taken from the IEG Parameters. The attribute names are given the prefix "B2BIDOC_".
4.7.6
4.7.7
Migration Guide
43
If the input format is known, the migration program creates either a XML or an Inhouse 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. Additional post envelope processing: Not set. Additional post transfer processing: Not set. 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 DP name: DocumentType DocumentService: The DS, created through the INH, is selected. Use a messaging profile for enveloping of map output: Not set. Document Profile Attributes: Taken from the INH Parameters. The attribute names are given the prefix "B2BIDOC_".
4.7.8
Migration Guide
44
'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 contains a customer DPS. Initial processing step: Not set. Additional document processing: 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. Additional post envelope processing: Not set. Additional post transfer processing: Not set. 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. Use a messaging profile for enveloping of map output: Not set. Document Profile Attributes: 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 contains a customer DPS.
Migration Guide
45
Initial processing step: Not set. Additional document processing: 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. Additional post envelope processing: Not set. Additional post transfer processing: Not set. 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 DP name: DocumentType DocumentService: The DS, created through the NAT, is selected. Use a messaging profile for enveloping of map output: Not set. Document Profile Attributes: Taken from the NAT Parameters. Attribute names are given the prefix "B2BIDOC_".
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:
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:
Migration Guide
46
The recipient identifier is matched against the Community routing identifier defined in the messaging profile. 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
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:
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
When you specify EDIFACT as the analysis type, the classifier value is retrieved from the envelope of the received message. Source Address Source Sub Address Destination Address Destination Sub Address Document Type 4.7.10.4 EDIFACT/ODETTE Element Reference UNB S002:0004 UNB S002:0008 UNB S003:0010 UNB S003:0014 UNH S009:0065 or UNB S0026
When you specify X12 as the analysis type, the classifier value is retrieved from the envelope of the received message. Source Address Source Sub Address X12 Element Reference ISA06 NONE
Migration Guide
47
When you specify TRADACOMS as the analysis type, the classifier value is retrieved from the envelope of the received message. Source Address Source Sub Address Destination Address Destination Sub Address Document Type 4.7.10.6 TRADACOMS Element Reference STX FROM:Code, or FROM:Name if Code is blank STX FROM:Name , if Code is non-blank, otherwise NONE STX UNTO:Code, or UNTO:Name if Code is blank STX UNTO:Name, if Code is non-blank, otherwise NONE MHD TYPE: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: Source Address Source Sub Address Destination Address Destination Sub Address Message Type TransferData references Sender email address Not defined Recipient email address Not defined Email subject TransferData references PutApplName field ApplIdentityData field NONE NONE ApplOriginData field
MQ: Source Address Source Sub Address Destination Address Destination Sub Address Message Type
4.7.10.7
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 inhouse 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.
Migration Guide
48
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
Migration Guide
49
This chapter describes In-house detectors in AMTrix and in Axway B2Bi, and describes how to create them in provides B2Bi.
STRING; STRING; STRING; STRING; STRING; STRING; STRING; STRING; STRING; RECORD STRING;
Migration Guide
50
DECLARE PUBLIC FIELD $Value DECLARE PUBLIC FIELD $SkipIfEmptyOrAbsent false */ } DECLARE PUBLIC FIELD $Direction }
/* true |
The include file for this MBC is b2bi_detector.s4h which can be found in $CORE_SOLUTIONS_LOCAL/4edi/include.
Migration Guide
51
It can be omitted if the $DocumentAttribute is used to do the detection. If the value is 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. 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.. $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
52
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
53
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
54
7 Appendix
IN THIS CHAPTER
This appendix provides additional information you may need to refer to during the migration of AMTrix 4.4.3 map programs.
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. (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. (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.
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.
Migration Guide
Appendix
55
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.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
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];
Migration Guide
Appendix
56
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.
Migration Guide
Appendix
57
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] $FTP[$FTP_Server] $FTP[$FTP_User] $FTP[$FTP_Account] $FTP[$FTP_Password] = Name of the transferred file = Host name or IP = User = Account = 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] $FTP[$FTP_Server] $FTP[$FTP_User] $FTP[$FTP_Account] $FTP[$FTP_Password] = Name of the transferred file = Host name or IP = User = Account = Password
Migration Guide
Appendix
58
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: TRANSFER.ReceiveFile; TRANSFER.CreateFile; # Converting the input file to the output file TRANSFER.SendFile; TRANSFER.DeleteFile; 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 STATEMENT OLD_MAIN { 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
Migration Guide
Appendix
59
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
Migration Guide
Appendix
60
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.
Migration Guide
Appendix
61
7.3.1
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.
Migration Guide
Appendix
62
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
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.
Migration Guide
Appendix
63