Connect a historian

Read process data and alarm history from the site's Ignition or AVEVA PI historian, or import history as files.

Live: Ignition SQL tag history

BooleX reads Ignition's tag history and alarm journal from its database through the historian interface, so answers cite the site historian exactly as they would the platform store.

Create a read-only login

On the historian database, a login with SELECT only on sqlth_te, sqlth_partitions, the sqlt_data_* partition tables, alarm_events and alarm_event_data, with a read-only default transaction. Open the database port from the edge PC only (rule R3, flow F3).

Configure the site

historian: {product: ignition, prefix: "[default]CIP/"}

prefix is put before each tag name of the site tag list to find its Ignition tag path. Put the connection string in BOOLE_SITE_HISTORIAN_DSN, or in a file named by BOOLE_SITE_HISTORIAN_DSN_FILE, then restart the assistant.

Check it

Ask about a recent stop and open a ts:// citation: the trend comes from the historian. The Connectors panel on Knowledge gaps shows the connection state. Ignition's journal records active, cleared and acknowledged transitions; shelving and suppression are not in it.

Live: AVEVA PI through PI Web API

BooleX reads recorded values and summaries from the PI Data Archive, and event frames from an AF database as alarm history, through PI Web API. It sends HTTP GET requests only, never batch (a POST), so it cannot write to PI.

On the PI side

1. A read-only identity. Create a Windows or domain account for BooleX (for example PLANT\svc-boolex). On the PI Data Archive, map it (PI System Management Tools, Security, Mappings & Trusts) to a dedicated PI identity, for example BooleX Readers, and give that identity read access only: r on the data access of the PI points BooleX reads (Points, Security, data and point security), and read on the PI Data Archive's PIPOINT database security table. Give it no write (w) right anywhere.
2. Event frames (optional). In the AF database that holds the alarm event frames, give the same account an AF identity mapping with Read and Read Data on the database and its event frames, and nothing more.
3. The PI Web API endpoint. Note the PI Web API base URL, for example https://pi.plant.local/piwebapi. In PI Web API's configuration (the System Configuration element in AF), allow Basic authentication (AuthenticationMethods containing Basic) or the bearer method the site uses. Kerberos alone is not supported. Keep the CorsMethods and other settings as they are: BooleX makes no cross-origin calls.
4. Certificate trust. PI Web API serves HTTPS with the certificate bound at installation. Give BooleX the CA certificate that signed it (or the self-signed certificate itself) as a PEM file. BooleX checks the certificate and refuses the connection if it does not match.
5. The network. Open 443/TCP (or PI Web API's port) from the edge PC to the PI Web API server only (flow F21).

Configure the site

historian:
  product: pi_web_api
  base_url: https://pi.plant.local/piwebapi
  data_server: PISRV01            # the PI Data Archive
  prefix: "CIP."                  # put before each tag name to find its PI point
  asset_database: \\AFSRV01\Dairy  # event frames; leave out for process data only
  ca_file: certs/pi-web-api.pem   # relative to the site folder
  username: PLANT\svc-boolex      # leave out to use a bearer token

Put the account's password in a file named by BOOLE_SITE_HISTORIAN_PASSWORD_FILE. Without username, put a bearer token in a file named by BOOLE_SITE_HISTORIAN_TOKEN_FILE. Then restart the assistant.

A tag whose PI point is not \\data_server\prefix+tag gets a pi_point column in the site tag list (tags.csv, or the file tag_list names): a point path such as \\PISRV01\FIC-101.PV, or the point's WebId.

Each event frame is an alarm: active at its start, acknowledged when acknowledged (with the user), cleared at its end. The alarm ID is the first word of the event frame's name; set alarm_pattern (a regular expression whose first group is the alarm ID) for another naming.

Check it

Ask about a recent stop and open a ts:// citation: the trend comes from PI. If PI Web API cannot be reached, the answer says so, and the outage shows as a data-quality gap from the first failed read to the next good one. A value PI marks bad shows as bad, a questionable or substituted one as uncertain; a PI system state such as I/O Timeout has no value and is left out.

Files: alarm logs and trend exports

Where there is no live connection (the offline-import profile, or history from before go-live), import the exports with a column mapping per file.

site: plant-a
date_format: "%Y-%m-%d %H:%M:%S.%f"
utc_offset_h: 1
columns: {time: Time stamp, alarm: Alarm, transition: State, value: Value, operator: User}
states: {Came: active, Went: cleared, Ack: acknowledged}

site: plant-a
layout: long              # or wide: a time column and one column per tag
date_format: "%Y-%m-%d %H:%M:%S.%f"
utc_offset_h: 1
columns: {time: Time, tag: Tag, value: Value, quality: Quality}

python -m edge.import_history --alarm-log alarm_log.csv alarm-log.mapping.yaml --trend trend.csv trend.mapping.yaml
python -m edge.import_history --device-log drive_faults.csv drive.mapping.yaml   # a drive or robot fault log
python -m edge.import_history --batches batches.csv                                # batch and phase records

The records keep the export's timestamps. A drive or robot fault becomes an alarm event marked with its device, beside the PLC's alarms in the sequence of events.