openapi: 3.1.0
info:
  title: TM Creator APIs
  version: 1.0.0
  description: |
    Consolidated API documentation for the TM Creator service — project creation,
    management, templates, and file uploads.

    ### Authentication
    All endpoints require an API key passed in the `apikey` request header.

    ### Integration Flows

    #### Flow 1: Form-based Project Creation
    For simple, template-based, or XML-based project creation using `multipart/form-data`:

    ```
    ┌─────────────────────────────────────────────────────────────┐
    │  Client                                                     │
    │    │                                                        │
    │    ├── POST /tm/api/v1/projects/create/simple               │
    │    │     └─ Form fields + optional file attachment           │
    │    │                                                        │
    │    ├── POST /tm/api/v1/projects/create/from-template        │
    │    │     └─ templateId + scheduling + distribution params    │
    │    │                                                        │
    │    ├── POST /tm/api/v1/projects/create/from-xml             │
    │    │     └─ domainId + XML file                             │
    │    │                                                        │
    │    └── POST /tm/api/v1/projects/create/plan-from-xml        │
    │          └─ domainId + XML file                             │
    └─────────────────────────────────────────────────────────────┘
    ```

    These endpoints accept all data in a single request and return a project ID on success.

    #### Flow 2: Structured Project Creation (JSON-based, two-step)
    For advanced project creation with tasks, feedback questionnaires, rollout rules,
    and pre-uploaded attachments:

    ```
    ┌────────────────────────────────────────────────────────────────────────┐
    │  Step 1 (Optional): Upload files                                       │
    │                                                                        │
    │    POST /tm/v1/uploads                                                 │
    │      Content-Type: multipart/form-data                                 │
    │      Body: { files: [binary, binary, ...] }                            │
    │      Response: { items: [{ resource_id: "res_abc..." }, ...] }          │
    │                                                                        │
    │    ⮕ resource_ids are valid for 24 hours                               │
    │                                                                        │
    ├────────────────────────────────────────────────────────────────────────┤
    │  Step 2: Create project                                                │
    │                                                                        │
    │    POST /tm/v1/projects                                                │
    │      Content-Type: application/json                                    │
    │      Headers: Idempotency-Key: <uuid>                                  │
    │      Body: {                                                           │
    │        title, type, schedule, assignees, rollout,                       │
    │        tasks, feedback_questions,                                       │
    │        attachments: [{ type: "file", resource_id: "res_abc..." }]      │
    │      }                                                                 │
    │      Response: { id: "prj_123", status: "created" }                    │
    └────────────────────────────────────────────────────────────────────────┘
    ```

    If no file attachments are needed, skip Step 1 and call Step 2 directly.
    URL attachments (external links) do not require a prior upload.

    #### Flow 3: Project Lifecycle Actions
    After a project is created, use these endpoints to manage it:

    ```
    GET  /tm/api/v1/project/status     → Check current project status
    GET  /tm/api/v1/project/notes      → Retrieve project/task notes
    POST /tm/api/v1/projects/action/update  → Recall / Withdraw / Complete
    POST /tm/api/v1/projects/action/delete  → Delete pre-launch projects
    ```

    #### Flow 4: Discovery (Templates & Project Types)
    Before creating a project, query available templates and project types:

    ```
    GET /tm/api/v1/project-types       → List all available project types
    GET /tm/api/v1/templates           → List templates (filter by type, title, etc.)
    GET /tm/api/v1/templates/task      → List templates with their task definitions
    ```

servers:
  - url: https://dev-api.zebra.com
    description: Development Environment
  - url: https://test-api1.zebra.com
    description: Test Environment

security:
  - ApiKeyAuth: []

