ci-server-engineer/examples/CI-Eng-Sample/README.md

CI-Eng-Sample

A small, invented sample project that anyone with this repo can load into a CI Server test system (R1.03 or R1.05). Skills use its names in their examples, and every skill task is re-tested against it so that no other project is needed.

Built and tested on CI Server R1.03.00 (unlicensed test system), 2026-09-30; operator HMI, demo user and live-data feed added 2026-10-06. Reduced load (below) tested on R1.05.00 on a shared server, 2026-10-08: loads with 0 errors (the @VERSION 1.03.00 headers are accepted).

Every test ends with the system back in its original state: remove what was loaded, stop processes started for the test, undo certificate trust, delete scratch and temporary files.

Load and remove

Test systems only: loading writes to the CI Server database. CI Server must be running. From an elevated prompt, call the scripts by full path (a bare load.cmd may not be found from the current folder):

cmd /c "<repo>\examples\CI-Eng-Sample\load.cmd"
cmd /c "<repo>\examples\CI-Eng-Sample\remove.cmd"

• Each step prints a summary and writes a .qlo listing; check that Errors is 0.
• Restart CI Server after loading (stop, then start the CI Service): a new storage group stores no history until CI Server restarts.
• load.cmd on a system that already has the project reports Exists and changes nothing.
• Before remove.cmd, log out every CIENG session (Operator Interface and web): on 2026-10-06 an open session kept its user's authorization group in use (DSSP-E-NODEL … USER_VAL), and a retry in that state stopped the DSSSDA03 process (DUR-F-BAD_SIZE) until CI Server was restarted.
• remove.cmd takes about 1½ minutes: a storage group can only be deleted after its stop time has passed, so the script sets a stop time one minute ahead and waits. Removing the group also deletes its history.

Testing on a shared server (shared\)

For a server that other projects use, where CI Server must not be restarted:

Script	Does
shared\snapshot.ps1 -Out <file>	Read-only snapshot: record names (count, hash, CIENG* names) of every dataset the sample touches, file lists of tls\com, sup, sav, lst, the pki folders, running CI Server processes. Run before and after; compare the two files.
shared\reduced_load.cmd	load.cmd without the storage groups and history bindings (03, 04: need a restart), the authorization group and user CIENG (08, 08b: a password-less user on a shared server) and the layouts/displays (shared Layouts.xml)
shared\test_r105.ps1	Starts the Modbus slave mirror only for the test, checks classes, sub-items, Modbus loopback and OPC UA loopback with itmval, stops the mirror again
shared\reduced_remove.cmd	Removes exactly what reduced_load.cmd loaded
shared\clean_dss_tmp.ps1 -Since <time>	Deletes the dss_*.tmp files the test left in %TLS_LST_PATH% (ISS-091)

Copy the whole sample folder to a temporary folder on the server, run from there, and delete it afterwards. Also delete %TLS_LOG_PATH%\OPXCIENG.log. The OPC UA certificate exchange and its undo are user steps (see below); the client's own certificate <host>_OPXCIENG.der/.pem and the trusted copies stay in the pki folders (and in OPCUAC_PKI_CERTIFICATES_DF, which follows the files) until they are deleted; the server-side pkiserver\rejected folder is also created by the test; delete it when it is empty.

Current contents

