This document is relevant for releases after v. 3.0.8928.448.

Link's XSLT handling provides a set of methods which can be called from within XSLT. The methods give access to various data points from Link related to the document, partners and interchanges involved in the current flow, as well as providing an interface for performing conversion table lookups.

The library providing the methods is injected into the XSLT engine at runtime as an extension object using the namespace “http://link/xslt“, so in order to call the library methods from an XSLT script, it needs to reference this namespace and define a namespace prefix for it.

Here is an example XSLT calling every available method:

<?xml version="1.0" encoding="utf-16"?>
<xsl:stylesheet xmlns:func="http://link/xslt" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:msxsl="urn:schemas-microsoft-com:xslt" exclude-result-prefixes="msxsl s0 func" version="1.0" xmlns:s0="http://XsltFunctionsTest.Input" xmlns:ns0="http://XsltFunctionsTest.Output">
  <xsl:output omit-xml-declaration="yes" method="xml" version="1.0"/>
  <xsl:template match="/">
    <xsl:apply-templates select="/s0:Root"/>
  </xsl:template>
  <xsl:template match="/s0:Root">
    <ns0:Root>


      <Document>
        <DocumentType>
          <xsl:value-of select="func:GetDocumentTypeName()"/>
        </DocumentType>
        <MessageNumberIn>
          <xsl:value-of select="func:GetDocumentMessageNumberIn()"/>
        </MessageNumberIn>
        <MessageNumberOut>
          <xsl:value-of select="func:GetDocumentMessageNumberOut()"/>
        </MessageNumberOut>
        <DocumentNumber>
          <xsl:value-of select="func:GetDocumentNumber()"/>
        </DocumentNumber>
      </Document>

      <DocumentConfigIn>
        <Format>
          <xsl:value-of select="func:GetDocumentFormatIn()"/>
        </Format>
        <Variant>
          <xsl:value-of select="func:GetDocumentVariantIn()"/>
        </Variant>
        <Version>
          <xsl:value-of select="func:GetDocumentVariantVersionIn()"/>
        </Version>
      </DocumentConfigIn>

      <DocumentConfigOut>
        <Format>
          <xsl:value-of select="func:GetDocumentFormatOut()"/>
        </Format>
        <Variant>
          <xsl:value-of select="func:GetDocumentVariantOut()"/>
        </Variant>
        <Version>
          <xsl:value-of select="func:GetDocumentVariantVersionOut()"/>
        </Version>
      </DocumentConfigOut>

      <Distribution>
        <ConfigurationKeys>
          <UNBOverride>
            <xsl:value-of select="func:LookupDistributionConfigurationKey('UNBOverride')"/>
          </UNBOverride>
        </ConfigurationKeys>
      </Distribution>

      <InterchangeIn>
        <InterchangeNumber>
          <xsl:value-of select="func:GetInterchangeInNumber()"/>
        </InterchangeNumber>
        <InterchangeGuid>
          <xsl:value-of select="func:GetInterchangeInInterchangeGuid()"/>
        </InterchangeGuid>
        <TransmissionId>
          <xsl:value-of select="func:GetInterchangeInTransmissionId()"/>
        </TransmissionId>
        <DisplayAddress>
          <xsl:value-of select="func:GetInterchangeInDisplayAddress()"/>
        </DisplayAddress>
        <PortName>
          <xsl:value-of select="func:GetInterchangeInPortName()"/>
        </PortName>
        <FormatType>
          <xsl:value-of select="func:GetInterchangeInFormatType()"/>
        </FormatType>
      </InterchangeIn>

      <PartnerIn>
        <Name>
          <xsl:value-of select="func:GetPartnerInName()"/>
        </Name>
        <PartnerKey>
          <xsl:value-of select="func:GetPartnerInPartnerKey()"/>
        </PartnerKey>
        <Comment>
          <xsl:value-of select="func:GetPartnerInComment()"/>
        </Comment>
        <IsInternal>
          <xsl:value-of select="func:GetPartnerInIsInternal()"/>
        </IsInternal>
        <IsDeleted>
          <xsl:value-of select="func:GetPartnerInIsDeleted()"/>
        </IsDeleted>
        <MainId>
          <xsl:value-of select="func:GetPartnerInMainId()"/>
        </MainId>
        <GLN>
          <xsl:value-of select="func:LookupPartnerInIdByKey('GLN')"/>
        </GLN>
        <VendorNumber>
          <xsl:value-of select="func:LookupPartnerInConfigurationKey('VendorNumber')"/>
        </VendorNumber>
      </PartnerIn>

      <PartnerOut>
        <Name>
          <xsl:value-of select="func:GetPartnerOutName()"/>
        </Name>
        <PartnerKey>
          <xsl:value-of select="func:GetPartnerOutPartnerKey()"/>
        </PartnerKey>
        <Comment>
          <xsl:value-of select="func:GetPartnerOutComment()"/>
        </Comment>
        <IsInternal>
          <xsl:value-of select="func:GetPartnerOutIsInternal()"/>
        </IsInternal>
        <IsDeleted>
          <xsl:value-of select="func:GetPartnerOutIsDeleted()"/>
        </IsDeleted>
        <MainId>
          <xsl:value-of select="func:GetPartnerOutMainId()"/>
        </MainId>
        <CVR>
          <xsl:value-of select="func:LookupPartnerOutIdByKey('CVR')"/>
        </CVR>
        <CustomerNumber>
          <xsl:value-of select="func:LookupPartnerOutConfigurationKey('CustomerNumber')"/>
        </CustomerNumber>
      </PartnerOut>

      <ConversionTables>
        <Lookup1>
          <xsl:value-of select="func:ConversionLookupGlobalValue('Table1', 'LookupColumn1', 'Column1', 'Column1Value')"/>
        </Lookup1>
        <Lookup2>
          <xsl:value-of select="func:ConversionLookupPartnerInValue('Table2', 'LookupColumn2', 'Column1', 'Column1Value', 'Column2', 'Column2Value')"/>
        </Lookup2>
        <Lookup3>
          <xsl:value-of select="func:ConversionLookupPartnerOutValue('Table3', 'LookupColumn3', 'Column1', 'Column1Value', 'Column2', 'Column2Value', 'Column3', 'Column3Value')"/>
        </Lookup3>
      </ConversionTables>

      <LinkSettings>
        <Setting1>
          <xsl:value-of select="func:GetSettingValue('Setting1')"/>
        </Setting1>
      </LinkSettings>

      <ErrorHandling>
        <FailDocument>
          <xsl:value-of select="func:RaiseError('No lines found in order.', false())"/>
        </FailDocument>
        <FailDocumentWithErrorCode>
          <xsl:value-of select="func:RaiseError('No lines found in order.', 'RT62W', false())"/>
        </FailDocumentWithErrorCode>
        <IgnoreDocument>
          <xsl:value-of select="func:RaiseError('No lines found in order.', 'RT62W', 'Ignored', false())"/>
        </IgnoreDocument>
      </ErrorHandling>

      <ContextProperties>
        <TestProperty>
          <xsl:value-of select="func:GetContextPropertyValue('SomeProperty', 'http://schemas.bizbrains.com/properties/test')"/>
        </TestProperty>
      </ContextProperties>

      <xsl:variable name="test" select="func:SetContextPropertyValue('SomeProperty', 'http://schemas.bizbrains.com/properties/test', 'SomeValue')" />

    </ns0:Root>
  </xsl:template>
