Skip to main content

ASCII File Data Source

The ASCII File data source reads a local text file as an ASCII character stream, processing it line by line at a configurable poll interval. Each data point uses a Java-style regular expression to locate its identifier and extract a corresponding value from the file content. This makes it well suited for parsing CSV files, log files, configuration files, and any structured text output produced by external systems or scripts.

This data source is commonly used to integrate Mango with legacy systems that export data as flat files, to monitor log files generated by industrial equipment, or to ingest CSV data drops from third-party applications.

Overview​

PropertyValue
ModulemangoAutomation-AsciiFile
ProtocolFile system
DirectionPolling
Typical UseParsing data from CSV, log, and text files

Prerequisites​

  • A text file accessible on the local file system of the Mango server. Network paths (UNC paths, NFS mounts exposed as network paths) are not directly supported; the file must appear as a local path to the operating system.
  • Knowledge of the file format -- specifically, the structure of each line and how identifiers and values are arranged. You will need to write regular expressions to extract data.
  • File path access must be permitted in the ASCII File section of the Mango system settings. Administrators can restrict which directories the data source is allowed to read from.

Configuration​

Data Source Settings​

SettingDescription
NameA descriptive name for the data source.
XIDA unique identifier across all data sources. Auto-generated if left blank.
Update periodHow frequently Mango reads and parses the file.
File PathThe absolute path to the text file to read. Use the Check button to verify the path points to an existing file.

The file path must be an absolute path on the local file system. For example: /var/data/sensor_output.csv on Linux or C:\Data\sensor_output.csv on Windows.

tip

If the file is generated by an external process on a schedule, set the update period to match or slightly exceed that schedule to avoid reading incomplete writes.

Data Point Configuration​

Each data point extracts a value from the file by matching lines with a regular expression and identifying a specific capture group.

SettingDescription
Point IdentifierAn ASCII string used to identify which line in the file corresponds to this data point. The captured regex group at the Point Identifier Index is compared to this value using exact string matching (String.equals).
Point Identifier IndexThe integer index of the regex capturing group that contains the point identifier. Group 0 is the entire match; group 1 is the first set of parentheses, and so on.
Value RegexA Java-style regular expression that matches lines containing an (identifier, value) pair. The regex must include capturing groups for both the identifier and the value.
Value IndexThe integer index of the regex capturing group that contains the new value for the data point.
Data typeThe Mango data type for this point (Binary, Multistate, Numeric, or Alphanumeric). The extracted string is converted to this type.
Timestamp pattern(Optional) A SimpleDateFormat pattern for parsing a timestamp from the file content. When importing with timestamps, the protections on times for new point values are disabled.

Writing Regular Expressions​

The regular expression engine uses Java regex syntax. For reference on syntax, character classes, and quantifiers, consult the Java Regex Tutorial.

Example: Given a CSV file with lines like:

TEMP_ZONE1,72.5,2026-02-16 14:30:00
HUMIDITY_ZONE1,45.2,2026-02-16 14:30:00
PRESSURE_MAIN,1013.25,2026-02-16 14:29:55

A suitable Value Regex would be:

^([A-Z_]+),([0-9.]+),(.+)$
  • Group 1 captures the identifier (e.g., TEMP_ZONE1)
  • Group 2 captures the numeric value (e.g., 72.5)
  • Group 3 captures the timestamp (e.g., 2026-02-16 14:30:00)

For a data point reading TEMP_ZONE1:

SettingValue
Point IdentifierTEMP_ZONE1
Point Identifier Index1
Value Index2

Timestamp Patterns​

When the file contains timestamps, you can configure the data point to use them instead of the Mango poll time. The timestamp pattern follows the SimpleDateFormat specification. Common patterns include:

PatternExample
yyyy-MM-dd HH:mm:ss2026-02-16 14:30:00
MM/dd/yyyy HH:mm02/16/2026 14:30
yyyy-MM-dd'T'HH:mm:ss.SSSZ2026-02-16T14:30:00.000+0000

For the full pattern specification, see the SimpleDateFormat documentation.

Common Patterns​

Monitoring Log Files​

Many industrial devices and PLCs write status information to text files at regular intervals. Configure the ASCII File data source to read these files and extract key metrics such as temperatures, pressures, or equipment states. The update period should match the frequency at which the device writes to the file.

Ingesting CSV Data Drops​

External systems often export data as CSV files placed in a shared directory. Point the ASCII File data source at the CSV file and configure regex patterns to match the column structure. This is particularly useful for integrating with legacy systems that do not support modern API protocols.

Reading System Configuration Files​

You can monitor the contents of system configuration files (e.g., /etc/hostname, /proc/meminfo on Linux) to track system-level parameters as Mango data points. This provides a lightweight alternative to installing monitoring agents.

Using with Script-Generated Files​

A common pattern is to run an external script (via cron or Windows Task Scheduler) that queries an API, processes the results, and writes them to a text file. The ASCII File data source then reads this file, bridging Mango to systems that lack direct protocol support.

Troubleshooting​

File Not Found​

  1. Verify the file path is absolute and correct. Use the Check button in the data source editor.
  2. Ensure the Mango process has read permission on the file and its parent directories.
  3. Check that the path is allowed in the ASCII File section of the Mango system settings.

No Values Extracted​

  1. Regex does not match -- test your regular expression against the actual file content using an online Java regex tester. Ensure the regex matches the full line structure.
  2. Wrong capture group index -- verify that the Point Identifier Index and Value Index correspond to the correct parenthesized groups in your regex.
  3. Point Identifier mismatch -- the comparison uses exact string matching (String.equals), so the identifier must match character-for-character, including case.

Data Type Conversion Errors​

  1. If the point is configured as Numeric but the captured value contains non-numeric characters, conversion will fail. Check the regex to ensure it captures only the numeric portion.
  2. For Binary points, the captured value must be interpretable as a boolean (e.g., "true"/"false", "1"/"0").

Stale or Duplicate Values​

  1. If the external process overwrites the file in place, there may be a brief window where the file is partially written. Increase the update period or coordinate timing with the external process.
  2. If the file is appended to rather than overwritten, the data source will re-read all lines on every poll. Ensure your regex is specific enough to avoid matching old or duplicate lines unintentionally.