Maps are scoped to an Application. From the application menu, the Maps list shows every map you have defined inside that application; a map can only be referenced from ports in the same application.

The list view follows the platform's Selected Application behavior, with an Application selected, the list filters to it and the Application column is hidden; with no selection, the list spans every Application you have access to and the column is shown. Creating a new map uses the same flow: with an Application selected, the form opens with that Application preemptively chosen; without one, the form exposes an Application picker.

A map only does work once it is referenced from a hookpoint, most often a map step on a port. The hookpoint itself decides whether the map runs at all and, when several maps are in play, which one runs for a given message. The port’s Map Assignment setting picks between three configurations.

Typed table rows are unique by source Message Type, the UI enforces that. From the map’s own perspective the three modes look the same: write the XSLT once and the hookpoint decides when it runs. The hookpoint-specific rules, how the incoming Message Type is resolved, what happens after the map runs, and which modes are available on a given side of a given port, live with the port: see Receive port, Send port, Loopback port, and Null port.

A map’s output is not just a new payload, it is a brand-new message that carries its own message type. The runtime treats that as an instantiation moment: the new type’s promotions are evaluated against the freshly produced payload and, if a schema is associated with the destination type, the payload is validated against it. This is the same machinery that fires at inbound classification, the second of the two moments documented in When a message type is instantiated.

The Art2link ESB map engine is powered by SaxonHE 12.9, an industry-standard XSLT processor that provides full compliance with the latest W3C specifications.

A map can read only XML or JSON as its source. XML and JSON are first-class on the input side; CSV and TXT cannot be read by the map directly and must be disassembled to XML or JSON by a pipeline component first. On the output side any format can be written, including CSV and flat text via method="text".

A map navigates only XML or JSON, so a CSV or flat-text body has to be disassembled to XML or JSON by a pipeline component before the map runs; the map never reads the raw delimited string itself. The output side is unconstrained: method="text" lets the XSLT emit whatever character stream you build with string-join() and xsl:text, so a map can still produce CSV or flat text.

The mapping engine includes the full set of XSLT 3.0 / XPath 3.1 functions. Below are the most commonly used ones in integration scenarios.

Beyond the built-in XSLT and XPath library, maps can call user-authored custom functions, compiled C# methods deployed through the Art2link ESB UI. See the Custom functions topic for how to author and deploy them. Once a function is compiled, a map can invoke it in two ways.

