Wiki source code of SpEL Expressions

Last modified by Erik Bakker on 2023/11/24 08:28
Show last authors
1 {{container}}{{container layoutStyle="columns"}}(((
2 The tools in eMagiz provide a wide range of options to build your integrations with. For example, in some of the building blocks in the model, capability can be extended using SpEL expressions. SpEL expressions are derived from the Spring Integration Framework, which stands for Spring Expression Language. SpEL expressions are potent and handy, yet basic knowledge of SpEL expressions is required to add or modify the behavior of specific flows in eMagiz. In this microlearning, we will focus on implementing SpEL expressions within the eMagiz tooling.
3
4 Should you have any questions, please get in touch with [[academy@emagiz.com>>mailto:academy@emagiz.com]].
5
6 == 1. Prerequisites ==
7
8 * Advanced knowledge of the eMagiz platform
9 * A (very) basic understanding of Java
10
11 == 2. Key concepts ==
12
13 This microlearning centers around using SpEL expressions in eMagiz
14 By SpEL expressions, we mean A powerful expression language that supports querying and manipulating an object graph at runtime. It can be used with XML or annotation-based Spring configurations.
15
16 When using SpEL expressions within the eMagiz tool, follow these guidelines:
17
18 * Use annotations to describe the behavior of the SpEL expression. This is to ensure the maintainability of the flow.
19 * Don't make things too complicated when using SpEL expression. This is to ensure the readability of the flow
20
21 == 3. SpEL Expressions ==
22
23 The tools in eMagiz provide a wide range of options to build your integrations with. For example, in some of the building blocks in the model, capability can be extended using SpEL expressions. SpEL expressions are derived from the Spring Integration Framework, which stands for Spring Expression Language. SpEL expressions are potent and handy, yet basic knowledge of SpEL expressions is required to add or modify the behavior of specific flows in eMagiz. In this microlearning, we will focus on implementing SpEL expressions within the eMagiz tooling.
24
25 When using SpEL expressions within the eMagiz tool, follow these guidelines:
26
27 * Use annotations to describe the behavior of the SpEL expression. This is to ensure the maintainability of the flow.
28 * Don't make things too complicated when using SpEL expression. This is to ensure the readability of the flow
29
30 In the remainder of this microlearning, we take a look at some examples within the eMagiz tooling in which SpEL expressions could be used:
31
32 * Executing a logical operation in which you validate whether a particular value equals an expected value.
33 * Place the complete payload in a header. This is sometimes needed as you need to restore the original payload after performing another action.
34 * Routing best-practice
35 * To determine if a value in your message is listed in a list and use it as a filter.
36 * The example we use is the authorization in an all-entry flow when using the API key security mechanism for securing your web service.
37 * To create an if-statement using header values.
38
39 Before we delve into the examples, we first describe the SpEL notation.
40
41 === 3.1 SpEL notation ===
42
43 A message in eMagiz has two main parts, as you well know. One part is the payload, and the other part is the headers. Both are accessible via a SpEL expression.
44
45 To retrieve data from a payload you can use the following notation in SpEL: {{code}}#xpath(payload,'//\*:uniqueIdentifier'){{/code}}. For more information on using SpEL as an XPath expression please see this [[microlearning>>doc:Main.eMagiz Academy.Microlearnings.Advanced Level.Create your transformations.advanced-create-your-transformations-xpath-advanced||target="blank"]].
46
47 To retrieve data from a header, you can use one of the following notations:
48
49 * {{code language="spel"}}headers.nameOfHeader{{/code}}
50 * {{code language="spel"}}headers['nameOfHeader']{{/code}}
51
52 Below we describe the difference between both options:
53
54 * When it is required that the header is present, you can use {{code language="spel"}}headers.nameOfHeader{{/code}} (this will fail if the header is missing)
55 * When the header might be missing, you should use {{code language="spel"}}headers['nameOfHeader]{{/code}} (and then correctly handle ""null"" values)
56
57 === 3.2 Logical Operation ===
58
59 A very straightforward example of using SpEL to determine whether a message can continue is a logical operation. In the example described below, the message can only pass if the value stored in the header named error equals ''yes''. In all other cases, the message is not allowed to pass the filter and will be on the discard channel.
60
61 [[image:Main.Images.Microlearning.WebHome@advanced-data-handling-spel-expressions--logical-operation-example.png]]
62
63 === 3.3 Payload in Header ===
64
65 A standard header enricher gives you the option to add information on top of the payload. In this example, a new header is added with the name "backup" and the value of the header is the complete payload of the current message, {{code language="spel"}}value = payload{{/code}}. Take notice that ''Type'' is a SpEL expression. This expression is filled in on the tab ''Advanced''.
66
67 [[image:Main.Images.Microlearning.WebHome@advanced-data-handling-spel-expressions--payload-in-header.png]]
68
69 {{warning}}Please be aware that setting the payload in your header and transporting it along will double the size of your message.{{/warning}}
70
71 === 3.4 Routing best-practice ===
72
73 Below you will find the best practice to build the routing flow in eMagiz. This best practice uses the standard router where you can use a SpEL Expression to route your message. That SpEL Expression looks like this: “headers.model_targetSystem.split(',').![#this.trim()+#root.headers.model_messageType]”.
74
75 The first part of the SpEL Expression looks at the ''model_targetSystem'' header. This header can contain multiple values separated by a comma. So a message can be routed to various target systems. The second part of the SpEL Expression looks at the ''model_messageType'' header. This SpEL expression can be multiple values since the message can have various ''model_targetSystem'' headers.
76
77 An example of how this works is detailed below.
78
79 * Header: model_targetSystem: TMS, FMS
80 * Header: model_messageType: Order
81
82 Will be routed to the following value mappings:
83
84 * TMSOrder
85 * FMSOrder
86
87 [[image:Main.Images.Microlearning.WebHome@advanced-data-handling-spel-expressions--routing-best-practice.png]]
88
89 === 3.5 Api key authorization check ===
90
91 When using the API key method to authorize whether a client is indeed authorized, you can use a SpEL expression to validate the API key against a default list and provide feedback on whether the client is indeed authorized. Depending on the service you are hosting (REST or SOAP), you can implement it differently. This example will show the simplest way to implement this by using an excellent SpEL expression in a standard filter. An example of such a SpEL expression is:
92
93 (headers['Authorization']!=null or headers['Authorization']!='') and '${authentication.gateway.getdbtr.api-key}'.contains(';'+headers['Authorization']+';')
94
95 [[image:Main.Images.Microlearning.WebHome@advanced-data-handling-spel-expressions--api-key-auth-check.png]]
96
97 This SpEL expression validates whether the header called Authorization exists and whether the value in the header called Authorization is registered within the property called authentication.gateway.getdbtr.API-key.
98
99 === 3.6 If then else ===
100
101 With the help of a SpEL expression, you can also define an if then else statement (also known as an Elvis operator). In such a SpEL expression, you can determine based on specific criteria what to do. An example of how to implement this is depicted below:
102
103 headers['splxprs_messageID'] != null and {${splxprs.lvsprtr.message-ids}}.contains(headers.splxprs_messageID) ? true() : false()
104
105 This expression defines that when the header in question exists and the header's value can be found within a predefined property, the expression should return true(). In all other cases, it should return false().
106
107 [[image:Main.Images.Microlearning.WebHome@advanced-data-handling-spel-expressions--if-then-else.png]]
108
109 == 4. Key takeaways ==
110
111 * There are multiple alternatives for using SpEL expressions within eMagiz
112 * When using SpEL expressions, explain your work for maintainability purposes
113 * Check out the microlearning and the suggested additional readings for examples and more clarity on the subject
114
115 == 5. Suggested Additional Readings ==
116
117 If you are interested in this topic and want more information on it, please read the release notes provided by eMagiz when implementing SpEL expressions, and please check out the following links:
118
119 * [[SpEL explained>>https://www.baeldung.com/spring-expression-language||target="blank"]]
120 * [[SpEL in the Spring framework>>https://docs.spring.io/spring/docs/4.3.10.RELEASE/spring-framework-reference/html/expressions.html||target="blank"]])))((({{toc/}}))){{/container}}{{/container}}