</xsl:stylesheet>

The same example is available in the Visual Studio project template where it’s possible to debug into the XSLT.

Methods

Document

These are the methods that retrieve data related to the document being mapped.

GetDocumentTypeName()

This returns the name of the DocumentType the document has, e.g. SalesOrder, Invoice, Freight Note, etc.

GetDocumentMessageNumberIn()

MessageNumberIn is an internal Link Property. It is usually empty.

GetDocumentMessageNumberOut()

MessageNumberOut is an internal Link property. It is used in some cases to assign an internally unique ID to each message in a batch.

GetDocumentNumber()

This method fetches the DocumentNumber of the current document, if one has been promoted. The DocumentNumber property is usually the “logical” ID of a document, so if it’s an invoice it’s the invoice number, if it’s an order it’s the order number, etc.

GetDocumentFormatIn() / GetDocumentFormatOut()

These methods return the name of the Link Format defined in the ingoing and outgoing DocumentConfig of this document.

GetDocumentVariantIn() / GetDocumentVariantOut()

These methods return the name of the Link Variant defined in the ingoing and outgoing DocumentConfig of this document.

GetDocumentVariantVersionIn() / GetDocumentVariantVersionOut()

These methods return the name of the Link VariantVersion defined in the ingoing and outgoing DocumentConfig of this document.

