Jira Heirarchy Integration

The Jira to ClickTime Integration is an automated, scheduled synchronization that aligns your organizational hierarchy in Jira with your ClickTime workspace. By mirroring Jira Project Categories, Projects, and standard Root Issue Types into ClickTime Clients, Jobs, and Tasks, this one-way integration ensures your teams track time against accurate, up-to-date entries with zero administrative double-entry.

1. Integration Overview & Benefits

Keeping your task management system and timesheet database aligned is a critical requirement for accurate project costing, billing, and resource planning. The Jira to ClickTime Integration runs seamlessly on a recurring cron interval, transferring operational structural parameters from your Jira instance to ClickTime.

This one-directional synchronization manages three core operational tiers: Clients, Jobs, and Tasks. It actively monitors adjustments inside Jira and processes only newly added or modified entities while skipping unchanged entries.

Key Business Benefits:

• Seamless Hierarchy: Automatic translation of Project Categories to Clients, Projects to Jobs, and Issue Types to Tasks.
• Delta Optimization: Minimizes API overhead by only updating changed data.
• Workflow Flexibility: Turn individual sync pathways on or off independently via the admin console.

2. Operational Mechanics (How It Works)

The integration executes a strictly one-directional (Jira → ClickTime) mapping flow. The structural mapping logic is standardized across these target entity relationships:

3. Step-by-Step Configuration Wizard

To configure the integration, administrators complete a 5-page setup wizard in the ClickTime Administration Console.

Page 1: Core Connections & Global Options

1. ClickTime Connection: Input your ClickTime API Key to authorize the ClickTimeComponent (version 267) to manage database structures.
2. Jira Connection: Enter your host domain (e.g., your-domain.atlassian.net) and basic Jira API token to authorize the atlassian-jira component (version 75).
3. Notification Email Address: Set the administrative email address for status reports, logs, and sync conflict warnings.
4. Disable Emails Flag: A boolean toggle (defaulting to false). Set to true to suppress automated emails during sandbox sync runs or diagnostic tests.
5. ClickTime-PrIntegration-DB: Configure the internal MS SQL Server database connection string to track sync configurations and mapping relationships.
6. SendGrid Connection: Authenticates the SendGrid delivery module (version 82) to push automated notifications to administrators.
7. External System Name: A custom system label (defaults to "Jira") used to dynamically prefix system logs and email notification headers.

Page 2: Client Options

1. Client Mapping: Select Project Categories to trigger active sync. Select --DO NOT SYNC-- if you wish to manage your ClickTime Client list manually.
2. Default Client: Choose an active ClickTime Client from the dynamic database dropdown. Any incoming project that lacks a parent category (or if Client mapping is disabled) will default to this selection.

Page 3: Job Options

1. Job Mapping: Select Projects to map Jira Projects directly to ClickTime Jobs. Select --DO NOT SYNC-- to manage Jobs manually.

Page 4: Task Options

1. Task Mapping: Select Issue Types to synchronize standard Jira Issue Types as ClickTime Tasks. Select --DO NOT SYNC-- to manage Tasks inside ClickTime manually.

Page 5: Finalize, Concurrency, and Cron Settings

1. Client Concurrency: Set numerical limits for parallel Client processing (default 10, absolute maximum 15) to throttle database workloads.
2. Job Concurrency: Set numerical limits for parallel Job upsert processing (default 10, absolute maximum 15).
3. Sync Hierarchy Schedule: Cron interval expression to control execution frequency (defaults to 0 */4 * * *, running every 4 hours).

4. Advanced Data Mapping Specifications

The technical definitions below specify how target objects are transformed, mapped, and parsed by the integration runtime:

Jira Project Category → ClickTime Client Mapping

Jira Project → ClickTime Job Mapping

Jira Issue Type → ClickTime Task Mapping

5. Deployment Modes: SEED vs. SYNC

To guarantee high-fidelity data migration and protect any pre-existing manual structures, the integration utilizes two operational modes:

6. Technical Flow & Orchestration

The integration runs on an asynchronous pipeline structured to handle large volumes of data while preventing thread blocks or database lockups.

1. Cron Trigger: The scheduler initiates execution. Multiple simultaneous trigger requests are blocked to maintain singleton operation execution.
2. Jira Fetching: Atlassian's endpoints are called in parallel to retrieve category structures, projects (active and archived), and standard root issue types.
3. Local Delta Filters: Evaluates incoming records against active local ClickTime data. Elements without any changes are filtered out.
4. Batch Chunking: Hardcoded batching groups modified records into distinct chunks of 25 records.
5. Process Webhook: Distributes each chunk to processing queues via POST webhooks, executing with parallel-concurrency values up to 15.
6. Verification & Storage: Checks mappings against uspPrGetEntityMapping, checks numbers inside ClickTime if mapping is absent, chooses the appropriate action (MAP, UPDATE, or INSERT), and updates the DB via uspPrSaveEntityMapping.

7. Troubleshooting & Error Resilience

The integration contains built-in, automated exception handlers to resolve sync conflicts without interrupting overall performance:

• API Call Retries: Primary read operations (getActiveClientsRequest, getActiveJobsRequest, and getActiveTasksRequest) use a built-in retry mechanism. If a connection drops, the integration waits exactly 16 seconds before retrying the call.
• Ignore on Search: Key structural lookups (e.g., getClientByClientNumber or getJobByJobNumber) are set to "ignore". If a search returns "not found", the system continues with an INSERT instead of stopping.
• Skipping Jobs (Client Missing): If a Jira Project's parent category cannot be resolved, and no Default Client was specified on Page 2 of the setup wizard, the system skips the Job. It logs a status of OK-JOB-SKIPPED-CLIENTNOTFOUND and continues without failing.
• Inactive Record Safeguard: Archived Jira records with no pre-existing ClickTime mapping are skipped. The integration only deactivates *existing* active ClickTime Jobs; it will not create a new, inactive record.
• Decoupled Logging and Alerts: All transaction logs (uspPrLogEvent) and email notifications (handled via SendGrid using custom SQL templates from uspPrGetNotificationType) are processed asynchronously, ensuring notification steps do not slow down the core time-tracking sync.

8. Frequently Asked Questions (FAQ)

Can timesheets or tracked hours in ClickTime sync back into Jira?

No. This integration is strictly one-directional (Jira → ClickTime). It manages Client, Job, and Task structures in ClickTime based on your Jira setup, but does not transfer timesheet data or hours back to Jira.

What happens if an active Jira Project Category is renamed?

During the next scheduled SYNC run, the integration will detect the name change. It will identify the matching mapping using the unique Jira ID and update the Client's name in ClickTime (using updateClientRequest).

If a Jira Project is deleted, does it delete the ClickTime Job?

No. To protect historical tracking and time entries, the integration does not delete records in ClickTime. Renaming, deleting, or re-categorizing parent records in Jira will never trigger deletion in ClickTime.

Why are our custom Jira sub-tasks or epics failing to synchronize?

The Task synchronization path is restricted to root Jira issue types with hierarchyLevel === 0. This is designed to keep your ClickTime task lists concise and easy for employees to navigate during timesheet entry.

Can we adjust how often the synchronization runs?

Yes. On Page 5 of the configuration wizard, administrators can adjust the Sync Hierarchy Schedule. This field supports standard cron expressions (defaulting to 0 */4 * * * for an execution every 4 hours).