This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

XSLT Functions

A reference of all custom XSLT functions available in Stroom.

1: Conversion Functions
2: Date/Time Functions
3: Network Functions
4: Other Functions
5: Stroom Pipeline Functions
6: String Functions
7: URI/URL Functions
8: Value Functions
9:

Stroom has a number of built in custom XSLT functions that can be called from within the XSLTFilter pipeline element. These functions provide additional capabilities and access to data held in Stroom.

Using Stroom XSLT Functions

To use a Stroom custom XSLT function you need to add the xmlns:stroom="stroom" namespace declaration to the XSLT document. The convention is to use the namespace prefix stroom to make it clear that function calls are to a Stroom built-in function, but any prefix can be used.

<xsl:stylesheet
  version="2.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:stroom="stroom"
  xmlns="event-logging:3"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  ...>

The following is an example of calling the hash custom XSLT function to produce a hash of the username value.

  <xsl:template match="/record">
    <HashedUser>
      <xsl:value-of select="stroom:hash(data[@name='username']/@value, 'SHA-256')"/>
    </HashedUser>
  </xsl:template>

Return Values

XSLT functions can return the following data types:

Boolean - True/false.
Date - A date value (xs:date).
Date-Time - A date and time value (xs:datetime).
Decimal - A decimal or floating point value (xs:decimal).
Integer - A number with no decimal part (xs:integer).
String - A simple string value (xs:string).
Sequence - Any sequence of nodes or atomic values, e.g. a single node, a list of nodes or a list of strings.

Functions

The following table lists all the Stroom XSLT functions.

Function	Category
`add-meta()`	Pipeline
`ask-ai()`	Other
`bitmap-lookup()`	Pipeline
`cidr-to-numeric-ip-range()`	Network
`classification()`	Pipeline
`col-from()`	Pipeline
`col-to()`	Pipeline
`cosine-similarity()`	Other
`current-time()`	Date
`current-unixTime()`	Date
`current-user()`	Value
`decode-url()`	URI
`dictionary()`	Pipeline
`encode-url()`	URI
`feed-attribute()`	Pipeline
`feed-name()`	Pipeline
`fetch-json()`	Network
`format-date()`	Date
`format-dateTime()`	Date
`from-unixTime()`	Date
`get()`	Pipeline
`hash()`	Conversion
`hex-to-dec()`	Conversion
`hex-to-oct()`	Conversion
`hex-to-string()`	Conversion
`host-address()`	Network
`host-name()`	Network
`http-call()`	Network
`ip-in-cidr()`	Network
`json-to-xml()`	Conversion
`line-from()`	Pipeline
`line-to()`	Pipeline
`link()`	String
`log()`	Pipeline
`lookup()`	Pipeline
`manifest()`	Pipeline
`manifest-for-id()`	Pipeline
`meta()`	Pipeline
`meta-attribute()`	Pipeline
`meta-keys()`	Pipeline
`meta-stream()`	Pipeline
`meta-stream-for-id()`	Pipeline
`numeric-ip()`	Network
`parent-for-id()`	Pipeline
`parent-id()`	Pipeline
`parse-dateTime()`	Date
`parse-uri()`	URI
`part-no()`	Pipeline
`pipeline-name()`	Pipeline
`pointIsInsideXYPolygon()`	Other
`put()`	Pipeline
`random()`	Value
`random-integer()`	Value
`record-no()`	Pipeline
`search-id()`	Pipeline
`send-email()`	Other
`source()`	Pipeline
`source-id()`	Pipeline
`split-document()`	Other
`stream-id()`	Pipeline
`to-unixTime()`	Date

1 - Conversion Functions

Functions for converting a value from one form to another, e.g. hexToString.

`hash`

hash(value, [algorithm], [salt])➡String

Generates a hash of the supplied value using the named hash algorithm. The SHA-256 algorithm will be used if not supplied.

You can optionally supply a salt value to prepend to the hash.

Function Arguments:

Param	Type	Default Value	Allowed Values	Min Count	Description
`value`	String	-	-	-	The value to hash.
`algorithm`	String	`SHA-256`	`MD5`, `SHA`, `SHA-224`, `SHA-256`, `SHA-384`, `SHA-512`	-	The name of the hash algorithm to use.
`salt`	String	-	-	-	The salt to use as input to the hashing function. The salt will be hashed first followed by the value.

Return Value:

Type	Description
String	The hash of the value

`hex-to-dec`

hex-to-dec(hex)➡String

Converts a hexadecimal value to its decimal representation.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`hex`	String		-	-		-	The hexadecimal value to convert.

Return Value:

Type	Description
String	The decimal representation, or an empty sequence if conversion fails.

`hex-to-oct`

hex-to-oct(hex)➡String

Converts a hexadecimal value to its octal representation.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`hex`	String		-	-		-	The hexadecimal value to convert.

Return Value:

Type	Description
String	The octal representation, or an empty sequence if conversion fails.

`hex-to-string`

hex-to-string(hex, charset)➡String

Decodes hexadecimal bytes to text using the specified character set. Whitespace in the hexadecimal input is ignored.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`hex`	String		-	-		-	The hexadecimal bytes to decode.
`charset`	String		-	-		-	The character set name, such as `UTF-8`.

Return Value:

Type	Description
String	The decoded text, or an empty sequence if decoding fails.

Example

XSLT:

<string><xsl:value-of select="stroom:hex-to-string('74 65 73 74 69 6e 67 20 31 32 33', 'UTF-8')" /></string>

XML:

<string>testing 123</string>

`json-to-xml`

json-to-xml(json)➡Sequence

Converts JSON text to XML nodes for use in XPath expressions.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`json`	String		-	-		-	The JSON text to convert.

Return Value:

Type	Description
Sequence	The XML representation of the JSON value.

2 - Date/Time Functions

Functions for date/time parsing and manipulation.

`current-time`

current-time()➡String

Returns the current system date and time in Stroom’s standard date-time format.

Return Value:

Type	Description
String	The current date and time.

`current-unixTime`

current-unixTime()➡Integer

Returns the current system time as milliseconds since the Unix epoch.

Return Value:

Type	Description
Integer	The current time in milliseconds since the Unix epoch.

`format-date`

Parses a date and formats it as a string. A single argument is interpreted as milliseconds since the Unix epoch; other forms parse an input pattern and may specify input and output time zones.

format-date(epochMillis)➡String

Formats milliseconds since the Unix epoch in Stroom’s standard date-time format.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`epochMillis`	Integer		-	-		-	The number of milliseconds since the Unix epoch.

Return Value:

Type	Description
String	The formatted date string, or an empty sequence if parsing or formatting fails.

format-date(inputDate, inputPattern, [inputTimeZone])➡String

Parses a date string and returns Stroom’s standard date-time format.

Function Arguments:

Param	Type	Default Value	Allowed Values	Min Count	Description
`inputDate`	String	-	-	-	The date string to parse.
`inputPattern`	String	-	-	-	The pattern describing the input date.
`inputTimeZone`	String	-	-	-	The input time zone; defaults to UTC. `GMT/BST` handles British Summer Time.

Return Value:

Type	Description
String	The formatted date string, or an empty sequence if parsing or formatting fails.

format-date(inputDate, inputPattern, inputTimeZone, outputPattern, [outputTimeZone])➡String

Parses a date string and formats it with a custom output pattern.

Function Arguments:

Param	Type	Default Value	Allowed Values	Min Count	Description
`inputDate`	String	-	-	-	The date string to parse.
`inputPattern`	String	-	-	-	The pattern describing the input date.
`inputTimeZone`	String	-	-	-	The input time zone; defaults to UTC.
`outputPattern`	String	-	-	-	The pattern for the output string.
`outputTimeZone`	String	-	-	-	The output time zone; defaults to UTC.

