Skip to Content
Last modified by Martijn Woudstra on 2022/08/25 15:57
Show last authors
1 {{container}}
2 {{container layoutStyle="columns"}}
3 (((
4 In this microlearning, we will explain how to transform flat files delivered to XML that can be used fo further validation.
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 flat file (text, csv or EDIFACT) to an xml message and vice versa. 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-FlatFileTransformation-bestpractice.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 **Adding the correct component**
32 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.
33
34 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-FlatFileTransformation-xml2flat-Step2.png]]
35
36 **Select the type of flat file you want to generate**
37 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.
38
39 **Input**
40 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-FlatFileTransformation-xml2flat-Step3-2.png]]
41 **Output**
42 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-FlatFileTransformation-xml2flat-Step3-1.png]]
43
44 **Definining the xpath to create the lines**
45 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.
46
47 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-FlatFileTransformation-xml2flat-Step4.png]]
48
49 **Filling in the correct xpath expression per column**
50 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
51
52 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-FlatFileTransformation-xml2flat-Step5.png]]
53
54 {{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}}
55
56 **Setting the delimiter (optional)**
57
58 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.
59
60 **Setting the Line separator (optional)**
61 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.
62
63 **Setting the charset (optional)**
64 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:
65 • windows-1252
66 • US-ASCII
67 • x-UTF-8-BOM
68
69 === 3.2 Complex scenario step by step ===
70
71 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.
72
73 **Setting up the xml**
74 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).
75 If you need held setting up such an xml please feel free to contact the CAPE Academy or the eMagiz Competence Center.
76
77 **Adding the correct component**
78 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.
79
80 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-FlatFileTransformation-Step2.png]]
81
82 **Select the type of flat file you want to generate**
83 In these cases you will want to opt for the fixed length format option and in this example we need two columns.
84
85 **Input**
86
87 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-FlatFileTransformation-Step3-1.png]]
88
89 **Output**
90
91 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-FlatFileTransformation-Step3-2.png]
92
93 **Definining the XPath to create the lines**
94 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
95
96 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-FlatFileTransformation-Step4.png]]
97
98 **Filling in the correct xpath expression per column**
99 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
100
101 [[image:Main.Images.Microlearning.WebHome@intermediate-create-your-transformations-FlatFileTransformation-Step5.png]]
102
103 {{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}}
104
105 **Setting the Line separator (optional)**
106 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.
107
108 **Setting the charset (optional)**
109 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:
110 • windows-1252
111 • US-ASCII
112 • x-UTF-8-BOM
113
114 == 4. Assignment ==
115
116 Build an entry that retrieves files from an external source and ensures that the data is delivered on the onramp queue.
117 This assignment can be completed with the help of your (Academy) project you have created/used in the previous assignment.
118
119 == 5. Key takeaways ==
120
121 Key considerations when picking up files are:
122
123 * What are the determining criteria to define when a file is "ready" to be picked up (age, pattern, size, etc.)
124 * With what frequency is eMagiz going to check for new files
125 * Has eMagiz the appropriate rights to read from the directory where the messages are to be retrieved from
126 * What is the format (i.e. XML, JSON, EDI, TXT, CSV, etc.) of the files that eMagiz needs to retrieve
127
128 == 6. Suggested Additional Readings ==
129
130 If you are interested in this topic and want more information on it please read the help text provided by eMagiz.
131
132 == 7. Silent demonstration video ==
133
134 This video demonstrates how you could have handled the assignment and gives you some context on what you have just learned.
135
136 {{video attachment="intermediate-create-your-transformation-xml2flatfile.mp4" reference="Main.Videos.Microlearning.WebHome"/}})))
137
138 ((({{toc/}}))){{/container}}
139 {{/container}}