Difference between revisions of "Functions"

From PresenceWiki
Jump to: navigation, search
(File Operations)
(Encrypt File)
Line 427: Line 427:
Parameter 4: the key to use for encryption see above for valid key lengths
Parameter 4: the key to use for encryption see above for valid key lengths
=====Decrypt File=====
=====Decrypt File=====

Revision as of 07:47, 3 September 2015


About Presence Functions

Functions can be used almost anywhere a Presence Text Area is used, you know if you are in a Presence Text Area by Pressing CTRL+Space. Almost all Presence Functions will accept Presence Variables in the form of ${variable_name}, you can also embed other functions into functions e.g &round{"&random{"${maxval}"}"} would return a rounded integer rather than a double/float based on the value of the ${maxval} variable.

It is always a good idea to place quotes around any parameters within the function unless it is a numeric function that only accepts whole numbers, doing this helps to ensure the parser can recognise the start and end of the data.

Anybody can create their own Presence Functions, for more information see Function Call.

Testing Presence Functions

You can test functions using the Function Test Console

Index of Functions

This list aims to be a comprehensive list of default functions available with Presence. Please note that it is always a work in progress.

Boolean Functions

Equals String

Format: &equalsString{Paramter,Parameter}

This function compares String1 and String2. If they are equal it will return the value "true". Otherwise it will return "false".

Returns true
Returns false
If Boolean Test

Format: &if{Boolean Param To Test, True Result, False Result}

This function performs a test on a string. If it equals "true" or "1" the value of Parameter 2 will be returned. Otherwise, value of Parameter 3 will be returned.

&if{"true", "I AM TRUE", "I AM FALSE"}
Returns "I AM TRUE"
&if{"0", "I AM TRUE", "I AM FALSE"}
Returns "I AM FALSE"

Data Functions

On Demand Task Call

Format: &onDemand{taskAlias, parameter+,parameter+,param...}

Calls an On Demand Task that is on the Live Task Queue.

taskAlias: The alias of the Task to be called, the task should be on the Live Tasks Queue #On Demand Processes

parameter+ : The Parameters to be passed (zero or more).

&onDemand{"myTask","id=5", "now=true"}

Calls the Task referenced by the alias "myTask" and sets the following variables in the target task:

${id} = 5 ${now} = true

If the task returns a magic ${response} variable that value will be populated in the variable or space you are calling the function from.

Does Column Exist On Data Table

Format: &doesColumnExist{"COL_NAME"}

Tests to see if the specified column name exists in the current Data table - returns "true" if it does or "false" if not.

Parameter 1: The column name to test

Date Functions

All date functions use format patterns defined below, these date/time format patterns are based on Java Simple Date Format, for more information see http://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html

Date and Time Patterns

G Era designator e.g. "AD"

y Year e.g. yyyy="2015"; yy="15"

M Month in year e.g. M="8" (August); MM="08"; MMM="Aug" MMMM="August"

w Week in year e.g. w="33" (13/August/2015)

W Week in month e.g. W="2" (13/August/2015)

D Day in year e.g. D="225" (13/August/2015)

d Day in month e.g d="13" (13/August/2015)

F Day of week in month

E Day in week e.g. E="Thu"

a Am/pm marker

H Hour in day (0-23)

h Hour in day (1-12)

m Minute in hour

s Second in minute

S Millisecond

z Time zone e.g. z="BST"; zzzz="British Summer Time"

Z Time zone (RFC 822 time zone) e.g Z="+0100"

X Time zone (ISO 8601 time zone) e.g X="+01"; XX="+0100"; XXX="+01:00"

Get Current Date

Format: &currentDate{format, offset}

Returns: the current date in the format specified by the first parameter.

format=The date format to use to format the current date (e.g. "dd/MM/yyyy"). See #Date and Time Patterns

offset=(Optional) The offset in days (e.g. -1, 1, 2, -5)

Returns Aug/2015
Returns 13/08/2015 or whatever the current date is.
Returns 08/08/2015 (minus 5 days from the current date)
Returns 13/05/2015 (minus 3 months from the current date)
Returns 18/08/2015 (plus 5 days from the current date)
Format Date

Format: &formatDate{DATE_VALUE, input_format, output_format}

Returns: a new format for a date passed into the function on parameter 1

Returns 13/08/2015
&formatDate{"2015-08-13","yyyy-MM-dd","E dd MMM YYYY"}
Returns Thu 13 Aug 2015
Returns 13/08/2015 (adds 5 days to the date on parameter 1)
&formatDate{"2015-08-13","yyyy-MM-dd","EEEE dd MMM YYYY"}
Returns Thursday 13 Aug 2015
Adjust Time Zone

