Build a tracker driver

A driver adapts your tracker's API to GrigDesk's task format. It is a separate Git package installed through board settings.

When to use a separate package

Use one for another task system or a portal with custom authentication, statuses, timers or reports. The self-hosted Bitrix24 case explains where the standard driver's compatibility may end.

Tracker drivers and user plugins are different package types. A driver supplies data to the shared board; a custom panel belongs in a plugin.

Package structure

team-tracker/
  driver.json
  driver.ts
  src/
  types/

An example manifest for your own package:

{
  "id": "team-tracker",
  "name": "Team tracker",
  "version": "1.0.0",
  "contract": 1,
  "settings": {
    "baseUrl": {
      "type": "string",
      "required": true,
      "label": { "text": "Tracker address" }
    },
    "token": {
      "type": "string",
      "required": true,
      "secret": true,
      "label": { "text": "Access token" }
    }
  }
}

The default export of driver.ts is a TrackerFactory. It receives a TrackerHost and returns a TaskTracker. The installed version's contract lives in server/src/lib/trackers/contract.ts and shared/trackers/contracts.ts. Standard external drivers keep their own type snapshot and do not import core code at runtime.

What to implement

Area	Driver responsibility
Connection	isConfigured, testAuth, accountIdentity; credentials come from host.credentials.
Reading	listTasks, taskDetail, getDashboard, sourceUrl, probeTaskNumber.
Actions	Only supported methods, such as creation, comments, timers or status changes.
Capabilities	Declare available actions in capabilities; leave unsupported actions disabled.
Presentation	Status text and meaning, task card data, numeric KPIs and charts. Widget code and HTML are not sent to the interface.

Keep session authentication and API-specific behavior inside the package. The GrigDesk server stores credentials; keep real tokens out of Git. Honor read cancellation and queue behavior defined by the contract.

Verify and install

Start with prepared API responses: authentication, lists, task details, statuses, supported actions, permission errors and an unavailable portal. For customized Bitrix24, also verify your portal's handlers and fields.

Give the package a unique id; own is reserved for the internal tracker. The manifest version must match a stable vX.Y.Z tag. Follow the normal driver installation, configure access and verify it using a test project on the portal.