API: Actions & Capabilities

An action is a change one can trigger within the OpenProject instance. This could be creating a work package, exporting work packages or updating a user. An action can also be something where the user is able to be involved so where the user is in the passive role e.g. when being assigned a work package.

A capability combines an action with a context and a principal. It thus communicates, which principal can carry out (or be passively involved) which action within a certain context. E.g. a user might have the capability of creating work packages within a project.

In other words, an action is independent of a principal and context while a capability is a relation between an action, the context and the principal.

The actions are most of the time derived from permissions which can be configured via the administrative UI where an administrator selects from a set of permissions to be granted per role. But there are other cases, e.g. in order to become assignee or responsible of a work package, a user has to have a role which allows having work packages assigned which is not a permission.

Even though user might have a capability, it might still not be possible to carry out the action because some other requirement is not met. E.g. a user might have the capability to update work packages, but if a particular work package is in a readonly state, that work package cannot be updated.

Only a small set of actions that actually already exist in the system are currently exposed via the api. They will be added over time.

Action

An action describes what can be carried out within the application. Until an action becomes assigned, which turns it into a capability, it remains in the state of “could be”.

Linked Properties

Link Description Type Constraints Supported operations
self The action Action not null READ

Local Properties

Property Description Type Constraints Supported operations
id Identifier for the action String Not null READ
name A human readable name for the action Not yet implemented String Not null READ
description Describes what can be done by principals having that action Not yet implemented String Not null READ
modules Clusters the actions into groups into which they belong logically Not yet implemented []String Not null READ

Capabilities

Actions can be assigned to a principal by assigning roles to that principal. E.g. a user might receive the ‘work_packages/show’ action by having a role called reader assigned within a project.

Whenever a principal is assigned an action within a context, the principal has additional capabilities.

Exactly which actions can be gained by having a role assigned depends on the configuration of that role. The configuration is adaptable by admins within the administration of the OpenProject instance.

Linked Properties

Link Description Type Constraints Supported operations
self The capability
action The action the principal is granted Action not null READ
context The context the principal has this the action in. This is typically a project or the global context. Project or null READ
principal The principal being allowed the action. Action not null READ

Local Properties

Property Description Type Constraints Supported operations
id Identifier for the action String Not null READ
name A human readable name for the action String Not null READ

Methods

List actions

Returns a collection of actions. The client can choose to filter the actions similar to how work packages are filtered. In addition to the provided filters, the server will reduce the result set to only contain actions, for which the requesting client has sufficient permissions.

filters
string

optional query

JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. Currently supported filters are:

  • id: Returns only the action having the id or all actions except those having the id(s).

Example:
[{ "id": { "operator": "=", "values": ["memberships/create"] }" }]

sortBy
string

optional query

JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint. Currently supported sorts are:

  • No sort supported yet

Default:
[["id", "asc"]]

Example:
[["id", "asc"]]

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "self": {
            "href": "/api/v3/actions/work_packages/create",
            "title": "Add work package"
          }
        },
        "_type": "Action",
        "description": "Creating a work package within a project including the uploading of attachments. Some attributes might not be selected, e.g version which requires a second permission",
        "id": "work_packages/create",
        "modules": [
          "work_packages"
        ],
        "name": "Add work package"
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/actions/work_packages/assign_versions",
            "title": "Assigning version"
          }
        },
        "_type": "Action",
        "description": "Assigning a work package to a version when creating/updating a work package. Only principals having this permission can assign a value to the version property of the work package resource.",
        "id": "work_packages/assign_versions",
        "modules": [
          "work_packages",
          "versions"
        ],
        "name": "Assign version"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/actions"
    }
  },
  "_type": "Collection",
  "count": 2,
  "total": 2
}
List_actionsModel
{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/actions"
      }
    },
    "total": 2,
    "count": 2,
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_links": {
            "self": {
              "href": "/api/v3/actions/work_packages/create",
              "title": "Add work package"
            }
          },
          "_type": "Action",
          "id": "work_packages/create",
          "name": "Add work package",
          "description": "Creating a work package within a project including the uploading of attachments. Some attributes might not be selected, e.g version which requires a second permission",
          "modules": [
            "work_packages"
          ]
        },
        {
          "_links": {
            "self": {
              "href": "/api/v3/actions/work_packages/assign_versions",
              "title": "Assigning version"
            }
          },
          "_type": "Action",
          "id": "work_packages/assign_versions",
          "name": "Assign version",
          "description": "Assigning a work package to a version when creating/updating a work package. Only principals having this permission can assign a value to the version property of the work package resource.",
          "modules": [
            "work_packages",
            "versions"
          ]
        }
      ]
    }
  }
}

