Collectors

OverviewCopy Anchor Link

A collector reads the work items of one tracker into a workspace. It gives each item a number, such as WI-12, and keeps the item in step with the tracker. Triage, briefs, and sends then work on the item the same way for every tracker. See Work for that path.

A collector can also write back to the tracker. Each kind of write sits behind its own switch. A collector added in the app starts with every switch off except create, text, and badge.

TrackersCopy Anchor Link

Oxagen turns a tracker on only after its collector passes a sandbox check. Until then the tracker's page describes how its collector works once Oxagen turns it on.

What every collector doesCopy Anchor Link

• Connect. A collector reads through a connection of its tracker's own provider. A person with the organization Owner role, or the workspace Admin role, connects it. An API key or an agent run cannot add a collector, change one, or start a sync.
• Scope. The collector names the places it reads, such as teams, projects, or repositories. It reads nothing else.
• Read. A webhook rings the doorbell. Oxagen then reads the item from the tracker's API and maps what it read. It never maps the webhook body. A reconcile every 15 minutes reads what a webhook missed.
• Treat tracker text as data. An item's subject, description, and requester can come from people outside the workspace. Oxagen marks them tainted and shows them as text. It never follows them as an instruction.
• Write only a person's own text. Oxagen writes a title or a description only when it creates the issue for an item a person saved in Oxagen, and when a person edits that text in Oxagen. It never deletes an item, never assigns anyone, and never replies to a requester.

Sections of a tracker pageCopy Anchor Link

Each tracker page has the same sections, so you can compare trackers.

1. Account to connect with. Who signs in, and whose name appears on writes.
2. Scopes asked for. The permissions Oxagen requests from the tracker.
3. Scope choices. What the collector can read, and what the places look like in a collector file.
4. Default field mapping. How the tracker's statuses, resolutions, priorities, and types read as Oxagen values.
5. What each switch writes. The write-back switches and the tracker call behind each one.
6. What the tracker cannot do. Limits that come from the tracker.
7. Webhook and reconcile timing. How fast Oxagen hears of a change.

Field mappingCopy Anchor Link

Every tracker maps its own values to the same Oxagen statuses (Open, Blocked, Closed), resolutions (Done, Won't do, Duplicate, Canceled), and labels (a Priority label, P0 to P3, and a Type label). A mapping row has a direction. A read row says which tracker values read as an Oxagen value. A write row says which tracker value Oxagen writes for it. A workspace that has no rows for a tracker gets the defaults on its tracker page. An Owner or Admin changes a row in Work setup, under Fields, or with set_work_field_mapping. get_work_fields reads the mapping back.

Write-back switchesCopy Anchor Link

A collector file has a [write_back] table with eight switches. A switch the file leaves out takes the default. A collector added in the app starts with every switch off except create, text, and badge.

The capability input calls the status switch status_sync. A paused collector writes nothing. A write that cannot succeed until something changes is recorded once and skipped until you fix the cause. The causes are mapping_missing, status_unreachable, item_gone, and forbidden. A rate_limited or unavailable answer is retried on a later check.

Creating the issueCopy Anchor Link

Saving a work item in Oxagen creates its issue in the tracker of the collector that covers the item's repository, when that collector's create switch is on. The switch is on for every collector that writes back, so turn it off for a collector that should not create issues. The save never waits for the tracker. Oxagen asks the collector to make the issue as soon as the save is stored, so the link usually shows within seconds. The item shows the issue once it exists, or the reason and a Retry button. A retry finds an issue an earlier try already made, so one item never gets two issues. Oxagen leaves the issue's assignee empty.

• A GitHub collector covers the repositories its scope names.
• A GitLab collector covers the projects its scope names.
• A Linear or Jira collector covers the repositories its scope names in repos. It creates the issue in the team or project its scope names in create_team or create_project, or in its only team or project.

GitHub has no attachment API, so a GitHub issue links each file at an Oxagen address. Linear, Jira, and GitLab store each file with the issue.

A send note on a public item shows no cost, because anyone who can read the item can read the note. It lists each run and why it ended, and the work order in Oxagen shows the cost.

The work item badgeCopy Anchor Link

When a GitHub or GitLab collector reads an open issue into a new work item, Oxagen puts a badge at the top of the issue's description. The badge links to the item's page in Oxagen, so a person reading the issue can open the item in one click. An issue Oxagen creates gets the badge when it is made.

The badge sits between two HTML comments, which GitHub and GitLab show as nothing. Each time Oxagen reads the issue, it takes the badge out before it stores the description. So the badge never shows in the item's description, and putting it on the issue records no change to the item. When a person edits the description in Oxagen, the badge stays at the top of the issue.

Oxagen writes the badge once per item and leaves the rest of the description as it was, line endings included. If someone puts other text between the two comments, Oxagen leaves the description alone and keeps that text in the item. Issues a collector read before the badge existed have none. Turn the badge switch off to stop new badges. Badges already on issues stay.

Rate limitsCopy Anchor Link

Every request to a tracker other than GitHub counts against two limits: one for the tracker across every workspace, and one for the connection. A request over either limit waits for the next window. A reconcile moves its cursor only after it stores a page, so a read that fails partway loses nothing.

Source manifestCopy Anchor Link

A work item shows the name and mark of its tracker. Source manifest explains how a workspace changes both from its steering repo.

SettingsCopy Anchor Link

A tracker's sign-in needs client credentials in the deployment, and a tracker that sends webhooks needs a shared secret, which Oxagen uses to check that each webhook came from the tracker unchanged. Each tracker page links the settings it uses. Which tracker a build ships depends on its collector modules, not on a setting.

Capability referenceCopy Anchor Link