Grids
A grid is a layout for a page or a part of the page of the OpenProject application. It defines the structure (number of rows and number of columns) as well as the contents of the page.
The contents is defined by GridWidget
s. While a GridWidget
is it’s own type, it is not a resource in it’s own right as it is an intrinsic part of a Grid
.
Depending on what page a grid is defined for, different widgets may be eligible to be placed on the grid. The page might also define the permissions needed for accessing, creating or modifiying the grid.
Currently, the following pages employ grids:
- /my/page: The my page every user has. Only a user can access or modify their “my page”.
The delete action is not yet supported
Actions
Link | Description | Condition |
---|---|---|
updateImmediately | Directly perform edits on this grid | Permission: depends on the page the grid is defined for |
update | Validate edits on the grid via a form resource before commiting | Permission: depends on the page the grid is defined for |
Linked Properties
Link | Description | Type | Constraints | Supported operations | Condition |
---|---|---|---|---|---|
self | This grid | Grid | not null | READ | |
page | The url of the page the grid is defined for | url | not null | READ / WRITE | The page cannot be changed after the creation |
Local Properties
Property | Description | Type | Constraints | Supported operations | Condition |
---|---|---|---|---|---|
id | Grid’s id | Integer | x > 0 | READ | |
rowCount | The number of rows the grid has | Integer | x > 0 | READ/WRITE | |
columnCount | The number of columns the grid has | Integer | x > 0 | READ/WRITE | |
widgets | The set of GridWidget s selected for the grid |
[]GridWidget | READ/WRITE | The widgets cannot overlap | |
createdAt | The time the grid was created | DateTime | READ | ||
updatedAt | The time the grid was last updated | DateTime | READ |
GridWidget Properties
Property | Description | Type | Constraints | Supported operations | Condition |
---|---|---|---|---|---|
identifier | The kind of widget | String | not null | READ/WRITE | |
startRow | The row the widget starts at (1 based) | Integer | x > 0, x < rowCount of the grid, x < endRow | READ/WRITE | |
endRow | The row the widget ends. The widget’s area does not include the row itself. | Integer | x > 0, x <= rowCount of the grid, x > startRow | READ/WRITE | |
startColumn | The column the widget starts at (1 based) | Integer | x > 0, x < columnCount of the grid, x < endColumn | READ/WRITE | |
endColumn | The column the widget ends. The widget’s area does not include the column itself. | Integer | x > 0, x <= columnCount of the grid, x > startColumn | READ/WRITE | |
options | An options hash of values customizable by the widget | JSON | READ/WRITE |
Grid
- Parameters
- id
integer
(required) Example: 1grid id
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_type": "Grid", "id": 2, "rowCount": 8, "columnCount": 5, "widgets": [ { "_type": "GridWidget", "identifier": "time_entries_current_user", "startRow": 1, "endRow": 8, "startColumn": 1, "endColumn": 3 }, { "_type": "GridWidget", "identifier": "news", "startRow": 3, "endRow": 8, "startColumn": 4, "endColumn": 5 }, { "_type": "GridWidget", "identifier": "documents", "startRow": 1, "endRow": 3, "startColumn": 3, "endColumn": 6 } ], "createdAt": "2018-12-03T16:58:30Z", "updatedAt": "2018-12-13T19:36:40Z", "_links": { "scope": { "href": "/my/page", "type": "text/html" }, "updateImmediately": { "href": "/api/v3/grids/2", "method": "patch" }, "update": { "href": "/api/v3/grids/2/form", "method": "post" }, "self": { "href": "/api/v3/grids/2" } } }
- Response
404
Toggle details Returned if the Grid does not exist or if the user does not have permission to view it.
Required permission depends on the page the grid is defined for
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." }
Grids
Lists all grids matching the provided filters and being part of the selected query page. The grids returned will also depend on the permissions of the requesting user.
- Parameters
- offset
integer
(optional) Default: 1 Example: 25Page number inside the requested collection.
- pageSize
integer
(optional) Example: 25Number of elements to display per page.
- filters
string
(optional) Example: [{ "page": { "operator": "=", "values": ["/my/page"] } }]JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. Currently supported filters are:
- page: Filter grid by work package
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_type": "Grid", "id": 2, "rowCount": 8, "columnCount": 5, "widgets": [ { "_type": "GridWidget", "identifier": "time_entries_current_user", "startRow": 1, "endRow": 8, "startColumn": 1, "endColumn": 3 }, { "_type": "GridWidget", "identifier": "news", "startRow": 3, "endRow": 8, "startColumn": 4, "endColumn": 5 }, { "_type": "GridWidget", "identifier": "documents", "startRow": 1, "endRow": 3, "startColumn": 3, "endColumn": 6 } ], "createdAt": "2018-12-03T16:58:30Z", "updatedAt": "2018-12-13T19:36:40Z", "_links": { "scope": { "href": "/my/page", "type": "text/html" }, "updateImmediately": { "href": "/api/v3/grids/2", "method": "patch" }, "update": { "href": "/api/v3/grids/2/form", "method": "post" }, "self": { "href": "/api/v3/grids/2" } } }
- Response
400
Toggle details Returned if the client sends invalid request parameters e.g. filters
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery", "message": [ "Filters Invalid filter does not exist." ] }
- Response
403
Toggle details Returned if the client is not logged in and login is required.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not authorized to view this resource." }
Creates a new grid applying the attributes provided in the body. The constraints applied to the grid depend on the page the grid is placed in which is why the create form end point should be used to be guided when wanting to create a grid.
- Request
Create grid
Toggle details Body
{ "rowCount": 8, "columnCount": 5, "widgets": [ { "identifier": "time_entries_current_user", "startRow": 1, "endRow": 8, "startColumn": 1, "endColumn": 3 }, { "identifier": "news", "startRow": 3, "endRow": 8, "startColumn": 4, "endColumn": 5 }, { "identifier": "documents", "startRow": 1, "endRow": 3, "startColumn": 3, "endColumn": 6 } ], "_links": { "scope": { "href": "/my/page" } } }
- Response
201
Toggle details Body
{ "_type": "Grid", "id": 2, "rowCount": 8, "columnCount": 5, "widgets": [ { "_type": "GridWidget", "identifier": "time_entries_current_user", "startRow": 1, "endRow": 8, "startColumn": 1, "endColumn": 3 }, { "_type": "GridWidget", "identifier": "news", "startRow": 3, "endRow": 8, "startColumn": 4, "endColumn": 5 }, { "_type": "GridWidget", "identifier": "documents", "startRow": 1, "endRow": 3, "startColumn": 3, "endColumn": 6 } ], "createdAt": "2018-12-03T16:58:30Z", "updatedAt": "2018-12-13T19:36:40Z", "_links": { "scope": { "href": "/my/page", "type": "text/html" }, "updateImmediately": { "href": "/api/v3/grids/2", "method": "patch" }, "update": { "href": "/api/v3/grids/2/form", "method": "post" }, "self": { "href": "/api/v3/grids/2" } } }
- Response
400
Toggle details 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
Toggle details Returned if the client does not have sufficient permissions.
Required permission: Depends on the page the grid is defined for.
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
422
Toggle details Returned if:
- a constraint for a property was violated (
PropertyConstraintViolation
)
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation", "message": "Grid is invalid.", "_embedded": { "details": { "attribute"=>"rowCount", "message"=>"Number of rows must be greater than 0." } } }
- a constraint for a property was violated (
Updates the given grid by applying the attributes provided in the body. The constraints applied to the grid depend on the page the grid is placed in which is why the create form end point should be used to be guided when wanting to update a grid.
- Request
Update grid
Toggle details Body
{ "rowCount": 8, "columnCount": 5, "widgets": [ { "identifier": "time_entries_current_user", "startRow": 1, "endRow": 8, "startColumn": 1, "endColumn": 3 }, { "identifier": "news", "startRow": 3, "endRow": 8, "startColumn": 4, "endColumn": 5 }, { "identifier": "documents", "startRow": 1, "endRow": 3, "startColumn": 3, "endColumn": 6 } ] }
- Response
200
Toggle details Body
{ "_type": "Grid", "id": 2, "rowCount": 8, "columnCount": 5, "widgets": [ { "_type": "GridWidget", "identifier": "time_entries_current_user", "startRow": 1, "endRow": 8, "startColumn": 1, "endColumn": 3 }, { "_type": "GridWidget", "identifier": "news", "startRow": 3, "endRow": 8, "startColumn": 4, "endColumn": 5 }, { "_type": "GridWidget", "identifier": "documents", "startRow": 1, "endRow": 3, "startColumn": 3, "endColumn": 6 } ], "createdAt": "2018-12-03T16:58:30Z", "updatedAt": "2018-12-13T19:36:40Z", "_links": { "scope": { "href": "/my/page", "type": "text/html" }, "updateImmediately": { "href": "/api/v3/grids/2", "method": "patch" }, "update": { "href": "/api/v3/grids/2/form", "method": "post" }, "self": { "href": "/api/v3/grids/2" } } }
- Response
400
Toggle details 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
Toggle details Returned if the client does not have sufficient permissions.
Required permission: The permission depends on the page the grid is placed in.
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
422
Toggle details Returned if:
- a constraint for a property was violated (
PropertyConstraintViolation
)
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation", "message": "Grid is invalid.", "_embedded": { "details": { "attribute"=>"rowCount", "message"=>"Number of rows must be greater than 0." } } }
- a constraint for a property was violated (
Grid Create Form
This endpoint returns a form to allow a guided creation of a new grids. The returned form will be pre-filled with default values for every property, if available.
For more details and all possible responses see the general specification of Forms. A page link must be provided in the body when calling this end point.
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_type": "Form", "_embedded": { "payload": { "rowCount": 6, "columnCount": 4, "widgets": [ { "_type": "GridWidget", "identifier": "work_packages_assigned", "startRow": 1, "endRow": 7, "startColumn": 1, "endColumn": 3 }, { "_type": "GridWidget", "identifier": "work_packages_created", "startRow": 1, "endRow": 7, "startColumn": 3, "endColumn": 5 } ], "_links": { "scope": { "href": "/my/page", "type": "text/html" } } }, "schema": { "_type": "Schema", "id": { "type": "Integer", "name": "ID", "required": true, "hasDefault": false, "writable": false }, "createdAt": { "type": "DateTime", "name": "Created on", "required": true, "hasDefault": false, "writable": false }, "updatedAt": { "type": "DateTime", "name": "Updated on", "required": true, "hasDefault": false, "writable": false }, "rowCount": { "type": "Integer", "name": "Number of rows", "required": true, "hasDefault": false, "writable": true }, "columnCount": { "type": "Integer", "name": "Number of columns", "required": true, "hasDefault": false, "writable": true }, "scope": { "type": "Href", "name": "Page", "required": true, "hasDefault": false, "writable": true, "_links": { "allowedValues": [ { "href": "/my/page", "title": "My page" } ] } }, "widgets": { "type": "[]GridWidget", "name": "Widgets", "required": true, "hasDefault": false, "writable": true, "_embedded": { allowedValues: [ { "_type": "GridWidget", "identifier": "work_packages_assigned" }, { "_type": "GridWidget", "identifier": "news" } ] }, "_links": {} }, "_links": {} }, "validationErrors": { "widgets": { "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MultipleErrors", "message": "Multiple field constraints have been violated.", "_embedded": { "errors": [ { "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation", "message": "Widgets is outside of the grid.", "_embedded": { "details": { "attribute": "widgets" } } }, { "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation", "message": "Widgets is outside of the grid.", "_embedded": { "details": { "attribute": "widgets" } } } ] } }, "rowCount": { "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation", "message": "Number of rows must be greater than 0.", "_embedded": { "details": { "attribute": "rowCount" } } } } }, "_links": { "self": { "href": "/api/v3/grids/form", "method": "post" }, "validate": { "href": "/api/v3/grids/form", "method": "post" } } }
Grid Update Form
This endpoint returns a form to allow a guided modification of an existing grid.
For more details and all possible responses see the general specification of Forms.
- Parameters
- id
integer
(required) Example: 1ID of the grid being modified
- Request
Update grid form
Toggle details Body
{ "rowCount": 8, "columnCount": 5, "widgets": [ { "identifier": "time_entries_current_user", "startRow": 1, "endRow": 8, "startColumn": 1, "endColumn": 3 }, { "identifier": "news", "startRow": 3, "endRow": 8, "startColumn": 4, "endColumn": 5 }, { "identifier": "documents", "startRow": 1, "endRow": 3, "startColumn": 3, "endColumn": 6 } ] }
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_type": "Form", "_embedded": { "payload": { "rowCount": 6, "columnCount": 5, "widgets": [ { "_type": "GridWidget", "identifier": "time_entries_current_user", "startRow": 1, "endRow": 8, "startColumn": 1, "endColumn": 3 }, { "_type": "GridWidget", "identifier": "news", "startRow": 3, "endRow": 8, "startColumn": 4, "endColumn": 5 }, { "_type": "GridWidget", "identifier": "documents", "startRow": 1, "endRow": 3, "startColumn": 3, "endColumn": 6 } ] }, "schema": { "_type": "Schema", "id": { "type": "Integer", "name": "ID", "required": true, "hasDefault": false, "writable": false }, "createdAt": { "type": "DateTime", "name": "Created on", "required": true, "hasDefault": false, "writable": false }, "updatedAt": { "type": "DateTime", "name": "Updated on", "required": true, "hasDefault": false, "writable": false }, "rowCount": { "type": "Integer", "name": "Number of rows", "required": true, "hasDefault": false, "writable": true }, "columnCount": { "type": "Integer", "name": "Number of columns", "required": true, "hasDefault": false, "writable": true }, "scope": { "type": "Href", "name": "Page", "required": true, "hasDefault": false, "writable": false, "_links": {} }, "widgets": { "type": "[]GridWidget", "name": "Widgets", "required": true, "hasDefault": false, "writable": true, "_links": {} }, "_links": {} }, "validationErrors": { "widgets": { "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MultipleErrors", "message": "Multiple field constraints have been violated.", "_embedded": { "errors": [ { "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation", "message": "Widgets is outside of the grid.", "_embedded": { "details": { "attribute": "widgets" } } }, { "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation", "message": "Widgets is outside of the grid.", "_embedded": { "details": { "attribute": "widgets" } } } ] } } } }, "_links": { "self": { "href": "/api/v3/grids/2/form", "method": "post" }, "validate": { "href": "/api/v3/grids/2/form", "method": "post" } } }
- Response
403
Toggle details Returned if the client does not have sufficient permissions.
Required permission: depends on the page the grid is defined for.
Note that you will only receive this error, if you are at least allowed to see the corresponding grid.
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
Toggle details Returned if the grid does not exist or the client does not have sufficient permissions to see it.
Required permission: view work package
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." }
Help and feedback
If you did not find what you were looking for
If you need help from the community or want to support others
If you are eligible for professional support and have more questions
REQUEST SUPPORT
If you find an easily fixable error or need for improvement in the documentation for the stable release
If you would like to suggest bigger updates or improvements to this documentation
If you want to contribute to translate this documentation to another language
If there's something you don't like or understand about this feature
If you want to propose a new feature that OpenProject does not offer yet
To further help OpenProject to shape and test new features
To view OpenProject premium features and pricing
If you want to try all premium features in the OpenProject Cloud Edition 14 days for free
If you want to try all premium features in your on premise Community installation 14 days for free