Wiki source code of Transformation - XPath Basic

Last modified by Erik Bakker on 2023/01/24 15:10
Hide last authors
Erik Bakker 17.1 1 {{container}}{{container layoutStyle="columns"}}(((
eMagiz 1.1 2
Erik Bakker 50.1 3 Sometimes the transformation tooling does not provide you with the exact correct transformation option to get the desired result in your output. For those cases, you can use a custom (handwritten) XPath expression to achieve the desired result.
eMagiz 1.1 4
Erik Bakker 50.1 5 In this microlearning, we will educate you on the basics of XPath and see how we can use it **within** the context of transforming messages. In other microlearnings, we will discuss the use of XPath **outside** the context of transforming messages.
eMagiz 1.1 6
Erik Bakker 17.1 7 Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].
eMagiz 1.1 8
9 == 1. Prerequisites ==
10
11 * Basic knowledge of the eMagiz platform
12
13 == 2. Key concepts ==
14
15 This microlearning focuses on XPath Basic in the context of transformations.
16
17 With XPath Basic, we mean: Understanding on a fundamental level what XPath is, how it is used and how you can use it within the transformation tooling of eMagiz
18
Erik Bakker 20.1 19 == 3. Transformation XPath Basic ==
eMagiz 1.1 20
Erik Bakker 50.1 21 Sometimes the transformation tooling does not provide you with the exact correct transformation option to get the desired result in your output. For those cases, you can use a custom (handwritten) XPath expression to achieve the desired result.
eMagiz 1.1 22
23 === 3.1 What is XPath ===
24
25 Before we delve into the use of XPath within the eMagiz tooling let us first discuss XPath itself. XPath stands for XML Path Language.
26 As the name suggests it can be used to write down a certain "path" to identify and navigate nodes in an XML message.
27 By following this "path" you can access all elements and attributes within your **input** XML message.
28
29 XPath is a widely used standard with a lot of built-in functions and is a W3C recommendation
30
31 === 3.2 Reading and Writing XPath ===
32
Erik Bakker 29.1 33 The simplest XPath is /. This simply means access the root of the **input** message. So to access the root of your **input** message you write down one forward-slash (i.e. /).
34 If you want to access an element below the root directly you can use two forward slashes (~//) to start your XPath expression.
eMagiz 1.1 35
36 For example, take a look at the following **input** message:
37
Carlijn Kokkeler 36.1 38 {{code language="xml"}}
39 <Projects>
40 <Project>
Carlijn Kokkeler 37.1 41 <ID>1</ID>
Carlijn Kokkeler 36.1 42 </Project>
43 </Projects>
44 {{/code}}
45
eMagiz 1.1 46 When I want to write a "path" to Projects I would only have to write down / and that is it. However, when I want to write a "path" to Project I have two options.
47 I can either start at the root (Absolute XPath) and navigate down from there which would give me /Projects/Project as a valid XPath expression.
48 On the other hand, I could also start directly at the Project element (Relative Xpath) which would give me //Project as a valid XPath expression.
49
50 To expand on that example we would now like to navigate to ID. The XPath can either start at the root level (Projects) or element level (Project or ID).
51 So this means that in this simple example we have three alternatives to end up with the same result:
52
53 * /Projects/Project/ID
54 * //Project/ID
Erik Bakker 22.1 55 * ~//ID
eMagiz 1.1 56
57 At this point you probably wonder why anyone would start their journey on the XPath "path" from the root level. Well imagine the following **input** message:
58
Carlijn Kokkeler 39.1 59 {{code language="xml"}}
60 <Projects>
61 <Project>
62 <ID>1</ID>
63 </Project>
64 <Status>
65 <ID>1</ID>
66 </Status>
67 </Projects>
68 {{/code}}
69
eMagiz 1.1 70 As you can see from this example taking the third option of our previous example would end up getting two results (both the ID under Project and the ID under Status).
71 There are also scenarios one could think of that would benefit from starting **not** on the root level of the **input** message. So always consider the context when writing down your XPath.
72
73 === 3.3 Absolute vs Relative XPath ===
74
75 As discussed in the previous segment there is a choice to be made between using an Absolute XPath (which starts at the root level) and the Relative XPath (which can start anywhere in the structure)
76
77 Below you find a summary of the main differences between both options.
78
79 **Absolute XPath**
80
81 * It is the direct way to find the element
82 * Disadvantage of the absolute XPath is that if there are any changes made in the path of the element then that XPath gets failed.
Erik Bakker 28.1 83 * Starts with the single forward-slash(i.e. /), which means you can select the element from the root node.
eMagiz 1.1 84
85 **Relative XPath**
86
87 * Finds the element(s) in the whole message, not considering the structure.
Erik Bakker 29.1 88 * Starts with the double forward-slash (i.e. ~//), which means it can search the element anywhere at the message.
eMagiz 1.1 89
90 === 3.4 Namespaces ===
91
Erik Bakker 35.1 92 To complicate things a little bit more we are now going to discuss namespaces. A namespace is a set of symbols that are used to organize objects of various kinds, so that these objects may be referred to by name.
eMagiz 1.1 93
94 An example of comparative nature would be:
95 There are in the Netherlands two cities named Hengelo. Via namespaces can we split and recognize them. The namespace that can be used to split them is using the namespace Province (Gelderland and Overijssel).
96 Gelderland:Hengelo & Overijssel:Hengelo
97
98 To handle namespaces while reading and writing XPath you have two options:
99
100 * Prefix
101 * Wildcard
102
103 ==== 3.4.1 Prefix ====
104
105 By defining the prefix of the namespace (i.e. sys, cdm, ns) you can refer to this prefix while reading and writing your XPath.
106 Let's return to our original example, only this time the **input** message has a namespace:
107
Carlijn Kokkeler 41.1 108 {{code language="xml"}}
109 <sys:Projects xmlns:sys="http://www.academy.emagiz.com/ns/mlacade/system/1.0/">
110 <sys:Project>
111 <sys:ID>1</sys:ID>
112 </sys:Project>
113 <sys:Status>
114 <sys:ID>1</sys:ID>
115 </sys:Status>
116 </sys:Projects>
117 {{/code}}
eMagiz 1.1 118
119 As you can see the notation has slightly changed. A prefix has occurred before each element and attributes called sys. To separate the prefix from the name of the element or attribute a colon (:) is used.
120 The XPath also needs to change to get the desired result. We need to take the prefix into account. This will result in the following valid XPath options:
121
122 * /sys:Projects
123 * /sys:Projects/sys:Project
124
125 ==== 3.4.2 Wildcard ====
126
127 By using the wildcard notation, an asterisk (\*), you specify that regardless of the chosen prefix by the party for delivering the **input** message you will accept it.
128 Using the prefix makes it clearer to others in which namespaces the XPath is written.
129 Using the wildcard is easier as you don't have to check for every XPath you write what the prefix is and whether there is a namespace.
130 Therefore we see a lot of use of the wildcard when writing a custom XPath in eMagiz.
131
132 Using the wildcard will result in the following valid XPath options:
133
Carlijn Kokkeler 42.1 134 * /*:Projects
135 * /*:Projects/*:Project
136
eMagiz 1.1 137 === 3.5 Custom XPath in Transformation ===
138
139 Now that we have a basic conceptual understanding of XPath let us turn our attention towards relating this information to eMagiz.
140 Specifically how you can use it while transforming your messages with the help of the transformation functionality in Create.
141
142 As you saw in the previous microlearning a lot of options are already available out of the box and don't require you to write your custom XPath.
143 However, sometimes it is necessary to write a custom XPath.
144
Carlijn Kokkeler 46.1 145 Let us look at an example in eMagiz:
eMagiz 1.1 146
Erik Bakker 17.1 147 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-create-transformation-xpath-basic--emagiz-transformation-xpath.png]]
eMagiz 1.1 148
149 In this example, you see two notes on two attributes. One on the DateTime on Order Level and one on the Description on OrderLine level. The requirements are:
150
151 * The DateTime should be filled with the DateTime value related to the **first** OrderLine
Erik Bakker 32.1 152 * The Description should be the value for ID and the value for DateTime merged with the help of a dash (i.e. -) icon.
eMagiz 1.1 153
154 To make this happen we need a custom XPath. Remember the discussion on Absolute vs Relative earlier in this microlearning?
155 The way the transformation logic is build up helps you ensure that the correct values end up in the correct places.
156 What I mean by that is that the line drawn towards a certain entity in the **output** determines the starting point from where to reason when writing an XPath.
157 For example, when looking at the Order entity you see that the origin is the Order entity of the **input** message.
158 So the basic XPath eMagiz would have generated to fill in the value for DateTime on Order level would be:
159
160 * OrderLine/DateTime
161
162 This is because the starting point of our "path" is the Order entity already.
163 To ensure that we only place the DateTime value of the first OrderLine in the DateTime field on Order level in the **output** message we need to change the XPath.
164 To do so enter Start Editing Mode and navigate to the Transformation. In here select the option Transformation and then Custom XPath
165
Erik Bakker 17.1 166 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-create-transformation-xpath-basic--emagiz-transformation-xpath-pop-up.png]]
eMagiz 1.1 167
168 In here we need to ensure that we only take the DateTime value from the **first** OrderLine. To do so we need to specify which of the OrderLines we want as input.
169 You can specify that by using the following notation:
170
171 * [1] = the first iteration of OrderLine
172 * [2] = the second iteration of OrderLine
173 * etc.
174
175 This would change our XPath to OrderLine[1]/DateTime. So let us fill that in and press Save.
176
Erik Bakker 17.1 177 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-create-transformation-xpath-basic--emagiz-transformation-xpath-pop-up-filled-in.png]]
eMagiz 1.1 178
179 Now let us turn our focus toward the second part of this example. Remember what we said earlier.
180 The starting point of your "path" within a transformation is determined by the starting point of the line that is drawn to the entity you are currently working with.
181 In this case that is the OrderLine.
182
183 So the basic XPath eMagiz would have generated to fill in the value for DateTime on Order level would be:
184
185 * DateTime|ID
186
187 This is not quite what we want as it does not account for the dash icon that needs to separate the two values.
188 So, once again select the transformation option and opt for Custom XPath.
189
190 As specified before there are a lot of built-in functions available when using XPath. One of these functions is the string-join.
191 With a string-join, you can join two input attributes together in a certain order and separate them with the help of a divider.
192
193 This would change our XPath to string-join((DateTime, ID),'-'). So let us fill that in and press Save.
194
Erik Bakker 17.1 195 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-create-transformation-xpath-basic--emagiz-transformation-xpath-pop-up-filled-in-string-join.png]]
eMagiz 1.1 196
197 When I tested this I got the following result. In a later microlearning, we will teach you all about testing these things yourself.
198
Erik Bakker 17.1 199 [[image:Main.Images.Microlearning.WebHome@crashcourse-platform-create-transformation-xpath-basic--emagiz-transformation-custom-xpath-result.png]]
eMagiz 1.1 200
Erik Bakker 53.1 201 == 4. Key takeaways ==
eMagiz 1.1 202
203 * XPath gives you the option to navigate through an XML document in a "path" like manner
204 * There are various ways of setting up your XPath (Absolute vs Relative)
205 * Consider the namespace
206 * Within the transformation, the starting point of each XPath depends on where the line on entity level was drawn from
207
Erik Bakker 53.1 208 == 5. Suggested Additional Readings ==
eMagiz 1.1 209
210 If you are interested in this topic and want more information on it please read the help text provided by eMagiz and/or read more information on the following link:
211
Erik Bakker 48.1 212 * [[XPath - Introduction>>https://www.w3schools.com/xml/xpath_intro.asp||target="blank"]]
213 * [[XPath - Explanation>>https://www.tutorialspoint.com/xpath/index.htm||target="blank"]]
Erik Bakker 47.1 214 * [[XPath - Tutorial>>https://www.softwaretestinghelp.com/xml-path-language-xpath-tutorial/||target="blank"]]
Erik Bakker 51.1 215 * [[XPath - Intermediate>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.Create your transformations.intermediate-create-your-transformations-xpath-intermediate||target="blank"]]
216 * [[XPath - Advanced>>doc:Main.eMagiz Academy.Microlearnings.Advanced Level.Create your transformations.advanced-create-your-transformations-xpath-advanced||target="blank"]]
Erik Bakker 17.1 217 )))((({{toc/}}))){{/container}}{{/container}}