Ticket external synchronization¶

Versio.io tickets can be mirrored into an external issue or service management system. A ticket that is synchronized keeps a counterpart in the external system: Versio.io creates it on the first synchronization and updates it on every following change.

Synchronization is one-way. Versio.io is the leading system. Changes made in the external system are never read back and are overwritten with the next update.

How synchronization works¶

Every change to a ticket — a field edit, a comment, a task, a state transition — writes an activity entry and raises a ticket sync event. The ticketing service picks the event up and processes each external system the ticket's type is bound to.

sequenceDiagram
    participant U as User
    participant T as Versio.io ticketing
    participant S as ticketSync state
    participant E as External system

    U->>T: Change ticket
    T->>T: Read ticket, tasks, comments, reporter
    T->>S: Read sync state for external system
    alt No counterpart yet
        T->>E: Create ticket (title)
        E-->>T: External id and link
    end
    T->>E: Update ticket (fields and description)
    T->>S: Store last sync date, external reference, error

Figure: Synchronization of a ticket into an external system

For every ticket and every bound external system, Versio.io stores one synchronization state: the last synchronization date, the last successful synchronization date, the error text of the last failure, and the reference of the external ticket. This state feeds the External sync tile on the ticket details page.

A failed synchronization does not block the ticket. The error is stored and shown on the ticket, and the next ticket change triggers a new attempt.

Configuration¶

Synchronization is configured in two places. An external system describes how to reach the other side. A binding on a ticket type decides which types are pushed into that system.

External systems¶

Environment settings → Ticketing → External systems. Each entry describes one connection.

Table: Configuration of an external system

Base URL and project differ per type:

Table: Meaning of base URL and project per external system type

Credential¶

The credential MUST be created in the credential vault under Environment settings → Access management → Credential vault before it can be selected.

Every shipped adapter reads its token from the password field of the credential. The user name is not used. GitLab and Jira send the token as a bearer token, Versio.io as an apiToken authorization.

Table: Credential per external system type

Binding a ticket type¶

Environment settings → Ticketing → ticket type → External sync. Add one of the configured external systems to bind the type to it.

Table: Options of a ticket type binding

A ticket is only synchronized when the external system and the binding are enabled. If either side is switched off, the system stays listed on the ticket with the status Disabled, so it remains visible that a target is configured but not synchronizing.

Note: Manual synchronization is not available yet. Tickets of an enabled binding are currently always synchronized on change, and the sync button on the ticket is inactive. See Current limitations.

Supported external systems¶

The type of an external system selects the adapter. Only the types below with the status available ship an adapter. The remaining types can already be selected in the configuration, but a ticket bound to them fails with No adapter found for external system type.

Table: External system types and their support status

Field support matrix¶

Not every Versio.io ticket field has a counterpart in every external system. A field that has no native counterpart is written into the description of the external ticket instead, so no information is lost.

Table: Legend of the field support matrix

Table: Support of Versio.io ticket fields per external system

Description content¶

The description of the external ticket is generated on every synchronization and overwrites what is there. It is assembled in this order:

1. A header table with state, severity, assignee, due date, creation date and creator. Fields that the system stores natively are left out — GitLab therefore has no due date column.
2. The Markdown description of the Versio.io ticket.
3. A Reporter section, if any reporter field is filled.
4. A Tasks section as a nested checklist, if the ticket has tasks.
5. A Comments section with author, date and the quoted comment text.

Note: The header renders the workflow state as its configured state id (e.g. v1000), not as its display name.

Synchronization status on the ticket¶

The External sync tile on the ticket details page lists every external system the ticket's type is bound to, with the reference of the external ticket and the status reached for this ticket.

Table: Synchronization status of a ticket

Current limitations¶

• Synchronization is one-way. Changes in the external system are overwritten, and deleting a Versio.io ticket does not delete its counterpart.
• Manual synchronization is not implemented. The sync button on the ticket is inactive, and an enabled binding always synchronizes on change regardless of the Automatic sync option.
• Versio.io: the counterpart is always created as the delivered Incident type in its New state, so a target environment without them rejects the creation. Due date, severity, assignee and workflow state are only written into the description, not into the fields the target ticket has for them.
• Jira: the issue type is fixed to Incident, the description is transferred as plain text so its Markdown is not rendered, the work estimate is not transferred, and comments and state transitions are not written as native Jira comments or transitions.