openapi: 3.0.0
info:
  title: ActionSessionSubscription
  version: 2.0.0
  description: >
    An **ActionSessionSubscription** represents the enrollment of a resource
    (person, equipment,

    work environment, substance, role, work group, office, PPE, or supplier) in
    a specific session.

    It links a session (ActionSession) to a compliance schedule entry
    (ActionSubscription).


    Use this API to:

    - Enroll a resource in a planned session

    - Find all enrollments for a session (filter by `action_session_id`)

    - Record the session outcome for each enrollee (field `done`)

    - Link a certificate generated from the session (field `certificate_id`)


    The `done` field tracks the outcome:

    - `-1`: outcome not yet recorded (default)

    - `0`: not passed / failed

    - `1`: passed / completed


    When the outcome is recorded as completed (`done: 1`), a certificate is
    typically generated

    and linked via the `certificate_id` field.
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
paths:
  /v2/action-session-subscription/index:
    post:
      summary: index
      operationId: indexActionSessionSubscription
      tags:
        - ActionSessionSubscriptions
      description: >
        Returns a paginated list of session enrollments.


        Most useful filters:

        - `action_session_id`: all enrollees in a specific session

        - `action_subscription_id`: all sessions an enrollment is linked to

        - `done`: filter by outcome (e.g. `done: -1` to find pending outcomes)

        - `action_type` + `subtenant_id`: all enrollments for a type of action
        in an office
      requestBody:
        description: Parameters for searching session enrollments
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ActionSessionSubscriptionIndexParams"
            example:
              filter:
                action_session_id: b1c2d3e4-f5a6-7890-bcde-f12345678901
                done: -1
              per-page: 10
              page: 1
              sort: subscriber_name
      responses:
        "200":
          description: List of session enrollments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ViewActionSessionSubscription"
              example:
                - action_session_subscription_id: d3e4f5a6-b7c8-9012-defg-h12345678901
                  action_session_id: b1c2d3e4-f5a6-7890-bcde-f12345678901
                  action_subscription_id: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a
                  done: 1
                  warning: 0
                  date_begin: 2024-03-15
                  date_expire: 2029-03-15
                  certificate_id: f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c
                  subtenant_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  tenant_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
                  subscriber_id: e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a
                  subscriber_type: PERSON
                  subscriber_code: JS001
                  subscriber_name: Smith John
                  action_id: c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f
                  action_code: FST-01
                  action_name: Fire Safety Training Medium Risk
                  action_type: TRAINING
                  validity_unit: YEAR
                  validity: 5
                  session_date_begin: 2024-03-15
          headers:
            X-Pagination-Current-Page:
              schema:
                type: integer
              description: Current page
            X-Pagination-Page-Count:
              schema:
                type: integer
              description: Total number of pages
            X-Pagination-Per-Page:
              schema:
                type: integer
              description: Number of items per page
            X-Pagination-Total-Count:
              schema:
                type: integer
              description: Total number of items
  /v2/action-session-subscription/create:
    post:
      summary: create
      operationId: createActionSessionSubscription
      tags:
        - ActionSessionSubscriptions
      description: >
        Creates a new session enrollment.


        Requires `action_session_id`, `action_subscription_id`, `subtenant_id`
        (office_id), and `tenant_id` (project_id).

        The `action_session_subscription_id` is auto-generated if not provided.


        The ActionSubscription must already exist (the resource must be enrolled
        in the action

        on the compliance schedule).
      requestBody:
        description: Session enrollment to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ActionSessionSubscription"
            example:
              action_session_id: b1c2d3e4-f5a6-7890-bcde-f12345678901
              action_subscription_id: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a
              subtenant_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              tenant_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
      responses:
        "201":
          description: Session enrollment created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionSessionSubscription"
              example:
                action_session_subscription_id: d3e4f5a6-b7c8-9012-defg-h12345678901
                action_session_id: b1c2d3e4-f5a6-7890-bcde-f12345678901
                action_subscription_id: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a
                done: -1
                warning: 0
                subtenant_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                tenant_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
  /v2/action-session-subscription/view/{id}:
    get:
      summary: view
      operationId: viewActionSessionSubscription
      tags:
        - ActionSessionSubscriptions
      description: |
        Retrieves a single session enrollment by its ID.
      parameters:
        - name: id
          in: path
          description: The action_session_subscription_id to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Session enrollment found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewActionSessionSubscription"
        "404":
          description: Session enrollment not found
  /v2/action-session-subscription/update/{id}:
    put:
      summary: update
      operationId: updateActionSessionSubscription
      tags:
        - ActionSessionSubscriptions
      description: >
        Updates an existing session enrollment.


        Typical use case: recording the outcome (`done: 1` or `done: 0`) and
        linking

        the generated certificate (`certificate_id`).
      parameters:
        - name: id
          in: path
          description: The action_session_subscription_id to update.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ActionSessionSubscription"
            example:
              done: 1
              certificate_id: f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c
              date_begin: 2024-03-15
              date_expire: 2029-03-15
      responses:
        "200":
          description: Session enrollment updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionSessionSubscription"
        "404":
          description: Session enrollment not found
  /v2/action-session-subscription/delete/{id}:
    delete:
      summary: delete
      operationId: deleteActionSessionSubscription
      tags:
        - ActionSessionSubscriptions
      description: |
        Deletes a session enrollment.

        If `force=false` (default), the response lists related entities.
        If `force=true`, the enrollment is deleted.
      parameters:
        - name: id
          in: path
          description: The action_session_subscription_id to delete.
          required: true
          schema:
            type: string
            format: uuid
        - name: force
          in: query
          description: If true, deletes the enrollment. If false, returns a preview of
            affected entities.
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Session enrollment deleted successfully
        "400":
          description: Preview of affected entities (returned when force=false)
