87 lines
5 KiB
Markdown
87 lines
5 KiB
Markdown
---
|
||
task: Read the audit trail (export, RQL query, audit report) and know what each tool records
|
||
version: R1.03
|
||
source: IM 36K10L25-01EN §1.1, §2.1.2, §3.1, App. 1; IM 36K10G10-01EN ch. 9; practiced on CI-Eng-Sample 2026-10-01
|
||
status: verified
|
||
---
|
||
|
||
# Read the audit trail
|
||
|
||
Read-only. Dataset `AUDIT_TRAIL` (storage group `ADT`); every field is read-only except
|
||
`APPLICATION_SUB` (the "modifiable ASCII application info") and `PROFILE`.
|
||
|
||
## 1. Fields
|
||
|
||
| Field | Content |
|
||
|---|---|
|
||
| `NAME` | `<ACTION_TIME>/<ACTION_STAMP>`, e.g. `01-OCT-26 17:05:00.181/84` |
|
||
| `ACTION_TIME`, `NOTIFICATION_TIME`, `MODIFICATION_TIME` | When it happened / reached AUDIT Service / `APPLICATION_SUB` was last changed |
|
||
| `SUBJECT_GROUP` | Subject: the **dataset name** for configuration and DSS value changes (`ITEM_DF`, `ITEM_VAL`, `SECTION_DF`, `REPORT_DF`, `AUDIT_EVENT_CLAS_DF` …) or a classifier subject (`CI-SERVER` for logins, `ITEM`, `SUB-ITEM` …) |
|
||
| `SUBJECT_ATTRIBUTE` | Changed field (`HIGH_LIMIT`, `ITEM_VALUE`, `DESCRIPTION` …); empty for insert/delete/login |
|
||
| `SUBJECT_ACTION` | `INSERT`, `MODIFY`, `DELETE`, `LOGIN`, `LOGOUT`, `LOGIN-ATTEMPT`, `ACKNOWLEDGE`, `SHELVE`, `UN-SHELVE` |
|
||
| `SUBJECT_SOURCE` | Tool that made the change (table in §2) |
|
||
| `SUBJECT_IDENT` | Record name: item, section, object (`<object>:<attribute>` for attribute values) … |
|
||
| `USER_NAME`, `PROFILE`, `TERMINAL` | CI Server user and profile; terminal often empty |
|
||
| `ACTION_NODE`/`ACTION_PROCESS`, `NOTIFICATION_NODE`/`NOTIFICATION_PROCESS` | Node and process (`DSSSDA00`, `JHMISET1086`, `DSSQLD00875` …) |
|
||
| `OLD_VALUE`, `NEW_VALUE` | Text, max 64 characters (longer values are cut) |
|
||
| `REASON`, `APPLICATION_INFO`, `APPLICATION_SUB` | Free text from the notifying program (empty in the tests) |
|
||
|
||
## 2. What is recorded (verified on R1.03.00)
|
||
|
||
| Action | Recorded as |
|
||
|---|---|
|
||
| `dssqld` load / modify / remove (any dataset) | `<DATASET>`, field, `INSERT`/`MODIFY`/`DELETE`, source **`ENT-ENG-MOD`**, user `FULL AUTHORIZATION`, plus a `CI-SERVER` `LOGIN`/`LOGOUT` pair per `dssqld` run (not `QUICKLOAD`) |
|
||
| Writing a value through DSS (`dssqld -m` on `ITEM_VAL`) | `ITEM_VAL` `ITEM_VALUE` `MODIFY`, old and new value — for **every** item, whatever its *Audit trailing wanted* (`AUDIT_INFO`) |
|
||
| Engineering Module: change an item field | `ITEM_DF` `<FIELD>` `MODIFY`, source `LOC-ENG-MOD`, user `ADMIN` (the logged-in user) |
|
||
| Engineering Module: right-click item › *Update value* | `ITEM_VAL` `ITEM_VALUE_STR` `MODIFY` (old/new) and `ITEM_VAL` `STATUS` `MODIFY`, source `LOC-ENG-MOD` |
|
||
| Engineering Module / Operator / OPC UA server login | `CI-SERVER` `LOGIN` / `LOGOUT`, source `LOC-ENG-MOD`, `OPER-INTERFACE`, `VIA-OPC-UAS` |
|
||
| Operator display write (button / input) on an item with *Audit trailing wanted* (`AUDIT_INFO` 1) | `ITEM` `VALUE` `MODIFY` `OPER-INTERFACE` (old/new) and `ITEM` `STATUS` `MODIFY`, user = operator; with `AUDIT_INFO` 0 **nothing** |
|
||
| `itmval -p` (ITEM Service API) | **nothing**, even with `AUDIT_INFO` 1 |
|
||
|
||
So `AUDIT_INFO` matters only for operator (and PROCESS) writes; DSS changes are always
|
||
audited. The `SUBJECT_SOURCE` of a user interface comes from its *audit
|
||
trail id* in `dssana.sup` `USER_INTERFACE` (Engineering Module = `LOC-ENG-MOD`).
|
||
|
||
## 3. Export
|
||
|
||
`dssqld -e` skips `AUDIT_TRAIL` in a full export (`NO-EXPORT` in `dssqld.sup`); name it:
|
||
|
||
```
|
||
dssqld -e audit.qlo -d AUDIT_TRAIL
|
||
```
|
||
|
||
or filter (dates as `dd-mm-yyyy hh:mm:ss`, local time):
|
||
|
||
```
|
||
@FIELDS
|
||
NAME,SUBJECT_GROUP,SUBJECT_ATTRIBUTE,SUBJECT_ACTION,SUBJECT_SOURCE,SUBJECT_IDENT,USER_NAME,OLD_VALUE,NEW_VALUE
|
||
@SELECT
|
||
'SUBJECT_IDENT = "<Section>.<Tag>" AND ACTION_TIME > "01-10-2026 17:00:00"'
|
||
@AUDIT_TRAIL
|
||
```
|
||
|
||
`dssqld -e out.csv audit.qli -c` (CSV). **Keep `NAME` in `@FIELDS`**: without the key field the
|
||
export silently returns 0 records (verified). The whole trail can be large (5 000 records after a
|
||
year of test work). Wildcards: `SUBJECT_IDENT LIKE "<Section>.*"` (`*`, not `%`; `=` with `*`
|
||
matches nothing).
|
||
|
||
## 4. RQL query and audit report
|
||
|
||
```
|
||
column t as 'DD-MM-YYYY hh:mm:ss' heading 'Time';
|
||
select action_time t, subject_group, subject_attribute, subject_action, subject_source,
|
||
subject_ident, user_name, old_value, new_value
|
||
from audit_trail
|
||
where action_time > @date - 3600 and subject_ident like '<Section>.%'
|
||
order by action_time;
|
||
```
|
||
|
||
Use aliases with `COLUMN … AS 'A12'` to keep lines short (the fields are 16–256 characters
|
||
wide). Try it in the interactive generator (skill `reporting`, `rql-interactive.md`). The sample
|
||
report `CIENG_AUDIT` (`examples/CI-Eng-Sample/19_audit_df.qli`) lists the last hour of events on
|
||
`CI-Eng-Sample.*`; generate it like any ad-hoc report (`define-reports.md` §2). Generated from
|
||
`dssqld` it is stored but not printed (`FSL-E-PRT_UNKUSER`, ISS-045).
|
||
|
||
In the Engineering Module, *Configuration › Reporting › Reports* holds the system reports
|
||
`AUDIT_TRAIL` and `UA_SERVER_AUDIT` (IM 36K10C30 App. 1). Generated there (as the logged-in
|
||
user) `CIENG_AUDIT` printed to `CIENG_FILE` and showed in the report viewer (checked by the user).
|