How Integration Hub works, section by section

Integration Hub keeps a traceunified record and its twin in another tool in step. Jira and GitHub have built-in connectors, and any tool with a conventional REST API connects through a declared contract. Your engineers keep working where they already work, and the controlled record stays where an auditor can read it.

This guide walks through the Hub one screen at a time, in the order you will meet them when you set up your first integration.

The three objects, and why there are three

Everything in the Hub is built from three things. Most confusion about integrations comes from mixing them up.

• A connection is how we reach the other tool: its address and a credential. Nothing more.
• A collection is what we are talking about over there: which of that tool’s projects are in scope, which artifact type, and which traceunified item type those artifacts map onto.
• An integration is what actually moves: it runs a collection, on its own schedule, with its own rules for direction, filtering and collisions.

One connection can serve many collections, and one collection can be run by several integrations. traceunified is always one end of every integration. The Hub does not route between two external tools.

Landscape — what is wired to what

Landscape draws your whole estate in three bands: the repositories (traceunified plus each connected tool), the collections written against them, and the integrations that run those collections. Four figures above the drawing count each band and say how many integrations are in error.

The point of the screen is the second click, not the first. Clicking any node isolates its chain and dims everything else. That answers the question every other list makes you work out in your head: if I rotate this Jira credential tonight, what stops? Click the connection and you see exactly which collections and integrations depend on it, and nothing that doesn’t.

Connections — reaching the other tool

A connection holds the address of a Jira, GitHub or REST tool and the credential used to reach it. Depending on the tool, that is a personal access token or OAuth 2.0.

• The credential is encrypted before it is stored and is never shown again. When you edit a connection, leaving the secret blank keeps the stored one. Nothing on the screen can read it back.
• A health check proves the credential still works. A connection that stops authenticating shows up in Activity as a setup problem rather than as a string of failed cycles.
• Webhooks are optional, and the connection tells you whether yours works. Each connection shows a callback URL and a secret for you to register in the other tool. Once registered, the connection records when a verified delivery last arrived. A webhook you registered that has never actually called is flagged, rather than trusted because it was configured.

Connections are held at the organisation level. Each project then chooses what it syncs.

Collections — what the artifacts are

A collection is four facts: the tool, which of its projects are in scope, which of its artifact types, and which traceunified item type those artifacts map onto. Some are chosen when you create it. The rest are set on the collection’s own page.

That page is where the mapping lives:

• Field mapping pairs each of your item type’s fields with the field it corresponds to in the other tool: Title with Summary, Status with status. It also checks the fields the other tool requires before it will create something, so a missing one surfaces at setup rather than as a failed write.
• Value maps translate picklists whose values differ on each side, so High here can mean P1 there.
• Relationships pair your trace relationships with the other tool’s link types. A link drawn in Jira becomes a real trace link here only where the collection maps that relationship. The Hub never invents a trace rule.
• Attachments, comments and relationships are paired the same way, against whatever the tool calls its equivalent.

Because traceunified is always one end, your item type is the shared model. There is no separate “canonical model” to maintain.

Integrations — what moves, and how

The Integrations list shows each integration as a wire between traceunified and the tool it talks to. Arrowheads show which way items flow. While an integration is running, packets travel the wire and the disc at its centre turns. Each integration can be paused and run again from its row.

Open one and its behaviour is split into eight aspects:

• Overview: which projects it covers, how many routes it has, and which item type it carries.

• Artifact creation: which side is allowed to create records in the other.

  • Outbound: a traceunified item creates its twin in the other tool.
  • Two-way: either side creates for the other.
  • Inbound: the other tool’s artifacts become traceunified items and nothing is created over there.

  The screen states the consequence of each. An item created from another tool has no approval history and no author here. Its origin is recorded as this integration and the administrator who chose the style.

• Field flow: for every mapped field, whether it moves out, in, or both ways. The declared list is the policy. A field left undeclared follows the collection, not a hidden default.

• Widget flow: the same question for attachments, comments and relationships.

• Routing: pairs a project (or a folder or set inside it) with a project in the other tool. Nothing travels until a route says so, so the scope of a sync is something you can point at.

• Filtering: which items on a route are eligible, in your own field names: is, is not, contains, does not contain, is empty, is not empty. A blank filter admits everything on the route, and the screen shows exactly what each cycle sends.

• Change detection: how often the engine asks what changed. By default that is a poll every five minutes, with a full scan every 24 hours behind it. Polling is the guarantee: a missed webhook costs latency, never a change. Register a webhook and edits arrive in seconds instead.

