= TASKANA RESTful API Documentation

== Overview

This is the REST documentation for http://taskana.pro)[TASKANA] - the world's first open source solution for Enterprise Task Management.

*For all Query Parameters:* +
Whenever a parameter is an array type, several values can be passed by declaring that parameter multiple times.

Whenever a parameter is a complex type, the attributes of the value-object can be passed as a json.
For example, a complex parameter with the name "complex-query-param" and attributes "attribute1" and "attribute2" would be specified in the following way: +
complex-query-param={"attribute1":"value1","attribute2":"value2"}

Whenever a parameter is a value-less type (e.g owner-is-null and current-user) it is expected to be defined without a value,
i.e., it should be specified as ?parameter and not ?parameter= or ?parameter=someValue

=== Hypermedia Support

NOTE: HATEOAS support is still in development.
Please have a look at example responses for each resource to determine the available links.

TASKANA uses the https://restfulapi.net/hateoas/)[HATEOAS] (Hypermedia as the Engine of Application State) REST constraint.
Most of our resources contain a `_links` section which contains navigation links.
Besides, helping to navigate through our REST API, the navigation links also encapsulate the API.
Using HATEOAS allows us to change some endpoints without modifying your frontend.

=== Errors

In order to support multilingual websites, TASKANA uses error codes to define which error occurred.
Additionally, an optional set of message variables, containing some technical information, is added, so that the website can describe the error with all details.

[%autowidth,width="100%"]
|===
| Status Code                 | Key                                              | Message Variables
| *400 BAD_REQUEST*           | CLASSIFICATION_SERVICE_LEVEL_MALFORMED           | serviceLevel, classificationKey, domain
| *400 BAD_REQUEST*           | CUSTOM_HOLIDAY_WRONG_FORMAT                      | customHoliday
| *400 BAD_REQUEST*           | DOMAIN_NOT_FOUND                                 | domain
| *400 BAD_REQUEST*           | INVALID_ARGUMENT                                 |
| *400 BAD_REQUEST*           | QUERY_PARAMETER_MALFORMED                        | malformedQueryParameters
| *400 BAD_REQUEST*           | TASK_INVALID_CALLBACK_STATE                      | taskId, taskCallbackState, requiredCallbackStates
| *400 BAD_REQUEST*           | TASK_INVALID_OWNER                               | taskId, currentUserId
| *400 BAD_REQUEST*           | TASK_INVALID_STATE                               | taskId, taskState, requiredTaskStates
| *403 FORBIDDEN*             | NOT_AUTHORIZED                                   | roles, currentUserId
| *403 FORBIDDEN*             | NOT_AUTHORIZED_ON_TASK_COMMENT                   | currentUserId, taskCommentId
| *403 FORBIDDEN*             | NOT_AUTHORIZED_ON_WORKBASKET_WITH_ID             | currentUserId, workbasketId, requiredPermissions
| *403 FORBIDDEN*             | NOT_AUTHORIZED_ON_WORKBASKET_WITH_KEY_AND_DOMAIN | currentUserId, workbasketKey, domain, requiredPermissions
| *404 NOT_FOUND*             | CLASSIFICATION_WITH_ID_NOT_FOUND                 | classificationId
| *404 NOT_FOUND*             | CLASSIFICATION_WITH_KEY_NOT_FOUND                | classificationKey, domain
| *404 NOT_FOUND*             | TASK_COMMENT_NOT_FOUND                           | taskCommentId
| *404 NOT_FOUND*             | TASK_NOT_FOUND                                   | taskId
| *404 NOT_FOUND*             | USER_NOT_FOUND                                   | userId
| *404 NOT_FOUND*             | WORKBASKET_WITH_ID_NOT_FOUND                     | workbasketId
| *404 NOT_FOUND*             | WORKBASKET_WITH_KEY_NOT_FOUND                    | workbasketKey, domain
| *409 CONFLICT*              | ATTACHMENT_ALREADY_EXISTS                        | attachmentId, taskId
| *409 CONFLICT*              | CLASSIFICATION_ALREADY_EXISTS                    | classificationKey, domain
| *409 CONFLICT*              | ENTITY_NOT_UP_TO_DATE                            | entityId
| *409 CONFLICT*              | TASK_ALREADY_EXISTS                              | externalTaskId
| *409 CONFLICT*              | USER_ALREADY_EXISTS                              | userID
| *409 CONFLICT*              | WORKBASKET_ACCESS_ITEM_ALREADY_EXISTS            | accessId, workbasketId
| *409 CONFLICT*              | WORKBASKET_ALREADY_EXISTS                        | workbasketKey, domain
| *409 CONFLICT*              | WORKBASKET_MARKED_FOR_DELETION                   | workbasketId
| *413 PAYLOAD_TOO_LARGE*     | PAYLOAD_TOO_LARGE                                |
| *423 LOCKED*                | CLASSIFICATION_IN_USE                            | classificationKey, domain
| *423 LOCKED*                | WORKBASKET_IN_USE                                | workbasketId
| *500 INTERNAL_SERVER_ERROR* | CONNECTION_AUTOCOMMIT_FAILED                     |
| *500 INTERNAL_SERVER_ERROR* | CONNECTION_NOT_SET                               |
| *500 INTERNAL_SERVER_ERROR* | CRITICAL_SYSTEM_ERROR                            |
| *500 INTERNAL_SERVER_ERROR* | DATABASE_UNSUPPORTED                             | databaseProductName
| *500 INTERNAL_SERVER_ERROR* | UNKNOWN_ERROR                                    |
|===

