Skip to content

API Script Library Design

Ed Mozley edited this page Nov 19, 2026 · 1 revision

πŸ“ API script library - design

Asked for by Ed, 19 November 2026, after trying the Knowledge migration demo: "put this demo script somewhere within System -> API then have a button ... called Scripts which would be a library of scripts that you could search by language, description, module ... heavily commented so people learn from them." For 5.7.0 if ready, else 5.8.0.

What it is

A Scripts tab under System β†’ API: a searchable library of ready-made scripts that use the REST API to do real jobs - export open tickets, turn monitoring alerts into tickets, sync people from HR, migrate a knowledge base. Every script comes in PowerShell and Python, is heavily commented so it teaches as it works, and can be copied or downloaded.

Decided

Question Decision Why
Where the scripts live Files shipped with FreeITSM (script-library/), not the database (Ed, 19 Nov 2026) People run these on their own machines with admin keys. In the database, anyone who could write to it - a stolen admin login, an injection bug - could add one line that sends the key elsewhere, to everybody who copies the script afterwards. As files they have the same trust as the code: reviewed in git, updated with each release, unchangeable from inside FreeITSM
Languages PowerShell and Python, every script in both (Ed, 19 Nov 2026) What an IT team actually uses. Python 3.13 installed on the dev laptop so both are tested
Python dependencies Standard library only - urllib, json, csv, argparse Runs anywhere Python runs, including locked-down servers where pip install is not allowed
Who can see it Whoever can open System β†’ API It sits beside the keys it needs
Running them Never on the server. Shown as text, copied or downloaded A library page is not a remote shell
Quality Every script run against a test install before it ships, and a CI check An example that calls an endpoint slightly wrong is worse than none, because people trust it

The rules every script follows

  1. A header of # @tag value lines (the same in both languages, so one parser reads both): @title, @summary, @module, @changes (no / yes), @level (starter / intermediate / advanced), @endpoints, @permissions.
  2. The key is never in the script. It is read from a file (default api-key.txt beside the script) or the FREEITSM_API_KEY environment variable.
  3. A script that changes data previews by default. It prints what it would do; nothing is written until you add -Apply (PowerShell) or --apply (Python).
  4. It stops on the first error and says which call failed and why.
  5. Heavy comments: what each block does and why, the API behaviour it relies on, and what to change for your own install.
  6. Only the endpoints in its header. The CI check fails the build if a script calls an endpoint not in its @endpoints, or lists an endpoint or permission that does not exist.

The screen

  • Left: a search box (title, summary, endpoint, module) and filters - language, module, "changes data" / "read only", level - then the list.
  • Right: the chosen script: title, summary, a PowerShell / Python switch, the endpoints and the exact key permissions it needs, then the script itself (comments picked out in a muted colour), with Copy and Download.
  • Deep link: system/api/?tab=scripts&script=<slug>.

Safety of the page itself

  • Files are read only from script-library/powershell/*.ps1 and script-library/python/*.py; a requested name must match ^[a-z0-9-]+$ and an existing file - no path from the request is ever joined to the folder.
  • Text is shown escaped (textContent); downloads are text/plain attachments with nosniff.
  • script-library/ is denied to direct web requests on Apache (.htaccess), IIS (web.config) and nginx, and probed by debug tool D009 - on some hosts a .py file in a web folder could otherwise be run as a CGI program.

The first scripts

Script Module Changes data What it shows
Check your API key (any) no /ping: what the key can do
Export open tickets to CSV Tickets no Paging through results
Turn a monitoring alert into a ticket Tickets yes Look first, then create or add a note - no duplicates
Close stale tickets with a note Tickets yes Filtering, notes, then a status change
Weekly SLA breach report Tickets no One call per ticket, then a summary
Time logged per analyst this month Tickets no Combining two endpoints
Sync people from an HR spreadsheet People yes Create-or-update ("upsert") by email
Import assets from a CSV Assets yes Upsert by asset tag
Warranty expiry report Assets no Date logic on the client
Leaver checklist People + Assets + Tasks yes Several modules, one job
Upcoming changes as a calendar file Changes no Writing an .ics file
Link matching tickets to a problem Problems yes Search, then act on the results
Knowledge migration Knowledge yes Folders, drafts, pictures, retries
Knowledge articles due for review Knowledge no Grouping by owner
Back up the knowledge base to HTML Knowledge no One file per article
Declare a service incident Service status yes Creating and updating an incident
Record morning check results Morning checks yes Run local checks, post the results
Contracts expiring soon Contracts no A report to paste into an email
Software licence compliance Software no Licences vs installations
Impact before a change CMDB no Following relationships
Bank holidays into the calendar Calendar yes Reading another web service, then FreeITSM
New starter tasks Tasks yes A checklist of tasks from one call each

More are added the same way: two files, a header, a test run, and the CI check.

Related: REST API Β· REST API: Knowledge

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally