GXS AI: Tutorial, lesson 1

Some time ago I taught a group of map developers how to work with different translators,
including Gentran Server for Windows/GIS/Sterling Integrator (SI) and GXS Application Integrator (AI) 4.*/5.*.
I prepared some materials which I’m going to share. They have a form of a step-by-step
instructions or tutorials. So, here is the first “lesson” – how to create a simple
map with GXS AI (appropriate software is supposed to be already installed).

Mention should be made that I (as almost all of my collegues) don’t use WorkBench for creating the maps – I use my text editor instead. But I used WorkBench to teach my guys because it was easier to explain them the structures. Later I showed them how to switch to using a text editor instead – we will discuss it in one of the lessons.

First simple map

As the first step we’ll try to create a simple translation map between two positional
documents. During this step we’ll learn the following terms/elements of GXS AI:

• access models
• data models
• data types
• records
• fields

Also, we’ll learn how to describe the source and target structures, create simple
links and write a simple code.

Let’s imagine that we have a very simple task – we need to create a map to translate
one simple structure into another. The source format is “A” and the target is “B”.
Both structures are simple positional documents (Fixed Length).

Format “A”

Record	Status	Name	Min	Max
LIN	M	Data Record	1	100

It’s a very simple document, it contains the same records LIN. At least one LIN record is mandatory,
there might be up to 100 LINs. The LIN record has the following format:

Record	Field	Name	Data Type	Status	Length	Position	Notes
LIN
	01	Record ID	AN	M	3	1-3	Always “LIN”
	02	Line Item ID	AN	M	12	4-15	UPC Code
	03	Quantity	N0	M	3	16-18	Qty ordered
	04	Unit Price	N	M	10	19-28	Item Price, USD
	05	Expiration Date	DT	M	8	29-36	Expiration Date, format YYYYMMDD

As you can see, the record contains 5 fields. The first one is the record ID (LIN)
– it’s a common practice to use the first (or one of the first) field as the record
indicator. The rest of the fields are intended for storing the data, such as the Item ID,
quantity, price and expiration date.

Data example:

LIN0123456789120500000125,9920100412
LIN0123456654371500000025,0020100831
LIN6678456789142500000012,0020100416
LIN9923456789151000000005,7520100519

The first record describes a product with ID of 012345678912, quantity = 50, price = 125,99 and the
Expiration date is 12 Apr 2010.

Format “B”

Record	Status	Name	Min	Max
01	M	Data Record	1	200

Record	Field	Name	Data Type	Status	Length	Position	Notes
01
	01	Record ID	AN	M	2	1-2	Always “01”
	02	Line #	N	M	3	3-5	Line Number
	03	Line Item ID	AN	M	12	6-17	UPC Code
	04	Unit Price	N	M	10	18-27	Item Price, USD
	05	Quantity	N	M	3	28-30	Qty ordered
	06	Expiration Date	DT	M	8	31-38	Expiration Date, format MM/DD/YY

As you can see, the format “B” is very close to “A”. “B” contains one more field – Line # (position),
the Expiration Date is MM/DD/YY instead of YYYMMDD and the Unit Price/Quantity goes in the opposite
direction.

010010123456789120000125,9905004/12/10
010020123456654370000025,0015008/31/10
010036678456789140000012,0025004/16/10
010049923456789150000005,7510005/19/10

Creating a base template

OK, now let’s create an “empty” template to start from.

1. Create a folder example01 in D:\Trandev\models\
2. Launch WorkBench (WB). You can find a WB description here: D:\Trandev\WBHelp_en\WorkbenchHelp.htm,
   “Introduction to Workbench”/”Basics of Workbench”:
   
   
3. Select File->New->Data Model->Source in the top menu. It means that we’re going to describe the
   source document’s format. Data Model is the description of the structure of source or target
   document.
   
   
