ITSM Sync Configuration Reference
Complete configuration reference for the bi-directional ITSM synchronization feature.
CLI Commands#
Integration Management#
im integration configure [flags]
| Flag |
Type |
Description |
--name |
string |
Integration name (required) |
--type |
string |
Integration type: servicenow, jira, pagerduty |
--org |
string |
Organization ID |
--base-url |
string |
External system API URL |
--direction |
string |
Sync direction: none, inbound, outbound, bidirectional |
--enabled |
bool |
Enable/disable integration |
--username |
string |
Username (ServiceNow) |
--password |
string |
Password (ServiceNow) |
--email |
string |
Email (Jira) |
--api-key |
string |
API key (Jira) |
--token |
string |
Bearer token (PagerDuty) |
--webhook-secret |
string |
Webhook signature secret |
--conflict-strategy |
string |
Conflict resolution: last-write-wins, ownership-priority, manual-review |
List Integrations#
im integration list [flags]
| Flag |
Type |
Description |
--org |
string |
Filter by organization |
--type |
string |
Filter by integration type |
--format |
string |
Output format: table, json |
Get Integration#
im integration get <name|id> [flags]
Delete Integration#
im integration delete <name|id>
Test Integration#
im integration test <name|id>
Sync Status#
im integration sync-status <name|id> [flags]
| Flag |
Type |
Description |
--format |
string |
Output format: table, json |
Field Ownership#
List Ownership Rules#
im integration field-ownership list <integration> [flags]
Set Ownership Rule#
im integration field-ownership set <integration> <field> [flags]
| Flag |
Type |
Description |
--owner |
string |
Owner: platform, external |
--priority |
int |
Priority (higher wins in conflicts) |
Delete Ownership Rule#
im integration field-ownership delete <integration> <field>
Conflict Management#
List Conflicts#
| Flag |
Type |
Description |
--integration |
string |
Filter by integration |
--status |
string |
Filter: pending, resolved, ignored |
--incident |
string |
Filter by incident ID |
--format |
string |
Output format: table, json |
Show Conflict#
im conflict show <conflict-id> [flags]
Resolve Conflict#
im conflict resolve <conflict-id> [flags]
| Flag |
Type |
Description |
--use-platform |
bool |
Use platform value |
--use-external |
bool |
Use external value |
--ignore |
bool |
Ignore the conflict |
Reconciliation#
Start Reconciliation#
im integration reconcile <integration> [flags]
| Flag |
Type |
Description |
--dry-run |
bool |
Check without making changes |
--auto-heal |
bool |
Automatically fix drift |
--format |
string |
Output format: table, json |
View History#
im integration reconcile history <integration> [flags]
Dead Letter Queue#
List DLQ Entries#
im integration dlq <integration> [flags]
Retry Entry#
im integration dlq-retry <integration> <entry-id>
Discard Entry#
im integration dlq-discard <integration> <entry-id>
Incident Links#
List Links#
im incident links <incident-id> [flags]
Create Link#
im incident link <incident-id> --integration <id> --external-id <id>
Delete Link#
im incident unlink <incident-id> --integration <id>
API Endpoints#
Integration Configuration#
| Method |
Endpoint |
Description |
POST |
/api/v1/integrations |
Create integration |
GET |
/api/v1/integrations |
List integrations |
GET |
/api/v1/integrations/{id} |
Get integration |
PATCH |
/api/v1/integrations/{id} |
Update integration |
DELETE |
/api/v1/integrations/{id} |
Delete integration |
POST |
/api/v1/integrations/{id}/test |
Test integration |
Sync Status#
| Method |
Endpoint |
Description |
GET |
/api/v1/integrations/{id}/sync-status |
Get sync status |
GET |
/api/v1/integrations/{id}/links |
List linked incidents |
Field Ownership#
| Method |
Endpoint |
Description |
GET |
/api/v1/integrations/{id}/ownership |
List ownership rules |
PUT |
/api/v1/integrations/{id}/ownership |
Replace all rules |
PATCH |
/api/v1/integrations/{id}/ownership/{field} |
Update field ownership |
DELETE |
/api/v1/integrations/{id}/ownership/{field} |
Delete rule |
Webhooks#
| Method |
Endpoint |
Description |
POST |
/api/v1/webhooks/{integration_id} |
Receive webhook |
Conflicts#
| Method |
Endpoint |
Description |
GET |
/api/v1/conflicts |
List conflicts |
GET |
/api/v1/conflicts/{id} |
Get conflict |
POST |
/api/v1/conflicts/{id}/resolve |
Resolve conflict |
POST |
/api/v1/conflicts/{id}/ignore |
Ignore conflict |
Reconciliation#
| Method |
Endpoint |
Description |
POST |
/api/v1/integrations/{id}/reconcile |
Start reconciliation |
GET |
/api/v1/integrations/{id}/reconcile/history |
Get history |
POST |
/api/v1/integrations/{id}/reconcile/schedule |
Configure schedule |
DELETE |
/api/v1/integrations/{id}/reconcile/schedule |
Remove schedule |
Dead Letter Queue#
| Method |
Endpoint |
Description |
GET |
/api/v1/integrations/{id}/dead-letter-queue |
List DLQ entries |
POST |
/api/v1/integrations/{id}/dead-letter-queue/{entry}/retry |
Retry entry |
DELETE |
/api/v1/integrations/{id}/dead-letter-queue/{entry} |
Discard entry |
Environment Variables#
| Variable |
Description |
Default |
INCIDENTS_SYNC_ENABLED |
Enable sync feature |
true |
INCIDENTS_SYNC_CONFLICT_WINDOW |
Conflict detection window |
5s |
INCIDENTS_SYNC_MAX_RETRIES |
Max retry attempts before DLQ |
5 |
INCIDENTS_SYNC_RATE_LIMIT |
Default rate limit per integration |
100 |
INCIDENTS_SYNC_BACKOFF_MULTIPLIER |
Exponential backoff multiplier |
2 |
INCIDENTS_SYNC_TRACE |
Enable detailed tracing |
false |
Database Tables#
integration_configurations#
Stores integration settings.
| Column |
Type |
Description |
id |
TEXT |
Primary key (UUID) |
organization_id |
TEXT |
Organization reference |
integration_type |
TEXT |
servicenow, jira, pagerduty |
name |
TEXT |
Display name |
base_url |
TEXT |
API endpoint URL |
credentials_encrypted |
BLOB |
Encrypted credentials |
sync_direction |
TEXT |
Sync mode |
enabled |
BOOLEAN |
Active flag |
webhook_secret_encrypted |
BLOB |
Encrypted webhook secret |
field_ownership#
Stores field ownership rules.
| Column |
Type |
Description |
id |
TEXT |
Primary key (UUID) |
integration_id |
TEXT |
Foreign key |
field_name |
TEXT |
Incident field name |
owner |
TEXT |
platform or external |
priority |
INTEGER |
Conflict priority |
incident_external_links#
Tracks linked incidents.
| Column |
Type |
Description |
id |
TEXT |
Primary key (UUID) |
incident_id |
TEXT |
Platform incident ID |
integration_id |
TEXT |
Foreign key |
external_id |
TEXT |
External system ID |
external_url |
TEXT |
Link to external system |
sync_status |
TEXT |
Current sync state |
retry_count |
INTEGER |
Failed attempt count |
conflict_records#
Stores detected conflicts.
| Column |
Type |
Description |
id |
TEXT |
Primary key (UUID) |
incident_id |
TEXT |
Platform incident ID |
integration_id |
TEXT |
Foreign key |
field_name |
TEXT |
Conflicting field |
platform_value |
TEXT |
Platform’s value |
external_value |
TEXT |
External system’s value |
status |
TEXT |
pending, resolved, ignored |
resolution |
TEXT |
Resolution action taken |
drift_detection_results#
Stores reconciliation job results.
| Column |
Type |
Description |
id |
TEXT |
Primary key (UUID) |
integration_id |
TEXT |
Foreign key |
started_at |
TIMESTAMP |
Job start time |
completed_at |
TIMESTAMP |
Job end time |
status |
TEXT |
Job status |
total_checked |
INTEGER |
Items examined |
discrepancies_found |
INTEGER |
Drift detected |
auto_healed |
INTEGER |
Items fixed |
OpenTelemetry Attributes#
Span Names#
| Span |
Description |
ProcessTimelineEvent |
Outbound sync processing |
ProcessWebhook |
Inbound webhook processing |
DetectConflict |
Conflict detection |
ResolveConflict |
Conflict resolution |
ReconciliationJob |
Drift detection job |
Common Attributes#
| Attribute |
Type |
Description |
sync.integration_id |
string |
Integration identifier |
sync.integration_type |
string |
Platform type |
sync.direction |
string |
outbound or inbound |
sync.incident_id |
string |
Platform incident ID |
sync.external_id |
string |
External system ID |
sync.field_count |
int |
Fields being synced |
sync.result |
string |
success, skipped, error, retry |