ci-server-engineer/.claude/skills/graphics/tasks/trend.md

---
task: Configure a trend (chart) component; what each setting does on the desktop and in the HTML display
version: R1.05 (first written for R1.03)
source: IM 36K10C50-01EN §2.27 (Trend, Tables 2.27-10…28), §2.29 (Micro Trend) (R1.05 5th ed. Feb. 2026); IM 36K10R30-01EN §4.8.7 (R1.05 4th ed. Feb. 2026); installed web client code (`%TLS_WAP_PATH%\mobileoperator\src\fasttools\ui\components\implementation\charts\`); practiced on CI-Eng-Sample (display CIENG_TrendLab, removed 2026-10-06) 2026-10-02; sample trends CIENG_Trends / CIENG_TankFaceplate and a test display on both clients 2026-10-06
status: verified on R1.03 (desktop Operator Interface: every row marked ✅/❌ below; HTML display: §6). R1.05: manuals re-checked 2026-10-08 — §2.27/2.29 unchanged except the trend's *Enterprise* property, now marked supported on the HTML display (from docs). Not re-tested on R1.05; whether the 50-pen web problem (ISS-041) still exists in the R1.05 web client is awaiting user verification (ISS-096) R1.05 (V5, 2026-10-09): pen limit and DataSource.js change read from the installed code; 50-pen problem probably fixed, not tested.
---

# Trend settings (desktop and web)

The settings below were tested on the sample display `CIENG_TrendLab` (removed from the sample
on 2026-10-06). Method used: change one XML value in the display, deploy, *View > Reload* in the
client, compare. Current sample: `CIENG_Trends` (trend with 2 pens and micro trends) and the
micro trends on `CIENG_Overview` and `CIENG_TankFaceplate`.

## 1. Before you start

- **Data**: the trend draws history. `TANK1.LEVEL` / `TANK1.INFLOW` are internal items: after a
  CI Server start they are `NOT INIT` (value 0) until something writes them, and the trend then
  shows nothing (or a bold black line at 0 with status drawing). For tests run
  `feed/cieng_feed.ps1` (writes sine waves with `itmval` every 5 s; `-Seconds` = run time,
  default 3600; it replaced `displays/trend_feed.ps1` on 2026-10-06), or the sample displays'
  live-data button *Start*.
- **Reload**: changes in the display file show after *View > Reload*. A reload within a few
  seconds of the deploy can still show the old file — reload again.
- The **Trend properties** dialog (right-click the trend) and the trend toolbar change the trend
  only for the session; *Save trend as* writes a trend definition to
  `%TLS_WAP_PATH%\cfg\charts\<name>.xml` (same `<chartPanel>` format; factory `Template1..4.xml`).
  The display file holds the start-up settings under `<chart>` › `<config>` › `<chartPanel>`.

## 2. Pen source (`<pen>` › `<source uri=…>`)

```
ci:/item/<Section>.<Tag>[?historygroup=<GROUP>[&amp;aggregationperiod=<PERIOD>]][#<ATTR>]
```

| Part | Values | Result (desktop and web the same) |
|---|---|---|
| no `historygroup` | — | works; trend picks the highest-priority storage group (here `CIENG_SCAN10S`, seen in table mode); legend without `[group]` |
| `historygroup=CIENG_EVENT` / `CIENG_SCAN10S` | an item storage group | works; legend `… [GROUP]` |
| aggregation group without attribute | e.g. `CIENG_AGG` | ❌ `WFL-E-HIS_ITMN` / `ITH-E-NO_ADM_UPD` *Item not defined in group, or group not specified* |
| aggregation group **with** `aggregationperiod` + `#MAX` | periods `30MIN HOUR SHIFT DAY WEEK MONTH YEAR`; attributes `MAX MIN AVG INT SDV CNT DFSM` | ✅ one flat segment per finished period; legend `… / AGG_MAX 30MIN [CIENG_AGG]` |
| `#H` `#HH` `#L` `#LL` `#DB` | limit / deadband attributes | ❌ *Record not found* unless the limit history is stored |
| `uri=""` | — | empty pen |

`&` must be written `&amp;` in the XML. The *Pen attributes > Attribute[n]* property of the
component is the same attribute (`ITEM_VALUE`, `AGG_MAX`…): connecting it to an item by mistake
gives *Short attribute name (<value>) is invalid* (ISS-041 history).

## 3. Pen settings (`<pen>`)

| XML | Values | Desktop result |
|---|---|---|
| `type` | 0/1 line, 2 bar (no button in the pen panel), 3 stair-step, 4 scatter (squares); **+256** = status drawing: offline / `NOT INIT` parts drawn bold black (256 = Edit Module default = line + status) | ✅ |
| `color`, `stroke width` | | ✅ |
| `paint` (fill) `<paint type="paint"><paint type="colorSet" …/></paint>` | | ✅ filled from 0 up, **opaque** (covers other pens); legend symbol filled |
| `visible` false | | ✅ line hidden **and** removed from legend; tick cleared in the pen panel |
| `visibleLegend` false / `legendText` | | ✅ hidden from / renamed in the legend |
| `scaleRangeType` | **0** item scale range (item definition), **1** manual `minimum`/`maximum`, **2** fit to data (with margin; min/max ignored) | ✅ |
| `procentual` | | ✅ axis 0–100 % of the range, `%` label |
| `timeShift` | seconds | ✅ data drawn later by that time (overlay of older data) |
| `axisVisible` | | ✅ value axis (left); clicking a legend entry also shows that pen's axis and thickens the line (hover thickens) |
| `axisPosition` | 0 left, 1 right | ✅ |
| `axisColor`, `labelColor` (`<axisColor type="colorSet" r=… g=… b=…/>`, `@NULL` = pen colour) | | ✅ axis + ticks / numbers |
| `labelRotation` | degrees | ✅ |
| `majorTickVisible` + `minorTickVisible` false | | removes the numbers too |
| `title`, `titlePlacement` | | ❌ nothing shown |
| `majorGridVisible`, `minorGridVisible`, `majorGridColor` | | ✅ horizontal grid in pen colour / given colour |
| `lowHighLimitGridVisible`, `lowLowHighHighLimitGridVisible` | | ✅ lines at the **item definition** limits |
| `lowLimit`…`highHighLimit` | | ❌ ignored (item definition limits are used) |
| `lowHighLimitGridAreaVisible` | | ✅ band L…H in pen colour, **opaque, drawn over the line** |
| `maximumPens` (chart level) | | ✅ only the first n pens are loaded |
| `description` | | pen panel shows the **item** description, not this value |

## 4. Chart settings (`<chartPanel>`)

| Group | XML | Desktop result |
|---|---|---|
| Time range | `<timeRange type="timeRangeLast" count="10"><type type="timeUnit" value="TimeUnitMinute"/></timeRange>`; `timeRangeCurrent` (no count) = current minute/hour/day…; units `TimeUnitMinute Hour Day Week Month Year` | ✅ (*Current hour*: 12:00–13:00, line up to now) |
| | `updating` true | ✅ runs live when opened (play grey, stop red) |
| | `updateInterval` (s) | ✅ shown in *Update every* (60 → "1 Minutes") |
| | `autoUpdateInterval` true | ✅ the *Update every* field disappears |
| | `fillHistory` false | ✅ empty (all pens red tag) until the first update interval, then filled |
| | custom range: `<timeRange type="timeRangeSpecific"><startTime type="date" value="2026.10.02 13:30:00.0 AEST"/><endTime type="date" value="…"/></timeRange>` (format `yyyy.MM.dd HH:mm:ss.S z`) | ✅ desktop and web: axis and time control show the range; desktop greys out play, stop and *Update every* (no live update) |
| Performance | `optimised` true (default) = sample interval by zoom (`cfg\configurations\ChartThresholdTables.xml`) | — |
| | `optimised` false + `useSampleInterval` true + `sampleInterval` 60 | ✅ one point per 60 s, last value held to now |
| | `useSampleInterval` false | ✅ all stored samples |
| | `updateFromHistory` false (runtime values) | no visible difference |
| Appearance | `plotAreaTransparent` false + `plotAreaPaint` | ✅ plot colour (paint has no effect while transparent) |
| | `backgroundPaint` | ❌ no visible effect |
| | `hairlineVisible`, `hairlineColor` | ✅ toolbar hairline button on; click in the plot → line + box with time and pen values |
| | `timeSliderVisible`, `valueSliderVisible` false | ✅ sliders removed |
| | `xAxisReversed` / `yAxisReversed` | ✅ newest left **and** time axis moves to the top / 0 at top **and** value axis moves right |
| | `renderMode` `Rendering2d`, `RenderingTable`, `Rendering3dObl`, `Rendering3dOrt`; `RenderingCSS` | ✅ table = sample time, value and status per pen (good to see what the server returns); 3dObl = hatched ribbons; 3dOrt = 3D box with the time axis into depth, lines thick and **black** (pen colours lost); ❌ `RenderingCSS`: display does not load (`renderingType 4 is unsupported`) |
| Time axis | `timeAxisMajorGridColor`, `timeAxisLabelRotation`, `timeAxisTitle` | ✅ (the time-axis title shows, unlike the pen title) |
| | `timeAxisLongLabelVisible` false | ✅ date line under the first label removed |
| | `timeAxisMinorTickVisible`, `timeAxisMinorGridVisible` | nothing at a 10-minute range |
| Header/footer | `headerText`, `footerText` | ✅ top-left above the plot / bottom-left below the time control |
| Legend | `legendPositionType` `PositionNorthEast` (default, right panel), `PositionSouthWest` (= full-height panel on the **left**); also `NorthBottom NorthTop NorthWest SouthBottom SouthTop SouthEast East Absolute` | ✅ |
| | `legendTitle`, `legendColor`, `legendBackgroundColor`, `legendTransparancy` | ✅ |
| Controls | `toolbarVisible` false, `timeRangeControlVisible` false | ✅ toolbar / date and range boxes removed |
| Pen panel | `penPanelVisible`; `penPanelLayout` columns: 0 visible, 1 colour, 2 source, 3 description, 4 units, 5 hairline value, 6 statistics (min \| max \| avg of the shown range), 7 legend, 8 min, 9 max, 10 %, 11 scale range, 12 time offset, 13 appearance, 14 axis, 15 grid (default visible 0–4, 8, 9, 11, 13) | ✅ |

Gaps (CI Server stopped): the desktop joined the last and next sample with a straight line, or
held a scan-group pen flat (seen once); the web drops to 0.

## 5. Component property sheet (Edit Module, connectable)

20 pen slots `[00]`–`[19]`. Inputs (⇦, item → trend): colours, tooltip, visible, transparency,
rotation, zoom. Outputs (⇨): *Hairline value[n]*, *Time range begin/end*, *Update interval*,
*Updating possible*. Both (◇): *Item name[n]*, *Attribute[n]*, *Color[n]*, *Min/Max[n]*,
*Scale type[n]*, *History group[n]*, *Updating*, *Use history*, *Item index/name*,
*Configuration file*. Connections were listed, not tested.

## 6. HTML display (web client)

- **A trend with fewer than 50 visible pens with an item draws no line** in R1.03 (ISS-041):
  the web code always builds 50 data columns (`PEN_COUNT_LIMIT`) but labels only the visible
  pens with an item; console `Mismatch between number of labels (…) and number of columns in
  array (51)`. The desktop is not affected. R1.05: not checked yet (ISS-096); the padding
  workaround is harmless, so keep it until the R1.05 web client is checked.
- **Workaround** (verified 2026-10-02): pad the trend to 50 pens with
  `displays/add_trend_spares.ps1 -Path <display>.xml`. Spares copy the first pen's source,
  are scaled to 1E30–2E30 (clipped), hidden from the legend and get blank unique legend texts
  in the legend background colour
  (the web legend ignores *Show in legend*, ISS-056). Run it again after editing the trend; do
  not keep hidden real pens: one hidden real pen (49 visible) and nothing draws again (checked).
  Cost: 50 history requests per trend. **Desktop side effect**: the hairline box lists every
  visible pen, so it shows 50 values (the user found this unusable); `hairlineVisible` false does
  not help, as the hairline can still be switched on from the trend toolbar. The sample trend
  `CIENG_Trends` therefore keeps its 2 pens and draws no line on the web (2026-10-06).
- Component level (outside `<chartPanel>`): `<opaque>true` with `<backgroundColor>` turned the
  frame around the plot **light** on the desktop instead of dark (2026-10-06, reverted);
  `backgroundPaint` in the chart panel has no effect (ISS-056).
- **Web check of the settings** (2026-10-02, padded scratch copy of `CIENG_TrendLab`, checked in
  the browser; supported-property lists: IM 36K10C50 Table 2.27-28, IM 36K10R30 §4.8.7):

  | Works as on the desktop | Ignored on the web | Different on the web |
  |---|---|---|
  | pen type line / stair-step / scatter, stroke, fill paint, `legendText`, scale range 0/1/2 (item, manual, fit), `axisVisible`, `axisColor`, `labelColor`; last / current time range, `updateInterval`, `autoUpdateInterval` (field hidden), `updating` true/false, fixed sample interval, `timeRangeControlVisible`; `plotAreaTransparent` + `plotAreaPaint`, header, footer, time-axis grid colour, time-axis label rotation, `timeAxisLongLabelVisible`, `legendVisible`, legend text and background colour | pen `labelRotation`, `axisPosition` (axis stays left), `procentual`, major/minor grid, limit lines; `timeAxisTitle`, legend position and title, pen panel, trend toolbar (no way to add pens in the browser), `xAxisReversed`, render mode (always 2D), *Show in legend* (ISS-056) | `timeShift`: data shifted, then message *Illegal start/end time specification*. Hairline: shown on **hover** (not click), box with time, value and status of the nearest pen only. Only **one** value axis is drawn; pens without an axis are plotted as % of their own range against it (misleading). Gaps (CI Server down) drop to 0. |
- **Micro Trend** (`<microTrend>`, up to 4 pens, own SVG drawing, no controls; per-pen
  `<property type="componentProperty"><name>itemName[0]</name><value>…</value></property>`,
  `scaleMin[n]`, `scaleMax[n]`; elements `numberOfPens`, `realTime`, `fillWithHistory`,
  `timeRange` (s, default 300), `sampleCount` (default 300)): drew on desktop and web the first
  time, then stayed blank on several later opens (ISS-055). Cause: *Number of pens* resets all
  pen sources, so fixed item names can be lost during load. **Connect** `microTrend.itemName[n]`
  to the item with attribute `ItemName` instead (`<action type="actionConnectTo">`, `<direction>1`,
  `<itemAttribute>ItemName`; samples `CIENG_Overview`, `CIENG_Trends`): both pens then drew on every open; the
  history fill still failed at times on the web and on the desktop (only the live part drew;
  ISS-055 open). `fillWithHistory` true on an item that is in **no** storage group (e.g.
  `SYSTEM.CPU_LOAD`) gives the message *Record not found* when the display opens, on the desktop
  and on the web (tested 2026-10-06): set it false for such items.

## R1.05: the 50-pen problem is probably fixed (V5, 2026-10-09, from code, not tested)

`PEN_COUNT_LIMIT` is still 50 in the R1.05 web client, but `trend/datasources/DataSource.js`
changed (change e12620, Oct-24, "revert previous change to enable component to function
again"): the checks that skip empty and invisible pens, commented out in the R1.03 file, are
active again. That is the cause of ISS-041, so a trend with fewer than 50 pens should draw on
R1.05. Not tested (no display may be changed on the shared server): keep the padding workaround
until it is checked on a test system (ISS-096).