Skip to Content
Last modified by Martijn Woudstra on 2022/10/05 13:14
Show last authors
1 {{container}}
2 {{container layoutStyle="columns"}}
3 (((
4
5 Most of the time, you can use the standard tooling of eMagiz to manipulate the data so that it makes sense for the (external) party that receives the data. However, sometimes there are cases in which you need a little bit of extra complexity. This microlearning will explain one of those more complex scenarios. In this microlearning, we will learn how to use two property lists to alter the input value to the desired output value. This functionality is beneficial when the list you are working with is not entirely static and is too long to be captured as an enum list.
6
7 Should you have any questions, please get in touch with [[academy@emagiz.com>>mailto:academy@emagiz.com]].
8
9 == 1. Prerequisites ==
10
11 * Basic knowledge of the eMagiz platform
12
13 == 2. Key concepts ==
14
15 This microlearning centers around comparing content to the property list.
16 By comparing, we mean Searching for the value in the list to get its position.
17
18 Essential characteristics of this functionality are:
19
20 * There is an input and an output list. Both are equal in length
21 * The logic searches for the position of the content in the input list
22 * The logic returns the corresponding value in the output list that holds the same position in the list
23
24 == 3. Compare content to the property list ==
25
26 Most of the time, you can use the standard tooling of eMagiz to manipulate the data so that it makes sense for the (external) party that receives the data. However, sometimes there are cases in which you need a little bit of extra complexity. This microlearning will explain one of those more complex scenarios. In this microlearning, we will learn how to use two property lists to alter the input value to the desired output value. This functionality is beneficial when the list you are working with is not entirely static and is too long to be captured as an enum list.
27
28 Essential characteristics of this functionality are:
29
30 * There is an input and an output list. Both are equal in length
31 * The logic searches for the position of the content in the input list
32 * The logic returns the corresponding value in the output list that holds the same position in the list
33
34 Before we take a look at the implementation in eMagiz lets us first explain the concept at hand. To make this work you need two seperate properties. Each of these properties should contain a comma seperated list of values. Something along these lines:
35
36 * Input list: one,two,three,four,five
37 * Output list: één,twee,drie,vier,vijf
38
39 Note that the key is that both lists have the same number of (unique) values within them. If there is a mismatch, or the ordering is wrong, the output will not be the desirable output. Furthermore you should always think of how you want your logic to react the moment it cannot find the corresponding value. Should it throw an error? Should it return to some default? That is up to you.
40
41 The moment a message arrives part of the message will be compared to the values in the input list. If the value can be found in the input list the position within the list is returned. So for example when the input message contains the value two the logic will return position 2 as a result. When the position is returned the next step of the logic will retrieve the value at position 2 in our output list. In this case that would be twee.
42
43 In the remainder of this microlearning, we will look at how you could implement this logic within the eMagiz tooling.
44
45 === 3.1 Implementation ===
46
47 To implement this piece of logic we need a custom snippet in our transformation that does the work for us. Note that whenever you use a custom snippet you should not forget to include references to other elements in case the output structure demands those. In the example that will follow we have a very simple output message and therefore the shown solution should not be implemented one on one in your project as that would most likely break your transformation.
48
49 First we need to navigate to the Create phase of eMagiz and open the flow in which we want to add this logic. Once you have opened your flow, you need to enter "Start editing" mode. This mode allows you to change the flow in question and add the logic to the transformation within the flow. When you have done so, it becomes time to navigate to the transformation part of your flow. In here you can add a custom snippet to your transformation. You can do so by clicking on the code icon.
50
51 [[image:Main.Images.Microlearning.WebHome@intermediate-data-handling-compare-content-to-propertylist--custom-snippet-icon.png]]
52
53 Within the custom snippet we need the following logic:
54
55 * Logic that determines what the position in the input list is of the supplied content (value)
56 * Logic that determines what the correspoding value, based on that position, in the output list is
57 * Logic that supplies this value to the correct output field
58
59 Creating this logic in this simple example will mean we end up with the following custom snippet:
60
61 {{code language="xml"}}
62 <xsl:variable name="indexOfInputValue" select="index-of((tokenize($possibleInputValues, ',')), //*:Name)"/>
63 <xsl:variable name="outputValue" select="if(exists(tokenize($possibleOutputValues,',')[$indexOfInputValue])) then tokenize($possibleOutputValues,',')[$indexOfInputValue] else 'unknown'"/>
64 <Module>
65 <Naam>
66 <xsl:value-of select="$outputValue"/>
67 </Naam>
68 <xsl:if test="exists(cdm:RequiredTime)">
69 <BenodigdeTijd>
70 <xsl:value-of select="cdm:RequiredTime"/>
71 </BenodigdeTijd>
72 </xsl:if>
73 <xsl:if test="exists(cdm:Description) and cdm:Description!=''">
74 <Omschrijving>
75 <xsl:value-of select="cdm:Description"/>
76 </Omschrijving>
77 </xsl:if>
78 <Niveau>
79 <xsl:value-of select="cdm:Level"/>
80 </Niveau>
81 </Module>
82 {{/code}}
83
84 As you can see we have added two variables to the snippet that will determine the index and the corresponding output value. Subsequently we make sure that the output element called Naam will be filled with the output value. In eMagiz you will see this when you add the custom snippet.
85
86 [[image:Main.Images.Microlearning.WebHome@intermediate-data-handling-compare-content-to-propertylist--custom-snippet-input.png]]
87
88 Finishing this is only half the battle. We still need to feed our property lists into the transformation. To do so we need parameters. For more information on parameters in transformation please check out this [microlearning](novice-create-your-transformations-xslt-parameters.md). In this case we need two parameters:
89
90 * possibleInputValues
91 * possibleOutputValues
92
93 [[image:Main.Images.Microlearning.WebHome@intermediate-data-handling-compare-content-to-propertylist--parameters-defined.png]]
94
95 After that we need to tell the component itself how these parameters (which are still empty shells) need to be filled. To do so navigate back to the flow canvas and open the XSLT transformer component. On the advanced tab you can define the relevant values for each of our parameters. In this case you need two seperate properties as input values.
96
97 [[image:Main.Images.Microlearning.WebHome@intermediate-data-handling-compare-content-to-propertylist--parameter-values-defined.png]]
98
99 With this configuration done your logic is complete. Do note that the logic is case sensitive. So when you receive Three instead of three the logic will default to unknown. If the other party cannot guarantee that data is always delivered exactly the same you should take additional measures to guarantee that.
100
101 === 3.2 Use cases ===
102
103 Now that we now how to implement it we can take a quick look at some possible use cases for this logic. We see this logic popping up mainly when both of the lists are static enough to be captured as property but change enough to make it impractical to use enumerations. A further complication of the use of enumerations, especially on CDM level is that certain elements might be reused across integrations and changing the enum list for one of them automatically means that you change them for all of them.
104
105 == 4. Assignment ==
106
107 Look for places where you could use this logic to aid your integration process within your (Academy) project.
108 This assignment can be completed with the help of your (Academy) project you have created/used in the previous assignment.
109
110 == 5. Key takeaways ==
111
112 Essential characteristics of this functionality are:
113
114 * There is an input and an output list. Both are equal in length
115 * The logic searches for the position of the content in the input list
116 * The logic returns the corresponding value in the output list that holds the same position in the list
117
118 == 6. Suggested Additional Readings ==
119
120 If you are interested in this topic and want more information, please read the help text provided by eMagiz.
121
122 == 7. Silent demonstration video ==
123
124 This video demonstrates how you could have handled the assignment and gives you some context on what you have just learned.
125
126 {{video attachment="intermediate-data-handling-compare-content-to-propertylist.mp4" reference="Main.Videos.Microlearning.WebHome"/}})))
127
128 ((({{toc/}}))){{/container}}
129 {{/container}}