connectors Package

Overview#

Package connectors provides interfaces and implementations for external ITSM system integration.

The connectors package enables bidirectional synchronization between the incident management platform and external ITSM systems such as ServiceNow, Jira Service Management, and PagerDuty.

Key features:

• Standardized Connector interface for all external systems
• Field mapping and conflict resolution for data synchronization
• Webhook support for real-time event processing
• Comprehensive error handling and retry logic
• Production-ready implementations for major ITSM platforms

Architecture:

The connector system is built around a common interface that all external system integrations must implement. This ensures consistency and enables hot-swapping of different ITSM platforms without changing the core incident management logic.

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ Incident Mgmt   │◄──►│ Connector        │◄──►│ External ITSM   │
│ Platform        │    │ Interface        │    │ (ServiceNow,    │
│                 │    │                  │    │  Jira, etc.)    │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Each connector handles:

• Authentication and connection management
• CRUD operations for incidents
• Field mapping between different data schemas
• Webhook validation and event parsing
• Conflict resolution during bidirectional sync

Supported Operations:

All connectors support a standard set of operations:

• CREATE: Create incidents in external systems
• READ: Retrieve incident data from external systems
• UPDATE: Modify existing incidents in external systems
• SYNC: Bidirectional synchronization with conflict resolution
• WEBHOOKS: Real-time event processing from external systems

Example Usage:

// Create and configure a ServiceNow connector
connector := connectors.NewServiceNowConnector()
config := connectors.Config{
	BaseURL:  "https://dev12345.service-now.com",
	Username: "connector_user",
	Password: "secure_password",
	SyncDirection: connectors.SyncBidirectional,
}

// Connect to external system
err := connector.Connect(ctx, config)
if err != nil {
	log.Fatal(err)
}

// Create incident in external system
incident := &models.Incident{
	Title:    "Database connectivity issues",
	Severity: models.SeveritySEV2,
	Status:   models.StatusOpen,
}

external, err := connector.CreateIncident(ctx, incident)
if err != nil {
	log.Printf("Failed to create incident: %v", err)
	return
}

log.Printf("Created incident %s in external system", external.ID)

Field Mapping:

Different ITSM systems use different field names and values. The connector system provides flexible field mapping to handle these differences:

mappings := &connectors.FieldMappings{
	StatusMappings: map[string]string{
		"open":      "New",
		"mitigated": "Work in Progress",
		"resolved":  "Resolved",
		"closed":    "Closed",
	},
	SeverityMappings: map[string]string{
		"SEV-1": "1 - Critical",
		"SEV-2": "2 - High",
		"SEV-3": "3 - Medium",
		"SEV-4": "4 - Low",
	},
}
connector.SetFieldMappings(mappings)

Conflict Resolution:

When synchronizing data between systems, conflicts can occur when the same field is modified in both systems. The connector system provides several conflict resolution strategies:

• LOCAL: Always use the incident management platform value
• EXTERNAL: Always use the external system value
• MANUAL: Flag for manual resolution by operators
• MERGE: Attempt to automatically merge values when possible

Error Handling:

All connector operations return structured errors that can be handled programmatically:

if err != nil {
	if connectorErr, ok := err.(*connectors.ConnectorError); ok {
		switch connectorErr.Code {
		case "AUTH_FAILED":
			// Handle authentication failure
		case "INCIDENT_NOT_FOUND":
			// Handle missing incident
		default:
			// Handle other errors
		}
	}
}

Import Path: github.com/systmms/incidents/internal/connectors

Variables#

ErrConnectorNotFound (and others)#

Common errors returned by connector operations.

These predefined errors provide consistent error codes and messages across all connector implementations. This enables standardized error handling and monitoring in the incident management platform.

var ErrConnectorNotFound ErrConnectionFailed ErrAuthenticationFailed ErrOperationNotSupported ErrIncidentNotFound ErrFieldMappingFailed ErrSyncConflict

Types#

Config#

Config holds connector-specific configuration for connecting to external ITSM systems.

The configuration supports multiple authentication methods and flexible synchronization options to accommodate different external system requirements and organizational policies.

Authentication methods (use only one):

• Username/Password: Basic authentication for legacy systems
• APIKey: API key authentication for modern REST APIs
• Token: Bearer token authentication for OAuth/JWT systems