Format: &adjustTimeZone{Date_in_originating_timezone,Format_of_date_in_param_1, Originating_timezone, Resulting_timezone, Resulting_date_format (OPTIONAL)}

This function adjusts a given date from the source timezone to another timezone. For example, an event happens in San Fransisco at 03:00 AM but the time needs to be displayed in London, which would be 11:00 AM.

&adjustTimeZone{"2013-08-02 03:00", "yyyy-MM-dd HH:mm", "US/Pacific", "Europe/London"}
Returns 2013-08-02 11:00

There is an optional 5th parameter which is the format to be used when creating the string that is returned. If it is omitted then the format specified in the 2nd parameter is used.

Calculate Date Ignoring Weekends


Using the start date DATE, formatted according to rules specified in FORMAT, add the number of days* specified in TIMEADJUST. IGNOREWEEKENDS should be set to "true" if weekends are ignored - in which case, if weekend days are encountered while adding minutes, skip to Monday.

Therefore if IGNOREWEEKENDS = true: Wednesday 22nd June 2011 @ 12:00 + 5 days = Wednesday 29th June 2011 @ 12:00

TIMEADJUST defaults to days, however other time periods can be specified by appending a letter, e.g.:

5000S = 5000 milliseconds

60s = 60 seconds

60m = 60 minutes

24H = 24 hours

1M = 1 month

1y = 1 year

Note that for months and years the IGNOREWEEKENDS attribute will be discarded - weekends will never be taken into account.

Calculate Runtime Basic

Format: &calcNextRuntimeFromBasic{Run_on_First_of_Month, Run_on_Last_of_Month, Run_On_Date, Run_Time(HH:mm)}

Gets Next Runtime From Date in milliseconds, only valid in a running task - can't be tested

The parameters for this are retrieved from the top info of the schedule info page. ie, Run on First of Month string (true/false) Run on Last of Month string (true/false) Run On Date string (1-31) Run Time (HH:MM) string

&calcNextRuntimeFromBasic{"true", "false", "0", "09:00"}
Returns 1441094400000
Calulate Runtime From Day

Format: &calcNextRuntimeFromDay{Run_on_First_of_Month, Run_on_Last_of_Month, Run_On_Date, Run_Time(HH:mm)}

Get Next Runtime From Day(s)

The parameters for this are retrieved from the bottom of the schedule info page.

This uses the context, so the data table should contain the following:-

Integer "DAYOFWEEK" 1-Sunday 2=Monday etc Integer "FREQUENCY" 0=Every, 1=First, 2=Last Integer "INTERVALMINUTES" eg 30 String "STARTTIME" eg 09:00 String "ENDTIME" eg 13:00

Calculate Timezone Difference Hours

Format: &calcTimezoneDifferenceHours{TIMEZONE}

Calculates the time difference between the system timezone and the specified timezone, returns difference in hours.

Example, if system running in GMT:


Will return -5 (ie GMT-5).

Current Time

Format: &currentTime{TIMEFORMAT}

Returns: the current time in the format specified by the first parameter, offset by the number of minutes in the second parameter (default is zero).

Parameter 1: The time format to use to format the current time (eg "HH:mm:ss" for 24 hour, "h:mm:ss a" for 12 hour + am/pm). Parameter 2: (Optional) The offset in minutes.

Examples assume current time is 15:30:00 PM

Returns (eg) "15:30:00"
&currentTime{"HH:mm", -60}
Returns "14:30" (60 minutes in the past)
&currentTime{"h.mm a", 30}
Returns "4.00 PM" (half an hour in the future)
Current Time Stamp

Format: &currentTimeStamp{"OPTIONAL"}

Returns: the current time in milliseconds, offset by the number of minutes in the parameter (default is zero).

Date In Milliseconds

Format: &dateInMillis{DATE,FORMAT}

Converts a given date into milliseconds from the 1970s epoch.

&dateInMillis{"01/01/2001", "dd/MM/yyyy"}
Returns 978307200000
Format Milliseconds

Format: &formatMilliseconds{MILLISECONDS,FORMAT}

Returns a millisecond date in a readable format specified.

&formatMilliseconds{"978307200000", "dd/MM/yyyy"}
Returns 01/01/2001
&formatMilliseconds{"0", "dd MMM yyyy"}
Returns the epoch date "01 Jan 1970"
Format TF400 Date

Format: &formatTF400Date{DATE, RETURN_FORMAT}

Formats a TF400 date numeric in the format specified.

TF400 dates are a LONG type in the following format:


They may be 13 or 14 digits depending on whether the hour part is before 12 PM.

This function prepends a trailing zero if necessary and returns the date as a String in the format specified.

