Transformation - XPath Basic

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

Sometimes the transformation tooling does not provide you with the exact correct transformation option to get the desired result in your output.

4

For those cases, you can use a custom (handwritten) XPath expression to achieve the desired result.

5

6

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.

7

In other microlearnings, we will discuss the use of XPath **outside** the context of transforming messages.

8

9

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

10

11

== 1. Prerequisites ==

12

13

* Basic knowledge of the eMagiz platform

14

15

== 2. Key concepts ==

16

17

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

18

19

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

20

21

== 3. Transformation XPath Basic ==

22

23

Sometimes the transformation tooling does not provide you with the exact correct transformation option to get the desired result in your output.

24

For those cases, you can use a custom (handwritten) XPath expression to achieve the desired result.

25

26

=== 3.1 What is XPath ===

27

28

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

29

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

30

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

31

32

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

33

34

=== 3.2 Reading and Writing XPath ===

35

36

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

37

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

38

39

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.

50

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.

51

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.

52

53

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

54

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

55

56

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

74

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.

75

76

=== 3.3 Absolute vs Relative XPath ===

77

78

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)

79

80

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

**Absolute XPath**

* It is the direct way to find the element

85

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

86

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

91

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

92

93

=== 3.4 Namespaces ===

94

95

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.

96

97

An example of comparative nature would be:

98

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

99

Gelderland:Hengelo & Overijssel:Hengelo

100

101

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

* Prefix

* Wildcard

==== 3.4.1 Prefix ====

107

108

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

109

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

110

111

112

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

123

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:

124

125

* /sys:Projects

126

* /sys:Projects/sys:Project

127

128

==== 3.4.2 Wildcard ====

129

130

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.

131

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

132

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.

133

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

134

135

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

136

137

* /*:Projects

138

* /*:Projects/*:Project

139

140

=== 3.5 Custom XPath in Transformation ===

141

142

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

143

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

144

145

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.

146

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

147

148

Let us look at an example in eMagiz:

149

150

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

151

152

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:

153

154

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

155

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

156

157

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

158

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

159

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.

160

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

161

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.

166

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.

167

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

168

169

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

170

171

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.

172

You can specify that by using the following notation:

173

174

* [1] = the first iteration of OrderLine

175

* [2] = the second iteration of OrderLine

176

* etc.

177

178

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

179

180

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

181

182

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

183

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.

184

In this case that is the OrderLine.

185

186

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.

191

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

192

193

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

194

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

195

196

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

197

198

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

199

200

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

201

202

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

== 4. Assignment ==

Open a flow that makes use of the transformation tooling and enters two custom XPath expression to achieve the following:

207

208

* A element on the root level should be filled with a value related to the **first** iteration of a list in your input message

209

* The desired output for a field called Description should be the input values of two other elements merged via a hashtag sign

210

This assignment can be completed within the (Academy) project that you have created/used in the previous assignment.

211

212

== 5. Key takeaways ==

213

214

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

215

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

216

* Consider the namespace

217

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

218

219

== 6. Suggested Additional Readings ==

220

221

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:

222

223

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

224

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

225

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

226

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

227

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

228

229

== 7. Silent demonstration video ==

230

231

This video demonstrates a working solution and how you can validate whether you have successfully completed the assignment.

232

233

{{video attachment="crashcourse-platform-create-transformation-xpath-basic.mp4" reference="Main.Videos.Microlearning.WebHome"/}}

234

235

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

Wiki source code of Transformation - XPath Basic

Navigation