How Integration Hub works, section by section

Integration Hub keeps a traceunified record and its twin in another tool in step. This release connects Jira and GitHub, which sync items both ways, and Bitbucket Cloud, which links the commits and pull requests that name an item back to it. 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 Bitbucket account and the credential used to reach it. For Jira that is an API token or OAuth 2.0. For GitHub it is a personal access token or OAuth 2.0. For Bitbucket it is an API token or a workspace access token.

• 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.
• The product sets up its own webhook. When the connection’s account can manage webhooks (a Jira administrator, or a GitHub or Bitbucket token with webhook permission), traceunified registers one in the other tool, scoped to the projects you route. It checks it daily and recreates it if someone deletes it, so edits arrive in seconds with nothing to click. When the account cannot, the connection runs on the poll alone, and still misses nothing.
• Change detection is a status, not a setting. Each connection reads Webhook + poll (changes in seconds, with when the last delivery arrived) or Poll (changes on the next poll). There is no poll-only switch: the poll always runs, and the webhook only makes it faster.
• Connections start read-only. A connection can read but never write until an organisation administrator switches on its write policy.
• A webhook made by hand is left alone. If you register one yourself with the URL and secret the connection shows, the product never overwrites it or adds a second. The connection records when a verified delivery last arrived, so a webhook that has never actually called is flagged rather than trusted.

A generic REST connector is built but not offered in this release. A connector is released only once it has run against a live instance of its tool.

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 row has one control, and it toggles: Run starts the integration and runs a cycle straight away, and Pause stops it. There is no separate “poll now”. To make a running integration catch up, pause it and run it again, or use Bulk Actions to run several at once.

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. Where the product has registered a webhook, 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 hand-made webhook that has never delivered, 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, check it passes its health check, and switch on its write policy if the integration will push.
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. Press Run, 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. Read the connection’s change detection. It says Webhook + poll if the product could register a webhook, or Poll if its account cannot manage webhooks. There is nothing to switch. If you want the speed without admin rights, register a webhook by hand with the URL and secret the connection shows.

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.