&formatTF400Date{"9342220130325", "dd MMM yyyy 'at' HH:mm:ss"}
Returns 25 Mar 2013 at 09:34:22
Milliseconds To Date


Coverts the milliseconds parameter to a formatted date string, same as #Format Milliseconds, retained for backwards compatibility

&millisToDate{"978307200000", "yyyy-MM-dd'T'HH:mm:ss.SSSZ"}
Returns 2001-01-01T00:00:00.000+0000
Parse Seven Digit Date

Format: &parseSevenDigitDate{DATE,NEW FORMAT}

Attempts to parse the seven digit date set in parameter 1. If this is successful, the function will then reformat the date in the date specified by parameter 2.

- Parameter 1: The seven-digit date to parse (eg "1032403") - Parameter 2: The Java date format to use for formatting. Eg "dd-MM-yyyy".

&parseSevenDigitDate{"1150101", "dd-MM-yyyy"}
Returns 01-01-2015
Seven Digit Date

Format: &sevenDigitFormat{DATE,FORMAT OF DATE}

Creates a seven digit string representation of the specified date, where the first character represents the century, ie 0 for years ending in 47-99 and 1 for years ending in 00-46.

Complete format is CYYMMDD.

Parameter 1: The date string to be parsed and reformatted Parameter 2: The date format to use in parsing the input date.

 &sevenDigitFormat{"23 Mar 2003", "dd MMM yyyy"}
Returns "1030323"
Validate Date

Format: &validatedate{DATE,FORMAT OF DATE, CHECK FUTURE} Pass it a date string and a date format.

Returns 1 if valid, else 0.

Can also pass it a true to check that the date is not in the future.

Excel Functions

Update Excel Cell


Updates a specified cell in an Excel worksheet.


1: Path of Excel file 2: Sheet index (zero based) 3: Row number (zero based) 4: Cell number (zero based) 5: New value

Returns the old value.

File Operations

Add files To Zip

Format: &addfilesToZip{DIR,ZIP FILE}

Creates a zip archive.

Argument #1: The directory containing files to be added to the archive Argument #2: The target zip file name.

Files are added recursively, ie subdirectory contents are also added. If the target zip file already exists it will be renamed to [old_file_name].yyyymmdd

Extract Text from PDF File

Format: &extractTextFromPdf{FILE}

Extracts text from a searchable PDF file. Some PDF files may not actually contain text even though it looks that way, instead you may get an embedded scanned image and this function will not be able to read a scanned image as text.

Useage: &extractTextFromPdf {"FILE_LOCATION"}

Does File Exist

Format: &fileExists{FILE LOCATION}

Tests whether the specified file exists. If the file exists the function returns "TRUE", otherwise returns "FALSE".

File Length

Format: &fileLength{"FILE_LOCATION"}

Returns the length of the specified file, or -1 if it doesn't exist or if the path specified is a folder.

Get File Value

Format: &getFileValue{FILE,KEY}

Gets a value from a INI or Properties type file.

Returns a String for the Key value specified in Parmeter2

Example: &getFileValue{"c:\myfile.ini","MYKEY"}

See also : #Set File Value

Lookup MIME Type By Extension

Format: &lookupMimeByExtention{"FILENAME_OR_EXTENSION"}

Attempts to retrieve the MIME type for the file name specifies. Uses the Java MimetypesFileTypeMap so is incomplete.

Returns application/octet-stream
Measure Image

Format: &measureImage{IMAGE_FILE}

Measures the width and height of image file specified in arg 1.

Returns a string of the format:


Set File Value

Format: &setFileValue{FILE,KEY,VALUE}

Sets a value in a INI or Properties type file.

Returns success string

Example: &setFileValue{"c:\myfile.ini","MYKEY", "MYVALUE"}

See also : #Get File Value

Touch File

Format: &touchFile{FILE}

Sets the last modified date of the file in parameter 1 to be the current system time.

Unzip File

Format: &unzip{ZIP,TO FOLDER}

Unzips the archive specified in argument #1 into the directory specified in argument #2.

Example: unzip{"/archive.zip", "/extracted/"}

Extracts the archive "/archive.zip" into the directory "/extracted". If the directory does not already exist it will be created at runtime.

Encrypt File

Format: &fileEncrypt{"/path/file.ext","/path/new_encrypted_file.enc","algorithm","key"}

The file encrypt function provides simple accessibility to common cryptography requirements. The supported algorithms are as follows:

Parameter 1: the location of the file to be encrypted

Parameter 2: the location of the newly created encrypted file.

Parameter 3: the Algorithm:

  • AES (from 16 to 32 chars key length)
  • ARCFOUR (from 8 to 32 chars key length)
  • BLOWFISH (from 4 to 56 chars key length)
  • DES (8 chars key length)
  • DESEDE (8, 16 24 chars key length)
  • RC2 (variable upto 128 chars key length)

