9.7. Expression Functions

Overview

9.7.1. Functions for API calls

HTTPRequest

Do an HTTP request, return the response content as a string

Arguments

  • Argument 1 (String) : Endpoint ID
  • Argument 2 (String) : Query URL
  • method (String) [Optional, GET] : Query method (“GET” or “POST”)
  • params (Any) [Optional, {}] : Query parameters (Dict or JSON-string)
  • data (Any) [Optional, {}] : Query data (Dict or string). If it is a Dict, then Content-Type is set to application/json in the headers.
  • headers (Any) [Optional, {}] : Query headers (Dict or JSON-string)

HTTPRequestFull

Do an HTTP request, return a dict containing response content and headers

Arguments

  • Argument 1 (String) : Endpoint ID
  • Argument 2 (String) : Query URL
  • method (String) [Optional, GET] : Query method (“GET” or “POST”)
  • params (Any) [Optional, {}] : Query parameters (Dict or JSON-string)
  • data (Any) [Optional, {}] : Query data (Dict or string). If it is a Dict, then Content-Type is set to application/json in the headers.
  • headers (Any) [Optional, {}] : Query headers (Dict or JSON-string)

URLEncode

Encodes a URI (or URL) using percent-encoding

Arguments

  • Argument 1 (String) : URI
  • plus (Boolean) [Optional, False] : Encode spaces as plus signs
  • exclude (String) [Optional, ] : Don’t encode the characters in this string

URLDecode

Decodes a percent-encoded URI (or URL)

Arguments

  • Argument 1 (String) : URI
  • plus (Boolean) [Optional, False] : Decode plus signs as spaces

9.7.2. General

Min

Return the smallest item of two arguments.

Arguments

  • Argument 1 (Numerical) : First source number
  • Argument 2 (Numerical) : Second source number

Max

Return the largest item of two arguments.

Arguments

  • Argument 1 (Numerical) : First source number
  • Argument 2 (Numerical) : Second source number

Round

Return the floating point value number rounded to n digits after the decimal point.

Arguments

  • Argument 1 (Numerical) : Source number
  • Argument 2 (Numerical) : Number of digits

Float

Return a floating point number constructed from a number or string.

Arguments

  • Argument 1 (Simple) : Source number or string

Int

Return an integer number constructed from a number or string.

Arguments

  • Argument 1 (Numerical) : Source number

Str

Return a string containing a nicely printable representation of an object.

Arguments

  • Argument 1 (Simple) : Source object

Len

Return the length (the number of items) of an object.

Arguments

  • Argument 1 (String) : Source string

9.7.3. Date Manipulations

IsoDater

Outputs an ISO date for the given string and format.

Arguments

SmartIsoDater

Outputs an ISO date for the given year month day.

Arguments

  • Argument 1 (String) : Year
  • Argument 2 (String) : Month
  • Argument 3 (String) : Day

GetDuration

Input two date strings in yyyy-mm-dd (%Y-%m-%d) format. Returns duration between given dates in days.

Arguments

  • Argument 1 (String) : Most recent date, in yyyy-mm-dd (%Y-%m-%d) format
  • Argument 2 (String) : Oldest date, in yyyy-mm-dd (%Y-%m-%d) format

DateTimeToTimeStamp

Transforms a UTC date string or date-time string to the number of seconds since 1970-01-01.

Arguments

  • Argument 1 (String) : date in yyyy-mm-dd (%Y-%m-%d) format or date-time in yyyy-mm-ddThh:mm:ss (%Y-%m-%dT%H:%M:%S) format

TimeStampToDateTime

Transforms a number (the number of seconds since 1970-01-01) to a UTC date-time string in yyyy-mm-ddThh:mm:ss (%Y-%m-%dT%H:%M:%S) format.

Arguments

  • Argument 1 (Numerical) : number of seconds since 1970-01-01

DateGetCurrent

Outputs the current date (read from the server machine clock) in ISO format.

Arguments

9.7.4. Dict Manipulations

DictHasKey

Determines whether a dict contain a specific key

