Splitting messages

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

When dealing with batch files containing multiple data entries, you often need to process each entry individually. eMagiz provides a powerful tool for this purpose: the splitter functionality. In this microlearning, we'll explore how to use eMagiz's splitter to divide incoming messages into multiple, manageable pieces. You'll learn the basics of message splitting and get familiar with how to apply XPath expressions to achieve your goals.

3

4

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

5

6

== 1. Prerequisites ==

7

8

* Basic knowledge of the eMagiz platform

9

10

== 2. Key concepts ==

11

12

This microlearning focuses on splitting messages.

13

14

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

15

16

== 3. Splitting messages ==

17

18

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.

19

20

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

26

27

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.

28

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

29

30

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

31

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

32

33

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

34

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

35

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

36

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.

37

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.

42

43

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

44

45

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

46

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

47

48

On flow level the solution therefore would look as follows:

49

50

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

51

52

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.

53

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

54

55

* The structure of the input message

56

* Whether the input messages has a namespace

57

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

58

59

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.

60

In this case the structure is provided by us:

61

62

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

63

64

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.

87

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

88

89

* The absence of a namespace declaration within the example message

90

* No namespace prefixes throughout the example message

91

92

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.

93

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

94

95

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

96

97

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

98

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

99

100

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

101

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

102

103

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

104

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

105

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

106

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

107

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

108

109

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

110

111

=== 3.2 Variations ===

112

113

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

114

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

115

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.

116

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.

117

118

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.

119

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

120

121

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

122

123

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

124

125

== 4. Key takeaways ==

126

127

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

128

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

129

** The structure of the input message

130

** Whether the input messages has a namespace

131

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

132

133

== 5. Suggested Additional Readings ==

134

135

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

136

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

137

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

138

*** [[Flow Editor - Components (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course Platform.Create - Flow Editor - Components.WebHome||target="blank"]]

139

* [[Split (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=%22split%22||target="blank"]]

140

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

Wiki source code of Splitting messages

Navigation