Parameter 4: the key to use for encryption see above for valid key lengths

Decrypt File

Format: &fileDecrypt{"/path/encrypted_file.enc","/path/decrypted_file.ext","algorithm","key"}

The file decrypt function provides simple accessibility to common cryptography requirements. The supported algorithms are as follows:

Parameter 1: the location of the file to be encrypted

Parameter 2: the location of the newly created encrypted file.

Parameter 3: the Algorithm:

  • AES (from 16 to 32 chars key length)
  • ARCFOUR (from 8 to 32 chars key length)
  • BLOWFISH (from 4 to 56 chars key length)
  • DES (8 chars key length)
  • DESEDE (8, 16 or 24 chars key length)
  • RC2 (variable upto 128 chars key length)

Parameter 4: the key to use for decryption see above for valid key lengths

HTML Utitlity Functions

HTML Encode

Format: &htmlEncode{HTML STRING}

Encodes a string of HTML, replacing any non-alphanumerics with their entity reference equivalent.

&htmlEncode{"I was wondering & found a £1 coin!"}
I was wondering &-a-m-p-; found a &-p-o-u-n-d-;1 coin&-#-3-3-; *Dashes inserted to explain, actual function does not insert dashes

URL Decode

Format: &urlDecode{URLEncodedText}

Utility function for HTML form decoding. Decodes a String from the application/x-www-form-urlencoded MIME format.

To conversion process is the reverse of that used by the urlEncode{} function. It is assumed that all characters in the encoded string are one of the following: "a" through "z", "A" through "Z", "0" through "9", and "-", "_", ".", and "*". The character "%" is allowed but is interpreted as the start of a special escaped sequence.

URL Encode

Format: &urlEncode{STING_TO_ENCODE}

Utility function for HTML form encoding. Converts a String to the application/x-www-form-urlencoded MIME format.

When encoding a String, the following rules apply:

The alphanumeric characters "a" through "z", "A" through "Z" and "0" through "9" remain the same.

The special characters ".", "-", "*", and "_" remain the same.

The space character " " is converted into a plus sign "+".

All other characters are unsafe and are first converted into one or more bytes using some encoding scheme. Then each byte is represented by the 3-character string "%xy", where xy is the two-digit hexadecimal representation of the byte.

The recommended encoding scheme to use is UTF-8. However, for compatibility reasons, if an encoding is not specified, then the default encoding of the platform is used.

JSON Functions

The following functions do basic operations on JSON formats, to parse a JSON format into a data table use the JSON Node to create JSON formats then you would use the Custom Data Formatter Standard Option.



Converts a JSON format document into XML. Place the JSON string into a variable first, this will place it into an effective CDATA section Create a Varible called ${jsondata} and populated the JSON data into it.

