Functions

From PresenceWiki
Revision as of 16:55, 13 August 2015 by Rob (Talk | contribs)

Jump to: navigation, search

Contents

Index of Functions

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

Boolean Functions

&equalsString{VAL1, VAL2}

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

&equalsString{"ABC","ABC"}
Returns true
&equalsString{"ABC","BC"}
Returns false


&if{VALUE, 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

&onDemand{taskAlias, parameter+}

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:

${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.

&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

&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)

&currentDate{"MMM/yyyy"}
Returns Aug/2015
&currentDate{"dd/MM/yyyy"}
Returns 13/08/2015 or whatever the current date is.
&currentDate{"dd/MM/yyyy",-5}
Returns 08/08/2015 (minus 5 days from the current date)
&currentDate{"dd/MM/yyyy",-3M}
Returns 13/05/2015 (minus 3 months from the current date)
&currentDate{"dd/MM/YYYY",5}
Returns 18/08/2015 (plus 5 days from the current date)
&formatDate{DATE_VALUE, input format, output format}

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

&formatDate{"2015-08-13","yyyy-MM-dd","dd/MM/yyyy"}
Returns 13/08/2015
&formatDate{"2015-08-13","yyyy-MM-dd","E dd MMM YYYY"}
Returns Thu 13 Aug 2015
&formatDate{"2015-08-13","yyyy-MM-dd","dd/MM/yyyy",5}
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
&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.

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

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.

&calcDateIgnoreWeekends{DATE, FORMAT, TIMEADJUST, IGNOREWEEKENDS}

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.

&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

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
&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 datatable 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

&calcTimezoneDifferenceHours{TIMEZONE}

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

Example, if system running in GMT:

&calcTimezoneDifferenceHours{"EST"}

Will return -5 (ie GMT-5).

&currentTime{TIMEFORMAT}

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.

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

Examples assume current time is 15:30:00 PM

&currentTime{"HH:mm:ss"}
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)
&currentTimeStamp{"OPTIONAL"}

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

&dateInMillis{DATE,FORMAT}

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

&dateInMillis{"01/01/2001", "dd/MM/yyyy"}
Returns 978307200000
&formatMilliseconds
&formatMilliseconds{"978307200000", "dd/MM/yyyy"}
Returns 01/01/2001
&formatMilliseconds{"0", "dd MMM yyyy"}
Returns the epoch date "01 Jan 1970"
&formatTF400Date{DATE, RETURN FORMAT}

Formats a TF400 date numeric in the format specified.

TF400 dates are a LONG type in the following format:

HHmmssyyyyMMdd

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
&millisToDate{MILLISECONDS,DATE FORMAT}

Coverts the milliseconds parameter to a formatted date string

&millisToDate{"978307200000", "yyyy-MM-dd'T'HH:mm:ss.SSSZ"}
Returns 2001-01-01T00:00:00.000+0000
&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
&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"
&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

&updateXLCell{PATH,SHEET INDEX,ROW,CELL,VALUE}

Updates a specified cell in an Excel worksheet.

Parameters:

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

&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

&extractTextFromPdf{FILE}

Extracts text from a searchable PDF file.

Useage: &extractTextFromPdf {"FILE_LOCATION"}

&fileExists{FILE LOCATION}

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

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

&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"}

&lookupMimeByExtention

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

&lookupMimeByExtension{".pdf"}
Returns application/octet-stream
&measureImage{IMAGE FILE}

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

Returns a string of the format:

width=n,height=n

&setFileValue{FILE,KEY,VALUE}

Sets a value in a INI or Properties type file.

Returns success string

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

&touchFile{FILE}

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

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

HTML Utitlity Functions

&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!"}
Returns
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
&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.

&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

&JSONToXML{JSON STRING}

Converts a JSON format document into XML. Place the JSON 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:

&JSONToXML{"${jsondata}"}
Returns
<menu><id>file</id><popup><menuitem><value>New</value><onclick>CreateNewDoc()</onclick></menuitem><menuitem><value>Open</value><onclick>OpenDoc()</onclick></menuitem>

<menuitem><value>Close</value><onclick>CloseDoc()</onclick></menuitem></popup><value>File</value></menu>

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"