update_work_item
Update a Polarion work item by patching fields such as title, status, priority, and custom fields, or trigger workflow transitions. Replaces assignees and hyperlinks entirely.
Instructions
Update an existing Polarion work item.
PATCHes the supplied fields and follows up with a GET so the caller
can confirm the change in current. None / empty string /
empty list all mean leave unchanged — this tool exposes no path
to clear a field.
description_html is RAW Polarion HTML, sent verbatim with no
sanitization, so XSS/script filtering is delegated to Polarion's
renderer — NEVER pass untrusted input. Pair with
get_work_item(include_description_html=True) for the round-trip.
For greenfield authoring use create_work_item(description=...)
(Markdown) — the two format paths never mix.
hyperlinks and assignee_ids REPLACE the existing lists (pass
the full list, not a delta). custom_fields is partial — omitted
keys are preserved. Unknown custom-field IDs silently persist as
ghost attributes; pass keys from a prior read to avoid creating them.
The module relationship is NOT exposed here: Polarion rejects
PATCHes that attempt to modify it. To attach, detach, or move a
work item between documents, use move_work_item_to_document /
move_work_item_from_document.
Prefer workflow_action over a raw status edit so the project's
transition rules run. workflow_action and change_type_to MUST
be paired with at least one body field — Polarion rejects empty PATCH
bodies (HTTP 400 "At least one of the members is required"). Direct
status / severity / resolution writes are NOT validated
server-side: unknown ids are stored verbatim as ghost values.
priority only coerces non-numeric inputs to the project default;
numeric strings outside the enum set also persist verbatim. Resolve
valid ids first via list_work_item_enum_options(project_id,
field_id, work_item_type).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Polarion project ID. | |
| work_item_id | Yes | Short ID of an EXISTING work item (e.g. 'MCPT-042'). | |
| title | No | New title (None to leave unchanged). | |
| description_html | No | New raw Polarion HTML body (round-trip shape from get_work_item); '' is a no-op. | |
| status | No | New workflow status; prefer ``workflow_action`` for real transitions. | |
| priority | No | New priority string (e.g. '50.0'). | |
| severity | No | New severity classification. | |
| due_date | No | New due date 'YYYY-MM-DD'. | |
| initial_estimate | No | New Polarion duration (e.g. '5 1/2d', '1w 2d'). | |
| resolution | No | New resolution outcome; prefer ``workflow_action`` so workflow rules apply. | |
| hyperlinks | No | REPLACES the hyperlink list — pass the full list, not a delta. | |
| assignee_ids | No | REPLACES the assignee list — pass the full list, not a delta. | |
| custom_fields | No | Partial custom-field update; rich-text values must be ``{'type':'text/html','value':...}``. | |
| workflow_action | No | Workflow action ID (e.g. 'close'); must be paired with at least one body field. | |
| change_type_to | No | Change work-item type; RESETS status; must be paired with at least one body field. | |
| include_current_description_html | No | When True, return the post-PATCH raw HTML body in ``current.description_html``. | |
| dry_run | No | When True, return payload preview without calling Polarion. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| updated | Yes | True on a real update; False on dry-run. | |
| dry_run | Yes | Whether this was a dry-run. | |
| current | Yes | Post-PATCH state for verification; None on dry-run. | |
| changes | Yes | Map of field names to their new values in the PATCH. | |
| payload_preview | Yes | JSON:API payload sent or previewed; None after real ops. |