Maps: Difference between revisions

From Commander4j
Created page with "A map in simple terms is a configuration which defines what you want the middleware to take as input and what you want it to generate as output. The middleware can handle multiple maps and each map can have 1 inbound connection and multiple outbound connections. The configuration for maps is within an xml file called config.xml An example of a map is shown below. In this example the system is configured to read an xml file and write the data out to 2 files, one ASCII..."
 
Updated by push_wiki.py
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
A map in simple terms is a configuration which defines what you want the middleware to take as input and what you want it to generate as output.
A Map is the core configuration unit in Middleware4j. Each map defines a complete message transformation pipeline: where to read data from, how to transform it, and where to send the result. Multiple maps can run simultaneously, each in its own background thread.


The middleware can handle multiple maps and each map can have 1 inbound connection and multiple outbound connections.
== Structure ==


The configuration for maps is within an xml file called config.xml
Each map consists of:


An example of a map is shown below. In this example the system is configured to read an xml file and write the data out to 2 files, one ASCII (flat file) and one CSV (Comma separated variables file).
* One '''input connector''' — monitors a directory and reads incoming files
* One or more '''output connectors''' — writes the transformed result to one or more destinations
* Optional '''XSLT stylesheets''' on input and/or output for data transformation
* Optional '''conditions''' on each output for content-based routing


== How a Map Processes a File ==


    <map id="map413" enabled="Y"
# The input connector polls its configured directory at the set interval (default 1000 ms).
        description="GEN C4J Prod Dec XML to Dual Output (ASCII and CSV Files)">
# When a file matching the file mask arrives, it is read and converted to an internal XML document by the input connector.
        <input id="in1" description="Read XML File">
# If an input XSLT stylesheet is configured, it is applied to transform the XML.
            <type>XML</type>
# Each output connector is evaluated in turn:
            <path>./interface/input/413 (GEN XML to Dual Output)</path>
## If a '''condition''' is configured, the output is only activated when the condition evaluates to true.
            <mask/>
## If activated, an optional output XSLT stylesheet is applied.
            <pollingInterval>1000</pollingInterval>
## The result is written to the output destination by the output connector.
            <XSLT/>
# The original input file is moved to a backup location.
        </input>
# If any step fails, the file is renamed with an <code>.error</code> extension and an email notification is sent (if email is configured).


        <output id="out1" enabled="Y" description="Write ASCII File">
== Configuration ==
            <path>./interface/output/413 (GEN Dual Output ASCII and CSV)</path>
            <type>ASCII</type>
            <outputPattern>1-10,12-21,23-32</outputPattern>
            <outputFileExtension>txt</outputFileExtension>
            <XSLT>C4J_PRODDEC_XML_to_ASCII_Flat_File.xsl</XSLT>
        </output>


        <output id="out2" enabled="Y" description="Write CSV">
Maps are defined in the main <code>config.xml</code> file. A minimal map looks like this:
            <path>./interface/output/413 (GEN Dual Output ASCII and CSV)</path>
            <type>CSV</type>
            <optionDelimeter>^</optionDelimeter>
            <csvOptions>separator=,^quote=""</csvOptions>
            <outputFileExtension>csv</outputFileExtension>
            <XSLT>C4J_PRODDEC_XML_to_SAGEX3_GoodsReceipt_CSV.xsl</XSLT>
        </output>
    </map>


<syntaxhighlight lang="xml">
<map>
  <id>Map01</id>
  <enabled>true</enabled>
  <description>ASCII File to CSV</description>
  <enableEmailNotifications>true</enableEmailNotifications>
  <connectors>
    <input>
      <id>in1</id>
      <type>ASCII</type>
      <url>
        <path>./interface/input/Map01</path>
        <mask/>
        <pollingInterval>1000</pollingInterval>
      </url>
      <xsl>
        <XSLT>Map01_ASCII_to_CSV.xsl</XSLT>
      </xsl>
      <ascii>
        <pattern>1-10,12-21,23-32</pattern>
      </ascii>
    </input>
    <output>
      <id>out1</id>
      <type>CSV</type>
      <url>
        <path>./interface/output/Map01</path>
      </url>
    </output>
  </connectors>