Return Value:

Type	Description
String	The formatted date string, or an empty sequence if parsing or formatting fails.

Date Formats

For details of date format syntax, as used by the inputPattern and outputPattern arguments, see Custom Date Formats.

Time Zones

The following is a list of some common time zone values:

Values	Zone Name
`GMT/BST`	A Stroom specific value for UK daylight saving time (see below)
`UTC`, `UCT`, `Zulu`, `Universal`, `+00:00`, `-00:00`, `+00`, `+0`	Coordinated Universal Time (UTC)
`GMT`, `GMT0`, `Greenwich`	Greenwich Mean Time (GMT)
`GB`, `GB-Eire`, `Europe/London`	British Time
`NZ`, `Pacific/Auckland`	New Zealand Time
`Australia/Canberra`, `Australia/Sydney`	Eastern Australia Time
`CET`	Central European Time
`EET`	Eastern European Time
`Canada/Atlantic`	Atlantic Time
`Canada/Central`	Central Time
`Canada/Pacific`	Pacific Time
`US/Central`	Central Time
`US/Eastern`	Eastern Time
`US/Mountain`	Mountain Time
`US/Pacific`	Pacific Time
`+02:00`, `+02`, `+2`	UTC +2hrs
`-03:00`, `-03`, `-3`	UTC -3hrs

A special time zone value of GMT/BST can be used when the inputDate is in local wall clock time with time zone information. In this case, the date/time will be used to determine whether the date is in British Summer Time or in GMT and adjust the output accordingly. See the examples below.

Parsing Examples

The following table shows various examples of calls to stroom:format-date() with their output. The stroom:format-date part has been omitted for brevity.

<!-- Date in millis since UNIX epoch -->
stroom:format-date('1269270011640')
-> '2010-03-22T15:00:11.640Z'

<!-- Simple date UK style date -->
stroom:format-date('29/08/24', 'dd/MM/yy')
-> '2024-08-29T00:00:00.000Z'

<!-- Simple date US style date -->
stroom:format-date('08/29/24', 'MM/dd/yy')
-> '2024-08-29T00:00:00.000Z'

<!-- ISO date with no delimiters -->
stroom:format-date('20010801184559', 'yyyyMMddHHmmss')
-> '2001-08-01T18:45:59.000Z'

<!-- Standard output, no TZ -->
stroom:format-date('2001/08/01 18:45:59', 'yyyy/MM/dd HH:mm:ss')
-> '2001-08-01T18:45:59.000Z'

<!-- Standard output, date only, with TZ -->
stroom:format-date('2001/08/01', 'yyyy/MM/dd', '-07:00')
-> '2001-08-01T07:00:00.000Z'

<!-- Standard output, with TZ -->
stroom:format-date('2001/08/01 01:00:00', 'yyyy/MM/dd HH:mm:ss', '-08:00')
-> '2001-08-01T09:00:00.000Z'

<!-- Standard output, with TZ -->
stroom:format-date('2001/08/01 01:00:00', 'yyyy/MM/dd HH:mm:ss', '+01:00')
-> '2001-08-01T00:00:00.000Z'

<!-- Single digit day and month, no padding -->
stroom:format-date('2001 8 1', 'yyyy MM dd')
-> '2001-08-01T00:00:00.000Z'

<!-- Double digit day and month, no padding -->
stroom:format-date('2001 12 28', 'yyyy MM dd')
-> '2001-12-28T00:00:00.000Z'

<!-- Single digit day and month, with optional padding -->
stroom:format-date('2001  8  1', 'yyyy ppMM ppdd')
-> '2001-08-01T00:00:00.000Z'

<!-- Double digit day and month, with optional padding -->
stroom:format-date('2001 12 31', 'yyyy ppMM ppdd')
-> '2001-12-31T00:00:00.000Z'

<!-- With abbreviated day of week month -->
stroom:format-date('Wed Aug 14 2024', 'EEE MMM dd yyyy')
-> '2024-08-14T00:00:00.000Z'

<!-- With long form day of week and month -->
stroom:format-date('Wednesday August 14 2024', 'EEEE MMMM dd yyyy')
-> '2024-08-14T00:00:00.000Z'

<!-- With 12 hour clock, AM -->
stroom:format-date('Wed Aug 14 2024 10:32:58 AM', 'E MMM dd yyyy hh:mm:ss a')
-> '2024-08-14T10:32:58.000Z'

<!-- With 12 hour clock, PM (lower case) -->
stroom:format-date('Wed Aug 14 2024 10:32:58 pm', 'E MMM dd yyyy hh:mm:ss a')
-> '2024-08-14T22:32:58.000Z'

<!-- Using minimal symbols -->
stroom:format-date('2001 12 31 22:58:32.123', 'y M d H:m:s.S')
-> '2001-12-31T22:58:32.123Z'

<!-- Optional time portion, with time -->
stroom:format-date('2001/12/31 22:58:32.123', 'yyyy/MM/dd[ HH:mm:ss.SSS]')
-> '2001-12-31T22:58:32.123Z'

<!-- Optional time portion, without time -->
stroom:format-date('2001/12/31', 'yyyy/MM/dd[ HH:mm:ss.SSS]')
-> '2001-12-31T00:00:00.000Z'

<!-- Optional millis portion, with millis -->
stroom:format-date('2001/12/31 22:58:32.123', 'yyyy/MM/dd HH:mm:ss[.SSS]')
-> '2001-12-31T22:58:32.123Z'

<!-- Optional millis portion, without millis -->
stroom:format-date('2001/12/31 22:58:32', 'yyyy/MM/dd HH:mm:ss[.SSS]')
-> '2001-12-31T22:58:32.000Z'

<!-- Optional millis/nanos portion, with nanos -->
stroom:format-date('2001/12/31 22:58:32.123456', 'yyyy/MM/dd HH:mm:ss[.SSS]')
-> '2001-12-31T22:58:32.123Z'

<!-- Fixed text -->
stroom:format-date('Date: 2001/12/31 Time: 22:58:32.123', ''Date: 'yyyy/MM/dd 'Time: 'HH:mm:ss.SSS')
-> '2001-12-31T22:58:32.123Z'

<!-- GMT/BST date that is BST -->
stroom:format-date('2009/06/01 12:34:11', 'yyyy/MM/dd HH:mm:ss', 'GMT/BST')
-> '2009-06-01T11:34:11.000Z'

<!-- GMT/BST date that is GMT -->
stroom:format-date('2009/02/01 12:34:11', 'yyyy/MM/dd HH:mm:ss', 'GMT/BST')
-> '2009-02-01T12:34:11.000Z'

<!-- Time zone offset -->
stroom:format-date('2009/02/01 12:34:11', 'yyyy/MM/dd HH:mm:ss', '+01:00')
-> '2009-02-01T11:34:11.000Z'

<!-- Named time zone -->
stroom:format-date('2009/02/01 23:34:11', 'yyyy/MM/dd HH:mm:ss', 'US/Eastern')
-> '2009-02-02T04:34:11.000Z'

Note

Parsing is done in lenient mode so, the count of each symbol is not critical, e.g. you can parse the year 2024 with y, yy, yyy or yyyy. Despite this, it is advisable to use a pattern that matches the known format of the input dates, e.g. in this example yyyy, to avoid confusing with anyone else reading your XSLT.

The count of each symbol is however critical when it comes to formatting.

Formatting Examples

<!-- Specific output, no input or output TZ -->
stroom:format-date('2001/08/01 14:30:59', 'yyyy/MM/dd HH:mm:ss', null, 'E dd MMM yyyy HH:mm (s 'secs')')
-> 'Wed 01 Aug 2001 14:30 (59 secs)'

