# Table of Contents - [REST API - Nextcloud Deck](#rest-api-nextcloud-deck) - [Home - Nextcloud Deck](#home-nextcloud-deck) - [Home - Nextcloud Deck](#home-nextcloud-deck) - [User documentation - Nextcloud Deck](#user-documentation-nextcloud-deck) - [Nextcloud API - Nextcloud Deck](#nextcloud-api-nextcloud-deck) - [User documentation - Nextcloud Deck](#user-documentation-nextcloud-deck) - [Class diagram - Nextcloud Deck](#class-diagram-nextcloud-deck) - [Markdown composing - Nextcloud Deck](#markdown-composing-nextcloud-deck) - [Markdown composing - Nextcloud Deck](#markdown-composing-nextcloud-deck) - [Implement import - Nextcloud Deck](#implement-import-nextcloud-deck) - [Nextcloud API - Nextcloud Deck](#nextcloud-api-nextcloud-deck) - [Data structure - Nextcloud Deck](#data-structure-nextcloud-deck) - [Implement import - Nextcloud Deck](#implement-import-nextcloud-deck) - [Class diagram - Nextcloud Deck](#class-diagram-nextcloud-deck) - [Data structure - Nextcloud Deck](#data-structure-nextcloud-deck) - [REST API - Nextcloud Deck](#rest-api-nextcloud-deck) --- # REST API - Nextcloud Deck * [Docs](https://deck.readthedocs.io/en/latest/) » * API documentation » * REST API * * * The REST API provides access for authenticated users to their data inside the Deck app. To get a better understanding of Decks data models and their relations, please have a look at the [data structure](https://deck.readthedocs.io/en/latest/structure/) documentation. Prerequisites ============= * All requests require a `OCS-APIRequest` HTTP header to be set to `true` and a `Content-Type` of `application/json`. * The API is located at https://nextcloud.local/index.php/apps/deck/api/v1.0 * All request parameters are required, unless otherwise specified Naming ------ * Board is the project like grouping of tasks that can be shared to different users and groups * Stack is the grouping of cards which is rendered in vertical columns in the UI * Card is the representation of a single task * Labels are defined on a board level and can be assigned to any number of cards Global responses ---------------- ### 400 Bad request In case the request is invalid, e.g. because a parameter is missing or an invalid value has been transmitted, a 400 error will be returned: { "status": 400, "message": "title must be provided" } ### 403 Permission denied In any case a user doesn't have access to a requested entity, a 403 error will be returned: { "status": 403, "message": "Permission denied" } Formats ------- ### Date Datetime values in request data need to be provided in ISO-8601. Example: 2020-01-20T09:52:43+00:00 Headers ------- ### If-Modified-Since Some index endpoints support limiting the result set to entries that have been changed since the given time. The supported date formats are: * IMF-fixdate: `Sun, 03 Aug 2019 10:34:12 GMT` * (obsolete) RFC 850: `Sunday, 03-Aug-19 10:34:12 GMT` * (obsolete) ANSI C asctime(): `Sun Aug 3 10:34:12 2019` It is highly recommended to only use the IMF-fixdate format. Note that according to [RFC2616](https://tools.ietf.org/html/rfc2616#section-3.3) all HTTP date/time stamps MUST be represented in Greenwich Mean Time (GMT), without exception. Example curl request: curl -u admin:admin -X GET \ 'http://localhost:8000/index.php/apps/deck/api/v1.0/boards/2/stacks' \ -H "OCS-APIRequest: true" \ -H "If-Modified-Since: Mon, 05 Nov 2018 09:28:00 GMT" ### ETag An ETag header is returned in order to determine if further child elements have been updated for the following endpoints: * Fetch all user board `GET /api/v1.0/boards` * Fetch a single board `GET /api/v1.0/boards/{boardId}` * Fetch all stacks of a board `GET /api/v1.0/boards/{boardId}/stacks` * Fetch a single stacks of a board `GET /api/v1.0/boards/{boardId}/stacks/{stackId}` * Fetch a single card of a board `GET /api/v1.0/boards/{boardId}/stacks/{stackId}/cards/{cardId}` * Fetch attachments of a card `GET /api/v1.0/boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments` If a `If-None-Match` header is provided and the requested element has not changed a `304` Not Modified response will be returned. Changes of child elements will propagate to their parents and also cause an update of the ETag which will be useful for determining if a sync is necessary on any client integration side. As an example, if a label is added to a card, the ETag of all related entities (the card, stack and board) will change. If available the ETag will also be part of JSON response objects as shown below for a card: { "id": 81, "ETag": "bdb10fa2d2aeda092a2b6b469454dc90", "title": "Test card" } Changelog ========= API version 1.0 --------------- * Deck >=1.0.0: The maximum length of the card title has been extended from 100 to 255 characters * Deck >=1.0.0: The API will now return a 400 Bad request response if the length limitation of a board, stack or card title is exceeded API version 1.1 --------------- This API version has become available with **Deck 1.3.0**. * The maximum length of the card title has been extended from 100 to 255 characters * The API will now return a 400 Bad request response if the length limitation of a board, stack or card title is exceeded * The attachments API endpoints will return other attachment types than deck\_file * Prior to Deck version v1.3.0 (API v1.0), attachments were stored within deck. For this type of attachments `deck_file` was used as the default type of attachments * Starting with Deck version 1.3.0 (API v1.1) files are stored within the users regular Nextcloud files and the type `file` has been introduced for that API version 1.2 (unreleased) ---------------------------- * Endpoints for the new import functionality have been added: * [GET /boards/import/getSystems - Import a board](https://deck.readthedocs.io/en/latest/API/#get-boardsimportgetsystems-import-a-board) * [GET /boards/import/config/system/{schema} - Import a board](https://deck.readthedocs.io/en/latest/API/#get-boardsimportconfigsystemschema-import-a-board) * [POST /boards/import - Import a board](https://deck.readthedocs.io/en/latest/API/#post-boardsimport-import-a-board) Endpoints ========= Boards ------ ### GET /boards - Get a list of boards #### Headers The board list endpoint supports setting an `If-Modified-Since` header to limit the results to entities that are changed after the provided time. #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | details | Bool | **Optional** Enhance boards with details about labels, stacks and users | #### Response ##### 200 Success Returns an array of board items [\ {\ "title": "Board title",\ "owner": {\ "primaryKey": "admin",\ "uid": "admin",\ "displayname": "Administrator"\ },\ "color": "ff0000",\ "archived": false,\ "labels": [],\ "acl": [],\ "permissions": {\ "PERMISSION_READ": true,\ "PERMISSION_EDIT": true,\ "PERMISSION_MANAGE": true,\ "PERMISSION_SHARE": true\ },\ "users": [],\ "shared": 0,\ "deletedAt": 0,\ "id": 10,\ "lastModified": 1586269585,\ "settings": {\ "notify-due": "off",\ "calendar": true\ }\ }\ ] ### POST /boards - Create a new board #### Request body | Parameter | Type | Description | | --- | --- | --- | | title | String | The title of the new board, maximum length is limited to 100 characters | | color | String | The hexadecimal color of the new board (e.g. FF0000) | { "title": "Board title", "color": "ff0000" } #### Response ##### 200 Success { "title": "Board title", "owner": { "primaryKey": "admin", "uid": "admin", "displayname": "Administrator" }, "color": "ff0000", "archived": false, "labels": [\ {\ "title": "Finished",\ "color": "31CC7C",\ "boardId": 10,\ "cardId": null,\ "id": 37\ },\ {\ "title": "To review",\ "color": "317CCC",\ "boardId": 10,\ "cardId": null,\ "id": 38\ },\ {\ "title": "Action needed",\ "color": "FF7A66",\ "boardId": 10,\ "cardId": null,\ "id": 39\ },\ {\ "title": "Later",\ "color": "F1DB50",\ "boardId": 10,\ "cardId": null,\ "id": 40\ }\ ], "acl": [], "permissions": { "PERMISSION_READ": true, "PERMISSION_EDIT": true, "PERMISSION_MANAGE": true, "PERMISSION_SHARE": true }, "users": [], "deletedAt": 0, "id": 10, "lastModified": 1586269585 } ##### 403 Forbidden A 403 response might be returned if the users ability to create new boards has been disabled by the administrator. For checking this before, see the `canCreateBoards` value in the [Nextcloud capabilties](https://deck.readthedocs.io/en/latest/API-Nextcloud/) . ### GET /boards/{boardId} - Get board details #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board to fetch | #### Response ##### 200 Success { "title": "Board title", "owner": { "primaryKey": "admin", "uid": "admin", "displayname": "Administrator" }, "color": "ff0000", "archived": false, "labels": [\ {\ "title": "Finished",\ "color": "31CC7C",\ "boardId": "10",\ "cardId": null,\ "id": 37\ },\ {\ "title": "To review",\ "color": "317CCC",\ "boardId": "10",\ "cardId": null,\ "id": 38\ },\ {\ "title": "Action needed",\ "color": "FF7A66",\ "boardId": "10",\ "cardId": null,\ "id": 39\ },\ {\ "title": "Later",\ "color": "F1DB50",\ "boardId": "10",\ "cardId": null,\ "id": 40\ }\ ], "acl": [], "permissions": { "PERMISSION_READ": true, "PERMISSION_EDIT": true, "PERMISSION_MANAGE": true, "PERMISSION_SHARE": true }, "users": [\ {\ "primaryKey": "admin",\ "uid": "admin",\ "displayname": "Administrator"\ }\ ], "deletedAt": 0, "id": 10 } ### PUT /boards/{boardId} - Update board details #### Request body | Parameter | Type | Description | | --- | --- | --- | | title | String | The title of the board, maximum length is limited to 100 characters | | color | String | The hexadecimal color of the board (e.g. FF0000) | | archived | Bool | Whether or not this board should be archived. | { "title": "Board title", "color": "ff0000", "archived": false } #### Response ##### 200 Success ### DELETE /boards/{boardId} - Delete a board #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board to fetch | #### Response ##### 200 Success ### POST /boards/{boardId}/undo\_delete - Restore a deleted board #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board to fetch | #### Response ##### 200 Success ### POST /boards/{boardId}/acl - Add new acl rule #### Request body | Parameter | Type | Description | | --- | --- | --- | | type | Integer | Type of the participant | | participant | String | The uid of the participant | | permissionEdit | Bool | Setting if the participant has edit permissions | | permissionShare | Bool | Setting if the participant has sharing permissions | | permissionManage | Bool | Setting if the participant has management permissions | ##### Supported participant types: * 0 User * 1 Group * 7 Circle #### Response ##### 200 Success [{\ "participant": {\ "primaryKey": "userid",\ "uid": "userid",\ "displayname": "User Name"\ },\ "type": 0,\ "boardId": 1,\ "permissionEdit": true,\ "permissionShare": false,\ "permissionManage": true,\ "owner": false,\ "id": 1\ }] ### PUT /boards/{boardId}/acl/{aclId} - Update an acl rule #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | permissionEdit | Bool | Setting if the participant has edit permissions | | permissionShare | Bool | Setting if the participant has sharing permissions | | permissionManage | Bool | Setting if the participant has management permissions | #### Response ##### 200 Success ### DELETE /boards/{boardId}/acl/{aclId} - Delete an acl rule #### Response ##### 200 Success Stacks ------ ### GET /boards/{boardId}/stacks - Get stacks #### Headers The board list endpoint supports setting an `If-Modified-Since` header to limit the results to entities that are changed after the provided time. #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board to fetch | #### Response [\ {\ "title": "ToDo",\ "boardId": 2,\ "deletedAt": 0,\ "lastModified": 1541426139,\ "cards": [...],\ "order": 999,\ "id": 4\ }\ ] ##### 200 Success ### GET /boards/{boardId}/stacks/archived - Get list of archived stacks #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board to fetch | #### Response [\ {\ "title": "ToDo",\ "boardId": 2,\ "deletedAt": 0,\ "lastModified": 1541426139,\ "cards": [...],\ "order": 999,\ "id": 4\ }\ ] ##### 200 Success ### GET /boards/{boardId}/stacks/{stackId} - Get stack details #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the stack belongs to | | stackId | Integer | The id of the stack | #### Response ##### 200 Success ### POST /boards/{boardId}/stacks - Create a new stack #### Request body | Parameter | Type | Description | | --- | --- | --- | | title | String | The title of the new stack, maximum length is limited to 100 characters | | order | Integer | Order for sorting the stacks | #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board to fetch | #### Response ##### 200 Success ### PUT /boards/{boardId}/stacks/{stackId} - Update stack details #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the stack belongs to | | stackId | Integer | The id of the stack | #### Request body | Parameter | Type | Description | | --- | --- | --- | | title | String | The title of the stack, maximum length is limited to 100 characters | | order | Integer | Order for sorting the stacks | #### Response ##### 200 Success ### DELETE /boards/{boardId}/stacks/{stackId} - Delete a stack #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the stack belongs to | | stackId | Integer | The id of the stack | #### Response ##### 200 Success Cards ----- ### GET /boards/{boardId}/stacks/{stackId}/cards/{cardId} - Get card details #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | #### Response ##### 200 Success ### POST /boards/{boardId}/stacks/{stackId}/cards - Create a new card #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | #### Request body | Parameter | Type | Description | | --- | --- | --- | | title | String | The title of the card, maximum length is limited to 255 characters | | type | String | Type of the card (for later use) use 'plain' for now | | order | Integer | Order for sorting the stacks | | description | String | _(optional)_ The markdown description of the card | | duedate | timestamp | _(optional)_ The duedate of the card or null | #### Response { "title":"Test", "description":null, "stackId":6, "type":"plain", "lastModified":1541528026, "createdAt":1541528026, "labels":null, "assignedUsers":null, "attachments":null, "attachmentCount":null, "owner":"admin", "order":999, "archived":false, "duedate": "2019-12-24T19:29:30+00:00", "deletedAt":0, "commentsUnread":0, "id":10, "overdue":0 } ##### 200 Success ### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId} - Update card details #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | #### Request data | Parameter | Type | Description | | --- | --- | --- | | title | String | The title of the card, maximum length is limited to 255 characters | | description | String | The markdown description of the card | | type | String | Type of the card (for later use) use 'plain' for now | | order | Integer | Order for sorting the stacks | | duedate | timestamp | The ISO-8601 formatted duedate of the card or null | { "title": "Test card", "description": "A card description", "type": "plain", "order": 999, "duedate": "2019-12-24T19:29:30+00:00", } #### Response ##### 200 Success ### DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId} - Delete a card #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | #### Response ##### 200 Success ### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignLabel - Assign a label to a card #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | #### Request data | Parameter | Type | Description | | --- | --- | --- | | labelId | Integer | The label id to assign to the card | | \#### Response | | | ##### 200 Success ### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/removeLabel - Remove a label to a card #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | #### Request data | Parameter | Type | Description | | --- | --- | --- | | labelId | Integer | The label id to remove to the card | #### Response ##### 200 Success ### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignUser - Assign a user to a card #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | #### Request data | Parameter | Type | Description | | --- | --- | --- | | userId | String | The user id to assign to the card | #### Response ##### 200 Success { "id": 3, "participant": { "primaryKey": "admin", "uid": "admin", "displayname": "admin" }, "cardId": 1 } ##### 400 Bad request { "status": 400, "message": "The user is already assigned to the card" } The request can fail with a bad request response for the following reasons: - Missing or wrongly formatted request parameters - The user is already assigned to the card - The user is not part of the board ### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unassignUser - Unassign a user from a card #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | #### Request data | Parameter | Type | Description | | --- | --- | --- | | userId | String | The user id to unassign from the card | #### Response ##### 200 Success ### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/reorder - Change the sorting order of a card #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | #### Request data | Parameter | Type | Description | | --- | --- | --- | | order | Integer | The position in the stack where the card should be moved to | | stackId | Integer | The id of the stack where the card should be moved to | #### Response ##### 200 Success Labels ------ ### GET /boards/{boardId}/labels/{labelId} - Get label details #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the label belongs to | | labelId | Integer | The id of the label | #### Response ##### 200 Success { "title": "Abgeschlossen", "color": "31CC7C", "boardId": "2", "cardId": null, "id": 5 } ### POST /boards/{boardId}/labels - Create a new label #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the label belongs to | #### Request data { "title": "Finished", "color": "31CC7C" } #### Response ##### 200 Success ### PUT /boards/{boardId}/labels/{labelId} - Update label details #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the label belongs to | | labelId | Integer | The id of the label | #### Request data { "title": "Finished", "color": "31CC7C" } #### Response ##### 200 Success ### DELETE /boards/{boardId}/labels/{labelId} - Delete a label #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the label belongs to | | labelId | Integer | The id of the label | #### Response ##### 200 Success Attachments ----------- ### GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments - Get a list of attachments #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | #### Response ##### 200 Success [\ {\ "cardId": 5,\ "type": "deck_file",\ "data": "6DADC2C69F4.eml",\ "lastModified": 1541529048,\ "createdAt": 1541529048,\ "createdBy": "admin",\ "deletedAt": 0,\ "extendedData": {\ "filesize": 922258,\ "mimetype": "application/octet-stream",\ "info": {\ "dirname": ".",\ "basename": "6DADC2C69F4.eml",\ "extension": "eml",\ "filename": "6DADC2C69F4"\ }\ },\ "id": 6\ }\ ] ### GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Get the attachment file #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the attachment belongs to | | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | #### Response ##### 200 Success ### POST /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments - Upload an attachment #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the attachment belongs to | | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | #### Request data | Parameter | Type | Description | | --- | --- | --- | | type | String | The type of the attachement | | file | Binary | File data to add as an attachment | * Prior to Deck version v1.3.0 (API v1.0), attachments were stored within deck. For this type of attachments `deck_file` was used as the default type of attachments * Starting with Deck version 1.3.0 (API v1.1) files are stored within the users regular Nextcloud files and the type `file` has been introduced for that #### Response ##### 200 Success ### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Update an attachment #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the attachment belongs to | | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | #### Request data | Parameter | Type | Description | | --- | --- | --- | | type | String | The type of the attachement | | file | Binary | File data to add as an attachment | For now only `deck_file` is supported as an attachment type. #### Response ##### 200 Success ### DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Delete an attachment #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the attachment belongs to | | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | #### Response ##### 200 Success ### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}/restore - Resore a deleted attachment #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the attachment belongs to | | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | #### Response ##### 200 Success ### GET /boards/import/getSystems - Import a board #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | system | Integer | The system name. Example: trello | #### Response Make a request to see the json schema of system { } ### GET /boards/import/config/system/{schema} - Import a board #### Request parameters #### Response [\ "trello"\ ] ### POST /boards/import - Import a board #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | system | string | The allowed name of system to import from | | config | Object | The config object (JSON) | | data | Object | The data object to import (JSON) | #### Response ##### 200 Success OCS API ======= The following endpoints are available through the Nextcloud OCS endpoint, which is available at `/ocs/v2.php/apps/deck/api/v1.0/`. This has the benefit that both the web UI as well as external integrations can use the same API. Config ------ Deck stores user and app configuration values globally and per board. The GET endpoint allows to fetch the current global configuration while board settings will be exposed through the board element on the regular API endpoints. ### GET /api/v1.0/config - Fetch app configuration values #### Response | Config key | Description | | --- | --- | | calendar | Determines if the calendar/tasks integration through the CalDAV backend is enabled for the user (boolean) | | cardDetailsInModal | Determines if the bigger view is used (boolean) | | cardIdBadge | Determines if the ID badges are displayed on cards (boolean) | | groupLimit | Determines if creating new boards is limited to certain groups of the instance. The resulting output is an array of group objects with the id and the displayname (Admin only) | { "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": { "calendar": true, "cardDetailsInModal": true, "cardIdBadge": true, "groupLimit": [\ {\ "id": "admin",\ "displayname": "admin"\ }\ ] } } } ### POST /api/v1.0/config/{id}/{key} - Set a config value #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | id | Integer | The id of the board | | key | String | The config key to set, prefixed with `board:{boardId}:` for board specific settings | | value | String | The value that should be stored for the config key | ##### Board configuration | Key | Value | | --- | --- | | notify-due | `off`, `assigned` or `all` | | calendar | Boolean | | cardDetailsInModal | Boolean | | cardIdBadge | Boolean | #### Example request curl -X POST 'https://admin:admin@nextcloud.local/ocs/v2.php/apps/deck/api/v1.0/config/calendar' -H 'Accept: application/json' -H "Content-Type: application/json" -H 'OCS-APIRequest: true' --data-raw '{"value":false}' { "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": false } } Comments -------- ### GET /cards/{cardId}/comments - List comments #### Request parameters string $cardId, int $limit = 20, int $offset = 0 | Parameter | Type | Description | | --- | --- | --- | | cardId | Integer | The id of the card | | limit | Integer | The maximum number of comments that should be returned, defaults to 20 | | offset | Integer | The start offset used for pagination, defaults to 0 | curl 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' #### Response A list of comments will be provided under the `ocs.data` key. If no or no more comments are available the list will be empty. ##### 200 Success { "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": [\ {\ "id": 175,\ "objectId": 12,\ "message": "This is a comment with a mention to @alice",\ "actorId": "admin",\ "actorType": "users",\ "actorDisplayName": "Administrator",\ "creationDateTime": "2020-03-10T10:23:07+00:00",\ "mentions": [\ {\ "mentionId": "alice",\ "mentionType": "user",\ "mentionDisplayName": "alice"\ }\ ]\ }\ ] } } In case a comment is marked as a reply to another comment object, the parent comment will be added as `replyTo` entry to the response. Only the next parent node is added, nested replies are not exposed directly. [\ {\ "id": 175,\ "objectId": 12,\ "message": "This is a comment with a mention to @alice",\ "actorId": "admin",\ "actorType": "users",\ "actorDisplayName": "Administrator",\ "creationDateTime": "2020-03-10T10:23:07+00:00",\ "mentions": [\ {\ "mentionId": "alice",\ "mentionType": "user",\ "mentionDisplayName": "alice"\ }\ ],\ "replyTo": {\ "id": 175,\ "objectId": 12,\ "message": "This is a comment with a mention to @alice",\ "actorId": "admin",\ "actorType": "users",\ "actorDisplayName": "Administrator",\ "creationDateTime": "2020-03-10T10:23:07+00:00",\ "mentions": [\ {\ "mentionId": "alice",\ "mentionType": "user",\ "mentionDisplayName": "alice"\ }\ ]\ }\ }\ ] ### POST /cards/{cardId}/comments - Create a new comment #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | cardId | Integer | The id of the card | | message | String | The message of the comment, maximum length is limited to 1000 characters | | parentId | Integer | _(optional)_ The start offset used for pagination, defaults to null | Mentions will be parsed by the server. The server will return a list of mentions in the response to this request as shown below. curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' -H 'Content-Type: application/json;charset=utf-8' --data '{"message":"My message to @bob","parentId":null}' #### Response A list of comments will be provided under the `ocs.data` key. If no or no more comments are available the list will be empty. ##### 200 Success { "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": { "id": "177", "objectId": "13", "message": "My message to @bob", "actorId": "admin", "actorType": "users", "actorDisplayName": "Administrator", "creationDateTime": "2020-03-10T10:30:17+00:00", "mentions": [\ {\ "mentionId": "bob",\ "mentionType": "user",\ "mentionDisplayName": "bob"\ }\ ] } } } ##### 400 Bad request A bad request response is returned if invalid input values are provided. The response message will contain details about which part was not valid. ##### 404 Not found A not found response might be returned if: - The card for the given cardId could not be found - The parent comment could not be found ### PUT /cards/{cardId}/comments/{commentId} - Update a comment #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | cardId | Integer | The id of the card | | commentId | Integer | The id of the comment | | message | String | The message of the comment, maximum length is limited to 1000 characters | Mentions will be parsed by the server. The server will return a list of mentions in the response to this request as shown below. Updating comments is limited to the current user being the same as the comment author specified in the `actorId` of the comment. curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' -H 'Content-Type: application/json;charset=utf-8' --data '{"message":"My message"}' #### Response A list of comments will be provided under the `ocs.data` key. If no or no more comments are available the list will be empty. ##### 200 Success { "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": { "id": "177", "objectId": "13", "message": "My message", "actorId": "admin", "actorType": "users", "actorDisplayName": "Administrator", "creationDateTime": "2020-03-10T10:30:17+00:00", "mentions": [] } } } ##### 400 Bad request A bad request response is returned if invalid input values are provided. The response message will contain details about which part was not valid. ##### 404 Not found A not found response might be returned if: - The card for the given cardId could not be found - The comment could not be found ### DELETE /cards/{cardId}/comments/{commentId} - Delete a comment #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | cardId | Integer | The id of the card | | commentId | Integer | The id of the comment | Deleting comments is limited to the current user being the same as the comment author specified in the `actorId` of the comment. curl -X DELETE 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' -H 'Content-Type: application/json;charset=utf-8' #### Response A list of comments will be provided under the `ocs.data` key. If no or no more comments are available the list will be empty. ##### 200 Success { "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": [] } } ##### 400 Bad request A bad request response is returned if invalid input values are provided. The response message will contain details about which part was not valid. ##### 404 Not found A not found response might be returned if: - The card for the given cardId could not be found - The comment could not be found Sessions -------- ### PUT /session/create - creates a new session #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the opened board | curl -X PUT 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session/create' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' \ -H 'Content-Type: application/json;charset=utf-8' \ --data '{"boardId":1}' #### Response ##### 200 Success { "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": { "token": "+zcJHf4rC6dobVSbuNa3delkCSfTW8OvYWTyLFvSpIv80FjtgLIj0ARlxspsazNQ" } } } ### POST /session/sync - notifies the server, that the session is still open #### Request body | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the opened board | | token | String | The session token from the /sessions/create response | curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session/create' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' \ -H 'Content-Type: application/json;charset=utf-8' \ --data '{"boardId":1, "token":"X3DyyoFslArF0t0NBZXzZXzcy8feoX/OEytSNXZtPg9TpUgO5wrkJ38IW3T/FfpV"}' #### Response ##### 200 Success { "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": [] } } ##### 404 Not Found the provided token is invalid or expired ### POST /session/close - closes the session #### Request body | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the opened board | | token | String | The session token from the /sessions/create response | curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session/close' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' \ -H 'Content-Type: application/json;charset=utf-8' \ --data '{"boardId":1, "token":"X3DyyoFslArF0t0NBZXzZXzcy8feoX/OEytSNXZtPg9TpUgO5wrkJ38IW3T/FfpV"}' #### Response ##### 200 Success { "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": [] } } [ClickSend is fast, reliable and dev-friendly. Get your first message out in minutes **Test for free.**](https://server.ethicalads.io/proxy/click/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) [Ads by EthicalAds](https://www.ethicalads.io/advertisers/topics/backend-web/?ref=ea-text) ![](https://server.ethicalads.io/proxy/view/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) --- # Home - Nextcloud Deck * [Docs](https://deck.readthedocs.io/en/latest/) » * Home * * * Deck ==== [![Build Status](https://travis-ci.org/nextcloud/deck.svg?branch=master)](https://travis-ci.org/nextcloud/deck) [![CodeCov](https://codecov.io/github/nextcloud/deck/coverage.svg?branch=master)](https://codecov.io/github/nextcloud/deck) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/e403f723f42a4abd93b2cfe36cbd7eee)](https://www.codacy.com/app/juliushaertl/deck?utm_source=github.com&utm_medium=referral&utm_content=nextcloud/deck&utm_campaign=Badge_Grade) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/nextcloud/deck/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/nextcloud/deck/?branch=master) [![#nextcloud-deck](https://img.shields.io/badge/IRC-%23nextcloud--deck%20on%20freenode-blue.svg)](https://webchat.freenode.net/?channels=nextcloud-deck) Deck is a kanban style organization tool aimed at personal planning and project organization for teams integrated with Nextcloud. * Add your tasks to cards and put them in order * Write down additional notes in markdown * Assign labels for even better organization * Share with your team, friends or family * Integrates with the [Circles](https://github.com/nextcloud/circles) app! * Attach files and embed them in your markdown description * Discuss with your team using comments * Keep track of changes in the activity stream * Get your project organized ![Deck - Manage cards on your board](http://download.bitgrid.net/nextcloud/deck/screenshots/1.0/Deck-2.png) ### Mobile apps * [Nextcloud Deck app for Android](https://github.com/stefan-niedermann/nextcloud-deck) - It is available in [F-Droid](https://f-droid.org/de/packages/it.niedermann.nextcloud.deck/) and the [Google Play Store](https://play.google.com/store/apps/details?id=it.niedermann.nextcloud.deck.play) * [deck NG for Android and iOS](https://github.com/meltzow/deck-ng) - It is available in [Google Play Store](https://play.google.com/store/apps/details?id=net.meltzow.deckng) and [Apple App Store](https://apps.apple.com/us/app/deck-ng/id6443334702) ### 3rd-Party Integrations * [trello-to-deck](https://github.com/maxammann/trello-to-deck) - Migrates cards from Trello * [mail2deck](https://github.com/newroco/mail2deck) - Provides an "email in" solution * [A-deck](https://github.com/leoossa/A-deck) - Chrome Extension that allows to create new card in selected stack based on current tab Installation/Update ------------------- This app is supposed to work on the two latest Nextcloud versions. ### Install latest release You can download and install the latest release from the [Nextcloud app store](https://apps.nextcloud.com/apps/deck) ### Install from git If you want to run the latest development version from git source, you need to clone the repo to your apps folder: git clone https://github.com/nextcloud/deck.git cd deck make install-deps make build Please make sure you have installed the following dependencies: `make, which, tar, npm, curl, composer` ### Install the nightly builds Instead of setting everything up manually, you can just [download the nightly build](https://github.com/nextcloud/deck/releases/tag/nightly) instead. These builds are updated every 24 hours, and are pre-configured with all the needed dependencies. Performance limitations ----------------------- Deck is not yet ready for intensive usage. A lot of database queries are generated when the number of boards, cards and attachments is high. For example, a user having access to 13 boards, with each board having on average 100 cards, and each card having on average 5 attachments, would generate 6500 database queries when doing the file related queries which would increase the page loading time significantly. Improvements on Nextcloud server and Deck itself will improve the situation. Developing ---------- ### Nextcloud environment You need to setup a [development environment](https://docs.nextcloud.com/server/latest/developer_manual//getting_started/devenv.html) of the current nextcloud version. You can also alternatively install & run the [nextcloud docker container](https://github.com/juliushaertl/nextcloud-docker-dev) . After the finished installation, you can clone the deck project directly in the `/[nextcloud-docker-dev-dir]/workspace/server/apps/` folder. ### PHP Nothing to prepare, just dig into the code. ### JavaScript This requires at least Node 16 and npm 7 to be installed. Deck requires running a `make build-js` to install npm dependencies and build the JavaScript code using webpack. While developing you can also use `make watch` to rebuild everytime the code changes. #### Hot reloading Enable debug mode in your config.php `'debug' => true,` Without SSL: npx webpack-dev-server --config webpack.hot.js \ --public localhost:3000 \ --output-public-path 'http://localhost:3000/js/' With SSL: npx webpack-dev-server --config webpack.dev.js --https \ --cert ~/repos/nextcloud/nc-dev/data/ssl/nextcloud.local.crt \ --key ~/repos/nextcloud/nc-dev/data/ssl/nextcloud.local.key \ --public nextcloud.local:3000 \ --output-public-path 'https://nextcloud.local:3000/js/' ### Running tests You can use the provided Makefile to run all tests by using: make test ### Documentation The documentation for our REST API can be found at https://deck.readthedocs.io/en/latest/API/ Contribution Guidelines ----------------------- Please read the [Code of Conduct](https://nextcloud.com/community/code-of-conduct/) . This document offers some guidance to ensure Nextcloud participants can cooperate effectively in a positive and inspiring atmosphere, and to explain how together we can strengthen and support each other. For more information please review the [guidelines for contributing](https://github.com/nextcloud/server/blob/master/.github/CONTRIBUTING.md) to this repository. ### Apply a license All contributions to this repository are considered to be licensed under the GNU AGPLv3 or any later version. Contributors to the Deck app retain their copyright. Therefore we recommend to add following line to the header of a file, if you changed it substantially: @copyright Copyright (c) , () For further information on how to add or update the license header correctly please have a look at [our licensing HowTo](https://github.com/nextcloud/server/blob/master/contribute/HowToApplyALicense.md) . ### Sign your work We use the Developer Certificate of Origin (DCO) as a additional safeguard for the Nextcloud project. This is a well established and widely used mechanism to assure contributors have confirmed their right to license their contribution under the project's license. Please read [developer-certificate-of-origin](https://github.com/nextcloud/server/blob/master/contribute/developer-certificate-of-origin) . If you can certify it, then just add a line to every git commit message: Signed-off-by: Random J Developer Use your real name (sorry, no pseudonyms or anonymous contributions). If you set your `user.name` and `user.email` git configs, you can sign your commit automatically with `git commit -s`. You can also use git [aliases](https://git-scm.com/book/tr/v2/Git-Basics-Git-Aliases) like `git config --global alias.ci 'commit -s'`. Now you can commit with `git ci` and the commit will be signed. [**Temporal Cloud:** Apps that never lose state. See every Workflow in real time. **Try for free.**](https://server.ethicalads.io/proxy/click/10292/019d59c8-f827-7580-8e14-14a5e5bafe8a/) [Ads by EthicalAds](https://www.ethicalads.io/advertisers/topics/frontend-web/?ref=ea-text) ![](https://server.ethicalads.io/proxy/view/10292/019d59c8-f827-7580-8e14-14a5e5bafe8a/) --- # Home - Nextcloud Deck * [Docs](https://deck.readthedocs.io/en/stable/) » * Home * * * Deck ==== [![Build Status](https://travis-ci.org/nextcloud/deck.svg?branch=main)](https://travis-ci.org/nextcloud/deck) [![CodeCov](https://codecov.io/github/nextcloud/deck/coverage.svg?branch=main)](https://codecov.io/github/nextcloud/deck) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/e403f723f42a4abd93b2cfe36cbd7eee)](https://www.codacy.com/app/juliushaertl/deck?utm_source=github.com&utm_medium=referral&utm_content=nextcloud/deck&utm_campaign=Badge_Grade) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/nextcloud/deck/badges/quality-score.png?b=main)](https://scrutinizer-ci.com/g/nextcloud/deck/?branch=main) [![#nextcloud-deck](https://img.shields.io/badge/IRC-%23nextcloud--deck%20on%20freenode-blue.svg)](https://webchat.freenode.net/?channels=nextcloud-deck) Deck is a kanban style organization tool aimed at personal planning and project organization for teams integrated with Nextcloud. * Add your tasks to cards and put them in order * Write down additional notes in markdown * Assign labels for even better organization * Share with your team, friends or family * Integrates with the [Circles](https://github.com/nextcloud/circles) app! * Attach files and embed them in your markdown description * Discuss with your team using comments * Keep track of changes in the activity stream * Get your project organized ![Deck - Manage cards on your board](http://download.bitgrid.net/nextcloud/deck/screenshots/1.0/Deck-2.png) ### Mobile apps * [Nextcloud Deck app for Android](https://github.com/stefan-niedermann/nextcloud-deck) - It is available in [F-Droid](https://f-droid.org/de/packages/it.niedermann.nextcloud.deck/) and the [Google Play Store](https://play.google.com/store/apps/details?id=it.niedermann.nextcloud.deck.play) * [deck NG for Android and iOS](https://github.com/meltzow/deck-ng) - It is available in [Google Play Store](https://play.google.com/store/apps/details?id=net.meltzow.deckng) and [Apple App Store](https://apps.apple.com/us/app/deck-ng/id6443334702) ### 3rd-Party Integrations * [trello-to-deck](https://github.com/maxammann/trello-to-deck) - Migrates cards from Trello * [mail2deck](https://github.com/newroco/mail2deck) - Provides an "email in" solution * [A-deck](https://github.com/leoossa/A-deck) - Chrome Extension that allows to create new card in selected stack based on current tab Installation/Update ------------------- The app can be installed through the app store within Nextcloud. You can also download the latest release from the [release page](https://github.com/nextcloud-releases/deck/releases) . Performance limitations ----------------------- Deck is not yet ready for intensive usage. A lot of database queries are generated when the number of boards, cards and attachments is high. For example, a user having access to 13 boards, with each board having on average 100 cards, and each card having on average 5 attachments, would generate 6500 database queries when doing the file related queries which would increase the page loading time significantly. Improvements on Nextcloud server and Deck itself will improve the situation. Developing ---------- There are multiple ways to develop on Deck. As you will need a Nextcloud server running, the individual options are described below. ### General build instructions General build instructions for the app itself are the same for all options. To build you will need to have [Node.js](https://nodejs.org/en/) and [Composer](https://getcomposer.org/) installed. * Install PHP dependencies: `composer install --no-dev` * Install JS dependencies: `npm ci` * Build JavaScript for the frontend * Development build `npm run dev` * Watch for changes `npm run watch` * Production build `npm run build` ### Faster frontend developing with HMR You can enable HMR (Hot module replacement) to avoid page reloads when working on the frontend: 1. ☑️ Install and enable [`hmr_enabler` app](https://github.com/nextcloud/hmr_enabler) 2. 🏁 Run `npm run serve` 3. 🌍 Open the normal Nextcloud server URL (not the URL given by above command) ### GitHub Codespaces / VS Code devcontainer * Open code spaces or the repository in VS Code to start the dev container * The container will automatically install all dependencies and build the app * Nextcloud will be installed from the master development branch and be available on a port exposed by the container ### Docker: Simple app development container * Fork the app * Clone the repository: `git clone https://github.com/nextcloud/deck.git` * Go into deck directory: `cd deck` * Build the app as described in the general build instructions * Run Nextcloud development container and mount the apps source code into it docker run --rm \ -p 8080:80 \ -v ~/path/to/app:/var/www/html/apps-extra/app \ ghcr.io/juliushaertl/nextcloud-dev-php80:latest ### Full Nextcloud development environment You need to setup a [development environment](https://docs.nextcloud.com/server/latest/developer_manual//getting_started/devenv.html) of the current Nextcloud version. You can also alternatively install & run the [nextcloud docker container](https://github.com/juliushaertl/nextcloud-docker-dev) . After the finished installation, you can clone the deck project directly in the `/[nextcloud-docker-dev-dir]/workspace/server/apps/` folder. ### Running tests You can use the provided Makefile to run all tests by using: make test ### Documentation The documentation for our REST API can be found at https://deck.readthedocs.io/en/latest/API/ Contribution Guidelines ----------------------- Please read the [Code of Conduct](https://nextcloud.com/community/code-of-conduct/) . This document offers some guidance to ensure Nextcloud participants can cooperate effectively in a positive and inspiring atmosphere, and to explain how together we can strengthen and support each other. For more information please review the [guidelines for contributing](https://github.com/nextcloud/server/blob/master/.github/CONTRIBUTING.md) to this repository. ### Apply a license All contributions to this repository are considered to be licensed under the GNU AGPLv3 or any later version. Contributors to the Deck app retain their copyright. Therefore we recommend to add following line to the header of a file, if you changed it substantially: @copyright Copyright (c) , () For further information on how to add or update the license header correctly please have a look at [our licensing HowTo](https://github.com/nextcloud/server/blob/master/contribute/HowToApplyALicense.md) . ### Sign your work We use the Developer Certificate of Origin (DCO) as a additional safeguard for the Nextcloud project. This is a well established and widely used mechanism to assure contributors have confirmed their right to license their contribution under the project's license. Please read [developer-certificate-of-origin](https://github.com/nextcloud/server/blob/master/contribute/developer-certificate-of-origin) . If you can certify it, then just add a line to every git commit message: Signed-off-by: Random J Developer Use your real name (sorry, no pseudonyms or anonymous contributions). If you set your `user.name` and `user.email` git configs, you can sign your commit automatically with `git commit -s`. You can also use git [aliases](https://git-scm.com/book/tr/v2/Git-Basics-Git-Aliases) like `git config --global alias.ci 'commit -s'`. Now you can commit with `git ci` and the commit will be signed. [ClickSend is fast, reliable and dev-friendly. Get your first message out in minutes **Test for free.**](https://server.ethicalads.io/proxy/click/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) [Ads by EthicalAds](https://www.ethicalads.io/advertisers/topics/backend-web/?ref=ea-text) ![](https://server.ethicalads.io/proxy/view/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) --- # User documentation - Nextcloud Deck * [Docs](https://deck.readthedocs.io/en/latest/) » * User documentation * * * Introduction ------------ ### What about Deck ? You may know Kanban website like Trello? Deck is about the same thing but secured and respectful of your privacy! Integrated in Nextcloud, you can easily manage your projects while having your data secured. ### Use cases Project management, time management or ideation, Deck makes it easier for you to manage your work. Using Deck ---------- Overall, Deck is easy to use. You can create boards, add users, share the Deck, work collaboratively and in real time. 1. [Create my first board](https://deck.readthedocs.io/en/latest/User_documentation_en/#1-create-my-first-board) 2. [Create stacks and cards](https://deck.readthedocs.io/en/latest/User_documentation_en/#2-create-stacks-and-cards) 3. [Handle cards options](https://deck.readthedocs.io/en/latest/User_documentation_en/#3-handle-cards-options) 4. [Archive old tasks](https://deck.readthedocs.io/en/latest/User_documentation_en/#4-archive-old-tasks) 5. [Manage your board](https://deck.readthedocs.io/en/latest/User_documentation_en/#5-manage-your-board) 6. [Import boards](https://deck.readthedocs.io/en/latest/User_documentation_en/#6-import-boards) 7. [Search](https://deck.readthedocs.io/en/latest/User_documentation_en/#7-search) 8. [New owner for the deck entities](https://deck.readthedocs.io/en/latest/User_documentation_en/#8-new-owner-for-the-deck-entities) ### 1\. Create my first board In this example, we're going to create a board and share it with an other nextcloud user. ![Gif for creating boards](https://deck.readthedocs.io/en/latest/resources/gifs/EN_create_board.gif) ### 2\. Create stacks and cards Stacks are simply columns with list of cards. It can represent a category of tasks or an y step in your projects for example. **Check this out :** ![Gif for creating columns](https://deck.readthedocs.io/en/latest/resources/gifs/EN_create_columns.gif) What about the cards? Cards are tasks, objects or ideas that fit into a stack. You can put a lot of cards in a stack! An infinity? Who knows! Who knows! And all the magic of this software consists on moving your cards from a stack to an other. **Check this out :** ![Gif for creating tasks](https://deck.readthedocs.io/en/latest/resources/gifs/EN_create_task.gif) ### 3\. Handle cards options Once you have created your cards, you can modify them or add options by clicking on them. So, what are the options? Well, there are several of them: * Tag Management * Assign a card to a user (s·he will receive a notification) * Render date, or deadline ![Gif for puting infos on tasks](https://deck.readthedocs.io/en/latest/resources/gifs/EN_put_infos.gif) And even : * Description in markdown language * Attachment - _you can leave a document, a picture or some other bonus like that._ ![Gif for puting infos on tasks 2](https://deck.readthedocs.io/en/latest/resources/gifs/EN_put_infos_2.gif) ### 4\. Archive old tasks Once finished or obsolete, a task could be archived. The tasks is not deleted, it's just archived, and you can retrieve it later ![Gif for puting infos on tasks 2](https://deck.readthedocs.io/en/latest/resources/gifs/EN_archive.gif) ### 5\. Manage your board You can manage the settings of your Deck once you are inside it, by clicking on the small wheel at the top right. Once in this menu, you have access to several things: * Sharing * Tags * Deleted objects * Timeline The **sharing tab** allows you to add users or even groups to your boards. **Tags** allows you to modify the tags available for the cards. **Deleted objects** allows you to return previously deleted stacks or cards. The **Timeline** allows you to see everything that happened in your boards. Everything! ### 6\. Import boards Importing can be done using the API or the `occ` `deck:import` command. Comments with more than 1000 characters are placed as attached files to the card. It is possible to import from the following sources: #### Trello JSON Steps: \* Create the data file \* Access Trello \* go to the board you want to export \* Follow the steps in [Trello documentation](https://help.trello.com/article/747-exporting-data-from-trello-1) and export as JSON \* Create the configuration file \* Execute the import informing the import file path, data file and source as `Trello JSON` Create the configuration file respecting the [JSON Schema](https://github.com/nextcloud/deck/blob/master/lib/Service/Importer/fixtures/config-trelloJson-schema.json) for import `Trello JSON` Example configuration file: { "owner": "admin", "color": "0800fd", "uidRelation": { "johndoe": "johndoe" } } **Limitations**: Importing from a JSON file imports up to 1000 actions. To find out how many actions the board to be imported has, identify how many actions the JSON has. #### Trello API Import using API is recommended for boards with more than 1000 actions. Trello makes it possible to attach links to a card. Deck does not have this feature. Attachments and attachment links are added in a markdown table at the end of the description for every imported card that has attachments in Trello. * Get the API Key and API Token [here](https://developer.atlassian.com/cloud/trello/guides/rest-api/api-introduction/#authentication-and-authorization) * Get the ID of the board you want to import by making a request to: https://api.trello.com/1/members/me/boards?key={yourKey}&token={yourToken}&fields=id,name This ID you will use in the configuration file in the `board` property \* Create the configuration file Create the configuration file respecting the [JSON Schema](https://github.com/nextcloud/deck/blob/master/lib/Service/Importer/fixtures/config-trelloApi-schema.json) for import `Trello JSON` Example configuration file: { "owner": "admin", "color": "0800fd", "api": { "key": "0cc175b9c0f1b6a831c399e269772661", "token": "92eb5ffee6ae2fec3ad71c777531578f4a8a08f09d37b73795649038408b5f33" }, "board": "8277e0910d750195b4487976", "uidRelation": { "johndoe": "johndoe" } } ### 7\. Search Deck provides a global search either through the unified search in the Nextcloud header or with the inline search next to the board controls. This search allows advanced filtering of cards across all board of the logged in user. For example the search `project tag:ToDo assigned:alice assigned:bob` will return all cards where the card title or description contains project **and** the tag ToDo is set **and** the user alice is assigned **and** the user bob is assigned. #### Supported search filters | Filter | Operators | Query | | --- | --- | --- | | title | `:` | text token used for a case-insentitive search on the cards title | | description | `:` | text token used for a case-insentitive search on the cards description | | list | `:` | text token used for a case-insentitive search on the cards list name | | tag | `:` | text token used for a case-insentitive search on the assigned tags | | date | `:` | 'overdue', 'today', 'week', 'month', 'none' | | | `>` `<` `>=` `<=` | Compare the card due date to the passed date (see [supported date formats](https://www.php.net/manual/de/datetime.formats.php)
) Card due dates are always considered UTC for comparison | | assigned | `:` | id or displayname of a user or group for a search on the assigned users or groups | Other text tokens will be used to perform a case-insensitive search on the card title and description In addition, quotes can be used to pass a query with spaces, e.g. `"Exact match with spaces"` or `title:"My card"`. ### 8\. New owner for the deck entities You can transfer ownership of boards, cards, etc to a new user, using `occ` command `deck:transfer-ownership` php occ deck:transfer-ownership previousOwner newOwner The transfer will preserve card details linked to the old owner, which can also be remapped by using the `--remap` option on the occ command. php occ deck:transfer-ownership --remap previousOwner newOwner Individual boards can be transferred by adding the id of the board to the command: php occ deck:transfer-ownership previousOwner newOwner 123 [ClickSend is fast, reliable and dev-friendly. Get your first message out in minutes **Test for free.**](https://server.ethicalads.io/proxy/click/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) [Ads by EthicalAds](https://www.ethicalads.io/advertisers/topics/backend-web/?ref=ea-text) ![](https://server.ethicalads.io/proxy/view/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) --- # Nextcloud API - Nextcloud Deck * [Docs](https://deck.readthedocs.io/en/latest/) » * API documentation » * Nextcloud API * * * Nextcloud APIs ============== Capabilities ------------ The [Nextcloud Capabilities API](https://docs.nextcloud.com/server/latest/developer_manual/client_apis/OCS/ocs-api-overview.html#capabilities-api) provides the following information for the Deck app: * `version` Current version of the Deck app running * `canCreateBoards` Ability of the current user to create new boards for themselves { "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": { "capabilities": { "deck": { "version": "0.8.0", "canCreateBoards": true }, } } } } Available sharees ----------------- When sharing a board to a user, group or circle, the possible sharees can be obtained though the files\_sharing API. API endpoint: https://nextcloud.local/index.php/apps/files\_sharing/api/v1/sharees ### Parameters * format: **The response format** * perPage: **Limit response number** * itemType: **List of types. Currently supported are** * 0 user * 1 group * 7 circle Comments -------- Comments are stored using the Nextcloud Comments API. You can use the WebDAV endpoint of Nextcloud to fetch, update and delete comments. ### List comments PROPFIND`remote.php/dav/comments/deckCard/{cardId}` ### Create comment POST `remote.php/dav/comments/deckCard/{cardId}` ### Update comment PROPPATCH `remote.php/dav/comments/deckCard/{cardId}/{commentId}` ### Delete comment DELETE `remote.php/dav/comments/deckCard/{cardId}/{commentId}` Activity -------- The Nextcloud activity app provides an API to fetch activities filtered for deck: [Activity app API documentation](https://github.com/nextcloud/activity/blob/master/docs/endpoint-v2.md) The deck app offers a filter `deck` to only request activity events that are relevant. [ClickSend is fast, reliable and dev-friendly. Get your first message out in minutes **Test for free.**](https://server.ethicalads.io/proxy/click/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) [Ads by EthicalAds](https://www.ethicalads.io/advertisers/topics/backend-web/?ref=ea-text) ![](https://server.ethicalads.io/proxy/view/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) --- # User documentation - Nextcloud Deck * [Docs](https://deck.readthedocs.io/en/stable/) » * User documentation * * * Introduction ------------ ### What about Deck ? You may know Kanban website like Trello? Deck is about the same thing but secured and respectful of your privacy! Integrated in Nextcloud, you can easily manage your projects while having your data secured. ### Use cases Project management, time management or ideation, Deck makes it easier for you to manage your work. Using Deck ---------- Overall, Deck is easy to use. You can create boards, add users, share the Deck, work collaboratively and in real time. 1. [Create my first board](https://deck.readthedocs.io/en/stable/User_documentation_en/#1-create-my-first-board) 2. [Create stacks and cards](https://deck.readthedocs.io/en/stable/User_documentation_en/#2-create-stacks-and-cards) 3. [Handle cards options](https://deck.readthedocs.io/en/stable/User_documentation_en/#3-handle-cards-options) 4. [Archive old tasks](https://deck.readthedocs.io/en/stable/User_documentation_en/#4-archive-old-tasks) 5. [Manage your board](https://deck.readthedocs.io/en/stable/User_documentation_en/#5-manage-your-board) 6. [Import boards](https://deck.readthedocs.io/en/stable/User_documentation_en/#6-import-boards) 7. [Search](https://deck.readthedocs.io/en/stable/User_documentation_en/#7-search) 8. [New owner for the deck entities](https://deck.readthedocs.io/en/stable/User_documentation_en/#8-new-owner-for-the-deck-entities) ### 1\. Create my first board In this example, we're going to create a board and share it with an other nextcloud user. ![Gif for creating boards](https://deck.readthedocs.io/en/stable/resources/gifs/EN_create_board.gif) ### 2\. Create stacks and cards Stacks are simply columns with list of cards. It can represent a category of tasks or an y step in your projects for example. **Check this out :** ![Gif for creating columns](https://deck.readthedocs.io/en/stable/resources/gifs/EN_create_columns.gif) What about the cards? Cards are tasks, objects or ideas that fit into a stack. You can put a lot of cards in a stack! An infinity? Who knows! Who knows! And all the magic of this software consists on moving your cards from a stack to an other. **Check this out :** ![Gif for creating tasks](https://deck.readthedocs.io/en/stable/resources/gifs/EN_create_task.gif) ### 3\. Handle cards options Once you have created your cards, you can modify them or add options by clicking on them. So, what are the options? Well, there are several of them: * Tag Management * Assign a card to a user (s·he will receive a notification) * Render date, or deadline ![Gif for puting infos on tasks](https://deck.readthedocs.io/en/stable/resources/gifs/EN_put_infos.gif) And even : * Description in markdown language * Attachment - _you can leave a document, a picture or some other bonus like that._ ![Gif for puting infos on tasks 2](https://deck.readthedocs.io/en/stable/resources/gifs/EN_put_infos_2.gif) ### 4\. Archive old tasks Once finished or obsolete, a task could be archived. The tasks is not deleted, it's just archived, and you can retrieve it later ![Gif for puting infos on tasks 2](https://deck.readthedocs.io/en/stable/resources/gifs/EN_archive.gif) ### 5\. Manage your board You can manage the settings of your Deck once you are inside it, by clicking on the small wheel at the top right. Once in this menu, you have access to several things: * Sharing * Tags * Deleted objects * Timeline The **sharing tab** allows you to add users or even groups to your boards. **Tags** allows you to modify the tags available for the cards. **Deleted objects** allows you to return previously deleted stacks or cards. The **Timeline** allows you to see everything that happened in your boards. Everything! ### 6\. Import boards Importing can be done using the API or the `occ` `deck:import` command. Comments with more than 1000 characters are placed as attached files to the card. It is possible to import from the following sources: #### Trello JSON Steps: \* Create the data file \* Access Trello \* go to the board you want to export \* Follow the steps in [Trello documentation](https://help.trello.com/article/747-exporting-data-from-trello-1) and export as JSON \* Create the configuration file \* Execute the import informing the import file path, data file and source as `Trello JSON` Create the configuration file respecting the [JSON Schema](https://github.com/nextcloud/deck/blob/main/lib/Service/Importer/fixtures/config-trelloJson-schema.json) for import `Trello JSON` Example configuration file: { "owner": "admin", "color": "0800fd", "uidRelation": { "johndoe": "johndoe" } } **Limitations**: Importing from a JSON file imports up to 1000 actions. To find out how many actions the board to be imported has, identify how many actions the JSON has. #### Trello API Import using API is recommended for boards with more than 1000 actions. Trello makes it possible to attach links to a card. Deck does not have this feature. Attachments and attachment links are added in a markdown table at the end of the description for every imported card that has attachments in Trello. * Get the API Key and API Token [here](https://developer.atlassian.com/cloud/trello/guides/rest-api/api-introduction/#authentication-and-authorization) * Get the ID of the board you want to import by making a request to: https://api.trello.com/1/members/me/boards?key={yourKey}&token={yourToken}&fields=id,name This ID you will use in the configuration file in the `board` property \* Create the configuration file Create the configuration file respecting the [JSON Schema](https://github.com/nextcloud/deck/blob/main/lib/Service/Importer/fixtures/config-trelloApi-schema.json) for import `Trello JSON` Example configuration file: { "owner": "admin", "color": "0800fd", "api": { "key": "0cc175b9c0f1b6a831c399e269772661", "token": "92eb5ffee6ae2fec3ad71c777531578f4a8a08f09d37b73795649038408b5f33" }, "board": "8277e0910d750195b4487976", "uidRelation": { "johndoe": "johndoe" } } ### 7\. Search Deck provides a global search either through the unified search in the Nextcloud header or with the inline search next to the board controls. This search allows advanced filtering of cards across all board of the logged in user. For example the search `project tag:ToDo assigned:alice assigned:bob` will return all cards where the card title or description contains project **and** the tag ToDo is set **and** the user alice is assigned **and** the user bob is assigned. #### Supported search filters | Filter | Operators | Query | | --- | --- | --- | | title | `:` | text token used for a case-insentitive search on the cards title | | description | `:` | text token used for a case-insentitive search on the cards description | | list | `:` | text token used for a case-insentitive search on the cards list name | | tag | `:` | text token used for a case-insentitive search on the assigned tags | | date | `:` | 'overdue', 'today', 'week', 'month', 'none' | | | `>` `<` `>=` `<=` | Compare the card due date to the passed date (see [supported date formats](https://www.php.net/manual/de/datetime.formats.php)
) Card due dates are always considered UTC for comparison | | assigned | `:` | id or displayname of a user or group for a search on the assigned users or groups | Other text tokens will be used to perform a case-insensitive search on the card title and description In addition, quotes can be used to pass a query with spaces, e.g. `"Exact match with spaces"` or `title:"My card"`. ### 8\. New owner for the deck entities You can transfer ownership of boards, cards, etc to a new user, using `occ` command `deck:transfer-ownership` php occ deck:transfer-ownership previousOwner newOwner The transfer will preserve card details linked to the old owner, which can also be remapped by using the `--remap` option on the occ command. php occ deck:transfer-ownership --remap previousOwner newOwner Individual boards can be transferred by adding the id of the board to the command: php occ deck:transfer-ownership previousOwner newOwner 123 [ClickSend is fast, reliable and dev-friendly. Get your first message out in minutes **Test for free.**](https://server.ethicalads.io/proxy/click/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) [Ads by EthicalAds](https://www.ethicalads.io/advertisers/topics/backend-web/?ref=ea-text) ![](https://server.ethicalads.io/proxy/view/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) --- # Class diagram - Nextcloud Deck * [Docs](https://deck.readthedocs.io/en/stable/) » * Developer documentation » * Import documentation » * Class diagram * * * Import class diagram -------------------- Importing boards to the Deck implements the class diagram below. > **NOTE**: When making any changes to the structure of the classes or implementing import from other sources, edit the `BoardImport.yuml` file ![Screenshot](https://deck.readthedocs.io/en/stable/resources/BoardImport.svg) [ClickSend is fast, reliable and dev-friendly. Get your first message out in minutes **Test for free.**](https://server.ethicalads.io/proxy/click/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) [Ads by EthicalAds](https://www.ethicalads.io/advertisers/topics/backend-web/?ref=ea-text) ![](https://server.ethicalads.io/proxy/view/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) --- # Markdown composing - Nextcloud Deck * [Docs](https://deck.readthedocs.io/en/latest/) » * Markdown composing * * * What is Markdown ---------------- The [wikipedia markdown entry](https://en.wikipedia.org/wiki/Markdown) introduced markdown as : > Markdown is a lightweight markup language with plain text formatting syntax. It is designed so that it can be converted to HTML and many other formats using a tool by the same name. Markdown is often used to format readme files, for writing messages in online discussion forums, and to create rich text using a plain text editor. As the initial description of Markdown contained ambiguities and unanswered questions, many implementations and extensions of Markdown appeared over the years to answer these issues. Markdown in Deck ---------------- The Deck application plugin uses the [markdown-it](https://github.com/markdown-it/markdown-it) script to offer support for markdown in the cards description field. Supported Markdown ------------------ Markdown comes in may flavors. The best way to learn markdown and understand how to use it, is simply to [try it](https://markdown-it.github.io/) on the original script official playground. That same link offers also a comprehensive list of what is supported, and what is not - rendering it unnecessary to duplicate that content in here. [CommonMark Markdown Reference](http://commonmark.org/help/) Note about checklists --------------------- It is possible to create checklists in Deck by writing it in Markdown, using the following syntax: - [ ] This is a not checked item - [x] This is a checked item Then, the items can be checked and unchecked by clicking on the rendered checkbox. Also, a summary of the completed items will be visible at the bottom of the card element. Known Issues ------------ As per [issue #127](https://github.com/nextcloud/deck/issues/127) Due to a known limitation of the current script to support markdown, Links that contain the `")"` character will not display well, or will break. The recommended solution is to use `"<"` and `">"` to wrap those links. It should assure their integrity. If you come by another case of broken link, or broken display of links, please report it by opening a new issue. [ClickSend is fast, reliable and dev-friendly. Get your first message out in minutes **Test for free.**](https://server.ethicalads.io/proxy/click/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) [Ads by EthicalAds](https://www.ethicalads.io/advertisers/topics/backend-web/?ref=ea-text) ![](https://server.ethicalads.io/proxy/view/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) --- # Markdown composing - Nextcloud Deck * [Docs](https://deck.readthedocs.io/en/stable/) » * Markdown composing * * * What is Markdown ---------------- The [wikipedia markdown entry](https://en.wikipedia.org/wiki/Markdown) introduced markdown as : > Markdown is a lightweight markup language with plain text formatting syntax. It is designed so that it can be converted to HTML and many other formats using a tool by the same name. Markdown is often used to format readme files, for writing messages in online discussion forums, and to create rich text using a plain text editor. As the initial description of Markdown contained ambiguities and unanswered questions, many implementations and extensions of Markdown appeared over the years to answer these issues. Markdown in Deck ---------------- The Deck application plugin uses the [markdown-it](https://github.com/markdown-it/markdown-it) script to offer support for markdown in the cards description field. Supported Markdown ------------------ Markdown comes in may flavors. The best way to learn markdown and understand how to use it, is simply to [try it](https://markdown-it.github.io/) on the original script official playground. That same link offers also a comprehensive list of what is supported, and what is not - rendering it unnecessary to duplicate that content in here. [CommonMark Markdown Reference](http://commonmark.org/help/) Note about checklists --------------------- It is possible to create checklists in Deck by writing it in Markdown, using the following syntax: - [ ] This is a not checked item - [x] This is a checked item Then, the items can be checked and unchecked by clicking on the rendered checkbox. Also, a summary of the completed items will be visible at the bottom of the card element. Known Issues ------------ As per [issue #127](https://github.com/nextcloud/deck/issues/127) Due to a known limitation of the current script to support markdown, Links that contain the `")"` character will not display well, or will break. The recommended solution is to use `"<"` and `">"` to wrap those links. It should assure their integrity. If you come by another case of broken link, or broken display of links, please report it by opening a new issue. [ClickSend is fast, reliable and dev-friendly. Get your first message out in minutes **Test for free.**](https://server.ethicalads.io/proxy/click/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) [Ads by EthicalAds](https://www.ethicalads.io/advertisers/topics/backend-web/?ref=ea-text) ![](https://server.ethicalads.io/proxy/view/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) --- # Implement import - Nextcloud Deck * [Docs](https://deck.readthedocs.io/en/latest/) » * Developer documentation » * Import documentation » * Implement import * * * Implement import ---------------- * Create a new importer class extending `ABoardImportService` * Create a listener for event `BoardImportGetAllowedEvent` to enable your importer. > You can read more about listeners on [Nextcloud](https://docs.nextcloud.com/server/latest/developer_manual/basics/events.html?highlight=event#writing-a-listener) > doc. Example: class YourCustomImporterListener { public function handle(Event $event): void { if (!($event instanceof BoardImportGetAllowedEvent)) { return; } $event->getService()->addAllowedImportSystem([\ 'name' => YourCustomImporterService::$name,\ 'class' => YourCustomImporterService::class,\ 'internalName' => 'YourCustomImporter'\ ]); } } * Register your listener on your `Application` class like this: $dispatcher = $this->getContainer()->query(IEventDispatcher::class); $dispatcher->registerEventListener( BoardImportGetAllowedEvent::class, YourCustomImporterListener::class ); * Use the `lib/Service/Importer/Systems/TrelloJsonService.php` class as inspiration [ClickSend is fast, reliable and dev-friendly. Get your first message out in minutes **Test for free.**](https://server.ethicalads.io/proxy/click/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) [Ads by EthicalAds](https://www.ethicalads.io/advertisers/topics/backend-web/?ref=ea-text) ![](https://server.ethicalads.io/proxy/view/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) --- # Nextcloud API - Nextcloud Deck * [Docs](https://deck.readthedocs.io/en/stable/) » * API documentation » * Nextcloud API * * * Nextcloud APIs ============== Capabilities ------------ The [Nextcloud Capabilities API](https://docs.nextcloud.com/server/latest/developer_manual/client_apis/OCS/ocs-api-overview.html#capabilities-api) provides the following information for the Deck app: * `version` Current version of the Deck app running * `canCreateBoards` Ability of the current user to create new boards for themselves { "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": { "capabilities": { "deck": { "version": "0.8.0", "canCreateBoards": true }, } } } } Available sharees ----------------- When sharing a board to a user, group or circle, the possible sharees can be obtained though the files\_sharing API. API endpoint: https://nextcloud.local/index.php/apps/files\_sharing/api/v1/sharees ### Parameters * format: **The response format** * perPage: **Limit response number** * itemType: **List of types. Currently supported are** * 0 user * 1 group * 7 circle Comments -------- Comments are stored using the Nextcloud Comments API. You can use the WebDAV endpoint of Nextcloud to fetch, update and delete comments. ### List comments PROPFIND`remote.php/dav/comments/deckCard/{cardId}` ### Create comment POST `remote.php/dav/comments/deckCard/{cardId}` ### Update comment PROPPATCH `remote.php/dav/comments/deckCard/{cardId}/{commentId}` ### Delete comment DELETE `remote.php/dav/comments/deckCard/{cardId}/{commentId}` Activity -------- The Nextcloud activity app provides an API to fetch activities filtered for deck: [Activity app API documentation](https://github.com/nextcloud/activity/blob/master/docs/endpoint-v2.md) The deck app offers a filter `deck` to only request activity events that are relevant. [ClickSend is fast, reliable and dev-friendly. Get your first message out in minutes **Test for free.**](https://server.ethicalads.io/proxy/click/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) [Ads by EthicalAds](https://www.ethicalads.io/advertisers/topics/backend-web/?ref=ea-text) ![](https://server.ethicalads.io/proxy/view/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) --- # Data structure - Nextcloud Deck * [Docs](https://deck.readthedocs.io/en/latest/) » * Developer documentation » * Data structure * * * Database structure ------------------ Deck stores most of its data inside of the database. The structure and relationships between entities is documented in the following ER diagram: ![Screenshot](https://deck.readthedocs.io/en/latest/resources/er-diagram.jpg) [ClickSend is fast, reliable and dev-friendly. Get your first message out in minutes **Test for free.**](https://server.ethicalads.io/proxy/click/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) [Ads by EthicalAds](https://www.ethicalads.io/advertisers/topics/backend-web/?ref=ea-text) ![](https://server.ethicalads.io/proxy/view/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) --- # Implement import - Nextcloud Deck * [Docs](https://deck.readthedocs.io/en/stable/) » * Developer documentation » * Import documentation » * Implement import * * * Implement import ---------------- * Create a new importer class extending `ABoardImportService` * Create a listener for event `BoardImportGetAllowedEvent` to enable your importer. > You can read more about listeners on [Nextcloud](https://docs.nextcloud.com/server/latest/developer_manual/basics/events.html?highlight=event#writing-a-listener) > doc. Example: class YourCustomImporterListener { public function handle(Event $event): void { if (!($event instanceof BoardImportGetAllowedEvent)) { return; } $event->getService()->addAllowedImportSystem([\ 'name' => YourCustomImporterService::$name,\ 'class' => YourCustomImporterService::class,\ 'internalName' => 'YourCustomImporter'\ ]); } } * Register your listener on your `Application` class like this: $dispatcher = $this->getContainer()->query(IEventDispatcher::class); $dispatcher->registerEventListener( BoardImportGetAllowedEvent::class, YourCustomImporterListener::class ); * Use the `lib/Service/Importer/Systems/TrelloJsonService.php` class as inspiration [ClickSend is fast, reliable and dev-friendly. Get your first message out in minutes **Test for free.**](https://server.ethicalads.io/proxy/click/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) [Ads by EthicalAds](https://www.ethicalads.io/advertisers/topics/backend-web/?ref=ea-text) ![](https://server.ethicalads.io/proxy/view/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) --- # Class diagram - Nextcloud Deck * [Docs](https://deck.readthedocs.io/en/latest/) » * Developer documentation » * Import documentation » * Class diagram * * * Import class diagram -------------------- Importing boards to the Deck implements the class diagram below. > **NOTE**: When making any changes to the structure of the classes or implementing import from other sources, edit the `BoardImport.yuml` file ![Screenshot](https://deck.readthedocs.io/en/latest/resources/BoardImport.svg) [ClickSend is fast, reliable and dev-friendly. Get your first message out in minutes **Test for free.**](https://server.ethicalads.io/proxy/click/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) [Ads by EthicalAds](https://www.ethicalads.io/advertisers/topics/backend-web/?ref=ea-text) ![](https://server.ethicalads.io/proxy/view/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) --- # Data structure - Nextcloud Deck * [Docs](https://deck.readthedocs.io/en/stable/) » * Developer documentation » * Data structure * * * Database structure ------------------ Deck stores most of its data inside of the database. The structure and relationships between entities is documented in the following ER diagram: ![Screenshot](https://deck.readthedocs.io/en/stable/resources/er-diagram.jpg) [ClickSend is fast, reliable and dev-friendly. Get your first message out in minutes **Test for free.**](https://server.ethicalads.io/proxy/click/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) [Ads by EthicalAds](https://www.ethicalads.io/advertisers/topics/backend-web/?ref=ea-text) ![](https://server.ethicalads.io/proxy/view/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) --- # REST API - Nextcloud Deck * [Docs](https://deck.readthedocs.io/en/stable/) » * API documentation » * REST API * * * The REST API provides access for authenticated users to their data inside the Deck app. To get a better understanding of Decks data models and their relations, please have a look at the [data structure](https://deck.readthedocs.io/en/stable/structure/) documentation. Prerequisites ============= * All requests require a `OCS-APIRequest` HTTP header to be set to `true` and a `Content-Type` of `application/json`. * The API is located at https://nextcloud.local/index.php/apps/deck/api/v1.0 * All request parameters are required, unless otherwise specified Naming ------ * Board is the project like grouping of tasks that can be shared to different users and groups * Stack is the grouping of cards which is rendered in vertical columns in the UI * Card is the representation of a single task * Labels are defined on a board level and can be assigned to any number of cards Global responses ---------------- ### 400 Bad request In case the request is invalid, e.g. because a parameter is missing or an invalid value has been transmitted, a 400 error will be returned: { "status": 400, "message": "title must be provided" } ### 403 Permission denied In any case a user doesn't have access to a requested entity, a 403 error will be returned: { "status": 403, "message": "Permission denied" } Formats ------- ### Date Datetime values in request data need to be provided in ISO-8601. Example: 2020-01-20T09:52:43+00:00 Headers ------- ### If-Modified-Since Some index endpoints support limiting the result set to entries that have been changed since the given time. The supported date formats are: * IMF-fixdate: `Sun, 03 Aug 2019 10:34:12 GMT` * (obsolete) RFC 850: `Sunday, 03-Aug-19 10:34:12 GMT` * (obsolete) ANSI C asctime(): `Sun Aug 3 10:34:12 2019` It is highly recommended to only use the IMF-fixdate format. Note that according to [RFC2616](https://tools.ietf.org/html/rfc2616#section-3.3) all HTTP date/time stamps MUST be represented in Greenwich Mean Time (GMT), without exception. Example curl request: curl -u admin:admin -X GET \ 'http://localhost:8000/index.php/apps/deck/api/v1.0/boards/2/stacks' \ -H "OCS-APIRequest: true" \ -H "If-Modified-Since: Mon, 05 Nov 2018 09:28:00 GMT" ### ETag An ETag header is returned in order to determine if further child elements have been updated for the following endpoints: * Fetch all user board `GET /api/v1.0/boards` * Fetch a single board `GET /api/v1.0/boards/{boardId}` * Fetch all stacks of a board `GET /api/v1.0/boards/{boardId}/stacks` * Fetch a single stacks of a board `GET /api/v1.0/boards/{boardId}/stacks/{stackId}` * Fetch a single card of a board `GET /api/v1.0/boards/{boardId}/stacks/{stackId}/cards/{cardId}` * Fetch attachments of a card `GET /api/v1.0/boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments` If a `If-None-Match` header is provided and the requested element has not changed a `304` Not Modified response will be returned. Changes of child elements will propagate to their parents and also cause an update of the ETag which will be useful for determining if a sync is necessary on any client integration side. As an example, if a label is added to a card, the ETag of all related entities (the card, stack and board) will change. If available the ETag will also be part of JSON response objects as shown below for a card: { "id": 81, "ETag": "bdb10fa2d2aeda092a2b6b469454dc90", "title": "Test card" } Changelog ========= API version 1.0 --------------- * Deck >=1.0.0: The maximum length of the card title has been extended from 100 to 255 characters * Deck >=1.0.0: The API will now return a 400 Bad request response if the length limitation of a board, stack or card title is exceeded API version 1.1 --------------- This API version has become available with **Deck 1.3.0**. * The maximum length of the card title has been extended from 100 to 255 characters * The API will now return a 400 Bad request response if the length limitation of a board, stack or card title is exceeded * The attachments API endpoints will return other attachment types than deck\_file * Prior to Deck version v1.3.0 (API v1.0), attachments were stored within deck. For this type of attachments `deck_file` was used as the default type of attachments * Starting with Deck version 1.3.0 (API v1.1) files are stored within the users regular Nextcloud files and the type `file` has been introduced for that API version 1.2 (unreleased) ---------------------------- * Endpoints for the new import functionality have been added: * [GET /boards/import/getSystems - Import a board](https://deck.readthedocs.io/en/stable/API/#get-boardsimportgetsystems-import-a-board) * [GET /boards/import/config/system/{schema} - Import a board](https://deck.readthedocs.io/en/stable/API/#get-boardsimportconfigsystemschema-import-a-board) * [POST /boards/import - Import a board](https://deck.readthedocs.io/en/stable/API/#post-boardsimport-import-a-board) Endpoints ========= Boards ------ ### GET /boards - Get a list of boards #### Headers The board list endpoint supports setting an `If-Modified-Since` header to limit the results to entities that are changed after the provided time. #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | details | Bool | **Optional** Enhance boards with details about labels, stacks and users | #### Response ##### 200 Success Returns an array of board items [\ {\ "title": "Board title",\ "owner": {\ "primaryKey": "admin",\ "uid": "admin",\ "displayname": "Administrator"\ },\ "color": "ff0000",\ "archived": false,\ "labels": [],\ "acl": [],\ "permissions": {\ "PERMISSION_READ": true,\ "PERMISSION_EDIT": true,\ "PERMISSION_MANAGE": true,\ "PERMISSION_SHARE": true\ },\ "users": [],\ "shared": 0,\ "deletedAt": 0,\ "id": 10,\ "lastModified": 1586269585,\ "settings": {\ "notify-due": "off",\ "calendar": true\ }\ }\ ] ### POST /boards - Create a new board #### Request body | Parameter | Type | Description | | --- | --- | --- | | title | String | The title of the new board, maximum length is limited to 100 characters | | color | String | The hexadecimal color of the new board (e.g. FF0000) | { "title": "Board title", "color": "ff0000" } #### Response ##### 200 Success { "title": "Board title", "owner": { "primaryKey": "admin", "uid": "admin", "displayname": "Administrator" }, "color": "ff0000", "archived": false, "labels": [\ {\ "title": "Finished",\ "color": "31CC7C",\ "boardId": 10,\ "cardId": null,\ "id": 37\ },\ {\ "title": "To review",\ "color": "317CCC",\ "boardId": 10,\ "cardId": null,\ "id": 38\ },\ {\ "title": "Action needed",\ "color": "FF7A66",\ "boardId": 10,\ "cardId": null,\ "id": 39\ },\ {\ "title": "Later",\ "color": "F1DB50",\ "boardId": 10,\ "cardId": null,\ "id": 40\ }\ ], "acl": [], "permissions": { "PERMISSION_READ": true, "PERMISSION_EDIT": true, "PERMISSION_MANAGE": true, "PERMISSION_SHARE": true }, "users": [], "deletedAt": 0, "id": 10, "lastModified": 1586269585 } ##### 403 Forbidden A 403 response might be returned if the users ability to create new boards has been disabled by the administrator. For checking this before, see the `canCreateBoards` value in the [Nextcloud capabilties](https://deck.readthedocs.io/en/stable/API-Nextcloud/) . ### GET /boards/{boardId} - Get board details #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board to fetch | #### Response ##### 200 Success { "title": "Board title", "owner": { "primaryKey": "admin", "uid": "admin", "displayname": "Administrator" }, "color": "ff0000", "archived": false, "labels": [\ {\ "title": "Finished",\ "color": "31CC7C",\ "boardId": "10",\ "cardId": null,\ "id": 37\ },\ {\ "title": "To review",\ "color": "317CCC",\ "boardId": "10",\ "cardId": null,\ "id": 38\ },\ {\ "title": "Action needed",\ "color": "FF7A66",\ "boardId": "10",\ "cardId": null,\ "id": 39\ },\ {\ "title": "Later",\ "color": "F1DB50",\ "boardId": "10",\ "cardId": null,\ "id": 40\ }\ ], "acl": [], "permissions": { "PERMISSION_READ": true, "PERMISSION_EDIT": true, "PERMISSION_MANAGE": true, "PERMISSION_SHARE": true }, "users": [\ {\ "primaryKey": "admin",\ "uid": "admin",\ "displayname": "Administrator"\ }\ ], "deletedAt": 0, "id": 10 } ### PUT /boards/{boardId} - Update board details #### Request body | Parameter | Type | Description | | --- | --- | --- | | title | String | The title of the board, maximum length is limited to 100 characters | | color | String | The hexadecimal color of the board (e.g. FF0000) | | archived | Bool | Whether or not this board should be archived. | { "title": "Board title", "color": "ff0000", "archived": false } #### Response ##### 200 Success ### DELETE /boards/{boardId} - Delete a board #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board to fetch | #### Response ##### 200 Success ### POST /boards/{boardId}/undo\_delete - Restore a deleted board #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board to fetch | #### Response ##### 200 Success ### POST /boards/{boardId}/acl - Add new acl rule #### Request body | Parameter | Type | Description | | --- | --- | --- | | type | Integer | Type of the participant | | participant | String | The uid of the participant | | permissionEdit | Bool | Setting if the participant has edit permissions | | permissionShare | Bool | Setting if the participant has sharing permissions | | permissionManage | Bool | Setting if the participant has management permissions | ##### Supported participant types: * 0 User * 1 Group * 7 Circle #### Response ##### 200 Success [{\ "participant": {\ "primaryKey": "userid",\ "uid": "userid",\ "displayname": "User Name"\ },\ "type": 0,\ "boardId": 1,\ "permissionEdit": true,\ "permissionShare": false,\ "permissionManage": true,\ "owner": false,\ "id": 1\ }] ### PUT /boards/{boardId}/acl/{aclId} - Update an acl rule #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | permissionEdit | Bool | Setting if the participant has edit permissions | | permissionShare | Bool | Setting if the participant has sharing permissions | | permissionManage | Bool | Setting if the participant has management permissions | #### Response ##### 200 Success ### DELETE /boards/{boardId}/acl/{aclId} - Delete an acl rule #### Response ##### 200 Success Stacks ------ ### GET /boards/{boardId}/stacks - Get stacks #### Headers The board list endpoint supports setting an `If-Modified-Since` header to limit the results to entities that are changed after the provided time. #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board to fetch | #### Response [\ {\ "title": "ToDo",\ "boardId": 2,\ "deletedAt": 0,\ "lastModified": 1541426139,\ "cards": [...],\ "order": 999,\ "id": 4\ }\ ] ##### 200 Success ### GET /boards/{boardId}/stacks/archived - Get list of archived stacks #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board to fetch | #### Response [\ {\ "title": "ToDo",\ "boardId": 2,\ "deletedAt": 0,\ "lastModified": 1541426139,\ "cards": [...],\ "order": 999,\ "id": 4\ }\ ] ##### 200 Success ### GET /boards/{boardId}/stacks/{stackId} - Get stack details #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the stack belongs to | | stackId | Integer | The id of the stack | #### Response ##### 200 Success ### POST /boards/{boardId}/stacks - Create a new stack #### Request body | Parameter | Type | Description | | --- | --- | --- | | title | String | The title of the new stack, maximum length is limited to 100 characters | | order | Integer | Order for sorting the stacks | #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board to fetch | #### Response ##### 200 Success ### PUT /boards/{boardId}/stacks/{stackId} - Update stack details #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the stack belongs to | | stackId | Integer | The id of the stack | #### Request body | Parameter | Type | Description | | --- | --- | --- | | title | String | The title of the stack, maximum length is limited to 100 characters | | order | Integer | Order for sorting the stacks | #### Response ##### 200 Success ### DELETE /boards/{boardId}/stacks/{stackId} - Delete a stack #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the stack belongs to | | stackId | Integer | The id of the stack | #### Response ##### 200 Success Cards ----- ### GET /boards/{boardId}/stacks/{stackId}/cards/{cardId} - Get card details #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | #### Response ##### 200 Success ### POST /boards/{boardId}/stacks/{stackId}/cards - Create a new card #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | #### Request body | Parameter | Type | Description | | --- | --- | --- | | title | String | The title of the card, maximum length is limited to 255 characters | | type | String | Type of the card (for later use) use 'plain' for now | | order | Integer | Order for sorting the stacks | | description | String | _(optional)_ The markdown description of the card | | duedate | timestamp | _(optional)_ The duedate of the card or null | #### Response { "title":"Test", "description":null, "stackId":6, "type":"plain", "lastModified":1541528026, "createdAt":1541528026, "labels":null, "assignedUsers":null, "attachments":null, "attachmentCount":null, "owner":"admin", "order":999, "archived":false, "duedate": "2019-12-24T19:29:30+00:00", "deletedAt":0, "commentsUnread":0, "id":10, "overdue":0 } ##### 200 Success ### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId} - Update card details #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | #### Request data | Parameter | Type | Description | | --- | --- | --- | | title | String | The title of the card, maximum length is limited to 255 characters | | description | String | The markdown description of the card | | type | String | Type of the card (for later use) use 'plain' for now | | order | Integer | Order for sorting the stacks | | duedate | timestamp | The ISO-8601 formatted duedate of the card or null | { "title": "Test card", "description": "A card description", "type": "plain", "order": 999, "duedate": "2019-12-24T19:29:30+00:00", } #### Response ##### 200 Success ### DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId} - Delete a card #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | #### Response ##### 200 Success ### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignLabel - Assign a label to a card #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | #### Request data | Parameter | Type | Description | | --- | --- | --- | | labelId | Integer | The label id to assign to the card | | \#### Response | | | ##### 200 Success ### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/removeLabel - Remove a label to a card #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | #### Request data | Parameter | Type | Description | | --- | --- | --- | | labelId | Integer | The label id to remove to the card | #### Response ##### 200 Success ### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignUser - Assign a user to a card #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | #### Request data | Parameter | Type | Description | | --- | --- | --- | | userId | String | The user id to assign to the card | #### Response ##### 200 Success { "id": 3, "participant": { "primaryKey": "admin", "uid": "admin", "displayname": "admin" }, "cardId": 1 } ##### 400 Bad request { "status": 400, "message": "The user is already assigned to the card" } The request can fail with a bad request response for the following reasons: - Missing or wrongly formatted request parameters - The user is already assigned to the card - The user is not part of the board ### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unassignUser - Unassign a user from a card #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | #### Request data | Parameter | Type | Description | | --- | --- | --- | | userId | String | The user id to unassign from the card | #### Response ##### 200 Success ### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/reorder - Change the sorting order of a card #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | #### Request data | Parameter | Type | Description | | --- | --- | --- | | order | Integer | The position in the stack where the card should be moved to | | stackId | Integer | The id of the stack where the card should be moved to | #### Response ##### 200 Success Labels ------ ### GET /boards/{boardId}/labels/{labelId} - Get label details #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the label belongs to | | labelId | Integer | The id of the label | #### Response ##### 200 Success { "title": "Abgeschlossen", "color": "31CC7C", "boardId": "2", "cardId": null, "id": 5 } ### POST /boards/{boardId}/labels - Create a new label #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the label belongs to | #### Request data { "title": "Finished", "color": "31CC7C" } #### Response ##### 200 Success ### PUT /boards/{boardId}/labels/{labelId} - Update label details #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the label belongs to | | labelId | Integer | The id of the label | #### Request data { "title": "Finished", "color": "31CC7C" } #### Response ##### 200 Success ### DELETE /boards/{boardId}/labels/{labelId} - Delete a label #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the label belongs to | | labelId | Integer | The id of the label | #### Response ##### 200 Success Attachments ----------- ### GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments - Get a list of attachments #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | #### Response ##### 200 Success [\ {\ "cardId": 5,\ "type": "deck_file",\ "data": "6DADC2C69F4.eml",\ "lastModified": 1541529048,\ "createdAt": 1541529048,\ "createdBy": "admin",\ "deletedAt": 0,\ "extendedData": {\ "filesize": 922258,\ "mimetype": "application/octet-stream",\ "info": {\ "dirname": ".",\ "basename": "6DADC2C69F4.eml",\ "extension": "eml",\ "filename": "6DADC2C69F4"\ }\ },\ "id": 6\ }\ ] ### GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Get the attachment file #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the attachment belongs to | | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | #### Response ##### 200 Success ### POST /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments - Upload an attachment #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the attachment belongs to | | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | #### Request data | Parameter | Type | Description | | --- | --- | --- | | type | String | The type of the attachement | | file | Binary | File data to add as an attachment | * Prior to Deck version v1.3.0 (API v1.0), attachments were stored within deck. For this type of attachments `deck_file` was used as the default type of attachments * Starting with Deck version 1.3.0 (API v1.1) files are stored within the users regular Nextcloud files and the type `file` has been introduced for that #### Response ##### 200 Success ### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Update an attachment #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the attachment belongs to | | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | #### Request data | Parameter | Type | Description | | --- | --- | --- | | type | String | The type of the attachement | | file | Binary | File data to add as an attachment | For now only `deck_file` is supported as an attachment type. #### Response ##### 200 Success ### DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Delete an attachment #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the attachment belongs to | | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | #### Response ##### 200 Success ### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}/restore - Resore a deleted attachment #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the board the attachment belongs to | | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | #### Response ##### 200 Success ### GET /boards/import/getSystems - Import a board #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | system | Integer | The system name. Example: trello | #### Response Make a request to see the json schema of system { } ### GET /boards/import/config/system/{schema} - Import a board #### Request parameters #### Response [\ "trello"\ ] ### POST /boards/import - Import a board #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | system | string | The allowed name of system to import from | | config | Object | The config object (JSON) | | data | Object | The data object to import (JSON) | #### Response ##### 200 Success OCS API ======= The following endpoints are available through the Nextcloud OCS endpoint, which is available at `/ocs/v2.php/apps/deck/api/v1.0/`. This has the benefit that both the web UI as well as external integrations can use the same API. Config ------ Deck stores user and app configuration values globally and per board. The GET endpoint allows to fetch the current global configuration while board settings will be exposed through the board element on the regular API endpoints. ### GET /api/v1.0/config - Fetch app configuration values #### Response | Config key | Description | | --- | --- | | calendar | Determines if the calendar/tasks integration through the CalDAV backend is enabled for the user (boolean) | | cardDetailsInModal | Determines if the bigger view is used (boolean) | | cardIdBadge | Determines if the ID badges are displayed on cards (boolean) | | groupLimit | Determines if creating new boards is limited to certain groups of the instance. The resulting output is an array of group objects with the id and the displayname (Admin only) | { "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": { "calendar": true, "cardDetailsInModal": true, "cardIdBadge": true, "groupLimit": [\ {\ "id": "admin",\ "displayname": "admin"\ }\ ] } } } ### POST /api/v1.0/config/{id}/{key} - Set a config value #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | id | Integer | The id of the board | | key | String | The config key to set, prefixed with `board:{boardId}:` for board specific settings | | value | String | The value that should be stored for the config key | ##### Board configuration | Key | Value | | --- | --- | | notify-due | `off`, `assigned` or `all` | | calendar | Boolean | | cardDetailsInModal | Boolean | | cardIdBadge | Boolean | #### Example request curl -X POST 'https://admin:admin@nextcloud.local/ocs/v2.php/apps/deck/api/v1.0/config/calendar' -H 'Accept: application/json' -H "Content-Type: application/json" -H 'OCS-APIRequest: true' --data-raw '{"value":false}' { "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": false } } Comments -------- ### GET /cards/{cardId}/comments - List comments #### Request parameters string $cardId, int $limit = 20, int $offset = 0 | Parameter | Type | Description | | --- | --- | --- | | cardId | Integer | The id of the card | | limit | Integer | The maximum number of comments that should be returned, defaults to 20 | | offset | Integer | The start offset used for pagination, defaults to 0 | curl 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' #### Response A list of comments will be provided under the `ocs.data` key. If no or no more comments are available the list will be empty. ##### 200 Success { "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": [\ {\ "id": 175,\ "objectId": 12,\ "message": "This is a comment with a mention to @alice",\ "actorId": "admin",\ "actorType": "users",\ "actorDisplayName": "Administrator",\ "creationDateTime": "2020-03-10T10:23:07+00:00",\ "mentions": [\ {\ "mentionId": "alice",\ "mentionType": "user",\ "mentionDisplayName": "alice"\ }\ ]\ }\ ] } } In case a comment is marked as a reply to another comment object, the parent comment will be added as `replyTo` entry to the response. Only the next parent node is added, nested replies are not exposed directly. [\ {\ "id": 175,\ "objectId": 12,\ "message": "This is a comment with a mention to @alice",\ "actorId": "admin",\ "actorType": "users",\ "actorDisplayName": "Administrator",\ "creationDateTime": "2020-03-10T10:23:07+00:00",\ "mentions": [\ {\ "mentionId": "alice",\ "mentionType": "user",\ "mentionDisplayName": "alice"\ }\ ],\ "replyTo": {\ "id": 175,\ "objectId": 12,\ "message": "This is a comment with a mention to @alice",\ "actorId": "admin",\ "actorType": "users",\ "actorDisplayName": "Administrator",\ "creationDateTime": "2020-03-10T10:23:07+00:00",\ "mentions": [\ {\ "mentionId": "alice",\ "mentionType": "user",\ "mentionDisplayName": "alice"\ }\ ]\ }\ }\ ] ### POST /cards/{cardId}/comments - Create a new comment #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | cardId | Integer | The id of the card | | message | String | The message of the comment, maximum length is limited to 1000 characters | | parentId | Integer | _(optional)_ The start offset used for pagination, defaults to null | Mentions will be parsed by the server. The server will return a list of mentions in the response to this request as shown below. curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' -H 'Content-Type: application/json;charset=utf-8' --data '{"message":"My message to @bob","parentId":null}' #### Response A list of comments will be provided under the `ocs.data` key. If no or no more comments are available the list will be empty. ##### 200 Success { "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": { "id": "177", "objectId": "13", "message": "My message to @bob", "actorId": "admin", "actorType": "users", "actorDisplayName": "Administrator", "creationDateTime": "2020-03-10T10:30:17+00:00", "mentions": [\ {\ "mentionId": "bob",\ "mentionType": "user",\ "mentionDisplayName": "bob"\ }\ ] } } } ##### 400 Bad request A bad request response is returned if invalid input values are provided. The response message will contain details about which part was not valid. ##### 404 Not found A not found response might be returned if: - The card for the given cardId could not be found - The parent comment could not be found ### PUT /cards/{cardId}/comments/{commentId} - Update a comment #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | cardId | Integer | The id of the card | | commentId | Integer | The id of the comment | | message | String | The message of the comment, maximum length is limited to 1000 characters | Mentions will be parsed by the server. The server will return a list of mentions in the response to this request as shown below. Updating comments is limited to the current user being the same as the comment author specified in the `actorId` of the comment. curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' -H 'Content-Type: application/json;charset=utf-8' --data '{"message":"My message"}' #### Response A list of comments will be provided under the `ocs.data` key. If no or no more comments are available the list will be empty. ##### 200 Success { "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": { "id": "177", "objectId": "13", "message": "My message", "actorId": "admin", "actorType": "users", "actorDisplayName": "Administrator", "creationDateTime": "2020-03-10T10:30:17+00:00", "mentions": [] } } } ##### 400 Bad request A bad request response is returned if invalid input values are provided. The response message will contain details about which part was not valid. ##### 404 Not found A not found response might be returned if: - The card for the given cardId could not be found - The comment could not be found ### DELETE /cards/{cardId}/comments/{commentId} - Delete a comment #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | cardId | Integer | The id of the card | | commentId | Integer | The id of the comment | Deleting comments is limited to the current user being the same as the comment author specified in the `actorId` of the comment. curl -X DELETE 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' -H 'Content-Type: application/json;charset=utf-8' #### Response A list of comments will be provided under the `ocs.data` key. If no or no more comments are available the list will be empty. ##### 200 Success { "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": [] } } ##### 400 Bad request A bad request response is returned if invalid input values are provided. The response message will contain details about which part was not valid. ##### 404 Not found A not found response might be returned if: - The card for the given cardId could not be found - The comment could not be found Sessions -------- ### PUT /session/create - creates a new session #### Request parameters | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the opened board | curl -X PUT 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session/create' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' \ -H 'Content-Type: application/json;charset=utf-8' \ --data '{"boardId":1}' #### Response ##### 200 Success { "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": { "token": "+zcJHf4rC6dobVSbuNa3delkCSfTW8OvYWTyLFvSpIv80FjtgLIj0ARlxspsazNQ" } } } ### POST /session/sync - notifies the server, that the session is still open #### Request body | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the opened board | | token | String | The session token from the /sessions/create response | curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session/create' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' \ -H 'Content-Type: application/json;charset=utf-8' \ --data '{"boardId":1, "token":"X3DyyoFslArF0t0NBZXzZXzcy8feoX/OEytSNXZtPg9TpUgO5wrkJ38IW3T/FfpV"}' #### Response ##### 200 Success { "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": [] } } ##### 404 Not Found the provided token is invalid or expired ### POST /session/close - closes the session #### Request body | Parameter | Type | Description | | --- | --- | --- | | boardId | Integer | The id of the opened board | | token | String | The session token from the /sessions/create response | curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session/close' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' \ -H 'Content-Type: application/json;charset=utf-8' \ --data '{"boardId":1, "token":"X3DyyoFslArF0t0NBZXzZXzcy8feoX/OEytSNXZtPg9TpUgO5wrkJ38IW3T/FfpV"}' #### Response ##### 200 Success { "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": [] } } [ClickSend is fast, reliable and dev-friendly. Get your first message out in minutes **Test for free.**](https://server.ethicalads.io/proxy/click/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) [Ads by EthicalAds](https://www.ethicalads.io/advertisers/topics/backend-web/?ref=ea-text) ![](https://server.ethicalads.io/proxy/view/10199/019d59c8-f82a-7b61-ba05-efbdf720f6ab/) ---