Arguments

  • Argument 1 (Dict) : Dictionary
  • Argument 2 (String) : String value to find

DictTranslate

Translates input based on a given dict.

Arguments

  • Argument 1 (String) : Key to translate
  • Argument 2 (Dict) : Translation dictionary

DictGet

Gets the value for a given key or none if not in dict.

Arguments

  • Argument 1 (Dict) : Source dictionary
  • Argument 2 (String) : Key to get value for
  • default (Any) [Optional, None] : Default value in case the key was not found

DictSet

Sets the value for a given key in a dict, and returns that value.

Arguments

  • Argument 1 (Dict) : Dictionary
  • Argument 2 (String) : Key to set value for
  • Argument 3 (Any) : Value to set
  • ignore_null (Boolean) [Optional, False] : Do not set the key-value pair in case either the key or the value are null

DictIncrCount

Convenience function for dicts used as counters. Presumes values are integers.If the given key is present, increases the associated value with 1; otherwise sets the value to 1. It returns the new count.

Arguments

  • Argument 1 (Dict) : Dictionary
  • Argument 2 (String) : Key that you want to count

DictKeys

Returns a list containing all the keys of a dict.

Arguments

  • Argument 1 (Dict) : Source dictionary

DictValues

Returns a list containing all the values of a dict.

Arguments

  • Argument 1 (Dict) : Source dictionary

DictClear

Removes every key/value from a dict.

Arguments

  • Argument 1 (Dict) : Source dictionary

DictTranslateList

Translates all elements of a list based on a given dict.

Arguments

  • Argument 1 (List) : List to translate
  • Argument 2 (Dict) : Translation dictionary

DictBuildTableLookup

Converts two lists to a table lookup dict, where the elements of the first list are usedas keys, and the elements of the second list are used to build lists attached tothe corresponding keys.

Arguments

  • Argument 1 (List) : List with keys
  • Argument 2 (List) : List with values

9.7.5. Geographical Object Creation and Manipulation

LatLonToGeo

Converts latitude and longitude in a geographical object.

Arguments

  • Argument 1 (String) : Latitude
  • Argument 2 (String) : Longitude

ExtractLocationPath

*Converts the first identifier of a given type into a geographical object.

Deprecated since version 6.80: This function is deprecated in favour of ExtractLocationPaths, and may be removed in the future. It silently ignores some inputs, which is not obvious from the function signature.*

Arguments

  • Argument 1 (String) : Input type
  • Argument 2 (List) : A list of identifiers

ExtractLocationPaths

Converts a list of identifiers of a given type into multiple geographical objects.

Arguments

  • Argument 1 (String) : Input type
  • Argument 2 (List) : A list of identifiers

9.7.6. Grammar Parsing

GrParse

Applies a grammar on a text string.

Arguments

  • Argument 1 (String) : Text
  • Argument 2 (Grammar) : Grammar definition

GrMultiParse

Applies a grammar on a text string.

Arguments

  • Argument 1 (String) : Text
  • Argument 2 (Grammar) : Grammar definition

GrValidate

Determines whether or not a text satisfies a grammar.

Arguments

  • Argument 1 (String) : Text
  • Argument 2 (Grammar) : Grammar definition

GrGetMatchList

Returns a list of matches from a grammar parsed string by specifying a dot-separated rules path.

Arguments

  • Argument 1 (Any) : Grammar parsed string
  • Argument 2 (String) : Rules path

GrGetMatch

Returns a single match from a grammar parsed string by specifying a dot-separated rules path.This function requires no more than one match to be present.

Arguments

  • Argument 1 (Any) : Grammar parsed string
  • Argument 2 (String) : Rules path

9.7.7. List Iteration

Map

Maps a list to a new list, applying an expression to each element.

Arguments

  • Argument 1 (List) : Source list
  • Argument 2 (Identifier) : List iterator identifier
  • Argument 3 (Expression) : Expression to be evaluated for each element
  • filter (Expression) [Optional, None] : Filter expression
  • ignore_null (Boolean) [Optional, True] : Do not add null values to the list

Reduce

Aggregates a list to a single element.

