BridgeGate™

Tutorial 2: Creating your 1st Set of Templates

Table of Contents

Creating your 1st Set of Templates

Introduction

This second sample walks you through creating your first Inbound and Outbound Templates for a simple data format consisting of a single Record consisting of 5 Fields. Only the basics are discussed here, with most of the bells and whistles left alone. As the Samples and Tutorials progress, we will go into more and more of the exciting features available in BridgeGate TEI.

Before we begin creating our Templates, let's take a look at our sample data format and gather an understanding of its requirements. Our data format consists of a single Record, named 'Person'. This Record consists of only 5 Fields- First Name, Last Name, Sex, Hair Color, Age. Most data formats use a delimiter to separate Records, and another, usually different, delimiter to separate Fields. For our example, we will use a Carriage Return (CRLF) to separate Records and a comma (,) to separate the Fields within the Records. For those of you who do not know what a Carriage Return is, that's the keyboard equivalent of the enter button.

Here is our sample data we will be creating Inbound and Outbound Templates for translating:

Fred,Flintsone,Male,Black,40
Barney,Rubble,Male,Blonde,33
Betty,Rubble,Female,Black,30
Wilma,Flintstone,Female,Red,35

When the Tutorial is finished, you will have created Outbound Templates capable of turning this data into these various formats:

XML Format

<PEOPLE>
<PERSON>
<FIRST_NAME>Fred</FIRST_NAME>
<LAST_NAME>Flintstone</LAST_NAME>
<SEX>Male</SEX>
<HAIR_COLOR>Black</HAIR_COLOR>
<AGE>40</AGE>
</PERSON>
<PERSON>
<FIRST_NAME>Barney</FIRST_NAME>
<LAST_NAME>Rubble</LAST_NAME>
<SEX>Male</SEX>
<HAIR_COLOR>Blonde</HAIR_COLOR>
<AGE>33</AGE>
</PERSON>
<PERSON>
<FIRST_NAME>Betty</FIRST_NAME>
<LAST_NAME>Rubble</LAST_NAME>
<SEX>Female</SEX>
<HAIR_COLOR>Black</HAIR_COLOR>
<AGE>30</AGE>
</PERSON>
<PERSON>
<FIRST_NAME>Wilma</FIRST_NAME>
<LAST_NAME>Flintstone</LAST_NAME>
<SEX>Female</SEX>
<HAIR_COLOR>Red</HAIR_COLOR>
<AGE>35</AGE>
</PERSON>
</PEOPLE>

Delimited Format (Using EDI X12 delimiters)

PER*Fred*Flintsone*Male*Black*40~PER*Barney*Rubble*Male*Blonde*33~PER*Betty*Rubble*Female*Black*30*PER*Wilma*Flintstone*Female*Red*35~

Fixed Length

Fred
Flintstone
Male
Black
40
Barney
Rubble
Male
Blonde
33
Betty
Rubble
Female
Black
40
Wilma
Flintstone
Female
Red
35

Creating an Inbound Template

You will start by defining the Inbound Template. The Inbound Template is where you tell BridgeGate™ how the data coming in to it will look; that is, the format--such as fields, lengths, data separators (delimiters), etc. The Inbound Template describes your company's data structure. In many cases this is in the form of an EDI specification (SEF), an XML DTD or XSD, a list of Database tables and columns, or just a set of name-value pairs. BridgeGate™ is pre-configured with many common data types. The types include Fixed Length, CSV, Name Value Pairs, Delimited, XML, Database, HL7, JSON, NCPDP, and X.12EDI.

To open our Inbound Template, click on the Inbound button in the toolbar:

We are going to start by creating a new Workflow group in which to place our Inbound Template. Right mouse click in the Workflow Group Navigator, or click the drop down arrow.

Select New Workflow Group, and enter the name you wish to use for your new Workflow Group:

Now open the same menu again, and this time select New Template Wizard…

Select the radio button to create a new Inbound Template.

Name this Template 'MySample2Inbound', named after the completed Inbound Template for this Tutorial, 'Sample2Inbound'. After entering the name and clicking 'Finish', the Inbound Template Screen automatically opens as shown in the tree.

Now, we will select the drop down arrow above the Records tree on the right hand side of the screen; pick 'New Record.'

