Services¶

Status: Active

Application that contains views and connectors for all integrations used within IDK.

• Purpose: Centralize integration logic and UI hooks for external systems
• Details: Deep dive is covered in the Integrations section

Related: Integrations (ClickUp, Toggl, Jira, QuickBooks, Pipedrive)

Connectors and data normalization¶

To integrate external systems while keeping internal code consistent, Services uses:

• Connectors: thin adapters per provider that talk to external APIs and map responses into a common shape, for example:
• idk/services/connector_clickup.py
• idk/services/connector_toggl.py
• Skeleton classes: normalized domain models used internally so the rest of the app can work provider-agnostically. See idk/services/skeleton.py for classes like Project, Space, Folder, List, Task, TimeEntry, TeamMember, and Conversation.

Flow: - Connector fetches/updates data from the external API - Data is normalized into skeleton classes - Other apps consume these normalized objects, independent of the original provider

Skeleton classes¶

These are the normalized data structures defined in idk/services/skeleton.py:

• Project: normalized project from external services (id, name, company)
• Space: normalized ClickUp space (id, name, flags, members)
• Folder: normalized ClickUp folder (id, name, status flags, space linkage)
• List: normalized ClickUp list (id, name, metadata, parent references)
• Task: normalized task (ids, status, dates, points, assignees, locations)
• TimeEntry: normalized time entry (date, duration, description, billable, tags, user)
• TeamMember: normalized user/member (id, username, email)
• Conversation: normalized FrontApp conversation (subject, body, status, assignee, tags)
• Version: software/version metadata (name, release date)
• Build: CI/build metadata (message, status, timing)

Connectors¶

Below are the main connectors under idk/services/, each exposing provider‑specific operations while returning/accepting normalized data where possible.

ClickUp Connector (connector_clickup.py)¶

• Capabilities: spaces/folders/lists discovery; task CRUD and status updates; task search by custom fields; subtasks; list/folder/space find‑or‑create; time entries create/fetch; running entry lookup; tag operations; chat messages to channels; estimate updates from points; hierarchical map build with caching and rate‑limit handling.
• Normalization: converts API responses into Space, Folder, List, Task, and TimeEntry objects and persists key entities to local models (e.g., TaskInstance, ListInstance, FolderInstance, SpaceInstance).
• Notes: aggressive logging, caching via Django cache, exponential backoff on 429s.

Toggl Connector (connector_toggl.py)¶

• Capabilities: projects and members fetch; detailed time entries retrieval (paginated); per‑project times; create/delete time entries; tag lookup; dashboard data.
• Normalization: wraps time entries into TimeEntry and persists to TimeEntryInstance when appropriate.
• Notes: supports search filters and pagination via Toggl Reports API; uses workspace context from settings.

Jira Connector (connector_jira.py)¶

• Capabilities: issue/time data integration for Jira projects.
• Typical use: source of tasks/time for reporting and normalization alongside other providers.

Tempo Connector (connector_tempo.py)¶

• Capabilities: Jira Tempo timesheets/time entries retrieval.
• Typical use: unify Jira time with other sources into TimeEntry.

FrontApp Connector (connector_frontapp.py)¶

• Capabilities: conversations, inbox events, metadata sync.
• Normalization: maps inbound data to Conversation normalized objects for downstream processing.

QuickBooks Connector (connector_quickbooks.py)¶

• Capabilities: accounting entities (customers, invoices, payments), invoice number syncing (tasks_quickbooks.py).
• Typical use: align invoicing data with IDK contracts/invoices.

FreshBooks Connectors (connector_freshbooks.py, connector_freshbooks_v2.py)¶

• Capabilities: integrate FreshBooks billing entities via classic and v2 endpoints.
• Typical use: alternative/legacy accounting integration paths.

Insightful Connector (connector_insightful.py)¶

• Capabilities: workforce analytics/time activity ingestion.
• Typical use: supplement time insights beyond manual tracking.

Teamwork Connector (connector_teamwork.py)¶

• Capabilities: Teamwork projects/tasks/time data retrieval.
• Typical use: unify another PM/time source into normalized Task/TimeEntry.

Skeleton class details¶

The following normalized classes in idk/services/skeleton.py provide a consistent, provider‑agnostic shape. Key fields shown are indicative, not exhaustive.

Project¶

• Purpose: Generic project from any provider.
• Key fields: project_id, name, company.

Space¶

• Purpose: ClickUp space abstraction.
• Key fields: space_id, name, private, statuses, multiple_assignees, features, archived, members.

Folder¶

• Purpose: ClickUp folder abstraction under a space.
• Key fields: folder_id, name, private, orderindex, override_statuses, hidden, space_id, task_count, archived, lists.

List¶

• Purpose: ClickUp list abstraction under a folder/space.
• Key fields: list_id, name, orderindex, content, status, priority, assignee, task_count, due_date, start_date, folder_id, space_id, archived, override_statuses, permission_level.

Task¶

• Purpose: Unified task representation.
• Key fields: task_id, task_status, task_active, task_description, task_created, task_updated, task_due_date, task_estimated_time, project_id, project_name, assignees, task_color, points, location_ids, principal_location.

TimeEntry¶

• Purpose: Unified time entry representation.
• Key fields: id, project_id, billable, date, description, duration, task_name, user_id, user_name, tags, task_id, source.

TeamMember¶

• Purpose: Unified user/member from an external system.
• Key fields: member_id, username, email.

Conversation¶

• Purpose: FrontApp conversation abstraction.
• Key fields: conversation_id, subject, body, status, status_id, status_category, assignee_*, recipient_*, tags, ticket_ids, custom_fields, created_at, updated_at, waiting_since, is_private, external_conversation_ids, links, scheduled_reminders, metadata.

Version¶

• Purpose: Software/version metadata.
• Key fields: version_name, version_release_date.

Build¶

• Purpose: CI/build metadata for jobs.
• Key fields: message, status, started_at, finish_at, duration.