With the SEEBURGER Business Integration Suite, you will be able to route, enhance, and filter messages in a well organised, secure way. This series of blogs are meant to get you going in the world of SEEBURGER integration.
In this example, we are creating a mapping with Business Partners from XML to a CSV list.
For a simple but successful mapping we need to execute the following steps:
- Create a new project
- Create or import the XSD
- Create the CSV message definition
- Start mapping
- Test mapping
- Add error handling
- Test mapping
Step 1: Create a New Project
For this demo I’ve have created a demo workspace. Go to File -> Create new project -> fill in a suitable name and description apply:
After the project is created you are able to see all different message types which are supported by SEEBURGER. In this example we are only using the CSV and XML messages.
Step 2: Create or Import XSD
In this demo I will show you how to create an XSD yourself. Ofcourse, the import functionality is a big plus in case of large messages. To create the XSD, right-click -> New -> Create XML message description -> Fill in the name and Title of the message and Apply:
At this moment we need to start building up the XML structure. First, we create a new element:
Within this element we create a sub element Business Partner with an occurrence of 0 to -1 to process multiple business partners in one message. With sub elements CustomerDetails and Location
The next step is adding Fields to the elements. For example, create the field Name:
Continue adding fields and make sure the following structure is created:
Step 3: Create the CSV Message Definition
Let’s create a CSV message definition. We would like to create a CSV list with customer name and location only. Just right-clink CSV -> New -> EDI message and name the message:
Create a record first:
Hint: After applying SEEBURGER is checking the input. If the input is incorrect it shows:
You are now able to auto-correct the input or to show information about invalid values.
Within this record we are creating the fields in the same way we have created the XML structure. Make sure the result looks like this example:
Step 4: Start Mapping
Now the mapping starts, create a new mapping with: right-click on mappings -> new -> mapping:
In the Properties of ‘Mapping’ you should select the source and destination format and name the mapping. The default name is a combination of the source and destination format. After applying the properties and opening the mapping, the view should be like:
Before starting the mapping, a record program needs to be created. Right-click on the BusinessPartners element and select ‘Create Record Program’:
Repeat this step for the sub elements CustomerDetails and Location.
Hint: Without creating a record program it is not possible to start mapping in case of XML source mappings. In this example we are mapping all elements of the XML structure so the root element can be used to create the record program. In runtime this means the full XML message will be read, in case only a particular sub elements is used, only create the record program on sub element level. This will speed up the process in runtime.
In this example we have multiple locations per business partner, it is not possible to drag and drop these items one-on-one because of the flat CSV structure. The customer details will be mapped to global variables first, then copy the name to the created variable.
Select CustomerDetails and open the Mapping Editor View. Type:
copy THIS:CustomerName to CUSTOMERNAME$;
The next step is mapping the variable and address details to the CSV file. We will copy the variable to CUSTOMERNAME and concatenate StreetName and StreetNumber to STREET. Select Location in the Source message and type:
copy CUSTOMERNAME$ to CUSTOMERADDRESS:CUSTOMERNAME;
copy THIS:StreetName &” “& THIS:StreetNumber to CUSTOMERADDRESS:STREET;
Now, drag and drop PostalCode to POSTALCODE and City to CITY.
This will result in:
It is this simple to create a XML to CSV mapping. Now save the mapping and compile.
Step 5: Test Mapping
This simple mapping can be tested in the MappingDesigner. Click on ‘Show Test Environment’.
A pop up will be shown, in this environment a test case can be created to validate the mapping. First create a new mapping configuration. Select new and confirm the default values.
The Test Environment Configurations will be filled in automatically with default values.
Now we have two options, we could select a test file or build it up from scratch using the Message Creator. Change the source File path to: C:\SEEBURGER\MappingDesigner\Test\BusinessPartnerList1.xml and select ‘Open the data to convert’. Now you have the possibility to create the XML by adding elements and fields. The result could look like:
Change the Destination File path to: C:\SEEBURGER\MappingDesigner\Test\RojoAddresslist.csv
Now select convert and the mapping will be executed.
To verify the process check the output ‘Open the converted data with alternative editor.
Step 6: Add Error Handling
To handle errors we need to create an error message first, then add error handling to our mapping and create a mapping to handle the error message. Technical errors can be handled as well as functional errors. In our example we could throw an error if the Country is not Netherlands.
Create a new XML message definition with the name Rojo_BusinessPartner_Error. Then add an error element by right-clicking the root element:
This will create the default error message.
Now, create the following mapping:
Create the record program and create the following mapping:
Save and compile the mapping.
Now we need to create a reference between the mapping and our ‘error mapping’.
Open the mapping ‘Rojo_BusinessPartner_XML_to_Rojo_CustomerAddress_CSV’ and open NewMapping (Source message: Root->Additional programs -> NewMapping).
Add the following code:
Hint: click on setErrorMapping in the mapping editor and F1 to read additional information of handling errors.
Now open the Location Mapping to add the functional check on Country. “We would like to throw an error ‘9999’ in case the Country is not Netherlands.
Add the following code:
Save and compile.
Step 7: Test Mapping
Now we are able to test our changes. Our first test is created with multiple business partners. One of them, SEEBURGER, is located in Germany. We can expect an error based on this country.
Let’s test it in the Test Environment.
Now errors are shown in the Warning section:
We can open the error mapping file to check the output file:
We can check our logging, the line “An error occured: Incorrect Country (ErrorCode 9999)” should be shown in the error log:
Thanks for following the steps in this blog. It is a simple scenario which can get quit complex when playing around with all the different functionalities. In this first scenario you have learned how to create a message definition, how to create a mapping with basic mapping features (such as variables, traces, concatenations), add error handling and configure the test environment.
Next time we will create a simple file to file scenario and deploy this mapping into the process.
Written by Geert van den Reek