openapi: 3.0.0
info:
  title: Action
  version: 2.0.0
  description: >
    An **Action** represents a preventive safety action defined within an
    office.

    Each action describes a compliance requirement: a training course, a medical
    examination,

    equipment maintenance, PPE provision, or an operational check procedure.


    **Hierarchy:** Project (company) → Office (work location) → Action
    (compliance requirement).


    Actions are the link between compliance requirements and the compliance
    schedule:

    - **ActionSubscription** (compliance schedule) records who must do what,
    linking an action to a person, equipment, work environment, substance, role,
    work group, office, PPE, or supplier

    - **CertificateAction** links a certificate to an action, proving the
    requirement has been fulfilled


    Use this API to:

    - Find actions defined in an office (filter by `subtenant_id` with the
    `office_id`)

    - Find actions by type (e.g. `action_type: TRAINING` for training courses)

    - Create new preventive actions within an office

    - Get the `action_id` needed to create compliance schedule entries or link
    certificates


    Action types (`action_type`):

    - `TRAINING`: training courses — applies to people

    - `HEALTH`: medical surveillance — applies to people

    - `PER`: personal protective equipment (PPE) — applies to people

    - `CHECK`: check procedures and checklists — applies to people, equipment,
    work environments, substances, roles, work groups, PPE, offices, suppliers

    - `MAINTENANCE`: maintenance — applies to equipment, work environments, PPE,
    offices


    The `action_type` field **cannot be changed** after creation.
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
paths:
  /v2/action/index:
    post:
      summary: index
      operationId: indexAction
      tags:
        - Actions
      description: >
        Returns a paginated list of actions.


        Most useful filters:

        - `subtenant_id` (office_id) + `action_type`: find all actions of a type
        in an office (e.g. all training courses at a construction site)

        - `tenant_id` (project_id) + `action_type`: find all actions of a type
        in the company

        - `name`: search an action by name


        The response includes compliance counts:

        - `countSubscribed`: total number of subscribed resources

        - `countValid`: number with a valid certificate

        - `countScheduled`: number with a scheduled future session

        - `countToDo`: number without a valid certificate or scheduled session —
        the compliance gaps to resolve
      requestBody:
        description: Parameters for searching actions
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ActionIndexParams"
            example:
              filter:
                subtenant_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                action_type: TRAINING
              per-page: 20
              page: 1
              sort: name
      responses:
        "200":
          description: List of actions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ViewAction"
              example:
                - action_id: c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f
                  action_type: TRAINING
                  code: FST-01
                  name: Fire Safety Training Medium Risk
                  description: Mandatory fire safety course for medium risk workers
                  validity_unit: YEAR
                  validity: 5
                  expire_interval: 90
                  subtenant_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  tenant_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
                  office_name: Rome North Site
                  project_name: Acme Construction Ltd
                  countSubscribed: 25
                  countValid: 18
                  countScheduled: 3
                  countToDo: 4
                  owned_active: true
                  parent_active: true
          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/create:
    post:
      summary: create
      operationId: createAction
      tags:
        - Actions
      description: >
        Creates a new action within an office.


        Requires `action_type`, `name`, `subtenant_id` (office_id), and
        `tenant_id` (project_id).

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


        Creating an action does **not** automatically create compliance schedule
        entries.

        To assign people, equipment, or other resources to this action, create
        ActionSubscription entries separately.


        The `validity` + `validity_unit` fields define how long certificates
        linked to this action remain valid

        (e.g. `validity: 5`, `validity_unit: YEAR` = certificates expire 5 years
        after issue).


        The `subscriber_type` field restricts which resource types can be
        subscribed to this action.

        If not specified, the allowed types are determined by the `action_type`.
      requestBody:
        description: Action object to be created
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Action"
            example:
              action_type: TRAINING
              code: FST-01
              name: Fire Safety Training Medium Risk
              description: Mandatory fire safety course for medium risk workers
              validity_unit: YEAR
              validity: 5
              expire_interval: 90
              subtenant_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              tenant_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
      responses:
        "201":
          description: Action created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Action"
              example:
                action_id: c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f
                action_type: TRAINING
                code: FST-01
                name: Fire Safety Training Medium Risk
                validity_unit: YEAR
                validity: 5
                expire_interval: 90
                subtenant_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                tenant_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
  /v2/action/view/{id}:
    get:
      summary: view
      operationId: viewAction
      tags:
        - Actions
      description: |
        Retrieves a single action by its ID.
      parameters:
        - name: id
          in: path
          description: The action_id to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Action found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewAction"
              example:
                action_id: c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f
                action_type: TRAINING
                code: FST-01
                name: Fire Safety Training Medium Risk
                validity_unit: YEAR
                validity: 5
                expire_interval: 90
                subtenant_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                tenant_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
                office_name: Rome North Site
                project_name: Acme Construction Ltd
                countSubscribed: 25
                countValid: 18
                countScheduled: 3
                countToDo: 4
                owned_active: true
                parent_active: true
        "404":
          description: Action not found
  /v2/action/update/{id}:
    put:
      summary: update
      operationId: updateAction
      tags:
        - Actions
      description: |
        Updates an existing action.

        The `action_type` field **cannot be changed** after creation.
      parameters:
        - name: id
          in: path
          description: The action_id to update.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Action fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Action"
            example:
              name: Fire Safety Training High Risk
              validity: 3
      responses:
        "200":
          description: Action updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Action"
              example:
                action_id: c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f
                action_type: TRAINING
                name: Fire Safety Training High Risk
                validity: 3
                validity_unit: YEAR
        "404":
          description: Action not found
  /v2/action/delete/{id}:
    delete:
      summary: delete
      operationId: deleteAction
      tags:
        - Actions
      description: >
        Deletes an action.


        If `force=false` (default), the response lists child entities
        (subscriptions, sessions, linked certificates).

        If `force=true`, the action and all related entities are deleted.
      parameters:
        - name: id
          in: path
          description: The action_id to delete.
          required: true
          schema:
            type: string
            format: uuid
        - name: force
          in: query
          description: If true, deletes the action and all child entities. If false,
            returns a preview of affected entities.
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Action deleted successfully
        "400":
          description: Preview of entities that would be deleted (returned when force=false)
