A productivity team app for storing all essentials such as tasks, documents, goals, chat, and more.
Supported syncing
| Type | Description | Supported Sync Modes | API Reference |
|---|---|---|---|
| Tasks | Sync data from any source to ClickUp tasks and subtasks | Upsert, Update, Insert | Tasks docs |
For more information about sync modes, refer to the sync modes docs.
Connect to ClickUp
Go to the Destinations overview page and click the Add destination button. Select ClickUp and click Continue. You can then authenticate Hightouch to ClickUp using OAuth.
Select Log in to ClickUp and log into your ClickUp account. You then need to select the ClickUp workspace or workspaces you want to connect to.
Once done, you will be redirected back to Hightouch to enter a descriptive name for your destination and complete setup.
Sync configuration
Once you've set up your ClickUp destination and have a model to pull data from, you can set up your sync configuration to begin syncing data. Go to the Syncs overview page and click the Add sync button to begin. Then, select the relevant model and the ClickUp destination you want to sync to.
Syncing tasks
In ClickUp, a task is a specific action or activity that needs to be completed to achieve a particular goal or objective. Hightouch supports syncing tasks and subtasks.
To get started, select the ClickUp workspace, space, folder, and list for your tasks. You can then choose to insert new tasks, update existing ones, or do both in upsert mode.
If you want to sync subtasks, you need to map the Parent field. Refer to the references section to learn more.
Hightouch doesn't update closed or archived ClickUp tasks. If your model contains data related to a closed or archived task, the sync creates a new task with the provided data.
Record matching
You can match rows from your model to tasks in ClickUp on identifer fields in ClickUp. The identifer fields you can use depend on your sync mode:
- In Upsert mode, you can match on custom fields, which are displayed as id in the dropdown menu.
- In Update mode, you can match on any of the following ClickUp fields:
- In Insert mode, ClickUp automatically generates an identifier for every new record synced, so there is no need to match an existing record.
To avoid unexpected duplicates or other potential issues, make sure you select a ClickUp field with unique values. Refer to the record matching docs for more information.
Field mapping
When creating a new task, ClickUp requires a name for it. Therefore, in upsert and insert modes, you must map the Name field to complete your configuration.
You can also map data from any of your model columns to default fields in ClickUp. The following default fields have some special guidelines:
- Status: The values you sync must be a valid statuses for your task. Status is case insensitive; for example,
in progressis the same asIN PROGRESS. See ClickUp's custom status docs for customization information. - Priority: This is a number that corresponds to the priorities available in the ClickUp UI. 1 is the must urgent priority while 4 is the least urgent.
- Time Estimate: This field must be in milliseconds.
Arrays
You can sync array fields to ClickUp by selecting model columns that contain either comma-delimited strings or arrays.
If you sync a comma-delimited string, for example "tag1, tag2, tag3", Hightouch transforms it into the array (["tag1", "tag2", "tag3"]) ClickUp expects.
Hightouch overwrites array values rather than aggregating them.
For example, suppose you sync the following array ["tag1", "tag2"] to the tags field of a particular task.
Then, a later sync sends another array ["tag1", "tag3"] to the same task's tags.
The tasks tags will be ["tag1", "tag3"], not ["tag1", "tag2", "tag3"] after the later sync runs.
References
You can relate tasks to other ClickUp objects while field mapping.
To do so, select a ClickUp reference field. Hightouch denotes these with a chainlink icon. Begin by selecting one of these fields, for example Links to. The Links To field lets you include a task ID to create a linked dependency for the task you're syncing.
Then, select a field on the object you're referencing to match on, for example, a task's ID, and the corresponding column from your model.
Hightouch uses this column to look up the related object's ID and create the relationship with the task you're syncing. Generally, it's best to match on ID fields, but Hightouch also supports matching on meaningful properties like email for users.
A common reference field is Parent. Mapping to the Parent field lets you sync subtasks.
The preceding screenshot shows associating a parent task to a subtask based on the parent's task ID. The parent cannot be a subtask itself and it must be part of the ClickUp list you selected in the sync configuration.
Hightouch syncs only one value to reference fields. This includes reference fields like assignees that allow multiple values.
Custom field mapping
Hightouch supports syncing data to these custom field types:
| Custom field type | Expected data type or description | Example |
|---|---|---|
| Checkbox | Boolean value | true or false |
| Date | Millisecond Unix timestamp; See the date formatting tip. | 1682452269219 |
| Dropdown | A series of options in a menu | - |
| Valid email address | lana@clickup.com | |
| Labels | A flexible list of options (invalid labels will be omitted) | - |
| Money | A numerical value | 9.99 |
| People | People or teams, see (#references) | Sam |
| Phone | A valid phone number with country and area code | "+1 123 456 7890" |
| Rating | A number value from 1 through 5 | 5 |
| Tasks | Tasks linked together without relationships | Task A |
| Text | Single-line text | "This is a single-line text" |
| Text Area | Multi-line text | "This is a multi-line text..." |
| Website | A valid URL | https://clickup.com |
Delete behavior
The delete behavior you select dictates what to do when a row no longer appears in your model's query results. You have the following options for upsert mode:
| Behavior | Description |
|---|---|
| Do nothing | Keep the task in ClickUp with all its synced fields |
| Clear | Clear all the mapped fields, but keep the task in ClickUp |
| Delete | Delete the synced tasks from ClickUp |
Update mode has these options:
| Behavior | Description |
|---|---|
| Do nothing | Keep the task in ClickUp with all its synced fields |
Insert mode doesn't support any delete behavior.
Tips and troubleshooting
Formatting dates
ClickUp expects millisecond Unix timestamps for all date fields.
A millisecond timestamp is numerical value with 13 digits, for example, 1620170285617, as compared to a traditional Unix timestamp which has ten.
A convenient way to convert your date values to Unix millisecond timestamps is to use the to_unix function in the template mapper.
The to_unix function throws an error if the input row's value is null. To avoid this, you can enter this Liquid into the template mapper:
{%- if row['column_name'] == null -%}
{{null}}
{%- else -%}
{{row['column_name'] | to_unix}}
{%- endif -%}Be sure to replace column_name with the name of your model column.
Common errors
To date, our customers haven't experienced any errors while using this destination. If you run into any issues, please don't hesitate to . We're here to help.
Live debugger
Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.
Sync alerts
Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.