ci-server-engineer/.claude/skills/audit-trail/tasks/configure-audit.md

task	version	source	status
Choose what AUDIT Service stores (classifier STORAGE, AUDIT_INFO), define selection groups, run an event logger (ADTLOG)	R1.03	IM 36K10L25-01EN §2.4, §3, §4.2, App. 1; practiced on CI-Eng-Sample 2026-10-01	verified (PROCESS-side ITEM.* events from docs)

Configure the audit trail

1. Event classifiers — what is stored

Each event type is a classifier <SUBJECT>.<ATTRIBUTE>.<ACTION>.<SOURCE> in AUDIT_EVENT_CLAS_DF (NAME, SUBJECT, ATTRIBUTE, AGITATION = action, SOURCE, BASIC_SET, STORAGE). Only STORAGE can be changed. Configuration and DSS value changes use subject DATASET with attribute NULL-ATTR, e.g. DATASET.NULL-ATTR.MODIFY.LOC-ENG-MOD (Engineering Module) or ….ENT-ENG-MOD (dssqld); logins use CI-SERVER.NULL-ATTR.LOGIN.<source>.

List the classifiers (and which are off): dssqld -e ecl.qlo -d AUDIT_EVENT_CLAS_DF. Change:

@FIELDS
NAME,STORAGE
@AUDIT_EVENT_CLAS_DF
"<SUBJECT>.<ATTRIBUTE>.<ACTION>.<SOURCE>",0

dssqld -m, or in the Engineering Module Configuration › Audit trail › Event classifiers (the change itself is audited: AUDIT_EVENT_CLAS_DF STORAGE MODIFY). Not immediate: the processes that report events (e.g. DSSSDA) cache the storage flags and re-read them every ECL_REFRESH seconds (default 1800). Verified: a classifier switched off was still recorded right after the change and no longer 31 minutes later; switching it back on is delayed the same way. Allow up to 30 minutes or restart CI Server (ISS-050). Confirm with the user before switching anything off.

Item option Audit trailing wanted (AUDIT_INFO)

ITEM_DF / SUB_ITEM_DF / EXTERNAL_ALARM_DF field AUDIT_INFO (default 0). It switches the ITEM.* / SUB-ITEM.* events raised by ITEM Service for operator writes. Verified on CI-Eng-Sample.PUMP1.MODE with the buttons on display CIENG_Tank:

• AUDIT_INFO 1: a button write 0 → 1 stored ITEM VALUE MODIFY OPER-INTERFACE, user ADMIN, old 0 / new 1, plus ITEM STATUS MODIFY (13 → 9).
• AUDIT_INFO 0: the write 1 → 0 left no audit record.

It does not affect DSS writes (dssqld, Engineering Module: always audited as ITEM_VAL dataset events) or itmval -p (never audited). Sample: 19b_audit_item_df.qli (dssqld -m, NAME,AUDIT_INFO). PROCESS writes (COMPUTE) also need AUDIT = YES in tls\sup\opc.sup (installed NO) and their classifiers are off by default; not tested.

2. Selection groups

A selection group is a named, compiled filter for an AUDIT destination (ADTLOG, the chronological overview). Dataset AUDIT_SELGRP_DF: NAME (≤ 32), DESCRIPTION, EXPRESSION (memo), COMPILE (1 = compile now), LISTING (compiler output), VALID_EXPRESSION.

Expression language (from the compiler's own listing):

• Words compared with a string: aai1 acnd acnm actm mai1 nond nonm reas sacs sact satr sbgp sbid term user (same meaning as the E_LAYOUT units in §4: sbgp subject, satr attribute, sact action, sacs source, sbid subject id, user …).
• Words compared with a constant: nval oval (new / old value).
• Operators = != > < >= <=, and, or, parentheses. No LIKE: match a name prefix with a range, e.g. sbid >= "<Section>." and sbid < "<Section>/" (/ sorts right after .).

Example (examples/CI-Eng-Sample/19_audit_df.qli):

@FIELDS
NAME,DESCRIPTION,EXPRESSION,COMPILE
@AUDIT_SELGRP_DF
"CIENG_ITEMS","Audit events on CI-Eng-Sample",@"
sbid >= "CI-Eng-Sample." and sbid < "CI-Eng-Sample/"
"@,1

dssqld -i. Write the memo over several lines (@" newline … newline "@): on one line @"<text>"@ is taken as a file name (CRL-E-EINVAL / CRL-E-ENOENT). Check: export the dataset — LISTING ends with ADTT-I-CMP_SUCC, Expression successfully compiled and VALID_EXPRESSION is 1. An error (e.g. ADTT-E-UNKNOWN_TOK) makes the dssqld line fail with ADTT-E-CMP_NO_SUCC and leaves VALID_EXPRESSION 0. Remove with dssqld -r (NAME only).

3. Event logger ADTLOG

adtlog -n <name> connects to ADTSTO and prints each new event as text (stdout, or the printer in PRT_DEV). It is not started by default (audit_start.cmd has it commented out; fmfprt.sup assigns the printer function AUDIT_TRAIL to ADTLOG). A process reads tls\sup\<name>.sup, so one setup file per logger instance.

Without a setup file the default layout is three lines per event (time with milliseconds, subject, attribute, action, source / subject id, user / old and new value). Verified test: adtlog -n adtlogt in a console, then a value write — the logger printed the LOGIN, the ITEM_VAL change and the LOGOUT. A console logger runs until stopped: Ctrl+C, or durstp -m -p <name> (skill system-management, bus-utilities.md).

Filtered logger: examples/CI-Eng-Sample/audit/adtlogci.sup (SEL_GROUP = "CIENG_ITEMS", one-line E_LAYOUT, TIMEFMT, HEADER, HEADER_AFTER). The user copies it to %TLS_ROOT_PATH%\tls\sup\ (admin); then adtlog -n adtlogci printed only the CI-Eng-Sample changes (no logins), one line each under the header. If the selection group does not exist or did not compile, the logger logs an error and exits. To run it permanently, add a start /B /NORMAL %TLS_ROOT_PATH%\tls\exe\adtlog -n <name> line to audit_start.cmd (admin, restart).

4. Setup keywords (adtsys.sup is the template)

MAX_OPEN_UNITS (20), PRT_DEV, QUESIZE (kB), SEL_GROUP; COL_PROC, DST_PROC, HIS_PROC, STO_PROC = <node>, <name>; NODE_ECL_FILE, NODE_SGP_FILE; E_LAYOUT = <unit>,<width>,… (AAI1 ACND ACNM ACTM MAI1 NOND NONM NOTM NVAL NWLN OVAL REAS SACS SACT SATR SBGP SBID SPCE TERM USER), E_NOSPACE, TIMEFMT (DD/MM/YY hh:mm:ss.ppp default — milliseconds shown, as the manual says); ECL_REFRESH (1800 s), FLOWC (30, 10), HBEAT (10), TRYCON (10); FORM_FEED, HEADER (repeat for more lines), HEADER_AFTER (re-print after n events; the header is also printed once at start). Which keyword applies to which process: L25 §4.2.2.

5. Retention

Audit records live in history storage group ADT (rollover 1 day; lifetime 52 weeks on the test system). Longer/shorter retention = change LIFE_TIME of ADT (skill history-management); archive like any storage group. Ask before shortening it.