kanbanworkflowstimelinescrumrubyroadmapproject-planningproject-managementopenprojectangularissue-trackerifcgantt-chartganttbug-trackerboardsbcf
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
2230 lines
90 KiB
2230 lines
90 KiB
# Group Projects
|
|
|
|
Projects are containers structuring the information (e.g. work packages, wikis) into smaller groups. They can be used in a classic project management approach but also when structuring work by departments.
|
|
|
|
As containers, they also control behaviour of the elements within them. One of the most important aspects of this is that projects limit permissions by having members with a certain permission set (roles) assigned to them.
|
|
|
|
## Actions
|
|
|
|
| Link | Description | Condition |
|
|
|:--------------------------: |----------------------------------------------------------------------| --------------------------------- |
|
|
| update | Form endpoint that aids in updating this projet | **Permission**: edit project |
|
|
| updateImmediately | Directly update this project | **Permission**: edit project |
|
|
| delete | Delete this project | **Permission**: admin |
|
|
| createWorkPackage | Form endpoint that aids in preparing and creating a work package | **Permission**: add work packages |
|
|
| createWorkPackageImmediately | Directly creates a work package in the project | **Permission**: add work packages |
|
|
|
|
## Linked Properties
|
|
|
|
| Link | Description | Type | Constraints | Supported operations |Condition |
|
|
| :----------: | ------------- | ---- | ----------- | -------------------- |----------------------------------------- |
|
|
| self | This project | Project | not null | READ | |
|
|
| categories | Categories available in this project | Collection | not null | READ | |
|
|
| types | Types available in this project | Collection | not null | READ | **Permission**: view work packages or manage types |
|
|
| versions | Versions available in this project | Collection | not null | READ | **Permission**: view work packages or manage versions |
|
|
| memberships | Memberships in the project | Collection | not null | READ | **Permission**: view members |
|
|
| workPackages | Work Packages of this project | Collection | not null | READ | |
|
|
| parent | Parent project of the project | Project | | READ/WRITE | **Permission** edit project |
|
|
| status | Denotes the status of the project, so whether the project is on track, at risk or is having trouble. | ProjectStatus | | READ/WRITE | **Permission** edit project |
|
|
|
|
Depending on custom fields defined for projects, additional links might exist.
|
|
|
|
## Local Properties
|
|
|
|
| Property | Description | Type | Constraints | Supported operations |
|
|
| :---------------------:| ------------- | ---- | ----------- | -------------------- |
|
|
| id | Projects' id | Integer | x > 0 | READ/WRITE |
|
|
| identifier | | String | | READ/WRITE |
|
|
| name | | String | | READ/WRITE |
|
|
| active | Indicates whether the project is currently active or already archived | Boolean | | READ/WRITE |
|
|
| statusExplanation | A text detailing and explaining why the project has the reported status | Formattable | | READ/WRITE |
|
|
| public | Indicates whether the project is accessible for everybody | Boolean | | READ/WRITE |
|
|
| description | | Formattable | | READ/WRITE |
|
|
| createdAt | Time of creation | DateTime | | READ |
|
|
| updatedAt | Time of the most recent change to the project | DateTime | | READ |
|
|
|
|
Depending on custom fields defined for projects, additional properties might exist.
|
|
|
|
## View project [/api/v3/projects/{id}]
|
|
|
|
+ Model
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Project",
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/projects/1",
|
|
"title": "Lorem"
|
|
},
|
|
"createWorkPackage": {
|
|
"href": "/api/v3/projects/1/work_packages/form",
|
|
"method": "post"
|
|
},
|
|
"createWorkPackageImmediate": {
|
|
"href": "/api/v3/projects/1/work_packages",
|
|
"method": "post"
|
|
},
|
|
"categories": {
|
|
"href": "/api/v3/projects/1/categories"
|
|
},
|
|
"types": {
|
|
"href": "/api/v3/projects/1/types"
|
|
},
|
|
"versions": {
|
|
"href": "/api/v3/projects/1/versions"
|
|
},
|
|
"workPackages": {
|
|
"href": "/api/v3/projects/1/work_packages"
|
|
}
|
|
"memberships": {
|
|
"href": "/api/v3/memberships?filters=[{"project":{"operator":"=","values":["1"]}}]
|
|
},
|
|
"customField456": {
|
|
"href": "/api/v3/users/315",
|
|
"method": "A user"
|
|
},
|
|
"projects": {
|
|
"href": "/api/v3/projects/123"
|
|
},
|
|
"status": {
|
|
"href": "/api/v3/project_statuses/on_track",
|
|
"title": "On track"
|
|
}
|
|
},
|
|
"id": 1,
|
|
"identifier": "project_identifier",
|
|
"name": "Project example",
|
|
"active": true,
|
|
"public": false,
|
|
"statusExplanation": {
|
|
"format": "markdown",
|
|
"raw": "Everything **fine**",
|
|
"html": "<p>Everything <strong>fine</strong></p>"
|
|
},
|
|
"description": {
|
|
"format": "markdown",
|
|
"raw": "Lorem **ipsum** dolor sit amet",
|
|
"html": "<p>Lorem <strong>ipsum</strong> dolor sit amet</p>"
|
|
},
|
|
"createdAt": "2014-05-21T08:51:20Z",
|
|
"updatedAt": "2014-05-21T08:51:20Z",
|
|
"customField123": 123
|
|
}
|
|
|
|
## View project [GET]
|
|
|
|
+ Parameters
|
|
|
|
+ id (required, integer, `1`) ... Project id
|
|
|
|
+ Response 200 (application/hal+json)
|
|
|
|
[View project][]
|
|
|
|
+ Response 404 (application/hal+json)
|
|
|
|
Returned if the project does not exist or the client does not have sufficient permissions
|
|
to see it.
|
|
|
|
**Required permission:** view project
|
|
|
|
*Note: A client without sufficient permissions shall not be able to test for the existence of a project.
|
|
That's why a 404 is returned here, even if a 403 might be more appropriate.*
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
|
|
"message": "The requested resource could not be found."
|
|
}
|
|
|
|
## Create project [/api/v3/projects]
|
|
|
|
## Create project [POST]
|
|
|
|
Creates a new project, applying the attributes provided in the body.
|
|
|
|
You can use the form and schema to be retrieve the valid attribute values and by that be guided towards successful creation.
|
|
|
|
+ Request Create project
|
|
|
|
+ Body
|
|
|
|
{
|
|
"identifier": "new_project_identifier",
|
|
"name": "New project name",
|
|
"customField35": "Text custom field value",
|
|
"statusExplanation": {
|
|
"format": "markdown",
|
|
"raw": "Everything **fine**",
|
|
"html": "<p>Everything <strong>fine</strong></p>"
|
|
},
|
|
"_links": {
|
|
"customField12": {
|
|
"href": "/api/v3/users/5"
|
|
},
|
|
"parent": {
|
|
"href": "/api/v3/projects/6"
|
|
},
|
|
"status": {
|
|
"href": "/api/v3/project_statuses/on_track"
|
|
}
|
|
}
|
|
}
|
|
|
|
+ Response 201
|
|
|
|
[View project][]
|
|
|
|
+ Response 400 (application/hal+json)
|
|
|
|
Occurs when the client did not send a valid JSON object in the request body.
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
|
|
"message": "The request body was not a single JSON object."
|
|
}
|
|
|
|
+ Response 403 (application/hal+json)
|
|
|
|
Returned if the client does not have sufficient permissions.
|
|
|
|
**Required permission:** add project which is a global permission
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
|
|
"message": "You are not authorized to access this resource."
|
|
}
|
|
|
|
+ Response 422 (application/hal+json)
|
|
|
|
Returned if:
|
|
|
|
* a constraint for a property was violated (`PropertyConstraintViolation`)
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
|
|
"message": "Name can't be blank.",
|
|
"_embedded": {
|
|
"details": {
|
|
"attribute": "name"
|
|
}
|
|
}
|
|
}
|
|
|
|
## Update project [/api/v3/projects/{id}]
|
|
|
|
## Update Project [PATCH]
|
|
|
|
Updates the given project by applying the attributes provided in the body.
|
|
|
|
+ Parameters
|
|
|
|
+ id (required, integer, `1`) ... Project id
|
|
|
|
+ Request Update project
|
|
|
|
+ Body
|
|
|
|
{
|
|
"name": "A new project name",
|
|
"_links": {
|
|
"customField35": {
|
|
"href": "/api/v3/users/3"
|
|
},
|
|
"status": {
|
|
"href": "/api/v3/project_statuses/at_risk",
|
|
}
|
|
}
|
|
}
|
|
|
|
+ Response 200
|
|
|
|
[View project][]
|
|
|
|
+ Response 400 (application/hal+json)
|
|
|
|
Occurs when the client did not send a valid JSON object in the request body.
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
|
|
"message": "The request body was not a single JSON object."
|
|
}
|
|
|
|
+ Response 403 (application/hal+json)
|
|
|
|
Returned if the client does not have sufficient permissions.
|
|
|
|
**Required permission:** edit project for the project to be altered
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
|
|
"message": "You are not authorized to access this resource."
|
|
}
|
|
|
|
+ Response 404 (application/hal+json)
|
|
|
|
Returned if the project does not exist or the client does not have sufficient permissions
|
|
to see it.
|
|
|
|
**Required permission:** view project
|
|
|
|
*Note: A client without sufficient permissions shall not be able to test for the existence of
|
|
a version. That's why a 404 is returned here, even if a 403 might be more appropriate.*
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
|
|
"message": "The requested resource could not be found."
|
|
}
|
|
|
|
+ Response 422 (application/hal+json)
|
|
|
|
Returned if:
|
|
|
|
* a constraint for a property was violated (`PropertyConstraintViolation`)
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
|
|
"message": "Name can't be blank.",
|
|
"_embedded": {
|
|
"details": {
|
|
"attribute": "name"
|
|
}
|
|
}
|
|
}
|
|
|
|
## Delete project [/api/v3/projects/{id}]
|
|
|
|
## Delete Project [DELETE]
|
|
|
|
Deletes the project permanently. As this is a lengthy process, the actual deletion is carried out asynchronously.
|
|
So the project might exist well after the request has returned successfully. To prevent unwanted changes to
|
|
the project scheduled for deletion, it is archived at once.
|
|
|
|
+ Parameters
|
|
|
|
+ id (required, integer, `1`) ... Project id
|
|
|
|
+ Response 204 (application/hal+json)
|
|
|
|
Returned if the project was successfully deleted. There is currently no end point to query for the actual deletion status.
|
|
Such an end point _might_ be added in the future.
|
|
|
|
+ Body
|
|
|
|
+ Response 403 (application/hal+json)
|
|
|
|
Returned if the client does not have sufficient permissions.
|
|
|
|
**Required permission:** admin
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
|
|
"message": "You are not authorized to access this resource."
|
|
}
|
|
|
|
+ Response 404 (application/hal+json)
|
|
|
|
Returned if the project does not exist or the client does not have sufficient permissions
|
|
to see it.
|
|
|
|
**Required permission:** view project
|
|
|
|
*Note: A client without sufficient permissions shall not be able to test for the existence of
|
|
a version. That's why a 404 is returned here, even if a 403 might be more appropriate.*
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
|
|
"message": "The requested resource could not be found."
|
|
}
|
|
|
|
+ Response 422 (application/hal+json)
|
|
|
|
Returned if the project cannot be deleted. This can happen when there are still references to the project in other projects
|
|
that need to be severed at first.
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
|
|
"message": "Work packages in non descendant projects reference versions of the project or its descendants.",
|
|
"_embedded": { "details": { "attribute": "base" } }
|
|
}
|
|
|
|
## List projects [/api/v3/projects{?filters,sortBy}]
|
|
|
|
+ Model
|
|
+ Body
|
|
|
|
{
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/projects"
|
|
}
|
|
},
|
|
"_type": "Collection",
|
|
"total": 2,
|
|
"count": 2,
|
|
"_embedded": {
|
|
"elements": [
|
|
{
|
|
"_type": "Project",
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/projects/6",
|
|
"title": "A project"
|
|
},
|
|
"createWorkPackage": {
|
|
"href": "/api/v3/projects/6/work_packages/form",
|
|
"method": "post"
|
|
},
|
|
"createWorkPackageImmediate": {
|
|
"href": "/api/v3/projects/6/work_packages",
|
|
"method": "post"
|
|
},
|
|
"categories": {
|
|
"href": "/api/v3/projects/6/categories"
|
|
},
|
|
"versions": {
|
|
"href": "/api/v3/projects/6/versions"
|
|
},
|
|
"projects": {
|
|
"href": "/api/v3/projects/123"
|
|
},
|
|
"status": {
|
|
"href": "/api/v3/project_statuses/on_track",
|
|
"title": "On track"
|
|
}
|
|
},
|
|
"id": 6,
|
|
"identifier": "a_project",
|
|
"name": "A project",
|
|
"active": true,
|
|
"statusExplanation": {
|
|
"format": "markdown",
|
|
"raw": "Everything **fine**",
|
|
"html": "<p>Everything <strong>fine</strong></p>"
|
|
},
|
|
"public": false,
|
|
"description": {
|
|
"format": "markdown",
|
|
"raw": "Lorem **ipsum** dolor sit amet",
|
|
"html": "<p>Lorem <strong>ipsum</strong> dolor sit amet</p>"
|
|
},
|
|
"createdAt": "2015-07-06T13:28:14+00:00",
|
|
"updatedAt": "2015-10-01T09:55:02+00:00",
|
|
"type": "Customer Project"
|
|
},
|
|
{
|
|
"_type": "Project",
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/projects/14",
|
|
"title": "Another project"
|
|
},
|
|
"createWorkPackage": {
|
|
"href": "/api/v3/projects/14/work_packages/form",
|
|
"method": "post"
|
|
},
|
|
"createWorkPackageImmediate": {
|
|
"href": "/api/v3/projects/14/work_packages",
|
|
"method": "post"
|
|
},
|
|
"categories": {
|
|
"href": "/api/v3/projects/14/categories"
|
|
},
|
|
"versions": {
|
|
"href": "/api/v3/projects/14/versions"
|
|
},
|
|
"projects": {
|
|
"href": null
|
|
},
|
|
"status": {
|
|
"href": "/api/v3/project_statuses/off_track",
|
|
"title": "Off track"
|
|
}
|
|
},
|
|
"id": 14,
|
|
"identifier": "another_project",
|
|
"name": "Another project",
|
|
"active": false,
|
|
"statusExplanation": {
|
|
"format": "markdown",
|
|
"raw": "Uh **oh**",
|
|
"html": "<p>Uh <strong>oh</strong></p>"
|
|
},
|
|
"public": true,
|
|
"description": {
|
|
"format": "markdown",
|
|
"raw": "",
|
|
"html": ""
|
|
},
|
|
"createdAt": "2016-02-29T12:50:20+00:00",
|
|
"updatedAt": "2016-02-29T12:50:20+00:00",
|
|
"type": null
|
|
}]
|
|
}
|
|
}
|
|
}
|
|
|
|
## List projects [GET]
|
|
|
|
Returns a collection of projects. The collection can be filtered via query parameters similar to how work packages are filtered. In addition to the provided filter, the result set is always limited to only contain projects the client is allowed to see.
|
|
|
|
+ Parameters
|
|
+ filters (optional, string, `[{ "ancestor": { "operator": "=", "values": ['1'] }" }]`) ... JSON specifying filter conditions.
|
|
Accepts the same format as returned by the [queries](#queries) endpoint.
|
|
Currently supported filters are:
|
|
+ active: based on the active property of the project
|
|
+ ancestor: filters projects by their ancestor. A project is not considered to be it's own ancestor.
|
|
+ created_at: based on the time the project was created
|
|
+ latest_activity_at: based on the time the last activity was registered on a project.
|
|
+ name_and_identifier: based on both the name and the identifier.
|
|
+ parent_id: filters projects by their parent.
|
|
+ principal: based on members of the project.
|
|
+ type_id: based on the types active in a project.
|
|
+ user_action: based on the actions (see [Actions](#actions)) the current user has in the project.
|
|
+ id: based on projects' id.
|
|
There might also be additional filters based on the custom fields that have been configured.
|
|
+ sortBy (optional, string, `[["id", "asc"]]`) ... JSON specifying sort criteria.
|
|
Currently supported orders are:
|
|
+ id
|
|
+ name
|
|
+ created_at
|
|
+ public
|
|
+ latest_activity_at
|
|
+ required_disk_space
|
|
There might also be additional orders based on the custom fields that have been configured.
|
|
|
|
|
|
+ Response 200 (application/hal+json)
|
|
|
|
[List projects][]
|
|
|
|
## Projects schema [/api/v3/projects/schemas]
|
|
|
|
+ Model
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Schema",
|
|
"_dependencies": [],
|
|
"id": {
|
|
"type": "Integer",
|
|
"name": "ID",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": false
|
|
},
|
|
"name": {
|
|
"type": "String",
|
|
"name": "Name",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"minLength": 1,
|
|
"maxLength": 255
|
|
},
|
|
"identifier": {
|
|
"type": "String",
|
|
"name": "Identifier",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"minLength": 1,
|
|
"maxLength": 100
|
|
},
|
|
"description": {
|
|
"type": "Formattable",
|
|
"name": "Description",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true
|
|
},
|
|
"public": {
|
|
"type": "Boolean",
|
|
"name": "Public",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": true
|
|
},
|
|
"active": {
|
|
"type": "Boolean",
|
|
"name": "Active",
|
|
"required": true,
|
|
"hasDefault": true,
|
|
"writable": true
|
|
},
|
|
"status": {
|
|
"type": "ProjectStatus",
|
|
"name": "Status",
|
|
"required": false,
|
|
"hasDefault": true,
|
|
"writable": true,
|
|
"_links": {
|
|
"allowedValues": [
|
|
{
|
|
"href": "/api/v3/project_statuses/on_track",
|
|
"title": "On track"
|
|
},
|
|
{
|
|
"href": "/api/v3/project_statuses/at_risk",
|
|
"title": "At risk"
|
|
},
|
|
{
|
|
"href": "/api/v3/project_statuses/off_track",
|
|
"title": "Off track"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"statusExplanation": {
|
|
"type": "Formattable",
|
|
"name": "Status explanation",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true
|
|
},
|
|
"parent": {
|
|
"type": "Project",
|
|
"name": "Subproject of",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"location": "_links",
|
|
"visibility": "default",
|
|
"_links": {}
|
|
},
|
|
"createdAt": {
|
|
"type": "DateTime",
|
|
"name": "Created on",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": false
|
|
},
|
|
"updatedAt": {
|
|
"type": "DateTime",
|
|
"name": "Updated on",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": false
|
|
},
|
|
"customField30": {
|
|
"type": "Integer",
|
|
"name": "Integer project custom field",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"visibility": "default"
|
|
},
|
|
"customField31": {
|
|
"type": "CustomOption",
|
|
"name": "List project custom field",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"location": "_links",
|
|
"visibility": "default",
|
|
"_links": {}
|
|
},
|
|
"customField32": {
|
|
"type": "Version",
|
|
"name": "Version project custom field",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"location": "_links",
|
|
"visibility": "default",
|
|
"_links": {}
|
|
},
|
|
"customField34": {
|
|
"type": "Boolean",
|
|
"name": "Boolean project custom field",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"visibility": "default"
|
|
},
|
|
"customField35": {
|
|
"type": "String",
|
|
"name": "Text project custom field",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"visibility": "default"
|
|
},
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/projects/schema"
|
|
}
|
|
}
|
|
}
|
|
|
|
## View project schema [GET]
|
|
|
|
+ Response 200 (application/hal+json)
|
|
|
|
[Projects schema][]
|
|
|
|
## Project create form [/api/v3/projects/form]
|
|
|
|
This endpoint returns a form allowing a guided creation of new projects.
|
|
|
|
For more details and all possible responses see the general specification of [Forms](#forms).
|
|
|
|
## Project create form [POST]
|
|
|
|
+ Request Create project form
|
|
|
|
+ Body
|
|
|
|
{
|
|
"identifier": "new_project_identifier",
|
|
"name": "New project name",
|
|
"customField35": "Text custom field value"
|
|
}
|
|
|
|
+ Response 200 (application/hal+json)
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Form",
|
|
"_embedded": {
|
|
"payload": {
|
|
"identifier": "new_project_identifier",
|
|
"name": "New project name",
|
|
"active": true,
|
|
"public": false,
|
|
"description": {
|
|
"format": "markdown",
|
|
"raw": null,
|
|
"html": ""
|
|
},
|
|
"customField30": null,
|
|
"customField34": null,
|
|
"customField35": "Text custom field value",
|
|
"customField41": {
|
|
"format": "markdown",
|
|
"raw": "",
|
|
"html": ""
|
|
},
|
|
"customField42": null,
|
|
"statusExplanation": {
|
|
"format": "markdown",
|
|
"raw": null,
|
|
"html": "<p></p>"
|
|
},
|
|
"_links": {
|
|
"customField26": {
|
|
"href": null,
|
|
"title": null
|
|
},
|
|
"customField31": {
|
|
"href": null,
|
|
"title": null
|
|
},
|
|
"parent": {
|
|
"href": null
|
|
},
|
|
"status": {
|
|
"href": null
|
|
}
|
|
}
|
|
},
|
|
"schema": {
|
|
"_type": "Schema",
|
|
"_dependencies": [],
|
|
"id": {
|
|
"type": "Integer",
|
|
"name": "ID",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": false
|
|
},
|
|
"name": {
|
|
"type": "String",
|
|
"name": "Name",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"minLength": 1,
|
|
"maxLength": 255
|
|
},
|
|
"identifier": {
|
|
"type": "String",
|
|
"name": "Identifier",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"minLength": 1,
|
|
"maxLength": 100
|
|
},
|
|
"description": {
|
|
"type": "Formattable",
|
|
"name": "Description",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true
|
|
},
|
|
"public": {
|
|
"type": "Boolean",
|
|
"name": "Public",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": true
|
|
},
|
|
"active": {
|
|
"type": "Boolean",
|
|
"name": "Active",
|
|
"required": true,
|
|
"hasDefault": true,
|
|
"writable": true
|
|
},
|
|
"status": {
|
|
"type": "ProjectStatus",
|
|
"name": "Status",
|
|
"required": false,
|
|
"hasDefault": true,
|
|
"writable": true,
|
|
"_links": {
|
|
"allowedValues": [
|
|
{
|
|
"href": "/api/v3/project_statuses/on_track",
|
|
"title": "On track"
|
|
},
|
|
{
|
|
"href": "/api/v3/project_statuses/at_risk",
|
|
"title": "At risk"
|
|
},
|
|
{
|
|
"href": "/api/v3/project_statuses/off_track",
|
|
"title": "Off track"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"statusExplanation": {
|
|
"type": "Formattable",
|
|
"name": "Status explanation",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true
|
|
},
|
|
"parent": {
|
|
"type": "Project",
|
|
"name": "Subproject of",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"location": "_links",
|
|
"visibility": "default",
|
|
"_links": {
|
|
"allowedValues": {
|
|
"href": "/api/v3/projects/available_parent_projects"
|
|
}
|
|
}
|
|
},
|
|
"createdAt": {
|
|
"type": "DateTime",
|
|
"name": "Created on",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": false
|
|
},
|
|
"updatedAt": {
|
|
"type": "DateTime",
|
|
"name": "Updated on",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": false
|
|
},
|
|
"customField26": {
|
|
"type": "User",
|
|
"name": "Project user",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"location": "_links",
|
|
"visibility": "default",
|
|
"_links": {
|
|
"allowedValues": {
|
|
"href": "/api/v3/principals?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22%21%22%2C%22values%22%3A%5B%220%22%2C%223%22%5D%7D%7D%2C%7B%22type%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%22User%22%5D%7D%7D%2C%7B%22member%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%22%22%5D%7D%7D%5D&pageSize=0"
|
|
}
|
|
}
|
|
},
|
|
"customField30": {
|
|
"type": "Integer",
|
|
"name": "some project cf",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"visibility": "default"
|
|
},
|
|
"customField31": {
|
|
"type": "CustomOption",
|
|
"name": "list project cf",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"location": "_links",
|
|
"visibility": "default",
|
|
"_embedded": {
|
|
"allowedValues": [
|
|
{
|
|
"_type": "CustomOption",
|
|
"id": 513,
|
|
"value": "abc",
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/custom_options/513",
|
|
"title": "abc"
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"_type": "CustomOption",
|
|
"id": 514,
|
|
"value": "def",
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/custom_options/514",
|
|
"title": "def"
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"_type": "CustomOption",
|
|
"id": 515,
|
|
"value": "ghi",
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/custom_options/515",
|
|
"title": "ghi"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"_links": {
|
|
"allowedValues": [
|
|
{
|
|
"href": "/api/v3/custom_options/513",
|
|
"title": "abc"
|
|
},
|
|
{
|
|
"href": "/api/v3/custom_options/514",
|
|
"title": "def"
|
|
},
|
|
{
|
|
"href": "/api/v3/custom_options/515",
|
|
"title": "ghi"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"customField34": {
|
|
"type": "Boolean",
|
|
"name": "Bool Project CF",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"visibility": "default"
|
|
},
|
|
"customField35": {
|
|
"type": "String",
|
|
"name": "text project cf",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"visibility": "default"
|
|
},
|
|
"customField41": {
|
|
"type": "Formattable",
|
|
"name": "Long text project cf",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"visibility": "default"
|
|
},
|
|
"customField42": {
|
|
"type": "Date",
|
|
"name": "Date project cf",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"visibility": "default"
|
|
},
|
|
"_links": {}
|
|
},
|
|
"validationErrors": {
|
|
"identifier": {
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
|
|
"message": "Identifier has already been taken.",
|
|
"_embedded": {
|
|
"details": {
|
|
"attribute": "identifier"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/projects/form",
|
|
"method": "post"
|
|
},
|
|
"validate": {
|
|
"href": "/api/v3/projects/form",
|
|
"method": "post"
|
|
}
|
|
}
|
|
}
|
|
|
|
+ Response 400 (application/hal+json)
|
|
|
|
Occurs when the client did not send a valid JSON object in the request body.
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
|
|
"message": "The request body was not a single JSON object."
|
|
}
|
|
|
|
+ Response 403 (application/hal+json)
|
|
|
|
Returned if the client does not have sufficient permissions.
|
|
|
|
**Required permission:** add project which is a global permission
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
|
|
"message": "You are not authorized to access this resource."
|
|
}
|
|
|
|
## Project update form [/api/v3/projects/{id}/form]
|
|
|
|
This endpoint returns a form allowing a guided modification of existing projects.
|
|
The returned payload part of the form will be contain a merge between the already existing properties' values (as long as they are writeable) and the provided values with the later having precedence.
|
|
|
|
For more details and all possible responses see the general specification of [Forms](#forms).
|
|
|
|
## Project update form [POST]
|
|
|
|
+ Parameters
|
|
|
|
+ id (required, integer, `1`) ... Project id
|
|
|
|
+ Request Update project form
|
|
|
|
+ Body
|
|
|
|
{
|
|
"identifier": "new_project_identifier",
|
|
"name": "New project name",
|
|
"customField35": "Text custom field value"
|
|
}
|
|
|
|
+ Response 200 (application/hal+json)
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Form",
|
|
"_embedded": {
|
|
"payload": {
|
|
"identifier": "new_project_identifier",
|
|
"name": "New project name",
|
|
"active": true,
|
|
"public": false,
|
|
"description": {
|
|
"format": "markdown",
|
|
"raw": null,
|
|
"html": ""
|
|
},
|
|
"customField30": null,
|
|
"customField34": null,
|
|
"customField35": "Text custom field value",
|
|
"customField41": {
|
|
"format": "markdown",
|
|
"raw": "",
|
|
"html": ""
|
|
},
|
|
"customField42": null,
|
|
"statusExplanation": {
|
|
"format": "markdown",
|
|
"raw": "There is some risk of failure",
|
|
"html": "<p>There is some risk of failure</p>"
|
|
},
|
|
"_links": {
|
|
"customField26": {
|
|
"href": null,
|
|
"title": null
|
|
},
|
|
"customField31": {
|
|
"href": null,
|
|
"title": null
|
|
},
|
|
"parent": {
|
|
"href": "/api/v3/projects/45"
|
|
},
|
|
"status": {
|
|
"href": "/api/v3/project_statuses/at_risk"
|
|
}
|
|
}
|
|
},
|
|
"schema": {
|
|
"_type": "Schema",
|
|
"_dependencies": [],
|
|
"id": {
|
|
"type": "Integer",
|
|
"name": "ID",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": false
|
|
},
|
|
"name": {
|
|
"type": "String",
|
|
"name": "Name",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"minLength": 1,
|
|
"maxLength": 255
|
|
},
|
|
"identifier": {
|
|
"type": "String",
|
|
"name": "Identifier",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"minLength": 1,
|
|
"maxLength": 100
|
|
},
|
|
"description": {
|
|
"type": "Formattable",
|
|
"name": "Description",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true
|
|
},
|
|
"public": {
|
|
"type": "Boolean",
|
|
"name": "Public",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": true
|
|
},
|
|
"active": {
|
|
"type": "Boolean",
|
|
"name": "Active",
|
|
"required": true,
|
|
"hasDefault": true,
|
|
"writable": true
|
|
},
|
|
"status": {
|
|
"type": "ProjectStatus",
|
|
"name": "Status",
|
|
"required": false,
|
|
"hasDefault": true,
|
|
"writable": true,
|
|
"_links": {
|
|
"allowedValues": [
|
|
{
|
|
"href": "/api/v3/project_statuses/on_track",
|
|
"title": "On track"
|
|
},
|
|
{
|
|
"href": "/api/v3/project_statuses/at_risk",
|
|
"title": "At risk"
|
|
},
|
|
{
|
|
"href": "/api/v3/project_statuses/off_track",
|
|
"title": "Off track"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"statusExplanation": {
|
|
"type": "Formattable",
|
|
"name": "Status",
|
|
"required": true,
|
|
"hasDefault": true,
|
|
"writable": true,
|
|
},
|
|
"parent": {
|
|
"type": "Project",
|
|
"name": "Subproject of",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"location": "_links",
|
|
"visibility": "default",
|
|
"_links": {
|
|
"allowedValues": {
|
|
"href": "/api/v3/projects/available_parent_projects?of=123"
|
|
}
|
|
}
|
|
},
|
|
"createdAt": {
|
|
"type": "DateTime",
|
|
"name": "Created on",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": false
|
|
},
|
|
"updatedAt": {
|
|
"type": "DateTime",
|
|
"name": "Updated on",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": false
|
|
},
|
|
"customField26": {
|
|
"type": "User",
|
|
"name": "Project user",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"location": "_links",
|
|
"visibility": "default",
|
|
"_links": {
|
|
"allowedValues": {
|
|
"href": "/api/v3/principals?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22%21%22%2C%22values%22%3A%5B%220%22%2C%223%22%5D%7D%7D%2C%7B%22type%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%22User%22%5D%7D%7D%2C%7B%22member%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%22%22%5D%7D%7D%5D&pageSize=0"
|
|
}
|
|
}
|
|
},
|
|
"customField30": {
|
|
"type": "Integer",
|
|
"name": "some project cf",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"visibility": "default"
|
|
},
|
|
"customField31": {
|
|
"type": "CustomOption",
|
|
"name": "list project cf",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"location": "_links",
|
|
"visibility": "default",
|
|
"_embedded": {
|
|
"allowedValues": [
|
|
{
|
|
"_type": "CustomOption",
|
|
"id": 513,
|
|
"value": "abc",
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/custom_options/513",
|
|
"title": "abc"
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"_type": "CustomOption",
|
|
"id": 514,
|
|
"value": "def",
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/custom_options/514",
|
|
"title": "def"
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"_type": "CustomOption",
|
|
"id": 515,
|
|
"value": "ghi",
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/custom_options/515",
|
|
"title": "ghi"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"_links": {
|
|
"allowedValues": [
|
|
{
|
|
"href": "/api/v3/custom_options/513",
|
|
"title": "abc"
|
|
},
|
|
{
|
|
"href": "/api/v3/custom_options/514",
|
|
"title": "def"
|
|
},
|
|
{
|
|
"href": "/api/v3/custom_options/515",
|
|
"title": "ghi"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"customField34": {
|
|
"type": "Boolean",
|
|
"name": "Bool Project CF",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"visibility": "default"
|
|
},
|
|
"customField35": {
|
|
"type": "String",
|
|
"name": "text project cf",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"visibility": "default"
|
|
},
|
|
"customField41": {
|
|
"type": "Formattable",
|
|
"name": "Long text project cf",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"visibility": "default"
|
|
},
|
|
"customField42": {
|
|
"type": "Date",
|
|
"name": "Date project cf",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"visibility": "default"
|
|
},
|
|
"_links": {}
|
|
},
|
|
"validationErrors": {
|
|
"identifier": {
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
|
|
"message": "Identifier has already been taken.",
|
|
"_embedded": {
|
|
"details": {
|
|
"attribute": "identifier"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/projects/5/form",
|
|
"method": "post"
|
|
},
|
|
"validate": {
|
|
"href": "/api/v3/projects/5/form",
|
|
"method": "post"
|
|
}
|
|
}
|
|
}
|
|
|
|
+ Response 400 (application/hal+json)
|
|
|
|
Occurs when the client did not send a valid JSON object in the request body.
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
|
|
"message": "The request body was not a single JSON object."
|
|
}
|
|
|
|
+ Response 403 (application/hal+json)
|
|
|
|
Returned if the client does not have sufficient permissions.
|
|
|
|
**Required permission:** edit projects in the project
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
|
|
"message": "You are not authorized to access this resource."
|
|
}
|
|
|
|
|
|
## Project copy form [/api/v3/projects/{id}/copy/form]
|
|
|
|
This endpoint returns a form allowing a guided copy process of existing projects.
|
|
The returned payload part of the form will be contain a merge between the already existing properties' values of the source project (as long as they are writeable) and the provided values to be set for a new project.
|
|
|
|
For available properties, please see the project endpoint.
|
|
|
|
The copy form has a `_meta` property that allows defining which associations to copy. Please check the table below
|
|
and copy schema embedded in the copy form response for available options.
|
|
|
|
The embedded schema of this form describes all associations to copy with a human readable string including the total count of associated objects in the source project.
|
|
|
|
For more details and all possible responses see the general specification of [Forms](#forms).
|
|
|
|
### Meta parameters
|
|
|
|
| Meta property | Description | Type | Constraints | Supported operations |Condition |
|
|
| :------------------------: | --------------------------------------------------- | ---- | ----------- | -------------------- |----------|
|
|
| sendNotifications | Whether to send out notifications | Boolean | not null | READ/WRITE | |
|
|
| copyMembers | Whether to copy project members | Boolean | not null | READ/WRITE | |
|
|
| copyVersions | Whether to copy project versions | Boolean | not null | READ/WRITE | |
|
|
| copyCategories | Whether to copy project categories | Boolean | not null | READ/WRITE | |
|
|
| copyWorkPackages | Whether to copy project work packages | Boolean | not null | READ/WRITE | |
|
|
| copyWorkPackageAttachments | Whether to copy project attachments of work packages | Boolean | not null | READ/WRITE | |
|
|
| copyWiki | Whether to copy project wiki pages | Boolean | not null | READ/WRITE | |
|
|
| copyWikiPageAttachments | Whether to copy project wiki page attachments | Boolean | not null | READ/WRITE | |
|
|
| copyForums | Whether to copy project forums | Boolean | not null | READ/WRITE | |
|
|
| copyQueries | Whether to copy project queries | Boolean | not null | READ/WRITE | |
|
|
| copyBoards | Whether to copy project boards | Boolean | not null | READ/WRITE | |
|
|
| copyOverview | Whether to copy the project overview page | Boolean | not null | READ/WRITE | |
|
|
|
|
## Project copy form [POST]
|
|
|
|
+ Parameters
|
|
|
|
+ id (required, integer, `1`) ... Project id
|
|
|
|
+ Request copy project form
|
|
|
|
+ Body
|
|
|
|
{
|
|
"identifier": "copied_project_identifier",
|
|
"name": "Copied project name",
|
|
"customField35": "Text custom field value",
|
|
"_meta": {
|
|
"copyOverview": false,
|
|
"copyWorkPackages": true
|
|
}
|
|
}
|
|
|
|
+ Response 200 (application/hal+json)
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Form",
|
|
"_embedded": {
|
|
"payload": {
|
|
"identifier": "copied_project_identifier",
|
|
"name": "Copied project name",
|
|
"active": true,
|
|
"public": false,
|
|
"description": {
|
|
"format": "markdown",
|
|
"raw": null,
|
|
"html": ""
|
|
},
|
|
"customField30": null,
|
|
"customField34": null,
|
|
"customField35": "Text custom field value",
|
|
"customField41": {
|
|
"format": "markdown",
|
|
"raw": "",
|
|
"html": ""
|
|
},
|
|
"customField42": null,
|
|
"statusExplanation": {
|
|
"format": "markdown",
|
|
"raw": "There is some risk of failure",
|
|
"html": "<p>There is some risk of failure</p>"
|
|
},
|
|
"_links": {
|
|
"customField26": {
|
|
"href": null,
|
|
"title": null
|
|
},
|
|
"customField31": {
|
|
"href": null,
|
|
"title": null
|
|
},
|
|
"parent": null,
|
|
"status": {
|
|
"href": "/api/v3/project_statuses/at_risk"
|
|
}
|
|
},
|
|
"_meta": {
|
|
"copyOverview": false,
|
|
"copyBoards": false,
|
|
"copyForums": false,
|
|
"copyMembers": false,
|
|
"copyVersions": false,
|
|
"copyWiki": false,
|
|
"copyWikiPageAttachments": false,
|
|
"copyWorkPackages": false,
|
|
"copyWorkPackageAttachments": false,
|
|
"copyQueries": false,
|
|
"copyCategories": false
|
|
}
|
|
},
|
|
"schema": {
|
|
"_type": "Schema",
|
|
"_dependencies": [],
|
|
"id": {
|
|
"type": "Integer",
|
|
"name": "ID",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": false
|
|
},
|
|
"name": {
|
|
"type": "String",
|
|
"name": "Name",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"minLength": 1,
|
|
"maxLength": 255
|
|
},
|
|
"identifier": {
|
|
"type": "String",
|
|
"name": "Identifier",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"minLength": 1,
|
|
"maxLength": 100
|
|
},
|
|
"description": {
|
|
"type": "Formattable",
|
|
"name": "Description",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true
|
|
},
|
|
"public": {
|
|
"type": "Boolean",
|
|
"name": "Public",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": true
|
|
},
|
|
"active": {
|
|
"type": "Boolean",
|
|
"name": "Active",
|
|
"required": true,
|
|
"hasDefault": true,
|
|
"writable": true
|
|
},
|
|
"status": {
|
|
"type": "ProjectStatus",
|
|
"name": "Status",
|
|
"required": false,
|
|
"hasDefault": true,
|
|
"writable": true,
|
|
"_links": {
|
|
"allowedValues": [
|
|
{
|
|
"href": "/api/v3/project_statuses/on_track",
|
|
"title": "On track"
|
|
},
|
|
{
|
|
"href": "/api/v3/project_statuses/at_risk",
|
|
"title": "At risk"
|
|
},
|
|
{
|
|
"href": "/api/v3/project_statuses/off_track",
|
|
"title": "Off track"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"statusExplanation": {
|
|
"type": "Formattable",
|
|
"name": "Status",
|
|
"required": true,
|
|
"hasDefault": true,
|
|
"writable": true,
|
|
},
|
|
"parent": {
|
|
"type": "Project",
|
|
"name": "Subproject of",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"location": "_links",
|
|
"visibility": "default",
|
|
"_links": {
|
|
"allowedValues": {
|
|
"href": "/api/v3/projects/available_parent_projects?of=123"
|
|
}
|
|
}
|
|
},
|
|
"createdAt": {
|
|
"type": "DateTime",
|
|
"name": "Created on",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": false
|
|
},
|
|
"updatedAt": {
|
|
"type": "DateTime",
|
|
"name": "Updated on",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": false
|
|
},
|
|
"customField26": {
|
|
"type": "User",
|
|
"name": "Project user",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"location": "_links",
|
|
"visibility": "default",
|
|
"_links": {
|
|
"allowedValues": {
|
|
"href": "/api/v3/principals?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22%21%22%2C%22values%22%3A%5B%220%22%2C%223%22%5D%7D%7D%2C%7B%22type%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%22User%22%5D%7D%7D%2C%7B%22member%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%22%22%5D%7D%7D%5D&pageSize=0"
|
|
}
|
|
}
|
|
},
|
|
"customField30": {
|
|
"type": "Integer",
|
|
"name": "some project cf",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"visibility": "default"
|
|
},
|
|
"customField31": {
|
|
"type": "CustomOption",
|
|
"name": "list project cf",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"location": "_links",
|
|
"visibility": "default",
|
|
"_embedded": {
|
|
"allowedValues": [
|
|
{
|
|
"_type": "CustomOption",
|
|
"id": 513,
|
|
"value": "abc",
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/custom_options/513",
|
|
"title": "abc"
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"_type": "CustomOption",
|
|
"id": 514,
|
|
"value": "def",
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/custom_options/514",
|
|
"title": "def"
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"_type": "CustomOption",
|
|
"id": 515,
|
|
"value": "ghi",
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/custom_options/515",
|
|
"title": "ghi"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"_links": {
|
|
"allowedValues": [
|
|
{
|
|
"href": "/api/v3/custom_options/513",
|
|
"title": "abc"
|
|
},
|
|
{
|
|
"href": "/api/v3/custom_options/514",
|
|
"title": "def"
|
|
},
|
|
{
|
|
"href": "/api/v3/custom_options/515",
|
|
"title": "ghi"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"customField34": {
|
|
"type": "Boolean",
|
|
"name": "Bool Project CF",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"visibility": "default"
|
|
},
|
|
"customField35": {
|
|
"type": "String",
|
|
"name": "text project cf",
|
|
"required": true,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"visibility": "default"
|
|
},
|
|
"customField41": {
|
|
"type": "Formattable",
|
|
"name": "Long text project cf",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"visibility": "default"
|
|
},
|
|
"customField42": {
|
|
"type": "Date",
|
|
"name": "Date project cf",
|
|
"required": false,
|
|
"hasDefault": false,
|
|
"writable": true,
|
|
"visibility": "default"
|
|
},
|
|
"copyOverview": {
|
|
"type": "Boolean",
|
|
"name": "Overview",
|
|
"required": false,
|
|
"hasDefault": true,
|
|
"writable": true,
|
|
"location:" "_meta"
|
|
},
|
|
"copyBoards": {
|
|
"type": "Boolean",
|
|
"name": "Boards",
|
|
"required": false,
|
|
"hasDefault": true,
|
|
"writable": true,
|
|
"location:" "_meta"
|
|
},
|
|
"copyForums": {
|
|
"type": "Boolean",
|
|
"name": "Forums",
|
|
"required": false,
|
|
"hasDefault": true,
|
|
"writable": true,
|
|
"location:" "_meta"
|
|
},
|
|
"copyMembers": {
|
|
"type": "Boolean",
|
|
"name": "Members",
|
|
"required": false,
|
|
"hasDefault": true,
|
|
"writable": true,
|
|
"location:" "_meta"
|
|
},
|
|
"copyVersions": {
|
|
"type": "Boolean",
|
|
"name": "Versions",
|
|
"required": false,
|
|
"hasDefault": true,
|
|
"writable": true,
|
|
"location:" "_meta"
|
|
},
|
|
"copyWiki": {
|
|
"type": "Boolean",
|
|
"name": "Wiki",
|
|
"required": false,
|
|
"hasDefault": true,
|
|
"writable": true,
|
|
"location:" "_meta"
|
|
},
|
|
"copyWikiPageAttachments": {
|
|
"type": "Boolean",
|
|
"name": "Wiki page attachments",
|
|
"required": false,
|
|
"hasDefault": true,
|
|
"writable": true,
|
|
"location:" "_meta"
|
|
},
|
|
"copyWorkPackages": {
|
|
"type": "Boolean",
|
|
"name": "Work packages",
|
|
"required": false,
|
|
"hasDefault": true,
|
|
"writable": true,
|
|
"location:" "_meta"
|
|
},
|
|
"copyWorkPackageAttachments": {
|
|
"type": "Boolean",
|
|
"name": "Work package attachments",
|
|
"required": false,
|
|
"hasDefault": true,
|
|
"writable": true,
|
|
"location:" "_meta"
|
|
},
|
|
"copyQueries": {
|
|
"type": "Boolean",
|
|
"name": "Queries",
|
|
"required": false,
|
|
"hasDefault": true,
|
|
"writable": true,
|
|
"location:" "_meta"
|
|
},
|
|
"copyCategories": {
|
|
"type": "Boolean",
|
|
"name": "Categories",
|
|
"required": false,
|
|
"hasDefault": true,
|
|
"writable": true,
|
|
"location:" "_meta"
|
|
},
|
|
"_links": {}
|
|
},
|
|
"validationErrors": {
|
|
"identifier": {
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
|
|
"message": "Identifier has already been taken.",
|
|
"_embedded": {
|
|
"details": {
|
|
"attribute": "identifier"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/projects/5/copy/form",
|
|
"method": "post"
|
|
},
|
|
"validate": {
|
|
"href": "/api/v3/projects/5/copy/form",
|
|
"method": "post"
|
|
}
|
|
}
|
|
}
|
|
|
|
+ Response 400 (application/hal+json)
|
|
|
|
Occurs when the client did not send a valid JSON object in the request body.
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
|
|
"message": "The request body was not a single JSON object."
|
|
}
|
|
|
|
+ Response 403 (application/hal+json)
|
|
|
|
Returned if the client does not have sufficient permissions.
|
|
|
|
**Required permission:** copy projects in the source project
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
|
|
"message": "You are not authorized to access this resource."
|
|
}
|
|
|
|
|
|
|
|
## Create project copy [/api/v3/projects/{id}/copy]
|
|
|
|
This endpoint allows triggering a copy process of an existing project.
|
|
The request payload will be passed as attributes to the new project being created. Unset values will be retained from the existing project where possible.
|
|
|
|
For available properties, please see the project endpoint.
|
|
|
|
The copy endpoint has a `_meta` property that allows defining which associations to copy. Please check the copy schema embedded in the project copy form response for available options.
|
|
|
|
## Create project copy [POST]
|
|
|
|
+ Parameters
|
|
|
|
+ id (required, integer, `1`) ... Project id
|
|
|
|
|
|
+ Request Create copy project
|
|
|
|
+ Body
|
|
|
|
{
|
|
"identifier": "copied_project_identifier",
|
|
"name": "Copied project name",
|
|
"customField35": "Text custom field value",
|
|
"_meta": {
|
|
"copyOverview": false,
|
|
"copyWorkPackages": true
|
|
}
|
|
}
|
|
|
|
+ Response 302 (application/hal+json)
|
|
|
|
Returned if the request is successful. It will redirect to the job statuses API with the backend job that got created. You can query that endpoint to check the status of the copy, and eventually get the created project.
|
|
|
|
+ Body
|
|
|
|
|
|
|
|
+ Response 400 (application/hal+json)
|
|
|
|
Occurs when the client did not send a valid JSON object in the request body.
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
|
|
"message": "The request body was not a single JSON object."
|
|
}
|
|
|
|
+ Response 403 (application/hal+json)
|
|
|
|
Returned if the client does not have sufficient permissions.
|
|
|
|
**Required permission:** copy projects in the source project
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
|
|
"message": "You are not authorized to access this resource."
|
|
}
|
|
|
|
+ Response 422 (application/hal+json)
|
|
|
|
Returned if:
|
|
|
|
* a constraint for a property was violated (`PropertyConstraintViolation`)
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
|
|
"message": "Name can't be blank.",
|
|
"_embedded": {
|
|
"details": {
|
|
"attribute": "name"
|
|
}
|
|
}
|
|
}
|
|
|
|
|
|
|
|
## List available parent project candidates [/api/v3/projects/available_parent_projects{?filters,of,sortBy}]
|
|
|
|
+ Model
|
|
+ Body
|
|
|
|
{
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/projects/available_parent_projects?of=123"
|
|
}
|
|
},
|
|
"_type": "Collection",
|
|
"total": 2,
|
|
"count": 2,
|
|
"_embedded": {
|
|
"elements": [
|
|
{
|
|
"_type": "Project",
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/projects/6",
|
|
"title": "A project"
|
|
},
|
|
"createWorkPackage": {
|
|
"href": "/api/v3/projects/6/work_packages/form",
|
|
"method": "post"
|
|
},
|
|
"createWorkPackageImmediate": {
|
|
"href": "/api/v3/projects/6/work_packages",
|
|
"method": "post"
|
|
},
|
|
"categories": {
|
|
"href": "/api/v3/projects/6/categories"
|
|
},
|
|
"versions": {
|
|
"href": "/api/v3/projects/6/versions"
|
|
},
|
|
"status": {
|
|
"href": "/api/v3/project_statuses/on_track",
|
|
"title": "On track"
|
|
}
|
|
},
|
|
"id": 6,
|
|
"identifier": "a_project",
|
|
"name": "A project",
|
|
"active": true,
|
|
"statusExplanation": {
|
|
"format": "markdown",
|
|
"raw": "Everything **fine**",
|
|
"html": "<p>Everything <strong>fine</strong></p>"
|
|
},
|
|
"public": false,
|
|
"description": {
|
|
"format": "markdown",
|
|
"raw": "Lorem **ipsum** dolor sit amet",
|
|
"html": "<p>Lorem <strong>ipsum</strong> dolor sit amet</p>"
|
|
},
|
|
"createdAt": "2015-07-06T13:28:14+00:00",
|
|
"updatedAt": "2015-10-01T09:55:02+00:00",
|
|
"type": "Customer Project"
|
|
},
|
|
{
|
|
"_type": "Project",
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/projects/14",
|
|
"title": "Another project"
|
|
},
|
|
"createWorkPackage": {
|
|
"href": "/api/v3/projects/14/work_packages/form",
|
|
"method": "post"
|
|
},
|
|
"createWorkPackageImmediate": {
|
|
"href": "/api/v3/projects/14/work_packages",
|
|
"method": "post"
|
|
},
|
|
"categories": {
|
|
"href": "/api/v3/projects/14/categories"
|
|
},
|
|
"versions": {
|
|
"href": "/api/v3/projects/14/versions"
|
|
},
|
|
"status": {
|
|
"href": "/api/v3/project_statuses/on_track",
|
|
"title": "On track"
|
|
}
|
|
},
|
|
"id": 14,
|
|
"identifier": "another_project",
|
|
"name": "Another project",
|
|
"active": true,
|
|
"statusExplanation": {
|
|
"format": "markdown",
|
|
"raw": "Everything super **fine**",
|
|
"html": "<p>Everything super <strong>fine</strong></p>"
|
|
},
|
|
"public": true,
|
|
"description": {
|
|
"format": "markdown",
|
|
"raw": "",
|
|
"html": ""
|
|
},
|
|
"createdAt": "2016-02-29T12:50:20+00:00",
|
|
"updatedAt": "2016-02-29T12:50:20+00:00",
|
|
"type": null
|
|
}]
|
|
}
|
|
}
|
|
}
|
|
|
|
## List available parent project candidates [GET]
|
|
|
|
Lists projects which can become parent to another project. Only sound candidates are returned.
|
|
For instance a project cannot become parent of itself or it's children.
|
|
|
|
To specify the project for which a parent is queried for, the `of` parameter can be provided. If no `of`
|
|
parameter is provided, a new project is assumed. Then, the check for the hierarchy is omitted as a new project cannot be
|
|
part of a hierarchy yet.
|
|
|
|
Candidates can be filtered. Most commonly one will want to filter by name or identifier.
|
|
You can do this through the `filters` parameter which works just like the work package index.
|
|
|
|
For instance to find all parent candidates with "rollout" in their name:
|
|
|
|
```
|
|
?filters=[{"name_and_identifier":{"operator":"~","values":["rollout"]}}]
|
|
```
|
|
|
|
+ Parameters
|
|
+ filters (optional, string, `[{ "ancestor": { "operator": "=", "values": ['1'] }" }]`) ... JSON specifying filter conditions.
|
|
+ of (optional, number or identifier, `123` ... The id or identifier of the project the parent candidate is determined for
|
|
+ sortBy (optional, string, `[["id", "asc"]]`) ... JSON specifying sort criteria.
|
|
Accepts the same format as returned by the [queries](#queries) endpoint and allows all the filters and sortBy supported by the project list end point.
|
|
|
|
+ Response 200 (application/hal+json)
|
|
|
|
[List available parent project candidates][]
|
|
|
|
+ Response 403 (application/hal+json)
|
|
|
|
Returned if the client does not have sufficient permissions.
|
|
|
|
**Required permission:** edit project in a project or the global add project permission
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
|
|
"message": "You are not authorized to access this resource."
|
|
}
|
|
|
|
## List projects by version [/api/v3/versions/{id}/projects]
|
|
|
|
+ Model
|
|
+ Body
|
|
|
|
{
|
|
"_links":
|
|
{
|
|
"self":
|
|
{
|
|
"href": "/api/v3/versions/2/projects"
|
|
}
|
|
},
|
|
"total": 1,
|
|
"count": 1,
|
|
"_type": "Collection",
|
|
"_embedded":
|
|
{
|
|
"elements": [
|
|
{
|
|
"_type": "Project",
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/projects/1",
|
|
"title": "Lorem"
|
|
},
|
|
"categories": { "href": "/api/v3/projects/1/categories" },
|
|
"versions": { "href": "/api/v3/projects/1/versions" },
|
|
"status": {
|
|
"href": "/api/v3/project_statuses/on_track",
|
|
"title": "On track"
|
|
}
|
|
},
|
|
"id": 1,
|
|
"identifier": "project_identifier",
|
|
"name": "Project example",
|
|
"description": {
|
|
"format": "markdown",
|
|
"raw": "Lorem **ipsum** dolor sit amet",
|
|
"html": "<p>Lorem <strong>ipsum</strong> dolor sit amet</p>"
|
|
},
|
|
"active": true,
|
|
"statusExplanation": {
|
|
"format": "markdown",
|
|
"raw": "Everything **fine**",
|
|
"html": "<p>Everything <strong>fine</strong></p>"
|
|
},
|
|
"createdAt": "2014-05-21T08:51:20Z",
|
|
"updatedAt": "2014-05-21T08:51:20Z"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
|
|
## List projects with version [GET]
|
|
|
|
This endpoint lists the projects where the given version is available.
|
|
|
|
The projects returned depend on the sharing settings of the given version,
|
|
but are also limited to the projects that the current user is allowed to see.
|
|
|
|
+ Parameters
|
|
|
|
+ id (required, integer, `1`) ... Version id
|
|
|
|
+ Response 200 (application/hal+json)
|
|
|
|
[List projects by version][]
|
|
|
|
+ Response 404 (application/hal+json)
|
|
|
|
Returned if the version does not exist or the client does not have sufficient permissions
|
|
to see it.
|
|
|
|
**Required permission:** view work packages **or** manage versions (any project where the given version is available)
|
|
|
|
*Note: A client without sufficient permissions shall not be able to test for the existence of a version.
|
|
That's why a 404 is returned here, even if a 403 might be more appropriate.*
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
|
|
"message": "The requested resource could not be found."
|
|
}
|
|
|
|
## View project status
|
|
|
|
The project status enumerations are a fixed set set status a project can be in: "On track", "At risk" and "Off track". They can be
|
|
used to communicate a judgement on the project's likeliness to succeed.
|
|
|
|
## View project status [/api/v3/project_statuses/{id}]
|
|
|
|
+ Model
|
|
+ Body
|
|
|
|
{
|
|
"_type": "ProjectStatus",
|
|
"id": "on_track",
|
|
"name": "On track",
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/project_statuses/on_track"
|
|
}
|
|
}
|
|
}
|
|
|
|
## View project status [GET]
|
|
|
|
+ Parameters
|
|
|
|
+ id (required, string, `on_track`) ... Project status id
|
|
|
|
+ Response 200 (application/hal+json)
|
|
|
|
[View project status][]
|
|
|
|
+ Response 404 (application/hal+json)
|
|
|
|
Returned if the project status does not exist.
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
|
|
"message": "The requested resource could not be found."
|
|
}
|
|
|