Wiki source code of SpEL Functions eMagiz

Last modified by Erik Bakker on 2023/11/26 20:39
Show last authors
1 {{container}}{{container layoutStyle="columns"}}(((
2 {{warning}}
3 Please note that this microlearning is for the new generation architecture only.
4 {{/warning}}
5
6 In the previous [[microlearning>>doc:Main.eMagiz Academy.Microlearnings.Advanced Level.Data Handling.advanced-data-handling-spel-functions.WebHome||target="blank"]] we explained the concept of SpEL and how to use some generic SpEL functions throughout components in the tooling. In this microlearning, we focus on specific SpEL functions that are part of the eMagiz platform and make it easier for users to perform particular actions using SpEL. As explained in the previous [[microlearning>>doc:Main.eMagiz Academy.Microlearnings.Advanced Level.Data Handling.advanced-data-handling-spel-functions.WebHome||target="blank"]], there are various components in the Create phase where you can use these SpEL expressions. Based on what you need and on the function of the SpEL expression, you can determine which component is most suitable to achieve your end goal.
7
8 Should you have any questions, please get in touch with [[academy@emagiz.com>>mailto:academy@emagiz.com]].
9
10 == 1. Prerequisites ==
11
12 * Advanced knowledge of the eMagiz platform
13 * A (very) basic understanding of Java
14
15 == 2. Key concepts ==
16
17 This microlearning centers around listing out specific SpEL functions available in eMagiz
18 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.
19
20 When using SpEL expressions within the eMagiz tool, follow these guidelines:
21
22 * Use annotations to describe the behavior of the SpEL expression. This is to ensure the maintainability of the flow.
23 * Make things simple when using SpEL expressions. This is to ensure the readability of the flow
24
25 == 3. SpEL Functions - eMagiz ==
26
27 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 and 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. This microlearning will focus on a standard set of SpEL functions offered within the eMagiz platform.
28
29 === 3.1 JSON and XML functions ===
30
31 Below is a list of SpEL functions you can execute on a JSON or XML message. Per function, we describe what it can do for you.
32
33 {{code language="spel"}}#xpath(payload,String Xpath in question){{/code}}
34
35 Returns the value of the field to which the XPath expression is referring.
36
37 {{code language="spel"}}#jsonPath(payload,String jsonPath in question){{/code}}
38
39 Returns the field value to which the JSON path expression is referring.
40
41 {{code language="spel"}}#jsonToObject(String input){{/code}}
42
43 Returns your JSON payload as a Java object. This is used on default in the Aggregator component and the Standard Content Enricher so we can manipulate the payload in one go, instead of using multiple components to achieve the same result.
44
45 {{code language="spel"}}#objectToJson(Object input){{/code}}
46
47 Returns your Java object as a JSON payload. This is used on default in the Aggregator component and the Standard Content Enricher so we can manipulate the payload in one go, instead of using multiple components to achieve the same result.
48
49 {{code language="spel"}}#xmlToObject(String input){{/code}}
50
51 Returns your XML payload as a Java object. This is used on default in the Aggregator component and the Standard Content Enricher so we can manipulate the payload in one go, instead of using multiple components to achieve the same result.
52
53 {{code language="spel"}}#objectToXml(Object input){{/code}}
54
55 Returns your Java object as an XML payload. This is used on default in the Aggregator component and the Standard Content Enricher so we can manipulate the payload in one go, instead of using multiple components to achieve the same result.
56
57 === 3.2 Datetime operations ===
58
59 Below, you will find a list of SpEL functions that you can execute to calculate various dateTime values or manipulate dateTime values. Per function, we describe what it can do for you.
60
61 {{code language="spel"}}#currentDateTime(){{/code}}
62
63 Returns a java.time.OffsetDateTime object holding the current datetime at UTC timezone. e.g. '2023-11-14T09:06:21.180Z'.
64
65 {{code language="spel"}}#currentEpochMilli(){{/code}}
66
67 Returns the current datetime represented in epoch milliseconds.
68
69 {{code language="spel"}}#currentEpochSecond(){{/code}}
70
71 Returns the current datetime represented in epoch seconds.
72
73 {{code language="spel"}}#dateTimeToEpochMilli(OffsetDateTime input){{/code}}
74
75 Takes an OffsetDateTime as input and transforms it to epoch milliseconds.
76
77 {{code language="spel"}}#dateTimeToEpochSecond(OffsetDateTime input){{/code}}
78
79 Takes an OffsetDateTime as input and transforms it to epoch seconds.
80
81 {{code language="spel"}}#epochMilliToDateTime(long input){{/code}}
82
83 Takes an epoch millisecond string as input and transforms it to an OffsetDateTime at timezone UTC.
84
85 {{code language="spel"}}#epochSecondToDateTime(long input){{/code}}
86
87 Takes an epoch second string as input and transforms it to an OffsetDateTime at timezone UTC.
88
89 {{code language="spel"}}#formatDateTime(OffsetDateTime input){{/code}}
90
91 Takes an OffsetDateTime as input and transforms it to the 'xs:dateTime' format, suitable for use in XML.
92
93 {{code language="spel"}}#parseDateTime(String input){{/code}}
94
95 Takes an 'xs:dateTime' and transforms it to an OffsetDateTime in UTC.
96
97 === 3.3 Encoding and decoding ===
98
99 Below is a list of SpEL functions you can execute on a JSON or XML message. Per function, we describe what it can do for you.
100
101 {{code language="spel"}}#base64Decode(String base64EncodedString, String resultType){{/code}}
102
103 Transforms a base64 encoded string to bytes or decoded string. Valid options for the resultType parameter are 'bytes' or 'string'.
104
105 {{code language="spel"}}#base64Encode(Object valueToEncode){{/code}}
106
107 Encodes the input to base64.
108
109 {{code language="spel"}}#hexDecode(String hexEncodedString, String resultType){{/code}}
110
111 Transforms a hex-encoded string to bytes or decoded string. Valid options for the resultType parameter are 'bytes' or 'string'.
112
113 {{code language="spel"}}#hexEncode(Object valueToEncode){{/code}}
114
115 Encodes the input to hex.
116
117 {{code language="spel"}}#hmac(String algorithm, String secretKey, Object data, String resultType){{/code}}
118
119 Encodes usig hmac. Valid options for the algorithm parameter are variants of javax.crypto.Mac algorithm, e.g. 'HmacMD5', 'HmacSHA1', 'HmacSHA256'. Valid options for the resultType parameter are 'bytes', ' base64' or 'hex'.
120
121 == 4. Key takeaways ==
122
123 * eMagiz offers a wide variety of SpEL functions within the platform that make using the platform for complex cases easier.
124 * When using SpEL expressions, explain your work for maintainability purposes
125 * Check out the previous [[microlearning>>doc:Main.eMagiz Academy.Microlearnings.Advanced Level.Data Handling.advanced-data-handling-spel-functions.WebHome||target="blank"]] alongside this microlearning and the suggested additional readings for examples and more clarity on the subject
126
127 == 5. Suggested Additional Readings ==
128
129 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:
130
131 * [[SpEL explained>>https://www.baeldung.com/spring-expression-language||target="blank"]]
132 * [[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}}