openapi: 3.0.3

info:
  title: Tasks
  description: "For retrieving and managing tasks. For information of how to construct requests utilising fieldsets, sorting, paging, filters, and '*includes*', please refer to the API Developer Portal. E&OE."
  version: "1.0"

externalDocs:
  description: API Developer Portal - Constructing API Requests
  url: https://docs.actionstep.com/api-requests/

paths:
  '/tasks':
    get:
      description: Returns a collection of tasks
      tags:
        - Tasks
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedTasks'

    post:
      description: Create a new task.
      tags:
        - Tasks
      requestBody:
        $ref: '#/components/requestBodies/CreateTask'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'

  '/tasks/{id}':
    get:
      description: Returns a single task.
      tags:
        - Tasks
      parameters:
        - name: id
          in: path
          description: Unique identifier for a task.
          required: true
          schema:
            type: integer
            format: int32
          example: 9287
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'

    put:
      description: Update a task.
      tags:
        - Tasks
      parameters:
        - name: id
          in: path
          description: Unique identifier for a task.
          required: true
          schema:
            type: integer
            format: int32
          example: 608
      requestBody:
        $ref: '#/components/requestBodies/UpdateTask'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'

    delete:
      description: Delete a task.
      tags:
        - Tasks
      parameters:
        - name: id
          in: path
          description: Unique identifier for a task.
          required: true
          schema:
            type: integer
            format: int32
          example: 608
      responses:
        '204':
          description: Success, No Content.