<!-- Specific output, UTC input, no output TZ -->
stroom:format-date('2001/08/01 14:30:59', 'yyyy/MM/dd HH:mm:ss', 'UTC', 'E dd MMM yyyy HH:mm (s 'secs')')
-> 'Wed 01 Aug 2001 14:30 (59 secs)'

<!-- Specific output, no output TZ -->
stroom:format-date('2001/08/01 14:30:59', 'yyyy/MM/dd HH:mm:ss', '+01:00', 'E dd MMM yyyy HH:mm (s 'secs')')
-> 'Wed 01 Aug 2001 13:30 (59 secs)'

<!-- Specific output, with input and output TZ -->
stroom:format-date('2001/08/01 14:30:59', 'yyyy/MM/dd HH:mm:ss', '+01:00', 'E dd MMM yyyy HH:mm', '+02:00')
-> 'Wed 01 Aug 2001 15:30'

<!-- Padded 12 hour clock output -->
stroom:format-date('2001/08/01 14:07:05.123', 'yyyy/MM/dd HH:mm:ss.SSS', 'UTC', 'E dd MMM yyyy pph:ppm:pps a')
-> 'Wed 01 Aug 2001  2: 7: 5 PM'

<!-- Padded 12 hour clock output -->
stroom:format-date('2001/08/01 22:27:25.123', 'yyyy/MM/dd HH:mm:ss.SSS', 'UTC', 'E dd MMM yyyy pph:ppm:pps a')
-> 'Wed 01 Aug 2001 10:27:25 PM'

<!-- Non-Padded 12 hour clock output -->
stroom:format-date('2001/08/01 14:07:05.123', 'yyyy/MM/dd HH:mm:ss.SSS', 'UTC', 'E dd MMM yyyy h:m:s a')
-> 'Wed 01 Aug 2001 2:7:5 PM'

<!-- Long form text -->
stroom:format-date('2001/08/01 14:07:05.123', 'yyyy/MM/dd HH:mm:ss.SSS', 'UTC', 'EEEE d MMMM yyyy HH:mm:ss')
-> 'Wednesday 1 August 2001 14:07:05'

Reference Time

When parsing a date string that does not contain a full zoned date and time, certain assumptions will be made.

If there is no time zone in inputDate and no inputTimeZone argument has been passed then the time zone of the input date will be assumed to be in the UTC time zone.

If any of the date parts are not present, e.g. an input of 28 Oct then Stroom will use a reference date to fill in the gaps. The reference date is the first of these values that is non-null

The create time of the stream being processed by the XSLT.
The current time, i.e. now().

For example for a call of stroom:format-date('28 Oct', 'dd MMM') and a stream create time of 2024, it will return 2024-10-28T00:00:00.000Z.

`format-dateTime`

format-dateTime(dateTime, [pattern], [timeZone])➡String

Formats an XPath date-time value using an optional output pattern and time zone. Without a pattern it uses Stroom’s standard date-time format; the default time zone is UTC.

Function Arguments:

Param	Type	Default Value	Allowed Values	Min Count	Description
`dateTime`	Date-Time	-	-	-	The XPath date-time value to format.
`pattern`	String	-	-	-	The output pattern. Omit for Stroom’s standard date-time format.
`timeZone`	String	-	-	-	The output time zone; defaults to UTC.

Return Value:

Type	Description
String	The formatted date-time string, or an empty sequence if formatting fails.

Date Formats

For details of date format syntax, as used by the pattern argument, see Custom Date Formats.

Examples

<!-- Default format -->
stroom:format-dateTime(xs:dateTime('2024-08-29T00:00:00Z'))
-> '2024-08-29T00:00:00.000Z'

<!-- Default format +2hr zone offset -->
stroom:format-dateTime(xs:dateTime('2001-08-01T18:45:59.123+02:00'))
-> '2001-08-01T16:45:59.123Z'

<!-- Default format +2hr30min zone offset -->
stroom:format-dateTime(xs:dateTime('2001-08-01T18:45:59.123+02:30'))
-> '2001-08-01T16:15:59.123Z'

<!-- Default format -3hr zone offset -->
stroom:format-dateTime(xs:dateTime('2001-08-01T18:45:59.123-03:00'))
-> '2001-08-01T21:45:59.123Z'

<!-- Simple date format UK style date -->
stroom:format-dateTime(xs:dateTime('2024-08-29T00:00:00Z'), 'dd/MM/yy')
-> '29/08/24'

<!-- Simple date format US style date -->
stroom:format-dateTime(xs:dateTime('2024-08-29T00:00:00Z'), 'MM/dd/yy')
-> '08/29/24'

<!-- With no delimiters -->
stroom:format-dateTime(xs:dateTime('2001-08-01T18:45:59Z'), 'yyyyMMddHHmmss')
-> '20010801184559'

<!-- Standard output, no TZ -->
stroom:format-dateTime(xs:dateTime('2001-08-01T18:45:59Z'), 'yyyy/MM/dd HH:mm:ss')
-> '2001/08/01 18:45:59'

<!-- Format with nanos -->
stroom:format-dateTime(xs:dateTime('2010-01-01T23:59:59.123456Z'), 'yyyy-MM-dd'T'HH:mm:ss.SSSSSSXX')
-> '2010-01-01T23:59:59.123456Z'

<!-- Standard output, with TZ -->
stroom:format-dateTime(xs:dateTime('2001-08-01T09:00:00Z'), 'yyyy/MM/dd HH:mm:ss', '-08:00')
-> '2001/08/01 01:00:00'

<!-- Standard output, with TZ -->
stroom:format-dateTime(xs:dateTime('2001-08-01T00:00:00Z'), 'yyyy/MM/dd HH:mm:ss', '+01:00')
-> '2001/08/01 01:00:00'

<!-- GMT/BST date that is BST -->
stroom:format-dateTime(xs:dateTime('2009-06-01T11:34:11Z'), 'yyyy/MM/dd HH:mm:ss', 'GMT/BST')
-> '2009/06/01 12:34:11'

<!-- GMT/BST date that is GMT -->
stroom:format-dateTime(xs:dateTime('2009-02-01T12:34:11Z'), 'yyyy/MM/dd HH:mm:ss', 'GMT/BST')
-> '2009/02/01 12:34:11'

<!-- Named time zone -->
stroom:format-dateTime(xs:dateTime('2009-02-02T04:34:11Z'), 'yyyy/MM/dd HH:mm:ss', 'US/Eastern')
-> '2009/02/01 23:34:11'

`from-unixTime`

from-unixTime(milliseconds)➡Date-Time

Converts milliseconds since the Unix epoch to an XPath date-time value.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`milliseconds`	Integer		-	-		-	Milliseconds since the Unix epoch.

Return Value:

Type	Description
Date-Time	The corresponding date-time value.

`parse-dateTime`

parse-dateTime(inputDate, [pattern], [timeZone])➡Date-Time

Parses a date string to an XPath date-time value. Without a pattern it expects Stroom’s standard date-time format; the default time zone is UTC.

Function Arguments:

Param	Type	Default Value	Allowed Values	Min Count	Description
`inputDate`	String	-	-	-	The date string to parse.
`pattern`	String	-	-	-	Optional input date pattern.
`timeZone`	String	-	-	-	The input time zone; defaults to UTC.

Return Value:

Type	Description
Date-Time	The parsed date-time value, or an empty sequence if parsing fails.

Examples

<!-- ISO 8061 -->
stroom:parse-dateTime('2024-08-29T00:00:00Z')
-> '2024-08-29T00:00:00Z'

<!-- ISO 8061 with nanos -->
stroom:parse-dateTime('2010-01-01T23:59:59.123456Z')
-> '2010-01-01T23:59:59.123456Z'

