Last modified by Eva Torken on 2023/08/10 12:40
Show last authors
1 {{container}}
2 {{container layoutStyle="columns"}}
3 (((
4 In this microlearning, we will explain how to transform XML into a flat file solution that can be send to an external party.
5
6 Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].
7
8 == 1. Prerequisites ==
9
10 * Basic knowledge of the eMagiz platform
11
12 == 2. Key concepts ==
13
14 This microlearning discusses the approach to transform an XML to a Flat File. Once transformed, that flat file can be used by a target system for further consumption.
15
16 As the name suggest this standard component gives you, the user, the possibility to transform an XML message to a flat-file (text, csv or EDIFACT). In the following chapters we will work out two examples. The first example will always be the simpler case, which you will encounter more often. The second example will be the advanced case.
17
18 {{warning}}In the case of transforming an EDIFACT message, this can generally be done easier via the particular components eMagiz provides you. Keep this in mind when designing your message solution.{{/warning}}
19
20 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-xml-2-flatfile--best-practice.png]]
21
22 == 3. XML to Flat file transformation ==
23
24 === 3.1 Simple scenario step by step ===
25
26 Follow these steps carefully in order to acquire the desired result. If a step is unclear or you are not able to follow it, please contact eMagiz Academy.
27
28 **Setting up the xml**
29 It is beneficial, when working with this component to prepare your XML message to make this transformation much easier. This can be done to create a structure in which you have a root under which you have one list of records containing all relevant information (i.e Records/Record structure)
30
31 **Validate before transforming to flat-file**
32 A best practice is to validate the system message before transforming to your flat-file solution.
33
34 **Adding the correct component**
35 The first step is adding the correct component to your flow. In this case you will need a blue rectangular shape component of the transformer family. The component is called: xml to flat file transformer. It is wise to name it according to its function. This way it is clear for all to see what the function of the component is within the context of the flow. See below for an example of such naming convention.
36
37 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-FlatFileTransformation-xml2flat-Step2.png]]
38
39 **Select the type of flat file you want to generate**
40 In most cases you will want to generate a csv file. So you can select that option and already state how many columns you want in your output. This number should correspond to the number of attributes in your input xml. After you have executing both actions you only need to press generate columns.
41
42 **Input**
43 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-FlatFileTransformation-xml2flat-Step3-2.png]]
44 **Output**
45 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-FlatFileTransformation-xml2flat-Step3-1.png]]
46
47 **Definining the xpath to create the lines**
48 The first thing we need to set up within the component is the xpath expression we are using to split the incoming xml messages to separate lines we are transforming to lines within the flat file. Standard we often see an xpath like: /Records/Record. In the example below we choose /_:Employees/_:Employee. Alternatively you can determine the namespace prefix and the namespace itself, just as you can in the support object called Xpath expression.
49
50 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-FlatFileTransformation-xml2flat-Step4.png]]
51
52 **Filling in the correct xpath expression per column**
53 For each column you have just generated you now have to define the xpath expression. Because you were smart in step 1 of this how-to this step just has become a lot easier. Due to the nature of the xml message that will form the input the xpaths you need to set will mimic the name of the attribute they correspond with. See below for an example
54
55 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-FlatFileTransformation-xml2flat-Step5.png]]
56
57 {{warning}}When the input xml has a namespace you need to take this into account when writing your xpath expression to make this work. Just as you would need to take that into account when using the standard transformation tooling.{{/warning}}
58
59 **Setting the delimiter (optional)**
60
61 If the delimiter in your output file deviates from the standard (comma) you can specify this under the Advanced tab. The option is called Delimiter. In this field you could place a semicolon, inverted question marks or exclamation marks.
62
63 **Setting the Line separator (optional)**
64 On the Advanced tab you also have the determine the line separator. Most often this will come into use when working with different operating systems. The default “Linux” enter (\u000A) differs from the default “Windows” enter (\u000D\u000A). So when the customer asks you to use an CarriageReturn and LineFeed as Line separator go for the Windows option.
65
66 **Setting the charset (optional)**
67 In some cases you need to deviate from the standard UTF-8 charset when formatting the lines. If this is the case you can determine the charset in this component in order for the connected system to handle the input correctly. Examples of different charsets are:
68 • windows-1252
69 • US-ASCII
70 • x-UTF-8-BOM
71
72 === 3.2 Complex scenario step by step ===
73
74 Follow these steps carefully in order to acquire the desired result. If a step is unclear or you are not able to follow it, please contact CAPE Academy.
75
76 **Setting up the xml**
77 It is beneficial, when working with this component to prepare your xml message to make this transformation much easier. In this complex case this will be done by using a custom xslt to already format the xml in such a way that it will become easier to split and use this component. In the custom xslt you can create a record in which you define two parts of the line that have a certain structure (i.e recordtype and recordvalue).
78 If you need held setting up such an xml please feel free to contact the CAPE Academy or the eMagiz Competence Center.
79
80 **Adding the correct component**
81 The first step is adding the correct component to your flow. In this case you will need a blue rectangular shape component of the transformer family. The component is called: xml to flat file transformer. It is wise to name it according to its function. This way it is clear for all to see what the function of the component is within the context of the flow. See below for an example of such naming convention.
82
83 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-FlatFileTransformation-Step2.png]]
84
85 **Select the type of flat file you want to generate**
86 In these cases you will want to opt for the fixed length format option and in this example we need two columns.
87
88 **Input**
89
90 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-FlatFileTransformation-Step3-1.png]]
91
92 **Output**
93
94 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-FlatFileTransformation-Step3-2.png]
95
96 **Definining the XPath to create the lines**
97 The first thing we need to set up within the component is the xpath expression we are using to split the incoming xml messages to separate lines we are transforming to lines within the flat file. The expression is completly depended on how you have built your xml in step 1
98
99 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-FlatFileTransformation-Step4.png]]
100
101 **Filling in the correct xpath expression per column**
102 For each column you have just generated you now have to define the xpath expression. Because you were smart in step 1 of this how-to this step just has become a lot easier. Due to the nature of the xml message that will form the input the xpaths you need to set will mimic the name of the attribute or entity they correspond with. See below for an example
103
104 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-FlatFileTransformation-Step5.png]]
105
106 {{warning}}when the input xml has a namespace you need to take this into account when writing your xpath expression to make this work. Just as you would need to take that into account when using the standard transformation tooling.{{/warning}}
107
108 **Setting the Line separator (optional)**
109 On the Advanced tab you also have the determine the line separator. Most often this will come into use when working with different operating systems. The default “Linux” enter (\u000A) differs from the default “Windows” enter (\u000D\u000A). So when the customer asks you to use an CarriageReturn and LineFeed as Line separator go for the Windows option.
110
111 **Setting the charset (optional)**
112 In some cases you need to deviate from the standard UTF-8 charset when formatting the lines. If this is the case you can determine the charset in this component in order for the connected system to handle the input correctly. Examples of different charsets are:
113 • windows-1252
114 • US-ASCII
115 • x-UTF-8-BOM
116
117 == 4. Key takeaways ==
118
119 Key considerations when transforming XML to a flat-file are:
120
121 * Create a simplified structure in your system message before transforming to flat-file (i.e. Records/Record)
122 * Do not define a namespace for your system message to make life easier
123 * Consider which character encoding is required by the external system and take additional measures if this deviates from the standard (i.e. UTF-8)
124
125 == 5. Suggested Additional Readings ==
126
127 If you are interested in this topic and want more information on it please read the help text provided by eMagiz.
128 )))
129
130 ((({{toc/}}))){{/container}}
131 {{/container}}