We want to have a single Record, consisting of 5 Fields. Let's create those now. Notice the tabs for 'Header' and 'Trailer'. Other Tutorials will touch on these Records so we will ignore those for now. After clicking 'New Record', the Unnamed1 is displayed:

Now repeat this action, only this time, select 'New Field'. The new unnamed Field is then displayed:

Create 4 more Fields in this manner.

Then select the UNNAMED1 Record from the tree to the right. The screen for the Record is displayed along with all 5 Fields we created in the tree as well. We will define the attributes for this record and its fields.

Our Records are delimited with a Carriage Return (CRLF) and the Fields within the Record are delimited by a Comma (,). The Template Properties in the lower left hand panel is where these settings are located. By default, the first data type in the drop down says "CSV (Comma Separated Value)". This is close to what we want, but CSV formats also have double quotes "" around each Field in addition to the commas to separate Fields. Our data format does not specify this, so we have to manually set our data type.

Select DELIMITED from the Data Type drop down.

The Record Delimiter button will show No Delimiter Chosen. Press the button for Record Delimiter.

The Delimiter Chooser will be displayed from which you can select Use CRLF.

The Record Delimiter will now be set to CRLF.

Next, press the button for Field Delimiter:

The Delimiter Chooser will be displayed from which you can select your delimiter. If not already selected, choose ASCII 44 (,) as the Field Delimiter.

The Field Delimiter will now be set to ASCII 44 (,).

Then check the Strip Quotes and the Trim Data check boxes.

Select the unnamed record in the Records tree, and name it PERSON by typing it into Record Name in Record Properties.

Now select the first Field named UNNAMED1. We will use all Char Field Type for the PERSON Record; hence choose 'Char' from the drop down list. Change the Map Name to 'First Name' and the description to 'First Name' as well.

This time, the Description entered will be displayed in the Tree to the right. We will repeat this process for each unnamed field using, Last Name, Sex, Hair Color, and Age. Thus, follow these same instructions for the first Field and name the following 4 Fields. After finishing each screen, notice the Field name change in the tree to the right.

2nd Field: Last Name
3rd Field: Sex
4th Field: Hair Color
5th Field: Age

The following screen shows all 5 Fields finished:

That's it for out Inbound Template. We now have all the information we need to define our original data. Click the Save button in the Toolbar at the top of the screen:

You will be prompted if you want to save the Inbound Template. A Save Changes/Verification screen will be displayed. Click 'Verify Selected Items'. If there are no errors found, no further instructions on the Save Verification screen are shown. Simply click the 'Save Selected Items' button.

Creating the First Outbound Template: XML

From the Toolbar, click on the Outbound button:

Similar to the process we used to create an Inbound Template, we will select the Wizard for creating an Outbound Template. Make sure that you have selected the Workflow group you created, sample2test, and again pick 'New Template Wizard' from the drop down list.

We are going to create a new Outbound Template.

Name the Outbound Template, MySample2XMLOutbound.

Again, notice CSV (Comma Separated Value) is the first data type in the drop down in the Template Properties panel, lower left hand corner.

Select XML for the data type from the drop down.

For the Inbound Template Dependencies, select MySample2Inbound, which we just created. This allows BridgeGate™ to know which Inbound Template from which we are going to create mappings.

Leave all the checkboxes, such as Trim Data, unchecked.

We can now begin to define the outbound fields. Select the <UNNAMED_ELEMENT> at the TOP of the screen named 'Records'.

In this exercise, we will create a direct mapping between the Inbound and the Outbound Templates.

Note that XML will not allow element names to contain spaces. In the verification process, if you see a warning (for example for <FIRST NAME>), you will need to change the XML Element Name to read 'FIRST_NAME', replacing the space with an underscore.

The simplest way to create your outbound XML elements is using the Mapping Mode. Make sure that the Link Mode is unchecked.

Right-click on the <UNNAMED_ELEMENT> at the TOP of the screen named 'Records'. and delete this record.

Then you may simply drag the entire tree from the Source Record Layout and drop it onto the Record tree:

Then as you select each of the newly created fields from the 'Records' tree screen, lines will display showing the mappings.:

De-selecting Mapping Mode will return the screen to the properties screen where you will see that fields have been properly mapped to the inbound data.

If we chose not to drag over our Inbound Fields, we could define them individually. This would be more convenient if we have different names and attributes in our Outbound Template than we did in our Inbound Template. To do this, right click or use the drop down in the Record tree and Add New Element under the PERSON element.