</map>
</syntaxhighlight>


Refer to [[Example Configuration]] for a overview of how maps and connectors work.
== Key Settings ==
 
=== Map Level ===
 
{| class="wikitable"
|-
! Setting !! Description
|-
| '''id''' || Unique identifier for this map (e.g. Map01)
|-
| '''enabled''' || true/false — disabled maps are loaded but do not run
|-
| '''description''' || Human-readable description shown in the GUI
|-
| '''enableEmailNotifications''' || Whether to send error emails for this map
|}
 
=== Input Connector ===
 
{| class="wikitable"
|-
! Setting !! Description
|-
| '''type''' || The connector type: ASCII, CSV, XML, IDOC, Excel, EMAIL, RAW, PDF_PRINT
|-
| '''path''' || The directory to monitor for incoming files
|-
| '''mask''' || File extension filter (leave empty to process all files)
|-
| '''pollingInterval''' || How often to check the directory, in milliseconds
|-
| '''xsl / XSLT''' || Optional XSLT stylesheet to apply after reading
|}
 
=== Output Connector ===
 
{| class="wikitable"
|-
! Setting !! Description
|-
| '''type''' || The connector type: ASCII, CSV, XML, SOCKET, MQTT, EMAIL, Excel, PDF_PRINT, RAW, IDOC
|-
| '''path''' || Output directory (multiple directories separated by semicolons)
|-
| '''xsl / XSLT''' || Optional XSLT stylesheet to apply before writing
|-
| '''use83GUID''' || Use short (8.3) GUID filenames for legacy application compatibility
|-
| '''retainOriginalFilename''' || Keep the original input filename on the output file
|}
 
== Conditional Routing ==
 
An output connector can be made conditional using an XPath expression evaluated against the internal XML document. This allows a single map to route different messages to different outputs based on their content.
 
<syntaxhighlight lang="xml">
<condition>
  <param1>/message/messageData/storageBin</param1>
  <param1_Type>xquery</param1_Type>
  <param2>DESPATCH</param2>
  <param2_Type>literal</param2_Type>
  <comparitor>EQUAL</comparitor>
</condition>
</syntaxhighlight>
 
Supported comparitors are <code>EQUAL</code> and <code>NOT EQUAL</code>. Either or both parameters can be XPath expressions (<code>xquery</code>) or fixed values (<code>literal</code>).
 
== Multiple Outputs ==
 
A single map can have any number of output connectors. All enabled outputs whose conditions are satisfied receive the transformed message. This allows one incoming file to simultaneously update multiple systems in different formats.
 
== Global Settings ==
 
Global settings that apply to all maps are defined at the top of <code>config.xml</code>:
 
{| class="wikitable"
|-
! Setting !! Description
|-
| '''logPath''' || Directory for transformation log files
|-
| '''XSLTPath''' || Directory where XSLT stylesheets are stored
|-
| '''logArchiveRetentionDays''' || How many days to keep old log files
|-
| '''retryOpenFileCount''' || Number of times to retry reading a locked file
|-
| '''retryOpenFileDelay''' || Delay in milliseconds between retries
|-
| '''enableEmailNotifications''' || Global email notification toggle
|-
| '''statusReportTime''' || Time of day to send the daily status report email
|}
 
See also: [[Connectors]], [[Middleware4j Example Configuration]], [[Overview_Middleware4j]]
 
[[Category:Middleware4j]]

Latest revision as of 12:17, 1 April 2026

A Map is the core configuration unit in Middleware4j. Each map defines a complete message transformation pipeline: where to read data from, how to transform it, and where to send the result. Multiple maps can run simultaneously, each in its own background thread.

Structure

Each map consists of:

  • One input connector — monitors a directory and reads incoming files
  • One or more output connectors — writes the transformed result to one or more destinations
  • Optional XSLT stylesheets on input and/or output for data transformation
  • Optional conditions on each output for content-based routing

