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

Custom Action 

View custom action
/api/v3/custom_actions/{custom_action_id}
  • Parameters
  • custom_action_id
    integer (required) Example: 1

    The id of the custom action to fetch

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
  "_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"
    }
  }
}
  • Response  403

  • Returned if the client does not have sufficient permissions.

    Required permission: edit work packages in any project

    Headers
    Content-Type: application/hal+json
    Body
    {
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
  • Response  404

  • Returned if the custom action does not exist.

    Headers
    Content-Type: application/hal+json
    Body
    {
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}

Execute custom action 

Execute custom action
/api/v3/custom_actions/{custom_action_id}/execute

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.

  • Parameters
  • custom_action_id
    integer (required) Example: 1

    The id of the custom action to execute

  • Request  Execute custom action
  • Headers
    Content-Type: application/json
    Body
    {
  "lockVersion": "3",
  "_links": {
    "workPackage": {
      "href": "/api/v3/work_packages/42"
    }
  }
}
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    Returns the work package resource that was updated. See [Work packages](work-packages) section for details.
  • Response  400

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

    Headers
    Content-Type: application/hal+json
    Body
    {
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
  • Response  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.

    Headers
    Content-Type: application/hal+json
    Body
    {
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
  • Response  404

  • Returned if the custom action does not exist.

    Headers
    Content-Type: application/hal+json
    Body
    {
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
  • Response  409

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

    Headers
    Content-Type: application/hal+json
    Body
    {
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:UpdateConflict",
  "message": "Couldn't update the resource because of conflicting modifications."
}
  • Response  422

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

    Headers
    Content-Type: application/hal+json
    Body
    {
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Delay must be a number greater than or equal to 0",
  "_embedded": {
    "details": {
      "attribute": "delay"
    }
  }
}