SpEL Functions eMagiz

Last modified by Erik Bakker on 2024/09/02 16:01

Please note that this microlearning is for the new generation architecture only.

In the previous microlearning 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, 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.

Should you have any questions, please get in touch with academy@emagiz.com.

1. Prerequisites

Advanced knowledge of the eMagiz platform
A (very) basic understanding of Java

2. Key concepts

This microlearning centers around listing out specific SpEL functions available in eMagiz
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.

When using SpEL expressions within the eMagiz tool, follow these guidelines:

Use annotations to describe the behavior of the SpEL expression. This is to ensure the maintainability of the flow.
Make things simple when using SpEL expressions. This is to ensure the readability of the flow

3. SpEL Functions - eMagiz

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.

3.1 JSON and XML functions

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.

#xpath(payload,String Xpath in question)

Returns the value of the field to which the XPath expression is referring.

#jsonPath(payload,String jsonPath in question)

Returns the field value to which the JSON path expression is referring.

#jsonToObject(String input)

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.

#objectToJson(Object input)

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.

#xmlToObject(String input)

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.

#objectToXml(Object input)

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.

3.2 Datetime operations

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.

#currentDateTime()

Returns a java.time.OffsetDateTime object holding the current datetime at UTC timezone. e.g. '2023-11-14T09:06:21.180Z'.

#currentEpochMilli()

Returns the current datetime represented in epoch milliseconds.

#currentEpochSecond()

Returns the current datetime represented in epoch seconds.

#dateTimeToEpochMilli(OffsetDateTime input)

Takes an OffsetDateTime as input and transforms it to epoch milliseconds.

#dateTimeToEpochSecond(OffsetDateTime input)

Takes an OffsetDateTime as input and transforms it to epoch seconds.

#epochMilliToDateTime(long input)

Takes an epoch millisecond string as input and transforms it to an OffsetDateTime at timezone UTC.

#epochSecondToDateTime(long input)

Takes an epoch second string as input and transforms it to an OffsetDateTime at timezone UTC.

#formatDateTime(OffsetDateTime input)

Takes an OffsetDateTime as input and transforms it to the 'xs:dateTime' format, suitable for use in XML.

#parseDateTime(String input)

Takes an 'xs:dateTime' and transforms it to an OffsetDateTime in UTC.

3.3 Encoding and decoding

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.

#base64Decode(String base64EncodedString, String resultType)

Transforms a base64 encoded string to bytes or decoded string. Valid options for the resultType parameter are 'bytes' or 'string'.

#base64Encode(Object valueToEncode)

Encodes the input to base64.

#hexDecode(String hexEncodedString, String resultType)

Transforms a hex-encoded string to bytes or decoded string. Valid options for the resultType parameter are 'bytes' or 'string'.

#hexEncode(Object valueToEncode)

Encodes the input to hex.

#hmac(String algorithm, String secretKey, Object data, String resultType)

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

4. Key takeaways

eMagiz offers a wide variety of SpEL functions within the platform that make using the platform for complex cases easier.
When using SpEL expressions, explain your work for maintainability purposes
Check out the previous microlearning alongside this microlearning and the suggested additional readings for examples and more clarity on the subject