LinkProxy - XSLT

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.rest.proxy/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:LinkProxy="http://link.rest.proxy/xslt" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:msxsl="urn:schemas-microsoft-com:xslt" exclude-result-prefixes="msxsl s0 LinkProxy" version="1.0" xmlns:s0="http://XsltProxyTest.Input" xmlns:ns0="http://XsltProxyTest.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="LinkProxy:GetDocumentTypeName()"/>
        </DocumentType>
        <MessageNumberIn>
          <xsl:value-of select="LinkProxy:GetDocumentMessageNumberIn()"/>
        </MessageNumberIn>
        <MessageNumberOut>
          <xsl:value-of select="LinkProxy:GetDocumentMessageNumberOut()"/>
        </MessageNumberOut>
        <DocumentNumber>
          <xsl:value-of select="LinkProxy:GetDocumentNumber()"/>
        </DocumentNumber>
      </Document>

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

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

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

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

      <InterchangeOut>
        <InterchangeNumber>
          <xsl:value-of select="LinkProxy:GetInterchangeOutNumber()"/>
        </InterchangeNumber>
        <InterchangeGuid>
          <xsl:value-of select="LinkProxy:GetInterchangeOutInterchangeGuid()"/>
        </InterchangeGuid>
        <TransmissionId>
          <xsl:value-of select="LinkProxy:GetInterchangeOutTransmissionId()"/>
        </TransmissionId>
        <DisplayAddress>
          <xsl:value-of select="LinkProxy:GetInterchangeOutDisplayAddress()"/>
        </DisplayAddress>
        <PortName>
          <xsl:value-of select="LinkProxy:GetInterchangeOutPortName()"/>
        </PortName>
        <FormatType>
          <xsl:value-of select="LinkProxy:GetInterchangeOutFormatType()"/>
        </FormatType>
      </InterchangeOut>

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

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

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

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

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

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

    </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.

Interchanges

These are the methods that retrieve data related to the interchanges of the document being mapped. Keep in mind that in most normal mapping scenarios, the outgoing interchange will not yet have been created at the time the map is executed, so you should not use the methods related to the outgoing interchange unless you are certain that the outgoing interchange will exist at that point.

GetInterchangeInNumber() / GetInterchangeOutNumber()

InterchangeNumber is an internal Link property. It is primarily used for assigning a unique ID to a document batch.

GetInterchangeInInterchangeGuid() / GetInterchangeOutInterchangeGuid()

InterchangeGuid is an internal Link unique identifier assigned to each ingoing or outgoing interchange.

GetInterchangeInTransmissionId() / GetInterchangeOutTransmissionId()

TransmissionId is an internal Link property assigned to an ingoing or outgoing transmission, receiving or sending interchanges, for traceability purposes.

GetInterchangeInDisplayAddress() / GetInterchangeOutDisplayAddress()

The display address of an interchange indicates where it came from (in the case of an ingoing interchange) or where it was sent to (in the case of an outgoing interchange). This could for instance be something like sftp://sftp.customername.com:22/Outgoing/SalesOrders/*.xml.

GetInterchangeInPortName() / GetInterchangeOutPortName()

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

GetInterchangeInFormatType() / GetInterchangeOutFormatType()

This indicates the format type of the ingoing or outgoing 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], …)

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.

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, bool 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 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.

RaiseError(string message, string errorCode, bool 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, bool 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 proxy class.

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.

Data manipulation

The proxy library 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.