How the workflow action Add a note to the ticket (add_ticket_note) writes a real note by System, internal or shared with the requester, while every action saved before the option existed keeps writing to the ticket's history. Built for #268 (5.0.0). User guide: Workflows → Actions (the add_ticket_note row). The engine as a whole: Workflow engine - Developer Guide.

The one-line version: the action gained two args. write_to is a dropdown whose empty value means History only (a Workflow Note row in ticket_audit, as before) and whose note value inserts into ticket_notes with analyst_id NULL, which means System since #281. shared sets is_internal to 0. A new action starts as a note through new_default, which the editor applies only when an action is added or its type is changed. A plain default would have been seeded into every saved action the moment its panel was opened, and flipped it on the next save. The note dispatches no ticket.note_added, so a workflow cannot trigger itself. Before Database Verify the note falls back to the history and the run says so.

🗄️ schema · ⚙️ engine · 🔌 endpoint · 🖥️ UI · 🔗 cross-module · 🧪 tests

Nothing new was added for #268. It relies on two columns that already allow NULL.

-- database/freeitsm.sql
CREATE TABLE IF NOT EXISTS `ticket_notes` (
    `id`                INT NOT NULL AUTO_INCREMENT,
    `ticket_id`         INT NOT NULL,
    `analyst_id`        INT NULL,                        -- NULL = System: no person wrote it (an imported Jira / Azure DevOps comment) (#281)
    `note_text`         LONGTEXT NOT NULL,
    `is_internal`       TINYINT(1) NULL DEFAULT 1,
    `created_datetime`  DATETIME NULL DEFAULT CURRENT_TIMESTAMP,
    `is_demo`           TINYINT(1) NOT NULL DEFAULT 0,   -- set by the demo data importer (#1297)
    PRIMARY KEY (`id`),
    CONSTRAINT `fk_notes_tickets` FOREIGN KEY (`ticket_id`) REFERENCES `tickets` (`id`),
    CONSTRAINT `fk_notes_analysts` FOREIGN KEY (`analyst_id`) REFERENCES `analysts` (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

// includes/db_verify_schema.php
'ticket_notes' => [
    'id'                => 'INT NOT NULL AUTO_INCREMENT',
    'ticket_id'         => 'INT NOT NULL',
    'analyst_id'        => 'INT NULL',   // NULL = System: no person wrote it (#281)
    // …
],

• analyst_id NULL is the only honest value for a note no person wrote. 0 is refused by fk_notes_analysts. That refusal is exactly what broke imported tracker comments in #281.
• is_internal 1 means analysts only. 0 means it also shows on the requester's portal.

-- database/freeitsm.sql
CREATE TABLE IF NOT EXISTS `ticket_audit` (
    `id`                INT NOT NULL AUTO_INCREMENT,
    `ticket_id`         INT NOT NULL,
    -- NULL = nobody did this; the workflow engine did (GH #120). …
    `analyst_id`        INT NULL,
    `field_name`        VARCHAR(100) NOT NULL,
    `old_value`         VARCHAR(500) NULL,
    `new_value`         VARCHAR(500) NULL,
    `created_datetime`  DATETIME NULL DEFAULT CURRENT_TIMESTAMP,
    `is_demo`           TINYINT(1) NOT NULL DEFAULT 0,   -- set by the demo data importer (#1297)
    PRIMARY KEY (`id`),
    CONSTRAINT `fk_ticket_audit_ticket` FOREIGN KEY (`ticket_id`) REFERENCES `tickets` (`id`),
    CONSTRAINT `fk_ticket_audit_analyst` FOREIGN KEY (`analyst_id`) REFERENCES `analysts` (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

A workflow's history row is field_name = 'Workflow Note', analyst_id NULL, old_value NULL and the note in new_value. The same shape is written by includes/services/checklists.php and includes/services/mandatory_fields.php. The history of the action itself: Issue 120 - workflow notes could never be written.

Note the sizes: new_value is VARCHAR(500), note_text is LONGTEXT. See section 10.

// workflow/includes/engine.php - availableActions()
$ticketIdArg = [
    'type'          => 'text',
    'label'         => 'Ticket ID',
    'default'       => '{{ticket.id}}',
    'supports_vars' => true,
    'required'      => true,
];
// …
'add_ticket_note' => [
    'label'       => 'Add a note to the ticket',
    'description' => 'Add a note to the ticket. "A note on the ticket" writes a real note in its Notes, shown as written by System - internal unless you share it with the requester. "History only" writes it to the ticket\'s history instead, as this action always did. It never emails anyone.',
    'args'        => [
        'ticket_id' => $ticketIdArg,
        'note'      => ['type' => 'textarea', 'label' => 'Note', 'required' => true, 'supports_vars' => true],
        // GH #268. The EMPTY value is "History only": a workflow saved before
        // this option existed has no value and must keep doing exactly what it
        // did. new_default (not default) applies only when the action is first
        // added - `default` is also seeded into existing actions when their
        // panel is opened, which would flip a saved workflow on its next save.
        'write_to'  => ['type' => 'select', 'label' => 'Write it as', 'new_default' => 'note', 'options' => [
            ['value' => '',     'label' => 'History only (as before)'],
            ['value' => 'note', 'label' => 'A note on the ticket'],
        ]],
        'shared'    => ['type' => 'bool', 'label' => 'Share the note with the requester (shows on their portal)', 'default' => false],
    ],
],

shared has an ordinary default of false. That is safe: false is what a missing value already means to argBool(), so seeding it into a saved action changes nothing.

// workflow/includes/engine.php
private static function action_add_ticket_note(array $args, array $payload): array
{
    $ticketId = self::argInt($args, 'ticket_id', $payload);
    $note     = self::argString($args, 'note', $payload);
    if (!$ticketId) throw new Exception('ticket_id is required');
    if ($note === '') throw new Exception('note is required');
    $conn = connectToDatabase();
    self::assertRecordInRunCompany($conn, 'tickets', $ticketId, 'ticket');

    // GH #268: a REAL note, in the ticket's Notes, written by System (analyst_id
    // NULL - possible since GH #281). Internal unless shared with the requester.
    //
    // TRAP: no ticket.note_added is dispatched for it. A workflow that adds a note
    // whenever a note is added would otherwise trigger itself until the chain
    // depth stopped it - and nobody needs a bell for a workflow's own note.
    if (($args['write_to'] ?? '') === 'note') {
        $shared = self::argBool($args, 'shared', $payload, false);
        try {
            $conn->prepare(
                "INSERT INTO ticket_notes (ticket_id, analyst_id, note_text, is_internal, created_datetime)
                 VALUES (?, NULL, ?, ?, UTC_TIMESTAMP())"
            )->execute([$ticketId, $note, $shared ? 0 : 1]);
            $noteId = (int)$conn->lastInsertId();
            $conn->prepare("UPDATE tickets SET updated_datetime = UTC_TIMESTAMP() WHERE id = ?")->execute([$ticketId]);
            return ['ticket_id' => $ticketId, 'note_id' => $noteId, 'written_as' => 'note', 'shared' => $shared, 'note_length' => strlen($note)];
        } catch (PDOException $e) {
            // Before Database Verify, a note cannot be written with no author.
            // The note still lands - in the history, as before - and the run says so.
            $fellBack = $e->getMessage();
        }
    }

    // History only: the ticket's audit trail, as this action always wrote it.
    // analyst_id NULL marks it as written by the workflow engine.
    $conn->prepare(
        "INSERT INTO ticket_audit (ticket_id, analyst_id, field_name, old_value, new_value, created_datetime)
         VALUES (?, NULL, 'Workflow Note', NULL, ?, UTC_TIMESTAMP())"
    )->execute([$ticketId, $note]);
    return ['ticket_id' => $ticketId, 'written_as' => 'history', 'note_length' => strlen($note)]
         + (isset($fellBack) ? ['fell_back' => 'Run Database Verify to write real notes: ' . $fellBack] : []);
}

Things to notice:

• write_to is compared exactly to 'note'. It is not rendered as a template and not read through a helper. Anything else, including a missing key, goes to the history. That is the whole compatibility guarantee on the server side.
• The company check comes first. assertRecordInRunCompany() runs before either write, so a company's own workflow can't reach another company's ticket in either mode.
• A real note bumps tickets.updated_datetime, as TicketsService::createNote() does. The History only path does not, as before.
• The step's output can be chained like any action's: {{last.note_id}}, {{steps.2.written_as}}.

shared is read with the engine's checkbox helper, which tolerates the shapes old or hand-edited JSON can carry:

private static function argBool(array $args, string $key, array $payload, bool $default = false): bool
{
    if (!array_key_exists($key, $args)) return $default;
    $raw = $args[$key];
    if (is_bool($raw)) return $raw;
    if ($raw === null || $raw === '') return $default;
    $s = strtolower(trim((string)$raw));
    return !in_array($s, ['0', 'false', 'no', 'off'], true);
}

The service is what the screen uses. It inserts with $ctx->actorId, dispatches ticket.note_added and may email the requester a shared note. A workflow's note must do none of the last two (section 6), and the action promises "It never emails anyone". So the handler writes the row itself and copies only the updated_datetime bump.

Every add_ticket_note saved before 5.0.0 has args {ticket_id, note} and no write_to. It must keep writing to the history, because the people who built it chose that behaviour, and a note suddenly appearing in Notes (or, worse, on the portal) is a change they never asked for. At the same time, a newly added action should be a real note, because that is what people expect "Add a note" to do.

Three pieces make both true:

1. The empty value means History only. A missing write_to and '' read the same: ($args['write_to'] ?? '') === 'note' is false.
2. There is no default on write_to. The test checks this.
3. new_default says what a new action starts as, and only the add and type-change paths read it.

When the editor draws an action's form, it seeds any arg that has a starting value but no saved value into n.args, so the value round-trips through save without anyone touching the field:

// assets/js/workflow-editor.js - drawing an action's arg form
const shownDefault = argDefault(norm, false);
const currentVal = (argName in n.args) ? n.args[argName] : (shownDefault !== undefined ? shownDefault : '');
// …
// Seed n.args with the rendered default so it round-trips
// through save without the user having to touch every field.
if (!(argName in n.args) && shownDefault !== undefined) n.args[argName] = shownDefault;

With 'default' => 'note', opening an old workflow and clicking on its note action would write write_to: 'note' into it. The next save, even one made to change something unrelated, would silently move that workflow from the history to real notes. new_default is invisible to this path, because the form passes isNew = false.

// assets/js/workflow-editor.js
/**
 * An arg's starting value. trigger_defaults (GH #274) win when the workflow's trigger
 * starts with one of their prefixes - a ticket action on a task trigger starts as
 * {{task.ticket_id}}; then new_default, for a NEWLY added action only (GH #268); then default.
 *
 * @param {object} s  the arg's spec
 * @param {boolean} isNew  a new action (or one whose type just changed)
 */
function argDefault(s, isNew) {
    if (!s || typeof s !== 'object') return undefined;
    if (s.trigger_defaults && triggerEvent) {
        for (const pre of Object.keys(s.trigger_defaults)) if (triggerEvent.startsWith(pre)) return s.trigger_defaults[pre];
    }
    if (isNew && s.new_default != null) return s.new_default;
    return s.default != null ? s.default : undefined;
}

The two callers that pass true:

function addAction() {
    const firstType = Object.keys(window.WF_ACTION_DEFS)[0];
    // …
    const def = window.WF_ACTION_DEFS[firstType] || {};
    const defaults = {};
    Object.keys(def.args || {}).forEach(k => {
        // new_default: for a NEWLY added action only (GH #268) - never seeded into
        // a saved one, whose missing value keeps meaning what it always meant.
        const v = argDefault(def.args[k], true);
        if (v !== undefined) defaults[k] = v;
    });
    const lastY = lowestNodeY('action', 'condition', 'trigger');
    const n = addActionNode(COL_X, lastY + ROW_GAP, firstType, defaults);
    renderAll();
    selectNode(n.id);
}

function updateActionTypeFromDetail() {
    const n = nodes.find(x => x.id === selectedNodeId);
    if (!n || n.kind !== 'action') return;
    n.type = document.getElementById('wfActType').value;
    // …
    const def = window.WF_ACTION_DEFS[n.type] || {};
    const next = {};
    Object.keys(def.args || {}).forEach(k => {
        // Changing the action's type makes it a new action: new_default applies (GH #268).
        const v = argDefault(def.args[k], true);
        if (v !== undefined) next[k] = v;
    });
    n.args = next;
    showDetailForAction(n);
    if (n.el) n.el.innerHTML = renderNodeContent(n);
    markDirty();
}

addAction() adds the first action type in the catalogue (log_message), so in practice a person adds an action and then picks Add a note to the ticket from the type dropdown. That second step is updateActionTypeFromDetail(), which is why it must also pass true. Changing type throws away the old args anyway, so it really is a new action.

The select control picks the option whose value equals String(currentVal). A saved action with no write_to has currentVal = '', which matches the History only option, so the screen tells the truth about what the action will do.

Any time an existing action gains an option where new actions should behave differently from saved ones, use the same three pieces: an empty value meaning the old behaviour, new_default for the new behaviour, no default. The engine guide's TRAP says the same.

A note added on screen goes through TicketsService::createNote(), which dispatches the event:

// includes/services/tickets.php - createNote()
try {
    WorkflowEngine::dispatch('ticket.note_added', [
        'ticket'      => self::eventTicket($ticketRow),
        'note_id'     => $noteId,
        'is_internal' => $isInternal,
    ]);
} catch (Exception $wfEx) {
    error_log('Workflow dispatch error in TicketsService createNote: ' . $wfEx->getMessage());
}

action_add_ticket_note() deliberately does not. A workflow on ticket.note_added with an Add a note to the ticket action would otherwise fire itself on its own note. The engine's guards ($activeWorkflowIds, MAX_CHAIN_DEPTH, MAX_RUNS_PER_REQUEST) would stop it and record an aborted run, but two workflows that each note on the other's note would still ping-pong down to the depth limit, writing a note at every step.

What not dispatching also means, because these all hang off that event:

Live updates are not affected. includes/live_pulse.php watches the newest ticket_notes.id and ticket_audit.id directly, so an open ticket catches up either way.

On an install upgraded to 5.0.0 that has not yet run System → Database Verify, ticket_notes.analyst_id may still be NOT NULL. The insert then throws PDOException, and the handler:

1. keeps the message in $fellBack;
2. writes the note to ticket_audit instead, exactly as History only does;
3. returns written_as = 'history' plus fell_back = 'Run Database Verify to write real notes: …'.

The step counts as a success, so the rest of the workflow still runs and the note is not lost. The run's step output in the execution log is where the author sees why it went to the history.

The probe that makes the column nullable came with #281:

// api/system/db_verify.php
try {
    $notesCol = $conn->prepare(
        "SELECT IS_NULLABLE FROM information_schema.columns
         WHERE table_schema = ? AND table_name = 'ticket_notes' AND column_name = 'analyst_id'"
    );
    $notesCol->execute([$dbName]);
    $notesRow = $notesCol->fetch(PDO::FETCH_ASSOC);
    $notesDetails = [];
    if ($notesRow && strtoupper($notesRow['IS_NULLABLE']) === 'NO') {
        $conn->exec("ALTER TABLE `ticket_notes` MODIFY `analyst_id` INT NULL");
        $notesDetails[] = "analyst_id: NOT NULL → NULL (a note no person wrote - an imported Jira comment - is System)";
    }
    if ($notesRow && strtoupper($notesRow['IS_NULLABLE']) === 'YES' || $notesDetails) {
        $zeros = $conn->exec("UPDATE `ticket_notes` SET `analyst_id` = NULL WHERE `analyst_id` = 0");
        if ($zeros) $notesDetails[] = "$zeros note(s) with no author (analyst 0) now marked System";
    }
    // … step 3: drop integration_comment_map rows whose imported note was refused
    if ($notesDetails) {
        $results[] = ['table' => 'ticket_notes', 'status' => 'updated', 'details' => $notesDetails];
    }
} catch (Exception $e) {
    // Non-fatal: notes keep working for people; only imported comments stay refused.
}

The column pass in Database Verify adds missing columns but never loosens existing ones, hence the separate probe. Relaxing NOT NULL invalidates no existing row, so it is safe to re-run. The full story: Issue 281 - imported comments never arrived.

ticket_audit.analyst_id was relaxed the same way for #120, so the fallback itself needs nothing new.

Every reader of ticket_notes already used a LEFT JOIN on analysts and already handled a missing author (#281). #268 changed no reader.

// api/tickets/get_notes.php - after the LEFT JOIN query
if ($note['analyst_name']) {
    $note['author_kind'] = 'analyst';
} elseif ($tracker) {
    $note['author_kind'] = 'tracker';
    $note['analyst_name'] = (string)$tracker['connection_name'];
} elseif ((int)$note['analyst_id'] > 0) {
    $note['author_kind'] = 'former';
} else {
    $note['author_kind'] = 'system';
}

// assets/js/inbox.js - renderNotes()
let author = note.analyst_name;
if (!author) {
    author = note.author_kind === 'system'
        ? t('tickets.note_author.system')
        : t('tickets.note_author.former');
}

tickets.note_author.system is System in English. A workflow note has no tracker map row and a NULL analyst_id, so it lands on system. The note text is drawn through NoteImages.render(), which escapes it, so merge-code values are shown as plain text.

Six templates write a real note. Each sets 'write_to' => 'note' explicitly, because a template's args are copied straight into the new workflow and never go through argDefault():

// workflow/includes/templates.php - sla_breach_alert
'type' => 'add_ticket_note',
'args' => [
    'ticket_id' => '{{ticket.id}}',
    'write_to'  => 'note',   // GH #268: a real note, by System
    'note'      => 'SLA BREACHED: the {{sla.target}} target was missed by {{sla.overdue_minutes}} minutes.',
],

None sets shared, so all six write internal notes.

1. An analyst adds an action in the workflow editor and picks Add a note to the ticket. updateActionTypeFromDetail() seeds ticket_id = {{ticket.id}} (or {{task.ticket_id}} on a task trigger) and write_to = 'note' from new_default. Drawing the form seeds shared = false.
2. Save stores {"type":"add_ticket_note","args":{"ticket_id":"{{ticket.id}}","write_to":"note","shared":false,"note":"…"}} in workflows.actions.
3. The trigger fires. executeActionList() renders the args against the payload and calls action_add_ticket_note().
4. The handler checks the ticket is in the run's company, inserts into ticket_notes with analyst_id NULL and is_internal 1 (or 0 when shared), and bumps tickets.updated_datetime. No event is dispatched.
5. The step returns note_id and written_as = 'note', recorded in workflow_executions.
6. Open screens pick the note up on the next live-updates heartbeat. The Notes list shows it by System. If shared, the requester sees it on the portal by Support.

A workflow saved before 5.0.0 follows the same path, except that write_to is missing at step 4, so it writes the Workflow Note history row instead. A dry run writes nothing in either mode: it records would_args, which shows the write_to the real run would use.

• TRAP: never give write_to a default. The editor seeds default into saved actions when their panel is drawn (section 5). tests/workflow-ticket-note.php fails if one appears.
• TRAP: never dispatch ticket.note_added from the action (section 6). A workflow could then trigger itself, and every watcher would get a bell for automation.
• History only is capped at 500 characters. ticket_audit.new_value is VARCHAR(500). On a MySQL server in strict mode (the MySQL 8 default) a longer rendered note fails the step with Data too long; without strict mode it is cut. A real note (LONGTEXT) has no such limit. The pre-Database-Verify fallback goes to the history too, so it shares the cap.
• shared is ignored for History only. The checkbox has no show_when, so it stays visible when History only is picked, but the handler reads it only inside the note branch.
• Other ways to build an action do not read new_default. The form actions editor (forms/edit/index.php) shows spec.default or the first option, so a new Add a note to the ticket on a form starts as History only. A REST API caller (POST /workflows) gets History only unless it sends "write_to": "note"; GET /workflow-actions lists each arg's default but neither new_default nor a select's options.
• Always $args['write_to'] ?? ''. Reading the key directly would raise a warning on every saved action that predates the option.

The other locales still carry the old "appends a free-text note to the audit trail" wording until they are next translated.

tests/workflow-ticket-note.php, 11 checks. It runs on the throwaway database config.php uses and skips itself unless FREEITSM_TEST_DATABASE names that database:

FREEITSM_TEST_DATABASE=<the throwaway database config.php uses> php tests/workflow-ticket-note.php

It needs Database Verify to have run on that database, so that ticket_notes.analyst_id allows NULL. It runs each action through WorkflowEngine::runActionList() against the newest existing ticket, tags every note ZZ268-<random>, and in finally deletes the notes, history rows and execution rows it made.

$run = function (array $args) use ($tid, &$runs): array {
    $r = WorkflowEngine::runActionList('ZZ268 test', 'ticket.created',
        [['type' => 'add_ticket_note', 'args' => ['ticket_id' => '{{ticket.id}}'] + $args]],
        ['ticket' => ['id' => $tid]]);
    if (!empty($r['execution_id'])) $runs[] = (int)$r['execution_id'];
    return $r;
};

What it does not cover: the pre-Database-Verify fallback (the test database has already been verified), and the editor itself. The editor was checked in a real browser when #268 was built: a new action opened as A note on the ticket, a saved one as History only.

Also run after a change here: workflow-task-actions (its end-to-end example writes a real note), tracker-comment-import (#281), workflow-company-scope, case-report.

• Workflows (user guide) → Actions · Workflow engine - Developer Guide
• Workflows for tasks - Developer Guide (trigger_defaults, the task-done recipe)
• Issue 281 - imported comments never arrived (why analyst_id NULL is System)
• Issue 120 - workflow notes could never be written (the History only row)
• GitHub #268