openapi: 3.0.0
info:
  title: ActionSession
  version: 2.0.0
  description: >
    An **ActionSession** represents a scheduled occurrence of a preventive
    action.

    The business meaning changes depending on the action type:

    - For `TRAINING`: a course **edition**

    - For `HEALTH`: a medical **visit**

    - For `PER`: a PPE **delivery**

    - For `MAINTENANCE`: a maintenance **order**

    - For `CHECK`: a check **session** or inspection report


    A session belongs to an action and can have:

    - One or more **dates** (ActionSessionDate): the days when it takes place

    - One or more **subscriptions** (ActionSessionSubscription): the resources
    enrolled in this specific occurrence


    Use this API to:

    - Schedule a course edition, maintenance order, medical visit, or PPE
    delivery

    - Find sessions for an action (filter by `action_id`)

    - Check enrollment counts and their status (completed, failed, pending)


    A session can have its own `validity` and `validity_unit` values, which
    override the action's

    values for certificates generated from this specific occurrence.
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
paths:
  /v2/action-session/index:
    post:
      summary: index
      operationId: indexActionSession
      tags:
        - ActionSessions
      description: |
        Returns a paginated list of action sessions.

        Most useful filters:
        - `action_id`: all sessions for a specific action
        - `action_type` + `subtenant_id`: all sessions of a type in an office
        - `tenant_id`: all sessions in a company

        The response includes enrollment counts and session dates.
      requestBody:
        description: Parameters for searching action sessions
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ActionSessionIndexParams"
            example:
              filter:
                action_id: c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f
                action_type: TRAINING
              per-page: 10
              page: 1
              sort: -date_begin
      responses:
        "200":
          description: List of action sessions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ViewActionSession"
              example:
                - action_session_id: b1c2d3e4-f5a6-7890-bcde-f12345678901
                  action_id: c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f
                  validity_unit: YEAR
                  validity: 5
                  subtenant_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  tenant_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
                  action_code: FST-01
                  action_name: Fire Safety Training Medium Risk
                  action_type: TRAINING
                  count_subscribed: 12
                  count_done: 10
                  count_fail: 1
                  count_unknown: 1
                  date_begin: 2024-03-15
                  date_end: 2024-03-16
          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/create:
    post:
      summary: create
      operationId: createActionSession
      tags:
        - ActionSessions
      description: >
        Creates a new session for an action.


        Requires `action_id`, `subtenant_id` (office_id), and `tenant_id`
        (project_id).

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


        Creating a session does **not** automatically create dates or
        enrollments.

        After creation, create ActionSessionDate entries (session dates)

        and ActionSessionSubscription entries (enrollments) separately.
      requestBody:
        description: Action session to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ActionSession"
            example:
              action_id: c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f
              validity_unit: YEAR
              validity: 5
              subtenant_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              tenant_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
      responses:
        "201":
          description: Action session created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionSession"
              example:
                action_session_id: b1c2d3e4-f5a6-7890-bcde-f12345678901
                action_id: c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f
                validity_unit: YEAR
                validity: 5
                subtenant_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                tenant_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
  /v2/action-session/view/{id}:
    get:
      summary: view
      operationId: viewActionSession
      tags:
        - ActionSessions
      description: |
        Retrieves a single action session by its ID.
      parameters:
        - name: id
          in: path
          description: The action_session_id to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Action session found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewActionSession"
        "404":
          description: Action session not found
  /v2/action-session/update/{id}:
    put:
      summary: update
      operationId: updateActionSession
      tags:
        - ActionSessions
      description: |
        Updates an existing action session.
      parameters:
        - name: id
          in: path
          description: The action_session_id to update.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ActionSession"
            example:
              validity_unit: YEAR
              validity: 3
      responses:
        "200":
          description: Action session updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionSession"
        "404":
          description: Action session not found
  /v2/action-session/delete/{id}:
    delete:
      summary: delete
      operationId: deleteActionSession
      tags:
        - ActionSessions
      description: >
        Deletes an action session.


        If `force=false` (default), the response lists child entities (dates,
        enrollments).

        If `force=true`, the session and all related entities are deleted.
      parameters:
        - name: id
          in: path
          description: The action_session_id to delete.
          required: true
          schema:
            type: string
            format: uuid
        - name: force
          in: query
          description: If true, deletes the session and all child entities. If false,
            returns a preview of affected entities.
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Action session deleted successfully
        "400":
          description: Preview of entities that would be deleted (returned when force=false)
