# ClickUp

{% hint style="info" %}
Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.
{% endhint %}

[ClickUp](https://clickup.com/) is a project management tool that combines tasks, document collaboration, and issue management in a single platform.

Integrating ClickUp with Cortex allows you to:

* View task information directly on [entity pages](#entity-pages) in Cortex
* Create ClickUp tasks based on Initiatives directly from Cortex
* Map ClickUp identities to users in Cortex
* View open ClickUp tasks in the [dev homepage](#dev-homepage)
* Create [Scorecards](#scorecards-and-cql) that track progress and drive alignment on projects involving your ClickUp tasks

## How to configure ClickUp with Cortex

### Prerequisites

Before getting started:

* Create a [ClickUp personal API token](https://clickup.com/api/developer-portal/authentication/#generate-your-personal-api-token).

### Configure the integration in Cortex

1. In Cortex, navigate to the [ClickUp settings page](https://app.getcortexapp.com/admin/integrations/clickup).
   * Click **Integrations** from the main nav. Search for and select **ClickUp**.
2. Click **Add configuration**.
3. Configure the ClickUp integration form:
   * **API token**: Enter your ClickUp API token.
4. Click **Save**.

If you’ve set everything up correctly, you’ll see the option to **Remove Integration** in settings.

You can also use the **Test configuration** button to confirm that the configuration was successful. If your configuration is valid, you’ll see a banner that says “Configuration is valid. If you see issues, please see documentation or reach out to Cortex support.”

Note that mapping options will not appear in Cortex for users who have not finished user registration in ClickUp. If a user is partially registered, Cortex will filter them out of the mapping page.

To modify the integration configuration, see [Modifying an existing integration configuration](/ingesting-data-into-cortex/integrations.md#modifying-an-existing-integration-configuration).

## How to connect Cortex entities to ClickUp

### Auto discovery of spaces, folders, and tags

By default, Cortex will use the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities.md#cortex-tag) (e.g. `my-entity`) as the "best guess" for ClickUp space, folder, or tag. For example, if your Cortex tag is `my-entity`, then the corresponding space, folder, or tag in ClickUp should also be `my-entity`.

If your ClickUp space, folder, or tag don’t cleanly match the Cortex tag, you can override this in the Cortex entity descriptor.

### Editing the entity descriptor

You can map any number of ClickUp spaces, folders, and tags to a Cortex entity. Spaces and folders can be mapped by using either ID or name.

You can find your folder ID or space ID in your ClickUp URL: `https://app.clickup.com/:workspace_id/v/f/:folder_id/:space_id`.

**Mapping spaces by ID or name**

When mapping spaces, you can use the ID or name for the space.

```yaml
x-cortex-issues:
  clickup:
    spaces:
      - identifier: 123456789
        identifierType: ID
```

```yaml
x-cortex-issues:
  clickup:
    spaces:
      - identifier: My Space
        identifierType: NAME
```

These blocks share the same fields:

| Field            | Description                                            | Required |
| ---------------- | ------------------------------------------------------ | :------: |
| `spaces`         | Denotes that mapping should be based on ClickUp spaces | **true** |
| `identifier`     | Identifier for the space; either the full ID or name   | **true** |
| `identifierType` | Type of identifier; either `ID` or `NAME`              | **true** |

**Mapping folders by ID or name**

When mapping folders, you can use the ID or name for the folder.

```yaml
x-cortex-issues:
  clickup:
    folders:
      - identifier: 123456789
        identifierType: ID
```

```yaml
x-cortex-issues:
  clickup:
    folders:
      - identifier: my-folder
        identifierType: NAME
```

| Field            | Description                                            | Required |
| ---------------- | ------------------------------------------------------ | :------: |
| `folders`        | Denotes that mapping should be based on ClickUp folder | **true** |
| `identifier`     | Identifier for the folder; either the full ID or name  | **true** |
| `identifierType` | Type of identifier; either `ID` or `NAME`              | **true** |

**Mapping by tags**

Cortex also supports mapping entities to ClickUp [tags](https://help.clickup.com/hc/en-us/articles/6304382595991-Manage-task-tags).

```yaml
x-cortex-issues:
  clickup:
    tags:
      - name: tag a
      - name: tag b
      - name: tag c
```

| Field     | Description                                          | Required |
| --------- | ---------------------------------------------------- | :------: |
| `folders` | Denotes that mapping should be based on ClickUp tags | **true** |
| `name`    | Name for the tag                                     | **true** |

### Specify a list for Initiative issues

You can also specify a ClickUp list to store all issues created via Cortex Initiatives. If `Use list defined in entity YAML` is **toggled on** in the Initiative issue creation form, Cortex will automatically create tasks in the specified list for a given entity.

If a list is not specified in an entity's YAML and `Use list defined in entity YAML` option is **toggled on** in the initiative issue creation form, Cortex will attempt to create a list in the mapped space or folder above.

Define one of these following blocks in an entity descriptor to specify a list for Initiative issues.

**Specify list by ID**

```yaml
x-cortex-issues:
    clickup:
      initiativesList:
        id: 12345
```

| Field             | Description         | Required |
| ----------------- | ------------------- | :------: |
| `initiativesList` | Denotes that Cortex | **true** |
| `name`            | Name for the tag    | **true** |

**Specify list by name**

```yaml
x-cortex-issues:
    clickup:
      initiativesList:
        name: Cortex Initiative Issues
```

### Identity mappings

Cortex maps email addresses in your ClickUp instance to email addresses that belong to team members in Cortex. When [identity mapping](/configure/settings/managing-users/identity-mapping.md) is set up, users will be able to see their personal on-call status from the developer homepage.

Note that mapping options will not appear in Cortex for users who have not finished user registration in ClickUp. If a user is partially registered, Cortex will filter them out of the mapping page.

## Using the ClickUp integration

### Entity pages

**Integrations - ClickUp**

Tasks detected from your ClickUp instance will populate on the **Issue tracking** page in the entity's sidebar. Each row will show the following information (when available in ClickUp):

* Task name (hyperlinked to task in ClickUp)
* Project
* Assignees
* Priority
* Created at
* Due date

### Initiatives

Initiatives allow you to set deadlines for specific rules or a set of rules in a given Scorecard and send notifications to users about upcoming due dates.

From the Issues tab of an Initiative, you can automatically [create a ClickUp task from a failing rule](#create-a-task-from-an-initiative-issue).

### Dev homepage

The ClickUp integration enables Cortex to pull information about tasks into the Dev homepage. You can find open tasks assigned to you under the [Issues tab](https://app.getcortexapp.com/admin/home?activeTab=Issues).

Issues are refreshed every 5 minutes, or you can click **Refresh ClickUp tasks** to manually refresh issues.

### Scorecards and CQL

With the ClickUp integration, you can create Scorecard rules and write CQL queries based on ClickUp tasks.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

<details>

<summary>List of ClickUp tasks</summary>

Get ClickUp tasks meeting the given filter criteria.

* Assignees
* Created at
* Creator
* Due date
* Folder
* Priority
  * "Urgent", "High", "Normal," and "Low"
* Status
* Tags
* Task name

Statuses are dependent on your own ClickUp configured statuses. Closed tasks are filtered out by default.

**Definition:** `clickup.tasks()`

**Examples**

To evaluate the maturity of an entity in a Scorecard, you can use this expression to make sure it has fewer than five unassigned ClickUp tasks:

```
clickup.tasks().filter((task) => task.assignees.length < 1).length < 5
```

You can also query for entities that don't have any urgent ClickUp tasks with a "security" tag:

```
clickup.tasks(priorities=["Urgent"], tags=["security"]).length == 0
```

</details>

### View integration logs <a href="#still-need-help" id="still-need-help"></a>

## Create a task from an Initiative issue

Initiatives allow you to set deadlines for specific rules or a set of rules in a given Scorecard and send notifications to users about upcoming due dates. You can create a ClickUp task from a failing rule in an Initiative. Learn more in [Creating issues based on Initiatives](/improve/initiatives/issue-config.md).

The issue configuration will apply to all entities that meet the filter criteria. Once an entity is passing the rule, Cortex will automatically close the associated ticket.

## Background sync

Cortex conducts a background sync of ClickUp identities every day at 10 a.m. UTC. Pull requests and issues are refreshed every 5 minutes.

## Still need help?[​](https://docs.cortex.io/docs/reference/integrations/aws#still-need-help) <a href="#still-need-help" id="still-need-help"></a>

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: <help@cortex.io>, or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cortex.io/ingesting-data-into-cortex/integrations/clickup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.