paths:
  # ──────────────────────────────────────────────
  #  Form-based Project Creation
  # ──────────────────────────────────────────────

  /tm/api/v1/projects/create/simple:
    post:
      summary: Create Simple Project
      description: Create a simple project in Task Manager.
      operationId: createSimpleProject
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - messageType
                - projectTitle
                - startDate
                - endDate
                - userId
                - assignDept
                - assignTo
              properties:
                messageType:
                  type: string
                  description: Project Type ID
                projectTitle:
                  type: string
                  description: Project Title
                startDate:
                  type: string
                  format: date
                  description: Project Start Date
                  example: Date in System Date Format
                endDate:
                  type: string
                  format: date
                  description: Project End Date
                  example: Date in System Date Format
                priority:
                  type: string
                  description: Project Priority
                unitId:
                  type: string
                  description: Comma separated Unit IDs
                listId:
                  type: string
                  description: Comma separated Distribution List IDs
                userId:
                  type: string
                  description: Creator's User ID
                assignDept:
                  type: string
                  description: Project responsible department
                assignTo:
                  type: string
                  description: Project responsible profile ID
                assignUser:
                  type: string
                  description: Project assigned to specific user
                attachURL:
                  type: string
                  description: Comma separated URLs to be attached
                file:
                  type: string
                  format: binary
                  description: File attachments
                projNotes:
                  type: string
                  description: Project Notes
                execLevel:
                  type: string
                  description: Project Execution Level
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectSuccessResponse'
              example:
                status: SUCCESS
                data:
                  projectId: "12345"
                  assignedTo: "SM"
                  projectTitle: "Floor security: Use of safety equipment"
                message: "4011215 - Project successfully submitted to queue."
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorResponse'
              example:
                status: ERROR
                error:
                  - code: "1005"
                    message: "Please Provide Unit Id OR List Id"

  /tm/api/v1/projects/create/from-template:
    post:
      summary: Create Project from Template
      description: Create projects using a template.
      operationId: createProjectFromTemplate
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - templateId
                - startDate
                - endDate
                - unitId
                - userId
                - assignDept
                - assignTo
              properties:
                templateId:
                  type: string
                  description: Template Id
                projectTitle:
                  type: string
                  description: Project name
                projType:
                  type: string
                  description: Project type Id
                startDate:
                  type: string
                  format: date
                  description: Project start date
                  example: Date in System Date Format
                endDate:
                  type: string
                  format: date
                  description: Project end date
                  example: Date in System Date Format
                unitId:
                  type: string
                  description: Comma separated list of units for distribution
                userId:
                  type: string
                  description: Creator user id
                assignDept:
                  type: string
                  description: Assign to Dept
                assignTo:
                  type: string
                  description: Assign to Profile
                execLevel:
                  type: string
                  description: Project execution level
                additionalInfo:
                  type: string
                  description: Additional info
                projNotes:
                  type: string
                  description: Project notes
                priority:
                  type: string
                  description: Project priority
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectSuccessResponse'
              example:
                status: SUCCESS
                data:
                  projectId: "12345"
                  assignedTo: "SM"
                  projectTitle: "Floor security: Use of safety equipment"
                message: "4011215 - Project successfully submitted to queue."
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorResponse'
              example:
                status: ERROR
                error:
                  - code: "835"
                    message: "Invalid Input Parameters"

  /tm/api/v1/projects/create/from-xml:
    post:
      summary: Create Project from XML
      description: Project creation using XML file.
      operationId: createProjectFromXml
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - domainId
                - xml
              properties:
                domainId:
                  type: string
                  description: Domain Id
                xml:
                  type: string
                  format: binary
                  description: XML File
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: SUCCESS
                  data:
                    type: object
                    properties:
                      projectId:
                        type: string
                        example: "12345"
                  message:
                    type: string
                    example: "Project Created Successfully"
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorResponse'
              example:
                status: ERROR
                error:
                  - code: "835"
                    message: "Invalid Input Parameters"

  /tm/api/v1/projects/create/plan-from-xml:
    post:
      summary: Create Plan from XML
      description: Plan creation using XML file.
      operationId: createPlanFromXml
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - domainId
                - xml
              properties:
                domainId:
                  type: string
                  description: Domain Id
                xml:
                  type: string
                  format: binary
                  description: XML File
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: SUCCESS
                  data:
                    type: object
                    properties:
                      projectId:
                        type: string
                        example: "12345"
                  message:
                    type: string
                    example: "Plan Created Successfully"
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorResponse'
              example:
                status: ERROR
                error:
                  - code: "835"
                    message: "Invalid Input Parameters"

  # ──────────────────────────────────────────────
  #  Project Actions
  # ──────────────────────────────────────────────

  /tm/api/v1/projects/action/delete:
    post:
      summary: Delete Project
      description: Delete a pre-launch project based on provided Project Id list.
      operationId: deleteProject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - projectIds
              properties:
                projectIds:
                  type: string
                  description: Comma separated Project Ids
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: SUCCESS
                  message:
                    type: string
                    example: "Project deleted successfully"
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorResponse'
              example:
                status: ERROR
                error:
                  - code: "839"
                    message: "projectId not provided."

  /tm/api/v1/projects/action/update:
    post:
      summary: Update Project Action
      description: Take action on a project and generate change request internally.
      operationId: updateProjectAction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - projectId
                - actionFlag
              properties:
                projectId:
                  type: string
                  description: Initiative Id of project
                actionFlag:
                  type: string
                  description: "Project Action Flag (R/W/C for Recall/Withdraw/Complete)"
                prjReason:
                  type: string
                  description: Reason for Action
                prjComment:
                  type: string
                  description: Comment for Action
                extIdentifier:
                  type: string
                  description: Project Identifier
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: SUCCESS
                  message:
                    type: string
                    example: "The changes are applied successfully."
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorResponse'
              example:
                status: ERROR
                error:
                  - code: "1010"
                    message: "Error: Given action is not applicable"

  # ──────────────────────────────────────────────
  #  Templates
  # ──────────────────────────────────────────────

  /tm/api/v1/templates:
    get:
      summary: Get Template List
      description: Retrieve Template list.
      operationId: getTemplates
      parameters:
        - in: query
          name: messageType
          schema:
            type: string
          description: Project Type ID
        - in: query
          name: templateId
          schema:
            type: string
          description: Project Template ID
        - in: query
          name: projectTitle
          schema:
            type: string
          description: Template title
        - in: query
          name: execLevel
          schema:
            type: string
          description: Project Execution Level
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: SUCCESS
                  message:
                    type: string
                    example: "Query Successful"
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        projectType:
                          type: string
                          example: "PPT"
                        templateId:
                          type: string
                          example: "4001303"
                        templateName:
                          type: string
                          example: "Test program project template 25122020"
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorResponse'
              example:
                status: ERROR
                error:
                  - code: "1019"
                    message: "No Data Found"

  /tm/api/v1/templates/task:
    get:
      summary: Get Template List with Tasks
      description: Retrieve Template list with tasks associated using template Id or template title.
      operationId: getTemplatesWithTasks
      parameters:
        - in: query
          name: messageType
          schema:
            type: string
          description: Project Type ID
        - in: query
          name: templateId
          schema:
            type: string
          description: Project Template ID
        - in: query
          name: projectTitle
          schema:
            type: string
          description: Template title
        - in: query
          name: execLevel
          schema:
            type: string
          description: Project Execution Level
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: SUCCESS
                  message:
                    type: string
                    example: "Query Successful"
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        templateName:
                          type: string
                          example: "test split attach 2205 Nk template"
                        projectType:
                          type: string
                          example: "NXL"
                        templateId:
                          type: string
                          example: "10283200"
                        tasks:
                          type: array
                          items:
                            type: object
                            properties:
                              taskTitle:
                                type: string
                                example: "task1"
                              taskId:
                                type: string
                                example: "1667550868077"
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorResponse'
              example:
                status: ERROR
                error:
                  - code: "1019"
                    message: "No Data Found"

  # ──────────────────────────────────────────────
  #  Project Queries
  # ──────────────────────────────────────────────

  /tm/api/v1/project/notes:
    get:
      summary: Retrieve Project/Task Notes
      description: Retrieve notes of a project or task.
      operationId: getProjectNotes
      parameters:
        - in: query
          name: projectId
          required: true
          schema:
            type: string
          description: Initiative Id
        - in: query
          name: taskId
          schema:
            type: string
          description: Task Id
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Query Successful"
                  status:
                    type: string
                    example: SUCCESS
                  data:
                    type: object
                    properties:
                      notes:
                        type: string
                        description: HTML-formatted project/task notes.
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorResponse'
              example:
                status: ERROR
                error:
                  - code: "839"
                    message: "projectId not provided."

  /tm/api/v1/project/status:
    get:
      summary: Get Project Status
      description: Retrieve project status using a Project Id.
      operationId: getProjectStatus
      parameters:
        - in: query
          name: projectId
          required: true
          schema:
            type: string
          description: Project Id
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Query Successful"
                  status:
                    type: string
                    example: SUCCESS
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        example: "In Progress"
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorResponse'
              example:
                status: ERROR
                error:
                  - code: "839"
                    message: "projectId not provided."

  /tm/api/v1/project-types:
    get:
      summary: Get Project Type List
      description: Retrieve list of project types.
      operationId: getProjectTypes
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: SUCCESS
                  message:
                    type: string
                    example: "Query Successful"
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        projectType:
                          type: string
                          example: "ZX"
                        description:
                          type: string
                          example: "MESSAGING PROJECT"
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorResponse'
              example:
                status: ERROR
                error:
                  - code: "1020"
                    message: "Error while processing request"

  # ──────────────────────────────────────────────
  #  File Uploads (for /tm/v1/projects flow)
  # ──────────────────────────────────────────────

  /tm/v1/uploads:
    post:
      summary: Upload Attachments
      description: |
        Securely upload binary files directly to the server.
        Returns an array of `resource_id`s valid for 24 hours.
        These `resource_id`s are referenced in the `POST /tm/v1/projects` payload.

        **Required permission:** `projects:create`
      operationId: uploadAttachments
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/XRequestId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [files]
              properties:
                files:
                  type: array
                  description: Array of files. Max 10 files per request, max 25 MB each.
                  minItems: 1
                  maxItems: 10
                  items:
                    type: string
                    format: binary
      responses:
        '201':
          description: Upload successful.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  # ──────────────────────────────────────────────
  #  Structured Project Creation (JSON)
  # ──────────────────────────────────────────────

  /tm/v1/projects:
    post:
      summary: Create Project
      description: |
        Creates a new project entity with optional tasks and feedback questionnaires,
        and rolls it out to the specified organizational units.

        **Required permission:** `projects:create`

        ---

        ### Business Rules

        Many fields and features are controlled by the **project type configuration** —
        a set of properties configured per project type in the admin UI. The server validates
        all fields against this configuration and returns `422 Unprocessable Entity` when
        business rules are violated.

        Key project type properties that affect validation:

        | Property | Effect |
        |----------|--------|
        | "Define Tasks?" / "Mandatory Tasks?" | Whether `tasks` array can or must be included |
        | "Allow Project Notes and Attachments?" / "Notes are mandatory" | Whether `description` is required |
        | "Allow Project Tags?" | Whether `tags` are persisted |
        | "Allow multiple assignments at project level?" | Single vs multiple entries in `assignees.role_departments` |
        | "Collect working days required for the project?" | Whether `schedule.working_days` is required |
        | "Auto complete project?" / "Configurable at project level" | Whether `auto_complete_days` is honored |
        | "Confidential?" / "Configurable at project level" | Whether `is_confidential` is honored |
        | "Allow user to collect feedback on project/task completion?" | Whether `feedback_questions` / `external_form` are accepted |
        | "Collect project identifier?" | Whether `ref_id` is persisted |
        | "Allow efforts to be defined at project level?" | Whether `effort_minutes` is accepted |
        | "Time-sensitive project? -> Configurable at project level" | Whether `schedule.is_time_sensitive` is honored |

        ### Validation Constraints

        - `feedback_questions` and `external_form` are **mutually exclusive** — provide one or neither.
        - When task-level efforts are provided, their sum must not exceed project-level `effort_minutes`.
        - Task scheduling mode 2: `start_day + days_required - 1` must not exceed `schedule.working_days`.
        - `schedule.start_at` and `schedule.finish_at` must not be in the past and must not exceed the max fiscal calendar date.
        - All `role_id` + `department_id` combinations in `assignees` must be valid and active at the project's execution level.
        - Rollout units must exist at the specified `execution_level`.
        - `Idempotency-Key` header is required; reusing a key with a different payload returns `409 Conflict`.
      operationId: createProject
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/XRequestId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectCreateRequest'
            examples:
              SimpleProject:
                $ref: '#/components/examples/SimpleProject'
              RecurringProject:
                $ref: '#/components/examples/RecurringProject'
              ActionableProjectWithTasks:
                $ref: '#/components/examples/ActionableProjectWithTasks'
              MultipleAssignments:
                $ref: '#/components/examples/MultipleAssignments'
              TimeSensitiveSchedule:
                $ref: '#/components/examples/TimeSensitiveSchedule'
              AttachmentsAndUrls:
                $ref: '#/components/examples/AttachmentsAndUrls'
              RolloutOptions:
                $ref: '#/components/examples/RolloutOptions'
              FeedbackQuestions:
                $ref: '#/components/examples/FeedbackQuestions'
              ExternalIdAndMetadata:
                $ref: '#/components/examples/ExternalIdAndMetadata'
              TaskScheduleModes:
                $ref: '#/components/examples/TaskScheduleModes'
              TaskFeedbackAndAttachments:
                $ref: '#/components/examples/TaskFeedbackAndAttachments'
              Prerequisites:
                $ref: '#/components/examples/Prerequisites'
              ExternalForm:
                $ref: '#/components/examples/ExternalForm'
              AdditionalAttributes:
                $ref: '#/components/examples/AdditionalAttributes'
              TemplateBasedProject:
                $ref: '#/components/examples/TemplateBasedProject'
      responses:
        '201':
          description: Project successfully created.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Location:
              description: URI of the newly created project.
              schema:
                type: string
                example: /tm/v1/projects/prj_abc123
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

