API: Custom actions
Custom actions are a preconfigured set of changes that are applied to a work package.
Currently, this resource is a stub. The conditions and changes defined for the custom action are not yet present in the resource.
Actions
| Link | Description | Condition |
|---|---|---|
| executeImmediately | Apply the action to a work package |
Linked Properties
| Property | Description | Type | Constraints | Supported operations |
|---|---|---|---|---|
| self | This custom action | CustomAction | not null | READ |
Local Properties
| Property | Description | Type | Constraints | Supported operations |
|---|---|---|---|---|
| id | Custom action id | Integer | x > 0 | READ |
| name | The user selected name of the custom action | String | READ | |
| description | A text describing the custom action | String | READ |
Methods
View custom action
get /api/v3/custom_actions/{id} Parameters
id
integer
required path
The id of the custom action to fetch
Example:1
Responses
200
OK
Content-Type:
application/hal+json {
"_links": {
"executeImmediately": {
"href": "/apiChanges project and type in one go",
"method": "post",
"title": "Execute Change project and type"
},
"self": {
"href": "/api/v3/custom_actions/2",
"title": "Change project and type"
}
},
"_type": "CustomAction",
"description": "Changes project and type in one go",
"name": "Change project and type"
}
Custom_ActionModel {
"type": "object",
"example": {
"_type": "CustomAction",
"name": "Change project and type",
"description": "Changes project and type in one go",
"_links": {
"executeImmediately": {
"href": "/apiChanges project and type in one go",
"title": "Execute Change project and type",
"method": "post"
},
"self": {
"href": "/api/v3/custom_actions/2",
"title": "Change project and type"
}
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: edit work packages in any project
Content-Type:
application/hal+json {
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse {
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
404
Returned if the custom action does not exist.
Content-Type:
application/hal+json {
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
ErrorResponse {
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
Execute custom action
post /api/v3/custom_actions/{id}/executeA POST to this end point executes the custom action on the work package provided in the payload. The altered work package will be returned. In order to avoid executing the custom action unbeknown to a change that has already taken place, the client has to provide the work package’s current lockVersion.
Parameters
id
integer
required path
The id of the custom action to execute
Example:1
Request body
Content-Type:
application/json {
"_links": {
"workPackage": {
"href": "/api/v3/work_packages/42"
}
},
"lockVersion": "3"
}
{
"_links": {
"properties": {
"workPackage": {
"properties": {
"href": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"lockVersion": {
"type": "string"
}
}
Responses
200
OK
400
403
Returned if the client does not have sufficient permissions.
Required permission: edit work packages - Additional permissions might be required based on the custom action.
Content-Type:
application/hal+json {
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse {
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
404
Returned if the custom action does not exist.
Content-Type:
application/hal+json {
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
ErrorResponse {
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
406
409
Returned if the client provided an outdated lockVersion or no lockVersion at all.
Content-Type:
application/hal+json {
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:UpdateConflict",
"message": "Couldn't update the resource because of conflicting modifications."
}
ErrorResponse {
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
415
422
Returned if the custom action was not executed successfully e.g. when a constraint on a work package property was violated.
Content-Type:
application/hal+json {
"_embedded": {
"details": {
"attribute": "delay"
}
},
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
"message": "Delay must be a number greater than or equal to 0"
}
ErrorResponse {
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
