openapi: 3.0.0
info:
  title: Process board API - ValueStreamer
  version: 1.0.3
  description: "This is the specification of the REST interface for the process board."
servers:
  - url: https://api-tenant.valuestreamer.de/api
security:
  - basicAuth: []
tags:
- name: "Process activity"
  description: ""
- name: "Process activity: Description"
  description: "Endpoints for fetching and updating the data of the richtext input field 'description'."
- name: "Process activity: Planning"
  description: "Endpoints for fetching and updating the plan data."
- name: "Process activity: Status history"
- name: "Meta"
  description: "Endpoints to retrieve meta data."
paths:
  /exchange/processactivities:
    get:
      tags:
        - "Process activity"
      summary: "Retrieve a collection of process activities."
      description: "Returns a list of filterable process activities, ordered by creation date (desc)."
      parameters:
        - in: "query"
          name: "phase"
          description: "UUID of a phase"
          required: false
          schema:
            type: "string"
            format: "uuid"
        - in: "query"
          name: "board"
          description: "UUID of a process board"
          required: true
          schema:
            type: "string"
            format: "uuid"
        - in: "query"
          name: "page"
          description: "page id"
          required: true
          schema:
            type: "integer"
            maximum: 50
      responses:
        '200':
          description: OK
          content:
            application/vs.pb.v1.0.0+json:
              schema:
                allOf:
                  - properties:
                      page:
                        $ref: '#/components/schemas/Page'
                      entries:
                        type: array
                        items:
                          $ref: '#/components/schemas/ProcessActivityExcerpt'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
        - "Process activity"
      summary: "Insert a process activity"
      requestBody:
        required: true
        content:
          application/vs.pb.v1.0.0+json:
            schema:
              allOf:
                - $ref: '#/components/schemas/ProcessActivityDetails'
                - properties:
                    processBoardView:
                      type: string
                      format: uuid
                      description: "UUID of the process board of the activity."
                      nullable: false
                    responsibleTeam:
                      type: string
                      format: 'uuid'
                      description: "UUID of the assigned team"
                    targetEndDate:
                      type: string
                      format: 'date'
                      description: ""
                - required:
                  - "category"
                  - "priority"
                  - "processBoardView"
                  - "responsibleTeam"
                  - "statusCost"
                  - "statusQuality"
                  - "statusTime"
                  - "targetEndDate"
                  - "title"
      responses:
        '200':
          description: OK
          content:
            application/vs.pb.v1.0.0+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProcessActivityDetails'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /exchange/processactivities/{id}:
    get:
      tags:
        - "Process activity"
      summary: "Retrieve a specific process activity."
      parameters:
        - in: "path"
          name: "id"
          description: "UUID of the process activity."
          required: true
          schema:
            type: "string"
            format: "uuid"
      responses:
        '200':
          description: OK
          content:
            application/vs.pb.v1.0.0+json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProcessActivityDetails'
                - properties:
                    processBoardView:
                      type: string
                      format: uuid
                      description: "UUID of the process board of the activity."
                      nullable: false
                    responsibleTeam:
                      type: string
                      format: 'uuid'
                      description: "UUID of the assigned team"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
        - "Process activity"
      summary: "Update a process activity"
      parameters:
        - in: "path"
          name: "id"
          description: "UUID of the data process activity."
          required: true
          schema:
            type: "string"
            format: "uuid"
      requestBody:
        required: true
        content:
          application/vs.pb.v1.0.0+json:
            schema:
              allOf:
                - $ref: '#/components/schemas/ProcessActivityDetails'
      responses:
        '200':
          description: OK
          content:
            application/vs.pb.v1.0.0+json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ProcessActivityDetails'
                  - properties:
                      processBoardView:
                        type: string
                        format: uuid
                        description: "UUID of the process board of the activity."
                        nullable: false
                      responsibleTeam:
                        type: string
                        format: 'uuid'
                        description: "UUID of the assigned team"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - "Process activity"
      summary: "Delete a specific process activity."
      parameters:
        - in: "path"
          name: "id"
          description: "UUID of the process activity."
          required: true
          schema:
            type: "string"
            format: "uuid"
      responses:
        '204':
          description: Record deleted
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /exchange/processactivities/{id}/description:
    summary: "Get the data of the richtext input field 'description' of the process activity."
    get:
      tags:
        - "Process activity: Description"
      summary: "Get the description."
      parameters:
        - in: "path"
          name: "id"
          description: "UUID of the process activity."
          required: true
          schema:
            type: "string"
            format: "uuid"
      responses:
        '200':
          description: OK
          content:
            application/vs.pb.v1.0.0+json:
              schema:
                $ref: '#/components/schemas/Description'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
        - "Process activity: Description"
      summary: "Update the description."
      parameters:
        - in: "path"
          name: "id"
          description: "UUID of the process activity."
          required: true
          schema:
            type: "string"
            format: "uuid"
      requestBody:
        required: true
        content:
          application/vs.pb.1.0.0+json:
            schema:
              $ref: '#/components/schemas/Description'
      responses:
        '200':
          description: OK
          content:
            application/vs.pb.1.0.0+json:
              schema:
                $ref: '#/components/schemas/Description'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /exchange/processactivities/{id}/planning:
    get:
      tags:
        - "Process activity: Planning"
      summary: "Get the phase plannings of the process activity."
      parameters:
        - in: "path"
          name: "id"
          description: "UUID of the process activity."
          required: true
          schema:
            type: "string"
            format: "uuid"
      responses:
        '200':
          description: OK
          content:
            application/vs.pb.v1.0.0+json:
              schema:
                $ref: '#/components/schemas/ProcessActivityPhasePlanningRead'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
        - "Process activity: Planning"
      summary: "Update the phase plannings of the process activity. "
      parameters:
        - in: "path"
          name: "id"
          description: "UUID of the process activity."
          required: true
          schema:
            type: "string"
            format: "uuid"
      requestBody:
        required: true
        content:
          application/vs.pb.v1.0.0+json:
            schema:
              allOf:
                - $ref: '#/components/schemas/ProcessActivityPhasePlanningUpdate'
      responses:
        '200':
          description: OK
          content:
            application/vs.pb.v1.0.0+json:
              schema:
                $ref: '#/components/schemas/ProcessActivityPhasePlanningRead'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /exchange/processactivities/{id}/status-history:
    get:
      tags:
        - "Process activity: Status history"
      summary: "Get the status history of the processitem, ordered by date."
      parameters:
        - in: "path"
          name: "id"
          description: "UUID of the process activity."
          required: true
          schema:
            type: "string"
            format: "uuid"
      responses:
        '200':
          description: OK
          content:
            application/vs.pb.v1.0.0+json:
              schema:
                type: "array"
                items:
                  $ref: '#/components/schemas/History'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /exchange/processboard-categories:
    get:
      tags:
        - "Meta"
      summary: "Get all available categories"
      responses:
        '200':
          description: OK
          content:
            application/vs.pb.v1.0.0+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Category'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /exchange/processboard-labels:
    get:
      tags:
        - "Meta"
      summary: "Get all available labels"
      responses:
        '200':
          description: OK
          content:
            application/vs.pb.v1.0.0+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Label'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /exchange/processboards/{id}:
    get:
      tags:
        - "Meta"
        - "Processboard"
      summary: "Get the details of a processboard including labels, phases, categories ..."
      parameters:
        - in: "path"
          name: "id"
          description: "UUID of the board"
          required: true
          schema:
            type: "string"
            format: "uuid"
      responses:
        '200':
          description: OK
          content:
            application/vs.pb.v1.0.0+json:
              schema:
                $ref: '#/components/schemas/ProcessboardDetails'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'   
