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

Advertisements

41 thoughts on “GXS AI: Tutorial, lesson 1

  1. Hi Kim,

    I want to create an inbound map from EDI to flat. my question is where do i need to give details of
    delimiters present in input file in Application Integrator workbench.

    Regards
    Santosh

      • Thank u Gennady.

        I added above lines in the Initialisation section now when i am testing my inbound map i am gettibg below error

        IO: c = 66 Set start_char 65 end_char 90
        IO: c = 69 Set start_char 65 end_char 90
        IO: c = 71 Set start_char 65 end_char 90
        IO: read_set returning “BEG”; byte length = 3
        BEG Matching BEG to BEG dm->dh 74884480
        IO: func SECOND_DELIM called
        fill_sdm initial pre condition Seg_label met
        ||| —————-
        ||| DM: BEG_set instance 0 level 3
        fp_save set to 4 in BEG_set
        line number: 0; position: 3
        BEG_set – PRESENT rules
        [ NULL CONDITION ]
        +++ EVAL +++ VAR->OTElemCnt returning eval not instantiated
        exec_ops status 139

        Frankly telling you my knowledge in GXS..I have never work on it i am just seing existing map and trying to create it.
        Please help

    • as I remember, it’s because you’re trying to test the map out of environment, i.e. without deenveloping. To “fix” this problem, try this:

      In the text editor, open your source model and add right after the first comments block:

      ….
      ;;; WorkBench 4.0 checksum = 455413611
      ;;;
      DECLARATIONS {
      INCLUDE “OTX12.inc”
      INCLUDE “OTMainInit.inc”
      INCLUDE “OTError.inc”
      }

      Save and close. At the beginning of the source model (Initialization group), add

      [ ]
      PERFORM(“OTSrcInit”, “STD|X12|004010”, “X12”)

      [ ]
      SET_SECOND_DELIM(“*”)
      SET_FIRST_DELIM(“~”)
      [ ]
      VAR->OTElemCnt = 1
      VAR->OTCompCnt = 1
      VAR->OTTagCnt = 1

      That should be enough

  2. Thank you very much Kim…

    with your help i completed my first inbound map…….

    I have again two questions for you ๐Ÿ™‚

    1. In sterling B2B map editor we import EDI structures from standards, dtd files etc. Do we have any
    such kind of options in GXS workbench to upload EDI structures from standards. If yes where i can find that out
    out…I tried looking into folders but no success.

    2. If i need to migrate GXS maps to sterling B2B maps, do i need to create specification file for all structure and rules manually or there are availability of tool which can help me in creating specification file containing input, output side and rules info.

    Please help

    Regards
    Santosh.

    • Hi Santosh,

      BTW, my name is not Kim (Kim is my last name). My name is Gennady ๐Ÿ™‚

      About #1: There should be separate disks with the standard models, for X12, for EDIFACT and so on. There are folders and Source/Target Standard Models, like 4010/4010810S.STD, 4010/4010810T.STD. Plus there are some plugins. GXS approach is not the same as Sterling/IBM and their DB with standards

      About #2: As I know, there is no way of migration automation between GXS and Sterling. I tried to create a tool to help with it (with using of DDF files) but finally we didn’t use it.

  3. Hi Gennady :-),

    Thanks for reply.
    Is there any chance that the tool you developed is still with you and you willing to share it.
    If not that please share the logic to implement it.Right now i can think only one way that to write
    program for it .

    Regards
    Santosh

    • Just an idea: GXS AI uses text files (models), Sterling MapEditor might use .mxl format for the maps. I developed a parser which could:
      – create a base Sterling map with using of DDFs for both source and target. I.e. there was a library with DDFs for X12 and SAP Idocs, and you should choose the map type (X12 850 -> SAP IDoc ORDERS for example). The tool took 850 DDF and ORDERS DDF and created the base map – 850 as the source and ORDERS as the target. In MXL format.
      – Then it parsed both S and T models from GXS AI. From the T model it gathered the information about variables/arrays used and the elements names. From the S model – information about the source fields. And then it created a simple links in this Sterling base map + it generated some kind of report on the logic found.

      It was pretty primitive and we didn’t use it. I would recommend you to write a tool which would create a report with all the logic it could find (element + appropriate code). Something like Print to File in Sterling

  4. Hi Gennady,

    One quick doubt…while mapping input to output i first took the input field in a variable and then assigned it to output.
    but i can see in many map component files(.att) here that direct links are present.

    How we use direct link here. I can see in menu bar a option as Link but not getting how to use.

    Could you help me to understand.

    Regards
    Santosh

    • hi

      don’t understand why you’re asking about an 888 sample here. This post is not about samples or Item Maintenance ๐Ÿ™‚

      ST*888*0001~
      N1*DE*COMPANY NAME*9*2015113080000~
      G62*09*20140214~
      G53*001~
      NTE*PDS*FSH~
      LX*1~
      G39**MF*42109**4.8*N*K*22*CM*33*CM*44*CM*0.555*HL*010004*******UK*12345678901234*G*6.66~
      G69*DESC~
      LIN**VN*11223344*********C6*Z001*EJ*T~
      N9*SHL*84~
      N9*RV*36~
      SE*12*0001~

  5. Hi Gennady,

    How are you?
    Please help me with below problem
    I am doing an EDI to XML mapping. There is an element in output side named “Container” which has structure like

    Container
    sub-element1 value /sub-element1
    sub-element2 value /sub-element2
    sub-element3 value /sub-element3
    /Container

    We are not mapping any field from EDI input side to this Container element or its sub-elements
    but in expected output file we need to get container tag as below
    /Details
    Containers /
    /Shipment

    Could you help me how can i get a tag name in output side which is having no content.

    Regards
    Santosh

      • if this question about Sterling GIS/SI/Gentran Map Editor and not about GXS AI, try the following: create a link from any mandatory field in the input to the Pcdata block of this Container element. Try if it creates non-empty Container in the output (like Container {some data} /Container ). Then, add an extended rule to your Container element, like #Container = “”; to make it empty. I don’t have access to SI so cannot test it…

  6. I am sorry for confusion, I am using Sterling integrator Map editor i Just
    pasted year because i have kept this page in my favourites.

  7. Gennady,
    could you please share the documents, as i am very keen to learn GXS Application Integrator. Also let me know if you have any plans to schedule the training on it. thanks Much!!

  8. I’m new to gxs and i would like to open existing maps created in gxs and planning to create mapping workbook based on the existing maps.

    • Just fyi, i have installed AI, Workbench on my machine. I’m trying to open .att files but could not see any mapping links between source and target modes. Please help me how to open map components files and to check the mapping between source and target fields.

  9. Hi Gennady,

    I am new to GXS Application Integrator ,Can you provide some documentation ? If you provide this that would be a great help.
    Thanks in Advance

  10. Hi Sir ,
    This is malakonda reddy .T
    i am unable to Analyze the MAP “SPEC” can u give me the guide lines for Analyze the MAP . for developoing map

    Thanks Advance.

    • not sure if I understand what you mean. There are specs – documents which describe formats, and bridges/designs/crosswalks which describe the mapping rules. There are no standards, but usually PDF/MS Word is used for the specs and MS Excel – for bridges. These documents are designed for human beings ๐Ÿ™‚ and all you need just to read them like any other document

  11. Hello Gennady,

    I want to learn EDI mapping …So
    I tried find the work bench that you used in the above tutorial but eventually failed , Can you please let me know which work bench you are using to develop the EDI Maps and how can I get it

    • it was an old version – GXS AI 4.1. Workbench is not that important comparing with the server… So you need both Server and (optional) workbench. Where you can get them – it is hard to say… Usually it is client who provides necessary software. Maybe you could ask somebody to give you access to it, I don’t know

      • server is a service/console application you use to test your maps (in particular). I.e. Workbench is just a IDE, but to test your maps (which is important part of this work) you should have the server up and running.

        Maps might be developed in Notepad, workbench is not a vital part. But server is.

  12. Thank You again for the clarification..Can we use third party map developments tools(such as Altova Map force/Stylus Studio X16 XML Enterprise Suite) to develop the maps

  13. Hello Kim,
    I have installed AI Workbench 5.2 on my machine. Iโ€™m trying to open workbench getting this error (“C:\Trandev52\WB52\WorkbenchWorkspace\.metadata\.log”) . Please help me how to resolve this error. I have installed JAVA(6.0.23.0) also.

  14. Follow below steps.
    1. Install cservr
    2. Install WB ( make sure cservr is running)
    While installing the WB it will ask for java installation in WB. Say yes and install the java which comes with WB. After successful installation it will work.

  15. Hello Kim,

    I was wondering if you knew of a public group that offers help / ideas on Gentran Unix 6.1? I no longer work with the Windows version of Gentran.. Let me thank you in advance if you do know of any groups put there..
    -carlos

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s