ClickUp

CatalogScorecards

ClickUp 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 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
Create Scorecards 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.

Configure the integration in Cortex

In Cortex, navigate to the ClickUp settings page:
1. In Cortex, click your avatar in the lower left corner, then click Settings.
2. Under "Integrations," click ClickUp.
Configure the ClickUp integration form:
- API token: Enter your ClickUp API token.
Click Save.

caution

If you do not see the settings page you're looking for, you may not have permission to access that page. Please contact your admin for assistance.

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.

How to connect Cortex entities to ClickUp

Auto discovery of spaces, folders, and tags

By default, Cortex will use the entity tag (e.g. my-entity) as the "best guess" for ClickUp space, folder, or tag. For example, if your entity 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 entity tag, you can override this in the Cortex entity descriptor.

Editing the entity descriptor

If you need to override automatic discovery, you can define the following block in your Cortex 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.

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

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.

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

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.

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

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

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 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.

Expected results

Entity pages

Integrations - ClickUp

Tasks detected from your ClickUp instance will populate on the ClickUp page under the Integrations tab. 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.

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.

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 in Cortex.

List of ClickUp tasks

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

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.

From the Issues tab of an Initiative, you can automatically create a ClickUp task from a failing rule:

Click Create issue.
In the modal that appears, fill out the form:
- Integration: If you have multiple task tracking tools, select ClickUp from the Integration dropdown.
- Name: Enter a name for the configuration.
- Project: Select a project from the dropdown.
- Use list defined in entity YAML: Enable this toggle if you want to use the ClickUp list defined in a given entity's YAML. will override the "Space" field with "Default space."
  - Default space: This field appears if you have enabled the toggle above. Choose the The ClickUp space where the issue will be created if there is no list defined in the entity YAML.
- Space: Choose a space from your configured ClickUp instance.
Click Next.
Fill out the additional fields:
- List: Select a list from the dropdown.
- Tag: Enter a tag.
- Priority: Select a priority level from the dropdown.
Click Next.
- If you have any custom fields configured in ClickUp, you may need to configure additional fields here then click Next.
Choose whether to include or exclude specific entity types.
Click Save issue config.

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?

The following are all the ways to get assistance from our customer engineering team. Please use the option that is best for your users:

Email: help@cortex.io, or open a support ticket in the in app Resource Center
Chat: Available in the 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.

How to configure ClickUp with Cortex​

Prerequisites​

Configure the integration in Cortex​

How to connect Cortex entities to ClickUp​

Auto discovery of spaces, folders, and tags​

Editing the entity descriptor​

Mapping spaces by ID or name​

Mapping folders by ID or name​

Mapping by tags​

Specify a list for Initiative issues​

Specify list by ID​

Specify list by name​

Identity mappings​

Expected results​

Entity pages​

Integrations - ClickUp​

Initiatives​

Dev homepage​

Scorecards and CQL​

Create a task from an Initiative issue​

Background sync​

Still need help?​