Asana Integration Setup Guide
The Asana integration for ClickTime allows you to automatically sync your Asana Projects as ClickTime Jobs. This integration ensures that your project structure remains consistent across both platforms, utilizing real-time webhooks for immediate updates and a scheduled hourly resync to maintain data integrity.
Overview
By default, the Asana integration maps Asana Projects to ClickTime Jobs. All synced jobs are assigned to a single ClickTime Client selected during the setup process.
Key Features
- Real-time Sync: Changes in Asana (project creation, updates, or deletion) are reflected in ClickTime almost immediately.
- Hourly Resync: A full hierarchy resync runs every hour to ensure no data was missed.
- Duplicate Prevention: On the first deployment, the integration performs a "SEED" sync to map existing ClickTime records to Asana projects, preventing duplicate entries.
Prerequisites
Before beginning the setup, ensure you have the following information ready:
- You've contacted ClickTime Support (support@clicktime.com) or worked with your Customer Success Manager to gain access to the integration. This integration carries its own individual cost and requires your account is on a 12-month prepaid contract.
- ClickTime API Key: An API key with administrative permissions to read and write data.
- Asana Workspace: Access to the Asana workspace you intend to sync.
- Notification Email: An email address where integration status and error notifications will be sent.
Configuration and Setup
To enable the Asana Integration, our Services Team will navigate you through the setup portal:
1. Connection Settings
- ClickTime Connection: Enter your ClickTime API Key.
- Asana Connection: This is typically managed at the organizational level. You will be prompted to authorize ClickTime to access your Asana data.
- Notification Email Address: Enter the email address for system alerts.
2. Hierarchy Options
- Asana Workspace: Select the specific Asana workspace you wish to sync from the dynamic dropdown.
- ClickTime Client: Select the ClickTime Client that all synced Asana Projects should be assigned to.
- Job Mapping: Set this to "Projects" to enable the sync. (Setting this to "DO NOT SYNC" will pause the integration).
3. Schedule
- The Sync Hierarchy Schedule defaults to an hourly cron schedule (
0 */1 * * *).
Data Mapping
The following table outlines how data fields are transferred from Asana to ClickTime:
| Asana Field | ClickTime Field | Notes |
|---|---|---|
| Project Name + GID | Job Name | Names are formatted for uniqueness and capped at 50 characters. |
| Project GID | Job Number | Used as the unique External ID for record matching. |
| Archived Status | IsActive | If a project is archived in Asana, the ClickTime Job is marked inactive. |
| Project Notes | Notes | Transferred directly into the ClickTime Job notes field. |
Job Name Formatting Logic
To ensure uniqueness in ClickTime, the integration appends the Asana Project GID to the name:
-
Standard:
Project Name (GID) - Truncation: If the name is too long, the integration will use the last few characters of the GID or truncate the name to fit ClickTime's 50-character limit.
Advanced Sync Options
While the default deployment focuses on Projects and Jobs, the integration supports optional advanced sync domains:
- Task Sync (Asana Sections → ClickTime Tasks): Can be enabled to sync Asana Sections as ClickTime Tasks. Note that sections with the same name across different projects will map to a single global ClickTime Task.
- Client Sync (Asana Portfolios → ClickTime Clients): Can be enabled to sync Asana Portfolios as ClickTime Clients, allowing for dynamic client assignment rather than a single fixed client.
Troubleshooting & FAQ
Q: Will the integration create duplicates of my existing jobs?
A: No. During the initial "SEED" sync, the integration looks for existing ClickTime Jobs with a Job Number that matches the Asana Project GID. If a match is found, the records are linked rather than duplicated.
Q: What happens if I rename a project in Asana?
A: The real-time webhook will trigger an update in ClickTime, and the Job Name will be updated accordingly during the next sync cycle.
Q: How do I stop the sync temporarily?
A: You can set the Job Mapping configuration variable to "DO NOT SYNC." This will stop both the real-time updates and the scheduled hourly resync.
Comments
0 comments
Article is closed for comments.