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 Process Instance 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: ProcessInstance x-displayName: ProcessInstance description: ProcessInstance paths: /API/bpm/case: get: tags: - ProcessInstance summary: Finds ProcessInstances description: 'Finds ProcessInstances with pagination params and filters You can filter on: * `processDefinitionId`: The process definition ID * `rootCaseId`: the root process instance ID (since version 10.3 - 2025.1) * `name`: the process name * `started_by`: the ID of the user who started the process * `team_manager_id`: allow to retrieve the process instances in which all users with this manager ID ar involved) * `supervisor_id`: allow the retrived the process instances of all processes the user with this ID is supervisor of) beware you cannot use team_manager_id and supervisor_id at the same time * `searchIndex1Value`, `searchIndex2Value`, `searchIndex3Value`, `searchIndex4Value`, `searchIndex5Value`: the value of the corresponding search index (since version 10.3 - 2025.1) ' operationId: searchProcessInstances parameters: - $ref: '#/components/parameters/pageIndex' - $ref: '#/components/parameters/pageCount' - $ref: '#/components/parameters/pageFilter' - $ref: '#/components/parameters/pageOrder' 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/ProcessInstance' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' 5XX: $ref: '#/components/responses/ServerError' post: tags: - ProcessInstance summary: Create the ProcessInstance description: '![edition](https://img.shields.io/badge/edition-entreprise-blue) ![edition](https://img.shields.io/badge/edition-community-brightgreen) Create the ProcessInstance This way of creating a process instance using this method will only work for processes in which no contract is defined. To instantiate a process with a contract, check the process instantiation resource documentation. ' operationId: createProcessInstance requestBody: content: application/json: schema: $ref: '#/components/schemas/ProcessInstanceCreateRequest' description: '**Warning**: The attribute `variables` on the request payload is used to initialize the process variables (not BDM variables). If you want to initialize BDM variables at process instantiation, add a contract on the process and map BDM variables to the contract data. See Start a process using an instantiation contract for usage. ' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ProcessInstance' description: 'Success ' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': description: Case creation limit reached (Community 2024.3+ only) headers: Retry-After: schema: type: string format: date-time description: Date when case counter will be refilled content: application/json: schema: type: object properties: message: type: string description: The error message exception: type: string description: The exception type example: message: Error occurred when starting process 5524355418393634511. Case creation limit reached. exception: org.bonitasoft.web.toolkit.client.common.exception.api.APITooManyRequestException 5XX: $ref: '#/components/responses/ServerError' x-codegen-request-body-name: body delete: tags: - ProcessInstance summary: Delete the ProcessInstance by batch description: '![edition](https://img.shields.io/badge/edition-entreprise-blue) ![edition](https://img.shields.io/badge/edition-community-brightgreen) Delete a list of ProcessInstances for the given IDs ' operationId: deleteProcessInstanceByIds requestBody: content: application/json: schema: type: array items: description: ProcessInstance id type: string 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/case/{id}: get: tags: - ProcessInstance summary: Finds the ProcessInstance by ID description: 'Returns the single ProcessInstance for the given ID ' operationId: getProcessInstanceById parameters: - description: ID of the ProcessInstance to return in: path name: id required: true schema: type: string maxLength: 250 pattern: ^[A-Za-z0-9\_\-\.]{0,250}$ - description: Count of related resources in: query name: n required: false schema: type: string enum: - activeFlowNodes - failedFlowNodes responses: '200': description: 'Success ' content: application/json: schema: $ref: '#/components/schemas/ProcessInstance' '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: - ProcessInstance summary: Update the ProcessInstance by ID description: 'Only the state of a ProcessInstance (with the given ID) can be updated in order to cancel it (since version 10.3 - 2025.1). ' operationId: updateProcessInstanceById parameters: - description: ID of the ProcessInstance to update 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/ProcessInstanceUpdateRequest' description: Cancel the ProcessInstance. 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' delete: tags: - ProcessInstance summary: Delete the ProcessInstance by ID description: 'Delete the single ProcessInstance for the given ID ' operationId: deleteProcessInstanceById parameters: - description: ID of the ProcessInstance to delete in: path name: id required: true schema: type: string maxLength: 250 pattern: ^[A-Za-z0-9\_\-\.]{0,250}$ 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/case/{id}/context: get: tags: - ProcessInstance summary: Finds the Context by ProcessInstance ID description: 'Returns the Context for the given ProcessInstance ID ' operationId: getContextByProcessInstanceId parameters: - description: ID of the ProcessInstance 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: ProcessInstance: type: object description: ProcessInstance (Case) is an instance of a process. When you start a process, it creates a process instances. properties: id: description: the identifier of the ProcessInstance (Case) type: string end_date: description: the date set when the process instance is closed type: string failedFlowNodes: description: count of failed flow nodes if parameter n=failedFlowNodes is given type: string startedBySubstitute: description: the identifier of the substitute user (as Process manager or Administrator) who started the process. It can be also the substitute user if d=startedBySubstitute is given. type: string start: description: the starting date of the case type: string activeFlowNodes: description: count of active flow nodes if parameter n=activeFlowNodes is given type: string state: description: 'state: an enum that represent the state of the process instances' type: string enum: - initializing - started - suspended - cancelled - aborted - completing - completed - error - aborting rootCaseId: description: the identifier of the container of the case type: string started_by: description: the identifier of the user who started the case type: string processDefinitionId: description: the identifier of the process related of the case type: string last_update_date: description: the date of the last update done on the case type: string searchIndex1Label: description: the 1st search index label (from 6.5, in Subscription editions only) type: string searchIndex2Label: description: the 2nd search index label (from 6.5, in Subscription editions only) type: string searchIndex3Label: description: the 3rd search index label (from 6.5, in Subscription editions only) type: string searchIndex4Label: description: the 4th search index label (from 6.5, in Subscription editions only) type: string searchIndex5Label: description: the 5th search index label (from 6.5, in Subscription editions only) type: string searchIndex1Value: description: the 1st search index value (from 6.5, in Subscription editions only) type: string searchIndex2Value: description: the 2nd search index value (from 6.5, in Subscription editions only) type: string searchIndex3Value: description: the 3rd search index value (from 6.5, in Subscription editions only) type: string searchIndex4Value: description: the 4th search index value (from 6.5, in Subscription editions only) type: string searchIndex5Value: description: the 5th search index value (from 6.5, in Subscription editions only) type: string callerId: description: the identifier of the BPM entity who started the process. E.g. the call activity instance Id if it was started by a call activity or -1 if it was started by a user (since version 10.3 - 2025.1) type: string example: id: 1 end_date": '' failedFlowNodes": 9 startedBySubstitute": 345 start": '2014-11-27 17:55:00.906' activeFlowNodes": '9' state": started rootCaseId": '1' callerId": '-1' started_by": 989 processDefinitionId": '5777042023671752656' last_update_date": '2014-11-27 17:55:00.906' searchIndex1Label: mySearchIndex1Label searchIndex2Label: mySearchIndex2Label searchIndex3Label: mySearchIndex3Label searchIndex4Label: mySearchIndex4Label searchIndex5Label: mySearchIndex5Label searchIndex1Value: mySearchIndex1Value searchIndex2Value: mySearchIndex2Value searchIndex3Value: mySearchIndex3Value searchIndex4Value: mySearchIndex4Value searchIndex5Value: mySearchIndex5Value ProcessInstanceCreateRequest: type: object properties: processDefinitionId: description: the process definition Id type: string variables: description: process variables initial values type: array items: $ref: '#/components/schemas/ProcessVariable' example: processDefinitionId: '5777042023671752656' variables: - name: stringVariable value: aValue - name: dateVariable value: 349246800000 - name: numericVariable value: 55 ProcessVariable: type: object additionalProperties: type: object properties: name: description: variable name type: string ProcessInstanceUpdateRequest: type: object properties: state: description: 'state of the ProcessInstance (the only supported value is: cancelled)' type: string example: state: cancelled 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 parameters: 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 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 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 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 responses: NotFound: description: The resource for the specified ID was not found. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Resource not found. OK: description: OK ServerError: description: Unexpected error. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: An unexpected error occured. 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. BadRequest: description: Bad request. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Bad request Unauthorized: description: Authorization information is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Unauthorized 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: '![edition](https://img.shields.io/badge/edition-entreprise-blue) 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