Example configuration for ServiceNow:

config := Config{
	BaseURL:       "https://dev12345.service-now.com",
	Username:      "connector_user",
	Password:      "secure_password",
	SyncDirection: SyncBidirectional,
	SyncInterval:  5 * time.Minute,
	EnableWebhook: true,
	Custom: map[string]string{
		"table": "incident",
		"caller_id": "admin",
	},
}

{<nil> 10994 type 0 [0x140002b4e40] 0}

Connector#

Connector defines the interface that all ITSM connectors must implement.

This interface provides a standardized way to integrate with external ITSM systems such as ServiceNow, Jira Service Management, and PagerDuty. Each connector handles the specifics of authentication, API calls, and data mapping for its target system.

The interface is designed to support:

• Bidirectional data synchronization with conflict resolution
• Real-time event processing through webhooks
• Flexible field mapping between different data schemas
• Connection health monitoring and automatic retry logic
• Production-ready error handling and observability

{<nil> 5317 type 0 [0x14000291580] 0}

Methods#

NewJiraConnector#

NewJiraConnector creates a new Jira Service Management connector

{<nil> <nil> NewJiraConnector 0x140002c51a0 <nil>}

NewPagerDutyConnector#

NewPagerDutyConnector creates a new PagerDuty connector

{<nil> <nil> NewPagerDutyConnector 0x140003ce480 <nil>}

NewServiceNowConnector#

NewServiceNowConnector creates a new ServiceNow connector

{<nil> <nil> NewServiceNowConnector 0x1400040f200 <nil>}

ConnectorError#

ConnectorError represents structured errors from connector operations.

Connector errors include both human-readable messages and machine-readable error codes to enable proper error handling, monitoring, and debugging. The structured format allows calling code to handle specific error conditions appropriately.

{<nil> 29141 type 0 [0x140002bdb00] 0}

ConnectorFactory#

ConnectorFactory is a function that creates new instances of a specific connector type.

Factories enable lazy initialization and ensure that each connector instance is independent, allowing multiple instances of the same connector type with different configurations.

{<nil> 25745 type 0 [0x140002bd040] 0}

ConnectorInstance#

ConnectorInstance wraps a connector with its configuration and state

{<nil> 49016 type 0 [0x14000389a40] 0}

ExternalIncident#

ExternalIncident represents an incident as it exists in the external ITSM system.

This structure provides a normalized view of incident data from different external systems, allowing the incident management platform to work with incidents regardless of their source. Field values use the external system’s native format and are mapped to internal formats through the connector’s field mapping configuration.

The structure supports both common fields found in most ITSM systems and custom fields specific to particular implementations or organizational needs.

{<nil> 13962 type 0 [0x140002b5440] 0}

FieldConflict#

FieldConflict represents a data conflict detected during bidirectional synchronization.

Conflicts occur when the same field has been modified in both the incident management platform and the external ITSM system since the last successful sync. Each conflict contains the conflicting values and indicates how it should be resolved.

{<nil> 18930 type 0 [0x140002bc080] 0}

FieldMappings#

FieldMappings defines how data fields are translated between the incident management platform and external ITSM systems.

Different ITSM systems use different field names, value formats, and data schemas. Field mappings provide a flexible way to configure how data is translated during synchronization operations. This allows the same connector code to work with different external system configurations.

Example field mapping configuration for ServiceNow:

mappings := &FieldMappings{
	StatusMappings: map[string]string{
		"open":      "New",
		"mitigated": "Work in Progress",
		"resolved":  "Resolved",
		"closed":    "Closed",
	},
	SeverityMappings: map[string]string{
		"SEV-1": "1 - Critical",
		"SEV-2": "2 - High",
		"SEV-3": "3 - Medium",
		"SEV-4": "4 - Low",
	},
	CustomMappings: map[string]string{
		"service": "business_service",
		"owner":   "assigned_to",
	},
	Defaults: map[string]interface{}{
		"caller_id": "admin",
		"category":  "Software",
	},
}

{<nil> 23148 type 0 [0x140002bc980] 0}

Methods#

getDefaultJiraMappings#

{<nil> <nil> getDefaultJiraMappings 0x140003a2aa0 <nil>}

getDefaultPagerDutyMappings#