==== Errors

|====
| Message Variables        | Type
| accessId                 | String
| attachmentId             | String
| classificationId         | String
| classificationKey        | String
| currentUserId            | String
| customHoliday            | String
| databaseProductName      | String
| domain                   | String
| externalTaskId           | String
| historyEventId           | String
| malformedQueryParameters | MalformedQueryParameter[]
| requiredCallbackStates   | CallbackState[]
| requiredPermissions      | WorkbasketPermission[]
| requiredTaskStates       | TaskState[]
| roles                    | TaskanaRole[]
| taskCallbackState        | CallbackState
| taskCommentId            | String
| taskId                   | String
| taskState                | TaskState
| workbasketId             | String
| workbasketKey            | String
|====

== Task Resource

include::{snippets}/TaskControllerRestDocTest/createTaskDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/getSpecificTaskDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/getAllTasksDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/updateTaskDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/claimTaskDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/forceClaimTaskDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/selectAndClaimTaskDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/cancelClaimTaskDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/forceCancelClaimTaskDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/requestReviewTaskDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/forceRequestReviewTaskDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/requestChangesTaskDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/forceRequestChangesTaskDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/completeTaskDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/forceCompleteTaskDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/cancelTaskDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/terminateTaskDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/transferTaskDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/setTaskReadDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/deleteTaskDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/forceDeleteTaskDocTest/auto-section.adoc[]
include::{snippets}/TaskControllerRestDocTest/deleteTasksDocTest/auto-section.adoc[]

== Task Comment Resource

include::{snippets}/TaskCommentControllerRestDocTest/createTaskCommentDocTest/auto-section.adoc[]
include::{snippets}/TaskCommentControllerRestDocTest/getSpecificTaskCommentDocTest/auto-section.adoc[]
include::{snippets}/TaskCommentControllerRestDocTest/getAllTaskCommentsForSpecificTaskDocTest/auto-section.adoc[]
include::{snippets}/TaskCommentControllerRestDocTest/updateTaskCommentDocTest/auto-section.adoc[]
include::{snippets}/TaskCommentControllerRestDocTest/deleteTaskCommentDocTest/auto-section.adoc[]

== Classification Resource

include::{snippets}/ClassificationControllerRestDocTest/createClassificationDocTest/auto-section.adoc[]
include::{snippets}/ClassificationControllerRestDocTest/getClassificationDocTest/auto-section.adoc[]
include::{snippets}/ClassificationControllerRestDocTest/getAllClassificationsDocTest/auto-section.adoc[]
include::{snippets}/ClassificationControllerRestDocTest/updateClassificationDocTest/auto-section.adoc[]
include::{snippets}/ClassificationControllerRestDocTest/deleteClassificationDocTest/auto-section.adoc[]

== Workbasket Resource

include::{snippets}/WorkbasketControllerRestDocTest/createWorkbasketDocTest/auto-section.adoc[]
include::{snippets}/WorkbasketControllerRestDocTest/getSpecificWorkbasketDocTest/auto-section.adoc[]
include::{snippets}/WorkbasketControllerRestDocTest/getAllWorkbasketsDocTest/auto-section.adoc[]
include::{snippets}/WorkbasketControllerRestDocTest/getAllWorkbasketAccessItemsDocTest/auto-section.adoc[]
include::{snippets}/WorkbasketControllerRestDocTest/getAllWorkbasketDistributionTargetsDocTest/auto-section.adoc[]
include::{snippets}/WorkbasketControllerRestDocTest/updateWorkbasketDocTest/auto-section.adoc[]
include::{snippets}/WorkbasketControllerRestDocTest/removeWorkbasketAsDistributionTargetDocTest/auto-section.adoc[]
include::{snippets}/WorkbasketControllerRestDocTest/setAllWorkbasketAccessItemsDocTest/auto-section.adoc[]
include::{snippets}/WorkbasketControllerRestDocTest/setAllDistributionTargetsDocTest/auto-section.adoc[]
include::{snippets}/WorkbasketControllerRestDocTest/deleteWorkbasketDocTest/auto-section.adoc[]