Arguments

  • Argument 1 (List) : Source list
  • Argument 2 (Any) : Aggregator initial value
  • Argument 3 (Identifier) : Aggregator identifier
  • Argument 4 (Identifier) : List iterator identifier
  • Argument 5 (Expression) : Expression to be evaluated for each element
  • filter (Expression) [Optional, None] : Filter expression

Find

Returns the first element in a list for which an expression evaluates to True, or null in case no such element was found.

Arguments

  • Argument 1 (List) : Source list
  • Argument 2 (Identifier) : List iterator identifier
  • Argument 3 (Expression) : Find expression to be evaluated for each element
  • required (Boolean) [Optional, False] : Require presence of match
  • unique (Boolean) [Optional, False] : Require unique match

9.7.8. List manipulations

ListSize

Returns the number of elements in a list.

Arguments

  • Argument 1 (List) : Source list

ListNotEmpty

Determines whether a list has at least one element.

Arguments

  • Argument 1 (List) : Source list

ListEmpty

Determines whether a list has no elements.

Arguments

  • Argument 1 (List) : Source list

ListContains

Determines whether a list contains a specific element.

Arguments

  • Argument 1 (List) : Source list
  • Argument 2 (Any) : Element to find

ListDistinct

Returns the unique elements in a list.

Arguments

  • Argument 1 (List) : Source list

ListSort

Returns sorted elements of the input list.

Arguments

  • Argument 1 (List) : Source list

ListIntersection

Returns the elements common in two lists.

Arguments

  • Argument 1 (List) : Source list 1
  • Argument 2 (List) : Source list 2

ListSymmetricDifference

Returns the elements not in common to two lists.

Arguments

  • Argument 1 (List) : Source list 1
  • Argument 2 (List) : Source list 2

ListUnion

Returns the merged set of elements from two lists.

Arguments

  • Argument 1 (List) : Source list 1
  • Argument 2 (List) : Source list 2

ListAppend

Returns a list appended with the given element.

Arguments

  • Argument 1 (List) : Source list
  • Argument 2 (Any) : Element to append

ListConvert2Val

Converts all elements of a list to numerical values.

Arguments

  • Argument 1 (List) : Source list

ListMax

Returns the maximum value from a list.

Arguments

  • Argument 1 (List) : Source list

ListMin

Returns the minimum value from a list.

Arguments

  • Argument 1 (List) : Source list

ListSum

Returns the sum of all values from the list.

Arguments

  • Argument 1 (List) : Source list

ListMean

Returns the mean of all values from the list.

Arguments

  • Argument 1 (List) : Source list

ListJoin

Returns a string that is the join of the elements in the list, separated by a delimiter.

Arguments

  • Argument 1 (List) : Source List
  • Argument 2 (String) : Delimiter

ListGet

Returns the element form the list at the given index.

Arguments

  • Argument 1 (List) : Source List
  • Argument 2 (Integer) : Index

ListGetIndex

Returns the index for the given element in a list.

Arguments

  • Argument 1 (List) : Source List
  • Argument 2 (Any) : Value to be found

ListGetFirstElem

Returns the first element form the list, or a default value if the list is empty.

Arguments

  • Argument 1 (List) : Source List
  • require_singleton (Boolean) [Optional, False] : Requires the list to contain exactly one element
  • default (Any) [Optional, None] : Value to return if the list is empty

ListFlatten

In case a list contains elements that are lists, returns a flattened list with all elements.

Arguments

  • Argument 1 (List) : Source List

ListTranspose

For a list containing lists, performs a matrix transposition (i.e. swaps the first and second dimension).

Arguments

  • Argument 1 (List) : Source List

ListRange

Returns a list of numbers that belong to a specified range.

Arguments

  • Argument 1 (Integer) : Start value
  • Argument 2 (Integer) : Stop value (excluded from the range))
  • step (Integer) [Optional, 1] : Difference between each number

ListRemoveNull

Returns a new list with all null elements removed from the source list.

Arguments

  • Argument 1 (List) : Source List

ListReverse

Returns a new list with all elements in reverse order.

