Licenses	COMMUNITY, ENTERPRISE, CORPORATE
Since	VERSION 6.0

1 Introduction
2 Using a PEL Util
- 2.1 Auto-completion in the Online Workbench
3 PEL Utils Reference
- 3.1 @calc
  - 3.1.1 @calc.avg(list)
  - 3.1.2 @calc.sum(list)
- 3.2 @convert
  - 3.2.1 @convert.toBase64(object)
  - 3.2.2 @convert.fromBase64(base64Text)
  - 3.2.3 @convert.fromBase64ToBytes(base64Text)
  - 3.2.4 @convert.lazy(uri) Preview
  - 3.2.5 @convert.toJson(jsonString)
  - 3.2.6 @convert.toMap(object)
- 3.3 @date
  - 3.3.1 @date.format(dateTime, pattern)
  - 3.3.2 @date.isExpired(start, end, percentage, [currentDate])
  - 3.3.3 @date.isOverdue(dueDate [, currentDate])
  - 3.3.4 @date.now(pattern)
  - 3.3.5 @date.timestamp()
- 3.4 @instance
  - 3.4.1 @instance.domain()
  - 3.4.2 @instance.namespace()
  - 3.4.3 @instance.url([serviceName])
- 3.5 @list
  - 3.5.1 @list.add(list, element) Preview
  - 3.5.2 @list.contains(list, needle)
  - 3.5.3 @list.empty(value)
  - 3.5.4 @list.first(value)
  - 3.5.5 @list.last(value)
  - 3.5.6 @list.size(value)
  - 3.5.7 @list.sublist(value, expression)
- 3.6 @path
  - 3.6.1 @path.basename(path)
  - 3.6.2 @path.extension(path)
  - 3.6.3 @path.join(items)
- 3.7 @property
  - 3.7.1 @property.get(key)
  - 3.7.2 @property.lazy(key) Preview
  - 3.7.3 @property.value(key)
- 3.8 @text
  - 3.8.1 @text.append(basetext, text)
  - 3.8.2 @text.concat(separator, list)
  - 3.8.3 @text.concatAndFormat(separator, list, pel)
  - 3.8.4 @text.contains(value, needle)
  - 3.8.5 @text.isEmpty(value)
  - 3.8.6 @text.lang(value)
  - 3.8.7 @text.length(value)
  - 3.8.8 @text.lowerCase(value)
  - 3.8.9 @text.lowerCaseFirst(value)
  - 3.8.10 @text.prefix(text, stopWord)
  - 3.8.11 @text.random(length)
  - 3.8.12 @text.shorten(value, length)
  - 3.8.13 @text.trim(value)
  - 3.8.14 @text.upperCase(value)
  - 3.8.15 @text.upperCaseFirst(value)
  - 3.8.16 @text.uuid()
- 3.9 @user Preview
  - 3.9.1 @user.displayName([userData]) Preview
  - 3.9.2 @user.email() Preview
  - 3.9.3 @user.firstName() Preview
  - 3.9.4 @user.lastName() Preview
  - 3.9.5 @user.locale() Preview
  - 3.9.6 @user.uuid() Preview
  - 3.9.7 @user.username() Preview

Introduction

The PEL Utils is a powerful library of built-in utility methods which can be used inside a Pipeline Expression (PE) to simplify work. The libraries cover typical day-to-day flows and logics as simple helpers which are embedded into the PE.

Note: In order to understand PEL Utils you should have at least basic knowledge about the https://logabit.atlassian.net/wiki/spaces/DEVEX/pages/2151287454.

Using a PEL Util

The structure of calling a PEL Util inside a pipeline looks like this:

#{ @utilName.method(args) }

Replace utilName by the name of the utility and method by the function/method you want to call. See the documentation of the utility which parameters/arguments are supported.

Lets take a look on this example how to embed the PEL util @date inside a pipeline:

pipeline:
  - log: 
      message: "Today is: #{@date.now('dd.MM.YYYY')}"

The output of this example into the log would be this:

Today is: 12.08.2020

Another example is to detect the language of a given text automatically using the PEL util @text:

vars:
  text: "Guten Tag, Frau Meier"
pipeline:
  - log: 
      message: "#{@text.lang(vars.text)}"

The output of this example into the log would be this:

GERMAN

Auto-completion in the Online Workbench

Only: ENTERPRISE, CORPORATE

When using the low code editor of the online workbench in the web UI, you can get auto-completion support. Whenever you are inside a pipeline expression indicated by a starting #{ you can type @ + Ctrl + Space and you will get a list of all available PEL utils. For example:

After you have selected a util you can browse the available methods of the util by typing a period . + Ctrl + Space:

After running the pipeline, the output would be similar to this:

PEL Utils Reference

Here you can find a list of all built-in PEL utils ready to be used out-of-the box.

Note: Utils functions marked with Preview are not officially released yet and only here for preview and trial purposes. They can change without any notice. So be careful using them in production.

@calc

This utility provides utility methods for simple mathematical/calculation tasks.

@calc.avg(list)

Calculates the average based on the given list of input values.

Parameter: `list`	A list of numbers (integers or floats) to calculate the AVG from. In case the elements in the list are no number types it is tried to automatically convert them to a number.
Returns	Returns AVG of the given list of numbers.

Example 1

vars:
  ageList: "35, 89, 12, 56, 78, 23"
pipeline:
  - log: 
      message: "Average age: #{@calc.avg(vars.ageList)}"

Output:

Average age: 48.84

@calc.sum(list)

Calculates the sum based on the given list of input values.

Parameter: `list`	A list of numbers (integers or floats) to calculate the sum from. In case the elements in the list are no number types it is tried to automatically convert them to a number.
Returns	Returns the sum of the given list of numbers.

Example 1

vars:
  numbers: "10, 10, 10, 10"
pipeline:
  - log: 
      message: "The sum is: #{@calc.sum(vars.numbers)}"

Output:

The sum is: 40

@convert

This util provides methods to convert and encode/decode data from one format to another.

@convert.toBase64(object)

Converts the given plain text or byte array to a base64 encoded text.

Learn more about base64: https://en.wikipedia.org/wiki/Base64

Note: base64 encoding is not an encryption! If you need to encrypt data, use the encrypt commands.

Parameter: `rawText or byte array`	The content to base64 encode.
Returns	The base64 encoded `rawText` or null in case `rawText` was null.

Example 1

pipeline:
  - log: 
      message: "#{@convert.toBase64('Hello World!')}"

Output:

SGVsbG8gV29ybGQh

@convert.fromBase64(base64Text)

Converts the given base64 encoded text back to the original value.

Learn more about base64: https://en.wikipedia.org/wiki/Base64

Note: base64 encoding is not an encryption! If you need to encrypt data, use the encrypt commands.

Parameter: `base64Text`	The text to decode from base64 to the original value.
Returns	The base64 decoded `base64Text` or null in case `base64Text` was null.

Example 1

pipeline:
  - log: 
      message: "#{@convert.fromBase64('SGVsbG8gV29ybGQh')}"

Output:

Hello World!

@convert.fromBase64ToBytes(base64Text)

Converts the given base64 encoded text back to the original value and returns it as a byte array.

Learn more about base64: https://en.wikipedia.org/wiki/Base64

Note: base64 encoding is not an encryption! If you need to encrypt data, use the encrypt commands.

Parameter: `base64Text`	The text to decode from base64 to the original value.
Returns	The base64 decoded `base64Text` as byte array or null in case `base64Text` was null.

Example 1

pipeline:
  - log: 
      message: "#{@convert.fromBase64ToBytes('SGVsbG8gV29ybGQh')}"

Output:

[H,e,l,l,o, ,W,o,r,l,d,!]

@convert.lazy(uri) Preview

Loads the content of the given content uri as a lazy map.

Parameter: `uri`	The the content uri of the content to be loaded.
Returns	A map which lazy loads its content when accessed. This is especially useful for huge documents like JSON in order to lazy load them.

Example 1

pipeline:
  - log: 
      message: "#{@convert.lazy('uri:user:username=someUser')}"

Output:

id: "34ec9dcd-896c-45c8-bc13-d0085d22e193"
username: "someUser"
firstName: myFirstName
lastName: myLastName
email: "some@email.tld"
emailVerified: true
attributes: null
locale: null
displayName: "someUser"
emailAndDisplayName: "some@email.tld (myFirstName myLastName)"

@convert.toJson(jsonString)

Converts the given JSON string to a JSON node object required by some other utilities.

Parameter: `jsonString`	The JSON string to convert to JSON node
Returns	A JSON node object or null in case the input was null. Throws error in case the given `jsonString` is invalid.

@convert.toMap(object)

Tries to convert the given object to a map.

Parameter: `object`	An object which can be converted to a map. For example a JSON document.
Returns	The converted map. Throws exception in case the object could not be converted to map.

@date

This util is for date and time formatting and calculations.

@date.format(dateTime, pattern)

Formats the given dateTime string using the given pattern.