components:
  schemas:
    ActionSession:
      type: object
      properties:
        action_session_id:
          type: string
          format: uuid
          description: Unique identifier of the session. Auto-generated if not provided on
            creation.
        action_id:
          type: string
          format: uuid
          description: The action this session belongs to. Pass the `action_id` obtained
            from the Action API.
        validity_unit:
          type: string
          enum:
            - YEAR
            - MONTH
            - DAY
          description: Validity unit specific to this session. If set, overrides the
            action's validity for certificates generated from this occurrence.
        validity:
          type: integer
          description: Number of validity units specific to this session.
        manager:
          type: string
          format: json
          description: Session managers (JSON).
        assignee:
          type: string
          format: json
          description: Session assignees (JSON).
        watcher:
          type: string
          format: json
          description: Session watchers (JSON).
        data:
          $ref: "#/components/schemas/ActionSessionData"
        subtenant_id:
          type: string
          format: uuid
          description: The office (work location) of this session. Pass the `office_id`.
        tenant_id:
          type: string
          format: uuid
          description: The project (company) of this session. Pass the `project_id`.
      required:
        - action_id
        - subtenant_id
        - tenant_id
    ViewActionSession:
      type: object
      properties:
        action_session_id:
          type: string
          format: uuid
          description: Unique identifier of the session.
        action_id:
          type: string
          format: uuid
          description: The action this session belongs to.
        validity_unit:
          type: string
          enum:
            - YEAR
            - MONTH
            - DAY
          description: Validity unit specific to this session.
        validity:
          type: integer
          description: Number of validity units specific to this session.
        data:
          $ref: "#/components/schemas/ActionSessionData"
        subtenant_id:
          type: string
          format: uuid
          description: The office of this session.
        tenant_id:
          type: string
          format: uuid
          description: The project of this session.
        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.
        count_subscribed:
          type: integer
          description: Total number of resources enrolled in this session.
        count_done:
          type: integer
          description: Number of enrolled resources that completed the session successfully.
        count_fail:
          type: integer
          description: Number of enrolled resources that did not pass.
        count_unknown:
          type: integer
          description: Number of enrolled resources whose outcome has not been recorded yet.
        date_begin:
          type: string
          format: date
          description: Start date of the session (from the earliest ActionSessionDate).
        date_end:
          type: string
          format: date
          description: End date of the session (from the latest ActionSessionDate).
        manager:
          type: string
          format: json
          description: Session managers (JSON).
        assignee:
          type: string
          format: json
          description: Session assignees (JSON).
        watcher:
          type: string
          format: json
          description: Session watchers (JSON).
    ActionSessionIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/ViewActionSession"
        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.
            "-date_begin").
          enum:
            - action_code
            - action_name
            - action_type
            - date_begin
            - date_end
      example:
        filter:
          action_id: c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f
          action_type: TRAINING
        per-page: 100
        page: 1
        sort: -date_begin
    ActionSessionData:
      description: >
        Additional structured data for the session. The fields depend on the
        action type:

        - **TRAINING** (course edition): `type` (required), `teacher`,
        `supplier`, `location`

        - **HEALTH** (medical visit): `type` (required), `location`

        - **MAINTENANCE** (maintenance order): `name`, `description`, `location`

        - **CHECK** (inspection report): `location`

        - **PER** (PPE delivery): `location`
      oneOf:
        - $ref: "#/components/schemas/ActionSessionDataTraining"
        - $ref: "#/components/schemas/ActionSessionDataHealth"
        - $ref: "#/components/schemas/ActionSessionDataMaintenance"
        - $ref: "#/components/schemas/ActionSessionDataCheck"
        - $ref: "#/components/schemas/ActionSessionDataPer"
    ActionSessionDataTraining:
      type: object
      description: Data fields for TRAINING sessions (course editions).
      properties:
        type:
          type: string
          enum:
            - base
            - update
          description: "Type of course edition: `base` = initial course, `update` =
            refresher/update course."
        teacher:
          type: string
          description: Name of the instructor/teacher.
        supplier:
          type: string
          description: Name of the training provider/supplier.
        location:
          type: string
          description: Location where the course takes place.
    ActionSessionDataHealth:
      type: object
      description: Data fields for HEALTH sessions (medical visits).
      properties:
        type:
          type: string
          enum:
            - PERIODIC
            - PREVENTIVE
            - REQUEST
            - JOBCHANGE
            - END
            - SICK
          description: |
            Type of medical visit:
            - `PERIODIC`: periodic surveillance visit
            - `PREVENTIVE`: pre-employment/preventive visit
            - `REQUEST`: visit requested by the worker
            - `JOBCHANGE`: visit due to change of job role
            - `END`: end-of-employment visit
            - `SICK`: visit after sick leave
        location:
          type: string
          description: Name or address of the medical facility.
    ActionSessionDataMaintenance:
      type: object
      description: Data fields for MAINTENANCE sessions (maintenance orders).
      properties:
        name:
          type: string
          description: Name or code of the maintenance order.
        description:
          type: string
          description: Detailed description of the maintenance work (may contain HTML).
        location:
          type: string
          description: Location where the maintenance takes place.
    ActionSessionDataCheck:
      type: object
      description: Data fields for CHECK sessions (inspection reports).
      properties:
        location:
          type: string
          description: Location where the check/inspection takes place.
    ActionSessionDataPer:
      type: object
      description: Data fields for PER sessions (PPE deliveries).
      properties:
        location:
          type: string
          description: Location where the PPE delivery takes place.
  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