== Workbasket Access Item Resource

include::{snippets}/WorkbasketAccessItemControllerRestDocTest/getWorkbasketAccessItemsDocTest/auto-section.adoc[]
include::{snippets}/WorkbasketAccessItemControllerRestDocTest/removeWorkbasketAccessItemsDocTest/auto-section.adoc[]

== Monitoring Resources

include::{snippets}/MonitorControllerRestDocTest/computeWorkbasketReportDocTest/auto-section.adoc[]
include::{snippets}/MonitorControllerRestDocTest/computeWorkbasketPriorityReportDocTest/auto-section.adoc[]
include::{snippets}/MonitorControllerRestDocTest/computeClassificationCategoryReportDocTest/auto-section.adoc[]
include::{snippets}/MonitorControllerRestDocTest/computeClassificationReportDocTest/auto-section.adoc[]
include::{snippets}/MonitorControllerRestDocTest/computeDetailedClassificationReportDocTest/auto-section.adoc[]
include::{snippets}/MonitorControllerRestDocTest/computeTaskCustomFieldValueReportDocTest/auto-section.adoc[]
include::{snippets}/MonitorControllerRestDocTest/computeTaskStatusReportDocTest/auto-section.adoc[]
include::{snippets}/MonitorControllerRestDocTest/computeTimestampReportDocTest/auto-section.adoc[]

== Access Id Resource

include::{snippets}/AccessIdControllerRestDocTest/searchForAccessIdDocTest/auto-section.adoc[]
include::{snippets}/AccessIdControllerRestDocTest/getGroupsForAccessIdDocTest/auto-section.adoc[]
include::{snippets}/AccessIdControllerRestDocTest/searchUsersByNameOrAccessIdForRoleTest/auto-section.adoc[]

== User Resource

include::{snippets}/UserControllerRestDocTest/getUserDocTest/auto-section.adoc[]
include::{snippets}/UserControllerRestDocTest/getUsersDocTest/auto-section.adoc[]
include::{snippets}/UserControllerRestDocTest/createUserDocTest/auto-section.adoc[]
include::{snippets}/UserControllerRestDocTest/updateUserDocTest/auto-section.adoc[]
include::{snippets}/UserControllerRestDocTest/deleteUserDocTest/auto-section.adoc[]

== Configuration Resources

include::{snippets}/TaskanaEngineControllerRestDocTest/getAllDomainsDocTest/auto-section.adoc[]
include::{snippets}/TaskanaEngineControllerRestDocTest/getClassificationCategoriesDocTest/auto-section.adoc[]
include::{snippets}/TaskanaEngineControllerRestDocTest/getClassificationTypesDocTest/auto-section.adoc[]
include::{snippets}/TaskanaEngineControllerRestDocTest/getClassificationCategoriesByTypeMapDocTest/auto-section.adoc[]
include::{snippets}/TaskanaEngineControllerRestDocTest/getCurrentUserInfoDocTest/auto-section.adoc[]
include::{snippets}/TaskanaEngineControllerRestDocTest/getHistoryProviderIsEnabledDocTest/auto-section.adoc[]
include::{snippets}/TaskanaEngineControllerRestDocTest/getCurrentVersionDocTest/auto-section.adoc[]
include::{snippets}/TaskanaEngineControllerRestDocTest/getCustomConfigurationAttributesDocTest/auto-section.adoc[]
include::{snippets}/TaskanaEngineControllerRestDocTest/setCustomConfigurationAttributesDocTest/auto-section.adoc[]

== Import / Export

include::{snippets}/ClassificationDefinitionControllerRestDocTest/exportClassificationDefinitionsDocTest/auto-section.adoc[]
include::{snippets}/ClassificationDefinitionControllerRestDocTest/importClassificationDefinitionsDocTest/auto-section.adoc[]
include::{snippets}/WorkbasketDefinitionControllerRestDocTest/exportWorkbasketDefinitionsDocTest/auto-section.adoc[]
include::{snippets}/WorkbasketDefinitionControllerRestDocTest/importWorkbasketDefinitionDocTest/auto-section.adoc[]