<!-- ISO 8061 with millis -->
stroom:parse-dateTime('2010-01-01T23:59:59.123Z')
-> '2010-01-01T23:59:59.123Z'

<!-- ISO 8061 Zulu/UTC -->
stroom:parse-dateTime('2001-08-01T18:45:59.123+00:00')
-> '2001-08-01T18:45:59.123Z'

<!-- ISO 8061 +2hr zone offset -->
stroom:parse-dateTime('2001-08-01T18:45:59.123+02')
-> '2001-08-01T16:45:59.123Z'

<!-- ISO 8061 +2hr zone offset -->
stroom:parse-dateTime('2001-08-01T18:45:59.123+02:00')
-> '2001-08-01T16:45:59.123Z'

<!-- ISO 8061 +2hr30min zone offset -->
stroom:parse-dateTime('2001-08-01T18:45:59.123+02:30')
-> '2001-08-01T16:15:59.123Z'

<!-- ISO 8061 -3hr zone offset -->
stroom:parse-dateTime('2001-08-01T18:45:59.123-03:00')
-> '2001-08-01T21:45:59.123Z'

<!-- Simple date UK style date -->
stroom:parse-dateTime('29/08/24', 'dd/MM/yy')
-> '2024-08-29T00:00:00Z'

<!-- Simple date US style date -->
stroom:parse-dateTime('08/29/24', 'MM/dd/yy')
-> '2024-08-29T00:00:00Z'

<!-- ISO date with no delimiters -->
stroom:parse-dateTime('20010801184559', 'yyyyMMddHHmmss')
-> '2001-08-01T18:45:59Z'

<!-- Standard output, no TZ -->
stroom:parse-dateTime('2001/08/01 18:45:59', 'yyyy/MM/dd HH:mm:ss')
-> '2001-08-01T18:45:59Z'

<!-- Standard output, date only, with TZ -->
stroom:parse-dateTime('2001/08/01', 'yyyy/MM/dd', '-07:00')
-> '2001-08-01T07:00:00Z'

<!-- Standard output, with TZ -->
stroom:parse-dateTime('2001/08/01 01:00:00', 'yyyy/MM/dd HH:mm:ss', '-08:00')
-> '2001-08-01T09:00:00Z'

<!-- Standard output, with TZ -->
stroom:parse-dateTime('2001/08/01 01:00:00', 'yyyy/MM/dd HH:mm:ss', '+01:00')
-> '2001-08-01T00:00:00Z'

`to-unixTime`

to-unixTime(dateTime)➡Integer

Converts an XPath date-time value to milliseconds since the Unix epoch.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`dateTime`	Date-Time		-	-		-	The date-time value to convert.

Return Value:

Type	Description
Integer	The corresponding milliseconds since the Unix epoch.

3 - Network Functions

Functions relating to networking (host names, IP addresses, etc.) or making remote calls.

`cidr-to-numeric-ip-range`

cidr-to-numeric-ip-range(cidr)➡Sequence

Converts a CIDR IP address range to an array of numeric IP addresses representing the start and end (broadcast) of the range.

When storing the result in a variable, ensure you indicate the type as a string array (xs:string*).

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`cidr`	String		-	-		-	The CIDR range to convert, for example `192.168.1.0/24`.

Return Value:

Type	Description
Sequence	An array containing the start and end addresses as numeric strings.

Example

XSLT:

<xsl:variable name="range" select="stroom:cidr-to-numeric-ip-range('192.168.1.0/24')" as="xs:string*" />
<Range>
  <Start><xsl:value-of select="$range[1]" /></Start>
  <End><xsl:value-of select="$range[2]" /></End>
</Range>

XML:

<Range>
  <Start>3232235776</Start>
  <End>3232236031</End>
</Range>

`fetch-json`

fetch-json(url, [clientConfig])➡Sequence

Sends an HTTP GET request and converts a JSON response body to XML using json-to-xml(). A 404 response produces an empty sequence.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`url`	String		-	-		-	The URL to fetch.
`clientConfig`	String		-	-		-	Optional JSON HTTP client configuration, including SSL settings.

Return Value:

Type	Description
Sequence	The XML representation of the JSON response, or an empty sequence when no usable response is returned.

`host-address`

host-address(hostname, [ignoreWarnings])➡String

Resolves a host name to an IP address.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`hostname`	String		-	-		-	The host name to resolve.
`ignoreWarnings`	Boolean		-	-		-	Suppress resolution warnings when `true`.

Return Value:

Type	Description
String	The resolved IP address, or an empty sequence if resolution fails.

`host-name`

host-name(ipAddress, [ignoreWarnings])➡String

Resolves an IP address to a host name.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`ipAddress`	String		-	-		-	The IP address to resolve.
`ignoreWarnings`	Boolean		-	-		-	Suppress resolution warnings when `true`.

Return Value:

Type	Description
String	The resolved host name, or an empty sequence if resolution fails.

`http-call`

http-call(url, [headers], [mediaType], [data], [clientConfig])➡Sequence

Sends an HTTP POST request and returns a stroom-http XML response containing the status, headers and body. The request body is optional.

Function Arguments:

Param	Type	Default Value	Allowed Values	Min Count	Description
`url`	String	-	-	-	The URL to request.
`headers`	String	-	-	-	Optional newline-separated HTTP headers in `name:value` form.
`mediaType`	String	`application/json; charset=utf-8`	-	-	The request media type; defaults to `application/json; charset=utf-8`.
`data`	String	-	-	-	Optional request body.
`clientConfig`	String	-	-	-	Optional JSON HTTP client configuration, including SSL settings.

Return Value:

Type	Description
Sequence	An XML response document containing the response or an error.

`clientConfig`

The HTTP client can be configured using the clienConfig argument. This is a JSON object containing various optional configuration items. The following is an example of the client configuration object with all keys populated.

{
  "callTimeout": "PT30S",
  "connectionTimeout": "PT30S",
  "followRedirects": false,
  "followSslRedirects": false,
  "httpProtocols": [
    "http/2",
    "http/1.1"
  ],
  "readTimeout": "PT30S",
  "retryOnConnectionFailure": true,
  "sslConfig": {
    "keyStorePassword": "password",
    "keyStorePath": "/some/path/client.jks",
    "keyStoreType": "JKS",
    "trustStorePassword": "password",
    "trustStorePath": "/some/path/ca.jks",
    "trustStoreType": "JKS",
    "sslProtocol": "TLSv1.2",
    "hostnameVerificationEnabled": false
  },
  "writeTimeout": "PT30S"
}

If you are using two-way SSL then you may need to set the protocol to HTTP/1.1.

  "httpProtocols": [
    "http/1.1"
  ],

Example Output

The following is an example of the XML returned from the http-call function:

<response xmlns="stroom-http">
  <successful>true</successful>
  <code>200</code>
  <message>OK</message>
  <headers>
    <header>
      <key>cache-control</key>
      <value>public, max-age=600</value>
    </header>
    <header>
      <key>connection</key>
      <value>keep-alive</value>
    </header>
    <header>
      <key>content-length</key>
      <value>108</value>
    </header>
    <header>
      <key>content-type</key>
      <value>application/json;charset=iso-8859-1</value>
    </header>
    <header>
      <key>date</key>
      <value>Wed, 29 Jun 2022 13:03:38 GMT</value>
    </header>
    <header>
      <key>expires</key>
      <value>Wed, 29 Jun 2022 13:13:38 GMT</value>
    </header>
    <header>
      <key>server</key>
      <value>nginx/1.21.6</value>
    </header>
    <header>
      <key>vary</key>
      <value>Accept-Encoding</value>
    </header>
    <header>
      <key>x-content-type-options</key>
      <value>nosniff</value>
    </header>
    <header>
      <key>x-frame-options</key>
      <value>sameorigin</value>
    </header>
    <header>
      <key>x-xss-protection</key>
      <value>1; mode=block</value>
    </header>
  </headers>
  <body>{"buildDate":"2022-06-29T09:22:41.541886118Z","buildVersion":"SNAPSHOT","upDate":"2022-06-29T11:06:26.869Z"}</body>
