4.5.2.2. Structure of the channel.xml file – Babelway

To be able to use the parameters defined in the definition.xml file in the channel.xml file, we need to use a templating language. For the moment, Babelway only supports the JSP templating language.

JSP templating language

In order to use the JSP language, we need to convert our channels.xml file, into a JSP file. This happens to be extremely simple:

Change the extension of the file to JSP - rename channels.xml to channels.xml.jsp
Add the following JSP headers at the beginning of the file

<%@ page contentType="text/xml; charset=UTF-8" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="fn" uri="http://java.sun.com/jsp/jstl/functions" %>
<%@ taglib prefix="display" uri="/babelway/display" %>

That’s it! You're now ready to reference the parameters defined in your definition.xml file from your channels.xml.jsp using placeholders: ${parameterName}. Note that you can use the whole power of JSP (<c:if>, <c:choose>, ...) to do additional complex logic in your channels.xml.jsp.

PDF template parameter

Steps:

As soon as you export a channel with a PDF template parameter, the export will generate a parameter of type PdfTemplate[] in the definition.xml file. The structure will be as follows:

<parameter>
       <name>PdfTemplate</name>
       <type>
          <class>PdfTemplate[]</class>
          <ForceFieldsToBeExtracted>
              <Element type="PdfMessageDefinitionSimpleFieldDescription"> [...]</Element>
              <Element type="PdfMessageDefinitionSimpleFieldDescription"> [...]</Element>
              <Element type="PdfMessageDefinitionSimpleFieldDescription"> [...]</Element>
              [...]
              <Element type="PdfMessageDefinitionTableFieldDescription">
                   <Name>LineItems</Name>
                   <TableFields>
                     <TableField>
                       <Name>InvoiceLineQuantity</Name>
                     </TableField>
                     [...]
                   </TableFields>
             </Element>
         </ForceFieldsToBeExtracted>
      </type>
      <label>PDF Template</label>
      <tooltip>Define extraction rules based on the PDF template you will be sending</tooltip>
</parameter>

Note that the validations and the description in the node of the Message Definition tree are exported automatically as well, so you can configure everything in the Message Definition tree before the export.

In the channel.xml file, delete the whole XML tag (and children) <Templates> and replace it with the following instructions:

<MessageDefinitionInfo>
      <MessageDefinition>787116</MessageDefinition>
      <Direction>IN</Direction>
      <Type>PDF</Type>
      [...]
      <Parameters type="UnmodifiableMap">
         [...]
        <forcedFieldsToExtract type="PdfMessageDefinitionFieldDescription[]">
          <Element type="PdfMessageDefinitionSimpleFieldDescription">
            <Name>InvoiceNumber</Name>
          </Element>
          <Element type="PdfMessageDefinitionSimpleFieldDescription">
            <Name>InvoiceDate</Name>
          </Element>
          <Element type="PdfMessageDefinitionSimpleFieldDescription">
            <Name>InvoiceTypeCode</Name>
          </Element>
          <Element type="PdfMessageDefinitionSimpleFieldDescription">
            <Name>InvoiceNote</Name>
          </Element>
           [...]
        </forcedFieldsToExtract>
        <SplitTextWhenDoubleSpace type="Boolean">true</SplitTextWhenDoubleSpace>
         <!-- Instead of the Templates XML tag, replace it with the following line - 
             it will serialize the parameter ‘PdfTemplate’ defined in the definition.xml 
             to produce a new XML tag ‘Templates’ -->
         ${display:xmlSerialize('Templates', PdfTemplate)}
        <ValidationMode type="ValidationMode">loose</ValidationMode>
        [...]
     </Parameters>
</MessageDefinitionInfo>

Description and tooltip

To ease the integration with the end-user, a description can be added to each PDF field that will be displayed in the PDF Editor as a tooltip when the user mouses-over the field.

<Element type="PdfMessageDefinitionSimpleFieldDescription">
          <Name>InvoiceTypeCode</Name>
          <Description>Please indicate the document type by inputting a 
                       document type code: either 380 for invoice, or 381 for credit note
          </Description>
</Element>

Validation of PDF fields

It is possible to add some validations on each PDF extracted field, so that when the end-user will extract fields from its PDF, he will get an immediate feedback whether the extraction is valid or not.

