Using Mapping Tables

Mapping Tables for an Integration Flow version are defined as JSON Mapping Table metadata, further explained in Integration Flow Mapping Table definitions. To use Mapping Table contents in XSLT transformations, you must use U4XSLT Component (u4ik-camel-xslt). The u4xslt: component is an extension of the xslt: component provided in camel. The u4xslt: component allows you to process a message using an XSLT template. This can be ideal when using templating to generate responses for requests. The u4xslt: component has a base library of SAXON Java Extension Functions loaded by default for content enrichment purposes.

URI format

The URI format for u4xslt: component is u4xslt:templateName[?options]. The URI format contains templateName, which can be one of the following: the classpath-local URI of the template to invoke the complete URL of the remote template.

You can append query options to the URI in the following format: ?option1=value&option2=value&...

Refer to the Spring Documentation for more detail of the URI syntax.

Example URIs :

URI	Description
u4xslt:com/acme/mytransform.xsl	Refers to the file com/acme/mytransform.xsl on the classpath
u4xslt:file:///foo/bar.xsl	Refers to the file /foo/bar.xsl
u4xslt:http://acme.com/cheese/foo.xsl	Refers to the remote http resource

U4IK Camel component with Mapping Table functionality

The u4xslt: component has a library containing builtin functions for content enrichment purposes. Java Extension Functions from Saxon are used to implement this functionality. These functions are able to access and retrieve java-properties that are used for e.g. tentant-specific configuration. To use the builtin function one needs to reference component and XSLT in the Integration Flow.

For mapping tables, two functions are supported: - Function "get-mappingtable-value": The function get-mappingtable-value can be used to retrieve mapping table contents that are set in the Deployment. Use following syntax to apply the Camel function get-mappingtable-value: ext:get-mappingtable-value(mappingTableName as xs:string, keyValue* as xs:string, valueColumnName as xs:string) When keyValue is not in the Mapping Table, the function will return an empty string "". - Function "get-mappingtable-list": The function get-mappingtable-list can be used to retrieve mappingtable lists that are set in the Deployment. Use following syntax to apply the Camel function get-mappingtable-list: ext:get-mappingtable-list(mappingTableName as xs:string, keyValue* as xs:string, valueColumnName as xs:string) When keyValue is not in the Mapping Table, the function will return an empty sequence.

IMPORTANT: To use the function in the XSLT add namespace xmlns:ext = "http://extension.unit4.com to the XSLT. Also, don't forget to prefix the function with the namespace ext. The arguments of the function are of type xs:string. Make sure you provide the function with string values as arguments. The result of the function will always be of type xs:string or xsl:sequence

Arguments for both functions: mappingTableName : the first argument is always the name of the mappingtable keyValue : this argument is used to select the row ( up to 10 keys are supported). * valueColumnName : the last argument is always the name of the valuecolumn that needs to be returned

Examples

Map single key to single value:

To map a single key to a single value, you have to define a mapping table with one keyColumn and one valueColumn. An example could be a translation table for country codes to country names:

"mappingTableDefinitions": [{
  "name": "Country mappings",
  "keyColumns": [{
    "name": "countryCode",
    "type": "STRING",
    "displayName": "Country code"
  }],
  "valueColumns": [{
    "name": "countryName",
    "type": "STRING",
    "displayName": "Country name"
  }]
}]

During deployment of the Integration Flow version for a tenant the Mapping Table will be filled with values, an example of this filled Mapping Table could be the following:

Example XSLT using get-mappingtable-value with 1 key. When countryCode="NL", then function returns "Netherlands". When countryCode="DE", then function returns "Germany". When countryCode is not in the Mapping Table as a key value, the function will return an empty string "".

<?xml version="1.0"?>
<xsl:stylesheet version="2.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:ext = "http://extension.unit4.com"
    exclude-result-prefixes="xs">
    <xsl:output method="xml" indent="yes"/>

    <xsl:template match="/">
      <xsl:variable name="countryCode" select="example/@countrycode" as="xs:string"/> 

      <root>
        <xsl:value-of select="ext:get-mappingtable-value('Country mappings', $countryCode,'countryName')" />
      </root>

    </xsl:template>
</xsl:stylesheet>

NOTE: In the above example the country code that's provided in the input payload as an attribute of example element will be put in a variable called countryCode. That variable is declared of type xs:string. The variable is used in the get-mappingtable-value function as key value.

Map single key to multiple values:

To map a single key to multiple values, you have to define a mapping table with one keyColumn and multiple valueColumns. An example could be a table that maps AGB codes into corresponding UZI and URA numbers:

"mappingTableDefinitions": [{
  "name": "AGB code to UZI and URA number mappings",
  "keyColumns": [{
    "name": "agbCode",
    "type": "INTEGER",
    "min": 10000000,
    "max": 99999999,
    "displayName": "AGB code"
    }],
    "valueColumns": [{
      "name": "uziNr",
      "type": "STRING",
      "displayName": "UZI number"
      },
    {
      "name": "uraNr",
      "type": "INTEGER",
      "min": 10000000,
      "max": 99999999,
      "displayName": "URA number"
    }]
  }]

During deployment of the Integration Flow version for a tenant the Mapping Table will be filled with values, an example of this filled Mapping Table could be the following:

Regarding following input payload:

<declaratieDatasets xmlns="http://u4ik.unit4.com/integration-flow/dbc-grouper">
    <declaratieDataset agbcode="99001033" beginDatumDeclaratietraject="2018-01-01" declaratieDatasetNummer="e6d92346-2157-058d-4914-81044464fa75" typeAanlevering="P">
      <client geboorteDatum="1956-01-14" geslacht="V" privacyverklaring="false">
        </client>
    </declaratieDataset>
</declaratieDatasets>

