The on-change subsection of a fields section specifies one
or more actions to be performed when the field value is edited by the
user. It has the general form
on-change [ "query-expression" ] {
[ add-audit-trail ]
[ audit-trail-format {
format "formatstring"
[ fields { "fieldname" ... } ]
} ]
[ require-change-reason ]
[ set-field | append-to-field "fieldname" {
"format-string" [ fieldlist ]
} ]
[ require { "fieldname" ... } ]
}
The optional query-expression controls whether or not the actions
in the on-change section are taken. If the expression fails to
match, the actions are skipped.
The add-audit-trail option indicates that an entry should be
appended to the PR's audit-trail when this field is changed. The format
of the entry is controlled by the optional audit-trail-format
section within the field, or by the global audit-trail-format
section. See Audit-trail formats and Outgoing email formats.
The require-change-reason option specifies that a change reason
must be present in the PR when this field is edited. This option only
makes sense if an audit-trail entry is required, as the change reason is
otherwise unused.
The set-field and append-to-field options are used to
change the value of the field fieldname in the PR. The supplied
format is used to format the value that will be placed in the field.
append-to-field appends the resulting formatted string to the
existing, while set-field completely replaces the contents.
Any field may be edited by the set-field or
append-to-field option (the read-only option on a field is
ignored). However, the changes are subject to the usual field content
checks.
The require option specifies that one or more fields must have
a (non-blank) value when this field is changed.
A field may be enforced to have a (non-blank) value at all times by including it in the set of fields required for the initial PR, see Initial PR input fields, as well as in the set of fields required on change of the field itself.
There is also a global on-change section that is executed once
for each PR edit. A typical use for such a section is to set the
last-modified date of the PR.