</response>

Example Usage

This is an example of how to use the function call in your XSLT. It is recommended to place the clientConfig JSON in a Dictionary to make it easier to edit and to avoid having to escape all the quotes.

  ...
  <xsl:template match="record">
    ...
    <!-- Read the client config from a Dictionary into a variable -->
    <xsl:variable name="clientConfig" select="stroom:dictionary('HTTP Client Config')" />
    <!-- Make the HTTP call and store the response in a variable -->
    <xsl:variable name="response" select="stroom:http-call('https://reqbin.com/echo', null, null, null, $clientConfig)" />
    <!-- Apply 'response' templates to the response -->
    <xsl:apply-templates mode="response" select="$response" />
    ...
  </xsl:template>
  
  <xsl:template mode="response" match="http:response">
    <!-- Extract just the body of the response -->
    <val><xsl:value-of select="./http:body/text()" /></val>
  </xsl:template>
  ...

`ip-in-cidr`

ip-in-cidr(ipAddress, cidr)➡Boolean

Checks whether an IPv4 address lies within a CIDR range.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`ipAddress`	String		-	-		-	The IPv4 address to check.
`cidr`	String		-	-		-	The CIDR range, for example `192.168.1.0/24`.

Return Value:

Type	Description
Boolean	`true` if the address is in the range; otherwise `false`.

`numeric-ip`

numeric-ip(ipAddress)➡String

Converts an IP address to a numeric string suitable for range comparisons and reference data lookups.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`ipAddress`	String		-	-		-	The IP address to convert.

Return Value:

Type	Description
String	The numeric IP address, or an empty sequence if conversion fails.

4 - Other Functions

Functions that don’t fit into any other category.

`ask-ai`

ask-ai(model, message, [systemPrompt])➡String

Asks a configured chat model a question and returns its reply. The model is resolved by name or UUID; each call sends a request unless an identical response is cached.

Function Arguments:

Param	Type	Default Value	Allowed Values	Min Count	Description
`model`	String	-	-	-	The name or UUID of the chat model.
`message`	String	-	-	-	The message to send to the model.
`systemPrompt`	String	-	-	-	Optional instructions for the model.

Return Value:

Type	Description
String	The model’s reply, or an empty sequence if the model or message is unavailable.

You must hold the Use permission on the model document. Where the model cannot be found, or you do not have permission to use it, a warning is recorded against the stream and an empty sequence is returned.

Performance

Warning

The model is asked once per call, so a pipeline that calls this for every record will make one request per record, each of which may take seconds or longer. Consider whether the question really needs asking of every record.

Repeated identical questions are served from a cache rather than being asked again, so calling this with the same model, message and system prompt costs one request however many records ask it. The cache is configured by the chatResponseCache property of the ai configuration branch. Setting its maximumSize to 0 asks the model every time.

Examples

Asking a model to classify a value.

<xsl:variable name="answer"
              select="stroom:ask-ai('Event Classifier', concat('Is this user agent a bot? Answer yes or no. ', UserAgent))"/>

Giving the model a role with a system prompt.

<xsl:variable name="answer"
              select="stroom:ask-ai(
                  'Event Classifier',
                  Description,
                  'You are a security analyst. Answer in one short sentence.')"/>

`cosine-similarity`

cosine-similarity(vectorA, vectorB)➡Decimal

Calculates the cosine similarity of two numeric vectors, such as embedding vectors. The result is between -1 and 1; larger values indicate that the vectors point more closely in the same direction.

Both vectors must have the same number of elements, otherwise an error is raised. If either vector has zero magnitude, the function returns 0.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`vectorA`	Sequence		-	-		-	The first sequence of numbers.
`vectorB`	Sequence		-	-		-	The second sequence of numbers, with the same length as `vectorA`.

Return Value:

Type	Description
Decimal	The cosine similarity of the two vectors, or `0` if either has zero magnitude.

Example

XSLT:

<xsl:variable name="a" select="(1, 0, 1)" as="xs:double*" />
<xsl:variable name="b" select="(1, 1, 1)" as="xs:double*" />
<Similarity><xsl:value-of select="stroom:cosine-similarity($a, $b)" /></Similarity>

XML:

<Similarity>0.8164965809277259</Similarity>

`pointIsInsideXYPolygon`

pointIsInsideXYPolygon(xPos, yPos, xPolyData, yPolyData)➡Boolean

Tests whether a point is inside a polygon. Useful for determining if a user is inside a physical zone based on their location and the boundary of that zone.

The list of values supplied for xPolyData must correspond with the list of values supplied for yPolyData and both must contain at least three points. The points that define the polygon must be provided in order, i.e. starting from one point on the polygon and then travelling round the path of the polygon until it gets back to the beginning.

Function Arguments:

Param	Type	Default Value	Allowed Values	Min Count	Description
`xPos`	Decimal	-	-	-	The point’s X coordinate.
`yPos`	Decimal	-	-	-	The point’s Y coordinate.
`xPolyData`	Sequence	-	-	-	The polygon’s X coordinates, in vertex order.
`yPolyData`	Sequence	-	-	-	The corresponding Y coordinates, in vertex order.

Return Value:

Type	Description
Boolean	`true` if the point is inside the polygon; otherwise `false`.

`send-email`

send-email(to, subject, body, [cc], [bcc])➡Empty Sequence

Sends an email using the SMTP server and from address configured in stroom.analytics.emailConfig. Each address argument is a ; separated list of email addresses, and there must be at least one recipient across to, cc and bcc. If the body contains HTML tags it is sent as HTML, otherwise as plain text.

An email is sent every time the function is called, so calling it for every record will send an email for every record. No email is sent while stepping. Instead an INFO message shows the email that would have been sent.

As the function returns an empty sequence, call it somewhere its result is used, e.g. <xsl:sequence select="stroom:send-email(...)"/>, otherwise the XSLT processor may not call it.

Function Arguments:

Param	Type	Default Value	Allowed Values	Min Count	Description
`to`	String	-	-	-	The `;` separated addresses to send the email to.
`subject`	String	-	-	-	The subject of the email. It must be a single line.
`body`	String	-	-	-	The body of the email, as plain text or HTML.
`cc`	String	-	-	-	The `;` separated addresses to copy the email to.
`bcc`	String	-	-	-	The `;` separated addresses to blind copy the email to.

Return Value:

Type	Description
Empty Sequence	An empty sequence.

`split-document`

split-document(doc, segmentSize, overlapSize)➡Sequence

Splits text into overlapping segments for language-model tokenisation. The segment and overlap sizes are estimated token counts.

Function Arguments:

Param	Type	Default Value	Allowed Values	Min Count	Description
`doc`	String	-	-	-	The document text to split.
`segmentSize`	Integer	-	-	-	The target segment size in estimated tokens.
`overlapSize`	Integer	-	-	-	The overlap between adjacent segments in estimated tokens.

Return Value:

Type	Description
Sequence	An array of text segments, or an empty array if splitting fails.

5 - Stroom Pipeline Functions

Functions for obtaining information about the current pipeline process.

`add-meta`

add-meta(key, value)➡Empty Sequence

Adds a metadata key and value to the output destination. Blank keys are ignored.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`key`	String		-	-		-	The metadata key to write.
`value`	String		-	-		-	The metadata value to write.