Notice the Source Layout has '?' signs next to each Field as we go. This is because they have not yet been mapped.

First, give the new Element a name, in this case use FIRST_NAME. Then you can map the Inbound to Outbound by choosing the Inbound Record and Field names in the Element Properties.

Repeat the process naming each new Element in order as LAST_NAME, SEX, HAIR_COLOR, AGE and mapping them each to the corresponding inbound data.

Another alternate way to create outbound XML elements

You may also manually create outbound XML elements one at a time, and then map them from Inbound to Outbound by dragging and dropping using the Link Mode (Link Mode Checked).

To do this, after creating the People elements, toggle the 'Drag and Drop mode icon to enable Inbound Template fields to be associated with Outbound Template fields by either dragging the fields (or records) from the inbound to the outbound, or overlay by checking the Link Mode checkbox.

The Inbound Template is displayed here to allow you to drag and drop the Inbound Records and Fields to the Target Layout, which is the right side of the screen. This allows you to quickly recreate all the Fields needed for the outbound data format without actually having to create and modify them. When you drag the Inbound field to the Outbound field, you will notice that the '?' changes to '<E>':

Since this Tutorial is only focusing on the basics of translating a data format into another, we will leave the Fields in the same order as they were read in. One by one, select the 5 Fields and drag them to the Fields on the right side. For all Records other than to top most Record, you will be prompted to insert the Field within the Record or as the next sibling to the Record. Drag the remaining Fields, one by one, onto the last dropped Field on the Target Layout, ensuring the same order is maintained. If the Fields become out of order from the Source Layout, drag them to the proper place within the Target Layout tree. BridgeGate Template Builder drops all objects BELOW the object it was dropped on. If you want, drag the Fields out of order intentionally here and place them back in order, to get a feel for the drag and drop abilities.

You may not choose to have all Records you create for the Outbound Template mapped from an Inbound Record. If you create a Record or Field in your Outbound Template that does not exist in your Inbound Template, then this is left blank. If you wish BridgeGate™ to warn you when outbound fields are unmapped, check the box: "When saving Outbound Templates, warn of unmapped Fields" from the File menu under Preferences.

All of the other properties for Fields will be discussed in later Tutorials. That's it for the first Outbound Template! Click 'Save' from the Toolbar at the top of the screen:

Testing the First Outbound Template

To test this Inbound Template/Outbound Template combination we just created, click on the Test button in the Toolbar:

The Test Template screen shows two drop down boxes. The Inbound Template drop down is the main drop down on this screen. When you select an Inbound Template, only the Outbound Templates that have been linked to the Inbound Template will show up in the Outbound Template drop down. Since we only have a single Inbound Template, it is automatically selected in the Inbound Template drop down. You should see the MySample2Inbound in the inbound list.

Copy and paste the following data into the Test Data area of the Screen.

Fred,Flintstone,Male,Black,40
Barney,Rubble,Male,Blonde,33
Betty,Rubble,Female,Black,30
Wilma,Flintstone,Female,Red,35

The translation of the data should be rendered in XML, as seen in the following screen.

Troubleshooting the First Outbound Template

The following errors are possible from the Manage Outbound Template Screen.

You Must Specific a Root Element for this outbound XML Data.

Element names cannot have a space in them. Consider using an underscore '_'.

The Root Element is specified on the 'Template Header' tab, at the top of the screen. Enter 'PEOPLE' for its value. The Fields <FIRST NAME> <LAST NAME> and <HAIR COLOR> need to be changed to <FIRST_NAME> <LAST_NAME> and <HAIR_COLOR>.

Creating the Second Outbound Template: Delimited with EDI Look

Now that you've created the XML Outbound Template, the rest of the Outbound Templates will be a breeze. While there is no Standard EDI Format for the Flintstones (no cartoon character segments either), and this format really isn't very close to an EDI spec, this section of the Tutorial will show you how quickly you can copy an already created template, make a change or two, and yield completely different looking data. To start, open the Outbound Template screen from the Toolbar:

Right-click on the existing mysample2xmloutbound template to launch the New Template Wizard. Then Click the 'Copy selected Template…' option.

Give the new template the name of 'MySample2EDIOutbound' and click 'Ok'.

The newly copied Outbound Template opens up in the Outbound Template Screen. If you still had the other Outbound Template Screen open, it was just closed and the new one opened in its place.

