Skip to Content
Version 1.1 by marijn on 2022/05/10 11:22
Show last authors
1 {{html wiki="true"}}
2 <div class="ez-academy">
3 <div class="ez-academy_body">
4
5 <div class="doc">
6
7
8
9 = Splitting messages =
10
11 Sometimes you receive or need to retrieve a batch file of data containing a large number of iterations on the same object (i.e Project, Employee, Order, Invoice, etc.)
12 that you want or need to process individually from one another. To do so you can use the splitter functionality of eMagiz to split the incoming messages into multiple messages.
13
14 In this microlearning, we will educate you on how you can split messages with the help of eMagiz tooling.
15
16 Should you have any questions, please contact academy@emagiz.com.
17
18 * Last update: February 8th, 2021
19 * Required reading time: 7 minutes
20
21 == 1. Prerequisites ==
22
23 * Basic knowledge of the eMagiz platform
24
25 == 2. Key concepts ==
26
27 This microlearning focuses on splitting messages.
28
29 With splitting messages we mean: Cutting up the input messages in multiple output messages with the same format
30
31
32
33 == 3. Splitting messages ==
34
35 Sometimes you receive or need to retrieve a batch file of data containing a large number of iterations on the same object (i.e Project, Employee, Order, Invoice, etc.)
36 that you want or need to process individually from one another. To do so you can use the splitter functionality of eMagiz to split the incoming messages into multiple messages.
37
38 There are two split options available on flow level in eMagiz:
39
40 * Standard splitter
41 * Xpath splitter
42
43 <p align="center">[[image:crashcourse-platform-create-splitting-messages--splitter-options-flow.png||]]</p>
44
45 In this microlearning, we will turn our attention to the Xpath splitter as that option is used in 99% of the cases we encounter when someone wants to split a message.
46 With the help of the Xpath splitter, you can split the message based on the result of an Xpath expression.
47
48 According to the help text of eMagiz: "The splitter uses the provided XPath expression to split the payload into many nodes.
49 By default, this will result in each Node becoming the payload of a new message."
50
51 As you remember from our microlearnings on Xpath an XPath navigates through the input XML based on the expression given.
52 What the starting point of this navigation is differs based on the context.
53 If you want to write an XPath while doing a transformation any input element can be the starting point of your XPath.
54 However, when you write an XPath outside of the transformation tooling the root node of your input message will always be the starting point for your XPath.
55 That is a crucial point in quickly getting the right XPath for the job
56
57 === 3.1 Basic ===
58
59 In this use case, we want to split our list of Projects into single Project messages that will validate against our system message.
60
61 <p align="center">[[image:crashcourse-platform-create-splitting-messages--splitter-system-message.png||]]</p>
62
63 To do so we need to place an XPath splitter before validating the system message.
64 As a reminder, the best practice is that after every mutation on the message level you validate to check your work.
65
66 On flow level the solution therefore would look as follows:
67
68 <p align="center">[[image:crashcourse-platform-create-splitting-messages--splitter-flow-level-solution.png||]]</p>
69
70 Now it becomes time for the crucial part of this component. Determining the correct XPath to split my message to end up with a valid system message.
71 To be able to determine the correct XPath we need to know:
72
73 * The structure of the input message
74 * Whether the input messages has a namespace
75 * Always start at the root of the input message when writing an XPath outside of the transformation
76
77 Let us first determine what the structure of the input message is. In most cases, you can derive this from the documentation supplied by the external party.
78 In this case the structure is provided by us:
79
80 <p align="center">[[image:crashcourse-platform-create-splitting-messages--splitter-input-message-structure.png||]]</p>
81
82 Furthermore, we give you an example of how such an input message could look like:
83
84 <Projects>
85 <Project>
86 <ID>ID-1</ID>
87 <Description>Example Microlearning</Description>
88 <ExternalID>1</ExternalID>
89 </Project>
90 <Project>
91 <ID>ID-2</ID>
92 <ExternalID>3</ExternalID>
93 </Project>
94 <Project>
95 <ID>ID-3</ID>
96 <Description>Microlearning Example</Description>
97 <ExternalID>3</ExternalID>
98 </Project>
99 </Projects>
100
101 With the help of an example message or documentation dictating the structure of a message (i.e. an XSD), you can quickly see whether a message has a namespace.
102 In this example, no namespace is used. We conclude this based on two things:
103
104 * The absence of a namespace declaration within the example message
105 * No namespace prefixes throughout the example message
106
107 No, that we have all the information we need to determine the correct XPath let us take a look at the component to see what and how we need to fill in the XPath expression.
108 Double click on the splitter component to access the following pop-up
109
110 <p align="center">[[image:crashcourse-platform-create-splitting-messages--xpath-splitter-pop-up.png||]]</p>
111
112 As you can see the component needs to know the correct XPath expression and needs to know whether a namespace is used.
113 As we don't have a namespace in this example it becomes less complicated to figure out the correct XPath.
114
115 Remember we start at the root and work our way down from there. So in this case we start at Projects.
116 To get the correct Xpath notation (remember!) we need to start with a forward slash indicating the root level.
117
118 The beginning of the XPath should look like this: /Projects. But that is not all.
119 If we would stop here the splitter would split on the Projects level, meaning we have not ended up with a valid system message.
120 So we need to continue with our navigation into the next element in our input structure. This is the Project element.
121 This means that the Xpath will be: /Projects/Project. This is also the desired result of our XPath expression
122 as this will split on Project level giving us three separate and valid system messages.
123
124 <p align="center">[[image:crashcourse-platform-create-splitting-messages--xpath-splitter-pop-up-filled-in.png||]]</p>
125
126 === 3.2 Variations ===
127
128 The above XPath expression is not the only expression that will yield a correct result.
129 In case you don't want to start your XPath expression at the root level but somewhere in the middle of your input message you can use two forward backslashes (i.e. //)
130 to determine that you want to start at a certain element in the input message. In this example, we also could have written the Xpath as //Project which yields the same result.
131 Especially in cases where there is a nested structure of multiple lists, it could be advantageous to start at one of those lists instead of starting at the root level to reduce the complexity of your XPath.
132
133 In cases where you don't know whether or not a namespace will be used in the input message or you don't want to specify namespace and namespace prefix, you can utilize the wildcard option in eMagiz.
134 This wildcard option states that all namespaces and namespace prefixes are valid when trying to resolve the XPath expression.
135
136 Incorporating such a wildcard within our initial XPath would look as follows:
137
138 <p align="center">[[image:crashcourse-platform-create-splitting-messages--xpath-splitter-pop-up-filled-in-wildcard.png||]]</p>
139
140 ===== Practice =====
141
142 == 4. Assignment ==
143
144 Make sure that you add a splitter to your flow that splits messages before they are validated. To end up with valid output messages make sure to use the correct XPath.
145 This assignment can be completed within the (Academy) project that you have created/used in the previous assignment.
146
147 == 5. Key takeaways ==
148
149 * eMagiz offers two types of splitters of which the XPath splitter is used in most cases
150 * To determine the XPath expression in your splitter correctly remember the following things:
151 * The structure of the input message
152 * Whether the input messages has a namespace
153 * Always start at the root of the input message when writing an XPath outside of the transformation
154
155
156
157 == 6. Suggested Additional Readings ==
158
159 If you are interested in this topic and want more information on it please read the help text provided by eMagiz and read the info on the following links:
160
161 * https://www.w3schools.com/xml/xpath_intro.asp
162
163 == 7. Silent demonstration video ==
164
165 This video demonstrates a working solution and how you can validate whether you have successfully completed the assignment.
166
167 <iframe width="1280" height="720" src="../../vid/microlearning/crashcourse-platform-create-splitting-messages.mp4" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
168
169 </div>
170
171 </div>
172 </div>
173
174 {{/html}}