Create work package relation
create_work_package_relationLink two work packages with a relation type (blocks, follows, duplicates, relates) to record dependencies or scheduling links.
Instructions
Link two work packages (blocks, follows, duplicates, relates, ...).
Use this to record a dependency the schedule or the reader needs to know about: "ship the client layer follows design sign-off", "this duplicates #4321". Returns the created relation with its id, type, reverse_type, both work packages, lag and description.
Pitfalls. OpenProject stores one canonical direction per pair, so the
passive spellings are rewritten on save: creating precedes from A to
B comes back as B follows A, with from_work_package and
to_work_package swapped. That is the same fact, not an error — read
type and reverse_type from the result rather than assuming what
you sent. Only one relation may
exist between two work packages: a second one answers 409 conflict, and
changing it means update_work_package_relation on the existing id. A
relation that would close a scheduling cycle is rejected with a
validation error. Creating a follows relation can move dates, since
OpenProject reschedules the successor.
Cross-references: get_work_package(include=['relations']) lists what
a work package is already linked to and produces relation ids;
update_work_package_relation edits one;
delete_work_package_relation removes it; parent/child hierarchy goes
through update_work_package(parent_id=...).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lag | No | Working days to keep between the two work packages. Valid only on 'follows' and 'precedes'; passing it with any other type is refused here before the request is sent. | |
| type | Yes | How from_id relates to to_id. 'follows' schedules from_id after to_id, 'precedes' before it; 'blocks'/'blocked' express dependency without scheduling; 'duplicates'/'duplicated', 'includes'/'partof', 'requires'/'required' come in mirrored pairs; 'relates' is the neutral link. Parent/child hierarchy is NOT a relation — set it with update_work_package(parent_id=...). | |
| to_id | Yes | The other work package. It must be visible to the account and different from from_id. | |
| from_id | Yes | Work package the relation is read from — 'type' describes what this one does to the other. Ids come from search_work_packages or list_work_packages. | |
| description | No | Optional note explaining why the two work packages are linked. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Relation id. Pass it to update_work_package_relation or delete_work_package_relation — it is not a work package id. | |
| lag | No | Working days kept between the predecessor and the successor. Only follows/precedes relations carry one; null everywhere else. | |
| type | No | Relation type as OpenProject stored it, read from the 'from' work package (e.g. 'follows' means 'from' is scheduled after 'to'). | |
| description | No | Free-text note stored on the relation; null when unset. | |
| reverse_type | No | The same relation read from the 'to' work package: 'follows' <-> 'precedes', 'blocks' <-> 'blocked', 'relates' <-> 'relates'. | |
| to_work_package | No | Work package the relation points to. | |
| from_work_package | No | Work package the relation starts at. |