e.g. ${jsondata} would contain
{"menu": {
  "id": "file",
  "value": "File",
  "popup": {
    "menuitem": [
      {"value": "New", "onclick": "CreateNewDoc()"},
      {"value": "Open", "onclick": "OpenDoc()"},
      {"value": "Close", "onclick": "CloseDoc()"}

So you then call the function:





Converts an XML document into JSON format.

Parameter 1: XML document

{"menu": {
"id": "file",
"popup": {"menuitem": [
  "value": "New",
  "onclick": "CreateNewDoc()"
  "value": "Open",
  "onclick": "OpenDoc()"
  "value": "Close",
  "onclick": "CloseDoc()"
"value": "File"

Miscellaneous Functions

Inspect Context

Format: &inspectContext{CONTEXT_VALUE}

Inspects the current Presence Context and returns the value of the property specified in the first parameter. The property can be a dot separated list of objects and properties, for example, some common usages may be:

data.empty - returns true if the data table is empty, or false otherwise

data.rowCount - returns the number of rows in the current data table

taskMode - returns the current mode of the task as a number (see Presence Context)

container.topLeveltask.taskName - the name of the currently running (top level) task

container.nestedTask.taskName - the name of the currently running (nested) task

If an asterisk is specified instead of a property name, all of the available properties will be returned as a comma-separated list. For example:

Returns all available properties for the context data table
Returns all available properties for the context (includes data and container).

Is Null


Tests if first parameter is null (empty) and returns second parameter if it is. Otherwise returns first parameter.

&isNull{"", "it was null"}
Returns "it was null"
&isNull{"i'm here!", "it was null"}
Returns "i'm here!".
Read AS400 Data Area


Reads a data area on the IBM Midrange iSeries/AS400 and Returns the value.

Tiff Page Count

Format: &TiffPageCount{TIFFBYTES}

Determines the number of pages in the tiff image passed to the function.

Parameter 1: The Tiff image ByteArray

Returns: the number of pages in the TIFF supplied.


Format: &contains{FIND_STING, SEARCH_STRING}

Check to see if a string contains another string. both are converted to lowercase. if the string is found then the starting position of that string is returned otherwise false is returned.

Convert TIFF to PNG


Converts a TIFF stream into a PNG stream.

Parameter 1: The byte array variable of the entire TIFF Parameter 2: Scale (1 = full size) Parameter 3: Page number

Format Duration

Format: &formatDuration{DURATION}

Formats a duration (specified in seconds or minutes) as hours, minutes and seconds.

Duration Examples:

8273s = 02:17:53

149s = 00:02:29

228m = 03:48:00

60m = 01:00:00

Format Excel Date

Format: &formatXlsDate{DATE, CENT}

Formats a date from a non standard date string to dd/MM/yyyy

First parameter is the date

Second parameter is the century

e.g. 12/2/07 becomes 12/02/2007

Also if the year is first it will swap it around.

FTP Delete

Format: ftpDelete{RESOURCEID,PATH}

Deletes a file from an FTP server

Param 1: The Unique ID of the FTP resource

Param 2: The Path of the file to be deleted

You can find out the resource ID of the FPT server resource by using a SQL on the Presence Internal Database.



Logs on to James admin server, sends a command and returns the response.


Format: &md5{STRING}

Creates a MD5 Hash from a string

&md5{"my string here but it will be much longer than the hash, this type of hash is widely used for sending secrete keys"}
Returns "292be0ab57c86dea40d449d0a5f504de"
iSeries/AS400 Command


Calls a program on an AS400 / iSeries as it is now known.


parm 1 = System Host Name or IP address

parm 2 = User ID

parm 3 = Password

parm 4 = Cmd to call e.g call pgm(qgpl/myclpgm)

parm 5 = Ignore program errors ("true" or "false")

parm 6-99 string values for the parmeters.

e.g. &AS400CMD{"MYAS400","userid","password","call pgm(QGPL/MYCL)","false"} will call the program without passing any parameters

&AS400CMD{"MYAS400","userid","password","call pgm(QGPL/MYCL)","false",":VAR{ORDERID}",":VAR{QUANTITY}",":VAR{PRODUCT}"} will call the program for each row in the data table, with values from a previous presence query.

Numeric Functions

Byte String

Format: &byteString{BYTE}

This converts Presence's internal byte storage mechanism into the correct format for external applications. Specifically, 128 is subtracted from the value of each byte. Function cannot be tested, will only work during runtime


Format: &divide{VAL1,VAL2}

Divides 1st parameter by 2nd parameter and returns the result.

Returns 2.

Format: &eval{EXPRESSION}

Evaluates the expression in argument 1 and returns the logical result.

Returns 70
Returns 45
Returns 3

eval also supports the following functions:

  • varr
  • var
  • trunc
  • tanh
  • tan
  • sum
  • stddev
  • sqrt
  • sinh
  • sin
  • sign
  • sech
  • sec
  • round
  • random
  • rad
  • pow
  • permr
  • perm
  • min
  • max
  • log2
  • log10
  • log
  • hypot
  • frac
  • floor
  • fact
  • exp2
  • exp10
  • exp
  • deg
  • cur
  • csch
  • csc
  • count
  • coth
  • cot
  • cos
  • combr
  • comb
  • ceil
  • avg
  • atanh
  • atan2
  • atan
  • asinh
  • asin
  • asech
  • asec
  • acsch
  • acoth
  • acot
  • acosh
  • acos
  • abs

The following constants are supported:

  • TB = 1099511627776L
  • STEFAN_BOLTZMANN = 5.6704E-8
  • SPEED_OF_LIGHT = 299792458
  • RYDBERG = 10973731.568549
  • PYTHAGORAS = Math.sqrt(2)
  • PROTON_MASS =1.67262158E-27
  • PLANCK = 6.62606876E-34
  • PI = Math.PI
  • NEWTON =6.673E-11
  • MOLAR_GAS = 8.314472
  • MIN_INT = Integer.MIN_VALUE
  • MIN_DEC = Double.MAX_VALUE
  • MB = 1048576
  • MAX_INT = Integer.MAX_VALUE
  • MAX_DEC = Double.MAX_VALUE
  • MAGNETIC_FLUX = 2.067833636E-15
  • MAGNETIC = 4E-7 * Math.PI
  • MADELUNG = 2.0531987328
  • KHINTCHINE = 2.685452001
  • KB = 1024
  • INVERSE_FINE_STRUCTURE = 137.03599976
  • IMAGINARY_UNIT = Math.sqrt(-1)
  • GRAVITY = 9.80665
  • GB = 1073741824
  • FINE_STRUCTURE = 7.297352533E-3
  • FEIGENBAUM = 2.50290787509589282228390287272909
  • FARADAY = 96485.3415
  • EULER = 0.57721566490153286060651209008240243104215933593992
  • ELEMENTARY_CHARGE = 1.602176462E-19
  • ELECTRON_VOLT = 1.602176462E-19
  • ELECTRON_MASS = 9.10938188E-31
  • ELECTRIC_CONSTANT = 8.854187817E-12
  • E = Math.E
  • CONDUCTANCE_QUANTUM = 7.748091696E-5
  • CATALAN = 0.915965594
  • BOLTZMANN = 1.3806503E-23
  • AVOGADRO = 6.02214199E+23
  • ATOMIC_MASS = 1.66053873E-27
  • APERY = 1.20205690315959428539973816151144999076498629234049

Hex Value

Format: &hexVal{NUMBER}

Returns the hexidecimal value of the number passed in parameter 1.

Returns FF

Format: &multiply{VAL+}

Multiplies all parameters and returns the result.

Returns 40

Format: &percent{PERCENTAGE,VALUE}

Returns the first argument expressed as a percentage of the second.

Returns 50

Format: &random{MAX}

Returns a random number between zero and the argument specified

Could Return 49.21655577700601

Format: &round{NUMBER}

Round the parameter to the nearest whole number. See java.lang.Math.round(double) for contract.

Returns an integer representing the rounded value.

Returns 6

Format: &subtract{VAL1,VAL2}

Subtracts argument 2 from argument 1 and returns the result.

Returns 25

Format: &sum{VAL+}

Adds all the parameters and returns the result.

Returns 4802

Presence Internal Functions

Current Task Name

Format: &currentTaskName{}

Returns the current task name. No parameters required.

Print Functions

PDF Print


Returns either Printed,Failed to print or throws an error


1:PDF File

2:Printer UNC


4:Page-From:- 1 = first page

5:Page-To:- -1 = all

6:Throw Errors:-'True'=On failure, errors will be thrown back to the task 'False'=On failure the result will be 'Failed', but the task will continue

7:Duplex printing 'True' or 'False' (optional,default is false)

8:Short Edge Binding 'True' or 'False' (optional,default is false) applies with duplex printing

Security Functions

Validate Windows User And Password


Validates windows user and password details are valid using Windows Acitve Directory and Fast Binding.

returns string 'true' or 'false', throws an error on failure.


1:Username domain\User 2:Password 3:LDAP url 4:Factory class

&ValidateWindowsUserAndPassword{"mydomain\robert", "password", "ldap://adserver:389", "com.sun.jndi.ldap.LdapCtxFactory"}
Returns false as this is not the correct password.
Create SHA Hash

Format: &createSHAHash{VALUE,ITERATIONS}

A secure one-way hash function that converts the input value into a fixed length hash value, using an SHA (secure hash algorithm) digest.

The original input value can never be retrieved from the hash value. This is useful for storing passwords etc, where the original value never needs to be known but the hashed value can be compared for correctness.

Parameter 1: Input value Parameter 2: Number of iterations to use (optional, default 1)

&createSHAHash{"Input Value"}
Returns a4c9cbd6e25fd7ae420dbe02ecf40785fb89099c
&createSHAHash{"Input Value",3}
Returns a9676f44e0ae8b65c393a1463e97d20552b93d33

Format: &decrypt{ENCRYPTED TEXT, KEY(optional)}

Decrypts the encrypted value specified to provide the original text value. Uses the Triple DES algorithm and a key that is unique to your Presence installation.

Parameter 1: An encrypted value Parameter 2 (optional): Encryption key Result: A decrypted value


Format: &encrypt{TEXT TO ENCRYPT, KEY(optional)}

Encrypts the specified value using a triple DES cipher algorithm. The key used is unique to each Presence installation. The resulting value can be decrypted using the decrypt{String} function.

Parameter 1: The string value to be encrypted. Result: An encrypted string, which can only be decrypted on the same Presence installation.

Parameter 2 (optional): A string to use as an encryption key.

String Functions

Chop Text


This function splits a long string of text into two parts, looking for a delimiter near the middle of the string.

The first and second half are placed into variables named in parameters 4 and 5.

&ChopText{"10 Coppergate Mews, 109-111 Brighton Road, Surbiton, Surrey, United Kingdom KT6 5NE", 60, ",", ${test1}, ${test2}}

Returns 41 (chop position), populates ${test1} with "10 Coppergate Mews, 109-111 Brighton Road" and populates ${test2} with "Surbiton, Surrey, United Kingdom KT6" 5NE

Base 64 Decode

Format: &base64decode{BASE64STRING}

Decodes a Base64 String and converts it into a byte array.

Returns "74686520717569636b2062726f776e20666f78206a756d706564206f76657220746865206c617a7920646f67"
Base 64 Encode

Format: &base64encode{BASE64STRING}

Converts the specified byte array (hex) into BASE64, returns the output.

Returns "dGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZWQgb3ZlciB0aGUgbGF6eSBkb2c="
Capitalises Words

Format: &capitaliseWords{STRING}

Capitalises the first letter of each word, where words are expected to be separated by space (" ") characters.

&capitaliseWords{"mr smith"}
Returns "Mr Smith"

Format: &concat{VALS+}

Concatinates any strings passed to the function. Accepts unlimited parameters. Returns a concatinated string.

&concat{"hello ", "how ", "are you","?"}
Returns "hello, how are you?"
Find Text In Line

Format: &findTextInLine{Multiline_Input_String, Regexp_Search, Return Type}

Locates specified text in a line of text in the first parameter.

&findTextInLine{"This is line 1
This is line 2
This is line 3", ".*3", "WHOLE_LINE"}
Returns: "This is line 3"
&findTextInLine{"This is line 1
This is line 2
This is line 3", ".*1", "WHOLE_LINE"}
Returns: "This is line 1"

Third parameter controls what's returned if a match is found:


Fix File Name

Format: &fixFileName{FILENAME}

Converts a filename into something sensible. Any characters other than a-z, A-Z and 0-9 are converted to an underscore (_) except for the last period (i.e. the extension)

 &fixFileName{"a file *&%name.png"}
Returns "a_file____name.png"
Format Number

Format: &formatNumber{NUMBER, FORMAT}

Formats a number specified by parameter 1 in the format specified by parameter 2. Returns the formatted number.

&formatNumber{123456.789, "###,###.###"}
Returns "123,456.789" The hash sign (#) denotes a digit, the comma is a placeholder for the grouping separator, and the period is a placeholder for the decimal separator.
&formatNumber{123456.789, "###.##"}
Returns "123456.79" The value has three digits to the right of the decimal point, but the pattern has only two. The format method handles this by rounding up.
&formatNumber{123.78, "000000.000"}
Returns "000123.780" The pattern specifies leading and trailing zeros, because the 0 character is used instead of the hash sign (#).
&formatNumber{12345.67, "£###,###.###"}
Returns "£12,345.67" The first character in the pattern is the dollar sign ($). Note that it immediately precedes the leftmost digit in the formatted output.
Get Text From HTML(Mark-Up)

Format: &getTExtFromHTML{MARKUP}

Function to remove html tags from a string.

Will also replace <-b-r-> <-p-> <-h1-> etc with a new line *dashes not in real example, used to stop formatting errors

Also replaces:-

&-l-t-; with a < &-g-t-; with a > &-q-u-o-t-; with a " &-a-m-p-; with a & &-n-b-s-p-; with a space *dashes not in real example, used to stop formatting errors

&getTextFromHTML{"<!DOCTYPE html>
<h1>My First Heading</h1>
<p>My first paragraph.</p>
My First Heading

My first paragraph.

Index Of


Given the string specified in the first parameter, returns the index (position) of the string specified in the second parameter. The first character is at position zero and so on. Return value is zero based.

If the string cannot be found -1 is returned.

&indexOf{"text.to.search", "."}
Returns 4
Lower Case

Format: &lowerCase{STRING}

Converts the string entered to lower case.

&lowerCase{"Hello R2D2!"}
Returns "hello r2d2".
Pad Left

Format: &padLeft{STRING}

Left-pads the specified string with the string specified to the length specified.

Parameter 1: The string to pad and measure the length of.

Parameter 2: The string to use for padding.

Parameter 3: The width of the returned string.

&padLeft ("string", ".", 9)
Returns "...string"

Format: &padRight{STRING}

Right-pads the specified string with the string specified to the length specified.

Parameter 1: The string to pad and measure the length of.

Parameter 2: The string to use for padding.

Parameter 3: The width of the returned string.

&padRight ("string", ".", 9)
Returns "string..."
Process String

Format: &processString{STRING}

Parses the string in argument one for function calls, etc. Returns the result.



Replaces occurrence of parameter 2 with parameter 3 in string parameter 1.

&replace{"The quick brown fox jumps over the lazy dog", "fox", "camel"}
Returns "The quick brown camel jumps over the lazy dog"
Replace Pattern


Given the input string in Parameter 1, replaces any occurrences of the pattern specified in parameter 2 with the string in parameter 3. Input patterns follow Java Regular Expression rules - see http://www.regexr.com/ for more information on regex patterns.

&replacePattern{"That costs £15.00", "[a-zA-Z\s£]+", ""}
Returns: "15.00". Replaces any words and the pound sign as well as white spaces.
Split Text In Columns (Actually Rows)


Splits the text specified in argument 1, based on the delimiter specified in argument 2. A new data column is created with the column name specified in argument 3, and the data table is appended with the new column.

Optional parameter 4 specifies the column name to store the position of the item. If omitted, the position is not stored.

&splitTextIntoColumns{"word1;word2;word3", ";", "WORDS", "POSITION"}
Returns "3 new rows created" and the data table at runtime would contain 3 rows and two Columns accessed via :var{WORDS} & :var{POSITION}. A very useful function for dealing with arrays returned from http requests, etc.
Multi Column Text Split

Format: &multiColumnTextSplit{TEXT, DELIMITER, COLNAME1, TEXT, DELIMITER, COLNAME2, [textToSplit, delim, colname] ...}

Splits text in parameter one according to delimiter specified in parameter two and creates a data table column named parameter three. The three paramaters can be repeated indefinitely to create a larger data table.

&multiColumnTextSplit{"word1;word2;word3", ";", "WORDS", "anotherword,anotherword,anotherword",",","COL2"}
Returns "3 new rows created" and the data table at runtime would contain 3 rows and two Columns accessed via :var{WORDS} & :var{COL2}. A very useful function for dealing with arrays returned from http requests, etc.
SQL String

Format: &sqlString{SQL_STRING_TO_CORRECT}

Parses the String to find any single quotes that would upset the database and replaces them with two single quotes as per SQL 92 standard

&sqlString{"Don't do that"}
Returns "Dont do that"
Starts With

Format: &stratsWith{TEXT,CHARS_TO_CHECK}

Tests to see if the string supplied by the first parameter begins with the string specified in the second parameter.


&startsWith{"Foobar", "Foo"}
Returns "true".
&startsWith{"Foobar", "Bar"}
Returns "false".
String Length

Format: &stringLength{STRING}

Returns the number of characters in the specified string.

Parameter 1: The string to measure the length of.

Returns "6".
Sub String

Format: &substring{STRING,START,END}

Returns a substring of the specified string.

Parameter 1: The string to get the substring of.

Parameter 2: The start character (first character being 1)

Parameter 3: The number of characters to retrieve.

Returns "foo".
Text To Binary

Format: &textToBinary{STRING}

Converts the text specified into a byte array, for inserting into a blob etc.

&textToBinary{"The quick brown dog"}
Returns a Byte array with 19 elements.

Format: &trim{STRING}

Trims the string specified by parameter 1, removing any leading or trailing spaces and line breaks.

&trim{"   spaced       "}
Returns "spaced".
Upper Case

Format: &upperCase{STRING}

Converts the string entered to upper case.

&upperCase{"Hello R2D2!"}
Returns "HELLO R2D2!".


Wraps text at a specified position


Parameter 1 = The text to wrap Parameter 2= true or false for wrap on word Parameter 3= Max number of Chars for a single line

&wrap{"The quick brown fox jumps over the lazy dog, he doesn't stop to say hello.", "false", "30"}
The quick brown fox jumps over

the lazy dog, he doesn't stop

to say hello.

Data Table Functions

Add Running Total

Format: &addRunningTotal{IN_COLUMN, OUT_COLUMN}

Keeps a running total of a column of numbers and sets an additional column to be the current total. eg: 0 1 2 0 1 2 3


0 1 2 2 3 4 5

Create Pivot Table


Creates a pivot table (see http://en.wikipedia.org/wiki/Pivot_table) based on the current Data Table.

ROWFIELD: This is the field which is used as the first column. COLUMNFIELD: Additional columns are created for each value of this field. FACTFIELD: The values of the columns are setting according to this field's values. AGGREGATION_METHOD: Where multiple values exist, this is the method that should be used to generate one unique value. Possible options are:

- SUM - the total sum of the values - COUNT - the count of values - MEAN - the arithmetic mean of the values - STD_DEV - the standard deviation of the values - RETAIN - only uses the first value found - REPLACE - uses the last value found

VARIABLE_NAME: (Optional) - if specified, the resulting data table will be stored in this variable rather than replacing the existing data table.

Append Row IDs

Format: &appendRowIds{COL_NAME(Optional)}

Appends a new column to the data table with a unique ID for each row of data, numbered from 1 to n where n is the number of records.

An optional argument can be provided to identify the column name to use. If this is ommitted a default column name of "PRESENCE_ROW_ID" is used.

If the column already exists it will be updated to reflect the current record positions.