4.5.2.1. Structure of the definition.xml file

The definition.xml file defines which parameters are exposed to the user, and defines all the steps that the user will go through to configure and deploy the connector. The file is static in the sense that we cannot make it dynamic with JSP and introduce conditional parameters or steps.

Structure

The structure of the definition.xml file consists of the following sections:

1. Name / Description of the connector. 
2. Definition of parameters (that will be later used in the channels.xml.jsp file or in any other files)
3. Steps that the user will go through to configure the connector. 

Example

Support of languages

As shown in the example above, the definition.xml file supports multiple languages to allow the user to go through the configuration steps & parameters in the same language as the one configured in the Babelway platform. 

XML tags that support the “lang” attribute (by default, if omitted, english will be used):

<name lang=”[fr|de|en|nl]”>
<description lang=”[fr|de|en|nl]”>
<label lang=”[fr|de|en|nl]”>
<tooltip lang=”[fr|de|en|nl]”>
<introduction lang=”[fr|de|en|nl]”>

Parameters

Parameters have the following mandatory structure: 

<parameters>
     <parameter>
         <name>InEmailAddress</name>
         <type><class>SmtpUserName</class></type>
         <label>IN Email Address</label>
         <tooltip>Email address on which CSV file are received</tooltip>
     </parameter>
     [...]
</parameters>

The name must be unique and must be referenced in one of the steps of the connector. If not, an error message will be displayed when the zip file is uploaded. It’s a technical name and is never displayed to the end-user when he will configure his connector.

The type of the parameter must be the exact same type as the parameter defined in the channels.xml file. In the example above, the parameter type is SmtpUserName, which is the exact same type as the parameter of the gateway that we would like to replace.

<GatewayInfo>
   <Gateway>43134</Gateway>
   <Type>GATEWAY_IN_SMTP_IN</Type>
   [...]
   <Parameters type="UnmodifiableMap">
      [...]
      <username type="SmtpUserName">${InEmailAddress}</username>
      [...]
   </Parameters>
</GatewayInfo>

The label and tooltip will be displayed to the end-user when he configures his connector. The label must tell what the parameter is, and the tooltip can contain some additional information that the end-user will see when he mouse-over the parameter. They both support the “lang” attribute to display them in the same language as the end-user. 

Example:

 

Mandatory/Optional

By default, all parameters defined in the definition.xml file are mandatory, meaning that if the end-user does not enter any value for them, the connector will not be deployable.

The XML tag “mandatory” allows to specify this:

<parameter>
    <name>InEmailAddress</name>
    <type><class>SmtpUserName</class></type>
    <label>IN Email Address</label>
    <tooltip>Email address on which CSV file are received</tooltip>
    <mandatory>true|false</mandatory>
</parameter>

AllowedValues/StringAllowedValues

In case you want to suggest a list of possible values to the user, the StringAllowedValues/AllowedValues tag can be used to pre-defined the list which will be displayed in a dropdown to the end-user using the connector. 

Some examples:

<parameter>
  <name>MyEmailAddress</name>
  <type>
      <class>EmailAddress</class>
      <AllowedValues type="EmailAddress[]">
      <AllowedValue>[e-mail]</AllowedValue>
      <AllowedValue>[e-mail]</AllowedValue>
      </AllowedValues>
  </type>
  <label>Email address</label>
  <tooltip>List of possible email addresses where to send the message</tooltip>
</parameter>
<parameter>
   <name>GatewayOutType</name>
   <type>
       <class>String</class>
       <StringAllowedValues type="String[]">
       <StringAllowedValue>CloudScan</StringAllowedValue>
       <StringAllowedValue>ScanIO</StringAllowedValue>
       </StringAllowedValues>
   </type>
   <label>Tradeshift Connection Type</label>
   <tooltip>CloudScan or ScanIO</tooltip>
</parameter>

Default value

You can also define a default-value that will be displayed when the user instantiates the connector. This is done with the default-value XML tag as follow:

<parameter>
    <name>username</name>
    <type>
          <class>String</class>
    </type>
    <label>Username</label>
    <tooltip>The username to connect to SFTP</tooltip>
    <default-value>christian</default-value>
</parameter>

For parameters of type Array ([]), the structure is a bit different. Below you can find a complex example on how to define a list of supported PEPPOL documents with some default value.
You can also notice some other parameters that can be set on Array like MinSize, MaxSize, AllowNullElements

<parameter>
  <name>P6</name>
  <type>
   <class>PeppolDocument[]</class>
   <MinSize>1</MinSize>
   <MaxSize>2</MaxSize>
   <AllowNullElements>false</AllowNullElements>
   <ElementsValueDescription>
      <ValueClass>PeppolDocument</ValueClass>
      <AllowedValues type="PeppolDocument[]">
          <AllowedValue>PEPPOL_INVOICE_P5_2_C10_2_V2_1</AllowedValue>
          <AllowedValue>PEPPOL_INVOICE_04_T10</AllowedValue>
      </AllowedValues>
   </ElementsValueDescription>
  </type>
  <label>P6</label>
  <tooltip>P6T</tooltip>
  <default-value>
   <Array type="PeppolDocument[]">
    <Element>PEPPOL_INVOICE_P5_2_C10_2_V2_1</Element>
   </Array>
  </default-value>
</parameter>