create_document
Create a Polarion document in a space using project ID, space ID, module name, title, and type. Optionally add home page content, custom fields, or status.
Instructions
Create a new Polarion document in a space.
Greenfield document creation. The document starts empty (or with the
optional home_page_content body) and headings / work item parts
can be added later via update_document and
move_work_item_to_document.
Format asymmetry: home_page_content here is Markdown (converted
to sanitized HTML on write) because greenfield authoring is natural
for LLMs. After creation the round-trip pair is
get_document(include_homepage_content_html=True) ↔
update_document(home_page_content_html=...) which speaks raw HTML
verbatim. The two formats never mix.
When home_page_content is provided, every block-level element of
the rendered HTML (<p>, <ul>, <ol>, <table>, <div>,
<blockquote>, <pre>) is stamped with a unique
id="polarion_mcp_N" anchor. Without these ids the document saves
but the next read_document_parts returns HTTP 500. Headings
<h1>..<h4> are intentionally skipped — Polarion rewrites their
ids into a polarion_wiki macro name=module-workitem macro form on
save.
module_name is Polarion's persistent identifier within the space
and is used in every subsequent URL (get_document,
update_document, etc.). It must be unique within space_id;
a duplicate name causes Polarion to return HTTP 409, surfaced here
as RuntimeError.
Polarion does NOT validate enum membership server-side. Unknown
type / status ids are stored verbatim as ghost values that
look real on later reads but never match Lucene queries. Resolve
valid ids first via list_document_enum_options(project_id,
field_id, document_type). custom_fields is the same story:
unknown field IDs silently persist as ghost attributes -- pass keys
taken 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). | |
| module_name | Yes | Polarion document identifier (e.g. 'MySpecV1'); must be unique within ``space_id`` and appears in the document URL. | |
| title | Yes | Human-readable document title (required, non-empty). | |
| type | Yes | Document type (e.g. 'req_specification', 'generic'). | |
| status | No | Optional initial workflow status (project default applies if omitted). | |
| home_page_content | No | Optional Markdown body; converted to sanitized HTML on write. | |
| custom_fields | No | Optional custom fields keyed by Polarion field ID; rich-text values must be ``{'type':'text/html','value':...}``. | |
| dry_run | No | When True, return payload preview without calling Polarion. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| created | Yes | True on a real create; False on dry-run. | |
| dry_run | Yes | Whether this was a dry-run. | |
| document_name | Yes | Module name of the new document; None on dry-run. | |
| payload_preview | Yes | JSON:API payload sent or previewed; None after real ops. |