Arguments

  • Argument 1 (List) : Source List

ListGetHead

Returns a new list containing the first N elements of the source list.

Arguments

  • Argument 1 (List) : Source List
  • Argument 2 (Integer) : Number of head elements to return

ListRemoveHead

Returns a new list with the first N elements removed.

Arguments

  • Argument 1 (List) : Source List
  • Argument 2 (Integer) : Number of head elements to remove

ListGetTail

Returns a new list containing the last N elements of the source list.

Arguments

  • Argument 1 (List) : Source List
  • Argument 2 (Integer) : Number of tail elements to return

ListRemoveTail

Returns a new list with the last N elements removed.

Arguments

  • Argument 1 (List) : Source List
  • Argument 2 (Integer) : Number of tail elements to remove

9.7.9. Math Functions

Sqrt

Returns the square root of a number

Arguments

  • Argument 1 (Numerical) : Argument

Log

Returns the logarithm of a number

Arguments

  • Argument 1 (Numerical) : Argument
  • base (Numerical) [Optional, None] : Base of the logarithm (default is natural logarithm, base e)

9.7.10. Misc Functions

FillNull

Returns a default value in case the first argument is null, else returns the first argument.

Arguments

  • Argument 1 (Any) : Argument to test for null value
  • default (Any) [Optional, ] : Return value in case of null value

GetBinnedIntervalString

Returns a string representation of the interval a number belongs to (note that the number is binned in the higher interval if it equals an interval boundary).

Arguments

  • Argument 1 (List) : Interval boundaries list, ordered smallest to largest
  • Argument 2 (Numerical) : Number to be binned

IsInteger

Checks if value is castable to int.

Arguments

  • Argument 1 (String) : String to test for castability

IsFloat

Checks if value is castable to float.

Arguments

  • Argument 1 (String) : String to test for castability

Error

Stops the evaluation of the expression and sets an error condition.

Arguments

  • Argument 1 (String) : Message
  • condition (Boolean) [Optional, True] : Boolean value that must be True in order to set the error

GenerateUUID

Generates a random UUID (Universally Unique Identifier, see RFC 4122).

Arguments

JSONToStr

Encodes an object as a JSON string.

Arguments

  • Argument 1 (Any) : The object (bool/int/float/str/list/dict)

9.7.11. String Regular Expressions

ReSearch

Returns the first match of a regular expression pattern, or null if not found.

Arguments

  • Argument 1 (String) : Target string
  • Argument 2 (String) : Regular expression pattern
  • case_sensitive (Boolean) [Optional, True] : Case sensitive pattern match

ReSearchAll

Returns a list with all matches of a regular expression pattern.

Arguments

  • Argument 1 (String) : Target string
  • Argument 2 (String) : Regular expression pattern
  • case_sensitive (Boolean) [Optional, True] : Case sensitive pattern match

ReSplit

Splits a string into a list of tokens using a regular expression pattern as separator.

Arguments

  • Argument 1 (String) : Target string
  • Argument 2 (String) : Regular expression pattern
  • max_split (Integer) [Optional, None] : Maximum number of splits
  • case_sensitive (Boolean) [Optional, True] : Case sensitive pattern match

ReReplace

Replaces all occurrences of a regular expression pattern with a new string.

Arguments

  • Argument 1 (String) : Target string
  • Argument 2 (String) : Regular expression pattern
  • Argument 3 (String) : Replacement string
  • max_count (Integer) [Optional, None] : Maximum number of replacements
  • case_sensitive (Boolean) [Optional, True] : Case sensitive pattern match

ReReplaceExpr

Replaces all occurrences of a regular expression pattern with a new string, by evaluating an expression for each occurrence.

Arguments

  • Argument 1 (String) : Target string
  • Argument 2 (String) : Regular expression pattern
  • Argument 3 (Identifier) : Match identifier
  • Argument 4 (Expression) : Expression to be evaluated for each occurrence (should use the match identifier)
  • max_count (Integer) [Optional, None] : Maximum number of replacements
  • case_sensitive (Boolean) [Optional, True] : Case sensitive pattern match

