4.4.4.4. Understanding functions

Functions are used in formulas to calculate the wanted output starting from your input fields.

Introduction

A function is an operation that takes values as input (the parameters), and computes an output value (the result). Functions can be written for any calculation you can think of. They will be identified by their name, and you have to know which settings they expect to be able to call them.

A function can be called in a formula by just typing the function name, an opening parentheses, the settings (separated by commas), and a closing parentheses. You can find some examples below :

max((3,5)) - 5
min((3,5)) - 3
lower-case('BABELWAY') - 'babelway'
concat('First ', 'example')  - 'First example'
string-length('Babelway') - 8
changeDateTimeFormat('2022-01-31', 'yyyy-MM-dd', 'yyyyMMdd') - '20220131

Function elements

The Babelway online help will give you immediate access to all elements that describe the function.

Function elements

1. The function name identifies the function. It is what you have to write before the opening parenthesis to call this function.

2. The library just indicates the provenance of this method. It can be one of the following :

   • XSL : This function is just standard XSL. If you know XSL, it is exactly the function that you know. Also, every help you can find on the Internet about this function is valid.

   • Babelway : This function is a Babelway-specific extension to xsl. You have to read the Babelway online help to know about this function, or call our support if you need more info.

   • User : This function has been defined by you, in the context of this mapping. You can freely update or delete it, according to your needs.

3. The description describes what the function does, and what it is intended for.

4. The result description describes the value that is returned by the function, including its type (see following section for more information about types).

5. The parameters section shows all information about the parameters of the function.

   1. The name of the parameter. It is just one word that should make you understand the parameter.

   2. The field for the value for this parameter. You can type the value into this field.

   3. More help about the parameter. You have to select the parameter for which you want to see this help. Help starts again with the function name.

   4. Type of the parameters (see following section for more information about types), and indication if this parameter is mandatory (the default) or not.

   5. More info to help you understand this parameter, and how you have to fill it.

6. The examples show you some function calls to the function, with the result. It should clarify how the function works.

Parameter types.

In every function, the parameters and the return type are typed objects (a string, a number, ...).

The reason for this is that functions can not operate on any parameter, but have requirements on them to be able to operate. As an example, a function that would multiply its parameters will require that the parameters are numbers. It will be able to calculate 3*5, but not 3 * 'abc'.

The type of the parameters summarizes most of the constraints on the parameters. It will also allow to detect immediately that the function can not work, because the parameter types are not the expected ones.

The following types are used in the functions of the mapping editor.

• String. It is the most basic type. It is just a sequence of characters, without any more constraint. When you write a String constant into an xpath expression, you have to enclose it with single quotes. Ex : 'abc', 'string example'. Also, all the fields coming from your source document are Strings. You can therefore just drag-and-drop them when you need a String parameter.

• Integer. An integer is a number without decimals, like 2 or 17 (but not 3.5). When you write an Integer constant into an xpath expression, it must be written as is, without enclosing it with a delimiter. Ex : max(3, 5)

• Boolean. A Boolean either true or false. When you write a Boolean constant into a xpath expression, it must be written as is, without enclosing it with a delimiter. Ex : true()

• Number. A number can contain any numeric value, like 2 or 3.5 . The best way to get a Number value from its representation is to use the function toNumber. Ex: toNumber('3.5'). You can also write Numbers directly in your xpath expressions, without enclosing quotes. Ex: 3.5 .

• DateTime. A date is an instant, like '02/06/2017 13:25:17.645'. As for Dates, you can not directly write DateTime constants in an xpath expression. They can only be returned by other functions, like currentDateTime(), or parseDateTime(representation, format)

• DateTimeFormat. A DateTimeFormat is a String that is used to represent the format of a DateTime. Besides being a String, it must comply to the same requirements as DateFormat, that are fully described in http://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html. Some examples are 'yyyy-MM-dd hh:mm:ss', or 'ddMMyyhhmm'.

• LookupTable. A LookupTable parameter must refer to an existing LookupTable in your environment. You can write a reference to a LookupTable directly in a formula by writing a string constant containing the name (or the id) of the lookup table ('stocks', 'clients', ...). In the Easy Function Editor, you can just choose your table in a dropdown menu.

• LookupTableColumn. A LookupTableColumn parameter must refer to a column of a specific LookupTable. You can write a reference to a LookupTableColumn directly in a formula by writing a string constant containing the name (or the index) of the column ('name', 'code', ...). In the Easy Function Editor, you can just choose your column in a dropdown menu.
  Note : The first two columns in the Lookuptable are indexed by design (default query of the interface is doing a full scan), which means searching for a value in first two columns are faster than the other columns. So, it's better if you have keys or identifiers to keep them on first two columns for faster search.

• Node. A single xml element. This type will be used to represent a single xml node from your source document or from an additional xml source. To complete it, you should drag-and-drop a simple node to the field or use an xpath expression referring to a single Node.

• NodeList. A list of xml elements. This type will be used to represent a list of nodes in your source document. In the Easy Function Editor, you can just choose your column in a dropdown menu.g-and-drop a loop node to the field.

• Object. Object is a special value meaning that anything is accepted. You can use Strings, Integers, Dates, ...

To illustrate the importance of types, take a deeper look to the differences between the functions changeDateTimeFormat and formatDateTime. changeDateTimeFormat will take the input date as a String. But it doesn't contain enough information to interpret it as a DateTime. Therefore, it also takes another parameter that is the format of this representation.

changeDateTimeFormat('2022-01-31', 'yyyy-MM-dd', 'yyyyMMdd')

formatDateTime will take the input date by just taking one DateTime parameter.

formatDateTime(currentDateTime(), 'yyyyMMdd')
formatDateTime(parseDateTime('2022-01-31', 'yyyy-MM-dd'), 'yyyyMMdd')

If you just want to change the format of a date contained in one of your source fields, changeDateTimeFormat seems to be exactly the ideal method. But passing by the DateTime objects will just be easier (and for many cases the only way) if you need to make more complex calculations.

formatDateTime(addDays(currentDateTime(), 7), 'yyyyMMdd')

In any case, you have to realize that the following calls would just be WRONG :

formatDateTime('2022-01-31', 'yyyyMMdd')    // formatDateTime expects a DateTime as first parameter, not a String.
changeDateTimeFormat(currentDate(), 'yyyy-MM-dd', 'yyyyMMdd')     // changeDateTimeFormat expects a String as first parameter, not a DateTime.