TheDude
/
openproject
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
OpenProject is the leading open source project management software.
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.
59302 Commits
139 Branches
203 Tags
1.2 GiB
 
 
 
 
 
 
Tag: Branch: Tree: bc905390ea
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'bc905390ea'
${ noResults }
openproject/docs/api/apiv3/endpoints/actions.apib

398 lines
18 KiB
Raw Blame History

# Group 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 |
## View action [/api/v3/actions/{id}]
+ Model
+ Body
{
"_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"
]
}
## View action [GET]
Returns an individual action.
+ Parameters
+ id (required, string, `work_packages/create`) ... action id which is the name of the action
+ Response 200 (application/hal+json)
[View action][]
+ Response 404 (application/hal+json)
Returned if the action does not exist.
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
## List actions [/api/v3/actions{?filters,sortBy}]
+ Model
+ Body
{
"_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"
]
}
]
}
}
## List actions [GET]
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.
+ Parameters
+ filters (optional, string, `[{ "id": { "operator": "=", "values": ["memberships/create"] }" }]`) ... JSON specifying filter conditions.
Accepts the same format as returned by the [queries](#queries) endpoint.
Currently supported filters are:
+ id: Returns only the action having the id or all actions except those having the id(s).
+ sortBy = ["id", "asc"] (optional, string, `[["id", "asc"]]`) ... JSON specifying sort criteria.
Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported sorts are:
+ *No sort supported yet*
+ Response 200 (application/hal+json)
[List actions][]
## View capabilities [/api/v3/capabilities/{id}]
+ Model
+ Body
{
"_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"
}
## View capabilities [GET]
+ Parameters
+ id (required, string, `work_packages/create/p123-567`) ... capability id
+ Response 200 (application/hal+json)
[View capabilities][]
+ Response 404 (application/hal+json)
Returned if the capability does not exist.
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
## List capabilities [/api/v3/capabilities{?filters,sortBy}]
+ Model
+ Body
{
"_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"
},
]
}
}
## List capabilities [GET]
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
+ Parameters
+ filters (optional, string, `[{ "principal": { "operator": "=", "values": ["1"] }" }]`) ... JSON specifying filter conditions.
Accepts the same format as returned by the [queries](#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`
+ sortBy = ["id", "asc"] (optional, string, `[["id", "asc"]]`) ... JSON specifying sort criteria.
Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported sorts are:
+ id: Sort by the capabilities id
+ Response 200 (application/hal+json)
[List capabilities][]
## View global context [/api/v3/capabilities/context/global]
+ Model
+ Body
{
"_links": {
"self": {
"href": "/api/v3/capabilities/context/global"
}
},
"_type": "CapabilityContext::Global",
"id": "global"
}
## View global context [GET]
Returns the global capability context. This context is necessary to consistently link to a context even if the context is not a project.
+ Parameters
+ Response 200 (application/hal+json)
[View global context][]
+ Response 404 (application/hal+json)
Returned if the action does not exist.
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}