# Integration Pattern: Service Provider eBond — Custom Validated Inbound API with Bidirectional State Sync ## Pattern Name **Service Provider eBond — Custom Validated Inbound API with Bidirectional State Sync** _Also known as: ITSM eBonding Integration, Managed Service Provider Ticket Sync_ --- ## Intent Establish a bidirectional, real-time ticket lifecycle synchronization between ServiceNow and an external service provider's ITSM platform — enforcing inbound data validation through a custom Scripted REST API while exposing read access via the native Table API and pushing outbound state changes via triggered scripted calls — maintaining ticket state consistency across organizational boundaries without granting the provider direct table-level write access. --- ## Motivation Enterprise IT organizations frequently delegate operational work to managed service providers who operate their own ITSM platforms. Tickets created in ServiceNow must be visible and actionable in the provider's system, and updates made by the provider must flow back into ServiceNow — without either party manually duplicating work across systems. A direct Table API write integration is too permissive: it allows providers to write arbitrary field values, bypass business rules, and circumvent data quality controls. A custom Scripted REST API acts as a controlled gateway, enforcing the data contract and validation rules that protect ServiceNow's ITSM data integrity. --- ## Applicability Use this pattern when: - A managed service provider or external partner operates their own ITSM platform and requires bidirectional ticket synchronization - Inbound writes from external parties must be validated against business rules before touching production tables - The external party should not have unrestricted Table API write access to ServiceNow - Outbound notifications to the provider must be triggered by ticket lifecycle events (assignment, state change, resolution) - The integration must maintain a cross-reference between ServiceNow ticket numbers and provider ticket numbers --- ## Participants |Participant|Role|Technology (Example Implementation)| |---|---|---| |ServiceNow Instance|Primary ITSM platform; ticket of record for internal operations|ServiceNow| |Scripted REST API|Custom inbound write endpoint with validation and access control|ServiceNow Scripted REST API| |Table API|Native read endpoint for provider queries against ServiceNow records|ServiceNow Table API| |Business Rules / Script Includes|Trigger outbound calls to provider on ticket lifecycle events|ServiceNow Business Rules (async)| |Service Provider Platform|External ITSM system operated by the managed service provider|Provider ITSM (e.g., Remedy, ServiceNow, Cherwell, custom)| |Cross-Reference Store|Maps ServiceNow ticket sys_id / number to provider ticket ID|Custom field on incident/change table or dedicated mapping table| --- ## Structure ``` Service Provider Platform │ ▲ │ Inbound writes │ Outbound reads │ (POST/PATCH) │ (GET — Table API) ▼ │ ┌─────────────────────────────────────────────────┐ │ ServiceNow Instance │ │ │ │ ┌─────────────────────────────────┐ │ │ │ Scripted REST API │ │ │ │ (custom inbound endpoint) │ │ │ │ │ │ │ │ • Authentication check │ │ │ │ • Schema validation │ Table │ │ │ • Business rule enforcement │◄──API ─────┤ │ │ • Field value validation │ (reads) │ │ │ • Cross-ref resolution │ │ │ └──────────────┬──────────────────┘ │ │ │ Validated write │ │ ▼ │ │ Incident / Change / Problem Tables │ │ │ │ │ │ Lifecycle event │ │ ▼ │ │ Business Rule (async trigger) │ │ │ │ │ │ Outbound REST call │ └─────────────────┼───────────────────────────────┘ │ ▼ Service Provider Platform (state update / ticket sync) ``` --- ## Flow ### Inbound — Provider Writes to ServiceNow (Scripted REST API) 1. **Provider triggers inbound call** — Service provider's platform POSTs or PATCHes to the custom ServiceNow Scripted REST API endpoint when a ticket update occurs on their side (work notes added, state changed, resolved, etc.) 2. **Authentication** — Scripted REST API validates the caller's credentials (Basic auth or OAuth token scoped to the integration user); unauthorized requests rejected at the endpoint before any data access 3. **Schema validation** — Endpoint script validates required fields are present, data types are correct, and enumerated values (state, priority, category) conform to ServiceNow's accepted value set; malformed requests returned with descriptive error responses 4. **Business rule enforcement** — Custom validation logic enforces rules that the Table API would bypass — e.g., preventing state transitions that violate workflow (cannot resolve without resolution code), preventing writes to fields the provider is not authorized to update 5. **Cross-reference resolution** — Provider ticket ID mapped to ServiceNow sys_id via the cross-reference store; ensures the update targets the correct ServiceNow record 6. **Controlled write** — Validated payload written to the target table (incident, change, problem) via server-side script; only explicitly permitted fields updated 7. **Response** — Endpoint returns success with the ServiceNow ticket number and current state, or a structured error payload the provider's system can parse and handle ### Inbound — Provider Reads from ServiceNow (Table API) 8. **Provider queries ticket state** — Service provider's platform calls the ServiceNow Table API (GET) to retrieve current ticket state, work notes, or field values 9. **ACL enforcement** — ServiceNow's native ACL framework governs which fields and records the integration user's role can read; no custom logic required for read access 10. **Response** — Table API returns JSON record(s); provider platform parses and syncs state to their local ticket ### Outbound — ServiceNow Pushes to Provider 11. **Lifecycle event trigger** — An async Business Rule fires on the ServiceNow incident/change/problem table when a relevant state change occurs — e.g., ticket assigned to provider's assignment group, work note added by internal team, ticket recalled from provider, resolution applied 12. **Outbound REST call** — Business Rule script (or Script Include) constructs and dispatches a REST call to the service provider's API endpoint, passing the updated ticket state and relevant field values 13. **Cross-reference lookup** — Provider ticket ID retrieved from the cross-reference store and included in the outbound payload so the provider's system can identify the corresponding ticket 14. **Error handling** — Failed outbound calls logged to a dedicated integration error table; retry logic or alerting triggered for persistent failures --- ## Tradeoffs ### Advantages - **Controlled write surface** — Scripted REST API acts as a validation gateway; providers cannot write arbitrary values or trigger unintended state changes the way direct Table API write access would allow - **Separation of read and write paths** — Table API handles reads natively with ACL enforcement; custom development effort focused exclusively on the write validation layer where it adds value - **Explicit data contract** — The Scripted REST API endpoint defines and enforces the integration contract; schema, permitted fields, and valid values are codified in the endpoint script rather than implied - **Bidirectional symmetry** — Both parties can initiate updates; neither system is purely passive, reflecting real managed service relationships where work flows in both directions - **Cross-reference traceability** — Mapping table maintains a durable link between ServiceNow and provider ticket IDs, enabling reconciliation and audit ### Limitations - **Custom development per provider** — Each service provider has different API contracts, authentication mechanisms, and field mappings; there is no reusable configuration-driven onboarding path - **Validation logic maintenance** — Business rules encoded in the Scripted REST API must be maintained as ServiceNow workflows and valid value sets evolve; validation that becomes stale silently accepts bad data - **Outbound failure visibility** — Async Business Rule failures do not surface in a centralized monitoring UI without custom error logging and alerting infrastructure - **No native retry mechanism** — Failed outbound calls require custom retry logic; there is no built-in queue or at-least-once delivery guarantee on Business Rule-triggered REST calls - **State divergence risk** — If either side misses an update (network failure, downtime, unhandled error), ticket state between the two systems can diverge silently; reconciliation requires manual intervention or a periodic sync job - **Authentication management** — Integration user credentials and OAuth tokens must be rotated and managed out-of-band; expiry causes silent integration failure --- ## Key ServiceNow Components |Component|Purpose in this Pattern| |---|---| |Scripted REST API|Custom REST endpoint with full control over request parsing, validation logic, and response structure| |Table API|Native OOB REST interface for record reads; governed by ACLs and integration user role| |Business Rule (async)|Server-side trigger fired on record insert/update; initiates outbound REST calls without blocking the UI transaction| |Script Include|Reusable server-side library encapsulating outbound call logic, cross-reference lookup, and error handling — called by Business Rules| |ACL (Access Control List)|Governs Table API read access at table and field level for the integration user role| |REST Message|Configured outbound HTTP endpoint definition used by Business Rule scripts for provider API calls| |Integration User|Dedicated ServiceNow user account scoped to the eBond integration; principle of least privilege applied to roles and ACLs| --- ## eBond Data Contract — Typical Field Scope |Direction|Typical Fields Synchronized| |---|---| |**Inbound (Provider → ServiceNow)**|Work notes, state, provider ticket number, resolution code, resolution notes, estimated completion date| |**Outbound (ServiceNow → Provider)**|Ticket number, short description, detailed description, priority, state, assignment group, SLA due date, work notes from internal teams, closure code| |**Read (Provider queries ServiceNow)**|Current state, SLA metrics, CI/asset details, caller information, ticket history| --- ## Related Patterns - **Federated Device Inventory Ingestion** — Shares the MID Server / scripted integration mechanics but targets CMDB rather than ITSM ticket sync - **Event-Driven Webhook Integration** — Evolution of the outbound Business Rule pattern; replaces polling and async triggers with webhook push from ServiceNow to provider - **IntegrationHub Spoke Pattern** — Configuration-driven successor; replaces custom Business Rule outbound scripts with Flow Designer actions and spoke steps - **API Gateway Pattern** — Architectural complement; placing an API gateway in front of the Scripted REST API adds rate limiting, centralized auth, and request logging without modifying ServiceNow --- ## Implementation Notes - Scope the **integration user role** tightly — grant read access only to tables and fields required for the Table API path; grant write access only via the Scripted REST API's server-side script running in elevated context, not via the integration user's direct table permissions - Log **every inbound request** to a dedicated integration transaction log table — request timestamp, caller, payload hash, validation result, and target record sys_id; this log is essential for diagnosing state divergence disputes with the provider - Implement a **periodic reconciliation job** that compares open ticket states between ServiceNow and the provider — catches divergence caused by missed updates on either side and surfaces tickets requiring manual resync - Define the **cross-reference mapping** as a dedicated table (not a field on the incident table) if multiple providers are eBonded — a single field cannot accommodate multiple provider ticket IDs per ServiceNow ticket - Agree on a **data contract document** with each provider before development begins — enumerate every field, valid value set, required vs. optional, and who owns each field; this document becomes the source of truth for both the Scripted REST API validation logic and the provider's integration development - Version the **Scripted REST API endpoint** (e.g., `/api/mycompany/ebond/v1/incident`) from day one — versioning enables non-breaking contract evolution and gives providers a migration path when the contract changes - Treat **outbound Business Rule failures** as first-class operational events — route errors to an owning team with enough context (ticket number, provider, payload, HTTP response) to diagnose and manually resync without reverse-engineering log entries