# Versioning

Versioning tracks time series value changes for the purpose of audit trail and data reconciliation.

The capability is required for vertical applications such as Energy Data Management.

# Versioning Fields

Once enabled, the database tracks changes made to stored values with the following versioning fields:

Field Name	Description
Version Time	Timestamp when insert command is received. Set automatically by ATSD server with millisecond precision.
Version Source	User-defined field to track the source of change events such as username, device id, or IP address. Set to user:{username} by default for changes made through the web interface.
Version Status	User-defined field to classify change events. Set to invalid for NaN and out of range values by default if Invalid Value Action = SET_VERSION_STATUS

# Enabling Versioning

Versioning is disabled by default.

Enable versioning for specific metrics via Meta API, by setting the Versioning drop-down to Yes in the multi-record editor or enabling Versioning in the Metric Editor.

Additionally, set Invalid Value Action to SET_VERSION_STATUS to initialize Version Status as invalid if the inserted sample is not a valid number or is outside of the specified minimum and maximum bounds.

# Inserting Version Fields

To insert versioning fields along with the modified value, use the reserved tags:

• $version_source
• $version_status

These tags are converted to the corresponding versioning fields. Note that $version_status tag overrides invalid value set by SET_VERSION_STATUS trigger.

Options to insert versioned series:

• Network Commands
• Data Entry Series form
• CSV Parser using Default Tags
• CSV Parser using Renamed Columns

# Network Commands

To insert versioned samples, use a series command with the version tags:

series e:{entity} m:{metric}={number} t:$version_status={status} t:$version_source={source} d:{iso-date}

Example:

series e:e-vers m:m-vers=13 t:$version_status=OK t:$version_source=collector-1 d:2019-03-20T15:25:40Z

# Data Entry Form

Add versioned samples by opening the form on the Data > Data Entry > Series page and specifying versioning tags:

# CSV Parser using Default Tags

To apply the same versioning fields to all records in a CSV file, specify them in the Default Tags field in the CSV parser or on the CSV File Upload page.

$version_status={status}
$version_source={source}

# CSV Parser using Renamed Columns

To extract versioning fields from CSV content, add the version tags to the Tag Columns field and specify mappings between the original column names and version tag names in the Renamed Columns field.

# View Versions

Retrieve version history on the Ad-hoc Export page or via scheduled Export Job.

# Ad-hoc Export page

Open the Filters section and enable Display Versions on the Data > Export page.

• Records with version history are highlighted with blue borders. Blue border represents the latest value, transparent border represents a historical, overwritten value.
• NaN represents deleted values.
• Aggregation functions and other calculations ignore historical and deleted values.

# Version Filters

Name	Description
Revisions Only	Displays only modified values.
Version Filter	An expression to filter version history. The expression can contain the version_source, version_status and version_time fields. The version_time field supports calendar syntax using the date() function. The version_source and version_status fields support wildcards. To view the deleted values use Double.isNaN(value) method in the Sample Filter field.

Examples:

• Match using wildcards.

version_source LIKE 'col*'

• Match using date function.

version_time > date('2019-03-01 10:41:00') AND version_time < date('now')

• Match using exact value.

version_status = 'OK'

• Display only modified values.

  

# Modifying Values

Create a report in HTML format on the Ad-hoc Export page with versioning mode enabled.

Click timestamp for the selected record to open the Data Entry page.

Change version Status, Source, and Value fields and click Update.

# Deleting Values

Create a report in HTML format on the Ad-hoc Export page with versioning mode enabled.

Click the timestamp for the selected record to open the Data Entry page.

Change version Status and Source, change the Value and click Delete.

Note that the current value for the selected timestamp is not deleted. Instead, it is replaced with a NaN marker.

A value can also be deleted by selecting the value checkbox clicking Delete on the Data > Export page.

# Deleting Multiple Series Values

To delete multiple values, select specific rows using checkboxes or select all rows using the header checkbox. Click Delete.