Create work package relation
create_work_package_relationLink two work packages with a relation type (follows, blocks, duplicates) to record dependencies. Returns the created relation with its id, type, and work package details.
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. |