openapi: 3.0.0
info:
  title: ActionSessionDate
  version: 2.0.0
  description: >
    An **ActionSessionDate** represents a specific day of a session.

    A session can span multiple days — each day is an ActionSessionDate.


    For example, a 3-day training course will have one ActionSession with 3
    ActionSessionDate entries.


    Use this API to:

    - Define the dates when a session takes place (after creating the session)

    - Find the dates for a session (filter by `action_session_id`)

    - Modify the schedule of a planned session
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
paths:
  /v2/action-session-date/index:
    post:
      summary: index
      operationId: indexActionSessionDate
      tags:
        - ActionSessionDates
      description: >
        Returns a paginated list of session dates.


        Most useful filters:

        - `action_session_id`: all dates for a specific session

        - `action_type` + `subtenant_id`: all dates for a type of action in an
        office

        - `subscriber_id` (query parameter): dates of sessions where a specific
        resource is enrolled
      parameters:
        - name: subscriber_id
          in: query
          description: Filter by subscriber ID. Returns only session dates where this
            resource is enrolled.
          required: false
          schema:
            type: string
            format: uuid
      requestBody:
        description: Parameters for searching session dates
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ActionSessionDateIndexParams"
            example:
              filter:
                action_session_id: b1c2d3e4-f5a6-7890-bcde-f12345678901
              per-page: 10
              page: 1
              sort: date_begin
      responses:
        "200":
          description: List of session dates
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ViewActionSessionDate"
              example:
                - action_session_date_id: c2d3e4f5-a6b7-8901-cdef-123456789012
                  action_session_id: b1c2d3e4-f5a6-7890-bcde-f12345678901
                  date_begin: 2024-03-15T09:00:00
                  date_end: 2024-03-15T17:00:00
                  subtenant_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  tenant_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
                  action_id: c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f
                  action_code: FST-01
                  action_name: Fire Safety Training Medium Risk
                  action_type: TRAINING
                  office_name: Rome North Site
                  project_name: Acme Construction Ltd
          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-date/create:
    post:
      summary: create
      operationId: createActionSessionDate
      tags:
        - ActionSessionDates
      description: >
        Creates a new date for a session.


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

        The `action_session_date_id` is auto-generated if not provided.
      requestBody:
        description: Session date to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ActionSessionDate"
            example:
              action_session_id: b1c2d3e4-f5a6-7890-bcde-f12345678901
              date_begin: 2024-03-15T09:00:00
              date_end: 2024-03-15T17:00:00
              subtenant_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              tenant_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
      responses:
        "201":
          description: Session date created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionSessionDate"
              example:
                action_session_date_id: c2d3e4f5-a6b7-8901-cdef-123456789012
                action_session_id: b1c2d3e4-f5a6-7890-bcde-f12345678901
                date_begin: 2024-03-15T09:00:00
                date_end: 2024-03-15T17:00:00
                subtenant_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                tenant_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
  /v2/action-session-date/view/{id}:
    get:
      summary: view
      operationId: viewActionSessionDate
      tags:
        - ActionSessionDates
      description: |
        Retrieves a single session date by its ID.
      parameters:
        - name: id
          in: path
          description: The action_session_date_id to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Session date found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewActionSessionDate"
        "404":
          description: Session date not found
  /v2/action-session-date/update/{id}:
    put:
      summary: update
      operationId: updateActionSessionDate
      tags:
        - ActionSessionDates
      description: |
        Updates an existing session date.
      parameters:
        - name: id
          in: path
          description: The action_session_date_id to update.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ActionSessionDate"
            example:
              date_begin: 2024-04-01T09:00:00
              date_end: 2024-04-01T17:00:00
      responses:
        "200":
          description: Session date updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionSessionDate"
        "404":
          description: Session date not found
  /v2/action-session-date/delete/{id}:
    delete:
      summary: delete
      operationId: deleteActionSessionDate
      tags:
        - ActionSessionDates
      description: |
        Deletes a session date.

        If `force=false` (default), the response lists related entities.
        If `force=true`, the date is deleted.
      parameters:
        - name: id
          in: path
          description: The action_session_date_id to delete.
          required: true
          schema:
            type: string
            format: uuid
        - name: force
          in: query
          description: If true, deletes the date. If false, returns a preview of affected
            entities.
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Session date deleted successfully
        "400":
          description: Preview of affected entities (returned when force=false)
components:
  schemas:
    ActionSessionDate:
      type: object
      properties:
        action_session_date_id:
          type: string
          format: uuid
          description: Unique identifier of the session date. Auto-generated if not
            provided on creation.
        action_session_id:
          type: string
          format: uuid
          description: The session this date belongs to. Pass the `action_session_id`
            obtained from the ActionSession API.
        date_begin:
          type: string
          format: date-time
          description: Start date and time of this day.
        date_end:
          type: string
          format: date-time
          description: End date and time of this day.
        data:
          type: string
          format: json
          description: Additional structured data in JSON format.
        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`.
      required:
        - action_session_id
        - date_begin
        - date_end
        - subtenant_id
        - tenant_id
    ViewActionSessionDate:
      type: object
      properties:
        action_session_date_id:
          type: string
          format: uuid
          description: Unique identifier of the session date.
        action_session_id:
          type: string
          format: uuid
          description: The session this date belongs to.
        subtenant_id:
          type: string
          format: uuid
          description: The office of this session date.
        tenant_id:
          type: string
          format: uuid
          description: The project of this session date.
        date_begin:
          type: string
          format: date-time
          description: Start date and time.
        date_end:
          type: string
          format: date-time
          description: End date and time.
        data:
          type: string
          format: json
          description: Additional structured data.
        action_id:
          type: string
          format: uuid
          description: The action this session belongs to.
        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.
        office_name:
          type: string
          description: Name of the office.
        project_name:
          type: string
          description: Name of the project (company).
        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).
    ActionSessionDateIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/ViewActionSessionDate"
        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:
            - date_begin
            - date_end
            - action_code
            - action_name
            - action_type
      example:
        filter:
          action_session_id: b1c2d3e4-f5a6-7890-bcde-f12345678901
        per-page: 100
        page: 1
        sort: date_begin
  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