Return Value:

Type	Description
Empty Sequence	An empty sequence.

`bitmap-lookup`

bitmap-lookup(map, key, [time], [ignoreWarnings], [trace], [delimiter])➡Sequence

The bitmap-lookup() function looks up a bitmap key from reference or context data a value (which can be an XML node set) for each set bit position and adds it to the resultant XML.

If the look up fails no result will be returned.

Function Arguments:

Param	Type	Default Value	Allowed Values	Min Count	Description
`map`	String	-	-	-	The name of the map to perform the lookup in.
`key`	String	-	-	-	The key to lookup in the named map.
`time`	String	-	-	-	Determines which set of reference data was effective at the requested time. If no reference data exists with an effective time before the requested time then the lookup will fail. Time is in the format `yyyy-MM-dd'T'HH:mm:ss.SSSXX`, e.g. `2010-01-01T00:00:00.000Z`.
`ignoreWarnings`	Boolean	-	-	-	If true, any lookup failures will be ignored, else they will be reported as warnings.
`trace`	Boolean	-	-	-	If true, additional trace information is output as INFO messages.
`delimiter`	String	`<space>`	-	-	The delimiter to use when concatenating multiple lookup values. The default delimiter is a space.

Return Value:

Type	Description
Sequence	The matching value or XML nodes, or an empty sequence if no value is found.

Examples

For the purposes of these examples, the reference data store map contains:

Key (Bit position)	Value
0	Administrator
1	Manage_Users
2	Perform_Export
3	View_Data
4	Manage_Jobs
5	Delete_Data
6	Manage_Volumes

The following are example lookups using the above reference data:

Lookup Key (decimal)	Lookup Key (Hex)	Bitmap	Result
`0`	`0x0`	`0000000`	-
`1`	`0x1`	`0000001`	`Administrator`
`74`	`0x4A`	`1001010`	`Manage_Users View_Data Manage_Volumes`
`2`	`0x2`	`0000010`	`Manage_Users`
`96`	`0x60`	`1100000`	`Delete_Data Manage_Volumes`

`classification`

classification()➡String

Returns the display classification of the feed for the data being processed.

Return Value:

Type	Description
String	The feed’s display classification, if available.

`col-from`

col-from()➡String

Returns the input column where the current record begins. The column can be 0.

Return Value:

Type	Description
String	The starting input column, if available.

`col-to`

col-to()➡String

Returns the input column where the current record ends.

Return Value:

Type	Description
String	The ending input column, if available.

`dictionary`

dictionary(name)➡String

Returns the contents of a Dictionary document for use during translation. The dictionary may be identified by name or UUID.

The main use for this function is to allow users to abstract the management of a set of keywords from the XSLT so that it is easier for some users to make quick alterations to a dictionary that is used by some XSLT, without the need for the user to understand the complexities of XSLT.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`name`	String		-	-		-	The name or UUID of the Dictionary document.

Return Value:

Type	Description
String	The dictionary contents, if the document is found.

`feed-attribute`

Is Alias of: meta

feed-attribute(key)➡String

Looks up a metadata value for the current stream part.

The key can be Feed, StreamType, CreatedTime, EffectiveTime, Pipeline or any other attribute supplied when the stream was sent to Stroom, e.g. meta('System').

feed-attribute() is a deprecated alias.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`key`	String		-	-		-	The metadata key (case-insensitive), such as `Feed`, `StreamType` or a supplied attribute.

Return Value:

Type	Description
String	The value for the key, or an empty sequence if the key is not found.

`feed-name`

feed-name()➡String

Returns the name of the feed for the data currently being processed.

Return Value:

Type	Description
String	The current feed name, if available.

`get`

get(key)➡String

Reads a value stored under a key by put() during the current pipeline process.

Values are stored against a key name so that multiple values can be stored. These functions can be used for many purposes but are most commonly used to count a number of records that meet certain criteria.

The map is in the scope of the current pipeline process so values do not live after the stream has been processed. Also, the map will only contain entries that were put() within the current pipeline process.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`key`	String		-	-		-	The key used when storing the value.

Return Value:

Type	Description
String	The stored value, or an empty sequence if the key is absent.

Example

An example of how to count records is shown below:

<!-- Get the current record count -->
<xsl:variable name="currentCount" select="number(stroom:get('count'))" />

<!-- Increment the record count -->
<xsl:variable name="count">
  <xsl:choose>
    <xsl:when test="$currentCount">
      <xsl:value-of select="$currentCount + 1" />
    </xsl:when>
    <xsl:otherwise>
      <xsl:value-of select="1" />
    </xsl:otherwise>
  </xsl:choose>
</xsl:variable>

<!-- Store the count for future retrieval -->
<xsl:value-of select="stroom:put('count', $count)" />

<!-- Output the new count -->
<data name="Count">
  <xsl:attribute name="Value" select="$count" />
</data>

`line-from`

line-from()➡String

Returns the input line where the current record begins, counting from 1.

Return Value:

Type	Description
String	The starting input line, if available.

`line-to`

line-to()➡String

Returns the input line where the current record ends.

Return Value:

Type	Description
String	The ending input line, if available.

`log`

log(severity, message)➡Empty Sequence

The log() function writes a message to the processing log with the specified severity. Severities of INFO, WARN, ERROR and FATAL can be used. Severities of ERROR and FATAL will result in records being omitted from the output if a RecordOutputFilter is used in the pipeline.

The counts for RecWarn, RecError will be affected by warnings or errors generated in this way therefore this function is useful for adding business rules to XML output.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`severity`	String		-	`INFO`, `WARN`, `ERROR`, `FATAL`		-	The message severity, such as `INFO`, `WARN`, `ERROR` or `FATAL`.
`message`	String		-	-		-	The message to output to the log.

Return Value:

Type	Description
Empty Sequence	An empty sequence.

Example

Heading

This call will warn if a SID is not the correct length.

<xsl:if test="string-length($sid) != 7">
  <xsl:value-of select="stroom:log('WARN', concat($sid, ' is not the correct length'))"/>
</xsl:if>

The same functionality can also be achieved using the standard xsl:message element, see <xsl:message>.

`lookup`

lookup(map, key, [time], [ignoreWarnings], [trace])➡Sequence

Looks up a key in reference or context data and return the matching string or XML. A map path separated by / performs chained lookups. Numeric keys can also match key ranges in the reference data.

If the look up fails no result will be returned.

Function Arguments:

Param	Type	Default Value	Allowed Values	Min Count	Description
`map`	String	-	-	-	The reference data map name, or `/`-separated map path.
`key`	String	-	-	-	The lookup key.
`time`	String	-	-	-	Set the time to use when determining which reference data stream to use based on its effective time. which set of reference data was effective at the requested time. The reference data stream with the latest effective time that is before this value will be used. If no reference data exists with an effective time before the requested time then the lookup will fail. Time is in the format `yyyy-MM-dd'T'HH:mm:ss.SSSXX`, e.g. `2010-01-01T00:00:00.000Z`.
`ignoreWarnings`	Boolean	-	-	-	Suppress warnings for failed lookups when `true`.
`trace`	Boolean	-	-	-	Output additional trace information as `INFO` messages when `true`.

Return Value:

Type	Description
Sequence	The matching value or XML nodes, or an empty sequence if no value is found.

Example

By testing the result, a default value may be output if no result is returned.

The following example uses lookup to convert a staff number into an employee ID, assuming the STAFF_NO_TO_EMP_ID reference data map has been loaded with the staff number to employee ID mappings.

