openapi: 3.0.0
info:
  title: EntityEmployee
  version: 2.0.0
  description: >
    An **EntityEmployee** represents the assignment of a person to an office
    resource:

    a safety role, a piece of equipment, a work environment, or a substance.


    For example: assigning "John Smith" to the role "Safety Officer" or to the
    equipment "Forklift A".


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

    - `ROLE`: a safety organization role (`office_role_id`)

    - `EQUIPMENT`: a piece of equipment (`office_equipment_id`)

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

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


    Use this API to:

    - Assign a person to a role, equipment, work environment, or substance

    - Find all people assigned to a resource (filter by `entity_id`)

    - Find all resources a person is assigned to (filter by `person_office_id`)


    Supports historicization.
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
paths:
  /v2/entity-employee/index:
    post:
      summary: index
      operationId: indexEntityEmployee
      tags:
        - EntityEmployees
      description: >
        Returns a paginated list of person-resource assignments.


        Most useful filters:

        - `entity_id`: all people assigned to a specific resource

        - `person_office_id`: all resources a person is assigned to

        - `type`: filter by resource type (`ROLE`, `EQUIPMENT`,
        `WORK_ENVIRONMENT`, `SUBSTANCE`)

        - `office_id`: all assignments in an office
      requestBody:
        description: Parameters for searching
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EntityEmployeeIndexParams"
            example:
              filter:
                entity_id: 1a2b3c4d-5e6f-7890-abcd-ef1234567890
                type: ROLE
              per-page: 20
              page: 1
              sort: person_last_name
      responses:
        "200":
          description: List of person-resource assignments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ViewEntityEmployee"
          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/entity-employee/create:
    post:
      summary: create
      operationId: createEntityEmployee
      tags:
        - EntityEmployees
      description: |
        Assigns a person to a resource.

        Requires `entity_id`, `person_office_id`, `office_id`, and `project_id`.
        The `entity_employee_id` is auto-generated if not provided.

        What to pass as `entity_id` depends on the `type`:
        - `ROLE`: pass the `office_role_id`
        - `EQUIPMENT`: pass the `office_equipment_id`
        - `WORK_ENVIRONMENT`: pass the `office_work_environment_id`
        - `SUBSTANCE`: pass the `office_substance_id`
      requestBody:
        description: Assignment to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EntityEmployee"
      responses:
        "201":
          description: Assignment created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EntityEmployee"
  /v2/entity-employee/view/{id}:
    get:
      summary: view
      operationId: viewEntityEmployee
      tags:
        - EntityEmployees
      description: Retrieves a single assignment by its ID.
      parameters:
        - name: id
          in: path
          description: The entity_employee_id to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Assignment found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewEntityEmployee"
        "404":
          description: Assignment not found
  /v2/entity-employee/update/{id}:
    put:
      summary: update
      operationId: updateEntityEmployee
      tags:
        - EntityEmployees
      description: Updates an existing assignment.
      parameters:
        - name: id
          in: path
          description: The entity_employee_id to update.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EntityEmployee"
      responses:
        "200":
          description: Assignment updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EntityEmployee"
        "404":
          description: Assignment not found
  /v2/entity-employee/delete/{id}:
    delete:
      summary: delete
      operationId: deleteEntityEmployee
      tags:
        - EntityEmployees
      description: |
        Deletes a person-resource assignment.

        If `force=false` (default), the response lists child entities.
        If `force=true`, the assignment and related entities are deleted.
      parameters:
        - name: id
          in: path
          description: The entity_employee_id to delete.
          required: true
          schema:
            type: string
            format: uuid
        - name: force
          in: query
          description: If true, deletes the assignment and all child entities.
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Assignment deleted successfully
        "400":
          description: Preview of entities that would be deleted (returned when force=false)
components:
  schemas:
    EntityEmployee:
      type: object
      required:
        - entity_id
        - person_office_id
        - office_id
        - project_id
      properties:
        entity_employee_id:
          type: string
          format: uuid
          description: Unique identifier. Auto-generated if not provided.
        entity_id:
          type: string
          format: uuid
          description: >
            The resource this person is assigned to. What to pass depends on
            `type`:

            - `ROLE`: pass the `office_role_id`

            - `EQUIPMENT`: pass the `office_equipment_id`

            - `WORK_ENVIRONMENT`: pass the `office_work_environment_id`

            - `SUBSTANCE`: pass the `office_substance_id`
        person_office_id:
          type: string
          format: uuid
          description: The person-office assignment. Pass the `person_office_id` from the
            PersonOffice API.
        type:
          type: string
          maxLength: 50
          enum:
            - EQUIPMENT
            - WORK_ENVIRONMENT
            - SUBSTANCE
            - ROLE
          description: |
            Type of resource:
            - `ROLE`: a safety organization role
            - `EQUIPMENT`: a piece of equipment
            - `WORK_ENVIRONMENT`: a work environment
            - `SUBSTANCE`: a substance
        office_id:
          type: string
          format: uuid
          description: The office. Pass the `office_id`.
        project_id:
          type: string
          format: uuid
          description: The project (company). Pass the `project_id`.
    ViewEntityEmployee:
      type: object
      properties:
        entity_employee_id:
          type: string
          format: uuid
        entity_id:
          type: string
          format: uuid
        person_office_id:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - EQUIPMENT
            - WORK_ENVIRONMENT
            - SUBSTANCE
            - ROLE
        office_id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        person_id:
          type: string
          format: uuid
          description: The person ID.
        person_code:
          type: string
          description: Employee code.
        person_first_name:
          type: string
        person_last_name:
          type: string
        person_is_external:
          type: boolean
          description: Whether the person is external prevention staff.
        entity_code:
          type: string
          description: Code of the assigned resource.
        entity_name:
          type: string
          description: Name of the assigned resource.
        office_name:
          type: string
          description: Name of the office.
        project_name:
          type: string
          description: Name of the project.
        project_type:
          type: string
          enum:
            - safety
            - template
        owned_active:
          type: boolean
          nullable: true
          description: Whether this assignment is currently active.
        parent_active:
          type: boolean
          nullable: true
          description: Whether the parent entities are currently active.
    EntityEmployeeIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/ViewEntityEmployee"
        per-page:
          type: integer
          minimum: 1
          default: 100
        page:
          type: integer
          minimum: 1
          default: 1
        sort:
          type: string
          enum:
            - person_code
            - person_first_name
            - person_last_name
            - entity_code
            - entity_name
            - type
        history:
          type: boolean
          description: If true, includes historicized entries.
      example:
        filter:
          entity_id: 1a2b3c4d-5e6f-7890-abcd-ef1234567890
          type: ROLE
        per-page: 100
        page: 1
        sort: person_last_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
