OIAnalytics®

Query time series data from OIAnalytics® SaaS application.

Connection Settings

Main Configuration

Setting	Description	Example Value
Use OIAnalytics registration	Use pre-configured connection settings from OIAnalytics registration. Default: enabled.	Enabled/Disabled
Timeout	Duration in seconds before connection failure is reported. Default: 30.	30

Manual Configuration (when registration not used)

Setting	Description	Example Value
Host	Hostname of the OIAnalytics® SaaS application.	https://optimistik.oianalytics.com
Accept unauthorized certificate	Enable if HTTP queries pass through a firewall that strips certificates.	Enabled/Disabled

Authentication Settings

Setting	Description	Example Value
Authentication method	Authentication type for the connection.	Access key/Secret, Azure AD (Client Secret), Azure AD (Certificate)
Access key	Access key for Access key/Secret authentication.	my_access_key
Secret	Secret for Access key/Secret authentication.	••••••••
Tenant ID	Azure AD tenant identifier (for Azure AD methods).	tenant-id-uuid
Client ID	Azure AD client identifier (for Azure AD methods).	client-id-uuid
Client Secret	Azure AD client secret (for Azure AD Client Secret method).	••••••••
Certificate	Certificate selected from OIBus's Certificates page (for Azure AD Certificate method), not a raw file path.	(selected from list)
Scope	OAuth scope (for Azure AD Certificate method).	https://resource/.default

Proxy Configuration

Setting	Description	Example Value
Use proxy	Route requests through a proxy server.	Enabled/Disabled
Proxy URL	URL of the proxy server.	http://proxy.example.com:8080
Proxy username	Username for proxy authentication (if required).	proxy_user
Proxy password	Password for proxy authentication (if required).	••••••••

Group Settings

Items can be organised into groups. Each group defines a shared collection schedule and default throttling settings. Items in the same group are still fetched one at a time in sequence — the group simply provides common defaults that individual items can override.

Setting	Description	Example Value
Name	Unique label for the group within this connector.	Group A
Scan mode	Schedule used to collect all items in the group.	Every 1 min
Throttling	Default throttling values (Max read interval, Read delay, Start time offset, End time offset, Recovery strategy) inherited by items in the group.	3600, 200, 0, 0, oldest

Item Settings

Each item can be individually configured. Items inherit their scan mode and throttling defaults from their group, but each setting can be overridden per item by disabling Sync with group.

Throttling Settings

Throttling controls how OIBus paces historical data requests. These settings appear on each group (for connectors that support groups) or on each item (for single-item connectors). Items in a group can override the group defaults by disabling the Sync with group toggle.

Setting	Description	Example Value
Max read interval	Maximum duration of each sub-query in seconds. Larger time ranges are automatically split into chunks not exceeding this value.	3600
Read delay	Pause in milliseconds between consecutive sub-queries. Helps prevent server overload and manages rate limits.	1000
Start time offset	Milliseconds added to the start of the query window (@StartTime). A negative value moves the start earlier, to capture late-arriving data from the previous interval — this is the old "Overlap" behavior. A positive value moves the start later instead, skipping that much of the window.	-60000
End time offset	Milliseconds added to the end of the query window (@EndTime). A negative value pulls the end in earlier — useful for eventually-consistent sources where the very latest rows aren't reliable yet. A positive value extends the window later. If the resulting end is not after the effective start, the query is skipped for this run.	0
Recovery strategy	Order in which OIBus catches up on a backlog of unqueried sub-intervals — e.g. after being stopped for a while, or on first run against a wide time range. From oldest to newest (default) processes the backlog chronologically. From newest to oldest queries the most recent sub-interval first, so up-to-date values become available immediately while older gaps are backfilled afterward.	From oldest to newest

How Throttling Works

1. Interval splitting — A 24-hour range with Max read interval = 3600 (1 hour) is split into 24 separate 1-hour sub-queries.
2. Read delay — A pause is inserted between sub-queries to manage server load.
3. Start/End time offset — With Start time offset = -60000 (-1 minute), a query for [10:00–11:00] actually requests [9:59–11:00], ensuring no late-arriving data is missed. End time offset shifts the other boundary the same way.
4. Recovery strategy — Only matters when there's more than one sub-interval to catch up on. With From newest to oldest, the tracked instant only advances once every sub-interval in the backlog has been queried — this avoids skipping over not-yet-queried older intervals if OIBus restarts mid-catch-up.

Offsets apply to the full query range

Start/End time offset are applied once, to the start and end of the overall query window — not to the start of each individual sub-interval when a large range is split into chunks by Max read interval.

Recommended Configurations

Scenario	Max read interval	Read delay	Start time offset
Stable network, small datasets	3600 (1 hour)	500	0 (none)
Unstable network	1800 (30 min)	2000	0 (none)
Large historical retrievals	7200 (2 hours)	1000	0 (none)
Real-time with occasional gaps	900 (15 min)	200	-15000 (-15 sec)

Going deeper

For the reasoning behind these numbers — sizing Max read interval against real data volumes, the Read delay / Max read interval trade-off on a large backlog, and worked examples of Start vs. End time offset (including the batched multi-item case where items don't all flush at once) — see Tuning South History Call Settings.

Endpoint Settings

Setting	Description	Example Value
Endpoint	API endpoint for HTTP requests	/api/oianalytics/data/values

Query Parameters

Query Variables:

• @StartTime: Initial execution time, updates to most recent timestamp from results
• @EndTime: Current time (now()) or sub-interval end when queries are split

Query Splitting

Large time intervals are automatically divided into smaller chunks using:

• Max read interval (from throttling settings)
• Reduces server and network load
• Improves data stream resilience

Repeated keys

Adding the same key several times sends it as an array of values in the request, instead of overwriting the previous one. This is useful for endpoints that accept multiple values for a single parameter, such as data-reference below.

Example: querying data values

To retrieve raw values for several data references over a time window, configure the item with the /api/oianalytics/data/values endpoint and the following query parameters:

Key	Value
from	@StartTime
to	@EndTime
aggregation	RAW_VALUES
data-reference	CIP_Line_1_Acid_Tank_Level
data-reference	CIP_Line_1_Caustic_Tank_Level

Since data-reference is repeated, it is sent as data-reference=CIP_Line_1_Acid_Tank_Level&data-reference=CIP_Line_1_Caustic_Tank_Level, letting the endpoint return values for both tank levels in a single query.

CSV Serialization Options

Setting	Description	Example Value
Filename	Output filename pattern with variables: @ConnectorName, @CurrentDate	data_@ConnectorName.csv
Delimiter	Field separator character	COMMA (,), SEMI_COLON (;), DOT (.), COLON (:), PIPE (|), SLASH (/), TAB (\t), NON_BREAKING_SPACE
Compression	Enable gzip compression	Enabled/Disabled
Output datetime format	Format for datetime fields in CSV	yyyy-MM-dd HH:mm:ss
Output timezone	Timezone for datetime values	UTC or Europe/Paris

Filename Variables

• @ConnectorName: Connector name
• @CurrentDate: Current timestamp in yyyy_MM_dd_HH_mm_ss_SSS format (fixed format)
• Datetime format setting doesn't affect filename timestamp