<xsl:variable name="staffNo" select="StaffNumber"/>
<xsl:if test="$staffNo">
   <xsl:variable name="sid" select="stroom:lookup('STAFF_NO_TO_EMP_ID', $staffNo, $formattedDateTime)"/>

   <xsl:choose>
      <xsl:when test="$empId">
         <User>
             <Id><xsl:value-of select="$empId"/></Id>
         </User>
      </xsl:when>
      <xsl:otherwise>
         <data name="StaffNumber">
            <xsl:attribute name="Value"><xsl:value-of select="$staffNo"/></xsl:attribute>
         </data>
      </xsl:otherwise>
   </xsl:choose>
</xsl:if>

Range Lookups

Reference data entries can either be stored with single string key or a key range that defines a numeric range, e.g. 1-100. When a lookup is preformed the passed key is looked up as if it were a normal string key. If that lookup fails Stroom will try to convert the key to an integer (long) value. If it can be converted to an integer than a second lookup will be performed against entries with key ranges to see if there is a key range that includes the requested key.

Range lookups can be used for looking up an IP address where the reference data values are associated with ranges of IP addresses. In this use case, the IP address must first be converted into a numeric value using numeric-ip(), e.g.:

<xsl:value-of select="stroom:lookup('IP_TO_LOCATION', numeric-ip($ipAddress))"/>

Similarly the reference data must be stored with key ranges whose bounds were created using this function.

Nested Maps

The lookup function allows you to perform chained lookups using nested maps. For example you may have a reference data map called USER_ID_TO_LOCATION that maps user IDs to some location information for that user and a map called USER_ID_TO_MANAGER that maps user IDs to the user ID of their manager. If you wanted to decorate a user’s event with the location of their manager you could use a nested map to achieve the lookup chain. To perform the lookup set the map argument to the list of maps in the lookup chain, separated by a /, e.g. USER_ID_TO_MANAGER/USER_ID_TO_LOCATION.

This will perform a lookup against the first map in the list using the requested key. If a value is found the value will be used as the key in a lookup against the next map. The value from each map lookup is used as the key in the next map all the way down the chain. The value from the last lookup is then returned as the result of the lookup() call. If no value is found at any point in the chain then that results in no value being returned from the function.

In order to use nested map lookups each intermediate map must contain simple string values. The last map in the chain can either contain string values or XML fragment values.

`manifest`

manifest()➡Sequence

Returns the manifest attributes of the current stream as an XML document in the stroom-meta namespace. The document has a manifest root element and a string element for each attribute, with its name in the key attribute. The attributes are ordered by name.

If the stream cannot be read, an empty manifest element is returned.

Return Value:

Type	Description
Sequence	An XML document containing the stream’s manifest attributes.

`manifest-for-id`

manifest-for-id(streamId)➡Sequence

Returns the manifest attributes of the specified stream as an XML document in the stroom-meta namespace. The document has a manifest root element and a string element for each attribute, with its name in the key attribute. The attributes are ordered by name.

If the stream cannot be read, an empty manifest element is returned.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`streamId`	String		-	-		-	The ID of the stream whose manifest is required.

Return Value:

Type	Description
Sequence	An XML document containing the stream’s manifest attributes.

`meta`

Aliases:

feed-attribute

meta(key)➡String

Looks up a metadata value for the current stream part.

The key can be Feed, StreamType, CreatedTime, EffectiveTime, Pipeline or any other attribute supplied when the stream was sent to Stroom, e.g. meta('System').

feed-attribute() is a deprecated alias.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`key`	String		-	-		-	The metadata key (case-insensitive), such as `Feed`, `StreamType` or a supplied attribute.

Return Value:

Type	Description
String	The value for the key, or an empty sequence if the key is not found.

Note

This is not the same as meta-attribute().

meta-attribute() - reads the manifest of the whole stream from the data store, so it will open the stream's source.
meta() - reads the meta data of the part currently being processed, and is what most translations want.

`meta-attribute`

meta-attribute(key)➡String

Reads one attribute from the current stream’s manifest. This opens the manifest from the stream’s source, unlike meta() which reads metadata for the current part.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`key`	String		-	-		-	The manifest attribute key to read.

Return Value:

Type	Description
String	The manifest attribute value, or an empty sequence if the key is not found.

Note

This is not the same as meta().

meta() - reads the meta data of the part currently being processed, and is what most translations want.
meta-attribute() - reads the manifest of the whole stream from the data store, so it will open the stream's source.

`meta-keys`

meta-keys()➡Sequence

Returns the metadata keys for the current stream part as an array of strings.

Return Value:

Type	Description
Sequence	An array containing the available metadata keys.

Warning

When calling this function and assigning the result to a variable, you must specify the variable data type of xs:string* (array of strings).

Example

The following fragment is an example of using meta-keys() to emit all meta values for a given stream, into an Event/Meta element:

<Event>
  <xsl:variable name="metaKeys" select="stroom:meta-keys()" as="xs:string*" />
  <Meta>
    <xsl:for-each select="$metaKeys">
      <string key="{.}"><xsl:value-of select="stroom:meta(.)" /></string>
    </xsl:for-each>
  </Meta>
</Event>

`meta-stream`

meta-stream()➡Sequence

Returns metadata for the current stream and part as an XML document in the stroom-meta namespace. The document has a meta-stream root element and a string element for each metadata entry, with its name in the key attribute. The entries are ordered by name.

If the stream part cannot be read, an empty meta-stream element is returned.

Return Value:

Type	Description
Sequence	An XML document containing the stream part’s metadata.

`meta-stream-for-id`

meta-stream-for-id(streamId, partNo)➡Sequence

Returns metadata for the specified streamId and partNo as an XML document in the stroom-meta namespace. The document has a meta-stream root element and a string element for each metadata entry, with its name in the key attribute. The entries are ordered by name.

If the stream part cannot be read, an empty meta-stream element is returned.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`streamId`	Integer		-	-		-	The ID of the stream containing the part.
`partNo`	Integer		-	-		-	The part number within the stream, starting at `1`.

Return Value:

Type	Description
Sequence	An XML document containing the stream part’s metadata.

`parent-for-id`

parent-for-id(streamId)➡String

Returns the parent stream ID of the specified input stream.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`streamId`	String		-	-		-	The ID of the input stream.

Return Value:

Type	Description
String	The parent stream ID, if one exists.

`parent-id`

parent-id()➡String

Returns the parent stream ID of the current input stream.

Return Value:

Type	Description
String	The parent stream ID, if one exists.

`part-no`

part-no()➡String

Returns the current part number within a multipart input stream, counting from 1.

Return Value:

Type	Description
String	The current part number.

`pipeline-name`

pipeline-name()➡String

Returns the name of the pipeline currently processing the stream.

Return Value:

Type	Description
String	The pipeline name, if available.

`put`

put(key, value)➡Empty Sequence

Stores a string under a key for retrieval by get() during the current pipeline process.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`key`	String		-	-		-	The key under which to store the value.
`value`	String		-	-		-	The value to store.

Return Value:

Type	Description
Empty Sequence	An empty sequence.

`record-no`

record-no()➡String

Returns the current record number within the current stream part, counting from 1.

Return Value:

Type	Description
String	The current record number, if available.

`search-id`

search-id()➡String

Returns the batch search ID when a pipeline is processing as part of a batch search.

Return Value:

Type	Description
String	The batch search ID, if available.

`source`

source()➡Sequence

Returns an XML document in the stroom-meta namespace describing the current source location.

Return Value:

Type	Description
Sequence	The XML source location, or an empty sequence if no location is available.

`source-id`

Aliases:

stream-id

source-id()➡String

Returns the ID of the current input stream. stream-id() is an alias retained for compatibility.

Return Value:

Type	Description
String	The current input stream ID, if available.

`stream-id`

Is Alias of: source-id

stream-id()➡String

