Skip to main content

OPC UA History Read Node

Reads historical data from OPC UA server variables. This node supports multiple history read types including raw data, modified data, and aggregated (processed) data retrieval.

Configuration​

Node Properties​

  • Name: Optional friendly name for the node
  • Endpoint: OPC UA server endpoint configuration (required)
  • History Type: Type of historical data to retrieve
  • NodeId: The target variable node identifier (optional - can be provided via message)
  • Output Type: Format of the output data

History Types​

Based on the selected history type, the node will retrieve different kinds of historical data:

Raw Data​

Retrieves raw historical values stored in the server's history database.

Configuration:

  • Start Time: Beginning of time range (datetime or relative string ) for instance "2024-01-15T10:30:00Z" or "1 hour ago"
  • End Time: End of time range (datetime or relative string like "now")
  • Number of Values: Maximum values to return per node (default: 100)
  • Return Bounds: Include bounding values outside the time range

Raw Modified​

Retrieves raw historical values that have been modified or updated.

Configuration:

  • Same as Raw Data with additional tracking of value modifications

Processed Details​

Retrieves aggregated historical data using server-side processing functions.

Configuration:

  • Start Time: Beginning of aggregation period
  • End Time: End of aggregation period
  • Processing Interval: Time interval for aggregation (e.g., "1 minute", "30 seconds")
  • Aggregate Type: Type of aggregation function to apply

Aggregate Types​

For processed details, the following aggregate functions are supported:

  • Average - Mean value over the interval
  • Count - Number of data points
  • Delta - Change between first and last values
  • DeltaBounds - Change including boundary values
  • DurationBad - Time duration with bad quality
  • DurationGood - Time duration with good quality
  • Interpolative - Interpolated value at interval boundaries
  • Maximum - Highest value in interval
  • Minimum - Lowest value in interval
  • PercentBad - Percentage of bad quality data
  • PercentGood - Percentage of good quality data
  • Range - Difference between max and min values
  • StandardDeviationPopulation - Population standard deviation
  • StandardDeviationSample - Sample standard deviation
  • Total - Sum of all values
  • VariancePopulation - Population variance
  • VarianceSample - Sample variance
  • WorstQuality - Worst quality value in interval

NodeId and Topic​

The target variable can be specified in two ways:

  • NodeId: The NodeId of the variable to read (e.g., ns=2;s=Temperature)

or it can be specified via the msg.nodeId or the msg.topic property:

  • Topic: An alternative way to specify the NodeId using the msg.topic property (e.g., msg.topic = "ns=2;s=Temperature")

Priority order for NodeId resolution:

  1. msg.nodeId (if defined)
  2. msg.topic (if defined)
  3. msg.payload (if defined)
  4. NodeId configured in the node properties

Note: ensure that the injected message does not contain conflicting NodeId information in msg.nodeId or msg.topic or msg.payload if you want to use the NodeId configured in the node properties.

Output Types​

  • Time+Value - Timestamp and value only
  • Time+Variant - Timestamp and full variant information
  • DataValue - Complete OPC UA DataValue structure
  • StatusCode - Status codes only
  • DataValueReversible - DataValue with reversible encoding

Input Message Formats​

Basic History Read​

msg = {
    nodeId: "ns=2;s=Temperature", // Target variable (optional if configured)
    topic: "ns=2;s=Temperature", // Alternative way to specify nodeId
    startTime: "1 hour ago", // Start time (optional)
    endTime: "now", // End time (optional)
    numValuesPerNode: 50, // Max values to return (optional)
    returnBounds: true, // Include boundary values (optional)
    processingInterval: "5 minutes", // For processed data (optional)
    outputType: "TimeValue", // Output format (optional)
};

Time Specifications​

Time values can be specified as:

Absolute Times:

  • ISO 8601 strings: "2024-01-15T10:30:00Z"
  • Date objects: new Date()

Relative Times:

  • "now" - Current time
  • "1 hour ago" - One hour before current time
  • "2 days ago" - Two days before current time
  • "30 minutes ago" - Thirty minutes before current time
  • "1 week ago" - One week before current time

Duration Formats:

  • "1 second", "2 seconds"
  • "1 minute", "5 minutes"
  • "1 hour", "3 hours"
  • "1 day", "7 days"
  • "1 week", "2 weeks"

Output Message Format​

Raw/Modified Data Response​

