Preference Templates - edmozley/freeitsm GitHub Wiki

๐Ÿงฉ Preference templates

System โ†’ Preference Templates (3.13.0, discussion #124)

A template is a named set of preferences - timezone, language, the sidebar, module order and the rest - that an administrator gives to people in one go. A team starts from the same setup instead of each person finding every setting alone, and every new analyst can start from it automatically.

Giving someone a template is a one-off copy. Afterwards they can change anything on their own Preferences page, exactly as before.

Making a template

  1. Set up your own Preferences page the way you want the team to start: timezone, language, sidebar, notifications, whatever matters.
  2. Go to System โ†’ Preference Templates and press New.
  3. Give it a name ("Service desk") and, if you like, a description.
  4. Take the settings from - you, by default, or any active analyst whose setup you want to copy.
  5. Tick which settings go in. Anything not ticked is left alone when the template is given to someone, so a template can be as small as "timezone and language".
  6. Save.

The settings are copied as they are at that moment. To change one later, change it on that person's Preferences page and edit the template, taking the settings from them again. Editing a template with Keep what the template has lets you rename it, change its description or untick sections without taking anything new.

A setting the source never chose (still on the built-in default) goes in as "the built-in default". Giving that template to someone puts that setting back to the default for them too - so a template always leaves people set up exactly like its source.

Giving it to people

Press Apply on a template, tick the people (search the list, or All / None), and Apply. You are asked to confirm, because it replaces their own choices for the settings in the template. Settings outside the template are not touched. Each apply is recorded in the system log (preference_template_applied).

New analysts

Tick Give this template to every new analyst on one template. From then on, anyone created - on the Analysts screen, through the REST API, or signing in for the first time through LDAP or single sign-on - starts with it. Only one template can do this; ticking it on one takes it off any other.

What a template can hold

Every section of the Preferences page except the personal ones - My details, Signature and Working hours (each analyst's own calendar feed):

Interface language, Timezone, Date format, Time format, Money, Opening a task, Ticket list, Live updates, Closing the search panel, Subtasks on the task calendar, Subtasks on the task board, Empty work sections on a task, Start page, Watchtower's unowned cards, In the bell, Notification sound, Desktop notifications, Tasks assigned to you, Notification position, Notification animation, Module order, Sidebar (on/off, which modules, how names show, the waffle button), Left panels, Selecting several tickets, Ticket workspace, My company for new tickets, Morning Checks chart.

Empty work sections on a task and My company for new tickets were added in PR #299; before that, a template could not carry them.

Deleting a template changes nobody - what it gave people is theirs.

For developers

  • includes/preference_templates.php - PREF_TEMPLATE_SECTIONS (Preferences page section id => heading key and its user_preferences keys), PREF_TEMPLATE_PERSONAL, prefTemplateCapture(), prefTemplateApply() (one transaction, or joins the caller's), prefTemplatesApplyForNew() (never throws).
  • api/system/preference_templates.php - list / save / delete / apply; system administrators only (admin_api_guard.php).
  • system/preference-templates/index.php - the page; the action row's New opens the form.
  • Table preference_templates: name, description, settings (JSON key => value, null = the built-in default, so applying it deletes the row), for_new_analysts.
  • Nothing that reads a preference changed. Templates only write user_preferences, so the 33 places that read preferences needed no change.
  • TRAP: a new setting on the Preferences page is not in templates until its key is added to PREF_TEMPLATE_SECTIONS (or to PREF_TEMPLATE_PERSONAL). tests/preference-templates.php fails until it is.
  • The four analyst-create paths (api/tickets/save_analyst.php, includes/services/analysts.php, includes/ldap.php, api/auth/oidc_callback.php) each call prefTemplatesApplyForNew(). A fifth create path must too.

See also