Returns the ID of the current input stream. stream-id() is an alias retained for compatibility.

Return Value:

Type	Description
String	The current input stream ID, if available.

6 - String Functions

Functions for string parsing and manipulation.

`link`

Builds a Markdown-style link for display in a dashboard table. The optional type suffix controls whether Stroom opens it in a dialog, tab, browser tab or dashboard.

link(url)➡String

Uses the URL as both link text and target.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`url`	String		-	-		-	The link target.

Return Value:

Type	Description
String	The formatted link string.

link(title, url, [type])➡String

Uses a separate title and target URL, with optional target type.

Function Arguments:

Param	Type	Default Value	Allowed Values	Min Count	Description
`title`	String	-	-	-	The text to display.
`url`	String	-	-	-	The link target.
`type`	String	-	`tab`, `dialog`, `dashboard`, `stepping`, `data`, `annotation`, `browser`	-	The target display type.

Return Value:

Type	Description
String	The formatted link string.

Examples

link('https://www.somehost.com/somepath')
> [https://www.somehost.com/somepath](https://www.somehost.com/somepath)

link('Click Here','https://www.somehost.com/somepath')
> [Click Here](https://www.somehost.com/somepath)

link('Click Here','https://www.somehost.com/somepath', 'dialog')
> [Click Here](https://www.somehost.com/somepath){dialog}

link('Click Here','https://www.somehost.com/somepath', 'dialog|Dialog Title')
> [Click Here](https://www.somehost.com/somepath){dialog|Dialog Title}

Type can be one of:

dialog : Display the content of the link URL within a stroom popup dialog.
tab : Display the content of the link URL within a stroom tab.
browser : Display the content of the link URL within a new browser tab.
dashboard : Used to launch a stroom dashboard internally with parameters in the URL.
stepping : Opens the stepper using the parameters in the URL.
browser : Opens a new browser tab.
annotation : Opens (and creates) the annotation using the URL parameters.

If you wish to override the default title or URL of the target link in either a tab or dialog you can. Both dialog and tab types allow titles to be specified after a |, e.g. dialog|My Title.

7 - URI/URL Functions

Functions relating to parsing and manipulating URI/URLs.

`decode-url`

decode-url(encodedUrl)➡String

Decodes a URL-encoded string.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`encodedUrl`	String		-	-		-	The URL-encoded string.

Return Value:

Type	Description
String	The decoded string, or an empty sequence if decoding fails.

`encode-url`

encode-url(url)➡String

URL-encodes a string.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`url`	String		-	-		-	The string to encode.

Return Value:

Type	Description
String	The encoded string, or an empty sequence if encoding fails.

`parse-uri`

parse-uri(uri)➡Sequence

The parse-uri() function takes a Uniform Resource Identifier (URI) in string form and returns an XML node with a namespace of uri containing the URI’s individual components of authority, fragment, host, path, port, query, scheme, schemeSpecificPart and userInfo.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`uri`	String		-	-		-	The URI string to parse.

Return Value:

Type	Description
Sequence	An XML document containing the URI components, or an empty sequence for an invalid URI.

Example Usage

Given that rURI contains the following text:

http://foo:bar@w1.superman.com:8080/very/long/path.html?p1=v1&amp;p2=v2#more-details

XSLT:

<!-- Display and parse the URI contained within the text of the rURI element -->
<xsl:variable name="uri" select="stroom:parse-uri(rURI)" />

<URI>
  <xsl:value-of select="rURI" />
</URI>
<URIDetail>
  <xsl:copy-of select="$uri"/>
</URIDetail>

XML:

<URI>http://foo:bar@w1.superman.com:8080/very/long/path.html?p1=v1&amp;p2=v2#more-details</URI>
<URIDetail>
  <authority xmlns="uri">foo:bar@w1.superman.com:8080</authority>
  <fragment xmlns="uri">more-details</fragment>
  <host xmlns="uri">w1.superman.com</host>
  <path xmlns="uri">/very/long/path.html</path>
  <port xmlns="uri">8080</port>
  <query xmlns="uri">p1=v1&amp;p2=v2</query>
  <scheme xmlns="uri">http</scheme>
  <schemeSpecificPart xmlns="uri">//foo:bar@w1.superman.com:8080/very/long/path.html?p1=v1&amp;p2=v2</schemeSpecificPart>
  <userInfo xmlns="uri">foo:bar</userInfo>
</URIDetail>

8 - Value Functions

Functions that simply supply a value.

`current-user`

current-user([form])➡String

Returns the identity of the user Stroom is processing as. This is mainly useful in interactive processing, such as a search.

The form of the user’s identity returned is controlled by the optional form argument. By default, the display name is used, falling back to the subject identifier if there is no display name.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`form`	String		-	`display`, `subject`, `full`		-	The form of the user’s identity to return. If not provided ‘display name is used, falling back to the subject identifier if there is no display name.

Return Value:

Type	Description
String	The requested user identity, or an empty sequence if unavailable.

`random`

random()➡Decimal

Generates a random decimal number between 0.0 (inclusive) and 1.0 (exclusive).

Return Value:

Type	Description
Decimal	The random decimal number.

`random-integer`

random-integer(upperBound)➡Integer

Generates a random integer between 0 (inclusive) and the upper bound (exclusive).

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`upperBound`	Integer		-	-		-	The upper bound of the random integer (exclusive).

Return Value:

Type	Description
Integer	The random integer.

XSLT Functions

Using Stroom XSLT Functions

Return Values

Functions

1 - Conversion Functions

hash

hex-to-dec

hex-to-oct

hex-to-string

Example

json-to-xml

2 - Date/Time Functions

current-time

current-unixTime

format-date

Date Formats

Time Zones

Parsing Examples

Note

Formatting Examples

Reference Time

format-dateTime

Date Formats

Examples

from-unixTime

parse-dateTime

Examples

to-unixTime

3 - Network Functions

cidr-to-numeric-ip-range

Example

fetch-json

host-address

host-name

http-call

clientConfig

Example Output

Example Usage

ip-in-cidr

numeric-ip

4 - Other Functions

ask-ai

Performance

Warning

Examples

See Also

cosine-similarity

Example

pointIsInsideXYPolygon

send-email

split-document

5 - Stroom Pipeline Functions

add-meta

bitmap-lookup

Examples

classification

col-from

col-to

dictionary

feed-attribute

feed-name

get

See Also

Example

line-from

line-to

log

Example

lookup

Example

Range Lookups

Nested Maps

manifest

manifest-for-id

meta

Note

meta-attribute

Note

meta-keys

Warning

`hash`

`hex-to-dec`

`hex-to-oct`

`hex-to-string`

`json-to-xml`

`current-time`

`current-unixTime`

`format-date`

`format-dateTime`

`from-unixTime`

`parse-dateTime`

`to-unixTime`

`cidr-to-numeric-ip-range`

`fetch-json`

`host-address`

`host-name`

`http-call`

`clientConfig`

`ip-in-cidr`

`numeric-ip`

`ask-ai`

`cosine-similarity`

`pointIsInsideXYPolygon`

`send-email`

`split-document`

`add-meta`

`bitmap-lookup`

`classification`

`col-from`

`col-to`

`dictionary`

`feed-attribute`

`feed-name`

`get`

`line-from`

`line-to`

`log`

`lookup`

`manifest`

`manifest-for-id`

`meta`

`meta-attribute`

`meta-keys`

`meta-stream`

`meta-stream-for-id`

`parent-for-id`

`parent-id`

`part-no`

`pipeline-name`

`put`

`record-no`

`search-id`

`source`

`source-id`

`stream-id`

`link`

`decode-url`

`encode-url`

`parse-uri`

`current-user`

`random`

`random-integer`