Name	Kind	Details
CI-Eng-Sample	Section	Top level
CI-Eng-Sample.TANK1, .PUMP1, .SYSTEM	Sections	Tank, pump, system monitoring
CI-Eng-Sample.TANK1.LEVEL	Item, Real	%, format 999.9, limits LL 10 / L 20 / H 80 / HH 90, scale 0–100, stored in CIENG_EVENT; alarming on (ack type CIENG_ACK, area CIENG_TANKS; 16_item_alarm_df.qli)
CI-Eng-Sample.TANK1.INFLOW	Item, Real	m3/h, format 9999.9, scale 0–500, stored in CIENG_EVENT
CI-Eng-Sample.PUMP1.RUNNING	Item, Boolean
CI-Eng-Sample.PUMP1.MODE	Item, Integer	0 manual, 1 auto
CI-Eng-Sample.SYSTEM.CPU_LOAD	Item, Real	Target for intcpumon
CI-Eng-Sample.SYSTEM.DISK_C	Item, Real	Target for intdskmon (reports used %)
CI-Eng-Sample.SYSTEM.PING_LOCALHOST	Item, Integer	Target for inttcpmon (1 = reachable)
CI-Eng-Sample.SYSTEM.PROC_ALM	Item, Integer	Target for intmon (1 = alm process running)
CI-Eng-Sample.PUMP1.RUNNING.RUN_SECONDS	Sub-item, Integrator	Running time in seconds (adds value × integration granule, itm_int_secs in itm.sup, default 1 s)
CI-Eng-Sample.TANK1.LEVEL.MAX	Sub-item, Min-Max	Highest level seen
CI-Eng-Sample.DEMO	Section	Tutorial examples
CI-Eng-Sample.DEMO.COUNTER	Item, Integer	Counts 1…100, one step per second, written by DEMO.INCR1
CI-Eng-Sample.DEMO.FEED_ON	Item, Boolean	1 while the live-data feed runs in display mode (feed\cieng_feed.ps1 -UntilFlag); the display button Stop writes 0
CIENG_1S	Trigger group	Every second
CIENG_INCR	Class (traditional)	Increments DEMO.COUNTER, wraps at 100; compiled on load
CI-Eng-Sample.DEMO.INCR1	Object	Instance of CIENG_INCR
CI-Eng-Sample.TEMPLATES	Section	Template items for classes
CI-Eng-Sample.TEMPLATES.TPL_REAL	Item, Real	Template for items that objects create (format 9999.9, scale 0–1000)
CIENG_TANK	Class (traditional)	Prompt Tank capacity (m3); signal LEVEL = <object section>.LEVEL (trigger on value); creates <object>.VOLUME from TPL_REAL; volume = level × capacity / 100; logs when the level crosses 80; refuses capacity ≤ 0
CI-Eng-Sample.TANK1.CALC	Object	CIENG_TANK, capacity 200; creates section TANK1.CALC and item TANK1.CALC.VOLUME
CIENG_JFLOW	Class (Java)	Attaches <object section>.INFLOW; creates <object>.sPerMin = inflow / 60; logs each change
CI-Eng-Sample.TANK1.JFLOW	Object	CIENG_JFLOW; creates item TANK1.JFLOW.sPerMin (mixed case, as the Java identifier)
CIENG_EVENT	Item storage group	Event/Item, lifetime 1 week, rollover 1 day
CIENG_SCAN10S	Item storage group	Scan/Time every 10 s with quality, priority 10 (source for aggregation), lifetime 1 day, rollover 1 hour; TANK1.LEVEL, TANK1.INFLOW
CIENG_AGG	Item storage group	Aggregation 30 min + hourly, lifetime 4 weeks, rollover 1 week; TANK1.LEVEL max/min/average (read with INTERPOLATION = "30Minutes" / "Hour", ATTRIBUTE = "Maximum" …)
CI-Eng-Sample.PLC1	Section	Modbus loopback station
CI-Eng-Sample.PLC1.COMM_OK	Item, Boolean	Status item of station CIENG_PLC (1 = communicating, status 22 when off-scan)
CI-Eng-Sample.PLC1.SETPOINT / .READBACK	Items, Integer	Written to holding register 1 (RO:1) / read from input register 1 (RI:1), same memory
CI-Eng-Sample.PLC1.CMD / .FEEDBACK	Items, Boolean	Written to coil 1 (DO:1) / read from input bit 1 (DI:1), same memory
CIENG_MB_LINE	Modbus line (TCP/IP)	Equipment manager EQPCIENG (created and started by loading the line)
CIENG_PLC	Modbus station	Open Modbus/TCP to localhost:5020, unit 1, output method On change and connect
CIENG_SCAN1S	Modbus scan type	1000 ms
CI-Eng-Sample.UA	Section	OPC UA loopback station
CI-Eng-Sample.UA.COMM_OK	Item, Boolean	Status item of station CIENG_UA (1 = connected)
CI-Eng-Sample.UA.LEVEL_COPY	Item, Real	TANK1.LEVEL read back through CI Server's own OPC UA server
CI-Eng-Sample.UA.SRV_STATE	Item, Integer	OPC UA server state node (ns 0, i=2259), 0 = Running
CIENG_UA_LINE	OPC UA client line	Client process OPXCIENG (created and started by loading the line)
CIENG_UA	OPC UA station	opc.tcp://localhost:34493, Basic256Sha256 / SignAndEncrypt, anonymous; subscription CIENG_SUB (1 s); points LEVEL, SRV_STATE
OPC visible	Flags	Sections CI-Eng-Sample, TANK1 and item TANK1.LEVEL are OPC visible, item read-only (12_opc_visible_df.qli)
CIENG_ACK	Acknowledgement type	Every alarm needs an acknowledgement; return to normal automatic only if the alarm was acknowledged (same matrix as MANUAL)
CIENG_TANKS	Area of interest	Label for tank items (TANK1.LEVEL AOI_1)
CIENG_TANK1	Alarm selection area	SECTION = "CI-Eng-Sample.TANK1", compiled on load
CIENG_VIEWER	Authorization group	Read-only: ITEM_READ, SECTION_READ, ALARM_CURRENT_READ, ALARM_CHRONO_READ
CIENG	User	Demo user, no password, factory group OPERATOR; logs on to layout CIENG_Operator with display CIENG_Overview (desktop and web). The only user the sample creates; ADMIN is not changed.
CIENG_FILE	Printer device + destination	FILE output to %TLS_LST_PATH%\cieng_report.txt (overwritten by each printed report); destination visible to operators
CIENG_TANK1	Report	Values of the TANK1 items + last-hour statistics of one item (ad-hoc parameter chosen in an item browser, default LEVEL); daily 06:00 local time and ad hoc; output CIENG_FILE; lifetime 1 week
CIENG_INFLOW_HI	Report	Generated 5 s after TANK1.INFLOW rises above 400; output CIENG_FILE
CIENG_HTML	Report	Ad hoc; TANK1 values as an HTML table (cursor loop) plus the logbook text
CIENG_AUDIT	Report	Ad hoc; audit trail events on CI-Eng-Sample.* of the last hour
CIENG_ITEMS	Audit selection group	Expression sbid >= "CI-Eng-Sample." and sbid < "CI-Eng-Sample/", compiled on load