The recommended way to add validation is to add them before the export in the MD tree, so that the validation is not only on the PDF UI screen, but also when processing messages.

<Element type="PdfMessageDefinitionSimpleFieldDescription">
         <Name>InvoiceTypeCode</Name>
         <Description>Please indicate the document type by inputting a document type code: 
                      either 380 for invoice, or 381 for credit note
         </Description>
         <Validations>
               <Validation>
                     <Type>mandatory</Type>
                     <Assertion></Assertion>
               </Validation>
               <Validation>
                     <Type>maxLength</Type>
                     <Assertion>3</Assertion>
               </Validation>
               <Validation>
                     <Type>minLength</Type>
                     <Assertion>3</Assertion>
               </Validation>
               <Validation>
                     <Type>regexp</Type>
                     <Assertion>380|381</Assertion>
               </Validation>
         </Validations>
</Element>

Validation will be displayed in the same tooltip when the user mouses-over the field:

Generic gateway

In some use cases, we would like that the gateway IN or OUT of the connector is generic and we want to let the end-user decide which protocol suits him best. For this purpose, connectors allows you to define a generic gateway IN / OUT as a parameter in the definition.xml file.

Below is an example of such a parameter with a list of allowed gateway types. In this example, the end-user can choose between 4 types of gateways: HTTP, EMAIL, SFTP Server or AS2.

<parameter>
   <name>GatewayIN</name>
   <type>
      <class>GatewayInfo</class>
      <direction>IN</direction>
      <GatewayTypeAllowedValues type="GatewayType[]">
           <GatewayTypeAllowedValue>GATEWAY_IN_SFTP_IN</GatewayTypeAllowedValue>
           <GatewayTypeAllowedValue>GATEWAY_IN_SMTP_IN</GatewayTypeAllowedValue>
           <GatewayTypeAllowedValue>GATEWAY_IN_HTTP_IN</GatewayTypeAllowedValue>
           <GatewayTypeAllowedValue>GATEWAY_IN_AS2_IN</GatewayTypeAllowedValue>
      </GatewayTypeAllowedValues>
  </type>
  <label>Gateway IN</label>
  <tooltip>Specify how you want to upload the messages!</tooltip>
</parameter>

Afterwards, this parameter must be referenced in the channels.xml.jsp file as follows:

<GatewayInfo>
      <Gateway>1</Gateway>
      <Type>${GatewayIN.type}</Type>
      <CreationMoment>2019-10-25T01:12:03.258+02:00</CreationMoment>
      <LastUpdateMoment>2019-10-25T01:12:03.308+02:00</LastUpdateMoment>
      <Name>Gateway IN</Name>
      <Hub>101</Hub>
      ${display:xmlSerialize('Parameters', GatewayIN.parameters)}
      <ExtraProcessings>
      </ExtraProcessings>
</GatewayInfo>

Note that the function xmlSerialize is a specific Babelway defined function.

Lookup table

Lookup tables used in channels will also be exported in the channels.xml file, but only their structure. Lookup table row data is not exported.

Certificate

Trusted certificates and private keys are not part of the export, for security reasons. However, it is still possible to build a connector that relies on a certificate (public or private).

Prerequisites:

The certificate must always be present in the environment where the connector definition has been built and uploaded.

Steps:

Find the parameter in the channels.xml where the certificate alias is defined.
Prepend the certificate alias with the keyword importFromHub:
This will indicate to Babelway that when deploying the connector, this certificate must be imported from the environment (hub) where the connector definition has been uploaded.

Here is an example with an AS2 gateway that has a trusted certificate to verify the AS2 signature generated by Tradeshift. The certificate has the alias “tradeshift” in this example and has been uploaded to the environment where the connector definition is installed.

<GatewayInfo>
      <Gateway>53550</Gateway>
      <Type>GATEWAY_IN_AS2_IN</Type>
      [...]      
      <Name>AS2 IN (TRADESHIFT)</Name>
      <Hub>101</Hub>
      <Parameters type="UnmodifiableMap">
        [...]
        <messageSignatureEnforced type="Boolean">true</messageSignatureEnforced>
        <certificateForVerification type="KeystoreCertAlias">importFromHub:tradeshift
        </certificateForVerification>
        [...]
      </Parameters>
</GatewayInfo>