Execute custom action
execute_custom_actionTrigger an admin-defined one-click action on a work package, applying several field changes simultaneously to speed up repetitive workflows.
Instructions
Run an instance-defined one-click action on a work package.
Custom actions are shortcuts an administrator configured — "Accept and
assign to me", "Reject", "Move to review" — that apply several field
changes at once, sometimes under conditions (role, status, project).
Use one when get_work_package(include=['custom_actions']) offers it,
instead of reproducing its effects field by field. Returns the updated
work package row (subject, type, status, priority, assignee, project,
dates, percentage_done, updated_at).
Pitfalls. The action decides what changes; this tool cannot influence it,
and OpenProject does not report which fields it touched — compare the
returned row with what you read before, or call get_work_package
again for the full detail (including the new lock_version for your
next update). Availability is per work package: an action listed on one
ticket may 403 on another because its conditions no longer hold, and a
422 usually means the resulting work package would be invalid (a
required field the action leaves empty). Writes are never retried
automatically — a conflict comes back with the fresh lock_version so
you can re-read and decide.
Cross-references: get_work_package(include=['custom_actions'])
produces the ids and says which are available right now;
update_work_package is the explicit alternative when you know exactly
which fields to set; list_work_package_comments shows what the action
recorded in the journal.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lock_version | No | The work package's current lockVersion, from get_work_package. Omit it and the current value is read first — safe, one extra request. A stale value returns a conflict carrying the fresh one. | |
| work_package_id | Yes | Work package to run the action on. It must be the one the action was listed for; conditions are re-checked server-side. | |
| custom_action_id | Yes | Id of the custom action to run. Get it from get_work_package(id=..., include=['custom_actions']), which lists the actions this instance defines AND this work package currently qualifies for — the names are instance-specific, so never guess an id. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Work package id. | |
| type | No | Work package type. | |
| status | No | Status. | |
| project | No | Owning project. | |
| subject | No | Subject line. | |
| assignee | No | Assigned user or group. | |
| due_date | No | ISO date (YYYY-MM-DD). | |
| priority | No | Priority. | |
| display_id | No | Human-facing id as the instance renders it. Matches the numeric id unless the instance uses semantic identifiers (17.x, e.g. 'PROJ-42'); null when the instance predates it. | |
| start_date | No | ISO date (YYYY-MM-DD). | |
| updated_at | No | ISO 8601 UTC timestamp. | |
| percentage_done | No | Progress, 0-100. |