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

---

task: Choose what AUDIT Service stores (classifier STORAGE, AUDIT_INFO), define selection groups, run an event logger (ADTLOG) version: R1.05 (first written for R1.03) source: IM 36K10L25-01EN §2.4, §3, §4.2, App. 1 (4th ed., Feb. 2026); R1.05 adtsys.sup, audit_start.cmd; practiced on CI-Eng-Sample 2026-10-01 status: verified on R1.03 (2026-10-01; PROCESS-side ITEM.* events from docs). R1.05: classifier list, setup file and start scripts checked 2026-10-09 (read-only); selection group CIENG_ITEMS loaded with 0 errors 2026-10-08 (load check only); STORAGE change, ADTLOG and the new APPRR / APPR layout units not tested on the shared server (awaiting user verification)

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>. R1.05 adds action PENDING and sources REST-SERVER, PYTOOLS, PASSWORD-CHECK (499 classifiers; list in audit-checks.md §3, ISS-141); the REST API, pyTOOLS and Password Check events can be switched off like any other.

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 (2026-10-01; re-checked 2026-10-06 with Manual / Auto on CIENG_Control: same events, user and old / new value):

• 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 .).
• R1.05: whether the compiler also accepts the new units apprr / appr was not tested (compiling needs a load; awaiting user verification on a non-shared system).

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 (admin, restart):

• R1.03: add a start /B /NORMAL %TLS_ROOT_PATH%\tls\exe\adtlog -n <name> line to audit_start.cmd.
• R1.05: put that line in your own tls\com\<prefix>_audit_start.cmd (e.g. cieng_audit_start.cmd) and a matching durstp line in <prefix>_audit_stop.cmd; audit_start.cmd / audit_stop.cmd call every ?*_audit_start.cmd / ?*_audit_stop.cmd (ISS-142). The product script stays untouched, so an upgrade does not lose the line. From the installed scripts; not tested (needs admin and a 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; R1.05 adds APPRR approval reason and APPR approver, ISS-140), 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 R1.03 test system and on the R1.05 test server). Longer/shorter retention = change LIFE_TIME of ADT (skill history-management); archive like any storage group. Ask before shortening it.