ReSearchNamedGroups

Returns named group matches, structured as (?P<name>…), as a dict.

Arguments

  • Argument 1 (String) : Target string
  • Argument 2 (String) : Regular expression pattern
  • case_sensitive (Boolean) [Optional, True] : Case sensitive pattern match

9.7.12. String Manipulations

StrSubstring

Returns a fixed part of a string.

Arguments

  • Argument 1 (String) : Source string
  • Argument 2 (Integer) : Start position
  • Argument 3 (Integer) : Stop position

StrFind

Returns the position of the first occurrence of a search string, and -1 if absent.

Arguments

  • Argument 1 (String) : Source string
  • Argument 2 (String) : Search string
  • case_sensitive (Boolean) [Optional, True] : Case sensitive
  • start_pos (Integer) [Optional, 0] : Start position

StrContains

Determines if a substring is present in a target string.

Arguments

  • Argument 1 (String) : Source string
  • Argument 2 (String) : Search string
  • case_sensitive (Boolean) [Optional, True] : Case sensitive

StrStarts

Determines if a substring is present at the start of a target string.

Arguments

  • Argument 1 (String) : Source string
  • Argument 2 (String) : Search string
  • case_sensitive (Boolean) [Optional, True] : Case sensitive

StrEnds

Determines if a substring is present at the end of a target string.

Arguments

  • Argument 1 (String) : Source string
  • Argument 2 (String) : Search string
  • case_sensitive (Boolean) [Optional, True] : Case sensitive

StrSplit

Splits a string into separate elements according to a delimiter.

Arguments

  • Argument 1 (String) : Source string
  • Argument 2 (String) : Delimiter; specify null or the empty string to split on whitespace
  • maxsplit (Integer) [Optional, -1] : If maxsplit is given, at most maxsplit splits are done (thus, the list will have at most maxsplit+1 elements)

StrSplitAndStrip

Splits a string into separate elements according to a delimiter, and strips whitespace from the resulting elements. Removes empty elements.

Arguments

  • Argument 1 (String) : Source string
  • Argument 2 (String) : Delimiter

StrLower

Converts a string to lower case.

Arguments

  • Argument 1 (String) : Source string

StrBefore

Returns string before the first occurrence of a substring, and null if the substring is not present.

Arguments

  • Argument 1 (String) : Source string
  • Argument 2 (String) : Substring

StrAfter

Returns string after the first occurrence of a substring, and null if the substring is not present.

Arguments

  • Argument 1 (String) : Source string
  • Argument 2 (String) : Substring

StrUpper

Converts a string to upper case.

Arguments

  • Argument 1 (String) : Source string

StrTitle

Returns string with all the first letters of each word upper case and the other letters lower case.

Arguments

  • Argument 1 (String) : Source string

StrCapitalize

Returns string with all the first letters Upper case and the rest lower case.

Arguments

  • Argument 1 (String) : Source string

StrStrip

Returns a string with leading and trailing characters removed.

Arguments

  • Argument 1 (String) : Source string
  • removable_chars (String) [Optional, None] : Characters to be stripped; by default any whitespace
  • leading_only (Boolean) [Optional, False] : Only remove leading characters
  • trailing_only (Boolean) [Optional, False] : Only remove trailing characters

StrRepeat

Returns a string that repeats a provided string a fixed number of times.

Arguments

  • Argument 1 (String) : Source string
  • Argument 2 (Integer) : Repeat count

StrReplace

Returns a string in which all occurrences of a given substring have been replaced.

Arguments

  • Argument 1 (String) : Source string
  • Argument 2 (String) : Old substring
  • Argument 3 (String) : Replacement substring

StrFormat

Interpolates tokens in a string using a dict lookup.

Arguments

  • Argument 1 (String) : Source string
  • Argument 2 (Dict) : Dict with interpolation values

StrIsNumeric

Determines if a string is numeric, returns boolean.

Arguments

  • Argument 1 (String) : Source string

StrZFill

Pads a string with zeros on the left side until it reaches a preset length.