Distribution

These are the methods that retrieve data related to the distribution this document is matched to.

LookupDistributionConfigurationKey(string keyname)

If a configuration key has been defined on the distribution this document is using, the value of the key can be extracted with this method.

InterchangeIn

These are the methods that retrieve data related to the ingoing interchange of the document being mapped.

GetInterchangeInNumber()

Interchange number is an identification of the interchange received by Link. It can be provider from the sending system. It is not a mandatory field, and will therefore not always be set. It is most often used when receiving EDIFACT interchanges.

GetInterchangeInInterchangeGuid()

InterchangeGuid is an iternal identification of the received interchange. It is set by Link, and is alway unique.

GetInterchangeInTransmissionId()

TransmissionId is an identfier representing the transmission of an data interchange to Link. It can be provided by the sending system, and is not a mandatory field.

GetInterchangeInDisplayAddress()

The display address of an interchange indicates where it came from. This could for instance be something like sftp://sftp.customername.com:22/Outgoing/SalesOrders/*.xml.

GetInterchangeInPortName()

This is the name of the channel through which an interchange has been received by Link. This could for instance be an ingoing or outgoing transport location.

GetInterchangeInFormatType()

This indicates the format type of the ingoing interchange, e.g. Xml, Json, Edifact, etc.

Partners

These are the methods that retrieve data related to the partners (sender/receiver) of the document being mapped.

GetPartnerInName() / GetPartnerOutName()

As the names imply, these methods return the name of the ingoing and outgoing partners, respectively.

GetPartnerInPartnerKey() / GetPartnerOutPartnerKey()

PartnerKey is an internal unique identifier for a partner in Link.

GetPartnerInComment() / GetPartnerOutComment()

If anything has been written in the comment field of one of the partners in Link, these methods can be used to retrieve it.

GetPartnerInIsInternal() / GetPartnerOutIsInternal()

Used to determine if a partner is an internal or external Link partner.

GetPartnerInIsDeleted() / GetPartnerOutIsDeleted()

Used to determine if one of the partners does exist in Link but have been marked as deleted.

GetPartnerInMainId() / GetPartnerOutMainId()

Gets the value of the identification marked as default on the ingoing and outgoing partner, respectively.

LookupPartnerInIdByKey(string qualifier) / LookupPartnerOutIdByKey(string qualifier)

Looks up the value of a partner identification based on a qualifier. If the partner has multiple identifications with the same qualifier, the one marked as default (if one of them is) is returned, or the first one found if not.

LookupPartnerInConfigurationKey(string keyname) / LookupPartnerOutConfigurationKey(string keyname)

This returns the value of a given partner configuration key if it has a value.

Conversion

These are the methods for doing lookups in conversion tables.

ConversionLookup[LookupType]Value(string conversiontablename, string returncolumn, string searchcolumn[N], string searchvalue[N], …, string suppressExceptions)

This is a template for the methods used for performing a conversion table lookup.

There are three types of lookup:

Global

Using the method ConversionLookupGlobalValue() will only look for global values in the conversion table indicated in the method call.

PartnerIn

Using the method ConversionLookupPartnerInValue() will look for partner specific values for the ingoing partner in the conversion table indicated in the method call, falling back to global values if no value can be matched for the specific partner.

PartnerOut

Using the method ConversionLookupPartnerOutValue() will look for partner specific values for the outgoing partner in the conversion table indicated in the method call, falling back to global values if no value can be matched for the specific partner.

Here is a description of the functionality associated with each of the input parameters.

string conversiontablename

This is the name of the conversion table to perform the lookup in.

string returncolumn

This is the name of the column in the conversion table that you want the value returned from.

string searchcolumn[N]

This is the name of the Nth column you want to match on in your conversion table lookup.

string searchvalue[N]

This is the value you want to match the above column on.

Each of the three lookup types support between 1 and 5 pairs of search columns and search values.

string suppressExceptions

