openapi: 3.0.0
info:
  title: WorkGroup
  version: 2.0.0
  description: >
    A **WorkGroup** represents a functional grouping within an office.

    There are three types:

    - `JOB`: a **job role / duty** (e.g. welder, crane operator, warehouse
    worker)

    - `WORK_PLACE`: a **work phase / operational area** (e.g. assembly line,
    painting department)

    - `HGROUP`: a **homogeneous exposure group** (e.g. workers exposed to noise)


    Work groups can contain people (WorkGroupPerson), resources like equipment,

    work environments, or substances (WorkGroupEntity), and suppliers
    (WorkGroupSupplier).


    A work group can be subject to check actions on the compliance schedule.

    In compliance schedule entries (ActionSubscription), the `subscriber_type`
    is `WORK_GROUP`

    and the `subscriber_id` is the `work_group_id`.


    Use this API to:

    - Define job roles, work phases, or homogeneous groups for an office

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

    - Browse work groups for an office (filter by `office_id`)


    Supports historicization.
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
paths:
  /v2/work-group/index:
    post:
      summary: index
      operationId: indexWorkGroup
      tags:
        - WorkGroups
      description: |
        Returns a paginated list of work groups.

        Most useful filters:
        - `office_id`: all work groups in a specific office
        - `work_group_type`: filter by type (`JOB`, `WORK_PLACE`, or `HGROUP`)
        - `name`: search by name
      requestBody:
        description: Parameters for searching work groups
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WorkGroupIndexParams"
            example:
              filter:
                office_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                work_group_type: JOB
              per-page: 20
              page: 1
              sort: name
      responses:
        "200":
          description: List of work groups
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ViewWorkGroup"
          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/work-group/create:
    post:
      summary: create
      operationId: createWorkGroup
      tags:
        - WorkGroups
      description: >
        Creates a new work group in an office.


        Requires `name` and `office_id`.

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


        After creation, assign people via WorkGroupPerson, resources via
        WorkGroupEntity,

        and suppliers via WorkGroupSupplier.
      requestBody:
        description: Work group to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WorkGroup"
      responses:
        "201":
          description: Work group created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkGroup"
  /v2/work-group/view/{id}:
    get:
      summary: view
      operationId: viewWorkGroup
      tags:
        - WorkGroups
      description: Retrieves a single work group by its ID.
      parameters:
        - name: id
          in: path
          description: The work_group_id to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Work group found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewWorkGroup"
        "404":
          description: Work group not found
  /v2/work-group/update/{id}:
    put:
      summary: update
      operationId: updateWorkGroup
      tags:
        - WorkGroups
      description: Updates an existing work group.
      parameters:
        - name: id
          in: path
          description: The work_group_id to update.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WorkGroup"
      responses:
        "200":
          description: Work group updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkGroup"
        "404":
          description: Work group not found
  /v2/work-group/delete/{id}:
    delete:
      summary: delete
      operationId: deleteWorkGroup
      tags:
        - WorkGroups
      description: >
        Deletes a work group.


        If `force=false` (default), the response lists child entities (people,
        resources, suppliers).

        If `force=true`, the work group and all related entities are deleted.
      parameters:
        - name: id
          in: path
          description: The work_group_id to delete.
          required: true
          schema:
            type: string
            format: uuid
        - name: force
          in: query
          description: If true, deletes the work group and all child entities.
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Work group deleted successfully
        "400":
          description: Preview of entities that would be deleted (returned when force=false)
components:
  schemas:
    WorkGroup:
      type: object
      required:
        - name
        - office_id
      properties:
        work_group_id:
          type: string
          format: uuid
          description: >
            Unique identifier. Auto-generated if not provided. Used as
            `subscriber_id` (with `subscriber_type: WORK_GROUP`) in the
            compliance schedule and as `resource_id` in certificates.
        code:
          type: string
          maxLength: 45
          description: Identifier code.
        name:
          type: string
          maxLength: 255
          description: Name of the work group.
        description:
          type: string
          nullable: true
          description: Optional description.
        office_id:
          type: string
          format: uuid
          description: The office this work group belongs to. Pass the `office_id`.
        work_group_type:
          type: string
          maxLength: 50
          enum:
            - WORK_PLACE
            - HGROUP
            - JOB
          description: >
            Type of work group:

            - `JOB`: a job role or duty (e.g. welder, crane operator)

            - `WORK_PLACE`: a work phase or operational area (e.g. assembly
            line)

            - `HGROUP`: a homogeneous exposure group (e.g. workers exposed to
            noise)
    ViewWorkGroup:
      type: object
      properties:
        work_group_id:
          type: string
          format: uuid
          description: Unique identifier. Used as `subscriber_id` (WORK_GROUP) or
            `resource_id`.
        code:
          type: string
        name:
          type: string
        description:
          type: string
        office_id:
          type: string
          format: uuid
        work_group_type:
          type: string
          enum:
            - WORK_PLACE
            - HGROUP
            - JOB
          description: Type of work group.
        project_id:
          type: string
          format: uuid
          description: The project (company) this work group belongs to.
        project_name:
          type: string
          description: Name of the project.
        project_type:
          type: string
          enum:
            - safety
            - template
        office_name:
          type: string
          description: Name of the office.
        owned_active:
          type: boolean
          nullable: true
          description: Whether this work group is currently active.
        parent_active:
          type: boolean
          nullable: true
          description: Whether the parent office is currently active.
    WorkGroupIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/ViewWorkGroup"
        per-page:
          type: integer
          minimum: 1
          default: 100
        page:
          type: integer
          minimum: 1
          default: 1
        sort:
          type: string
          enum:
            - code
            - name
            - work_group_type
            - office_name
        history:
          type: boolean
          description: If true, includes historicized entries.
      example:
        filter:
          office_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          work_group_type: JOB
        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