View action

Returns an individual action.

id
string

required path

action id which is the name of the action

Example:
work_packages/create

200

OK

{
  "_links": {
    "self": {
      "href": "/api/v3/actions/work_packages/create",
      "title": "Add work package"
    }
  },
  "_type": "Action",
  "description": "Creating a work package within a project including the uploading of attachments. Some attributes might not be selected, e.g version which requires a second permission",
  "id": "work_packages/create",
  "modules": [
    "work_packages"
  ],
  "name": "Add work package"
}
View_actionModel
{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/actions/work_packages/create",
        "title": "Add work package"
      }
    },
    "_type": "Action",
    "id": "work_packages/create",
    "name": "Add work package",
    "description": "Creating a work package within a project including the uploading of attachments. Some attributes might not be selected, e.g version which requires a second permission",
    "modules": [
      "work_packages"
    ]
  }
}

404

Returned if the action does not exist.

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

List capabilities

Returns a collection of actions assigned to a principal in a context. The client can choose to filter the actions similar to how work packages are filtered. In addition to the provided filters, the server will reduce the result set to only contain actions, for which the requesting client has sufficient permissions

filters
string

optional query

JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint.

  • action: Get all capabilities of a certain action

  • principal: Get all capabilities of a principal

  • context: Get all capabilities within a context. Note that for a project context the client needs to provide p{id}, e.g. p5 and for the global context a g

