Bonitasoft Data Retention API

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 Data Retention API
  description: "<p> \n<a download=\"openapi.yaml\" href=\"./openapi.yaml\" target=\"_blank\" class=\"btn-download\">Download OpenAPI specification</a>\n<a download=\"postman.json\" href=\"./postman.json\" target=\"_blank\" class=\"btn-download\">Download Postman collection</a>\n</p>\n\n<hr>\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: DataRetention
  x-displayName: Data Retention
  description: 'Configure how Bonita automatically deletes obsolete business data. A retention rule applies to a specific business object type and defines when its instances become eligible for deletion based on a reference date (creation or last update) and a retention period in days. The data retention service runs on a configurable cron schedule.


    This Web REST API is available in **Enterprise editions only**, since version 11.0.

    '
paths:
  /API/retention/object:
    get:
      tags:
      - DataRetention
      summary: List business object types with their retention rules
      description: '![edition](https://img.shields.io/badge/edition-entreprise-blue)


        Returns the list of all business object types defined in the deployed Business Data Model (BDM),

        each enriched with its composition tree and the retention rule that may apply to it.


        The full list is returned in a single response. Pagination is not applied because the

        BDM is a bounded set defined at deployment time.


        Requires the `DATA_RETENTION` feature to be active in the platform license.

        Available since Bonita 11.0.

        '
      operationId: findObjectsWithRetentionRules
      responses:
        '200':
          description: 'Successful operation. The full list of business object types is returned in a single

            response. No pagination is applied and no `Content-Range` header is set.

            '
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BusinessObjectWithRetentionRule'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        5XX:
          $ref: '#/components/responses/ServerError'
  /API/retention/schedule:
    get:
      tags:
      - DataRetention
      summary: Get the data retention schedule
      description: '![edition](https://img.shields.io/badge/edition-entreprise-blue)


        Returns the cron expression that triggers the data retention job. The expression is configured

        via the `bonita.runtime.retention.schedule.cron` platform property and is read-only at runtime.


        Requires the `DATA_RETENTION` feature to be active in the platform license.

        Available since Bonita 11.0.

        '
      operationId: getRetentionSchedule
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetentionSchedule'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        5XX:
          $ref: '#/components/responses/ServerError'
  /API/retention/rule:
    post:
      tags:
      - DataRetention
      summary: Create a retention rule
      description: '![edition](https://img.shields.io/badge/edition-entreprise-blue)


        Creates a data retention rule for a business object type. Once created, the data retention

        service will automatically delete business data of `dataClassName` whose `referenceDate` is

        older than `retentionDays` days.


        Only one retention rule can exist per BDM class name. Posting a second rule for a

        `dataClassName` that already has one returns `409 Conflict`.


        Requires the `DATA_RETENTION` feature to be active in the platform license.

        Available since Bonita 11.0.

        '
      operationId: createRetentionRule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetentionRuleCreateRequest'
      responses:
        '201':
          description: Retention rule created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataRetentionConfig'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        5XX:
          $ref: '#/components/responses/ServerError'
      x-codegen-request-body-name: body
  /API/retention/rule/{ruleId}:
    put:
      tags:
      - DataRetention
      summary: Update a retention rule by ID
      description: '![edition](https://img.shields.io/badge/edition-entreprise-blue)


        Updates the `referenceDate` and `retentionDays` of an existing retention rule.


        Requires the `DATA_RETENTION` feature to be active in the platform license.

        Available since Bonita 11.0.

        '
      operationId: updateRetentionRuleById
      parameters:
      - description: Numeric ID of the retention rule to update (the `id` field returned by `DataRetentionConfig`).
        in: path
        name: ruleId
        required: true
        schema:
          type: string
          pattern: ^[0-9]+$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetentionRuleUpdateRequest'
      responses:
        '200':
          description: Retention rule updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataRetentionConfig'
        '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'
      x-codegen-request-body-name: body
    delete:
      tags:
      - DataRetention
      summary: Delete a retention rule by ID
      description: '![edition](https://img.shields.io/badge/edition-entreprise-blue)


        Deletes the retention rule with the given ID. Existing BDM object instances of the underlying

        type are not deleted by this operation; only the retention rule itself is removed.


        Requires the `DATA_RETENTION` feature to be active in the platform license.

        Available since Bonita 11.0.

        '
      operationId: deleteRetentionRuleById
      parameters:
      - description: Numeric ID of the retention rule to delete (the `id` field returned by `DataRetentionConfig`).
        in: path
        name: ruleId
        required: true
        schema:
          type: string
          pattern: ^[0-9]+$
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        5XX:
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    RetentionRuleCreateRequest:
      type: object
      description: 'Body of `POST /API/retention/rule`. Defines a new data retention rule for the business object

        type identified by `dataClassName`. All three fields are required.

        '
      required:
      - dataClassName
      - referenceDate
      - retentionDays
      properties:
        dataClassName:
          description: 'Fully qualified Java class name of the business object type this rule applies to. Note the uppercase `N`.


            The corresponding field returned in the `DataRetentionConfig` response of this endpoint and of `PUT /API/retention/rule/{ruleId}`, `GET /API/retention/object` is named `dataClassname` (lowercase `n`).

            '
          type: string
        referenceDate:
          $ref: '#/components/schemas/ReferenceDate'
        retentionDays:
          description: Duration of the retention period, in days. Must be strictly positive.
          type: integer
          format: int32
          minimum: 1
      example:
        dataClassName: com.company.model.ContratClient
        referenceDate: LAST_UPDATE
        retentionDays: 365
    BusinessObjectWithRetentionRule:
      type: object
      description: 'A business object type defined in the Business Data Model (BDM) along with its optional data

        retention rule and composition tree.


        The `dataRetentionRule` field is `null` when no retention rule has been configured for this

        business object type.

        '
      required:
      - qualifiedName
      - compositions
      - dataRetentionRule
      properties:
        qualifiedName:
          description: Fully qualified Java class name of the business object type.
          type: string
        compositions:
          description: Direct composition children of this business object type as a recursive tree.
          type: array
          items:
            $ref: '#/components/schemas/CompositionNode'
        dataRetentionRule:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/DataRetentionConfig'
      example:
        qualifiedName: com.company.model.Order
        compositions:
        - qualifiedName: com.company.model.OrderLine
          compositions:
          - qualifiedName: com.company.model.Product
            compositions: []
        - qualifiedName: com.company.model.Address
          compositions: []
        dataRetentionRule:
          id: '1'
          dataClassname: com.company.model.Order
          referenceDate: CREATION
          retentionDays: 365
          createdAt: '1777473415401'
          updatedAt: '1777473415401'
    DataRetentionConfig:
      type: object
      description: 'A data retention rule configured for a specific business object type. It defines when and how

        business data of that type are automatically deleted by the data retention service.

        '
      required:
      - id
      - dataClassname
      - referenceDate
      - retentionDays
      - createdAt
      - updatedAt
      properties:
        id:
          description: Identifier of the retention rule. Serialized as a string to avoid JavaScript precision loss on large `long` values.
          type: string
        dataClassname:
          description: Fully qualified Java class name of the business object type this rule applies to. Note the lowercase `n` (the create-rule request body uses `dataClassName` instead).
          type: string
        referenceDate:
          $ref: '#/components/schemas/ReferenceDate'
        retentionDays:
          description: Duration of the retention period, in days. Always strictly positive — enforced by the engine on create and update.
          type: integer
          format: int32
          minimum: 1
        createdAt:
          description: Creation timestamp of this retention rule, in epoch milliseconds. Serialized as a string to avoid JavaScript precision loss.
          type: string
        updatedAt:
          description: Last update timestamp of this retention rule, in epoch milliseconds. Serialized as a string to avoid JavaScript precision loss.
          type: string
      example:
        id: '1'
        dataClassname: com.company.model.Request
        referenceDate: CREATION
        retentionDays: 365
        createdAt: '1777473415401'
        updatedAt: '1777473415401'
    CompositionNode:
      type: object
      description: 'A node in the recursive composition tree of a business object type. Each node holds the

        qualified name of a composed business object type and the list of its own composed children,

        allowing arbitrarily deep composition hierarchies to be expressed.

        '
      required:
      - qualifiedName
      - compositions
      properties:
        qualifiedName:
          description: Fully qualified Java class name of the composed business object type.
          type: string
        compositions:
          description: Direct composition children of this object, or an empty list if none.
          type: array
          items:
            $ref: '#/components/schemas/CompositionNode'
      example:
        qualifiedName: com.company.model.Address
        compositions: []
    RetentionSchedule:
      type: object
      description: 'Schedule on which the data retention service runs. The cron expression is configured via the

        `bonita.runtime.retention.schedule.cron` platform property.

        '
      required:
      - cronExpression
      properties:
        cronExpression:
          description: Cron expression that defines when the data retention job is triggered.
          type: string
      example:
        cronExpression: 0 0 2 * * 6
    RetentionRuleUpdateRequest:
      type: object
      description: 'Body of `PUT /API/retention/rule/{ruleId}`. Replaces the mutable fields of an existing

        retention rule. This is a full replacement of `referenceDate` and `retentionDays`, not a

        partial update — both fields must be provided on every call. The `dataClassName` of an

        existing rule cannot be changed.

        '
      required:
      - referenceDate
      - retentionDays
      properties:
        referenceDate:
          $ref: '#/components/schemas/ReferenceDate'
        retentionDays:
          description: Duration of the retention period, in days. Must be strictly positive.
          type: integer
          format: int32
          minimum: 1
      example:
        referenceDate: CREATION
        retentionDays: 730
    ReferenceDate:
      type: string
      description: 'Date field on a BDM object instance used as the starting point of the retention period calculation.


        - `CREATION`: retention is calculated from the creation date of the BDM object instance. The clock never resets.

        - `LAST_UPDATE`: retention is calculated from the last modification date of the BDM object instance. The clock resets on every modification.

        '
      enum:
      - CREATION
      - LAST_UPDATE
    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.
    Conflict:
      description: Conflict, the request could not be completed because it conflicts with the current state of the target resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Conflict
    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
    NoContent:
      description: OK (no content).
    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