{<nil> <nil> getDefaultPagerDutyMappings 0x1400040ec00 <nil>}

getDefaultServiceNowMappings#

{<nil> <nil> getDefaultServiceNowMappings 0x14000455ee0 <nil>}

IncidentUpdate#

IncidentUpdate represents fields to update in an external ITSM system.

This structure uses pointer fields to distinguish between fields that should be updated (non-nil pointers) and fields that should be left unchanged (nil pointers). This allows for partial updates where only specific fields are modified.

Field values should use the external system’s native format and will be processed through the connector’s field mapping configuration before being sent to the external API.

Example usage:

update := IncidentUpdate{
	Status:   &newStatus,    // Will update status field
	Priority: &newPriority,  // Will update priority field
	// Title is nil, so title field will not be changed
}

{<nil> 16420 type 0 [0x140002b5980] 0}

JiraChangeItem#

{<nil> 40342 type 0 [0x1400033ce80] 0}

JiraChangelog#

{<nil> 40236 type 0 [0x1400033cd80] 0}

JiraComponent#

{<nil> 38782 type 0 [0x1400033c280] 0}

JiraConnector#

JiraConnector implements the Connector interface for Jira Service Management

{<nil> 30034 type 0 [0x140002c6000] 0}

JiraContent#

{<nil> 38031 type 0 [0x140002fda80] 0}

JiraCreateFields#

{<nil> 38941 type 0 [0x1400033c440] 0}

JiraCreateRequest#

{<nil> 38865 type 0 [0x1400033c380] 0}

JiraCreateResponse#

{<nil> 39703 type 0 [0x1400033c940] 0}

JiraDescription#

{<nil> 37881 type 0 [0x140002fd940] 0}

JiraErrorResponse#

{<nil> 39817 type 0 [0x1400033ca80] 0}

JiraFields#

{<nil> 37159 type 0 [0x140002fd440] 0}

JiraIssue#

Jira-specific data structures

{<nil> 37001 type 0 [0x140002fd280] 0}

JiraIssueType#

{<nil> 38356 type 0 [0x140002fddc0] 0}

JiraPriority#

{<nil> 38274 type 0 [0x140002fdcc0] 0}

JiraProject#

{<nil> 38439 type 0 [0x140002fdec0] 0}

JiraResolution#

{<nil> 38698 type 0 [0x1400033c180] 0}

JiraStatus#

{<nil> 38194 type 0 [0x140002fdbc0] 0}

JiraUpdateFields#

{<nil> 39379 type 0 [0x1400033c740] 0}

JiraUpdateRequest#

{<nil> 39293 type 0 [0x1400033c680] 0}

JiraUser#

{<nil> 38517 type 0 [0x1400033c040] 0}

JiraWebhook#

{<nil> 39948 type 0 [0x1400033cb80] 0}

Manager#

Manager orchestrates all connector operations

{<nil> 48796 type 0 [0x140003898c0] 0}

Methods#

NewManager#

NewManager creates a new connector manager

{<nil> <nil> NewManager 0x140003a3ca0 <nil>}

Operation#

Operation represents supported ITSM operations that connectors can implement.

Not all connectors support all operations. Use the SupportedOperations() method to check which operations a specific connector implements before calling them.

{<nil> 9191 type 0 [0x140002b4cc0] 0}

Constants#

const OpCreateIncident const OpUpdateIncident const OpGetIncident const OpSyncIncident const OpWebhooks const OpFieldMapping

PDAgent#

{<nil> 68794 type 0 [0x140003fa240] 0}

PDAssignee#

{<nil> 67963 type 0 [0x140003efa40] 0}

PDAssignment#

{<nil> 67863 type 0 [0x140003ef840] 0}

PDBody#

{<nil> 66942 type 0 [0x140003ef000] 0}

PDCreateIncident#

{<nil> 66248 type 0 [0x140003ee840] 0}

PDError#

{<nil> 68145 type 0 [0x140003efc40] 0}

PDErrorResponse#

{<nil> 68082 type 0 [0x140003efb80] 0}

PDEscalationPolicy#

{<nil> 67766 type 0 [0x140003ef740] 0}

PDIncident#

{<nil> 67104 type 0 [0x140003ef1c0] 0}

PDIncidentRequest#

PagerDuty-specific data structures