components:
  schemas:
    ActionSessionSubscription:
      type: object
      properties:
        action_session_subscription_id:
          type: string
          format: uuid
          description: Unique identifier of the session enrollment. Auto-generated if not
            provided on creation.
        action_session_id:
          type: string
          format: uuid
          description: The session the resource is enrolled in. Pass the
            `action_session_id` obtained from the ActionSession API.
        action_subscription_id:
          type: string
          format: uuid
          description: The compliance schedule entry this enrollment is linked to. Pass
            the `action_subscription_id` obtained from the ActionSubscription
            API. This connects the session to the resource and the action on the
            compliance schedule.
        data:
          type: string
          format: json
          description: Additional structured data in JSON format. Content varies by action
            type.
        subtenant_id:
          type: string
          format: uuid
          description: The office (work location). Pass the `office_id`.
        tenant_id:
          type: string
          format: uuid
          description: The project (company). Pass the `project_id`.
        done:
          type: integer
          enum:
            - -1
            - 0
            - 1
          default: -1
          description: |
            Session outcome for this enrollee:
            - `-1`: outcome not yet recorded (default)
            - `0`: not passed / failed
            - `1`: passed / completed
        warning:
          type: integer
          enum:
            - 0
            - 1
          default: 0
          description: |
            - `0`: no warning (default)
            - `1`: warning active
        certificate_id:
          type: string
          format: uuid
          description: The certificate generated from this session for this enrollee.
            Optional — linked after creating the certificate via the Certificate
            API.
        date_begin:
          type: string
          format: date-time
          description: Start date of validity for this enrollment.
        date_expire:
          type: string
          format: date-time
          description: Expiration date for this enrollment.
      required:
        - action_session_id
        - action_subscription_id
        - subtenant_id
        - tenant_id
    ViewActionSessionSubscription:
      type: object
      properties:
        action_session_subscription_id:
          type: string
          format: uuid
          description: Unique identifier of the session enrollment.
        action_session_id:
          type: string
          format: uuid
          description: The session this enrollment belongs to.
        action_subscription_id:
          type: string
          format: uuid
          description: The linked compliance schedule entry.
        data:
          type: string
          format: json
          description: Additional structured data.
        subtenant_id:
          type: string
          format: uuid
          description: The office.
        tenant_id:
          type: string
          format: uuid
          description: The project.
        done:
          type: integer
          enum:
            - -1
            - 0
            - 1
          default: -1
          description: Session outcome (-1 pending, 0 failed, 1 completed).
        warning:
          type: integer
          enum:
            - 0
            - 1
          default: 0
          description: Warning flag.
        certificate_id:
          type: string
          format: uuid
          description: Certificate generated from this session for this enrollee.
        date_begin:
          type: string
          format: date-time
          description: Start date of validity.
        date_expire:
          type: string
          format: date-time
          description: Expiration date.
        subscriber_id:
          type: string
          format: uuid
          description: The ID of the enrolled resource (from the linked ActionSubscription).
        subscriber_type:
          type: string
          enum:
            - PERSON
            - ROLE
            - WORK_GROUP
            - WORK_ENVIRONMENT
            - SUBSTANCE
            - EQUIPMENT
            - OFFICE
            - PPE
            - UNIT
          description: The type of enrolled resource.
        subscriber_code:
          type: string
          description: Code of the enrolled resource.
        subscriber_name:
          type: string
          description: Name of the enrolled resource.
        action_code:
          type: string
          description: Code of the linked action.
        action_name:
          type: string
          description: Name of the linked action.
        action_type:
          type: string
          enum:
            - TRAINING
            - MAINTENANCE
            - HEALTH
            - CHECK
            - PER
          description: Type of the linked action.
        action_id:
          type: string
          format: uuid
          description: The action this session belongs to.
        validity_unit:
          type: string
          enum:
            - YEAR
            - MONTH
            - DAY
          description: Validity unit (from the session or action).
        validity:
          type: integer
          description: Number of validity units (from the session or action).
        session_date_begin:
          type: string
          format: date
          description: Start date of the session.
    ActionSessionSubscriptionIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/ViewActionSessionSubscription"
        per-page:
          type: integer
          minimum: 1
          default: 100
        page:
          type: integer
          minimum: 1
          default: 1
        sort:
          type: string
          description: Field to sort by. Prefix with minus for descending order (e.g.
            "-subscriber_name").
          enum:
            - subscriber_type
            - subscriber_code
            - subscriber_name
            - action_code
            - action_name
            - action_type
            - done
            - date_begin
            - date_expire
      example:
        filter:
          action_session_id: b1c2d3e4-f5a6-7890-bcde-f12345678901
          done: -1
        per-page: 100
        page: 1
        sort: subscriber_name
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        password:
          tokenUrl: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token
          scopes: {}
    AccessToken:
      type: apiKey
      in: query
      name: access-token