4. In the opened window select the Access Model – “Application Mapping”. Access Model describes the way GXS AI will process the structure. For the flat files (like our “A” and “B” formats) you should select “Application Mapping”:
   
   
5. Click “OK” and you’ll see the following:
   
   
6. Important note: as you can see, the physical path is incorrect. It’s D:\Trandev\models\NewModel1.mdl but we want to save our map (in this case it’s a part of the map – the source model) in the example01 directory. So, click File->Save As->Data Model, open example01 directory and save the model as “example01S.mdl”.
   
   
7. Now, let’s create a template for the target Data Model. Select File->New->Data Model->Target:
   
   
8. Again, select “Application Mapping” and click “OK”
   
   
9. Now, as you can see, there are two models – source (left) and target (right). One of them is active (and the other is not) so when you click Ctrl+S you save only the active model (!)
   
   
10. Make the target model active and save it in the example01 folder as “example01T.mdl”
11. Now… close the map (File->Close All)
    
    
12. With using of your text editor create a file with the name of “example01.att” (not “example01.att.txt” !!!) in D:\Trandev\models\example01 and put the following into it:

    ;;                                   example01.att
    ;;                                    ver 4.0
    ;;                                --------------
    S_ACCESS = "OTFixed.acc"
    S_MODEL = "D:\Trandev\models\example01\example01S.mdl"
    T_ACCESS = "OTFixed.acc"
    T_MODEL = "D:\Trandev\models\example01\example01T.mdl"

    This file describes our first map, access and data models for both the source and the target. “OTFixed.acc” is the name of the Access Model for the “Application Mapping”

13. Finally, get back to WorkBench, close/open the folder tree to refresh it, find “example01” folder and doubleclick on “example01.att”:
    
    
    
    You’ll see the template for our first map. Both the source and the target structures are empty yet.

Describing the data structures

Now we have to describe the data structures so our map will be able to process the source file and generate the right output.

Activate the source model in WorkBench. One more time (just in case) – you should
make sure the right part of the map is active. By default,both models have only
two groups – Initialization and Document. How do I recognize that they are
groups? What are the groups? To answer the first question, click on the “Document”
node in the structure tree and in the DMI Editor section and select the DMI Attributes
tab. You’ll see the name, access type, min/max of repetition and some other attributes:


About the groups. Group is an element of the model’s structure which may include
other structure’s elements like other groups and records. Usually we use group in
the following situations:

• To store repeating sequence of groups and/or records
• As a place for some
  code/logic

The group “Initialization” is used for variables and arrays. These
entities are one of the most important parts of the mapping logic in AI.AI uses
them to transfer data from the source to target structures. We’ll discuss them a
little bit later.

The group “Document” is the root element of the structure and we’ll describe our
structures under this element.

Now let’s add a new group – Comments at the top of the source structure ([GK] it
was one of the client’s requirements). To do it, select the “Initialization”group
in the source (left) model and select Model->Insert Item->Above in the top
menu:


You’ll see something like this:


By default, WorkBech creates groups (not records). Now we should rename the group
into “Comments”.

Important note: Every time you click on the “Insert” button on your keyboard, WorkBench
creates a new group inthe active structure. So, don’t use Ctrl+Ins/Shift+Ins combinations
to copy/paste any values – use Ctrl+C/Ctrl+V instead.

If you accidentally created a group, you can delete it with using of the following
button:

Now select this new group “Comments” and click on the “Rule Builder” tab. Rule Builder
is used to create the code.



To add a new code click on the icon with the plus sign. You’ll see the editor’s
window (textarea) with “[]” text. There is also a radiogroup with 3 options: “Present Rules”,
“Absent Rules” and “Error Rules”. They are used to indicate in which case your code
should be executed. Almost always we’ll use the “Present Rules” option so make sure
it’s selected.

Add the following code into the textarea

[ ]
;;--------------------------------------------
;;* Modelname   : example01S.mdl
;;* Author      : Gennady Kim
;;* Date        : 30-Mar-2010
;;* Description : Original Issue
;;--------------------------------------------

It’s just an example. “;” means that the following string is just a comment, not a code.

Save your model. To do it you should click on the following icon (see below).

Ctrl + S doesn’t save your model!

Now, it’s time to create the structures

Gennady Kim

• Application Integrator
• GXS AI
• Translation