Transformation - XPath Basic

{{container}}{{container layoutStyle="columns"}}(((

In this microlearning, we'll introduce you to XPath and how it can be used for custom transformations in eMagiz. When the built-in transformation options fall short, XPath expressions can help you achieve precise results by navigating and manipulating XML data. We’ll cover the basics of XPath, including how to use it within eMagiz to handle complex transformations. Let’s get started with the essentials!

4

5

Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].

6

7

== 1. Prerequisites ==

8

9

* Basic knowledge of the eMagiz platform

10

11

== 2. Key concepts ==

12

13

This microlearning focuses on XPath Basic in the context of transformations.

14

15

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

16

17

== 3. Transformation XPath Basic ==

18

19

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.

20

21

=== 3.1 What is XPath ===

22

23

Before we delve into the use of XPath within the eMagiz tooling let us first discuss XPath itself. XPath stands for XML Path Language.

24

As the name suggests it can be used to write down a certain "path" to identify and navigate nodes in an XML message.

25

By following this "path" you can access all elements and attributes within your **input** XML message.

26

27

XPath is a widely used standard with a lot of built-in functions and is a W3C recommendation

28

29

=== 3.2 Reading and Writing XPath ===

30

31

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. /).

32

If you want to access an element below the root directly you can use two forward slashes (~//) to start your XPath expression.

33

34

For example, take a look at the following **input** message:

</Project>

</Projects>

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.

45

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.

46

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.

47

48

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).

49

So this means that in this simple example we have three alternatives to end up with the same result:

50

51

* /Projects/Project/ID

* //Project/ID

* ~//ID

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:

</Project>

</Status>

</Projects>

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).

69

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.

70

71

=== 3.3 Absolute vs Relative XPath ===

72

73

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)

74

75

Below you find a summary of the main differences between both options.

**Absolute XPath**

* It is the direct way to find the element

80

* Disadvantage of the absolute XPath is that if there are any changes made in the path of the element then that XPath gets failed.

81

* Starts with the single forward-slash(i.e. /), which means you can select the element from the root node.

**Relative XPath**

* Finds the element(s) in the whole message, not considering the structure.

86

* Starts with the double forward-slash (i.e. ~//), which means it can search the element anywhere at the message.

87

88

=== 3.4 Namespaces ===

89

90

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.

91

92

An example of comparative nature would be:

93

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).

94

Gelderland:Hengelo & Overijssel:Hengelo

95

96

To handle namespaces while reading and writing XPath you have two options:

* Prefix

* Wildcard

==== 3.4.1 Prefix ====

102

103

By defining the prefix of the namespace (i.e. sys, cdm, ns) you can refer to this prefix while reading and writing your XPath.

104

Let's return to our original example, only this time the **input** message has a namespace:

105

106

107

<sys:Projects xmlns:sys="http://www.academy.emagiz.com/ns/mlacade/system/1.0/">

<sys:Project>

<sys:ID>1</sys:ID>

</sys:Project>

<sys:Status>

<sys:ID>1</sys:ID>

</sys:Status>

</sys:Projects>

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.

118

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:

119

120

* /sys:Projects

121

* /sys:Projects/sys:Project

122

123

==== 3.4.2 Wildcard ====

124

125

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.

126

Using the prefix makes it clearer to others in which namespaces the XPath is written.

127

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.

128

Therefore we see a lot of use of the wildcard when writing a custom XPath in eMagiz.

129

130

Using the wildcard will result in the following valid XPath options:

131

132

