Save a query
save_querySave a filter combination as a reusable OpenProject view, so you can re-run it later instead of rebuilding it each session.
Instructions
Save a filter set as a reusable OpenProject view.
Use it to keep a filter combination — "Overdue in Platform", "My open bugs" — instead
of rebuilding it each session: the view shows up in the OpenProject UI too, and
run_query reproduces it exactly. Prove filters with list_work_packages first.
Validated via POST /queries/form first, so an invalid filter name, unsupported
operator, or project-scoped filter on a global view comes back as violations naming
the attribute — nothing is saved. Returns the stored definition: {id, name, project, public, starred, filters (as readable sentences), group_by, sort_by, display_sums, updated_at, notes}. Keep the id — run_query takes it.
Pitfalls. If OpenProject keeps fewer filters than were sent, notes says so — read
filters rather than assuming a match. Custom-field filters (customField12) are sent
as plain values, since a list-typed one can't be told apart from a text one without
asking the instance; a failing one means nothing was saved — save that view in the UI
instead. Editing and deleting saved views isn't offered here: use the OpenProject UI.
Cross-references: list_queries lists what exists (with ids); run_query(query_id=...)
runs this view; list_work_packages validates filters first; list_projects supplies
project_id.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name the view is saved under, e.g. 'Overdue in Platform'. Not unique upstream — a repeat name creates a second view. | |
| star | No | Also star (favorite) the view, so it appears in the sidebar. A second call after the query exists; a failure still leaves it saved (noted in 'notes') — don't re-save. | |
| public | No | true shares the view with everyone who can see the project; false (default) keeps it private. Sharing usually needs 'manage public queries'. | |
| filters | Yes | The filters to store, same shape as run_query's override_filters / list_work_packages' raw_filters, e.g. [{'name': 'status', 'operator': 'o', 'values': []}, {'name': 'assignee', 'operator': '=', 'values': ['12']}]. Values are ids (or 'me'), not names. Pass [] for a view with no filters — unlike a listing, it then shows every status. | |
| sort_by | No | Stored sort order, e.g. [['due_date', 'asc'], ['id', 'desc']]. Unknown keys are rejected locally, listing the allowed set. Omit for the default. | |
| group_by | No | Column to group results by, e.g. 'status', 'assignee'. Makes run_query return 'groups' with per-group counts. Omit for a flat list. | |
| project_id | No | Numeric project id the view belongs to; from list_projects. Omit for a global view — project-scoped filters (version, category, subprojectId) are then rejected. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Query id — pass it to run_query as query_id. | |
| name | No | Query name as its author saved it. | |
| notes | No | What happened beyond the create itself: a failed star, filters OpenProject did not keep. Empty when everything landed as asked. | |
| public | No | True when shared with everyone who can see the project; false when private to its owner. | |
| filters | No | The stored filters as readable sentences, e.g. 'Status open' or 'Assignee is (OR) Grace Hopper'. Empty when the query filters nothing. | |
| project | No | Owning project, or null for a global (cross-project) query. | |
| sort_by | No | Stored sort order, e.g. ['Finish date asc']. | |
| starred | No | True when the current user starred (favorited) it. | |
| group_by | No | Column the results are grouped by, when the query groups. | |
| updated_at | No | ISO 8601 UTC timestamp. | |
| display_sums | No | True when the query asks for totals; then the result 'sums' is populated. |