Exercise 1 – Turning a Fixed-Width File into XML

Start the eiConsole. Your introductory dialog is the “Route File Management” dialog. At the top of your screen is the File Management context – within it, Working Directory and EIP Server. Select as your working directory the Basic Training directory.

Under Route Overview, you have a number of options, as well as under Associated Formats – we will not be utilizing any of them in Basic Training. Instead, at the bottom of the screen, you will see the options Import Route/Format – we won’t be using this – Edit Route, Add Route, Copy Route, Delete Route, and Close. These last five are the only ones you will be interacting with at all – you probably won’t touch Copy Route or Delete Route, but you can experiment with them in the course of developing understanding, if you want, for example, to create a duplicate route to test something without damaging your productive routes. (We will utilize outputs from one exercise as inputs for the next, so you want to keep all exercises intact for the purposes of training.)

You shouldn’t have any Routes, assuming you are running from a clean install, which you should be for purposes of learning this software. If you are utilizing a copy on another individual’s computer, make sure to check with them that their work is backed up, and simply exercise good conduct and don’t modify their routes without their permission.

Click Add Route. Name it whatever you want – I named mine testRouteOne. Now click on your route where it appeared in the dialog, and click Edit Route. You are now on the Route Editing screen.

Your First Route:

This screen should appear quite desolate when you first enter it. You’ll have Source System, Listener, Source Transform, Route, Target Transform, Transport, and Target System items, with an icon only under Route. At the top are Add Source, Delete Source, Add Target, and Delete Target buttons. These will become self-explanatory as we progress. For now, add both a source and a target.

Some pretty icons appeared! We aren’t going to worry about either the Source System or the Target System right now. Instead, click on the “Not Defined” icon under Listener. Here, you have Listener Configuration and Processor Configuration. Processor Configuration will be treated later – right now, give your Listener a name.

Listener Type:

Under Listener Type, you have a range of different options – you may need to resize your dialog to see all the context information for some of them. The context information should be self-explanatory for each of the options if you are familiar with the data source you’re attempting to utilize. The polling interval is by default -1; set this at 3. Set the Listener Type as Directory.

Select this chapter folder as your polling directory, and alienFlat as your filename restriction. Your Postprocess operation has two options – Delete or Move. (This is to prevent it from continually reading the same file.) Select Move, and set the target directory as this chapter folder – we aren’t going to be running this operation in anything but test mode, so we’re not worried about it continually rereading the file. You have just told it to read files named alienFlat from this directory every three seconds, if it can find such a file – if it can’t find it, it will wait until such a file appears. Once it is done, it will move the file into the same directory, and append the filename with a number indicating which instance it is. Fairly simple. Take the time now to open up alienFlat and see what it looks like – it is a fixed-width space delimited file. Some spreadsheet software packages can open this file up as well if you want to see it in the spreadsheet form.

Source Transform:

You could select a format profile, if you had one defined – we don’t yet, so let’s do that. Click “Add Format,” and choose a descriptive name you’ll recognize later, like EOneST. Adjust the dialog size again if necessary to fit the additional context.

You won’t be interacting with Format Info or Forking here – instead, select Transformation Module. We’re operating on a fixed-width file, so select Delimited and Fixed-Width File. We now need to configure the transformation – select Edit, below that. The opening dialog will ask you where to get the field names from – these are all self-explanatory, and we’re using a Fixed-Width, so select Other, and select Fixed-Width for both items, and hit Save.

On the left, you’ll see an empty space. Right-click on Base and add a record called “Alien.” On the right, in the center, you’ll see a Results Preview space – select the Open File icon just above it, and open alienFlat, located in this chapter directory. Notice that the first row is the header titles – so activate the “First Row is Headers” item at the top right of the screen.

On the left, right-click on Alien, and add a field called “Name”. Set the Start value at 1, and set Length at 9. (I’m giving you the specific length values used – you could count them yourself, in the text file, by starting at the first character in the item in question and continuing on to the last space before the next character. For files you create or integrate into your system, this will be what you need to do.) Add a field called “Race”, with a length of 10 – its starting point is automatically assigned. Similarly, the next field, Age, will also have a length of 10. Execute Transform – you should end up with four “Record: Alien”s, which you can expand by clicking on them, to see that their contents match the values in the fixed-width file you see above. Save your work, giving it a descriptive title, and exit this dialog.

You don’t need to configure XSLT on this, as you’ve already described the transform mechanism. Don’t worry about Route yet, let’s just move on to Target Transform.