components:
  schemas:
    PagedTasks:
      type: object
      properties:
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/Task'
        meta:
          $ref: '#/components/schemas/PageMetaData'

    PageMetaData:
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/PagingData'

    PagingData:
      type: object
      properties:
        tasks:
          $ref: '#/components/schemas/TasksPageData'

    TasksPageData:
      type: object
      properties:
        recordCount:
          description: The total number of tasks returned by the underlying query.
          type: integer
          example: 2487
        pageCount:
          description: The total number of pages generated by the underlying query.
          type: integer
          example: 50
        page:
          description: The page number for this page of tasks.
          type: integer
          example: 2
        pageSize:
          description: Page size.
          type: integer
          example: 50
        prevPage:
          description: A URL to the previous page of tasks.
          type: string
          example: https://ap-southeast-2.actionstep.com/api/rest/tasks?page=1
        nextPage:
          description: A URL to the next page of tasks.
          type: string
          example: https://ap-southeast-2.actionstep.com/api/rest/tasks?page=3

    Task:
      type: object
      properties:
        id:
          description: Unique identifier for the task.
          example: 2347
          type: integer
        name:
          description: Name for the task.
          example: Research.
          type: string
        status:
          description: Current status of the task.
          enum:
            - Incomplete
            - Complete
            - Hidden
            - Deleted
          default: Incomplete
          example: Complete
          type: string
        priority:
          description: Priority of the task.
          enum:
            - Low
            - Normal
            - High
          default: Normal
          example: High
          type: string
        dueTimestamp:
          description: The date and time the task is due to be completed.
          example: 2022-05-03T00:09:00+12:00
          format: timestamp
          type: string
        startedTimestamp:
          description: The date and time the task started.
          example: 2022-05-02T00:09:00+12:00
          format: timestamp
          type: string
        completedTimestamp:
          description: The date and time the task completed.
          example: 2022-05-03T00:10:30+12:00
          format: timestamp
          type: string
        lastModifiedTimestamp:
          description: The date and time the task was last modified.
          example: 2022-05-03T00:10:35+12:00
          format: timestamp
          type: string
        actualHours:
          description: (Deprecated) Number of hours spent on the task.
          example: 2.50
          type: number
          multipleOf: 0.01
        billableHours:
          description: (Deprecated) Number of billable hours for the task.
          example: 2.50
          type: number
          multipleOf: 0.01
        description:
          description: Description for the task.
          example: Research into the concrete manufacturing process.
          type: string
        assignedBy:
          description: Actionstep user who assigned to the task.
          example: Smith, John
          type: string
        completeDuringStep:
          description: Unique identifier for the step in which the task should be completed.
          example: 91764
          type: integer
        completeBeforeStep:
          description: Unique identifier for the step before which the task should be completed.
          example: 93299
          type: integer
        mustStartBeforeTimestamp:
          description: (Deprecated) The date and time the task must be started by.
          example: 2022-05-03T00:10:30+12:00
          format: timestamp
          type: string
        expectedDurationValue:
          description: (Deprecated) Duration of the task.
          example: 400
          type: integer
        expectedDurationUnits:
          description: (Deprecated) Duration units for the task.
          example: hours
          type: string
        isBillingHold:
          description: (Deprecated) Indicates if the task is on billing hold.
          enum:
            - T
            - F
          example: F
          type: string
        isPartBilled:
          description: (Deprecated) Indicates if the task has been part billed.
          enum:
            - T
            - F
          example: F
          type: string
        confirmedNonBillable:
          description: (Deprecated) Indicates if the task is non-billable.
          enum:
            - T
            - F
          example: F
          type: string
        confirmedNonBillableTimestamp:
          description: (Deprecated) Date and time the task is confirmed as non-billable.
          example: 2022-05-03T00:10:30+12:00
          format: timestamp
          type: string
        hasTriggerDate:
          description: Indicates if the expected completion date triggers a workflow process.
          enum:
            - T
            - F
          example: T
          type: string
        triggerField:
          description: Data field used as the trigger for a workflow process.
          example: DueDate
          type: string
        triggerOffset:
          description: Offset (in days) from the trigger field value that is used to trigger a workflow process. For example, 2 days before the due date trigger a workflow to send an email reminder.
          example: -2
          type: integer
        triggerWeekdaysOnly:
          description: Indicates if the offset is applicable to week days (Mon to Fri) only.
          enum:
            - T
            - F
          example: T
          type: string
        links:
          $ref: '#/components/schemas/TaskLinks'

    TaskLinks:
      type: object
      properties:
        triggerDataCollection:
          description: Unique identifier for the data collection containing the trigger field.
          example: 8834
          type: integer
        action:
          description: Unique identifier of the matter to which the task is associated.
          example: 34
          type: integer
        assignee:
          description: Actionstep user to whom this task has been assigned.
          example: 14
          type: integer
        rate:
          description: (Deprecated) Unique identifier of the rate table entry applicable to the task.
          example: 17
          type: integer
        confirmedNonBillableBy:
          description: (Deprecated) Actionstep user who confirmed the task as non-billable.
          example: 383
          type: integer
        linkedDocumentTemplate:
          description: Unique identifier for a document template linked to the task.
          example: 9642
          type: integer
        linkedDataCollection:
          description: Unique identifier for the data collection linked with the task.
          example: 4248
          type: integer
        template:
          description: Unique identifier for a task template used for the task.
          example: 23
          type: integer

    CreateTask:
      type: object
      required:
        - name
        - status
        - dueTimestamp
      properties:
        name:
          description: Name for the task.
          example: Research.
          type: string
        status:
          description: Current status of the task.
          enum:
            - Incomplete
            - Complete
            - Hidden
            - Deleted
          default: Incomplete
          example: Complete
          type: string
        priority:
          description: Priority of the task.
          enum:
            - Low
            - Normal
            - High
          default: Normal
          example: High
          type: string
        dueTimestamp:
          description: The date and time the task is due to be completed.
          example: 2022-05-03T00:09:00+12:00
          format: timestamp
          type: string
        startedTimestamp:
          description: The date and time the task started.
          example: 2022-05-02T00:09:00+12:00
          format: timestamp
          type: string
        completedTimestamp:
          description: The date and time the task completed.
          example: 2022-05-03T00:10:30+12:00
          format: timestamp
          type: string
        lastModifiedTimestamp:
          description: The date and time the task was last modified.
          example: 2022-05-03T00:10:35+12:00
          format: timestamp
          type: string
        actualHours:
          description: (Deprecated) Number of hours spent on the task.
          example: 2.50
          type: number
          multipleOf: 0.01
        billableHours:
          description: (Deprecated) Number of billable hours for the task.
          example: 2.50
          type: number
          multipleOf: 0.01
        description:
          description: Description for the task.
          example: Research into the concrete manufacturing process.
          type: string
        assignedBy:
          description: Actionstep user who assigned to the task.
          example: Smith, John
          type: string
        completeDuringStep:
          description: Unique identifier for the step in which the task should be completed.
          example: 91764
          type: integer
        completeBeforeStep:
          description: Unique identifier for the step before which the task should be completed.
          example: 93299
          type: integer
        mustStartBeforeTimestamp:
          description: (Deprecated) The date and time the task must be started by.
          example: 2022-05-03T00:10:30+12:00
          format: timestamp
          type: string
        expectedDurationValue:
          description: (Deprecated) Duration of the task.
          example: 400
          type: integer
        expectedDurationUnits:
          description: (Deprecated) Duration units for the task.
          example: hours
          type: string
        isBillingHold:
          description: (Deprecated) Indicates if the task is on billing hold.
          enum:
            - T
            - F
          example: F
          type: string
        isPartBilled:
          description: (Deprecated) Indicates if the task has been part billed.
          enum:
            - T
            - F
          example: F
          type: string
        confirmedNonBillable:
          description: (Deprecated) Indicates if the task is non-billable.
          enum:
            - T
            - F
          example: F
          type: string
        confirmedNonBillableTimestamp:
          description: (Deprecated) Date and time the task is confirmed as non-billable.
          example: 2022-05-03T00:10:30+12:00
          format: timestamp
          type: string
        hasTriggerDate:
          description: Indicates if the expected completion date triggers a workflow process.
          enum:
            - T
            - F
          example: T
          type: string
        triggerField:
          description: Data field used as the trigger for a workflow process.
          example: DueDate
          type: string
        triggerOffset:
          description: Offset (in days) from the trigger field value that is used to trigger a workflow process. For example, 2 days before the due date trigger a workflow to send an email reminder.
          example: -2
          type: integer
        triggerWeekdaysOnly:
          description: Indicates if the offset is applicable to week days (Mon to Fri) only.
          enum:
            - T
            - F
          example: T
          type: string
        links:
          $ref: '#/components/schemas/CreateTaskLinks'

    CreateTaskLinks:
      type: object
      required:
        - action
        - assignee
      properties:
        triggerDataCollection:
          description: Unique identifier for the data collection containing the trigger field.
          example: 8834
          type: integer
        action:
          description: Unique identifier of the matter to which the task is associated.
          example: 34
          type: integer
        assignee:
          description: Actionstep user to whom this task has been assigned.
          example: 14
          type: integer
        rate:
          description: (Deprecated) Unique identifier of the rate table entry applicable to the task.
          example: 17
          type: integer
        confirmedNonBillableBy:
          description: (Deprecated) Actionstep user who confirmed the task as non-billable.
          example: 383
          type: integer
        linkedDocumentTemplate:
          description: Unique identifier for a document template linked to the task.
          example: 9642
          type: integer
        linkedDataCollection:
          description: Unique identifier for the data collection linked with the task.
          example: 4248
          type: integer
        template:
          description: Unique identifier for a task template used for the task.
          example: 23
          type: integer

    UpdateTask:
      type: object
      required:
        - name
        - status
        - dueTimestamp
      properties:
        name:
          description: Name for the task.
          example: Research.
          type: string
        status:
          description: Current status of the task.
          enum:
            - Incomplete
            - Complete
            - Hidden
            - Deleted
          default: Incomplete
          example: Complete
          type: string
        priority:
          description: Priority of the task.
          enum:
            - Low
            - Normal
            - High
          default: Normal
          example: High
          type: string
        dueTimestamp:
          description: The date and time the task is due to be completed.
          example: 2022-05-03T00:09:00+12:00
          format: timestamp
          type: string
        startedTimestamp:
          description: The date and time the task started.
          example: 2022-05-02T00:09:00+12:00
          format: timestamp
          type: string
        completedTimestamp:
          description: The date and time the task completed.
          example: 2022-05-03T00:10:30+12:00
          format: timestamp
          type: string
        lastModifiedTimestamp:
          description: The date and time the task was last modified.
          example: 2022-05-03T00:10:35+12:00
          format: timestamp
          type: string
        actualHours:
          description: (Deprecated) Number of hours spent on the task.
          example: 2.50
          type: number
          multipleOf: 0.01
        billableHours:
          description: (Deprecated) Number of billable hours for the task.
          example: 2.50
          type: number
          multipleOf: 0.01
        description:
          description: Description for the task.
          example: Research into the concrete manufacturing process.
          type: string
        assignedBy:
          description: Actionstep user who assigned to the task.
          example: Smith, John
          type: string
        completeDuringStep:
          description: Unique identifier for the step in which the task should be completed.
          example: 91764
          type: integer
        completeBeforeStep:
          description: Unique identifier for the step before which the task should be completed.
          example: 93299
          type: integer
        mustStartBeforeTimestamp:
          description: (Deprecated) The date and time the task must be started by.
          example: 2022-05-03T00:10:30+12:00
          format: timestamp
          type: string
        expectedDurationValue:
          description: (Deprecated) Duration of the task.
          example: 400
          type: integer
        expectedDurationUnits:
          description: (Deprecated) Duration units for the task.
          example: hours
          type: string
        isBillingHold:
          description: (Deprecated) Indicates if the task is on billing hold.
          enum:
            - T
            - F
          example: F
          type: string
        isPartBilled:
          description: (Deprecated) Indicates if the task has been part billed.
          enum:
            - T
            - F
          example: F
          type: string
        confirmedNonBillable:
          description: (Deprecated) Indicates if the task is non-billable.
          enum:
            - T
            - F
          example: F
          type: string
        confirmedNonBillableTimestamp:
          description: (Deprecated) Date and time the task is confirmed as non-billable.
          example: 2022-05-03T00:10:30+12:00
          format: timestamp
          type: string
        hasTriggerDate:
          description: Indicates if the expected completion date triggers a workflow process.
          enum:
            - T
            - F
          example: T
          type: string
        triggerField:
          description: Data field used as the trigger for a workflow process.
          example: DueDate
          type: string
        triggerOffset:
          description: Offset (in days) from the trigger field value that is used to trigger a workflow process. For example, 2 days before the due date trigger a workflow to send an email reminder.
          example: -2
          type: integer
        triggerWeekdaysOnly:
          description: Indicates if the offset is applicable to week days (Mon to Fri) only.
          enum:
            - T
            - F
          example: T
          type: string
        links:
          $ref: '#/components/schemas/UpdateTaskLinks'

    UpdateTaskLinks:
      type: object
      required:
        - action
        - assignee
      properties:
        triggerDataCollection:
          description: Unique identifier for the data collection containing the trigger field.
          example: 8834
          type: integer
        action:
          description: Unique identifier of the matter to which the task is associated.
          example: 34
          type: integer
        assignee:
          description: Actionstep user to whom this task has been assigned.
          example: 14
          type: integer
        rate:
          description: (Deprecated) Unique identifier of the rate table entry applicable to the task.
          example: 17
          type: integer
        confirmedNonBillableBy:
          description: (Deprecated) Actionstep user who confirmed the task as non-billable.
          example: 383
          type: integer
        linkedDocumentTemplate:
          description: Unique identifier for a document template linked to the task.
          example: 9642
          type: integer
        linkedDataCollection:
          description: Unique identifier for the data collection linked with the task.
          example: 4248
          type: integer
        template:
          description: Unique identifier for a task template used for the task.
          example: 23
          type: integer

  requestBodies:
    CreateTask:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateTask'

    UpdateTask:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateTask'