Logic Apps (Standard) Data Mapper: Utility Functions
Overview
Utility functions are used to perform a variety of additional and distinct operations that don’t fit in the above Categories, such as stopping a transformation and returning the specified error code and description or format, etc.
Available Functions
The Utility functions are:
- Copy: Copies any and all of the input’s substructure.
- Error: Stops a transformation and returns the specified error code and description.
- Format date: Returns a date in the specified format.
- Format DateTime value: Returns a timestamp in the specified format.
- Format number: Returns a number in the specified format.
- Format time: Returns a time in the specified format.
Copy
This function states that it will copy any and all of the input’s substructure. It enables your maps to use schemas that include any and anyAttribute elements. These elements are, in essence, wildcards provided in the Schema definition language to match unknown structures or attributes.
The following figure shows the Copy function used in a map.
Behind the scenes, this function is translated to the following XPath expression: copy-of($arg)
Rules:
- The Copy function copies the element in the input instance message corresponding to the source schema node connected to the Copy function. The function also copies any and all of its substructure and re-creates it in the output instance message at the linked node in the destination schema. Thus, you can also use the Copy function to copy any source and destination records having identical substructures.
Error
This function states that it will stop a transformation and returns the specified error code and description.
Behind the scenes, this function is translated to the following XPath function: error($code, $description)
fn:error($code as xs:QName?,$description as xs:string)as none
Rules:
- Calling the
fn:errorfunction raises an application-defined error. - This function never returns a value. Instead, it always raises an error. The effect of the error is identical to the effect of dynamic errors raised implicitly, for example, when an incorrect argument is supplied to a function.
- The
$codeis an error code that distinguishes this error from others. It is anxs:QName; the namespace URI conventionally identifies the component, subsystem, or authority responsible for defining the meaning of the error code, while the local part identifies the specific error condition. The namespace URIhttp://www.w3.org/2005/xqt-errorsis used for errors defined in this specification; other namespace URIs may be used for errors defined by the application. - The
$descriptionis a natural-language description of the error condition.
Format date
This function states that it returns a date in the specified format.
Behind the scenes, this function is translated to the following XPath function: format-date($arg1, $arg2)
fn:format-date($value as xs:date?,$picture as xs:string)as xs:string?
Rules:
- The
$arg1 needs to be an xs:date in the following format yyyy-MM-DD or yyyy-MM-DDZ. - The
$arg2 (or picture) consists of a sequence of variable markers and literal substrings. A substring enclosed in square brackets is interpreted as a variable marker; substrings not enclosed in square brackets are taken as literal substrings. The literal substrings are optional and, if present, are rendered unchanged, including any whitespace. The variable markers are replaced in the result by strings representing aspects of the date and/or time to be formatted. These are described in detail below:- Y – year (absolute value);
- M – month in the year
- D – day in the month
- d – day in the year
- F – day of the week
- W – week in year
- w – week in the month
- C – calendar: the name or abbreviation of a calendar name
- E – era: the name of a baseline for the numbering of years, for example, the reign of a monarch
Sample:
- The expression
fn:format-date($d, “[Y0001]-[M01]-[D01]”) returns 2002-12-31 - The expression
fn:format-date($d, "[M]-[D]-[Y]")returns 12-31-2002. - The expression
fn:format-date($d, "[D1] [MI] [Y]")returns31 XII 2002. - The expression
fn:format-date($d, “[D1o] [MNn], [Y]”) returns 31st December, 2002 - The expression
fn:format-date($d, "[D01] [MN,*-3] [Y0001]")returns 31 DEC 2002. - The expression
fn:format-date($d, "[YWw]")returnsTwo Thousand and Three.
Format DateTime value
Returns a timestamp in the specified format.
This function states that it returns the specified value as an integer.
Behind the scenes, this function is translated to the following XPath function: format-dateTime($arg1, $arg2)
fn:format-dateTime($value as xs:dateTime?,$picture as xs:string)as xs:string?
Rules:
- The
$arg1 needs to be an xs:dateTime in the following format yyyy-MM-DDTHH:mm:ssZ or yyyy-MM-DDTHH:mm:ss-hh:mm. - The
$arg2 (or picture) consists of a sequence of variable markers and literal substrings. A substring enclosed in square brackets is interpreted as a variable marker; substrings not enclosed in square brackets are taken as literal substrings. The literal substrings are optional and, if present, are rendered unchanged, including any whitespace. The variable markers are replaced in the result by strings representing aspects of the date and/or time to be formatted. These are described in detail below:- Y – year (absolute value);
- M – month in the year
- D – day in the month
- d – day in the year
- F – day of the week
- W – week in year
- w – week in the month
- H – hour in the day (24 hours)
- h – hour in half-day (12 hours)
- P – am/pm marker
- m – minute in the hour
- s – second in a minute
- f – fractional seconds
- Z – timezone
- z – timezone (same as Z, but modified where appropriate to include a prefix as a time offset using GMT, for example, GMT+1 or GMT-05:00. For this component, there is a fixed prefix of GMT or a localized variation thereof for the chosen language, and the remainder of the value is formatted as for specifier Z. 01:01
- C – calendar: the name or abbreviation of a calendar name
- E – era: the name of a baseline for the numbering of years, for example, the reign of a monarch
Sample:
- The expression
fn:format-dateTime($dt, “[h].[m01][Pn] on [FNn], [D1o] [MNn]”) returns 3.58pm on Tuesday, 31st December - The expression
fn:format-date($d, "[M]-[D]-[Y]")returns 12-31-2002. - The expression
fn:format-dateTime($dt, "[M01]/[D01]/[Y0001] at [H01]:[m01]:[s01]")returns 12/31/2002 at 15:58:45.
Format number
Returns a number in the specified format.
This function states that it returns the specified value as an integer.
Behind the scenes, this function is translated to the following XPath function: format-number($arg1, $arg2)
fn:format-number($value as xs:numeric?,$picture as xs:string)as xs:string
Rules:
- Returns a string containing a number formatted according to a given picture string, taking account of decimal formats specified in the static context.
- The
$arg1maybe of any numeric data type (xs:double, xs:float, xs:decimal, or their subtypes, includingxs:integer).
Sample:
- The expression
format-number(12345.6, '#,###.00')returns"12,345.60". - The expression
format-number(12345678.9, '9,999.99')returns"12,345,678.90". - The expression
format-number(123.9, '9999')returns"0124". - The expression
format-number(0.14, '01%')returns"14%". - The expression
format-number(-6, '000')returns"-006".
Format time
Returns a time in the specified format.
This function states that it returns the specified value as an integer.
Behind the scenes, this function is translated to the following XPath function: format-time($arg1, $arg2)
fn:format-time($value as xs:time?,$picture as xs:string)as xs:string?
Rules:
- The
$arg1 needs to be an xs:time in the following format HH:mm:ssZ or HH:mm:ss-hh:mm. - The
$arg2 (or picture) consists of a sequence of variable markers and literal substrings. A substring enclosed in square brackets is interpreted as a variable marker; substrings not enclosed in square brackets are taken as literal substrings. The literal substrings are optional and, if present, are rendered unchanged, including any whitespace. The variable markers are replaced in the result by strings representing aspects of the date and/or time to be formatted. These are described in detail below:- H – hour in the day (24 hours)
- h – hour in half-day (12 hours)
- P – am/pm marker
- m – minute in the hour
- s – second in a minute
- f – fractional seconds
- Z – timezone
- z – timezone (same as Z, but modified where appropriate to include a prefix as a time offset using GMT, for example, GMT+1 or GMT-05:00. For this component, there is a fixed prefix of GMT or a localized variation thereof for the chosen language, and the remainder of the value is formatted as for specifier Z. 01:01
- C – calendar: the name or abbreviation of a calendar name
- E – era: the name of a baseline for the numbering of years, for example, the reign of a monarch
Sample:
- The expression
fn:format-time($t, “[h]:[m01] [PN]”) returns 3:58 PM - The expression
fn:format-time($t, "[h]:[m01]:[s01] [PN] [ZN,*-3]")returns 3:58:45 PM PDT. - The expression
fn:format-time($t, “[h]:[m01]:[s01] o’clock [PN] [ZN,*-3]”) returns 3:58:45 o’clock PM PDT. - The expression
fn:format-time($t,”[H01]:[m01]:[s01] [z,6-6]”) returns 15:58:45 GMT+02:00.
Hope you find this helpful! So, if you liked the content or found it useful and want to help me write more, you can buy (or help buy) my son a Star Wars Lego!