• Conflict resolution: what happens when the same two-way field was edited on both sides in one cycle. There are four answers, and the screen says whose work each one discards:

  • Report the collision is the default. Neither side is written, nothing is lost, and it is raised until someone settles it.
  • traceunified wins.
  • The external tool wins.
  • Most recent wins. This one is refused on any field whose change invalidates an approval, because a clock cannot decide a value a signature depends on.

Activity — everything the engine cannot finish on its own

Activity is the one screen you check routinely. At the top, the last 24 hours of sync cycles are counted by outcome: succeeded, moved nothing, failed, aborted, running and stalled. A high share of cycles that “moved nothing” is shown on purpose. An estate that succeeds every cycle while moving nothing is usually connected to nothing.

Below that, four tabs:

• Setup problems are configuration issues, each with its remedy. Examples: a paused integration, one with no routing, a route that has never linked anything, a connection that no longer authenticates or is read-only, a webhook with no secret or one that has never been received, and a cycle that stopped midway with nothing started on that route since.
• Errors are links that are not moving, in three states:
  • Held: outbound writes are paused for a reason the item itself supplies: its approval was superseded, a controlled status locked it, it is frozen, or it is checked out. Inbound changes keep mirroring.
  • Failing: the last attempt errored, and the error is shown.
  • Orphaned: one end of the link no longer exists.
• Pending lists writes waiting to be delivered to the other tool.
• Past activity lists writes that were delivered.

You act from here. You can queue a failed write again, abandon it, or clear a link’s error, one at a time or in bulk. Abandoning and clearing require a written reason, which is recorded.

Activity is also where account mapping announces itself. An inbound edit made by an external account the Hub cannot match to a person is held, not attributed to someone plausible. The Hub matches your explicit mappings first, then a matching rule such as the same email address, and it has no fallback user. The count of unattributed edits links to the queue where an administrator maps each account once.

Sync history — what every cycle did

Sync history is the engine’s log: one row per cycle, showing when it ran, what triggered it, how it ended and what it moved. Open a row for per-item detail, including why anything was skipped and the other tool’s own error text. The log also knows one thing nothing else does: continuity. It flags a window of external change that no cycle ever read.

Two things this screen deliberately is not:

• It is not the audit trail. An inbound change to a controlled item lands through the same save path as a person’s edit: a new version of the item and an audit entry, attributed to the mapped individual. That is the durable record. Sync history says how the cycle went. It is kept for a window your administrator sets (90 days unless configured) and is labelled on screen as operational, so nobody cites it as evidence.
• It is not a control panel. Nothing here starts or retries anything. You start an integration on the integration and retry a failed write from Activity, so the record of what happened cannot also be the place things are made to happen.

Trace coverage — what the sync did to the trace matrix

Every other screen in the Hub asks what the sync did to a field. Trace coverage asks what it did to the trace matrix. That question matters because a sync that brought in fifty requirements reports itself as a success on Activity and on Sync history, whether or not anyone ever traced them.

A synced item is a native traceunified record, so everything the digital thread does to a record it does to this one. A requirement that arrived from Jira can be traced, tested, baselined and reviewed like any other. Trace coverage measures how many actually are.

Choose a project and it shows four figures:

• Items linked externally: how many of the project’s items have a twin in another tool.
• Appear in a trace link: how many of those are traced, and what share that is.
• In no trace link at all: the finding, and the only figure that is ever highlighted.
• Of those links are suspect: how many of the trace links touching synced items are currently suspect.

Below the figures, the untraced items are listed by their external key and their traceunified ID, for example KAN-19 and PMS-TC-004, with each link’s state. A link whose item no longer exists is shown as such, because it is untraced for a different reason. An item counts as traced if it appears in a trace link in either direction.

The screen also states what its figures do not establish, alongside the figures rather than behind a disclosure. A trace link records that it is suspect but not what made it so, so the suspect count describes the state of the synced items and is never attributed to the sync. Attachment links do not count as traces. And this is one intersection, not the trace matrix itself: whether a given item type must trace to another is still the matrix’s question.

Trace coverage is available to organisation administrators, quality managers and project managers. Each person sees only the projects they can read.

A setup order that works

1. Connection: add the tool and its credential, and check it passes its health check.
2. Collection: choose the projects and artifact type, then map fields, values, relationships and attachments.
3. Integration: choose the artifact-creation style, declare field flow, add a route, and set a filter if not everything on the route should cross.
4. Conflict resolution: decide what settles a two-way collision before two people edit the same field.
5. Run it, then open Activity. Setup problems lists whatever is still missing. Once it is clear, map any unattributed accounts it reports.
6. After the first cycles, open Trace coverage for each synced project, and trace what arrived before it piles up.
7. Optionally, register the webhook, and confirm on the connection that a verified delivery arrived.

The Hub does not move items through another tool’s workflow. It keeps fields, links, comments and attachments in step, and leaves each tool’s own transitions to that tool.