Logic Apps (Standard) Data Mapper: Utility Functions

Posted: August 8, 2023  |  Categories: Azure Azure Integration Services Logic Apps
Tags: AIS Azure Azure Integration Services Data Mapper Logic Apps Logic Apps Standard Mapping Transformation Utility

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)

<AnyStructure>
        <xsl:copy-of select="/node/@*" />
        <xsl:copy-of select="/node/*" />
</AnyStructure>

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:error function 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 $code is an error code that distinguishes this error from others. It is an xs: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 URI http://www.w3.org/2005/xqt-errors is used for errors defined in this specification; other namespace URIs may be used for errors defined by the application.
  • The $description is 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]") returns 31 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]") returns Two 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 $arg1 maybe of any numeric data type (xs:double, xs:float, xs:decimal, or their subtypes, including xs: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! 

Author: Sandro Pereira

Sandro Pereira lives in Portugal and works as a consultant at DevScope. In the past years, he has been working on implementing Integration scenarios both on-premises and cloud for various clients, each with different scenarios from a technical point of view, size, and criticality, using Microsoft Azure, Microsoft BizTalk Server and different technologies like AS2, EDI, RosettaNet, SAP, TIBCO etc. He is a regular blogger, international speaker, and technical reviewer of several BizTalk books all focused on Integration. He is also the author of the book “BizTalk Mapping Patterns & Best Practices”. He has been awarded MVP since 2011 for his contributions to the integration community.

Leave a Reply

Your email address will not be published. Required fields are marked *

turbo360

Get integration tips every day. Follow us on:

Back to Top