The same double-curly binding used elsewhere in the map for variables, promoted properties, and other references. Typing {{ opens intellisense, which exposes available custom functions alongside the other binding sources. Calls written this way are resolved by a preprocessor pass before the XSLT runs, so the function executes outside the XSLT context, no XPath context is shared with it.

<xsl:template match="Order">
  <PurchaseOrder>
    <Active>{{Function.fnParseBool(Promoted.Order.IsActive)}}</Active>
  </PurchaseOrder>
</xsl:template>

The argument is itself a binding token, here a promotion, written without its own {{ }}: once you are inside the outer binding, a nested reference is written bare. It has to be a pre-resolved token like a promotion because the whole call is resolved before the XSLT runs: the preprocessor has no XPath context, so a bare payload field would mean nothing to it. A value that depends on the current node belongs to art:invoke below.

Custom functions can also be called inline from XSLT as native functions. This requires declaring the urn:art2link:functions namespace on the stylesheet and excluding its prefix from the result tree:

<xsl:stylesheet version="3.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:xs="http://www.w3.org/2001/XMLSchema"
                xmlns:art="urn:art2link:functions"
                exclude-result-prefixes="xs art">

With the namespace declared, invoke any custom function via art:invoke, passing the function name as the first argument and the function's parameters after it. Parameters use standard XPath nomenclature, so any XPath expression, field references, casts, computed values, can be passed in:

<xsl:template match="Order">
  <PurchaseOrder>
    <CreatedAt>
      <xsl:value-of select="art:invoke('fnFormatDateTime', string(CreatedAt))"/>
    </CreatedAt>
  </PurchaseOrder>
</xsl:template>

Unlike XML, JSON does not have elements or attributes. In XPath 3.1, JSON data is represented as maps (objects) and arrays. You navigate them using the lookup operator ?, this is the JSON equivalent of XPath's / for XML.

Given this JSON input:

{
  "orderId": "PO-1024",
  "customer": {
    "name": "Acme Corp",
    "region": "US-West"
  },
  "items": [
    { "sku": "A100", "qty": 5 },
    { "sku": "B200", "qty": 12 }
  ]
}

You would navigate it in XPath like this:

Four worked examples cover the most common integration shapes. Each one starts from a single XSLT 3.0 stylesheet, no library, no preprocessor, and emits the destination format with the standard xsl:output method.

The output pairings (XML → CSV, JSON → CSV, and so on) work the same way: read the XML or JSON source, then pick the xsl:output method for the destination. To go the other way, from CSV or flat text, disassemble it to XML or JSON in a pipeline component first, then map as usual.

Restructure an XML document into a different schema. This example maps a source <Order> to a canonical <PurchaseOrder> format.

<xsl:stylesheet version="3.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <xsl:output method="xml" indent="yes"/>

  <xsl:template match="Order">
    <PurchaseOrder id="{@OrderId}">
      <Buyer><xsl:value-of select="Customer/Name"/></Buyer>
      <Items>
        <xsl:for-each select="LineItems/Item">
          <LineItem sku="{@Code}">
            <Description><xsl:value-of select="Name"/></Description>
            <Qty><xsl:value-of select="Quantity"/></Qty>
            <Price><xsl:value-of select="UnitPrice"/></Price>
          </LineItem>
        </xsl:for-each>
      </Items>
      <Total><xsl:value-of select="sum(LineItems/Item/(Quantity * UnitPrice))"/></Total>
    </PurchaseOrder>
  </xsl:template>

</xsl:stylesheet>

Convert XML input to JSON output using XSLT 3.0 maps and arrays with serialize().

<xsl:stylesheet version="3.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:map="http://www.w3.org/2005/xpath-functions/map">

  <xsl:output method="text"/>

  <xsl:template match="Order">
    <xsl:variable name="result" select="
      map {
        'orderId': string(@OrderId),
        'buyer':   string(Customer/Name),
        'items':   array {
          for $item in LineItems/Item
          return map {
            'sku':   string($item/@Code),
            'name':  string($item/Name),
            'qty':   number($item/Quantity),
            'price': number($item/UnitPrice)
          }
        },
        'total': sum(LineItems/Item/(Quantity * UnitPrice))
      }"/>
    <xsl:value-of select="serialize($result, map { 'method': 'json', 'indent': true() })"/>
  </xsl:template>

</xsl:stylesheet>

Consume a JSON input and produce structured XML. The JSON body arrives as a raw string; the template matches / and parses it with parse-json(), after which the JSON is available as an XPath 3.1 map.

<xsl:stylesheet version="3.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <xsl:output method="xml" indent="yes"/>

  <!-- JSON arrives as a string; parse-json() turns it into an XPath 3.1 map -->
  <xsl:template match="/">
    <xsl:variable name="in" select="parse-json(.)"/>
    <Invoice>
      <InvoiceNumber><xsl:value-of select="$in?invoiceNo"/></InvoiceNumber>
      <Vendor><xsl:value-of select="$in?vendor?name"/></Vendor>
      <Lines>
        <xsl:for-each select="$in?lines?*">
          <Line>
            <Product><xsl:value-of select="?product"/></Product>
            <Amount><xsl:value-of select="?qty * ?price"/></Amount>
          </Line>
        </xsl:for-each>
      </Lines>
    </Invoice>
  </xsl:template>

</xsl:stylesheet>

Produce a flat delimited file from JSON input. This example generates pipe-delimited output with a header row, a common pattern for EDI and legacy system integrations.

<xsl:stylesheet version="3.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <xsl:output method="text"/>

  <xsl:template match="/">
    <xsl:variable name="in" select="parse-json(.)"/>
    <!-- Header -->
    <xsl:text>Product|Qty|Price|Total&#10;</xsl:text>
    <!-- Data rows -->
    <xsl:for-each select="$in?lines?*">
      <xsl:value-of select="string-join(
        (?product, string(?qty), string(?price), string(?qty * ?price)),
        '|')"/>
      <xsl:text>&#10;</xsl:text>
    </xsl:for-each>
  </xsl:template>

</xsl:stylesheet>