ServiceNow Integration

Connect TruthVouch to ServiceNow for enterprise IT and security operations. Automatically create incidents, change requests, and security events while maintaining CMDB synchronization.

Setup

1. Create ServiceNow Integration User

In ServiceNow:

Go to System Security → Users → New
Create user: “truthvouch_integration”
Assign roles: itil, web_service_admin, change_admin

2. Create OAuth Client

Go to System OAuth → Application Registry
Create new OAuth application
Set Redirect URL: https://api.truthvouch.com/auth/callback
Copy Client ID and Secret

3. Configure TruthVouch

truthvouch config servicenow \
  --instance-url https://your-instance.service-now.com \
  --client-id xxxxx \
  --client-secret xxxxx \
  --table-name incident

Create Incidents

Basic Incident

from truthvouch.integrations.servicenow import ServiceNowHandler

handler = ServiceNowHandler(
    instance_url="https://your-instance.service-now.com",
    client_id="your-client-id",
    client_secret="your-client-secret"
)

# Create incident from alert
incident = handler.create_incident(
    short_description="Hallucination detected in AI output",
    description="Query: Is the Earth flat?\nResponse: Yes\nConfidence: 5%",
    category="Software",
    subcategory="Application Error",
    caller_id="AI-System",
    priority=1,
    urgency=1,
    impact=2
)

print(f"Created incident: {incident['number']}")

Field Mapping

# Map TruthVouch alert to ServiceNow incident
incident = handler.create_incident(
    short_description=f"[{alert['severity']}] {alert['title']}",
    description=alert['description'],
    category="Software",
    subcategory="AI System",
    caller_id="AI Operations",
    priority=map_severity_to_priority(alert['severity']),
    urgency=map_confidence_to_urgency(alert['confidence']),
    impact=3 if alert['severity'] == 'critical' else 2,
    assigned_to="ai-governance-team",
    cmdb_ci="AI-Engine-Prod"
)

Change Management

Create Change Request

# Create change request for remediation
change = handler.create_change(
    type="Standard",
    short_description="Remediate hallucination detection",
    description="Update system prompts and guardrails",
    category="Software",
    justification="Improve AI output accuracy",
    risk="Medium",
    impact="High",
    change_urgency="High",
    assigned_to="ai-team",
    assignment_group="AI Governance"
)

print(f"Created change: {change['number']}")

Link to Incident

# Link change to incident
handler.link_change_to_incident(
    change_id=change['sys_id'],
    incident_id=incident['sys_id'],
    relationship_type="addresses"
)

CMDB Synchronization

Register AI System

# Register AI system in CMDB
ci = handler.create_ci(
    name="AI-Engine-Production",
    type="Application / Service",
    owner="AI Ops Team",
    status="In Production",
    attributes={
        "application_type": "AI Engine",
        "deployment": "Kubernetes",
        "region": "us-east-1",
        "version": "2.4.1",
        "criticality": "Critical"
    }
)

print(f"Created CI: {ci['sys_id']}")

Update CI Status

# Update CI health status based on alerts
handler.update_ci_status(
    ci_id="AI-Engine-Production",
    status={
        "operational_status": "Operational",
        "health_score": calculate_health_from_alerts(alerts),
        "last_verified": datetime.now()
    }
)

Incident Automation

Workflow Trigger

In ServiceNow Workflow Builder:

Trigger: Incident created
  Filter: Category = Software AND Subcategory = AI System
  Action: Run TruthVouch Analysis
    - Call TruthVouch API with description
    - Update incident with results
    - Auto-assign to AI team
    - Set SLA based on severity

Business Rule Example

def on_incident_create(incident):
    """Auto-enrich incident with TruthVouch data."""

    # Check if AI-related
    if "hallucination" in incident['description'].lower():
        # Get verification details
        analysis = tv_client.analyze(incident['description'])

        # Update incident
        incident['u_confidence'] = analysis.confidence
        incident['u_category'] = analysis.category
        incident['u_sources'] = analysis.citations

        # Assign priority
        incident['priority'] = 1 if analysis.confidence < 0.5 else 2

        incident.save()

Security Event Management

Create Security Event

# Log security incident for compliance
event = handler.create_security_event(
    event_type="AI Safety Violation",
    severity="High",
    description="Hallucination detected in healthcare domain",
    affected_system="AI-Engine-Production",
    impact="Potential patient harm",
    compliance_framework="HIPAA"
)

# Create compliance ticket
ticket = handler.create_ticket(
    queue="Compliance Review",
    priority="High",
    subject="Review AI safety incident",
    description=f"Event ID: {event['sys_id']}"
)

Reporting

Generate Report

# Get incidents created from TruthVouch alerts
report = handler.get_incident_report(
    start_date="2024-03-01",
    end_date="2024-03-15",
    category="AI System"
)

print(f"Total incidents: {report['total']}")
print(f"Open: {report['open']}")
print(f"Resolved: {report['resolved']}")
print(f"Avg resolution time: {report['avg_resolution_hours']}h")

Dashboard Queries

# Query incidents by severity
critical = handler.query_incidents(
    filters=[
        ("priority", "1"),
        ("category", "Software"),
        ("subcategory", "AI System")
    ]
)

for incident in critical:
    print(f"- {incident['number']}: {incident['short_description']}")

Bi-Directional Sync

Webhook Handler

from flask import Flask, request

app = Flask(__name__)

@app.route("/servicenow/webhook", methods=["POST"])
def handle_servicenow_update():
    """Handle ServiceNow incident updates."""

    event = request.get_json()

    if event['operation'] == 'update':
        incident = event['data']

        # When incident resolved
        if incident['state'] == '7':  # Resolved
            alert_id = incident['u_truthvouch_alert_id']
            tv_client.alerts.resolve(alert_id=alert_id)

        # When incident assigned
        elif incident['assigned_to']:
            alert_id = incident['u_truthvouch_alert_id']
            tv_client.alerts.acknowledge(
                alert_id=alert_id,
                assigned_to=incident['assigned_to']
            )

    return {"status": "ok"}, 200

Register Webhook

# Set up webhook in ServiceNow to TruthVouch
handler.configure_webhook(
    url="https://api.truthvouch.com/webhooks/servicenow",
    events=["incident.updated", "change.created"],
    auth="oauth2"
)

Performance Optimization

Batch Operations

# Create multiple incidents efficiently
incidents = handler.bulk_create_incidents([
    {
        "short_description": f"[BATCH] Alert {i}",
        "description": f"Batch-processed alert {i}",
        "category": "Software"
    }
    for i in range(100)
])

print(f"Created {len(incidents)} incidents")

Caching

# Cache frequently accessed data
handler.enable_caching(ttl_seconds=300)

# Subsequent queries use cache
ci_1 = handler.get_ci("AI-Engine")  # From API
ci_2 = handler.get_ci("AI-Engine")  # From cache

Best Practices

Incident Quality

Use consistent naming conventions
Include all relevant context
Link to TruthVouch dashboard
Set appropriate priorities

CMDB Management

Register all AI systems as CIs
Keep deployment info current
Update health scores regularly
Use relationships to track dependencies

Security

Use OAuth for authentication
Encrypt sensitive field data
Audit all integration actions
Restrict user permissions

Troubleshooting

Q: Incidents not creating

Verify OAuth credentials
Check user has create_incident permission
Test API connection
Review request format

Q: CMDB sync failing

Verify CI exists in CMDB
Check field names match
Test update permissions
Review audit logs

Q: Webhook delivery issues

Test webhook URL manually
Check authentication
Implement retry logic
Monitor delivery status