Target Transform:

This part isn’t necessary, as the format is already fine, we’re doing it to familiarize you with the Target Transform dialog.

We need an example file to make this work. So, select Route from the menus, and switch to Testing mode. Nice screen, huh? Select Listener, and Start Test Here. Select Source Transform, and End Test here. Click the Execute Test button up at the top, and wait a few seconds – it should run, and then stop. view the stage output, and then save it with a nice descriptive name in this chapter folder, with the extension .xml .

Go back to editing mode, and select Target Transform.

Select Add Format. I named mine EOneTT.

This time we’re going to configure the XSLT. Disable Direct Relay, and select Edit.

Nice dialog, huh? We won’t be messing with MOST of this right now. ON the far left side of the screen, there is a big wide open space, above which is a single activated icon – “Open source format.” Click this, select XML Format Builder, and then “Add” the file you created just a moment ago. Read the Format – it will ask you if you want to use it as an example format – say yes. You should now have a nice blue sphere that says XCSData. Double-click it to see its contents. Why, there’s Alien, complete with Name, Race, and Age. Excellent.

On the right side, open a target format – select XML Format Builder again, remove the previous file, and then add the file “Alien.xml”, included in this directory. It will build a target format item.

Drag the “XCSData” icon into the center context – this has to do with the XSLT structure, and you are establishing the data source. Drag “Alien” over onto (That is, tabbed one space to the right.) If it appears directly below or above XCSData, you didn’t drag it onto the item, so delete it in question, and try again.

Now, from the RIGHT side, (the target side), drag Name, Race, and Age onto the “Alien” tab. They should appear just below it, nested. (They should be directly above and below one another) You’ve established the data path. Now drag Name, Race, and Age from the left side, the source side, onto each of those tabs, respectively. You’re telling the program what maps to what. Each data source should appear nested in its respective data target.

At the bottom, select “Testing”, and select the “Execute Transformation” gear icon at the top. You should get this:

<?xml version="1.0" encoding="UTF-8"?>
<alien>
        <name>zorgi</name>
        <race>pogi</race>
        <age>5</age>
</alien>

This isn’t what we want – first, only one of the aliens got converted, and second, we lost the “aliens” and “data” tabs. Let’s correct the second problem first – drag “data” over onto XCSData, and then drag “aliens” onto “data”. You can now drag “alien” (and all nested tags) on top of “aliens”, establishing what the structure should be. Go back down to testing, and execute the transformation again. You should now get this:

<?xml version="1.0" encoding="UTF-8"?>
<data>
        <aliens>
                <alien>
                        <name>zorgi</name>
                        <race>pogi</race>
                        <age>5</age>
                </alien>
        </aliens>
</data>

Which is better – the data is structured in the same format as our example file now, but there’s only one data item when a quick reference to the source data indicates there should be several. So what am I telling you to do wrong? Well, the way I have you doing it only tells it to collect one item. We need a “ForEach” function, which tells it to do the same thing several times. So go back to the mapping screen, and delete “Alien,” and everything nested in it by association.

Under XSLT Structures, on the second column bottom, there is a “For Each” function. Drag it on “Aliens.” This is a function that operates on your source data – so grab the “Alien” item from the left side (source data side), and drag it onto the @select option. This tells it to do something for each Alien in the source data. Now drag “alien” from the target data, and drop it onto the “for each” tag. (The select tag is specifically there to indicate what item it is operating for each of, so don’t try dropping it there.) It should appear nested under “for-each” directly under your @select tag. Drag name, race, and age from your target data, and drop them onto “alien” (the green target data icon under for-each), and then drag name, race, and age from your source data, and drop them onto their respective target datas. In this case, they have the same names, because we have arranged things that way – in complex transformations, this is unlikely to be the case, and you may even have to perform functions on data to transform it into the appropriate type. We’ll cover that later.

Under “testing,” make sure everything works fine – you should get four aliens matching the source data descriptions. If everything looks alright, save your configuration with a nice descriptive name, and exit this dialog.

Transport:

Now you simply have to decide what is done with the data. We want it saved as a file – go to the Transport tag, and select “Directory” under Transport Type. Use this chapter directory as your target, give it a nice descriptive target file name, and use xml as the target file extension. Done? Good. Go into testing mode and see if everything works. The final output will be displayed under Target Transformation, View Stage Output. Looks nice, doesn’t it? Yes it does.

And that concludes the first training exercise.