Splitting messages

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

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

3

4

In this microlearning, we will educate you on how you can split messages with the help of eMagiz tooling.

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 focuses on splitting messages.

15

16

With splitting messages we mean: Cutting up the input messages in multiple output messages with the same format

17

18

== 3. Splitting messages ==

19

20

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

21

22

There are two split options available on flow level in eMagiz:

* Standard splitter

* Xpath splitter

[[image:Main.Images.Microlearning.WebHome@crashcourse-platform-create-splitting-messages--splitter-options-flow.png]]

28

29

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.

30

With the help of the Xpath splitter, you can split the message based on the result of an Xpath expression.

31

32

According to the help text of eMagiz: "The splitter uses the provided XPath expression to split the payload into many nodes.

33

By default, this will result in each Node becoming the payload of a new message."

34

35

As you remember from our microlearnings on Xpath an XPath navigates through the input XML based on the expression given.

36

What the starting point of this navigation is differs based on the context.

37

If you want to write an XPath while doing a transformation any input element can be the starting point of your XPath.

38

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.

39

That is a crucial point in quickly getting the right XPath for the job

=== 3.1 Basic ===

In this use case, we want to split our list of Projects into single Project messages that will validate against our system message.

44

45

[[image:Main.Images.Microlearning.WebHome@crashcourse-platform-create-splitting-messages--splitter-system-message.png]]

46

47

To do so we need to place an XPath splitter before validating the system message.

48

As a reminder, the best practice is that after every mutation on the message level you validate to check your work.

49

50

On flow level the solution therefore would look as follows:

51

52

[[image:Main.Images.Microlearning.WebHome@crashcourse-platform-create-splitting-messages--splitter-flow-level-solution.png]]

53

54

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.

55

To be able to determine the correct XPath we need to know:

56

57

* The structure of the input message

58

* Whether the input messages has a namespace

59

* Always start at the root of the input message when writing an XPath outside of the transformation

60

61

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.

62

In this case the structure is provided by us:

63

64

[[image:Main.Images.Microlearning.WebHome@crashcourse-platform-create-splitting-messages--splitter-input-message-structure.png]]

65

66

Furthermore, we give you an example of how such an input message could look like:

<Description>Example Microlearning</Description>

</Project>

</Project>

<Description>Microlearning Example</Description>

</Project>

</Projects>

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.

89

In this example, no namespace is used. We conclude this based on two things:

90

91

* The absence of a namespace declaration within the example message

92

* No namespace prefixes throughout the example message

93

94

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

95

Double click on the splitter component to access the following pop-up

96

97

[[image:Main.Images.Microlearning.WebHome@crashcourse-platform-create-splitting-messages--xpath-splitter-pop-up.png]]

98

99

As you can see the component needs to know the correct XPath expression and needs to know whether a namespace is used.

100

As we don't have a namespace in this example it becomes less complicated to figure out the correct XPath.

101

102

Remember we start at the root and work our way down from there. So in this case we start at Projects.

103

To get the correct Xpath notation (remember!) we need to start with a forward slash indicating the root level.

104

105

The beginning of the XPath should look like this: /Projects. But that is not all.

106

If we would stop here the splitter would split on the Projects level, meaning we have not ended up with a valid system message.

107

So we need to continue with our navigation into the next element in our input structure. This is the Project element.

108

This means that the Xpath will be: /Projects/Project. This is also the desired result of our XPath expression

109

as this will split on Project level giving us three separate and valid system messages.

110

111

[[image:Main.Images.Microlearning.WebHome@crashcourse-platform-create-splitting-messages--xpath-splitter-pop-up-filled-in.png]]

112

113

=== 3.2 Variations ===

114

115

The above XPath expression is not the only expression that will yield a correct result.

116

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

117

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.

118

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.

119

120

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.

121

This wildcard option states that all namespaces and namespace prefixes are valid when trying to resolve the XPath expression.

122

123

Incorporating such a wildcard within our initial XPath would look as follows:

124

125

[[image:Main.Images.Microlearning.WebHome@crashcourse-platform-create-splitting-messages--xpath-splitter-pop-up-filled-in-wildcard.png]]

126

127

== 4. Key takeaways ==

128

129

* eMagiz offers two types of splitters of which the XPath splitter is used in most cases

130

* To determine the XPath expression in your splitter correctly remember the following things:

131

** The structure of the input message

132

** Whether the input messages has a namespace

133

** Always start at the root of the input message when writing an XPath outside of the transformation

134

135

== 5. Suggested Additional Readings ==

136

137

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:

138

139

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

140

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

Wiki source code of Splitting messages

Navigation