CSVexportHistory

This program exports selected history records from the Niagara station into a CSV file, using customizable formatting and time range filtering.

The export supports:
- one or more Niagara histories in the same CSV file;

- bounded time-range export;

- custom CSV column headers;

- configurable timestamp format and output timezone;

- configurable delimiter;

- optional filename prefix/suffix based on execution time;

- bucketed output such as 1 minute, 5 minutes, 15 minutes, or hourly rows;

- aggregation per bucket: Latest, Oldest, Average, Min, Max, or Sum;

- decimal formatting with dot or comma decimal separator;

-REV20260817 is a major update over REV2025091.

Installation

The ZIP file contains a single BOG file. Add the BOG to your Workbench User Home. Add it folder by dragging it from your files (My File System) to the station via the Niagara Workbench Nav Tree.

Usage (Version 2025-05-30)

# CSVexportHistory REV20260817

Direct comparison: CSVexportHistory_REV20250911 -> CSVexportHistory_REV20260817
## Overview
CSVexportHistory is a Niagara 4 Program Object that exports selected station histories to a CSV file.
It is intended for operators, commissioning engineers, and system integrators who need a repeatable way to extract trend data from a Niagara station without building a custom module. The Program can be run manually from Workbench or scheduled with a Trigger.

## User Guide
### 1. Select Histories To Export
In REV20260817, Execute reads only customHeadersMap.
You can populate customHeadersMap in three ways, and you can combine them:
- edit customHeadersMap directly;

- pick histories in historiesManualList, then run importManualList;

- set discoverQuery, then run Update Histories List or executeDiscovery.

### 2. Edit Headers And Column Order
customHeadersMap controls both export selection and CSV column order.
Format:
``texthistory:/Station/HistoryName=Original Name|Custom Header``
Rules:
- the left side is the history key;

- the line order is the CSV column order;

- the text after | is the CSV header;

- if the custom header is empty, the original/display name is used;

- lines starting with # are disabled;

- import and discovery never overwrite existing entries;

- commented entries are treated as intentionally disabled and are not re-added.
### 3. Configure The Export Range
Set exportTimeRange before running Execute.
### 4. Configure Output File
Set:
- csvDirectory, for example file:^exports;

- csvFilename, for example history_export;

- optional addExecTimeBeforeFN;

- optional addExecTimeAfterFN.
Example:
``textaddExecTimeBeforeFN = yyyyMMddHHmmsscsvFilename = history_exportaddExecTimeAfterFN =``
Example result:
``text20260817101530history_export.csv``
### 5. Configure CSV Format
Common slots:
- tsFormat: Java SimpleDateFormat pattern for timestamps, for example yyyy-MM-dd HH:mm:ss.SSS.

- csvDelimiter: accepts ,, ;, \t, tab, comma, semicolon, |, pipe, colon, space, or a single character.

- ExcelFormulaProtectionEnum: protects cells that Excel might interpret as formulas.

- UseCommaAsDecimal: writes numeric values with comma decimal separator when true.

- NumericDecimalPlaces: controls fixed numeric decimal places.
Important: tsFormat only changes how timestamps look. It does not change aggregation size. For example, yyyy.MM.dd does not create daily aggregation by itself.
### 6. Configure Bucketing And Aggregation
BucketTimeUnitEnum:
- 0 Milliseconds- 1 Seconds- 2 Minutes_1- 3 Minutes_5- 4 Minutes_15- 5 Hour
BucketModeEnum:
- 0 Truncate- 1 Round
BucketAggregateModeEnum:
- 0 Latest- 1 Oldest- 2 Average- 3 Min- 4 Max- 5 Sum
### 7. Use Chunking For Large Bucketed Exports
Set:
``textchunkModeAuto = true``
Chunking only applies to bucketed exports. It does not make unbucketed full-detail exports unlimited.
If a chunk is too large at runtime, the Program discards that in-flight chunk, splits it into smaller windows, and retries. Nothing from the failed chunk is written before the retry.
Runtime time and raw-record guards abort directly, because splitting does not reduce total work.

## Changes From REV20250911
- Execute now reads customHeadersMap instead of reading a direct manual list plus positional headers.

- CSV column order is now controlled by customHeadersMap line order.

- Disabled histories are represented by commenting lines with #.

- chunkModeAuto is now the main path for oversized bucketed exports.

- Guard values are hardcode.

## Known Limitations
- chunkModeAuto only chunks bucketed exports.

- Unbucketed exports still rely on SamplingRateHint_SamplesPerHour for pre-run estimation.

- Daily aggregation is not exposed as a bucket option in this revision.

- Numeric decimal parsing is controlled by the hard-coded DECIMALPARSEMODE constant, not by a Workbench slot.

PREVIOUS VERSIONS

Changes with version 2025-09-11

The 2025-09-11 release introduces major improvements:

- Bucketization & Aggregation

- Stronger validation and memory guards.

- Expanded CSV formatting and Excel-safe output.

- Flexible time handling with bucket aggregation.

- Safer filename generation and UTF-8 logging.

Usage (Version 2025-05-30)

This program exports selected history records from the Niagara station into a CSV file, using customizable formatting and time range filtering.

Users can define timestamp format, column headers, field delimiter, and dynamic naming options for the output file.

The export includes:

- A configurable list of history points to include.

- Optional time-based filtering using a defined time range.

- A log file (log.txt) that records executed BQL queries for auditing/debugging.

CUSTOM FIELDS:

Copyright 2025 Marco Binotto