components:
  schemas:
    Action:
      type: object
      properties:
        action_id:
          type: string
          format: uuid
          description: Unique identifier of the action. Auto-generated if not provided on
            creation. Compliance schedule entries (ActionSubscription) and
            certificate links (CertificateAction) reference the action via this
            field.
        action_type:
          type: string
          enum:
            - TRAINING
            - MAINTENANCE
            - HEALTH
            - CHECK
            - PER
          description: >
            Type of preventive action:

            - `TRAINING`: training courses — applies to people

            - `HEALTH`: medical surveillance — applies to people

            - `PER`: personal protective equipment — applies to people

            - `CHECK`: check procedures — applies to people, equipment, work
            environments, substances, roles, work groups, PPE, offices,
            suppliers

            - `MAINTENANCE`: maintenance — applies to equipment, work
            environments, PPE, offices

            Cannot be changed after creation.
        code:
          type: string
          maxLength: 50
          description: Identifier code for the action.
        name:
          type: string
          maxLength: 255
          description: Descriptive name of the action.
        description:
          type: string
          description: Optional detailed description.
        validity_unit:
          type: string
          enum:
            - YEAR
            - MONTH
            - DAY
          description: Unit for the certificate validity period. Used together with
            `validity`.
        validity:
          type: integer
          description: Number of validity units. Together with `validity_unit`, defines
            how long certificates linked to this action remain valid (e.g.
            validity 5 + validity_unit YEAR = 5 years).
        expire_interval:
          type: integer
          description: Number of days before expiration to trigger the EXPIRING status in
            the compliance schedule. Subscriptions transition from VALID to
            EXPIRING this many days before the certificate expires.
        manager:
          type: string
          format: json
          description: Action managers (JSON).
        assignee:
          type: string
          format: json
          description: Action assignees (JSON).
        watcher:
          type: string
          format: json
          description: Action watchers (JSON).
        subscriber_type:
          type: string
          format: json
          nullable: true
          description: >
            JSON array of resource types that can be subscribed to this action.

            Possible values: PERSON, ROLE, WORK_GROUP, WORK_ENVIRONMENT,
            SUBSTANCE, EQUIPMENT, OFFICE, PPE, UNIT.

            If null, the allowed types are determined by the `action_type`.
        data:
          type: string
          format: json
          description: Additional structured data in JSON format.
        subtenant_id:
          type: string
          format: uuid
          description: The office (work location) where this action is defined. Pass the
            `office_id` obtained from the Office API.
        tenant_id:
          type: string
          format: uuid
          description: The project (company) this action belongs to. Pass the `project_id`
            obtained from the Project API.
      required:
        - action_type
        - name
        - subtenant_id
        - tenant_id
    ViewAction:
      type: object
      properties:
        action_id:
          type: string
          format: uuid
          description: Unique identifier of the action.
        action_type:
          type: string
          enum:
            - TRAINING
            - MAINTENANCE
            - HEALTH
            - CHECK
            - PER
          description: Type of preventive action. See Action schema for details.
        code:
          type: string
          description: Identifier code for the action.
        name:
          type: string
          description: Descriptive name of the action.
        description:
          type: string
          description: Optional detailed description.
        validity_unit:
          type: string
          enum:
            - YEAR
            - MONTH
            - DAY
          description: Unit for the certificate validity period.
        validity:
          type: integer
          description: Number of validity units.
        expire_interval:
          type: integer
          description: Days before expiration to trigger EXPIRING status.
        manager:
          type: string
          format: json
          description: Action managers (JSON).
        assignee:
          type: string
          format: json
          description: Action assignees (JSON).
        watcher:
          type: string
          format: json
          description: Action watchers (JSON).
        subscriber_type:
          type: string
          format: json
          nullable: true
          description: JSON array of allowed subscriber types. If null, determined by
            `action_type`.
        data:
          type: string
          format: json
          description: Additional structured data.
        subtenant_id:
          type: string
          format: uuid
          description: The office (work location) where this action is defined.
        tenant_id:
          type: string
          format: uuid
          description: The project (company) this action belongs to.
        countSubscribed:
          type: integer
          description: Total number of resources subscribed to this action.
        countValid:
          type: integer
          description: Number of subscribed resources with a currently valid certificate.
        countScheduled:
          type: integer
          description: Number of subscribed resources with a scheduled future session.
        countToDo:
          type: integer
          description: Number of subscribed resources without a valid certificate or
            scheduled session — compliance gaps to resolve.
        office_name:
          type: string
          description: Name of the office where this action is defined.
        project_name:
          type: string
          description: Name of the project (company).
        project_type:
          type: string
          description: Type of the parent project.
        owned_active:
          type: boolean
          nullable: true
          description: Whether this action is currently active in its validity period.
        parent_active:
          type: boolean
          nullable: true
          description: Whether the parent office is currently active.
    ActionIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/ViewAction"
        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.
            "-name").
          enum:
            - code
            - name
            - action_type
            - office_name
            - project_name
        history:
          type: boolean
          description: If true, includes historicized (no longer active) entries in the
            results. By default only current entries are returned.
      example:
        filter:
          subtenant_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          action_type: TRAINING
        per-page: 100
        page: 1
        sort: 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