Arguments

  • Argument 1 (String) : Source string
  • Argument 2 (Integer) : Final padded length

StrUriEncode

Encodes a string to a valid URI.

Arguments

  • Argument 1 (String) : Source string
  • ontoforce_encoding (Boolean) [Optional, False] : Use ONTOFORCE encoding

StrParseJSON

Decodes a JSON encoded string to an object.

Arguments

  • Argument 1 (String) : The JSON encoded string

StrHash

Hashes a string into a fixed size hexadecimal string.

Arguments

  • Argument 1 (String) : Source string

9.7.13. Tree Utility Functions

CreateTreePath

Combine and encode a list of labels + uris as one value that defines a “tree”.

Arguments

  • Argument 1 (List) : List of labels
  • uris (List) [Optional, None] : List of URI’s corresponding to the labels
  • prefix (String) [Optional, None] : The prefix to use when building a uri from a label (if no uris are passed)

CreatePersonPath

Build a ‘tree path’ from a normalized person name (using ontoforce encoding) and encode the path as single value.

Arguments

  • Argument 1 (String) : Normalized name
  • uri (String) [Optional, ] : A URI identifying this person
  • prefix (String) [Optional, http://ns.ontoforce.com/person/] : The prefix to use when building a uri from a label (if no uri is passed)

9.7.14. XML Parsing

XmlGetText

Returns list of all the text parts for the supplied tag.

Arguments

  • Argument 1 (String) : Xml Node in string form
  • Argument 2 (String) : XPath to the node

XmlGetTextFirst

Returns the first matching text element for the supplied tag.

Arguments

  • Argument 1 (String) : Xml Node in string form
  • Argument 2 (String) : XPath to the node

XmlHasText

Returns True if a node with text is found and False if not.

Arguments

  • Argument 1 (String) : Xml Node in string form
  • Argument 2 (String) : XPath to the node

XmlSubNode

Returns a list of string formatted xml sub nodes with the given XPath.

Arguments

  • Argument 1 (String) : Xml Node in string form
  • Argument 2 (String) : XPath to the node
  • ignore_tails (Boolean) [Optional, False] : If a matching node has a tail (trailing text outside the node),specify whether or not to include it in the result

XmlHasSubNode

Returns True if a sub node is found and False if not.

Arguments

  • Argument 1 (String) : Xml Node in string form
  • Argument 2 (String) : XPath to the node

XmlGetAttribute

Returns a list of values for the supplied Attribute.

Arguments

  • Argument 1 (String) : Xml Node in string form
  • Argument 2 (String) : XPath to the node
  • Argument 3 (String) : Attribute name
  • required (Boolean) [Optional, True] : Specifies whether the presence of the attribute is required

XmlGetSingleAttribute

Returns an attribute that is found no more than once.

Arguments

  • Argument 1 (String) : Xml Node in string form
  • Argument 2 (String) : XPath to the node
  • Argument 3 (String) : Attribute name
  • required (Boolean) [Optional, True] : Specifies whether the presence of the attribute is required

XmlHasAttribute

Returns True if a value for the given attribute is found and False if not.

Arguments

  • Argument 1 (String) : List of Xml Node in string form
  • Argument 2 (String) : XPath to the node
  • Argument 3 (String) : Attribute name

XmlIterText

Loops over the given xml tag and its sub tags and returns all text parts.

Arguments

  • Argument 1 (String) : Xml Node in string form
  • Argument 2 (String) : XPath to the node
  • Argument 3 (String) : Delimiter to join on

XmlToFlatText

Converts XML to flat text removing all tags, with an optional list of rules determining how specific tag content should be converted.Each rule is a dictionary containing the following elements: - One of: - tag: the name of the tag - xpath: xpath identifying the target elements - (Optional) prefix: text to insert at the start of content of matching elements - (Optional) postfix: text to append to the end of the content of matching elements - (Optional) remove: if True, remove the matching elements

Arguments

  • Argument 1 (String) : Source XML
  • Argument 2 (List) : Set of rules
  • parse_html (Boolean) [Optional, False] : Parse as HTML rather than XML