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
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).
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:
|01||Record ID||AN||M||3||1-3||Always “LIN”|
|02||Line Item ID||AN||M||12||4-15||UPC Code|
|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.
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.
|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|
|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
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.
- Create a folder example01 in D:\Trandev\models\
Launch WorkBench (WB). You can find a WB description here: D:\Trandev\WBHelp_en\WorkbenchHelp.htm,
“Introduction to Workbench”/”Basics of Workbench”:
- 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
- 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”:
- Click “OK” and you’ll see the following:
- 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”.
- Now, let’s create a template for the target Data Model. Select File->New->Data Model->Target:
- Again, select “Application Mapping” and click “OK”
- 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 (!)
- Make the target model active and save it in the example01 folder as “example01T.mdl”
- Now… close the map (File->Close All)
- 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”
- 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
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
You’ll see something like this:
By default, WorkBech creates groups (not records). Now we should rename the group
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.
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
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