components:
  securitySchemes:
    basicAuth:           
      type: http
      scheme: basic
  schemas:
    Category:
      type: object
      description: 'A category must be assigned to a process activity.'
      properties:
        id:
          type: string
          format: uuid
          description: "UUID"
        name:
          type: string
          description: "name"
          maxLength: 255
        color:
          type: string
          description: "Color is used as a background color of a process activity in the process board."
          maxLength: 10
        removable:
          type: boolean
        default:
          type: boolean
    # Schema for error response body
    Error:
      type: object
      properties:
        errorId:
          type: number
        errorMessage:
          type: string
    Description:
      type: object
      description: 'Description as HTML string, shown in the richtext editor.'
      properties:
        description:
          type: string
          maxLength: 4294967295
    FreeAttribute:
      type: object
      description: 'An additional attribute can be assigned to a process activity.'
      properties:
        id:
          type: string
          format: uuid
          description: "UUID"
        name:
          type: string
          description: "name"
          maxLength: 45
        abbreviation:
          type: string
          description: "Contains the abbreviation"
          maxLength: 20
        orderId:
          type: number
    History:
      type: object
      properties:
        comment:
          type: string
          description: ''
        modifiedByUser:
          type: string
          format: 'uuid'
        modifiedDate:
          type: string
          format: date
        statusCost:
          type: integer
          enum: [1,2,3]
          description: "1 green, 2 yellow, 3 red"
        statusQuality:
          type: integer
          enum: [1,2,3]
          description: "1 green, 2 yellow, 3 red"
        statusTime:
          type: integer
          enum: [1,2,3]
          description: "1 green, 2 yellow, 3 red"
    Label:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: "UUID"
        name:
          type: array
          description: "name"
          items: 
            type: object
            properties:
              language:
                $ref: '#/components/schemas/Languages'
              name:
                type: string
                description: "Translation"
                maxLength: 55
        removable:
          type: boolean
    Languages:
      type: string
      enum: [DE,EN]
    Page:
      type: object
      readOnly: true
      properties:
        page:
          type: integer
          description: "Number of the current page"
        elementsOnPage:
          type: integer
          description: "Number of elements on the current page"
        elementsPerPage:
          type: integer
          description: "Number of elements per page"
        totalPages:
          type: integer
          description: "Number of all pages"
        totalElements:
          type: integer
          description: "Number of all elements"
    Phase:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: "UUID of  the phase."
        abbreviation:
          type: string
          description: "Phase abbreviation."
          maxLength: 45
        name:
          type: string
          description: "Phase name."
          maxLength: 45
        orderId:
          type: integer
          description: 'Order of the phases'
    ProcessActivityExcerpt:
      type: "object"
      properties:
        id:
          type: string
          format: uuid
          description: "UUID of the process activity."
          readOnly: true
        category:
          type: string
          format: 'uuid'
          description: "UUID of the corresponding category"
        freeAttribute:
          type: string
          format: 'uuid'
          description: 'UUID of the corresponding attribute.'
        formId:
          type: string
          description: "Formular ID"
          maxLength: 50
        phase:
          type: string
          format: uuid
          description: "UUID of the phase of the activity."
        priority:
          type: boolean
          description: ""
        processitemLabel:
          type: string
          format: uuid
          description: "UUID of the label."
        processitemTemplate:
          type: string
          format: uuid
          description: "UUID of the template. Can't be changed after initial assignment."
        responsiblePerson:
          type: string
          format: 'uuid'
          description: "UUID of the assigned user."
        responsibleTeam:
          type: string
          format: 'uuid'
          description: "UUID of the assigned team"
        status:
          type: integer
          enum: [1,2,3]
          description: "Overall status, calculated based on status cost, quality and time. 1=green, 2=yellow, 3=red."
          readOnly: true
        title:
          type: string
          description: "Title of the process activity"
          maxLength: 255
    ProcessActivityDetails:
      type: "object"
      properties:
        id:
          type: string
          format: uuid
          description: "UUID of the process activity."
          readOnly: true
        actualEndDate:
          type: string
          format: 'date'
          description: "Date when the activity was moved to DONE."
          readOnly: true
        archivedDate:
          type: string
          format: 'date'
          description: "Archiving date of the process activity."
          readOnly: true
        category:
          type: string
          format: 'uuid'
          description: "UUID of the corresponding category"
          nullable: false
        createdBy:
          type: string
          format: 'uuid'
          readOnly: true
          description: "UUID of the creator user."
        createdByTeam:
          type: string
          format: 'uuid'
          readOnly: true
          description: "UUID of the creator team."
        createdDate:
          type: string
          format: 'date'
          description: "Creation date."
          readOnly: true
        freeAttribute:
          type: string
          format: 'uuid'
          description: 'UUID of the corresponding attribute.'
        formId:
          type: string
          description: "Formular ID"
          maxLength: 50
        linkedToTeam:
          type: string
          format: 'uuid'
          description: "UUID of the linked 'parent' team. (sub process)."
          readOnly: true
        linkedToProcessitem:
          type: string
          format: uuid
          description: "UUID of the linked process activity. (sub process)."
          readOnly: true
        linkedToProcess:
          type: string
          format: uuid
          description: "UUID of the linked process board. (sub process)."
          readOnly: true
        modifiedBy:
          type: string
          format: 'uuid'
          readOnly: true
          description: "UUID of the user who last modified the record."
        modifiedDate:
          type: string
          format: 'date'
          description: ""
          readOnly: true
        phase:
          type: string
          format: uuid
          description: "UUID of the phase of the activity."
        priority:
          type: boolean
          description: ""
          nullable: false
        processitemLabel:
          type: string
          format: uuid
          description: "UUID of the label."
        processitemTemplate:
          type: string
          format: uuid
          description: "UUID of the template. Can't be changed after initial assignment."
        responsiblePerson:
          type: string
          format: 'uuid'
          description: "UUID of the assigned user."
        status:
          type: integer
          enum: [1,2,3]
          description: "Overall status, calculated based on status cost, quality and time. 1=green, 2=yellow, 3=red."
          readOnly: true
        statusCost:
          type: integer
          enum: [1,2,3]
          description: "1=green, 2=yellow, 3=red."
        statusQuality:
          type: integer
          enum: [1,2,3]
          description: "1=green, 2=yellow, 3=red."
        statusTime:
          type: integer
          enum: [1,2,3]
          description: "1=green, 2=yellow, 3=red."
        statusMessage:
          type: string
          description: "Must be provided when the status of cost, quality or time changes."
        title:
          type: string
          description: "Title of the process activity"
          maxLength: 255
          nullable: false
    ProcessActivityPhasePlanningRead:
      description: "Dates of the process activity for a single phase."
      type: array
      items:
        type: object
        properties:
          phaseId:
            type: string
            format: 'uuid'
            description: 'UUID of the corresponding phase.'
          actualStartDate:
            type: string
            format: 'date'
            description: "Is set automatically when the process activity is moved from backlog into a phase."
            readOnly: true
          actualEndDate:
            type: string
            format: 'date'
            description: "Is set automatically when the process activity leaves the phase."
            readOnly: true
          targetEndDate:
            type: string
            format: 'date'
            description: "Planned end date."
          targetEndDateNew:
            type: string
            format: 'date'
            description: "Planned end date (new)."
        required:
          - phaseId
    ProcessActivityPhasePlanningUpdate:
      description: "Dates of the process activity for a single phase."
      type: array
      items:
        type: object
        properties:
          phaseId:
            type: string
            format: 'uuid'
            description: 'UUID of the corresponding phase.'
          targetEndDate:
            type: string
            format: 'date'
            description: "Planned end date."
          targetEndDateNew:
            type: string
            format: 'date'
            description: "Planned end date (new)."
        required:
          - phaseId
    ProcessboardDetails:
      type: "object"
      properties:
        id:
          type: string
          format: uuid
          description: "UUID"
        name:
            type: string
            maxLength: 255
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/FreeAttribute'
        categories:
          type: array
          items:
            $ref: '#/components/schemas/Category'
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
        phases:
          type: array
          items:
            $ref: '#/components/schemas/Phase'
        templates:
          type: array
          items:
            $ref: '#/components/schemas/Template'
    ProcessboardExcerpt:
      type: "object"
      properties:
        id:
          type: string
          format: uuid
          description: "UUID"
        name:
            type: string
    TeamExcerpt:
      type: "object"
      properties:
        id:
          type: string
          format: uuid
          description: "UUID of the team."
        name:
            type: string
            maxLength: 255
        shortName:
            type: string
            maxLength: 55
        parentTeam:
            type: string
            format: uuid
        interdisciplinary:
            type: boolean
            description: 'Marker whether the team is part of the organizational cascade (false), or an interdisciplinary cross-cutting team. (true)'
    Template:
      type: "object"
      properties:
        id:
          type: string
          format: uuid
          description: "UUID of the template."
        title:
            type: string
            maxLength: 45
        abbreviation:
            type: string
            maxLength: 45
        orderId:
            type: integer
            description: "Order of the templates"
    User:
      type: "object"
      properties:
        id:
          type: string
          format: uuid
        firstName:
          type: string
          maxLength: 55
        lastName:
          type: string
          maxLength: 55
        email:
          type: string
          maxLength: 255
  responses:
    NotFound:
      description: Resource not found
      content:
        application/vs.pb.v1.0.0+json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Not authorized
      content:
        application/vs.pb.v1.0.0+json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request
      content:
        application/vs.pb.v1.0.0+json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Conflict
      content:
        application/vs.pb.v1.0.0+json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal server error
      content:
        application/vs.pb.v1.0.0+json:
          schema:
            $ref: '#/components/schemas/Error'
    UnsupportedMediaType:
      description: UnsupportedMediaType
      content:
        application/vs.pb.v1.0.0+json:
          schema:
            $ref: '#/components/schemas/Error'