Skip to main content

Connector Versioning

Connectors use semantic versioning to maintain forensic integrity. Collections reference specific connector versions, ensuring reproducibility.

Semantic Versioning​

Versions follow the format: MAJOR.MINOR.PATCH.

Automatic Versioning​

When you publish, Traces inspects your unpublished changes and bumps the version automatically — there is no manual version picker. The highest-priority change wins (major > minor > patch):

ChangeBumpExample
Endpoint changes (add/remove/enable/disable, path or method edits)Major1.0.0 → 2.0.0
Dependency mapping or execution-order changesMinor1.0.0 → 1.1.0
Pagination, header, or notes changesPatch1.0.0 → 1.0.1

New connectors start at 1.0.0 when first created from a draft.

Creating New Versions​

Editing Published Connectors​

When you edit a published connector:

  1. Changes are tracked as "unpublished"
  2. The indicator shows "Unpublished changes"
  3. Active collections continue using the published version
  4. You can discard changes to revert

Publishing Changes​

  1. Click Publish in the editor toolbar
  2. Review the diff dialog showing exactly what will change, and optionally add a commit message
  3. Confirm publication

You don't pick the version type — Traces derives the version bump automatically from the changes you made (see Automatic Versioning below).

note

You can't publish while there are active collections using the connector — wait for them to finish.

What Happens on Publish​

Publishing creates a new connector record with a new UUID. The previous version is soft-deleted. This design ensures forensic integrity — each published version is an immutable snapshot.

Automatic migration on publish:

  • Test data (tested endpoints, endpoint results, dependency mappings, variables, pagination configs) are migrated to the new connector ID
  • Explorer state (acknowledged notes, tested indicators) is migrated
  • Endpoint IDs may change between versions. Dependency mappings and variable references are automatically remapped by matching endpoints on method + path

This means your test configuration carries forward seamlessly — you don't need to re-test everything after publishing.

Version History​

Click Version History in the editor toolbar to open the dedicated history page (/analyst/connectors/[id]/history). It's a git-style, two-panel diff viewer:

  • The left panel lists all versions of the connector — version number, creator, timestamp, status, and a Current badge on the active version.
  • The right panel shows a diff between the current configuration and the version you select, keyed by method + path.

Each diff item is labelled Added, Removed, Modified, or Unchanged, with a toggle to show or hide unchanged items. You can apply an individual change from an older version back onto the current one, or restore a whole version (see below).

Restoring a Version​

To bring back a previous version:

  1. Open Version History
  2. Select the version you want in the left panel
  3. Click Restore
  4. Confirm

Restoring creates a new version based on the selected one (rather than mutating history) and makes it the active version. As with publishing, this is blocked while active collections are using the connector.

Forensic Integrity​

Versioning maintains forensic integrity:

  • Immutable versions - Once published, versions cannot be modified
  • New record per version - Each publish creates a new connector with its own UUID
  • Collection references - Collections always reference specific version IDs
  • Reproducibility - Historical collections can be re-run with exact same configuration
  • Audit trail - Version history provides complete record

Why This Matters​

In forensic contexts:

  • Evidence collection must be reproducible
  • Configuration changes are documented
  • Historical collections use historical configs
  • No retroactive changes to collection logic

Best Practices​

Version Planning​

  1. Batch related changes - Group related fixes into single version
  2. Document changes - Use clear version notes
  3. Coordinate major versions - Warn users before breaking changes
  4. Test before publish - Always test new versions

Version Management​

  1. Don't over-version - Not every tiny change needs a version
  2. Keep old versions - Don't delete, they may be needed
  3. Monitor usage - Know which versions are in use
  4. Deprecate gracefully - Mark old versions deprecated before removal

Communication​

When making significant changes:

  1. Document in version notes
  2. Notify affected users if major change
  3. Provide migration guidance if needed
  4. Monitor for issues after release

Rollback Process​

If a new version has issues:

  1. Identify the problem
  2. Activate previous version
  3. Fix issues in development
  4. Test thoroughly
  5. Publish fixed version
  6. Activate fixed version
note

You cannot modify published versions. You must create a new version with fixes.

Version Retention​

All versions are retained:

  • Active versions cannot be deleted
  • Inactive versions are kept for audit
  • Collections reference version IDs permanently
  • No automatic cleanup

Next Steps​