# Give the team its work — tasks, labels, hand-offs

Create tasks for people or teams, move them through their life, label them to organize the board, park one until a chosen moment — it comes back by itself — and leave a permanent note on any record.

Work · a play in 4 steps.

## The steps

1. Create the task — assigned to people or teams. — [createTask](/reference/task/createTask/)
2. Move it on — take it, complete it, cancel it — or park it until a chosen moment. — [transitionTask](/reference/task/transitionTask/), [postponeTask](/reference/work-and-notes/postponeTask/)
3. Create the labels that organize the board. — [createTaskLabel](/reference/task-label/createTaskLabel/)
4. Attach a permanent note — with files when needed — to any record, and react to a note with a mark everyone can see. — [addNote](/reference/work-and-notes/addNote/), [mintNoteAttachmentUpload](/reference/work-and-notes/mintNoteAttachmentUpload/), [reactToNote](/reference/your-own-session/reactToNote/)

## The calls

Every operation this use case runs, in the order it first appears, with the request and the response its reference page shows.

### createTask

[createTask](/reference/task/createTask/) — mutation · Create a new task — a to-do assigned to people or teams at your organization.

**Example request**

```graphql
mutation ExampleCreateTask($input: NewTaskInput!) {
  createTask(input: $input) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    description
    priority
    createdBy
    systemOrigin
    reportTo
    assigneeUserIds
    teamIds
    labelIds
    dueAt
    overdue
    linkedFromTaskId
    returnAt
    originNoteId
    originAnchorType
    originAnchorId
  }
}
```

Variables:

```json
{
  "input": {
    "caption": "Blue jeans"
  }
}
```

Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`.

**Example response**

```json
{
  "data": {
    "createTask": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "TK-EXMP-0000-000F",
      "type": "Task",
      "caption": "Blue jeans",
      "status": "open",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "description": "Straight-cut, mid-rise, five pockets.",
      "priority": "<priority>",
      "createdBy": "01900000-0000-7000-8000-0b14e5a60000",
      "systemOrigin": "<system origin>",
      "reportTo": "01900000-0000-7000-8000-9d69c9660000",
      "assigneeUserIds": [
        "01900000-0000-7000-8000-fbe5fcb10000"
      ],
      "teamIds": [
        "01900000-0000-7000-8000-1abd3d160000"
      ],
      "labelIds": [
        "01900000-0000-7000-8000-a235e7410000"
      ],
      "dueAt": "2027-01-31T00:00:00.000Z",
      "overdue": true,
      "linkedFromTaskId": "01900000-0000-7000-8000-6de8c4e00000",
      "returnAt": "2027-01-31T00:00:00.000Z",
      "originNoteId": "01900000-0000-7000-8000-f1eb5d520000",
      "originAnchorType": "<origin anchor type>",
      "originAnchorId": "01900000-0000-7000-8000-323b002b0000"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

### transitionTask

[transitionTask](/reference/task/transitionTask/) — mutation · Move a task through its life — take it, complete it, cancel it, or pull a postponed one back now.

**Example request**

```graphql
mutation ExampleTransitionTask($id: ID!, $revision: ID!, $op: TaskTransitionOp!, $reason: String) {
  transitionTask(id: $id, revision: $revision, op: $op, reason: $reason) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    description
    priority
    createdBy
    systemOrigin
    reportTo
    assigneeUserIds
    teamIds
    labelIds
    dueAt
    overdue
    linkedFromTaskId
    returnAt
    originNoteId
    originAnchorType
    originAnchorId
  }
}
```

Variables:

```json
{
  "id": "01900000-0000-7000-8000-37386ae00000",
  "revision": "01900000-0000-7000-8000-b7960e180000",
  "op": "start",
  "reason": "Correcting a miscount."
}
```

Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`.

**Example response**

```json
{
  "data": {
    "transitionTask": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "TK-EXMP-0000-000F",
      "type": "Task",
      "caption": "Blue jeans",
      "status": "open",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "description": "Straight-cut, mid-rise, five pockets.",
      "priority": "<priority>",
      "createdBy": "01900000-0000-7000-8000-0b14e5a60000",
      "systemOrigin": "<system origin>",
      "reportTo": "01900000-0000-7000-8000-9d69c9660000",
      "assigneeUserIds": [
        "01900000-0000-7000-8000-fbe5fcb10000"
      ],
      "teamIds": [
        "01900000-0000-7000-8000-1abd3d160000"
      ],
      "labelIds": [
        "01900000-0000-7000-8000-a235e7410000"
      ],
      "dueAt": "2027-01-31T00:00:00.000Z",
      "overdue": true,
      "linkedFromTaskId": "01900000-0000-7000-8000-6de8c4e00000",
      "returnAt": "2027-01-31T00:00:00.000Z",
      "originNoteId": "01900000-0000-7000-8000-f1eb5d520000",
      "originAnchorType": "<origin anchor type>",
      "originAnchorId": "01900000-0000-7000-8000-323b002b0000"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

### postponeTask

[postponeTask](/reference/work-and-notes/postponeTask/) — mutation · Park a task until a chosen moment — it leaves the inboxes and comes back BY ITSELF at that time (the boomerang).

**Example request**

```graphql
mutation ExamplePostponeTask($id: ID!, $revision: ID!, $returnAt: String!, $reason: String) {
  postponeTask(id: $id, revision: $revision, returnAt: $returnAt, reason: $reason) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    description
    priority
    createdBy
    systemOrigin
    reportTo
    assigneeUserIds
    teamIds
    labelIds
    dueAt
    overdue
    linkedFromTaskId
    returnAt
    originNoteId
    originAnchorType
    originAnchorId
  }
}
```

Variables:

```json
{
  "id": "01900000-0000-7000-8000-37386ae00000",
  "revision": "01900000-0000-7000-8000-b7960e180000",
  "returnAt": "2027-01-31T00:00:00.000Z",
  "reason": "Correcting a miscount."
}
```

Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`.

**Example response**

```json
{
  "data": {
    "postponeTask": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "TK-EXMP-0000-000F",
      "type": "Task",
      "caption": "Blue jeans",
      "status": "open",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "description": "Straight-cut, mid-rise, five pockets.",
      "priority": "<priority>",
      "createdBy": "01900000-0000-7000-8000-0b14e5a60000",
      "systemOrigin": "<system origin>",
      "reportTo": "01900000-0000-7000-8000-9d69c9660000",
      "assigneeUserIds": [
        "01900000-0000-7000-8000-fbe5fcb10000"
      ],
      "teamIds": [
        "01900000-0000-7000-8000-1abd3d160000"
      ],
      "labelIds": [
        "01900000-0000-7000-8000-a235e7410000"
      ],
      "dueAt": "2027-01-31T00:00:00.000Z",
      "overdue": true,
      "linkedFromTaskId": "01900000-0000-7000-8000-6de8c4e00000",
      "returnAt": "2027-01-31T00:00:00.000Z",
      "originNoteId": "01900000-0000-7000-8000-f1eb5d520000",
      "originAnchorType": "<origin anchor type>",
      "originAnchorId": "01900000-0000-7000-8000-323b002b0000"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

### createTaskLabel

[createTaskLabel](/reference/task-label/createTaskLabel/) — mutation · Create a new label for organizing tasks at your organization.

**Example request**

```graphql
mutation ExampleCreateTaskLabel($input: NewTaskLabelInput!) {
  createTaskLabel(input: $input) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    color
  }
}
```

Variables:

```json
{
  "input": {
    "caption": "Blue jeans"
  }
}
```

Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`.

**Example response**

```json
{
  "data": {
    "createTaskLabel": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "LB-EXMP-0000-000F",
      "type": "TaskLabel",
      "caption": "Blue jeans",
      "status": "active",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "color": "<color>"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

### addNote

[addNote](/reference/work-and-notes/addNote/) — mutation · Attach a note (optionally with files) to any record — an order, a product, a customer.

**Example request**

```graphql
mutation ExampleAddNote($input: NewNoteInput!) {
  addNote(input: $input) {
    id
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    targetType
    authorId
    parentNoteId
    title
    kind
    body
    labelIds
    taskId
  }
}
```

Variables:

```json
{
  "input": {
    "targetConstructId": "01900000-0000-7000-8000-79e077380000",
    "targetType": "<target type>",
    "body": "Restock before the weekend.",
    "parentNoteId": "01900000-0000-7000-8000-907baa100000"
  }
}
```

Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`.

**Example response**

```json
{
  "data": {
    "addNote": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "type": "<type>",
      "caption": "Blue jeans",
      "status": "<status>",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "targetType": "<target type>",
      "authorId": "01900000-0000-7000-8000-0046e40b0000",
      "parentNoteId": "01900000-0000-7000-8000-907baa100000",
      "title": "Blue jeans",
      "kind": "<kind>",
      "body": "Restock before the weekend.",
      "labelIds": [
        "01900000-0000-7000-8000-a235e7410000"
      ],
      "taskId": "01900000-0000-7000-8000-6ceba5410000"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

### mintNoteAttachmentUpload

[mintNoteAttachmentUpload](/reference/work-and-notes/mintNoteAttachmentUpload/) — mutation · Get a short-lived, pre-authorized upload slot for a note attachment.

**Example request**

```graphql
mutation ExampleMintNoteAttachmentUpload($input: MintNoteAttachmentUploadInput!) {
  mintNoteAttachmentUpload(input: $input) {
    attachmentId
    key
    uploadUrl
    expiresAt
  }
}
```

Variables:

```json
{
  "input": {
    "targetConstructId": "01900000-0000-7000-8000-79e077380000",
    "targetType": "<target type>",
    "filename": "<filename>",
    "declaredContentType": "<declared content type>",
    "bytes": 1,
    "sha256": "<sha256>"
  }
}
```

Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`.

**Example response**

```json
{
  "data": {
    "mintNoteAttachmentUpload": {
      "attachmentId": "01900000-0000-7000-8000-7bdf12b50000",
      "key": "<key>",
      "uploadUrl": "https://example.com/hook",
      "expiresAt": "2027-01-31T00:00:00.000Z"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

### reactToNote

[reactToNote](/reference/your-own-session/reactToNote/) — mutation · React to a note with one of the canned emojis — a lightweight mark everyone can see and count.

**Example request**

```graphql
mutation ExampleReactToNote($targetConstructId: ID!, $noteId: ID!, $emoji: String!) {
  reactToNote(targetConstructId: $targetConstructId, noteId: $noteId, emoji: $emoji) {
    emoji
    count
    userIds
  }
}
```

Variables:

```json
{
  "targetConstructId": "01900000-0000-7000-8000-79e077380000",
  "noteId": "01900000-0000-7000-8000-cf06f4680000",
  "emoji": "<emoji>"
}
```

Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`.

**Example response**

```json
{
  "data": {
    "reactToNote": [
      {
        "emoji": "<emoji>",
        "count": 1,
        "userIds": [
          "01900000-0000-7000-8000-f79e33c40000"
        ]
      }
    ]
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```