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

id
integer

required path

The id of the custom action to fetch

Example:
1

200

OK

{
  "_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

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

404

Returned if the custom action does not exist.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}

Execute custom action

A 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.

id
integer

required path

The id of the custom action to execute

Example:
1

{
  "_links": {
    "workPackage": {
      "href": "/api/v3/work_packages/42"
    }
  },
  "lockVersion": "3"
}
{
  "_links": {
    "properties": {
      "workPackage": {
        "properties": {
          "href": {
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    "type": "object"
  },
  "lockVersion": {
    "type": "string"
  }
}

200

OK

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}

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.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

404

Returned if the custom action does not exist.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}

409

Returned if the client provided an outdated lockVersion or no lockVersion at all.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:UpdateConflict",
  "message": "Couldn't update the resource because of conflicting modifications."
}

422

Returned if the custom action was not executed successfully e.g. when a constraint on a work package property was violated.

{
  "_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"
}