* /*:Projects

133

* /*:Projects/*:Project

134

135

=== 3.5 Custom XPath in Transformation ===

136

137

Now that we have a basic conceptual understanding of XPath let us turn our attention towards relating this information to eMagiz.

138

Specifically how you can use it while transforming your messages with the help of the transformation functionality in Create.

139

140

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.

141

However, sometimes it is necessary to write a custom XPath.

142

143

Let us look at an example in eMagiz:

144

145

[[image:Main.Images.Microlearning.WebHome@crashcourse-platform-create-transformation-xpath-basic--emagiz-transformation-xpath.png]]

146

147

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:

148

149

* The DateTime should be filled with the DateTime value related to the **first** OrderLine

150

* The Description should be the value for ID and the value for DateTime merged with the help of a dash (i.e. -) icon.

151

152

To make this happen we need a custom XPath. Remember the discussion on Absolute vs Relative earlier in this microlearning?

153

The way the transformation logic is build up helps you ensure that the correct values end up in the correct places.

154

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.

155

For example, when looking at the Order entity you see that the origin is the Order entity of the **input** message.

156

So the basic XPath eMagiz would have generated to fill in the value for DateTime on Order level would be:

* OrderLine/DateTime

This is because the starting point of our "path" is the Order entity already.

161

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.

162

To do so enter Start Editing Mode and navigate to the Transformation. In here select the option Transformation and then Custom XPath

163

164

[[image:Main.Images.Microlearning.WebHome@crashcourse-platform-create-transformation-xpath-basic--emagiz-transformation-xpath-pop-up.png]]

165

166

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.

167

You can specify that by using the following notation:

168

169

* [1] = the first iteration of OrderLine

170

* [2] = the second iteration of OrderLine

171

* etc.

172

173

This would change our XPath to OrderLine[1]/DateTime. So let us fill that in and press Save.

174

175

[[image:Main.Images.Microlearning.WebHome@crashcourse-platform-create-transformation-xpath-basic--emagiz-transformation-xpath-pop-up-filled-in.png]]

176

177

Now let us turn our focus toward the second part of this example. Remember what we said earlier.

178

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.

179

In this case that is the OrderLine.

180

181

So the basic XPath eMagiz would have generated to fill in the value for DateTime on Order level would be:

* DateTime|ID

This is not quite what we want as it does not account for the dash icon that needs to separate the two values.

186

So, once again select the transformation option and opt for Custom XPath.

187

188

As specified before there are a lot of built-in functions available when using XPath. One of these functions is the string-join.

189

With a string-join, you can join two input attributes together in a certain order and separate them with the help of a divider.

190

191

This would change our XPath to string-join((DateTime, ID),'-'). So let us fill that in and press Save.

192

193

[[image:Main.Images.Microlearning.WebHome@crashcourse-platform-create-transformation-xpath-basic--emagiz-transformation-xpath-pop-up-filled-in-string-join.png]]

194

195

When I tested this I got the following result. In a later microlearning, we will teach you all about testing these things yourself.

196

197

[[image:Main.Images.Microlearning.WebHome@crashcourse-platform-create-transformation-xpath-basic--emagiz-transformation-custom-xpath-result.png]]

198

199

== 4. Key takeaways ==

200

201

* XPath gives you the option to navigate through an XML document in a "path" like manner

202

* There are various ways of setting up your XPath (Absolute vs Relative)

203

* Consider the namespace

204

* Within the transformation, the starting point of each XPath depends on where the line on entity level was drawn from

205

206

== 5. Suggested Additional Readings ==

207

208

* [[Crash Courses (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.WebHome||target="blank"]]

209

** [[Crash Course Platform (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course Platform.WebHome||target="blank"]]

210

*** [[Transformation - XML to XML (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course Platform.crashcourse-platform-create-transformation-xml-to-xml||target="blank"]]

211

*** [[Splitting messages (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course Platform.crashcourse-platform-create-splitting-messages||target="blank"]]

212

* [[Intermediate (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.WebHome||target="blank"]]

213

** [[Create your transformations (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.Create your transformations.WebHome||target="blank"]]

214

*** [[Transformation - XPath Intermediate (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.Create your transformations.intermediate-create-your-transformations-xpath-intermediate||target="blank"]]

215

* [[Advanced (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Advanced Level.WebHome||target="blank"]]

216

** [[Create your transformations (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Advanced Level.Create your transformations.WebHome||target="blank"]]

217

*** [[XPath Advanced (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Advanced Level.Create your transformations.advanced-create-your-transformations-xpath-advanced||target="blank"]]

218

* [[Expert (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Expert Level.WebHome||target="blank"]]

219

** [[Create your transformations (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Expert Level.Create your transformations.WebHome||target="blank"]]

220

*** [[Xpath Expert (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Expert Level.Create your transformations.expert-create-your-transformations-xpath-expert||target="blank"]]

221

* [[XPath - Introduction (External)>>https://www.w3schools.com/xml/xpath_intro.asp||target="blank"]]

222

* [[XPath - Explanation (External)>>https://www.tutorialspoint.com/xpath/index.htm||target="blank"]]

223

* [[XPath - Tutorial (External)>>https://www.softwaretestinghelp.com/xml-path-language-xpath-tutorial/||target="blank"]]

224

* [[XPath (Search Result)>>url:https://docs.emagiz.com/bin/view/Main/Search?sort=score&sortOrder=desc&highlight=true&facet=true&r=1&f_space_facet=1%2FMain.eMagiz+Academy.&f_type=DOCUMENT&f_locale=en&f_locale=&f_locale=en&text=%22xpath%22||target="blank"]]

225

)))((({{toc/}}))){{/container}}{{/container}}

Wiki source code of Transformation - XPath Basic

Navigation