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
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:


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 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


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

  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

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
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

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

81 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.


      • 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

      • Hi Kim,

        Its great to see this tutorial, Can I get access to the complete tutorial for this?

    • 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
      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”)

      [ ]
      [ ]
      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


    • 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 .


    • 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.


    • hi

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

      N1*DE*COMPANY NAME*9*2015113080000~

  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

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

    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
    Containers /

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


      • 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( 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..

  16. Hi Gennedy,
    I need a help from you in writing compliance error for the below mentioned condiation.
    850 EDI that contain Multiple different items with the Same Line # for the same ref PO should fail.
    Exception scenario example :


    PO1 ITMA 10
    PO1 ITMB 10
    PO1 ITMC 10

      • I really appreciate your fast reply and help sir.
        yeah i got the concept first i will do a while loop for PO and will do another while loop for line number in that i will write if condition for checking if linenum= line num but i dont know the syntax can you just provide me the sample code for this condition please, that would be very helpful for me.

      • I prefer to use ideas. For example you have

        PO1 ITMA 10
        PO1 ITMB 20
        PO1 ITMC 10 <<< duplicate 10, should raise an error

        I would use an array or a variable, lets say PROCESSED_ITEMS

        step value
        declaration: ""
        1st iteration: "~10~"
        2nd iteration: "~10~20~"
        3rd iteration: "~10~20~10~"

        on every iteration you check if the control value with "~"s belongs to this PROCESSED_ITEMS or not (with STRPOS() function), and if yes – raise an error

    • Hi Gennady,
      I tried the approach you have given me and it worked thanks alot.
      and I wanted to suggest me approach for the following
      currently file has this order :
      they wanted the order this way:

      N9 vr shpuld be the first line and N9 m1 should be the second line.
      please help me fixing this.
      Thanks in advance.

      • it is done with a counter

        At LX level you set a counter

        [ ]
        VAR->N9_Cnt = 0

        then, in N9 loop you need to add something like

        N9_Loop {
        N9_loop_check {
        [ ]
        VAR->N9_Cnt = VAR->N9_Cnt + 1
        }*1 .. 1

        N9 { Segment “N9”

        N9_01 { …
        [VAR->N9_Cnt == 1]
        N9_01 = “VR”
        [VAR->N9_Cnt == 2]
        N9_01 = “M1”

  17. hi Gennady,
    for 947 map i have to take the ticket number from file name and map it to the output. how can i do that?
    file name for instance abc_1234abc.csv
    1234abc is the ticket number.

  18. Hi Gennady Kim,

    Do you have any PDF document for OpenText TrustedLink™ Enterprise (TLE) Basic Concepts , Advance Mapper documents ?

  19. Hi Gennady ,

    I am newly working on GXS. Could you please provide some basic documentation about the GXS tool if you have any ? thanks in advance!!

  20. Hi Gennady,

    I have learned so much from your Tutorial.You have done very good work.I am wondering if there is a way to map a SOAP call in GXS AI.Do you have any idea regarding this?

  21. Hi Gennady,

    Do you have any article written about the Datatypes.If not could you please give some info for N and R with some examples.

    • R = Real, number with decimal part, like 12 or 12.34 or 12.00
      N = Natural. N0 – Integer, i.e. 123 in N2 format = 123. NX where X = 1, 2, … are special format, X describes the number of decimal positions, hope this example would help you:

      N1 format Real Value
      123 = 12.3
      120 = 12
      12 = 1.2
      1 = 0.1

      N2 format Real Value
      123 = 1.23
      120 = 1.2
      12 = 0.12
      1 = 0.01

  22. Pingback: IBM Sterling Gentran Server Training | Nisa Online Trainings - Online Training Platform To Learn In Demand & Latest Tools
  23. Hi Kim,

    I have followed your lessons 1 thru 6. When I am testing the translation, I am getting error 138. I have played with both source and target models and have not been able to fix it.

    Below are a couple of lines from the log file.

    ||| FINISHED ExpirationDate: status 0 statusc 0 occurrence 1 max occurrence 1
    post_cond oCRmLF not found
    err_push() status 138 msg “Post_cond oCRmLF of LIN not found” type 4 errstkp 0
    resetting fp to 0 in Document
    err_push() status 138 msg “DM_OBJ Document not found” type 4 errstkp 1
    Error: 138 type 4 msg DM_OBJ Document not found
    Error: 138 type 4 msg Post_cond oCRmLF of LIN not found
    Closing file: “C:\Trandev53\models\example01\in.txt”
    Closing file: “C:\Trandev53\models\example01\out.txt”
    Value Memory Info [Size = 7 KB ( 1 Pages @ 7936 Bytes/Page), Swapped? N, Max Memory = 923459 KB ( 119156 Pages)].
    send STATUS 138 to job 114
    Session 000114 ended at Thu Sep 2 11:54:31 2021
    with error cd 138

    Thank you.

    • Hi Ray,

      I haven’t worked with AI for years, hard to say. Here is what this error means:

      139 Data Model Item – No Value Found
      Some errors are generated to control the natural processing flow of the translator. They are soft errors and sometimes do not require any resolution. These errors get written in the trace log to show the process flow, but they do not stop the process.

      Error code 144 is returned in cases where the data model item has a value assigned to it before the function is executed. If there is no value assigned to the variable at runtime and the ampersand is missing, the translator tries to evaluate the variable. It returns error code 139 when it is unable to evaluate it.

      Cause 1: A result of the NOT_NULL( ) function; depends on whether the element is mandatory or optional.

      Resolution 1: If the element is optional (may not have a value) then use the NOT_NULL() function. This function will write out the element only if the variable references a value.

      Cause 2: No values on the Array or MetaLink.

      Resolution 2: Check that there is a value on the Array or MetaLink.

      Cause 3: Referencing a source data model item that has not been parsed yet.

      Resolution 3: Check that the data model item referenced was already parsed.

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 )

Google photo

You are commenting using your Google 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 )

Connecting to %s