update_document
Update a Polarion document's metadata or body by patching only the specified attributes, preserving unchanged fields. Use workflow actions for status transitions to enforce project rules.
Instructions
Update a Polarion document's metadata or body.
PATCHes only the attributes you set; omitted fields are preserved
server-side. Unlike update_work_item this does NOT follow up
with a GET — call get_document if you need the refreshed state.
home_page_content_html is the round-trip pair for
get_document(include_homepage_content_html=True). The HTML is
sent verbatim with no sanitization, so XSS/script filtering is
delegated to Polarion's renderer — NEVER pass untrusted input.
Empty string is rejected (would wipe the body and orphan every
heading); pass '<p></p>' for a near-empty body.
Body-write behaviour:
Heading auto-create: inline
<h1>..<h4>tags become heading work items withmoduleandoutline_numberset automatically. A bare<hN>Title</hN>alone is safe.Orphan headings: removing an
<hN>removes the part but leaves the heading work item behind (stillmodule-linked, nooutline_number).DO NOT inject anchorless
<p>paragraphs: ``XDO NOT inject work item macro references: appending
<div id="polarion_wiki macro name=module-workitem;params=id=NEW">creates aworkitem_<NEW>part visible inread_document_partsbut leaves the work item'smodulerelationship unset (space_id="",outline_number="") — an inconsistent half-attached state. Always attach viamove_work_item_to_document.
Workflow: prefer workflow_action over a raw status edit so
project rules run. workflow_action MUST be paired with at least
one attribute field — Polarion rejects empty PATCH bodies. Direct
status / type writes are NOT validated server-side: unknown
ids are stored verbatim as ghost values. Resolve valid ids first via
list_document_enum_options(project_id, field_id, document_type).
Unknown custom_fields IDs also become ghost attributes; pass
keys from a prior get_document.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Polarion project ID. | |
| space_id | Yes | Space ID (use '_default' for the default space). | |
| document_name | Yes | Document name within ``space_id``. | |
| title | No | New title (None to leave unchanged). | |
| status | No | New workflow status; prefer ``workflow_action`` for real transitions. | |
| type | No | New document type (e.g. 'req_specification'). | |
| home_page_content_html | No | New body as raw Polarion HTML (round-trip shape from get_document); '' is rejected. | |
| custom_fields | No | Partial custom-field update; rich-text values must be ``{'type':'text/html','value':...}``. | |
| workflow_action | No | Workflow action ID; must be paired with at least one attribute field. | |
| dry_run | No | When True, return payload preview without calling Polarion. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| updated | Yes | True on a real PATCH; False on dry-run. | |
| dry_run | Yes | Whether this was a dry-run. | |
| payload_preview | Yes | JSON:API payload sent or previewed; None after real ops. |