defect row to the record the maintainer creates. One maintainer
system is configured per project.
Delivery model
1
Submit writes locally
Submitting creates the
defect row and an outbox row in the same database
transaction. The reporter never waits for the maintainer’s system, and a report is
never lost because that system was unavailable. The report is read-only from then on.2
The job delivers
The
drain-outbox job runs every five minutes. It picks up due outbox rows and hands
each one to the project’s adapter, the connector that knows the maintainer
system’s API.3
The identifier is linked
When the maintainer’s system accepts the report and returns its own identifier, the
defect row’s external_system_id is changed from APP-… to that identifier, and the
report becomes SYNCED.4
The import takes over
The maintainer’s daily defect file includes the new record. The
import matches it by
external_system_id and updates the existing row instead of
creating a second one. From then on the defect is maintained by the import like any
other.Adapters
An adapter translates the platform’s neutral defect record into one call to the maintainer’s system, and reports back success with an identifier, or failure with a reason and whether retrying can help.log is the only adapter available today. It is also the adapter used whenever a project
has no enabled integration, so reporting works before an integration exists. Adapters for
specific maintainer systems are added per customer.
Disabling the integration pauses delivery: rows for that adapter stay pending, Retry answers
INTEGRATION_DISABLED, and delivery resumes on the next run after the integration is
enabled again. Only reports submitted while no integration is enabled go to log.
What is sent
Every adapter receives the same record, so the content of a delivery does not depend on the target system.
When the report has a slot but no serial, the component mounted in that slot at the moment
of submission is used.
Delivery states
Retry rules
A Project Admin can retry a pending or failed delivery from
Reported Defects. Retry resets the attempt count and delivers once,
immediately. It is refused once the maintainer has returned an identifier, because sending
again would create a duplicate there.
Every attempt carries a correlation id, the same across all attempts for one report, so
an attempt can be traced in both systems’ logs.
Credentials
Credentials are never stored in the database or shown in the application. The settings page lists only the names of the secrets an adapter needs. In the shared environments they live in Azure Key Vault, one secret per project, adapter and credential, namedproject-<project id>-<adapter>-<name> in lower case with
hyphens for underscores. The backend reads
them with its managed identity and caches each value for five minutes, so a rotated secret
takes effect within that time. Local development reads them from environment variables
instead.
The non-secret settings of an adapter, such as an endpoint address, are saved on the
project’s integration and validated against the adapter’s own schema.
What the customer provides
1
The system
Which maintenance system the maintainer uses, and the API through which it accepts new
defects or notifications.
2
The endpoint
The address of that API for each environment, and network access from the platform to
it.
3
Credentials
An account or client for the platform, with permission to create records and nothing
more. The values are placed in Key Vault by the operator.
4
Aligned code lists
Severity, category, consequence, fault indication and location values taken from the
maintainer system’s own catalogs. The platform sends the code; see
Code lists.
5
The identifier in the daily file
The maintainer’s daily defect file must carry the identifier their system returned, so
the import can take over the row.
Scheduled jobs
Tables
Field reference
integrations_maintainer_integration and integrations_outbound_sync.