Parameter: `dateTime`	The date and time string to be formatted. Must be in a valid ISO-8601 format. For example: `2030-01-10T20:00:00Z`. See here for a documentation of this ISO format: https://en.wikipedia.org/wiki/ISO_8601
Parameter: `pattern`	The pattern to be used to format the given date and time. Throws an error in case the pattern has an invalid format. For a full reference of all possible patterns, see here: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html
Returns	The value of `dateTime` formatted using the given pattern.

Example 1

pipeline:
  - log: 
      message: "Date: #{@date.format('2030-01-10T20:00:00Z', 'dd.MM.YYYY')}"

Output:

Date: 10.01.2030

@date.isExpired(start, end, percentage, [currentDate])

Returns true in case the given amount of percentage in given time range is already expired.

This method is useful if you want to measure whether a given amount of time inside a time frame has been already expired.

For example if you want to send a reminder email to a user in case a given amount of time has been expired within a given time frame: User registered at 1st January, 2020 and timeout of registration token is 11th January, 2020 so you will remind him after 70% (0.7) has been expired without finishing the registration. Then, this method would help to determine whether to send such a reminder, since it returns true on 9th of January, 2020 but false on 3rd of January, 2020.

Parameter: `start`	The start date in ISO-8601 format. For example: `2030-01-10T20:00:00Z`. See here for a documentation of this ISO format: https://en.wikipedia.org/wiki/ISO_8601
Parameter: `end`	The end date in ISO-8601 format. For example: `2030-01-10T20:00:00Z`. See here for a documentation of this ISO format: https://en.wikipedia.org/wiki/ISO_8601
Parameter: `percentage`	The expired amount as percentage in float (0.7 = 70%).
Parameter: `currentDate`	Optional parameter of the current date to be used for the calculation. Can be a ISO-8061 string or unix epoch timestamp in millis. If null, the current date of the server will be used.
Returns	true in case the amount of time has been expired within compared with current time.

Example 1

pipeline:
  - log: 
      message: "Date: #{@date.isExpired('2030-01-01T20:00:00Z', '2030-01-10T20:00:00Z', 0.7)}"

Output:

false

@date.isOverdue(dueDate [, currentDate])

Returns true in case the current date is after the given due date.

Parameter: `dueDate`	The due date as ISO-8061 string or unix epoch timestamp in millis.
Parameter: `currentDate`	The current date to be used for the calculation as ISO-8061 string or unix epoch timestamp in millis. If null, the current date of the server will be used.
Returns	True if currentDate is after dueDate.

Example 1

pipeline:
  - log: 
      message: "Date: #{@date.isOverdue('2010-01-01T20:00:00Z')}"

Output:

true

@date.now(pattern)

Gets the current server time and formats it using the given format pattern.

Parameter: `pattern`	The pattern to be used to format the current date and time. Throws an error in case the pattern has an invalid format. For a full reference of all possible patterns, see here: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html
Returns	The date and time formatted using the given pattern.

Example 1

pipeline:
  - log: 
      message: "Current date: #{@date.now('dd.MM.YYYY')}"

Output:

Current date: 01.03.2020

Example 2

pipeline:
  - log: 
      message: "Current date: #{@date.now('dd.MM.YYYY, HH:mm')}"

Output:

Current date: 01.03.2020, 23:11

@date.timestamp()

Returns the time in milliseconds since 01.01.1970 (also known as “unix epoch”).

Returns

Returns the time in milliseconds since 01.01.1970 (also known as “unix timestamp”).

Example 1

pipeline:
  - log: 
      message: "Timesmap: #{@date.timestamp()}"

Output:

Timestamp: 246668400000

@instance

An util which returns information about the instance this pipeline is currently running on.

@instance.domain()

The domain name, this instance is currently running at.

Returns

Returns the domain name this instance is currently running under. This is usually pipeforce.net.

Example 1

pipeline:
  - log: 
      message: "#{@instance.domain()}"

Output:

pipeforce.net

@instance.namespace()

The namespace, this instance is currently running at.

Returns

Returns the namespace this instance is currently running under. This is usually your company name.

Example 1

pipeline:
  - log: 
      message: "#{@instance.namespace()}"

Output:

acme

@instance.url([serviceName])

Returns the instance url to the given service.

Parameter: `serviceName`	The optional service name to return the url for. For example: hub, drive or portal. If null or empty, returns the home url of the instance.
Returns	The base url to the given service.

Example 1

pipeline:
  - log: 
      message: "#{@instance.url('drive')}"

Output:

https://drive-acme.pipeforce.net

Example 2

pipeline:
  - log: 
      message: "#{@instance.url()}"

Output:

https://acme.pipeforce.net

@list

This util helps in handling lists.

@list.add(list, element) Preview

Adds the given element at the end of the given list.