Example XSLT using get-mappingtable-value with 1 key that returns value for valueColumn uziNr and uraNr:

<?xml version="1.0"?>
<xsl:stylesheet version="2.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:r="http://u4ik.unit4.com/integration-flow/dbc-grouper" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:ext = "http://extension.unit4.com"
    exclude-result-prefixes="xs">
    <xsl:output method="xml" indent="yes"/>

  <xsl:template match="/">

    <xsl:variable name="agbCode" select="r:declaratieDatasets/r:declaratieDataset/@agbcode" as="xs:string"/>

    <root>
      <id root="2.16.528.1.1007.3.2">
        <xsl:attribute name="extension">
          <xsl:value-of select="ext:get-mappingtable-value('AGB code to UZI and URA number mappings', $agbCode,'uziNr')" />
        </xsl:attribute>
      </id>
      <Organization>
        <id root="2.16.528.1.1007.3.3">
          <xsl:attribute name="extension">
            <xsl:value-of select="ext:get-mappingtable-value('AGB code to UZI and URA number mappings', $agbCode,'uraNr')" />
          </xsl:attribute>
        </id>
        <name/>
      </Organization>
    </root>

  </xsl:template>
</xsl:stylesheet>

NOTE: In the above example the agb code that's provided in the input payload as an attribute of r:declaratieDatasets/r:declaratieDataset will be put in a variable called agbCode. That variable is declared of type xs:string. The variable is used in the get-mappingtable-value function as key value.

Map combination of keys to a single value:

To map a combination of keys to a single value, you have to define a mapping table with multiple keyColumns and one valueColumn. An example could be a table that maps product code, location and finance manner into a cost centre:

"mappingTableDefinitions": [{
  "name": "Cost centre mappings",
  "keyColumns": [{
    "name": "productCode",
    "type": "DROPDOWN",
    "allowedValues": ["Product code 1", "Product code 2", "Product code 3", "Product code 4", "Product code 5", "Product code 6"],
    "displayName": "Product code"
    },
    {
      "name": "location",
      "type": "STRING",
      "displayName": "Location"
    },
    {
      "name": "financeManner",
      "type": "STRING",
      "displayName": "Finance manner"
    }],
    "valueColumns": [{
      "name": "costCentre",
      "type": "INTEGER",
      "displayName": "Cost centre"
    }]
  }]

During deployment of the Integration Flow version for a tenant the Mapping Table will be filled with values, an example of this filled Mapping Table could be the following:

NOTE: Map combination of keys to multiple values works the same, you just have to define more value columns

Regarding following input payload:

<?xml version="1.0"?>
<body>
    <productCode>Product code 1</productCode>
    <location>200</location>
    <financeManner>PRV</financeManner>
</body>

Example XSLT using get-mappingtable-value with 3 keys (returns 2000), where key values are fetched via XPATH expressions:

<?xml version="1.0"?>
<xsl:stylesheet version="2.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:ext = "http://extension.unit4.com"
    exclude-result-prefixes="xs">
    <xsl:output method="xml" indent="yes"/>

    <xsl:template match="/">
        <root>
            <xsl:value-of select="ext:get-mappingtable-value('Cost centre mappings', string(body/productCode/text()), string(body/location/text()), string(body/financeManner/text()), 'costCentre')" />
        </root>
    </xsl:template>
</xsl:stylesheet>

NOTE: it is important to put string() around XPATH expressions that are used in the arguments of the get-mappingtable-value function.

Map single key to list of values:

To map a single key to a list of values, you have to define a mapping table with one keyColumn and one valueColumn with isList=true. An example could be a translation table for country codes to country names:

"mappingTableDefinitions": [{
  "name": "AGB code to message type list mappings",
  "keyColumns": [{
    "name": "agbCode",
    "type": "STRING",
    "displayName": "AGB code"
  }],
  "valueColumns": [{
    "name": "messageType",
    "type": "STRING",
    "displayName": "Message type",
    "isList": true
    }]
  }]

During deployment of the Integration Flow version for a tenant the Mapping Table will be filled with values, an example of this filled Mapping Table could be the following:

NOTE: Map combination of keys to list of values works the same, you just have to define more key columns

Example XSLT using get-mappingtable-list with 1 key (returning list AW33,AW35,AW39):

<?xml version="1.0"?>
<xsl:stylesheet version="2.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:ext = "http://extension.unit4.com"
    exclude-result-prefixes="xs">
    <xsl:output method="xml" indent="yes"/>

    <xsl:template match="/">
        <root>
            <xsl:variable name="tempVariable" select="ext:get-mappingtable-list('AGB code to message type list mappings','42424242','messageTypes')"/>
            <first_item>
                <!-- returns: 'AW33' -->
                <xsl:value-of select="$tempVariable[1]" />
            </first_item>
            <second_item>
                <!-- returns: 'AW35' -->
                <xsl:value-of select="$tempVariable[2]" />
            </second_item>
        </root>
    </xsl:template>
</xsl:stylesheet>

Example XSLT using get-mappingtable-list with 1 key (returns AW301,AW302):

<?xml version="1.0"?>
<xsl:stylesheet version="2.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:ext = "http://extension.unit4.com"
    exclude-result-prefixes="xs">
    <xsl:output method="xml" indent="yes"/>

    <xsl:template match="/">
        <root>
            <xsl:for-each select="ext:get-mappingtable-list('AGB code to message type list mappings','12121212','messageTypes')">
                <item>
                    <!-- returns: 'AW34' in first loop -->
                    <!-- returns: 'AW36'in second loop -->
                    <!-- returns: 'AW310'in second loop -->
                    <xsl:value-of select="."/>
                </item>
            </xsl:for-each>
        </root>
    </xsl:template>
</xsl:stylesheet>