ClickUp
ClickUp is a project management tool that combines tasks, document collaboration, and issue management in a single platform.
By integrating ClickUp with Cortex, you can drive insights into customer requests, security tickets, and ongoing projects. You can also create ClickUp tasks directly from Cortex based on Initiatives.
Setup and configuration
In order to connect Cortex with your ClickUp instance, you'll need to create a personal API token.
Configuration
Once you've created the API token, you'll set up the integration under ClickUp settings in Cortex. Paste the token in the Personal API token field and click save.
If you do not see the settings page you're looking for, you likely don't have the proper permissions and need to contact your admin.
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.
Registration
Discovery
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.
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.
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
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
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
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.
First select Create issue to open the Initiative issue creation form.
- Integration: If you have multiple task tracking tools, select ClickUp from the Integration dropdown.
- Name: A name for the configuration.
- Use list defined in entity yaml: This toggle will use the ClickUp list defined in a given entity's YAML and will override the "Space" field with "Default space."
- Default space: The ClickUp space where the issue will be created if there is no list defined in the entity YAML.
- Space: Options available in the dropdown are pulled in from the ClickUp instance configured in Settings.
Next, select list, tag, and priority level from the respective dropdowns. Finally, you can choose to include or exclude groups of entities, or define a more advanced filter.
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.