Parameter: `list`	A list-type data structure. Can be a collection, list, array, JSON array or a comma separated list for example.
Parameter: `element`	The element to be added to the given list.
Returns	`void`

Example 1

vars:
  names: "Megan, Sharol, Sabine, Claudia"
pipeline:
  - log: 
      message: "#{@list.add(vars.names, 'Herbert')}"

Output:

- "Megan"
- "Sharol"
- "Sabine"
- "Claudia"
- "Herbert"

@list.contains(list, needle)

Returns true in case value is a list and contains needle as entry.

Parameter: `list`	A list-type data structure. Can be a collection, list, array, JSON array or a comma separated list for example.
Parameter: `needle`	The entity to search for inside of value.
Returns	`true` in case needle could be found inside value. Returns `false` if not or if value is not a list structure.

Example 1

vars:
  names: "Megan, Sharol, Sabine, Claudia"
pipeline:
  - log: 
      message: "Lilly in list? #{@list.contains(vars.names, 'Lilly')}"

Output:

Lilly in list? false

@list.empty(value)

Returns the true in case the given value is null or empty.

Parameter: `value`	A list-type data structure. Can be a collection, list, array, JSON array or a comma separated list for example.
Returns	`true` in case value is null or empty. Empty means the list structure contains no entries.

Example 1

vars:
  names: "Megan, Sharol, Sabine, Claudia"
pipeline:
  - log: 
      message: "Empty: #{@list.empty(vars.names)}"

Output:

Empty: false

@list.first(value)

Returns the first element of the given list value.

Parameter: `value`	A list-type data structure. Can be a collection, list, array, JSON array or a comma separated list for example.
Returns	The very first element in the list or null in case value is not a list or is empty.

Example 1

vars:
  names: "Megan, Sharol, Sabine, Claudia"
pipeline:
  - log: 
      message: "#{@list.first(vars.names)}"

Output:

Megan

@list.last(value)

Returns the last element from the given list.

Parameter: `value`	A list-type data structure. Can be a collection, list, array, JSON array or a comma separated list for example.
Returns	The last element from the given list or `null` in case the list is empty, null or is no list structure.

Example 1

vars:
  names: "Megan, Sharol, Sabine, Claudia"
pipeline:
  - log: 
      message: "Last: #{@list.last(vars.names)}"

Output:

Last: Claudia

@list.size(value)

Returns the number of entries in the given list.

Parameter: `value`	A list-type data structure. Can be a collection, list, array, JSON array or a comma separated list for example.
Returns	The length of the given list or `0` in case it is empty, `null` or not a list structure.

Example 1

vars:
  names: "Megan, Sharol, Sabine, Claudia"
pipeline:
  - log: 
      message: "Size: #{@list.size(vars.names)}"

Output:

Size: 4

@list.sublist(value, expression)

Returns a sublist from value based on the given expression.

Parameter: value

A list-type data structure. Can be a collection, list, array, JSON array or a comma separated list for example.

Parameter: expression

An expression which defines the sublist to return. Possible values are:

last - Returns the last element of the list.
first - Returns the first element of the list.
START:END - Returns a new sublist from START index (inclusive) up to END index (inclusive).
START: - Returns a new sublist from START index (inclusive) up to the end of the list.
:END - Returns a new sublist from 0 up to given END index (inclusive).

Returns

The sublist as described by the expression or null in case value is null, is not a list structure or expression is not valid.

Example 1

vars:
  names: "Megan, Sharol, Sabine, Claudia"
pipeline:
  - log: 
      message: "Result: #{@list.sublist(var.names, 'last')}"

Output:

Result: Claudia

Example 2

vars:
  names: "Megan, Sharol, Sabine, Claudia"
pipeline:
  - log: 
      message: "Result: #{@list.sublist(var.names, '1:2')}"

Output:

Result: Sharol, Sabine

Example 3

vars:
  names: "Megan, Sharol, Sabine, Claudia"
pipeline:
  - log: 
      message: "Result: #{@list.sublist(var.names, ':2')}"

Output:

Result: Megan, Sharol, Sabine

Example 4

vars:
  names: "Megan, Sharol, Sabine, Claudia"
pipeline:
  - log: 
      message: "Result: #{@list.sublist(var.names, '2:')}"

Output:

Result: Sabine, Claudia

@path

The util helps to create and change paths.

@path.basename(path)

Returns the base name of a path or filename without extension.

Parameter: path

The path string. For example /foo/bar/file.txt

Returns

The basename of the path which is the filename without any extension. Examples:

/foo/bar/file → file
/foo/bar/file.txt → file
/foo/bar/ → ““
file.txt → file