Items created by objects (TANK1.CALC.VOLUME, TANK1.JFLOW.sPerMin) and their sections are deleted with the objects; they are not in 02_item_df.qli.

All items except PLC1.* are internal (no station). The PLC1 station talks to CI Server's own Modbus slave mirror (see below), so no PLC is needed either. New items start with status 13 (NOT INIT) until a value is written.

Files

File	Purpose
01_section_df.qli	Sections (SECTION_DF); parents before children
02_item_df.qli	Items (ITEM_DF)
02b_sub_item_df.qli	Sub-items (SUB_ITEM_DF)
03_his_group_df.qli	Item storage groups (HIS_GROUP_DF): event, scan, aggregation
04_item_his_df.qli	Items in the storage group (ITEM_HIS_DF, name <group>:<item>)
05_trigger_df.qli, 06_class_df.qli, 07_object_df.qli	Trigger group; classes (source in the METHOD memo, @" … "@, COMPILE 1; Traditional and Java); objects (ATTR_VALUE_1 = prompt answer)
08_auth_group_df.qli	Authorization group (AUTH_GROUP_DF)
08b_user_df.qli	Demo user CIENG (USER_DF); PASSWORD "" given explicitly - without the field the user has no password set and every logon fails (DSS-E-UNK_USER)
09_modbus_line_df.qli, 10_modbus_station_df.qli, 11_item_eqp_df.qli	Modbus line; station, scan type, points; items connected to points
12_opc_visible_df.qli	OPC visible / read flags (loaded with dssqld -m)
13_opcua_line_df.qli, 14_opcua_station_df.qli, 15_item_opcua_df.qli	OPC UA client line; station, subscription, points; connected items
01b_alarm_df.qli	Alarm definitions: acknowledgement type, area of interest, alarm selection area (ALARM_ACK_DF, ALARM_AOI_DF, ALARM_ASA_DF)
16_item_alarm_df.qli	Switch on alarming for TANK1.LEVEL (loaded with dssqld -m)
17_printer_df.tpl, 17_printer_df.ps1	Report file device and destination; the script fills in this system's node name and %TLS_LST_PATH% and writes 17_printer_df.qli (not in the repo)
18_report_df.qli	Reports (REPORT_DF, RQL in the QUERY memo)
19_audit_df.qli	Audit selection group (AUDIT_SELGRP_DF) and audit report
audit/adtlogci.sup	Setup file for an extra audit event logger ADTLOGCI filtered on CIENG_ITEMS (copied to tls\sup by an administrator, not by load.cmd)
83a_stop_report_df.qli	Clears the schedule of CIENG_TANK1 before removal (a scheduled report cannot be deleted)
equipment/eqpciengslv_start.cmd, _stop.cmd	Start/stop the Modbus slave mirror (copy to tls\com)
76_…93_remove_*.qli	Names to delete, in reverse order (audit 79, reports and printer 83/84 first, alarm definitions last, 93)
load.cmd, remove.cmd	Run the steps in the right order
19b_audit_item_df.qli	Audit trailing wanted for PUMP1.MODE (loaded with dssqld -m)
displays/CIENG_*.xml	The operator HMI: 8 displays in HTML mode (desktop and web), see Displays and layout
displays/generator/	build.py + cixml.py write the CIENG_*.xml files (Python 3 + Pillow); README.md there describes the tool
layouts/CIENG_Operator.xml, layouts/layout.ps1	Layout block (CIENG_Operator, CIENG_Popup) and the script that adds/removes it in Layouts.xml
displays/add_trend_spares.ps1	Pads every trend in a display file to 50 visible pens (web workaround, ISS-041); safe to run again. Kept as a tool; the sample trend is not padded
displays/deploy_displays.cmd, remove_displays.cmd	Copy the displays into the operator interface and export their HTML versions / delete them
feed/cieng_feed.ps1, cieng_feed_start.cmd, install_feed.ps1	Live-data feed (test values for the tank, pump and system items), its start wrapper for the display button, and the installer into C:\Users\Public\CI-Eng-Sample\feed
monitoring/*.sup.txt	Setup-file lines for the monitoring processes (not applied by load.cmd)

Modbus slave mirror (for station CIENG_PLC)

CIENG_PLC reads and writes CI Server's own Modbus slave: eqpmdcmem (slave memory) and eqpmdcslvtcp (Modbus TCP on port 5020). Without them the station reports bad communication (COMM_OK = 0) but everything loads. To start them with CI Server, an administrator copies equipment/eqpciengslv_start.cmd and eqpciengslv_stop.cmd to %TLS_ROOT_PATH%\tls\com; for a quick test they can also be started by hand from a normal prompt:

start eqpmdcmem -n EQPMDCMEM
start eqpmdcslvtcp -n EQPMDCSLVTCP -p 5020

Remove the two files from tls\com when the sample is removed. See skill equipment, task modbus-station.md.

OPC UA loopback (station CIENG_UA)

CIENG_UA is CI Server's OPC UA client connected to CI Server's own OPC UA server, so no external server is needed. The first connection on a system needs a one-time certificate exchange, done by the user (skill data-access, task opcua-client.md §4):

1. After loading, the client logs OPXC-E-CER_NO_TRU; trust the server certificate in %TLS_ALLUSERS_PATH%\pki\opxuac\pkiclient\rejected (Engineering Module, or move it to …\pkiclient\trusted\certs).
2. The server then rejects the client; move CI_SERVER_OPCUA_CLIENT_OPXCIENG […].der from %TLS_ALLUSERS_PATH%\pki\opxuas\pkiserver\rejected to …\pkiserver\trusted\certs (PowerShell: Move-Item -LiteralPath, the name contains brackets).

Then UA.COMM_OK = 1 and UA.LEVEL_COPY follows TANK1.LEVEL. The trust is kept when the sample is removed and loaded again.

Alarms (TANK1.LEVEL)

TANK1.LEVEL raises HIGH above 80 (Alarm 2, priority 2) and HIGH HIGH above 90 (Alarm 3, priority 1). To try it on a test system: itmval -p -n CI-Eng-Sample.TANK1.LEVEL -v 85, export ALARM_CURRENT (filter on ITEM_NAME), acknowledge with dssqld -m on ALARM_CURRENT (NAME, ACK 1), write the level back below 80. See skill alarm-management, task item-alarming.md.

Displays and layout (optional)

A dark dashboard-style operator HMI with its own layout (no AOG displays). All displays are in HTML mode, so the same files run in the Operator Interface (desktop) and in the browser (web). No admin rights needed. After load.cmd:

1. displays\deploy_displays.cmd copies the 8 displays into the operator interface and creates their HTML versions.
2. powershell -ExecutionPolicy Bypass -File layouts\layout.ps1 adds the layouts CIENG_Operator and CIENG_Popup to Layouts.xml (first run saves Layouts-before-CIENG.xml). Restart the Operator Interface afterwards: it reads the layouts only at start.
3. powershell -ExecutionPolicy Bypass -File feed\install_feed.ps1 installs the live-data feed (see Live data).
4. Log in as CIENG (no password): Operator Interface, or the web at http://localhost:8080/mobileoperator/. Other users: ?l=CIENG_Operator (web) or jwuipoi.cmd -layout CIENG_Operator (desktop).

Display	Where	Shows
CIENG_Header	top frame	KPIs (level coloured by its limits, inflow, volume, pump, PLC / OPC UA communication), live data Start / Stop with lamp, Tank 1 faceplate button, last update
CIENG_Overview	tab Overview	Tank 1 mimic (inflow pipe, level fill coloured by limits, limit marks, pump, outlet pipes), volume / flow / maximum / counter / run time, three ring gauges, micro trend; click the tank for the faceplate
CIENG_Control	tab Process control	Slider, spinner and input field on PLC1.SETPOINT with Modbus readback; toggle and Set ON / OFF on PLC1.CMD with FEEDBACK lamp; pump mode combo box and Manual / Auto buttons (audited), run check box; level test slider and buttons LL / L / Normal / H / HH
CIENG_Trends	tab Trends	Trend of level and inflow (10 min, 2 pens) and micro trends for level, inflow and CPU
CIENG_Alarms	tab Alarms	Current alarms and alarm history of CIENG_TANK1
CIENG_System	tab System	CPU and disk gauges, communication and process lamps with status, OPC UA loopback, report component
CIENG_AlarmBanner	bottom frame	Tank 1 alarm lamp, Alarm list button, 4-row alarm banner
CIENG_TankFaceplate	layout CIENG_Popup	Level, status, limits, maximum, last update, micro trend, Trends / Alarms / Close

Screen sizes: designed for 1920 x 1080. The desktop opens the tabs with stretchDisplay, so they fill any monitor (slightly stretched where the ratio differs); maximise the window, it opens over the taskbar. The web client does not zoom displays: use full screen (F11) and the browser zoom (estimates, not tested: about 100 % at 1920 x 1080, 80 % at 1536 x 864, 70 % at 1366 x 768).

Known limits (R1.03.00): the trend draws no line in the browser (a web trend needs 50 pens, ISS-041; the 2-pen trend keeps the desktop hairline box readable); the empty part of the alarm lists stays white; a tab opened by clicking the tab strip itself keeps its zoom until it is opened once from the toolbar, menu or F1–F6.

Remove: layouts\layout.ps1 -Remove (restores the file exactly), displays\remove_displays.cmd and feed\install_feed.ps1 -Remove. Close the displays in the Edit Module first. See skill graphics.

Live data

The sample items are internal: after a CI Server start they stay NOT INIT, so displays, trends and alarms show nothing until values are written. feed\cieng_feed.ps1 writes them every 5 s:

Option	Effect
(none)	Runs -Seconds (default 3600): TANK1.LEVEL 50 ± 25 % (inside the limits), TANK1.INFLOW 250 ± 150 m3/h; PUMP1.RUNNING follows the inflow in auto mode
-Alarms	TANK1.LEVEL 50 ± 33 %: crosses L 20 and H 80, so alarms appear (manual acknowledgement)
-System	Also writes SYSTEM.CPU_LOAD / DISK_C / PING_LOCALHOST / PROC_ALM with this PC's values; skipped while the monitoring processes run (they write the same items)
-UntilFlag	Runs while DEMO.FEED_ON = 1 (display buttons Start / Stop)

The header button Start runs C:\Users\Public\CI-Eng-Sample\feed\cieng_feed_start.cmd on the server (as the CI Server service account CIX_PROCESS; the factory group OPERATOR is enough), which starts the feed with -UntilFlag -Alarms -System. Only one copy runs at a time. Log: %TLS_LST_PATH%\cieng_feed.log. Stop the feed before manual tests with itmval (it overwrites the values within 5 s). After a CI Server restart the Live data lamp can stay green although no feed runs: click Start.

Monitoring processes (optional)

monitoring/ holds the lines to add to the setup files in %TLS_ROOT_PATH%\tls\sup\ so that intcpumon, intdskmon, inttcpmon, intmon and intspawn write into the SYSTEM items. These change the system's own setup files: back the files up first and restore them after testing. While they run, the live-data feed leaves the SYSTEM items alone (-System is skipped). See the system-management skill, task monitoring-processes.md.

Reports

No admin rights needed. load.cmd creates the device, destination and three reports; each report gets its own storage group of type Report. Try them (skill reporting, task define-reports.md):

• Ad hoc: REPORT_DF NAME,PARAM_VALUE_1,GENERATE = "CIENG_TANK1","CI-Eng-Sample.TANK1.INFLOW",1 with dssqld -m, or in the Engineering Module Configuration > Reporting > Reports › right-click › Generate. The output lands in REPORT_VAL; runs from the Engineering Module also print to %TLS_LST_PATH%\cieng_report.txt (runs from dssqld do not print, ISS-045).
• Trigger: itmval -p -n CI-Eng-Sample.TANK1.INFLOW -v 450 → CIENG_INFLOW_HI 5 s later; write a value below 400 before the next test.
• CIENG_TANK1 also runs every day at 06:00 (local time).

remove.cmd clears the schedule, removes the reports (with their generated reports and logbook files), the destination and device, and deletes cieng_report.txt.

Audit trail

No admin rights needed for 19_audit_df.qli. Every change made by load.cmd, dssqld or the Engineering Module is in the audit trail (skill audit-trail):

• Generate CIENG_AUDIT (ad hoc, like the other reports) to list the last hour of changes on CI-Eng-Sample.*: time, dataset, field, action, source, user, old and new value.
• Operator writes: with the displays deployed, click Manual / Auto on CIENG_Control; each click is stored as ITEM.VALUE.MODIFY.OPER-INTERFACE because PUMP1.MODE has Audit trailing wanted (19b_audit_item_df.qli).
• Export: dssqld -e audit.qlo -d AUDIT_TRAIL (whole trail) or a qli with @SELECT (keep NAME in @FIELDS).
• Event logger (optional, admin): copy audit\adtlogci.sup to %TLS_ROOT_PATH%\tls\sup\, then run adtlog -n adtlogci in a console; it prints each new CI-Eng-Sample event on one line (Ctrl+C to stop). Delete the file from tls\sup when the sample is removed.

Audit records themselves cannot be deleted; remove.cmd removes only the report and the selection group.

Planned additions

Phase	Adds
10	A symbol (the faceplate popup CIENG_TankFaceplate exists since 2026-10-06)

Rules

• Test systems only; invented names only, no real plant or customer data.
• Keep the load order: sections → template items → classes (compiled) → objects → other items → storage groups → items in storage groups (IM 36K10J10 §5.6). Keep remove.cmd in reverse order.
• Every file notes the CI Server version it was built and tested on.