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: 'Download OpenAPI specification

    Download Postman collection


    The REST API lets you access the data with HTTP requests; it is useful when implementing rich web forms / pages for a good user experience.'
  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: Data Retention
  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:
      - Data Retention
      summary: List business object types with their retention rules
      description: '!edition


        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:
      - Data Retention
      summary: Get the data retention schedule
      description: '!edition


        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:
      - Data Retention
      summary: Create a retention rule
      description: '!edition


        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:
      - Data Retention
      summary: Update a retention rule by ID
      description: '!edition


        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:
      - Data Retention
      summary: Delete a retention rule by ID
      description: '!edition


        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:
    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: []
    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
    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
    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
    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
    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
    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'
  responses:
    Unauthorized:
      description: Authorization information is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Unauthorized
    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
    NotFound:
      description: The resource for the specified ID was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Resource not found.
    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
    ServerError:
      description: Unexpected error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: An unexpected error occured.
    NoContent:
      description: OK (no content).
  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