create_work_item_links
Creates outgoing links from a source work item to specified targets, supporting cross-project links and optional revision pins.
Instructions
Create one or more outgoing links from a single source work item.
All links share the same source (project_id / work_item_id)
and are sent as a single bulk JSON:API request. For each spec
target_project_id defaults to project_id for the common
same-project case; pass it explicitly only for cross-project links.
The orientation matches list_work_item_links(direction="forward")
on the source.
Polarion does not validate link roles server-side: an unknown role
is stored verbatim and never matches subsequent queries. Resolve valid
roles by reading an existing link with
list_work_item_links(direction="forward") on a similar work item
in the same project.
Each spec's revision pins the link to a specific Polarion revision
when set, otherwise the link targets the current HEAD. suspect
marks the link as needing re-review (usually False for new links).
The returned link_ids are five-segment composites
<srcProj>/<srcWI>/<role>/<tgtProj>/<tgtWI> in input order, and
are the path identifiers for future delete/PATCH of the same links
via delete_work_item_links.
Bulk semantics -- partial-failure hazard: behavior on mixed-success
(e.g. one duplicate among otherwise valid links) is not currently
characterised on this server. On any 4xx response, assume nothing was
committed and re-query with
list_work_item_links(direction="forward") before retrying. If you
need per-link diagnostics, send one spec per call.
Phantom-success on same-role conflict: when the source work item is
attached to a document, move_work_item_to_document auto-creates
one outgoing link (role depends on project config -- see that
tool's docstring). Posting a NEW link with the SAME role from the
same source returns 201 and echoes the requested
link_id -- but the new link is NOT persisted. The pre-existing
auto-link remains the only forward link, with its original target.
There is no error to detect this client-side. After every create
on an in-document source, verify the actual stored state with
list_work_item_links(direction="forward") on the source AND
list_work_item_links(direction="back") on the intended target;
if your link is missing, detach via move_work_item_from_document,
create the link, then re-attach with move_work_item_to_document.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Source work item's project ID. | |
| work_item_id | Yes | Source work item ID (the links' outgoing endpoint). | |
| links | Yes | One or more links to create under the source work item. | |
| 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. | |
| link_ids | No | Composite 5-segment link ids in input order; empty on dry-run. | |
| payload_preview | No | JSON:API payload sent or previewed; None after real ops. |