This parameter is optional. If it is not used in a call, the lookup method will never fail, it will simply return an empty string if anything goes wrong, such as the conversion table not existing, or one of the lookup values being blank. If you explicitly want the map to fail in one of those situations, add the parameter to the end of the call as false() or ‘false’.

While the parameter is logically a boolean value, it is implemented as a string to make it “play nice” with XSLT.

Link settings

Should you have a need for it, you can get the value of any Link setting on the system.

GetSettingValue(string key)

Returns the value of the setting.

Error handling

These are the methods used for error handling.

RaiseError(string message, string retryAllowed)

This method is used for making a document intentionally go into Failed status in Link.

There can be many reasons for wanting to do this. Say for instance that you know that you sometimes get an order where one of the lines is missing the EAN number of the product. You also know that this will make the order impossible to process in your system. You may prefer in this situation to have the order fail in Link with a clear error message stating exactly why it failed, rather than having it sent on to your system and have to deal with it there.

In that case you can check the existence of the EAN number in the XSLT, and if it is missing you can call this method with a message saying that the EAN number is missing.

The retryAllowed parameter should always be set to false() or ‘false’ except in very specific cases. Any error that stems from faulty input data will not be resolved by trying to map the faulty data again. While the parameter is logically a boolean value, it is implemented as a string to make it “play nice” with XSLT.

RaiseError(string message, string errorCode, string retryAllowed)

This method is the same as above, but allows you to register the error with a specific error code. If you have a known error scenario that you know a specific department needs to take care of, you can register the error code in Link and assign a specific stakeholder to it. Then any time a document fails with that specific error code, the stakeholder will be notified.

RaiseError(string message, string errorCode, string documentStatus, string retryAllowed)

This method is the same as above, but allows you to set a specific document status rather than defaulting to “Failed”.

The practical use for this is making a document intentionally go into Ignored status in Link.

There can be many reasons for wanting to do this. Say for instance that you know that you sometimes get an order with no lines. You know that this happens due to an error in some customer’s system from time to time, and does not need any action from your side. Rather than having the faulty but unimportant order sent on to your system, it may be better to simply halt the processing of it in Link, and put a message on it saying why it has been ignored.

Context Properties

If your XSLT is being executed within Link, you can access the context properties of the message from the extension object.

GetContextPropertyValue(string propertyName, string propertyNamespace)

This method returns the value of the given context property from the message, or an empty string if the property does not exist.

SetContextPropertyValue(string propertyName, string propertyNamespace, string value)

This method writes a value to the message context.

Utility functions

The extension object also contains a few methods that do not extract any data from Link, but which can be useful in various mapping scenarios.

ConvertDate(string dateToConvert, string inputFormat, string outputFormat)

This method converts a date(time) from one format to another. The two format parameters use the standard .NET DateTime formatstring format.

ReturnNumberFormat(string number, string formatMask)

This method formats a number using a standard .NET number format mask.

Replace(string value, string replaceFrom, string replaceTo)

This method performs a string replace operation on value, replacing all instances of replaceFrom with replaceTo.

DateAdd(string dateTime, string format, string days, string months, string years)

Takes an input date and time string, which must be in the specified format, adds the given number of days, months, and years to it, and returns the resulting date and time formatted according to the same format.

TimeAdd(string dateTime, string format, string hours, string minutes)

Takes an input date and time string, which must be in the specified format, adds the given number of hours, and minutes to it, and returns the resulting date and time formatted according to the same format.

GetLocalDateTime()

Gets the current local date and time formatted according to the standard XML date and time format mask.

GetLocalDateTime(string formatMask)

Gets the current local date and time formatted according to the specified format mask.

GetUtcDateTime()

Gets the current UTC date and time formatted according to the standard XML date and time format mask.

GetUtcDateTime(string formatMask)

Gets the current UTC date and time formatted according to the specified format mask.

MathRound(string number, string decimals)

Round the given number to the specified number of decimal places using away-from-zero rounding.

RegexReplace(string input, string pattern, string replacement)

Apply the given regular expression pattern to substitute parts of the input string with the specified replacement string.

SplitString(string input, string separator, string index)

Divide the input string into segments using the given separator string and return the segment at the specified index (starting from 0). If no segment matches the index, an empty string is returned.

ToUpper(string input)

Transform the entire input string to uppercase.

ToLower(string input)

Transform the entire input string to lowercase.

XSLT functions