{<nil> 66168 type 0 [0x140003ee780] 0}

PDIncidentResponse#

{<nil> 67029 type 0 [0x140003ef100] 0}

PDIncidentUpdate#

{<nil> 66596 type 0 [0x140003eeb80] 0}

PDLogEntry#

{<nil> 68600 type 0 [0x140003fa0c0] 0}

PDReference#

{<nil> 66861 type 0 [0x140003eef00] 0}

PDService#

{<nil> 67678 type 0 [0x140003ef500] 0}

PDUpdateFields#

{<nil> 66673 type 0 [0x140003eec40] 0}

PDWebhook#

{<nil> 68271 type 0 [0x140003efd80] 0}

PDWebhookMessage#

{<nil> 68345 type 0 [0x140003efe40] 0}

PagerDutyConnector#

PagerDutyConnector implements the Connector interface for PagerDuty

{<nil> 59248 type 0 [0x140003b3d80] 0}

Registry#

Registry manages all registered connector factories and provides a central point for discovering and creating connector instances.

The registry enables dynamic connector loading and supports hot-swapping of different ITSM integrations without changing the core incident management code. This is essential for supporting multiple external systems and allowing runtime configuration changes.

Example usage:

registry := connectors.NewRegistry()
registry.Register("servicenow", NewServiceNowConnector)
registry.Register("jira", NewJiraConnector)
registry.Register("pagerduty", NewPagerDutyConnector)

// Create a connector instance
connector, err := registry.Create("servicenow")
if err != nil {
	log.Fatal(err)
}

{<nil> 25400 type 0 [0x140002bce00] 0}

Methods#

NewRegistry#

NewRegistry creates a new empty connector registry.

The registry must be populated with connector factories using Register() before it can create connector instances.

{<nil> <nil> NewRegistry 0x140002bf2c0 <nil>}

Resolution#

Resolution defines the strategy for resolving field conflicts during synchronization.

Different resolution strategies can be applied to different fields based on organizational policies and the specific context of the conflict. The resolution strategy determines which value is kept and how the conflict is handled.

{<nil> 19755 type 0 [0x140002bc340] 0}

Constants#

const ResolutionLocal const ResolutionExternal const ResolutionManual const ResolutionMerge

ServiceNowConnector#

ServiceNowConnector implements the Connector interface for ServiceNow

{<nil> 76219 type 0 [0x14000418640] 0}

ServiceNowIncident#

ServiceNow-specific data structures

{<nil> 82614 type 0 [0x1400043d540] 0}

ServiceNowWebhook#

{<nil> 83400 type 0 [0x1400043dac0] 0}

ServiceNowWebhookRecord#

{<nil> 83646 type 0 [0x1400043dd40] 0}

Status#

Status represents the current status of a connector

{<nil> 49390 type 0 [0x14000389ec0] 0}

Constants#

const StatusDisconnected const StatusConnecting const StatusConnected const StatusError const StatusSyncing

SyncDirection#

SyncDirection defines how data flows between the incident management platform and external systems.

The sync direction determines which system is authoritative for different types of changes and controls conflict resolution behavior during bidirectional synchronization.

{<nil> 12501 type 0 [0x140002b5300] 0}

Constants#

const SyncNone const SyncInbound const SyncOutbound const SyncBidirectional

SyncResult#

SyncResult contains the result of a bidirectional synchronization operation.

This structure provides detailed information about what happened during a sync operation, including success status, any conflicts detected, and which fields were updated. This information is crucial for audit trails, conflict resolution, and monitoring the health of synchronization processes.

{<nil> 17704 type 0 [0x140002b5c40] 0}

WebhookEvent#

WebhookEvent represents a parsed and normalized webhook event from an external ITSM system.

Webhook events provide real-time notifications when incidents are created, updated, or resolved in external systems. This structure normalizes the event data from different external systems into a common format that can be processed consistently.

The event can then trigger appropriate actions in the incident management platform, such as updating local incident state, sending notifications, or triggering workflows.

{<nil> 21043 type 0 [0x140002bc480] 0}

Functions#

mapWebhookEventType#

mapWebhookEventType maps external event types to our event types

{<nil> <nil> mapWebhookEventType 0x140003bbc40 <nil>}

Generated automatically from Go source code. Last updated: 2025-08-25T07:51:05-04:00