openapi: 3.0.0
info:
  title: IncidentResource
  version: 2.0.0
  description: >
    An **IncidentResource** represents a resource involved in an incident.

    Links an incident (Incident) to an office resource.


    The `entity_id` field contains the resource ID and `entity_type` specifies
    its kind:

    - `EQUIPMENT`: an equipment item (`office_equipment_id`)

    - `WORK_ENVIRONMENT`: a work environment (`office_work_environment_id`)

    - `SUBSTANCE`: a substance (`office_substance_id`)

    - `WORK_GROUP`: a work group (`work_group_id`)

    - `MATERIAL`: a material type (`material_id`)

    - `MATERIAL_ITEM`: a material item (`material_item_id`)

    - `ACTION`: a preventive action (`action_id`)


    Use this API to:

    - Register resources involved in an incident

    - Find all resources involved in an incident (filter by
    `office_incident_id`)

    - Find all incidents that involved a resource (filter by `entity_id`)
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
paths:
  /v2/incident-resource/index:
    post:
      summary: index
      operationId: indexIncidentResource
      tags:
        - IncidentResources
      description: |
        Returns a paginated list of resources involved in incidents.

        Most useful filters:
        - `office_incident_id`: all resources involved in a specific incident
        - `entity_id`: all incidents that involved a specific resource
        - `entity_type`: filter by resource type
      requestBody:
        description: Parameters for searching
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IncidentResourceIndexParams"
            example:
              filter:
                office_incident_id: 5c6d7e8f-9012-3456-abcd-ef5678901234
              per-page: 20
              page: 1
              sort: entity_name
      responses:
        "200":
          description: List of involved resources
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ViewIncidentResource"
          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/incident-resource/create:
    post:
      summary: create
      operationId: createIncidentResource
      tags:
        - IncidentResources
      description: >
        Registers a resource involved in an incident.


        Requires `office_incident_id`, `entity_id`, `entity_type`,
        `subtenant_id` (office_id), and `tenant_id` (project_id).

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


        What to pass as `entity_id` depends on `entity_type`:

        - `EQUIPMENT`: pass the `office_equipment_id`

        - `WORK_ENVIRONMENT`: pass the `office_work_environment_id`

        - `SUBSTANCE`: pass the `office_substance_id`

        - `WORK_GROUP`: pass the `work_group_id`

        - `MATERIAL`: pass the `material_id`

        - `MATERIAL_ITEM`: pass the `material_item_id`

        - `ACTION`: pass the `action_id`
      requestBody:
        description: Involved resource to register
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IncidentResource"
      responses:
        "201":
          description: Involved resource registered successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentResource"
  /v2/incident-resource/view/{id}:
    get:
      summary: view
      operationId: viewIncidentResource
      tags:
        - IncidentResources
      description: Retrieves a single involved resource by its ID.
      parameters:
        - name: id
          in: path
          description: The office_incident_resource_id to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Involved resource found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewIncidentResource"
        "404":
          description: Not found
  /v2/incident-resource/update/{id}:
    put:
      summary: update
      operationId: updateIncidentResource
      tags:
        - IncidentResources
      description: Updates an existing involved resource record.
      parameters:
        - name: id
          in: path
          description: The office_incident_resource_id to update.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IncidentResource"
      responses:
        "200":
          description: Updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentResource"
        "404":
          description: Not found
  /v2/incident-resource/delete/{id}:
    delete:
      summary: delete
      operationId: deleteIncidentResource
      tags:
        - IncidentResources
      description: Deletes an involved resource record.
      parameters:
        - name: id
          in: path
          description: The office_incident_resource_id to delete.
          required: true
          schema:
            type: string
            format: uuid
        - name: force
          in: query
          description: If true, deletes the record.
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Deleted successfully
        "400":
          description: Preview of affected entities (returned when force=false)
components:
  schemas:
    IncidentResource:
      type: object
      required:
        - office_incident_id
        - entity_id
        - entity_type
        - tenant_id
        - subtenant_id
      properties:
        office_incident_resource_id:
          type: string
          format: uuid
          description: Unique identifier. Auto-generated if not provided.
        office_incident_id:
          type: string
          format: uuid
          description: The incident. Pass the `office_incident_id` from the Incident API.
        entity_id:
          type: string
          format: uuid
          description: |
            The involved resource. What to pass depends on `entity_type`:
            - `EQUIPMENT`: pass the `office_equipment_id`
            - `WORK_ENVIRONMENT`: pass the `office_work_environment_id`
            - `SUBSTANCE`: pass the `office_substance_id`
            - `WORK_GROUP`: pass the `work_group_id`
            - `MATERIAL`: pass the `material_id`
            - `MATERIAL_ITEM`: pass the `material_item_id`
            - `ACTION`: pass the `action_id`
        entity_type:
          type: string
          enum:
            - EQUIPMENT
            - WORK_ENVIRONMENT
            - SUBSTANCE
            - WORK_GROUP
            - MATERIAL
            - MATERIAL_ITEM
            - ACTION
          description: Type of involved resource.
        description:
          type: string
          nullable: true
          description: Description of the resource's involvement.
        tenant_id:
          type: string
          format: uuid
          description: The project (company). Pass the `project_id`.
        subtenant_id:
          type: string
          format: uuid
          description: The office. Pass the `office_id`.
    ViewIncidentResource:
      type: object
      properties:
        office_incident_resource_id:
          type: string
          format: uuid
        office_incident_id:
          type: string
          format: uuid
        entity_id:
          type: string
          format: uuid
        entity_type:
          type: string
          enum:
            - EQUIPMENT
            - WORK_ENVIRONMENT
            - SUBSTANCE
            - WORK_GROUP
            - MATERIAL
            - MATERIAL_ITEM
            - ACTION
        description:
          type: string
        tenant_id:
          type: string
          format: uuid
        subtenant_id:
          type: string
          format: uuid
        entity_name:
          type: string
          description: Name of the involved resource.
        entity_code:
          type: string
          nullable: true
          description: Code of the involved resource.
        incident_code:
          type: string
          nullable: true
        incident_name:
          type: string
        incident_date:
          type: string
          format: date
        incident_category:
          type: string
        incident_status:
          type: string
          enum:
            - new
            - open
            - closed
        project_name:
          type: string
        project_type:
          type: string
          enum:
            - safety
            - template
        office_name:
          type: string
    IncidentResourceIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/ViewIncidentResource"
        per-page:
          type: integer
          minimum: 1
          default: 100
        page:
          type: integer
          minimum: 1
          default: 1
        sort:
          type: string
          enum:
            - entity_type
            - entity_name
            - incident_name
            - office_name
      example:
        filter:
          office_incident_id: 5c6d7e8f-9012-3456-abcd-ef5678901234
        per-page: 100
        page: 1
        sort: entity_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