Example:
[{ "principal": { "operator": "=", "values": ["1"] }" }]

sortBy
string

optional query

JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint. Currently supported sorts are:

  • id: Sort by the capabilities id

Default:
[["id", "asc"]]

Example:
[["id", "asc"]]

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "action": {
            "href": "/api/v3/actions/work_packages/create",
            "title": "Add work package"
          },
          "context": {
            "href": "/api/v3/projects/123",
            "title": "A project"
          },
          "principal": {
            "href": "/api/v3/users/567",
            "title": "Some user"
          },
          "self": {
            "href": "/api/v3/capabilities/work_packages/create/p123-567"
          }
        },
        "_type": "Capability",
        "id": "work_packages/create/p123-567"
      },
      {
        "_links": {
          "action": {
            "href": "/api/v3/actions/work_packages/assignee"
          },
          "context": {
            "href": "/api/v3/projects/123",
            "title": "A project"
          },
          "principal": {
            "href": "/api/v3/users/567",
            "title": "Some user"
          },
          "self": {
            "href": "/api/v3/capabilities/work_packages/assignee/p123-567"
          }
        },
        "_type": "Capability",
        "id": "work_packages/assignee/p123-567"
      },
      {
        "_links": {
          "action": {
            "href": "/api/v3/actions/memberships/create"
          },
          "context": {
            "href": "/api/v3/projects/345",
            "title": "A project"
          },
          "principal": {
            "href": "/api/v3/users/821",
            "title": "Some user"
          },
          "self": {
            "href": "/api/v3/capabilities/memberships/create/p345-821",
            "title": "Create members"
          }
        },
        "_type": "Capability",
        "id": "memberships/create/p345-821"
      },
      {
        "_links": {
          "context": {
            "href": "/api/v3/capabilities/context/global",
            "title": "Global"
          },
          "principal": {
            "href": "/api/v3/users/567",
            "title": "Some user"
          },
          "self": {
            "href": "/api/v3/capabilities/users/delete/g-567",
            "title": "Delete user"
          }
        },
        "_type": "Capability",
        "id": "users/delete/g-567"
      }
    ]
  },
  "_links": {
    "changeSize": {
      "href": "/api/v3/capabilities?pageSize={size}",
      "templated": true
    },
    "jumpTo": {
      "href": "/api/v3/capabilities?offset={offset}",
      "templated": true
    },
    "self": {
      "href": "/api/v3/capabilities"
    }
  },
  "_type": "Collection",
  "count": 4,
  "total": 4
}
List_capabilitiesModel
{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/capabilities"
      },
      "changeSize": {
        "href": "/api/v3/capabilities?pageSize={size}",
        "templated": true
      },
      "jumpTo": {
        "href": "/api/v3/capabilities?offset={offset}",
        "templated": true
      }
    },
    "total": 4,
    "count": 4,
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_links": {
            "self": {
              "href": "/api/v3/capabilities/work_packages/create/p123-567"
            },
            "action": {
              "href": "/api/v3/actions/work_packages/create",
              "title": "Add work package"
            },
            "context": {
              "href": "/api/v3/projects/123",
              "title": "A project"
            },
            "principal": {
              "href": "/api/v3/users/567",
              "title": "Some user"
            }
          },
          "_type": "Capability",
          "id": "work_packages/create/p123-567"
        },
        {
          "_links": {
            "self": {
              "href": "/api/v3/capabilities/work_packages/assignee/p123-567"
            },
            "action": {
              "href": "/api/v3/actions/work_packages/assignee"
            },
            "context": {
              "href": "/api/v3/projects/123",
              "title": "A project"
            },
            "principal": {
              "href": "/api/v3/users/567",
              "title": "Some user"
            }
          },
          "_type": "Capability",
          "id": "work_packages/assignee/p123-567"
        },
        {
          "_links": {
            "self": {
              "href": "/api/v3/capabilities/memberships/create/p345-821",
              "title": "Create members"
            },
            "action": {
              "href": "/api/v3/actions/memberships/create"
            },
            "context": {
              "href": "/api/v3/projects/345",
              "title": "A project"
            },
            "principal": {
              "href": "/api/v3/users/821",
              "title": "Some user"
            }
          },
          "_type": "Capability",
          "id": "memberships/create/p345-821"
        },
        {
          "_links": {
            "self": {
              "href": "/api/v3/capabilities/users/delete/g-567",
              "title": "Delete user"
            },
            "context": {
              "href": "/api/v3/capabilities/context/global",
              "title": "Global"
            },
            "principal": {
              "href": "/api/v3/users/567",
              "title": "Some user"
            }
          },
          "_type": "Capability",
          "id": "users/delete/g-567"
        }
      ]
    }
  }
}

View global context

Returns the global capability context. This context is necessary to consistently link to a context even if the context is not a project.

No parameters

200

OK

{
  "_links": {
    "self": {
      "href": "/api/v3/capabilities/context/global"
    }
  },
  "_type": "CapabilityContext::Global",
  "id": "global"
}
View_global_contextModel
{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/capabilities/context/global"
      }
    },
    "_type": "CapabilityContext::Global",
    "id": "global"
  }
}

404

Returned if the action does not exist.

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

View capabilities

id
string

required path

capability id

Example:
work_packages/create/p123-567

200

OK

{
  "_links": {
    "action": {
      "href": "/api/v3/actions/work_packages/create",
      "title": "Add work package"
    },
    "context": {
      "href": "/api/v3/projects/123",
      "title": "A project"
    },
    "principal": {
      "href": "/api/v3/users/567",
      "title": "Some user"
    },
    "self": {
      "href": "/api/v3/capabilities/work_packages/create/p123-567"
    }
  },
  "_type": "Capability",
  "id": "work_packages/create/p123-567"
}
View_capabilitiesModel
{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/capabilities/work_packages/create/p123-567"
      },
      "action": {
        "href": "/api/v3/actions/work_packages/create",
        "title": "Add work package"
      },
      "context": {
        "href": "/api/v3/projects/123",
        "title": "A project"
      },
      "principal": {
        "href": "/api/v3/users/567",
        "title": "Some user"
      }
    },
    "_type": "Capability",
    "id": "work_packages/create/p123-567"
  }
}

404

Returned if the capability does not exist.

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