# ════════════════════════════════════════════════
#  COMPONENTS
# ════════════════════════════════════════════════

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: API key passed in the `apikey` request header.

  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        format: uuid
      description: Prevents duplicate creations on network retries. Resubmitting the same key + payload returns the original 201 response. Keys expire after 24 hours.
    XRequestId:
      name: X-Request-Id
      in: header
      required: false
      schema:
        type: string
        format: uuid
      description: Client-generated correlation ID for distributed tracing. Echoed in the response.

  headers:
    XRequestId:
      description: Echoed correlation ID from the request.
      schema:
        type: string
        format: uuid

  schemas:
    # ── Shared simple response schemas ──

    ProjectSuccessResponse:
      type: object
      properties:
        status:
          type: string
          example: SUCCESS
        data:
          type: object
          properties:
            projectId:
              type: string
              example: "12345"
            assignedTo:
              type: string
              example: "SM"
            projectTitle:
              type: string
              example: "Floor security: Use of safety equipment"
        message:
          type: string
          example: "4011215 - Project successfully submitted to queue."

    LegacyErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: ERROR
        error:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string

    # ── Schemas for POST /tm/v1/projects ──

    ProjectCreateRequest:
      type: object
      required:
        - title
        - type
        - assignees
      properties:
        template_id:
          type: string
          description: Project ID of an existing project marked as a template. Base data (tasks, feedback, attachments, rollout, assignments, etc.) is copied from this project. Omit to create from scratch.
        title:
          type: string
          maxLength: 250
          description: Short, human-readable project name. HTML entities are unescaped and processed on ingestion. For recurring project types, the system may append a frequency suffix (e.g., "Weekly"), so keep titles under ~240 characters to avoid truncation.
        type:
          type: string
          minLength: 2
          maxLength: 4
          pattern: '^[A-Z0-9]{2,4}$'
          description: Project type code (2-4 uppercase letters or digits). Must match an active project type configured in the system.
        execution_level:
          type: integer
          minimum: 1
          description: Organizational hierarchy level number at which this project is executed (1 = Corporate level, max = store level). Defaults to the maximum org level (store) if omitted.
        description:
          type: string
          maxLength: 4000
          description: Rich-text body (project notes). Supports a safe subset of HTML and Markdown. May be mandatory depending on project type configuration.
        category:
          type: string
          description: Primary category for the project. Must match a category defined in the project type configuration.
        subcategory:
          type: string
          description: Subcategory within the primary category. Validated in combination with `category`.
        priority:
          type: integer
          minimum: 1
          description: Priority ID (typically 1-4). Defaults to the project type's configured default priority if omitted.
        tags:
          type: array
          maxItems: 20
          description: Free-form labels for filtering and search. Only persisted when the project type property "Allow Project Tags?" is enabled.
          items:
            type: string
            maxLength: 50
        is_confidential:
          type: boolean
          default: false
          description: Restricts project visibility to assigned users only. Only honored when the project type allows override.
        creator_department_id:
          type: string
          description: Department ID of the project creator. If omitted, derived from the authenticated user's profile.
        schedule:
          $ref: '#/components/schemas/Schedule'
        recurrence:
          $ref: '#/components/schemas/Recurrence'
        assignees:
          $ref: '#/components/schemas/Assignees'
        rollout:
          type: array
          maxItems: 5
          description: Where the project applies. Each rule defines a set of organizational units. Defaults to the creator's own unit if omitted.
          items:
            $ref: '#/components/schemas/RolloutRule'
        attachments:
          type: array
          maxItems: 10
          description: File or URL attachments for the project.
          items:
            $ref: '#/components/schemas/Attachment'
        tasks:
          type: array
          maxItems: 30
          description: Ordered list of tasks within the project. At least one task is required when the project type property "Mandatory Tasks?" is enabled.
          items:
            $ref: '#/components/schemas/TaskItem'
        feedback_questions:
          type: array
          maxItems: 50
          description: Inline feedback questionnaire. Mutually exclusive with `external_form`. Only applicable when the project type property "Allow user to collect feedback on project completion?" is enabled.
          items:
            $ref: '#/components/schemas/FeedbackQuestion'
        external_form:
          $ref: '#/components/schemas/ExternalForm'
        effort_minutes:
          type: integer
          minimum: 1
          description: Estimated effort to complete the project, in minutes.
        auto_complete_days:
          type: integer
          minimum: 1
          description: Number of days after the finish date to auto-complete the project. Omit to disable.
        notifications:
          $ref: '#/components/schemas/Notifications'
        prerequisites:
          type: array
          maxItems: 20
          description: Answers to prerequisite questions defined by the project type.
          items:
            $ref: '#/components/schemas/Prerequisite'
        ref_id:
          type: string
          maxLength: 256
          description: Client-supplied reference identifier for the project (e.g., ERP work-order ID).
        metadata:
          type: object
          additionalProperties: true
          maxProperties: 50
          description: Arbitrary key-value pairs for supplementary data. Maximum payload size is 8 KB.

    Schedule:
      type: object
      description: Project schedule. `finish_at` is required for non-recurring project types.
      properties:
        start_at:
          type: string
          format: date-time
          description: Project start date-time (ISO 8601 UTC). Must not be in the past. Defaults to current server time if omitted.
        finish_at:
          type: string
          format: date-time
          description: Project finish date-time (ISO 8601 UTC). Must be after `start_at` and must not be in the past.
        visibility:
          $ref: '#/components/schemas/Visibility'
        working_days:
          type: integer
          minimum: 1
          maximum: 999
          description: Total number of working days for the project. Required when the project type property "Collect working days required for the project?" is enabled.
        is_time_sensitive:
          type: boolean
          description: Caller-supplied time-sensitive flag. Honoured only when the project type exposes a "Time-sensitive project? -> Configurable at project level" override.

    Visibility:
      type: object
      required: [mode]
      description: Controls when the project becomes visible in the user's feed. Not applicable for `REP` (recurring) type projects.
      properties:
        mode:
          type: string
          enum: [immediate, overnight, on_specific_date, days_before_start]
          default: immediate
          description: |
            - `immediate`: Visible as soon as the project is created.
            - `overnight`: Visible after the next overnight processing run.
            - `on_specific_date`: Visible at the date-time specified in `visible_at`.
            - `days_before_start`: Visible N days before `start_at`, controlled by `day_offset`.
        visible_at:
          type: string
          format: date-time
          description: Visibility date-time (ISO 8601 UTC). Required when mode is `on_specific_date`.
        day_offset:
          type: integer
          minimum: 1
          description: Number of days before `start_at` to make the project visible. Required when mode is `days_before_start`.

    Assignees:
      type: object
      required: [role_departments]
      description: Defines who is responsible for the project or task using role-department intersection logic.
      properties:
        role_departments:
          type: array
          minItems: 1
          items:
            type: object
            required: [role_id, department_id]
            properties:
              role_id:
                type: string
                description: The role identifier. Must be a valid, active role at the project's execution level.
              department_id:
                type: string
                description: The department identifier. Must be a valid, active department at the project's execution level.

    RolloutRule:
      type: object
      discriminator:
        propertyName: type
        mapping:
          all: '#/components/schemas/RolloutAll'
          specific: '#/components/schemas/RolloutSpecific'
          group: '#/components/schemas/RolloutByGroup'
          attributes: '#/components/schemas/RolloutByAttributes'

    RolloutAll:
      type: object
      required: [type]
      description: Roll out to all units at the project's execution level.
      properties:
        type:
          type: string
          enum: [all]
        name:
          type: string
          maxLength: 64

    RolloutSpecific:
      type: object
      required: [type, units]
      description: Roll out to an explicit list of units.
      properties:
        type:
          type: string
          enum: [specific]
        name:
          type: string
          maxLength: 64
        units:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/RolloutUnit'

    RolloutUnit:
      type: object
      required: [id]
      description: A target unit. All units inherit the project-level dates.
      properties:
        id:
          type: string
          maxLength: 64
          description: Unit identifier (e.g., store ID).

    RolloutByGroup:
      type: object
      required: [type, group_ids]
      description: Roll out to all units in the specified groups (distribution lists).
      properties:
        type:
          type: string
          enum: [group]
        name:
          type: string
          maxLength: 64
        group_ids:
          type: array
          minItems: 1
          items:
            type: string
            maxLength: 64

    RolloutByAttributes:
      type: object
      required: [type, conditions]
      description: Roll out to units matching attribute-based conditions.
      properties:
        type:
          type: string
          enum: [attributes]
        name:
          type: string
          maxLength: 64
        operator:
          type: string
          enum: [and, or]
          description: Logical operator to combine multiple conditions. Required when `conditions` contains 2+ items.
        conditions:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/AttributeCondition'

    AttributeCondition:
      type: object
      required: [attribute_name, attribute_values]
      properties:
        attribute_name:
          type: string
          maxLength: 64
        attribute_values:
          type: array
          minItems: 1
          items:
            type: string
            maxLength: 128

    TaskItem:
      type: object
      required: [ref_id, title]
      description: A task within the project with its own schedule, assignees, attachments, and feedback.
      properties:
        ref_id:
          type: string
          maxLength: 64
          description: Client-supplied reference identifier. Must be unique within the project.
        title:
          type: string
          maxLength: 300
        priority:
          type: integer
          minimum: 1
          description: Task-level priority ID. Inherits from project priority if omitted.
        assignees:
          $ref: '#/components/schemas/Assignees'
        schedule:
          $ref: '#/components/schemas/TaskSchedule'
        effort_minutes:
          type: integer
          minimum: 1
        attachments:
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/Attachment'
        feedback_questions:
          type: array
          maxItems: 50
          items:
            $ref: '#/components/schemas/FeedbackQuestion'
        external_form:
          $ref: '#/components/schemas/ExternalForm'
        optional:
          $ref: '#/components/schemas/TaskOptional'

    TaskSchedule:
      type: object
      description: |
        Task timing — two modes:
        - Mode 1 (Absolute): provide `start_at` and `finish_at`.
        - Mode 2 (Relative): provide `start_day` and `days_required` (relative to project working days).
      properties:
        start_at:
          type: string
          format: date-time
        finish_at:
          type: string
          format: date-time
        start_day:
          type: integer
          minimum: 1
          description: 1-based day number within the project's working days.
        days_required:
          type: integer
          minimum: 1
          maximum: 999

    TaskOptional:
      type: object
      description: When present, this task only applies to stores matching the attribute conditions.
      properties:
        operator:
          type: string
          enum: [and, or]
        conditions:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/AttributeCondition'

    Attachment:
      type: object
      discriminator:
        propertyName: type
        mapping:
          file: '#/components/schemas/FileAttachment'
          url: '#/components/schemas/UrlAttachment'

    FileAttachment:
      type: object
      required: [type, resource_id, original_filename]
      description: Reference to a previously uploaded file.
      properties:
        type:
          type: string
          enum: [file]
        resource_id:
          type: string
          maxLength: 128
          description: The `resource_id` returned from the upload endpoint.
        original_filename:
          type: string
          maxLength: 255

    UrlAttachment:
      type: object
      required: [type, name, url]
      description: A URL link attachment.
      properties:
        type:
          type: string
          enum: [url]
        name:
          type: string
          maxLength: 255
        url:
          type: string
          format: uri
          maxLength: 2048

    Recurrence:
      type: object
      required: [frequency, range_type]
      description: Defines a repeating schedule for `REP` type projects. Omit entirely for one-time projects.
      properties:
        frequency:
          type: string
          enum: [daily, weekly, monthly, yearly, bi_weekly, fiscal_daily, fiscal_weekly, fiscal_periodic, fiscal_quarterly, fiscal_yearly]
        interval:
          type: integer
          minimum: 1
          default: 1
          description: Repeat every N periods. Applicable for calendar-based frequencies.
        days_of_week:
          type: array
          items:
            type: string
            enum: [mon, tue, wed, thu, fri, sat, sun]
        day_of_month:
          type: integer
          minimum: 1
          maximum: 31
        week_index:
          type: string
          enum: [first, second, third, fourth, last]
        month:
          type: integer
          minimum: 1
          maximum: 12
          description: Required for `yearly` frequency.
        range_type:
          type: string
          enum: [end_date, numbered, no_end]
          description: |
            - `end_date`: Stops on `ends_at`.
            - `numbered`: Stops after `occurrences` instances.
            - `no_end`: Indefinite recurrence.
        ends_at:
          type: string
          format: date-time
          description: Required when `range_type` is `end_date`.
        occurrences:
          type: integer
          minimum: 1
          description: Required when `range_type` is `numbered`.

    FeedbackQuestion:
      type: object
      discriminator:
        propertyName: response_type
        mapping:
          text: '#/components/schemas/FeedbackQuestionText'
          single_choice: '#/components/schemas/FeedbackQuestionSingleChoice'
          multiple_choice: '#/components/schemas/FeedbackQuestionMultipleChoice'
          number: '#/components/schemas/FeedbackQuestionNumber'
          boolean: '#/components/schemas/FeedbackQuestionBoolean'

    FeedbackQuestionBase:
      type: object
      required: [question_text, response_type]
      properties:
        question_text:
          type: string
          maxLength: 1000
        response_type:
          type: string
        is_mandatory:
          type: boolean
          default: false
        attributes:
          $ref: '#/components/schemas/FeedbackQuestionAttributes'

    FeedbackQuestionText:
      allOf:
        - $ref: '#/components/schemas/FeedbackQuestionBase'
        - type: object
          properties:
            response_type:
              type: string
              enum: [text]

    FeedbackQuestionNumber:
      allOf:
        - $ref: '#/components/schemas/FeedbackQuestionBase'
        - type: object
          properties:
            response_type:
              type: string
              enum: [number]
            allow_decimal:
              type: boolean
              default: false
            min_value:
              type: number
            max_value:
              type: number
            value_type:
              type: string
              enum: [digit, range]
              default: digit
              description: |
                - `digit`: Respondent enters a single numeric value.
                - `range`: Respondent selects within a min/max range.

    FeedbackQuestionBoolean:
      allOf:
        - $ref: '#/components/schemas/FeedbackQuestionBase'
        - type: object
          properties:
            response_type:
              type: string
              enum: [boolean]

    FeedbackQuestionSingleChoice:
      allOf:
        - $ref: '#/components/schemas/FeedbackQuestionBase'
        - type: object
          required: [options]
          properties:
            response_type:
              type: string
              enum: [single_choice]
            options:
              type: array
              minItems: 2
              maxItems: 100
              items:
                $ref: '#/components/schemas/FeedbackOption'

    FeedbackQuestionMultipleChoice:
      allOf:
        - $ref: '#/components/schemas/FeedbackQuestionBase'
        - type: object
          required: [options]
          properties:
            response_type:
              type: string
              enum: [multiple_choice]
            options:
              type: array
              minItems: 2
              maxItems: 100
              items:
                $ref: '#/components/schemas/FeedbackOption'

    FeedbackOption:
      type: object
      required: [ref_id, option_text]
      properties:
        ref_id:
          type: string
          maxLength: 64
        option_text:
          type: string
          maxLength: 255
        is_default:
          type: boolean
          default: false

    FeedbackQuestionAttributes:
      type: object
      properties:
        allow_attachments:
          type: boolean
          default: false
        mandatory_attachments:
          type: boolean
          default: false
          description: Setting to true implies `allow_attachments` is true.

    ExternalForm:
      type: object
      required: [form_id, title]
      description: Reference to an externally managed form/questionnaire. Mutually exclusive with `feedback_questions`.
      properties:
        form_id:
          type: string
          maxLength: 128
        title:
          type: string
          maxLength: 200

    Prerequisite:
      type: object
      required: [question_id, answer]
      description: Answer to a prerequisite question defined by the project type.
      properties:
        question_id:
          type: integer
          minimum: 1
        answer:
          type: string
          maxLength: 4000
          description: |
            Format depends on question type:
            - Text (single-line): free-text string, max 200 characters.
            - Text (multi-line): free-text string, max 4000 characters.
            - Numeric: integer as a string (e.g., "42").
            - Yes/No: "Y" or "N".
            - Single choice: option number as a string (e.g., "3").
            - Multiple choice: comma-separated option numbers (e.g., "1,3,5").

    Notifications:
      type: object
      description: Email notification settings for the project.
      properties:
        email_addresses:
          type: array
          items:
            type: string
            format: email
            maxLength: 255
        mailing_list_ids:
          type: array
          items:
            type: string
            maxLength: 128

    # ── Response schemas for /tm/v1/* ──

    UploadResponse:
      type: object
      properties:
        object:
          type: string
          enum: [list]
        expires_at:
          type: string
          format: date-time
          description: When the uploaded resource_ids expire (ISO 8601 UTC).
        items:
          type: array
          items:
            $ref: '#/components/schemas/UploadItem'

    UploadItem:
      type: object
      properties:
        resource_id:
          type: string
          description: Temporary ID to reference this file in the project creation payload.
        original_filename:
          type: string
        mime_type:
          type: string
          description: Detected MIME type (e.g., "application/pdf", "image/png").
        size_bytes:
          type: integer

    ProjectResponse:
      type: object
      properties:
        object:
          type: string
          enum: [project]
        id:
          type: string
          description: Unique project identifier.
        type:
          type: string
        template_id:
          type: string
        title:
          type: string
        status:
          type: string
          enum: [created, published, submitted]
        created_at:
          type: string
          format: date-time
        url:
          type: string
          description: Canonical API URL of the created project.
        ref_id:
          type: string
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/TaskItemResponse'

    TaskItemResponse:
      type: object
      properties:
        id:
          type: string
          description: Server-generated unique identifier for this task.
        ref_id:
          type: string
          description: Echoed client-supplied reference ID from the request.

    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [type, code, message]
          properties:
            type:
              type: string
              description: High-level error category.
            code:
              type: string
              description: Machine-readable error code.
            message:
              type: string
              description: Human-readable message.
            param:
              type: string
              description: The specific field that caused the error (dot-notation path).
            doc_url:
              type: string
              format: uri
            errors:
              type: array
              description: Present when multiple fields have errors (batch validation).
              items:
                type: object
                properties:
                  code:
                    type: string
                  param:
                    type: string
                  message:
                    type: string

  responses:
    BadRequest:
      description: Validation error. Required fields missing, invalid dates, or malformed JSON.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: validation_error
              code: invalid_parameter
              message: One or more request parameters are invalid.
              errors:
                - code: required
                  param: title
                  message: "The 'title' field is required."
                - code: invalid_format
                  param: schedule.finish_at
                  message: Must be a valid ISO 8601 UTC date-time.

    Unauthorized:
      description: Missing or invalid authentication.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: authentication_error
              code: unauthorized
              message: "API key is missing or invalid in the 'apikey' request header."

    Forbidden:
      description: Authenticated but insufficient permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: authorization_error
              code: access_denied
              message: You do not have permission to perform this action.

    Conflict:
      description: Idempotency-Key reused with a different request payload.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: idempotency_error
              code: idempotency_key_reused
              message: This Idempotency-Key has already been used with a different request payload.

    UnprocessableEntity:
      description: Request is syntactically valid but violates business rules.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            ExecutionLevelMismatch:
              summary: Execution Level Mismatch
              value:
                error:
                  type: business_rule_violation
                  code: execution_level_mismatch
                  message: Rollout units do not match the specified execution level.
                  param: rollout[0].units[0].id
            InvalidRoleDepartment:
              summary: Invalid Role-Department Assignment
              value:
                error:
                  type: business_rule_violation
                  code: role_department_not_found
                  message: "Role 'team_lead' does not exist within department 'dept_sales', or the combination is inactive."
                  param: assignees.role_departments[0]
            TaskScheduleExceedsWorkingDays:
              summary: Task Schedule Exceeds Working Days
              value:
                error:
                  type: business_rule_violation
                  code: task_schedule_overflow
                  message: "Task start_day (5) + days_required (8) - 1 exceeds project working_days (10)."
                  param: tasks[0].schedule
            MutuallyExclusiveFeedback:
              summary: Mutually Exclusive Feedback
              value:
                error:
                  type: business_rule_violation
                  code: mutually_exclusive_fields
                  message: "Only one of 'feedback_questions' or 'external_form' may be provided, not both."
                  param: external_form

    PayloadTooLarge:
      description: File size exceeds the 25 MB limit or total upload exceeds server capacity.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: validation_error
              code: payload_too_large
              message: One or more files exceed the 25 MB size limit.

    RateLimited:
      description: Request quota exceeded.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until the client may retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: rate_limit_error
              code: rate_limit_exceeded
              message: Too many requests. Please try again later.

    InternalServerError:
      description: An unexpected server error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: server_error
              code: internal_error
              message: An unexpected error occurred while processing the request.

    ServiceUnavailable:
      description: The service is temporarily unavailable.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Estimated seconds until the service recovers.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: server_error
              code: service_unavailable
              message: The service is temporarily unavailable. Please try again later.

  examples:
    SimpleProject:
      summary: 1. Simple Project - Minimum Required Fields
      value:
        title: Update Price Tags - Aisle 3
        type: ACT
        schedule:
          finish_at: '2026-04-10T17:00:00Z'
        assignees:
          role_departments:
            - role_id: store_associate
              department_id: dept_operations

    RecurringProject:
      summary: 2. Recurring Project - Weekly with End Date
      value:
        title: Weekly Safety Walkthrough
        type: REP
        priority: 2
        schedule:
          start_at: '2026-04-07T08:00:00Z'
          finish_at: '2026-04-07T17:00:00Z'
          working_days: 1
        assignees:
          role_departments:
            - role_id: store_manager
              department_id: dept_operations
        rollout:
          - type: all
        recurrence:
          frequency: weekly
          interval: 1
          days_of_week: [mon]
          range_type: end_date
          ends_at: '2026-12-31T23:59:59Z'
        auto_complete_days: 2

    ActionableProjectWithTasks:
      summary: 3. Actionable Project with Tasks
      value:
        title: New Employee Onboarding - Store 015
        type: ACT
        description: Complete all onboarding steps for the new hire before their first customer-facing shift.
        schedule:
          start_at: '2026-05-01T08:00:00Z'
          finish_at: '2026-05-10T17:00:00Z'
          working_days: 8
        assignees:
          role_departments:
            - role_id: team_lead
              department_id: dept_hr
        effort_minutes: 240
        tasks:
          - ref_id: tsk_orientation
            title: Conduct store orientation tour
            effort_minutes: 60
            schedule:
              start_day: 1
              days_required: 1
          - ref_id: tsk_system_training
            title: Complete POS and inventory system training
            effort_minutes: 120
            schedule:
              start_day: 2
              days_required: 3
          - ref_id: tsk_shadow_shift
            title: Shadow an experienced associate for a full shift
            effort_minutes: 60
            schedule:
              start_day: 5
              days_required: 1

    MultipleAssignments:
      summary: 4. Multiple Role-Department Assignments
      value:
        title: Store Grand Opening Preparation
        type: ACT
        priority: 1
        schedule:
          start_at: '2026-06-01T06:00:00Z'
          finish_at: '2026-06-15T22:00:00Z'
          working_days: 15
        assignees:
          role_departments:
            - role_id: store_manager
              department_id: dept_operations
            - role_id: merchandiser
              department_id: dept_visual_merchandising
            - role_id: team_lead
              department_id: dept_hr
        rollout:
          - type: specific
            units:
              - id: store_099

    TimeSensitiveSchedule:
      summary: 5. Time-Sensitive Schedule
      value:
        title: Limited-Time Promotion Setup
        type: ACT
        schedule:
          start_at: '2026-08-01T06:00:00Z'
          finish_at: '2026-08-01T10:00:00Z'
          is_time_sensitive: true
        assignees:
          role_departments:
            - role_id: merchandiser
              department_id: dept_visual_merchandising
        rollout:
          - type: all

    AttachmentsAndUrls:
      summary: 6. File and URL Attachments
      value:
        title: Planogram Reset - Snack Aisle
        type: ACT
        schedule:
          start_at: '2026-05-12T08:00:00Z'
          finish_at: '2026-05-16T17:00:00Z'
        assignees:
          role_departments:
            - role_id: merchandiser
              department_id: dept_visual_merchandising
        rollout:
          - type: group
            name: Flagship Stores
            group_ids: [grp_flagship_stores]
        attachments:
          - type: file
            resource_id: res_b2c3d4e5-f6a7-8901-2345-bcdef6789012
            original_filename: snack_aisle_planogram_v2.pdf
          - type: url
            name: Brand Guidelines - Snack Partners
            url: https://intranet.wtm.zebra.com/brand/snack-partners-2026

    RolloutOptions:
      summary: 7. Rollout Options - All Types in One Project
      value:
        title: Regional Compliance Audit - All Rollout Types
        type: ACT
        schedule:
          start_at: '2026-09-01T08:00:00Z'
          finish_at: '2026-09-30T18:00:00Z'
        assignees:
          role_departments:
            - role_id: compliance_auditor
              department_id: dept_compliance
        rollout:
          - type: all
            name: All Stores
          - type: specific
            name: Pilot Stores
            units:
              - id: store_101
              - id: store_102
          - type: group
            name: Northeast Flagship + Pilots
            group_ids: [grp_northeast_flagship, grp_pilot_stores]
          - type: attributes
            name: Supercenters and Express
            conditions:
              - attribute_name: store_format
                attribute_values: [supercenter, express]
          - type: attributes
            name: Large Northeast Stores
            operator: and
            conditions:
              - attribute_name: region
                attribute_values: [northeast]
              - attribute_name: size
                attribute_values: [large]

    FeedbackQuestions:
      summary: 8. Feedback Questions - All Response Types
      value:
        title: Customer Experience Survey
        type: ACT
        schedule:
          start_at: '2026-08-01T08:00:00Z'
          finish_at: '2026-08-31T18:00:00Z'
        assignees:
          role_departments:
            - role_id: customer_service_rep
              department_id: dept_customer_service
        feedback_questions:
          - question_text: Rate the overall store cleanliness (1-10).
            response_type: number
            is_mandatory: true
            min_value: 1
            max_value: 10
            allow_decimal: false
            value_type: range
          - question_text: Was the customer greeted within 30 seconds?
            response_type: boolean
            is_mandatory: true
          - question_text: What was the customer's primary concern?
            response_type: single_choice
            is_mandatory: true
            options:
              - ref_id: opt_pricing
                option_text: Pricing
              - ref_id: opt_availability
                option_text: Product availability
              - ref_id: opt_service
                option_text: Customer service
                is_default: true
              - ref_id: opt_other
                option_text: Other
          - question_text: Which areas need improvement? (Select all)
            response_type: multiple_choice
            options:
              - ref_id: opt_checkout
                option_text: Checkout speed
              - ref_id: opt_stock
                option_text: Product stocking
              - ref_id: opt_clean
                option_text: Cleanliness
              - ref_id: opt_staff
                option_text: Staff helpfulness
          - question_text: Additional observations.
            response_type: text
            attributes:
              allow_attachments: true
              mandatory_attachments: true

    ExternalIdAndMetadata:
      summary: 9. External Identifier and Metadata
      value:
        title: Restock Aisle 7 - Cereal and Snacks
        type: ACT
        priority: 2
        ref_id: WMS-2026-03-00482
        metadata:
          source_system: warehouse_management
          work_order_id: WO-90821
          cost_center: CC-4400
          requested_by: scheduler@erp.internal
          sla_tier: standard
        schedule:
          start_at: '2026-03-20T06:00:00Z'
          finish_at: '2026-03-20T14:00:00Z'
        assignees:
          role_departments:
            - role_id: stock_associate
              department_id: dept_warehouse
        rollout:
          - type: specific
            units:
              - id: store_042

    TaskScheduleModes:
      summary: 10. Tasks - Both Scheduling Modes + Optional Task
      value:
        title: Store Renovation Phase 1
        type: ACT
        schedule:
          start_at: '2026-07-01T06:00:00Z'
          finish_at: '2026-07-30T22:00:00Z'
          working_days: 22
        assignees:
          role_departments:
            - role_id: project_lead
              department_id: dept_facilities
        rollout:
          - type: specific
            units:
              - id: store_050
              - id: store_051
        tasks:
          - ref_id: tsk_demolition
            title: Remove old fixtures and flooring
            priority: 2
            effort_minutes: 480
            schedule:
              start_at: '2026-07-01T06:00:00Z'
              finish_at: '2026-07-05T22:00:00Z'
          - ref_id: tsk_electrical
            title: Complete electrical and lighting upgrade
            effort_minutes: 360
            schedule:
              start_day: 4
              days_required: 5
          - ref_id: tsk_pharmacy_refit
            title: Refit pharmacy counter and shelving
            priority: 1
            effort_minutes: 240
            schedule:
              start_day: 6
              days_required: 4
            optional:
              conditions:
                - attribute_name: has_pharmacy
                  attribute_values: ['true']

    TaskFeedbackAndAttachments:
      summary: 11. Tasks with Feedback and Attachments
      value:
        title: Quarterly Inventory Verification
        type: ACT
        schedule:
          start_at: '2026-10-01T08:00:00Z'
          finish_at: '2026-10-15T18:00:00Z'
          working_days: 10
        assignees:
          role_departments:
            - role_id: inventory_auditor
              department_id: dept_loss_prevention
        tasks:
          - ref_id: tsk_count_high_value
            title: Count high-value items in locked cases
            effort_minutes: 90
            schedule:
              start_day: 1
              days_required: 2
            attachments:
              - type: file
                resource_id: res_c4d5e6f7-a8b9-0123-4567-cdef89012345
                original_filename: high_value_item_list.xlsx
              - type: url
                name: Counting Procedures SOP
                url: https://intranet.wtm.zebra.com/sop/inventory-count
            feedback_questions:
              - question_text: Total variance amount in dollars.
                response_type: number
                is_mandatory: true
                min_value: 0
                max_value: 100000
                allow_decimal: true
                value_type: digit
              - question_text: Were any discrepancies found?
                response_type: boolean
                is_mandatory: true
              - question_text: Upload photo evidence of discrepancies.
                response_type: text
                attributes:
                  allow_attachments: true
                  mandatory_attachments: true
          - ref_id: tsk_scan_overstock
            title: Scan and reconcile overstock area
            effort_minutes: 60
            schedule:
              start_day: 3
              days_required: 2

    Prerequisites:
      summary: 12. Prerequisites - Question-Answer Pairs
      value:
        title: Hazardous Material Handling Update
        type: ACT
        priority: 1
        schedule:
          start_at: '2026-06-01T08:00:00Z'
          finish_at: '2026-06-15T17:00:00Z'
        assignees:
          role_departments:
            - role_id: safety_officer
              department_id: dept_compliance
        rollout:
          - type: all
        prerequisites:
          - question_id: 1
            answer: Y
          - question_id: 2
            answer: '3'
          - question_id: 3
            answer: 1,4,5
          - question_id: 4
            answer: All HAZMAT storage units have been inspected and certified within the last 90 days
        notifications:
          email_addresses: [safety-compliance@example.com]
          mailing_list_ids: [ml_district_managers]

    ExternalForm:
      summary: 13. External Form - Instead of Inline Feedback
      value:
        title: Quarterly Equipment Inspection
        type: ACT
        description: Complete the external equipment inspection form for HVAC, refrigeration, and electrical systems.
        schedule:
          start_at: '2026-10-01T08:00:00Z'
          finish_at: '2026-10-31T17:00:00Z'
          visibility:
            mode: overnight
        assignees:
          role_departments:
            - role_id: facilities_tech
              department_id: dept_facilities
        external_form:
          form_id: frm_equip_inspect_q4
          title: Q4 Equipment Inspection Checklist

    AdditionalAttributes:
      summary: 14. Additional Attributes - Template, Auto-Complete, Confidential, Tags, etc.
      value:
        title: Holiday Campaign Launch - Flagship Stores
        type: ACT
        template_id: tpl_holiday_campaign_2026
        category: marketing
        subcategory: seasonal_campaign
        description: Execute the holiday campaign across all flagship locations per the approved marketing brief.
        priority: 2
        tags: [holiday, marketing, flagship, q4]
        is_confidential: true
        creator_department_id: dept_marketing
        effort_minutes: 480
        schedule:
          start_at: '2026-11-15T06:00:00Z'
          finish_at: '2026-12-26T22:00:00Z'
          working_days: 30
          visibility:
            mode: days_before_start
            day_offset: 5
        assignees:
          role_departments:
            - role_id: campaign_manager
              department_id: dept_marketing
        rollout:
          - type: group
            group_ids: [grp_flagship_stores]
        auto_complete_days: 3
        notifications:
          email_addresses: [marketing-ops@example.com, regional-vp@example.com]
          mailing_list_ids: [ml_flagship_managers]

    TemplateBasedProject:
      summary: 15. Template-Based Project - Inherits from Template
      value:
        title: Weekly Endcap Reset - Q4 Week 42
        type: ACT
        template_id: tpl_endcap_reset_2026
        schedule:
          start_at: '2026-10-20T08:00:00Z'
          finish_at: '2026-10-25T17:00:00Z'
        assignees:
          role_departments:
            - role_id: merchandiser
              department_id: dept_merchandising