How a Map Processes a File

  1. The input connector polls its configured directory at the set interval (default 1000 ms).
  2. When a file matching the file mask arrives, it is read and converted to an internal XML document by the input connector.
  3. If an input XSLT stylesheet is configured, it is applied to transform the XML.
  4. Each output connector is evaluated in turn:
    1. If a condition is configured, the output is only activated when the condition evaluates to true.
    2. If activated, an optional output XSLT stylesheet is applied.
    3. The result is written to the output destination by the output connector.
  5. The original input file is moved to a backup location.
  6. If any step fails, the file is renamed with an .error extension and an email notification is sent (if email is configured).

Configuration

Maps are defined in the main config.xml file. A minimal map looks like this: 

<map>
  <id>Map01</id>
  <enabled>true</enabled>
  <description>ASCII File to CSV</description>
  <enableEmailNotifications>true</enableEmailNotifications>
  <connectors>
    <input>
      <id>in1</id>
      <type>ASCII</type>
      <url>
        <path>./interface/input/Map01</path>
        <mask/>
        <pollingInterval>1000</pollingInterval>
      </url>
      <xsl>
        <XSLT>Map01_ASCII_to_CSV.xsl</XSLT>
      </xsl>
      <ascii>
        <pattern>1-10,12-21,23-32</pattern>
      </ascii>
    </input>
    <output>
      <id>out1</id>
      <type>CSV</type>
      <url>
        <path>./interface/output/Map01</path>
      </url>
    </output>
  </connectors>
</map>

Key Settings

Map Level

Setting Description
id Unique identifier for this map (e.g. Map01)
enabled true/false — disabled maps are loaded but do not run
description Human-readable description shown in the GUI
enableEmailNotifications Whether to send error emails for this map

Input Connector

Setting Description
type The connector type: ASCII, CSV, XML, IDOC, Excel, EMAIL, RAW, PDF_PRINT
path The directory to monitor for incoming files
mask File extension filter (leave empty to process all files)
pollingInterval How often to check the directory, in milliseconds
xsl / XSLT Optional XSLT stylesheet to apply after reading

Output Connector

Setting Description
type The connector type: ASCII, CSV, XML, SOCKET, MQTT, EMAIL, Excel, PDF_PRINT, RAW, IDOC
path Output directory (multiple directories separated by semicolons)
xsl / XSLT Optional XSLT stylesheet to apply before writing
use83GUID Use short (8.3) GUID filenames for legacy application compatibility
retainOriginalFilename Keep the original input filename on the output file

Conditional Routing

An output connector can be made conditional using an XPath expression evaluated against the internal XML document. This allows a single map to route different messages to different outputs based on their content. 

<condition>
  <param1>/message/messageData/storageBin</param1>
  <param1_Type>xquery</param1_Type>
  <param2>DESPATCH</param2>
  <param2_Type>literal</param2_Type>
  <comparitor>EQUAL</comparitor>
</condition>

Supported comparitors are EQUAL and NOT EQUAL. Either or both parameters can be XPath expressions (xquery) or fixed values (literal).

Multiple Outputs

A single map can have any number of output connectors. All enabled outputs whose conditions are satisfied receive the transformed message. This allows one incoming file to simultaneously update multiple systems in different formats.

Global Settings

Global settings that apply to all maps are defined at the top of config.xml:

Setting Description
logPath Directory for transformation log files
XSLTPath Directory where XSLT stylesheets are stored
logArchiveRetentionDays How many days to keep old log files
retryOpenFileCount Number of times to retry reading a locked file
retryOpenFileDelay Delay in milliseconds between retries
enableEmailNotifications Global email notification toggle
statusReportTime Time of day to send the daily status report email

See also: Connectors, Middleware4j Example Configuration, Overview_Middleware4j

Retrieved from ‘https://wiki.commander4j.com/index.php?title=Maps&oldid=1782’