Even though we are going to model an X12 EDI, for the purpose of this exercise, make sure the data type drop down is 'DELIMITED' and the Record Delimiter is ~ ASCII code 126. To change this you can press the button and use the Chooser. Set the Field Delimiter to * ASCII 42.

Pick the Workflow Group and Inbound Template using the drop downs.

We are going to add an additional Field as a Constant as the first Field in this Record, above the First Name. First we want the top record to Loop over each inbound person. To do this select 'PERSON' from the Loop Record drop-down.

We will create the new Field under the PERSON Record. Right-Click on PERSON Record and select 'New Field'.

We will make this Field the SEGMENT id, which we will call 'PER' (fictional). To manually type this value in for the Field, we will change the Field Type from CHAR to CONSTANT. This is located in the middle of the screen in the Field Type Properties section. Notice when we select CONSTANT, the whole top mapping section disappears. This is because we are no longer retrieving the value for this Field from the inbound data; we are typing it in by hand. In the Constant Value text box, enter PER. Leave repeat # of times at 1. Repeatability is handy if we are repeating a value many times, such as CRLF or a space. The following screen shows us where we are at this point:

Click the Save button from the Toolbar at the top:

And the Save Verification screen is displayed. If there are no errors for this second Template, click 'Save Selected Items' as before, and close.

Testing the Second Outbound Delimited Template

Click the Test Template button from the Toolbar:

This time, change the Outbound Template from the second drop down to MySample2EDIOutbound.

The test data should still appear in the bottom of your screen:

If not, copy the following data into the Test Data window of the screen:

Fred,Flintstone,Male,Black,40
Barney,Rubble,Male,Blonde,33
Betty,Rubble,Female,Black,30
Wilma,Flintstone,Female,Red,35

Click the 'Test Translation' button and the results will display in the lower right panel of the screen:

Notice the data does not wrap around or have CRLF after each Record. This is because we used a tilde (~) for the Record delimiter.

Troubleshooting the Second Outbound Template:

The errors that could have happened here include:

PER not shown in data.

No tilde (~) is shown after each Record

My data is still XML format!

If PER is not showing up as the first Field for each Record, you have not created the Field. Also, if the tilde (~) is not showing up at the end of each Record, you have not created the Field for this either. Please follow the directions a few pages back for these. If your data is still showing as XML, close your browser, and select the MySample2EDIOutbound from the Outbound Template drop down, then click 'Test Data Translation' again.

Creating the Third Outbound Template: Fixed Length

Just like the second Outbound Template was easy to create, the Third will be just as easy. Click the Outbound button from the Toolbar:

Right click on the Outbound Template you just created, MySample2EDIutbound, and select 'Copy selected Template…'

Name this new copy MySample2FixedLengthOutbound. The newly copied Outbound Template (now your third Outbound Template) will automatically open. This time we will want the data type to FIXED LENGTH. Make sure the Record Delimiter is CRLF. Set the Workflow Group and Template to use.

In this Outbound Template, we are going to have only one Constant. Select the 'Records' tab from the top of the screen as before, select the first Field from the Outbound Record named 'Field: (Constant) PER', and hit the delete key. We no longer need this Field; it was only for the sample EDI Template. The delete action will launch a confirmation dialog box. click yes to delete the PER field.

The only other changes we will make for this Fixed Length format is to specify how long each Field will be. Since no field delimiter is used for Fixed Length, Field Length is very important. For each of the 5 Fields enter in the following Field Lengths:

First Name: 15
Last Name: 15
Sex: 6
Hair Color: 10
Age: 2

Click the Save button from the Toolbar at the top:

And the Save Verification screen is displayed. If there are no errors for this second Template, click 'Save Selected Items' as before, and close.

Testing the Third Outbound Template

Click on the Test Template button from the Toolbar at the top of the screen:

This time select the MySample2FixedLengthOutbound Template from the Outbound Template drop down. Enter in the following data:

Fred,Flintstone,Male,Black,40
Barney,Rubble,Male,Blonde,33
Betty,Rubble,Female,Black,30
Wilma,Flintstone,Female,Red,35

If you type this data in manually, and the Translation does not work, copy and paste this data in. Click the 'Test Translation' button and the results will display in the lower right panel of the screen. This last Template produces data with fixed length, columnar type fields:

This concludes Sample Tutorial 2.