openapi: 3.2.0
info:
license:
name: GPL-v2.0
url: http://www.gnu.org/licenses/gpl-2.0.txt
version: 1.0.9
title: Bonita User Task API
description: "
\nDownload OpenAPI specification\nDownload Postman collection\n
\n\n
\n\nThe REST API lets you access the data with HTTP requests; it is useful when implementing rich web forms / pages for a good user experience.\n\nAn open source [java client](https://github.com/bonitasoft/bonita-java-client) is implemented above the HTTP API. It is available on [Maven central](https://search.maven.org/search?q=g:%22org.bonitasoft.web%22%20AND%20a:%22bonita-java-client%22).\n\nIf your application is using a technology other than Java, you can integrate it with the Bonita solution using the Web REST API. This API provides\naccess to all Bonita objects (like processes, tasks, users, connectors etc.), to execute operations on them (create, retrieve, update, delete).\nYou can use these operations to create a workflow with Bonita and integrate it into your application. The Bonita Engine remains responsible for executing\nthe workflow logic (connectors, gateways with conditions, messages, timers etc.) while your application gives access to the workflow.\nUsers can manage processes and tasks, and perform administrative activities.\n\n### API Extensions\n\nYou can create [Rest API Extensions](https://documentation.ofelia.com/bonita/latest/api/rest-api-extensions) to extend the Rest API by adding missing resources (not provided by the Rest API).\nIt is possible for an extension to interact with the engine (via the API) or with any other external service (for example a database, a directory, or a web service).\n\n### Create a resource\n\n| Request URL | `http://.../API/{API_name}/{resource_name}/ `|\n|:-|:-|\n| Request Method | POST|\n| Request Payload | an item in JSON|\n| Response | the same item in JSON, containing the values provided in the posted item, completed with default values and identifiers provided by Bonita Engine.|\n\n### Read a resource\n\n| Request URL | `http://.../API/{API_name}/{resource_name}/{id} `|\n|:-|:-|\n| Request Method | GET|\n| Response | an item in JSON|\n\nExample `http://.../API/identity/user/5 `\n\n#### Extend resource response\n\nOn some resources, in GET methods the `d` (deploy) URL query parameter can be used to extend the response objects. The value of this parameter consists of an attribute for which you want to make an extended request (called a deploy) and retrieve attributes of a linked resource.\nThis means that instead of retrieving the ID or a parent or referenced resource, you can retrieve the full object.\n\nFor example, when you retrieve a task, you can also retrieve the process definition attributes in addition to the process definition ID that is already part of the task resource.\nThe supported deploy values for a task include its process (d=processId).\n\nSpecifiy multiple `d` parameter to extend several resources. For instance, to retrieve the flow node of id 143 and the associated process, process instance and assigned user, call `/API/bpm/flowNode/143?d=processId&d=caseId&d=assigned_id`\n\n#### With compound identifier\n\nThe order of the identifier parts for each resource type is given in the table above.\n\n| Request URL | `http://.../API/{API_name}/{resource_name}/{id_part1}/{id_part2} `|\n|:-|:-|\n| Request Method | GET|\n| Response | an item in JSON|\n\nExample `http://.../API/identity/membership/5/12/24 `\n\n### Update a resource\n\n| Request URL | `http://.../API/{API_name}/{resource_name}/{id} `|\n|:-|:-|\n| Request Method | PUT|\n| Request Payload | a map in JSON containing the new values for the attributes you want to change.|\n| Response | the corresponding item in JSON with new values where you requested a modification|\n\nExample `http://.../API/identity/user/5`\n\n#### With compound identifier:\n\nResponse: the corresponding item in JSON with new values where you requested a modification.\n\n| Request URL | `http://.../API/{API_name}/{resource_name}/{id_part1}/{id_part2} `|\n|:-|:-|\n| Request Method | PUT|\n| Request Payload | ` a map in JSON containing the new values for the attributes you want to change `|\n| Response | ` the corresponding item in JSON with new values where you requested a modification`|\n\nExample\n`http://.../API/identity/membership/5/12/24 `\n\n### Delete resources\n\nUse the DELETE request to remove multiple resources.\n\n| Request URL | `http://.../API/{API_name}/{resource_name}/ `|\n|:-|:-|\n| Request Method | DELETE|\n| Request Payload | A list of identifiers in JSON, for example `[\"id1\",\"id2\",\"id3\"]`. Compound identifiers are separated by '/' characters.|\n| Response | `empty `|\n\nExample\n`http://.../API/identity/membership/ `\n\n### Search for a resource\n\nThe required object is specified with a set of filters in the request URL. The URL parameters must be URL-encoded.\n\nResults are returned in a paged list, so you have to specify the page (counting from zero), and the number of results per page (count), additionally you can define a sort key (order). You can see the total number of matching results in the HTTP response header Content-Range.\nIf you are searching for business data using a custom query, there must be a [count query in the BDM](https://documentation.ofelia.com/bonita/latest/data/define-and-deploy-the-bdm). If there is no count query, results from a custom query on business data cannot be paged properly (the header Content-Range will be absent).\nFor business data default queries, the count query is defined automatically.\n\nThe available filters are the attributes of the item plus some specific filters defined by each item.\n\n| Request URL | `http://.../API/{API_name}/{resource_name}?p={page}&c={count}&o={order}&s={query}&f={filter_name}={filter_value}&f=... `|\n|:-|:-|\n| Request Method | GET|\n| Response | an array of items in JSON|\n\nExample\n`/API/identity/user?p=0&c=10&o=firstname&s=test&f=manager_id=3`\n\nFor a GET method that retrieves more than one instance of a resource, you can specify the following request parameters:\n\n* p (Mandatory): index of the page to display\n* c (Mandatory): maximum number of elements to retrieve\n* o: order of presentation of values in response: must be either `attributeName ASC` or `attributeName DESC`. The final order parameter value must be URL encoded.\n* f: list of filters, specified as `attributeName=attributeValue`. To filter on more than one attribute, specify an f parameters for each attribute. The final filter parameter value must be URL encoded.\n The attributes you can filter on are specific to the resource.\n* s: search on name or search indexes. Before Bonita 2024.1, the matching policy depended on the configuration of [word-based search](https://documentation.ofelia.com/bonita/2023.2/api/using-list-and-search-methods#word_based_search).\n For example, if word-based search was enabled, `s=Valid` returned matches containing the string \"valid\" at the start of any word in the attribute value word,\n such as \"Valid address\", \"Not a valid address\", and \"Validated request\" but not \"Invalid request\".\n If word-based search was disabled, `s=Valid` returned matches containing the string \"valid\" at the start of the attribute value, such as \"Valid address\" or \"Validated request\" but not \"Not a valid address\" or \"Invalid request\".\n Since Bonita 2024.1, the search mode can no longer be configured and a \"like-based\" algorithm is used. This means all the matching records for which the search term occurs anywhere in a phrase or a word are returned.\n\n### Errors\n\nThe API uses standard HTTP status codes to indicate the success or failure of the API call.\n\nIf you get a `401` response code :\n - make sure that the cookies have been transfered with the call\n - make sure that the cookies transfered are the ones generated during the last sucessfull login call\n - if one of the PUT, DELETE or POST method is used, make sure that the `X-Bonita-API-Token` header is included\n - if the X-Bonita-API-Token header is included, make sure that the value is the same as the one of the cookie generated during the last login\n - Maybe a logout was issued or the session has expired; try to log in again, and re run the request with the new cookies and the new value for the `X-Bonita-API-Token` header.\n"
x-logo:
url: images/ofelia-logo.svg
backgroundColor: '#19465f'
altText: Bonita API
href: /
servers:
- url: http://localhost:8080/bonita
description: Sample url for a local development server.
security:
- bonita_auth: []
bonita_token: []
- bearer_auth: []
tags:
- name: UserTask
x-displayName: UserTask
description: UserTask
paths:
/API/bpm/userTask:
get:
tags:
- UserTask
summary: Finds UserTasks
description: 'Finds UserTasks with pagination params and filters
- can order on `id`
- can search on `displayName`
- can filter on `displayName`
'
operationId: searchUserTasks
parameters:
- $ref: '#/components/parameters/pageIndex'
- $ref: '#/components/parameters/pageCount'
- $ref: '#/components/parameters/pageFilter'
- $ref: '#/components/parameters/pageOrder'
- $ref: '#/components/parameters/pageSearch'
responses:
'200':
description: 'Success '
headers:
Content-Range:
schema:
type: integer
format: int64
description: The total number of matching items
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UserTask'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
5XX:
$ref: '#/components/responses/ServerError'
/API/bpm/userTask/{id}:
get:
tags:
- UserTask
summary: Finds the UserTask by ID
description: 'Returns the single UserTask for the given ID
'
operationId: getUserTaskById
parameters:
- description: ID of the UserTask to return
in: path
name: id
required: true
schema:
type: string
maxLength: 250
pattern: ^[A-Za-z0-9\_\-\.]{0,250}$
responses:
'200':
description: 'Success '
content:
application/json:
schema:
$ref: '#/components/schemas/UserTask'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
5XX:
$ref: '#/components/responses/ServerError'
put:
tags:
- UserTask
summary: Update the UserTask by ID
description: 'Update the UserTask for the given ID.
Fields that can be updated are `assigned_id` and `state`. The only value that can be set for the state is `skipped`. You only need to specify the fields that are to be updated.
'
operationId: updateUserTaskById
parameters:
- description: ID of the UserTask to return
in: path
name: id
required: true
schema:
type: string
maxLength: 250
pattern: ^[A-Za-z0-9\_\-\.]{0,250}$
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserTaskUpdateRequest'
description: Partial UserTask description
required: true
responses:
'200':
$ref: '#/components/responses/OK'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
5XX:
$ref: '#/components/responses/ServerError'
/API/bpm/userTask/{id}/contract:
get:
tags:
- UserTask
summary: Finds the Contract by UserTask ID
description: 'Returns the Contract for the given UserTask ID
'
operationId: getContractByUserTaskId
parameters:
- description: ID of the UserTask that has the Contract to return
in: path
name: id
required: true
schema:
type: string
maxLength: 250
pattern: ^[A-Za-z0-9\_\-\.]{0,250}$
responses:
'200':
description: 'Success '
content:
application/json:
schema:
$ref: '#/components/schemas/Contract'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
5XX:
$ref: '#/components/responses/ServerError'
/API/bpm/userTask/{id}/execution:
post:
tags:
- UserTask
summary: Execute the UserTask
description: 'Execute the UserTask. In order to execute a task, the task contract values have to be provided.
'
operationId: executeUserTask
parameters:
- name: id
description: ID of the UserTask to execute
in: path
required: true
schema:
type: string
maxLength: 250
pattern: ^[A-Za-z0-9\_\-\.]{0,250}$
- name: assign
description: if true, assign the task to the current user and execute the task
in: query
schema:
type: boolean
required: false
requestBody:
content:
application/json:
schema:
type: object
additionalProperties: true
example:
ticket_comment: this is a comment
description: A JSON object matching task contract. Execute a task providing correct contract values.
required: true
responses:
'204':
$ref: '#/components/responses/NoContent'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
5XX:
$ref: '#/components/responses/ServerError'
x-codegen-request-body-name: body
/API/bpm/userTask/{id}/context:
get:
tags:
- UserTask
summary: Finds the Context by UserTask ID
description: 'Returns the Context for the given UserTask ID
'
operationId: getContextByUserTaskId
parameters:
- description: ID of the UserTask that has the Context to return
in: path
name: id
required: true
schema:
type: string
maxLength: 250
pattern: ^[A-Za-z0-9\_\-\.]{0,250}$
responses:
'200':
description: 'Success '
content:
application/json:
schema:
type: object
additionalProperties: true
example:
myBusinessData_ref:
name: myBusinessData
type: com.company.model.BusinessObject1
link: API/bdm/businessData/com.company.model.BusinessObject1/2
storageId: 2
storageId_string: '2'
myDocument_ref:
id: 1
processInstanceId: 3
name: myDocument
author: 104
creationDate: 1434723950847
fileName: TestCommunity-1.0.bos
contentMimeType: null
contentStorageId: '1'
url: documentDownload?fileName=TestCommunity-1.0.bos&contentStorageId=1
description: ''
version: '1'
index: -1
contentFileName: TestCommunity-1.0.bos
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
5XX:
$ref: '#/components/responses/ServerError'
components:
schemas:
ContractConstraint:
type: object
properties:
name:
description: constraint name
type: string
expression:
description: constraint expression
type: string
explanation:
description: constraint explanation
type: string
inputNames:
type: array
items:
type: string
ContractInput:
type: object
properties:
description:
description: input description
type: string
name:
description: input name
type: string
multiple:
description: true if input contains multiple values
type: string
type:
$ref: '#/components/schemas/ContractInputType'
inputs:
type: array
items:
$ref: '#/components/schemas/ContractInput'
ContractInputType:
type: string
description: the contract input type (string)
enum:
- TEXT
- BOOLEAN
- DATE
- INTEGER
- DECIMAL
- BYTE_ARRAY
- FILE
- LONG
- LOCALDATE
- LOCALDATETIME
- OFFSETDATETIME
ActivityState:
type: string
description: the current state of the activity
enum:
- failed
- initializing
- ready
- executing
- completing
- completed
- waiting
- skipped
- cancelled
- aborted
- cancelling subtasks
- aborting activity with boundary
- completing activity with boundary
Contract:
type: object
properties:
constraints:
type: array
items:
$ref: '#/components/schemas/ContractConstraint'
inputs:
type: array
items:
$ref: '#/components/schemas/ContractInput'
AbstractTask:
type: object
properties:
id:
description: the task id
type: string
maxLength: 250
pattern: ^[A-Za-z0-9\_\-\.]{0,250}$
type:
description: the task type
type: string
name:
description: the task technical name
type: string
displayName:
description: the human readable task name
type: string
description:
description: the task description
type: string
displayDescription:
description: the human readable task description
type: string
state:
$ref: '#/components/schemas/ActivityState'
reached_state_date:
description: the date ('yyyy-MM-dd HH:mm:ss.SSS') when this task reached the current state for example '2014-10-17 16:05:42.626'
type: string
pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]) (2[0-3]|[01][0-9]):[0-5][0-9]:[0-5][0-9]$
last_update_date:
description: the date ('yyyy-MM-dd HH:mm:ss.SSS') when this task was last updated for example '2014-10-17 16:05:42.626)
type: string
pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]) (2[0-3]|[01][0-9]):[0-5][0-9]:[0-5][0-9]$
dueDate:
description: the date ('yyyy-MM-dd HH:mm:ss.SSS') when this task is due for example '2014-10-17 16:05:42.626'
type: string
pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]) (2[0-3]|[01][0-9]):[0-5][0-9]:[0-5][0-9]$
priority:
description: the priority (string) of the current task
type: string
processId:
description: the process definition id of the process instance which define this task
type: string
maxLength: 250
pattern: ^[A-Za-z0-9\_\-\.]{0,250}$
parentCaseId:
description: the immediate containing process instance id (case id)
type: string
maxLength: 250
pattern: ^[A-Za-z0-9\_\-\.]{0,250}$
parentTaskId:
description: the parent Task id
type: string
maxLength: 250
pattern: ^[A-Za-z0-9\_\-\.]{0,250}$
rootCaseId:
description: the top/root process instance id (case id). In case of an "event sub process" `parentCaseId` will the id of the process instance called while `rootCaseId` will be the one from the caller process instance
type: string
maxLength: 250
pattern: ^[A-Za-z0-9\_\-\.]{0,250}$
rootContainerId:
description: same as rootCaseId
type: string
maxLength: 250
pattern: ^[A-Za-z0-9\_\-\.]{0,250}$
executedBy:
description: the id of the user who performed this task. The task has to be a human task otherwise its value will be 0
type: string
maxLength: 250
pattern: ^[A-Za-z0-9\_\-\.]{0,250}$
executedBySubstitute:
description: the id of the user who did actually performed the task when it has been done in the name of someone else. Value is 0 otherwise
type: string
actorId:
description: the id of the actor that can execute this task null otherwise
type: string
maxLength: 250
pattern: ^[A-Za-z0-9\_\-\.]{0,250}$
assigned_id:
description: the user id that this task is assigned to or 0 if it is unassigned
type: string
maxLength: 250
pattern: ^[A-Za-z0-9\_\-\.]{0,250}$
assigned_date:
description: the date ('yyyy-MM-dd HH:mm:ss.SSS') when the current task was assigned for example '2014-10-17 16:05:42.626'
type: string
pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]) (2[0-3]|[01][0-9]):[0-5][0-9]:[0-5][0-9]$
isTerminal:
description: True if the task is the last one in a flow
type: boolean
example:
displayDescription: This is my subtask
executedBySubstitute: 1
processId: 8367255255370238000
parentCaseId: 1
state: ready
rootContainerId: 1
type: MANUAL_TASK
assigned_id: 1
assigned_date: '2014-12-01 17:39:53.784'
id: 40006
executedBy: 1
caseId: 1
priority: above_normal
actorId: 1
description: This is my subtask
name: My subtask
reached_state_date: '2014-12-01 17:39:53.784'
rootCaseId: 1
displayName: My subtask
parentTaskId: 40001
dueDate: '2014-12-25 00:00:00.000'
last_update_date: '2014-12-01 17:39:53.784'
UserTaskUpdateRequest:
type: object
properties:
state:
description: The UserTask state
type: string
assigned_id:
description: The id of the user assign to the UserTask
type: string
example:
assigned_id: '1'
state: skipped
UserTask:
allOf:
- $ref: '#/components/schemas/AbstractTask'
- type: object
description: An executable task that is performed by a user.
example:
displayDescription: ''
executedBySubstitute: 0
processId: 5826139717723008000
state: ready
rootContainerId: 1002
type: USER_TASK
assigned_id: null
assigned_date: ''
id: 20004
executedBy: 0
caseId: 1002
priority: normal
actorId: 102
description: ''
name: Analyse case
reached_state_date: '2014-09-05 11:11:30.808'
displayName: Analyse case
dueDate: '2014-09-05 12:11:30.775'
last_update_date: '2014-09-05 11:11:30.808'
Error:
type: object
additionalProperties: true
properties:
message:
type: string
description: The error message
exception:
type: string
description: The exception type
explanations:
description: Further details on the error
type: array
items:
type: string
responses:
ServerError:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: An unexpected error occured.
NotFound:
description: The resource for the specified ID was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Resource not found.
NoContent:
description: OK (no content).
BadRequest:
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Bad request
OK:
description: OK
Forbidden:
description: Forbidden, The request contained valid data and was understood by the server, but the server is refusing action.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Forbidden, The request contained valid data and was understood by the server, but the server is refusing action.
Unauthorized:
description: Authorization information is missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Unauthorized
parameters:
pageIndex:
description: index of the page to display
explode: true
in: query
name: p
example: '0'
required: true
schema:
type: integer
minimum: 0
default: 0
format: int32
style: form
pageOrder:
description: can order on attributes
explode: true
in: query
name: o
required: false
schema:
type: string
maxLength: 250
pattern: ^[A-Za-z0-9%]{0,250}$
style: form
example: myProp%20ASC
pageFilter:
description: can filter on attributes with the format f={filter\_name}={filter\_value} with the name/value pair as url encoded string.
explode: true
in: query
name: f
required: false
schema:
type: array
items:
type: string
maxLength: 250
pattern: ^[A-Za-z0-9%]{0,250}$
style: form
example: abc%3d123
pageSearch:
description: can search on attributes
explode: true
in: query
name: s
required: false
schema:
type: string
maxLength: 250
pattern: ^[A-Za-z0-9%]{0,250}$
style: form
pageCount:
description: maximum number of elements to retrieve
explode: true
in: query
name: c
example: '10'
required: true
schema:
type: integer
minimum: 1
default: 20
format: int32
style: form
securitySchemes:
bonita_auth:
name: JSESSIONID
description: 'To call the REST API, you must first log on with a user registered in the Engine database. Please refer to the __[Login API](#operation/login)__ operations section.
'
type: apiKey
in: cookie
bonita_token:
name: X-Bonita-API-Token
description: 'To call the REST API, you must first log on with a user registered in the Engine database. Please refer to the __[Login API](#operation/login)__ operations section.
'
type: apiKey
in: header
bearer_auth:
description: '
When Bonita runtime is configured for SSO with openID Connect it is possible To call the REST API directly with a Bearer Authorization header containing the access token.
'
type: http
scheme: bearer
x-tagGroups:
- name: Authentication
tags:
- Authentication
- PlatformAuthentication
- name: Application
tags:
- Application
- ApplicationMenu
- ApplicationPage
- FormMapping
- name: BDM
tags:
- BDM
- BusinessDataQuery
- Business Data Operations
- BDMAccessControl
- DataRetention
- name: BPM
tags:
- Activity
- ArchivedActivity
- HumanTask
- ManualTask
- Task
- UserTask
- ArchivedHumanTask
- ArchivedManualTask
- ArchivedTask
- ArchivedUserTask
- ActivityVariable
- ArchivedActivityVariable
- ProcessInstanceVariable
- ArchivedProcessInstanceVariable
- ProcessInstanceDocument
- ArchivedProcessInstanceDocument
- Actor
- ActorMember
- ProcessInstance
- ArchivedProcessInstance
- ProcessInstanceInfo
- ProcessInstanceComment
- ArchivedProcessInstanceComment
- Process
- Diagram
- ProcessInfo
- ProcessParameter
- ProcessResolutionProblem
- ProcessSupervisor
- ProcessConnectorDependency
- ConnectorFailure
- ConnectorInstance
- ArchivedConnectorInstance
- FlowNode
- ArchivedFlowNode
- Failure
- ArchivedFailure
- TimerEventTrigger
- Message
- Signal
- Delegation
- name: Custom user info
tags:
- CustomUserDefinition
- CustomUserValue
- CustomUser
- name: Identity
tags:
- ProfessionalContactData
- Group
- Membership
- Role
- User
- Authentication
- name: Platform
tags:
- PlatformAuthentication
- Platform
- License
- Information
- name: Portal
tags:
- Page
- Profile
- ProfileEntry
- ProfileMember
- Theme
- Upload
- name: System
tags:
- I18nlocale
- I18ntranslation
- Log
- Session
- Maintenance
- name: Other
tags:
- RestAPIextensions
- name: Upload
tags:
- FormFileUpload