{
    // Original input properties
    nodeId: "ns=2;s=Temperature",
    startTime: "2024-01-15T09:00:00Z",
    endTime: "2024-01-15T10:00:00Z",

    // Historical data array
    payload: [
        {
            value: 23.5,                           // The historical value
            statusCode: "Good",                    // Quality of the data point
            sourceTimestamp: "2024-01-15T09:15:00Z" // When value was recorded
        },
        {
            value: 24.1,
            statusCode: "Good",
            sourceTimestamp: "2024-01-15T09:30:00Z"
        }
        // ... more historical values
    ]
}

Processed Data Response​

{
    // Original input properties
    nodeId: "ns=2;s=Temperature",
    startTime: "2024-01-15T09:00:00Z",
    endTime: "2024-01-15T10:00:00Z",

    // Aggregated data array
    payload: [
        {
            value: 23.8,                           // Average temperature
            statusCode: "Good",
            sourceTimestamp: "2024-01-15T09:05:00Z" // Interval start time
        },
        {
            value: 24.2,                           // Next interval average
            statusCode: "Good",
            sourceTimestamp: "2024-01-15T09:10:00Z"
        }
        // ... more aggregated intervals
    ]
}

Output Type Variations​

TimeValue Format:

payload: [{ value: 23.5, sourceTimestamp: "2024-01-15T09:15:00Z" }];

TimeVariant Format:

payload: [
    {
        value: { dataType: "Double", value: 23.5 },
        sourceTimestamp: "2024-01-15T09:15:00Z",
    },
];

DataValue Format:

payload: [
    {
        value: { dataType: "Double", value: 23.5 },
        statusCode: "Good",
        sourceTimestamp: "2024-01-15T09:15:00Z",
        serverTimestamp: "2024-01-15T09:15:01Z",
    },
];

Usage Examples​

Read Last Hour of Raw Data​

msg.nodeId = "ns=2;s=ProcessValue";
msg.startTime = "1 hour ago";
msg.endTime = "now";
msg.numValuesPerNode = 100;
return msg;

Read Daily Averages for Last Week​

msg.nodeId = "ns=2;s=Temperature";
msg.startTime = "1 week ago";
msg.endTime = "now";
msg.processingInterval = "1 day";
// Configure node for "processed-details" with "Average" aggregate
return msg;

Read Data for Specific Time Range​

msg.nodeId = "ns=2;s=Pressure";
msg.startTime = "2024-01-15T08:00:00Z";
msg.endTime = "2024-01-15T16:00:00Z";
msg.numValuesPerNode = 1000;
msg.returnBounds = true;
return msg;

Read Modified Values Only​

msg.nodeId = "ns=2;s=ControlVariable";
msg.startTime = "24 hours ago";
msg.endTime = "now";
// Configure node for "modified" history type
return msg;

Read 5-Minute Maximums​

msg.nodeId = "ns=2;s=FlowRate";
msg.startTime = "2 hours ago";
msg.endTime = "now";
msg.processingInterval = "5 minutes";
// Configure node for "processed-details" with "Maximum" aggregate
return msg;

Error Handling​

Common Status Codes​

  • Good - Data retrieved successfully
  • BadHistoryOperationUnsupported - Server doesn't support history
  • BadNodeIdUnknown - Variable not found
  • BadHistoryOperationInvalid - Invalid history operation parameters
  • BadTimestampsToReturnInvalid - Invalid timestamp specification
  • BadMaxAgeInvalid - Invalid time range specified

Error Response​

When history read fails:

{
    nodeId: "ns=2;s=BadVariable",
    payload: [],                    // Empty array
    statusCode: "BadNodeIdUnknown", // Error status
    message: "Node not found"       // Error description
}

Performance Considerations​

  1. Time Range: Limit time ranges to avoid excessive data retrieval
  2. Value Limits: Use numValuesPerNode to control response size
  3. Processing Intervals: Choose appropriate intervals for aggregated data
  4. Server Capabilities: Verify server supports required history features

Best Practices​

  1. Time Specification: Use relative times for dynamic queries
  2. Data Validation: Always check status codes in responses
  3. Chunking: Break large time ranges into smaller chunks
  4. Caching: Consider caching historical data for repeated queries
  5. Server Load: Avoid frequent large history requests
  6. Error Handling: Implement proper error handling for failed requests

Node Status Indicators​

  • Blue dot: History read operation in progress
  • Green dot: History data retrieved successfully
  • Red dot: History read operation failed
  • Yellow dot: Partial data retrieved (some quality issues)