Product Knowledge of Service Exchange (formerly knows as Service Bridge)Summary<!-- /*NS Branding Styles*/ --> .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } TABLE OF CONTENTS1. Overview - What Is Service Exchange2. Core Concepts - Producer, Consumer, and the Connection Model3. End-to-End Registration and Onboarding4. Authentication and Credential Management5. Remote Task Definitions (RTD)6. Remote Record Producers (RRP)7. Authorized Users and Personas8. Data Synchronization - How Records and Fields Sync9. Known Issues and Fixes 9.1 Comments / Work Notes Not Syncing (SE 2.3.10 Breaking Change) 9.2 Registration Stuck in Work in Progress 9.3 Registration Stuck in Closed Incomplete 9.4 Post-Clone Connection Break 9.5 Connection Down / Slow and Down 9.6 No Matching Registration Task Error 9.7 Not Authorised Contact User Error10. Troubleshooting Guide - Step-by-Step Isolation11. All Database Tables Reference12. System Properties Reference13. Background Jobs and Scheduled Scripts14. Post-Clone Recovery Checklist 1. OVERVIEW - WHAT IS SERVICE EXCHANGE================================================================================ Service Bridge, now officially named Service Exchange, is ServiceNow's native integration framework for connecting two separate ServiceNow instances so they can create, update, and synchronise work items with each other in real time. The problem it solves is organizational: large enterprises commonly run multiple ServiceNow instances — one for IT, one for a shared services team, one for a business unit, or one for a vendor partner. Without Service Bridge, the only way for work to cross instance boundaries is through manual processes or fragile custom integrations. Service Bridge provides a structured, managed, and bidirectional sync channel that is configuration-driven, not custom-coded. What it enables: A consumer instance user can create a ticket on a producer instance without logging into that instance.When the producer updates the ticket — changes state, adds a work note, resolves it — the consumer instance sees those updates automatically.Attachments, journal entries, comments, and field changes all flow in both directions based on how the connection is configured.Access is controlled per user and per connection through personas and authorized user lists. The product ships as five separate applications ServiceBridge : Base framework used by both sidesServicebridge-pro : Producer-side applicationServicebridge-con : Consumer-side applicationServicebridge-rps : Transport relay (RPS layer)Transport : The underlying transport/queue mechanism 2. CORE CONCEPTS - PRODUCER, CONSUMER, AND THE CONNECTION MODEL================================================================================ Producer InstanceThe instance that owns the work. It holds the actual task records (incidents, changes, requests). It controls what data gets exposed to consumers, defines the sync rules (Remote Task Definitions), and controls what consumers can create on its behalf (Remote Record Producers). The producer initiates nothing it responds to requests and pushes updates outward when its records change. Consumer InstanceThe instance that receives work and tracks it locally. It initiates the connection (registration), requests updates, and creates tasks on the producer via Remote Record Producers. It maintains a local mirror record (remote task) that reflects the producer's task state. ConnectionA connection is the live relationship between one producer and one consumer. Once registered and onboarded, it has a state (Up and Running, Slow and Down, Suspended) and a set of Remote Task Definitions that govern what syncs across it. Remote TaskWhen a producer task is shared with a consumer, the consumer gets a Remote Task record that mirrors key fields of the producer's original task. Changes to either side flow back through the connection. Provider TaskThe term for the producer's original task as seen from the consumer's perspective. When a consumer looks at a connected task, the "provider task" is the producer-side record. When the producer looks at what it shared, it sees "remote tasks" — one per consumer it sent it to. 3. END-TO-END REGISTRATION AND ONBOARDING================================================================================ Registration is the process by which a consumer instance formally connects to a producer instance and receives the credentials and configuration needed to sync. It happens once per connection and must be completed before any sync can occur. 3.1 WHO INITIATES REGISTRATION The CONSUMER always initiates. An administrator on the consumer instance provides the producer's URL and initial credentials, and the system sends an HTTP requestto the producer's registration REST API endpoint. The producer does not reach out first. 3.2 REGISTRATION STATES On the producer, the registration is tracked in the sn_sb_pro_registration table. It moves through these states: New - The initial state when the registration record is first created. The system immediately auto-transitions this to Awaiting Validation via the business rule "Set new Reg state to Awaiting Validation." Awaiting Validation - The producer received the consumer's registration request and is waiting for a producer administrator to review and approve it. No onboarding has started. The producer admin sees a notification prompting review. Work in Progress - The admin approved the request, and the automated onboarding flow (Automated Service Exchange Registration) is running. Credentials are being generated, OAuth tokens are being exchanged, and connection records are being created on both instances. This state should be transient. If it persists for more than a few minutes, something in the flow failed. Closed Incomplete - Onboarding started but could not be completed. The reason is recorded in the registration record's work notes. This can be triggered by validation failures, network errors, or missing required fields. Completed - All steps succeeded. The connection is established, credentials are exchanged, and both instances have each other's connection records. The connection state transitions to "Up and Running." 3.3 STEP-BY-STEP REGISTRATION FLOW Step 1 — Consumer Submits Request The consumer administrator creates a Provider Connection record on the consumer instance (sn_sb_con_provider_connection), supplying the producer's URL and initial onboarding credentials. The consumer instance sends an HTTP POST to the producer's /api/sn_sb_pro/register endpoint. Step 2 — Producer Creates Registration Record The producer's REST API creates an sn_sb_pro_registration record with state New. The business rule immediately moves it to Awaiting Validation. The producer admin is notified. Step 3 — Admin Review and Approval The producer admin navigates to the registration record and reviews the consumer's details: instance URL, company, and contact user. The admin verifies the consumer is a known and authorised party, then changes the state or approves via the provided UI action. Step 4 — Automated Onboarding Flow Executes Approval triggers the ServiceNow Flow "Automated Service Exchange Registration."This flow: a. Validates all prerequisites (Verify Crypto Module Access Policy, Verify consumer registration details) b. Generates OAuth credentials for the consumer c. Creates a Consumer Connection record on the producer (sn_sb_pro_consumer_connection) d. Sends the credentials to the consumer instance e. Consumer creates a Provider Connection record (sn_sb_con_provider_connection) with the received credentials f. A test sync is performed to verify that the connection works Step 5 — Connection Goes Up and Running The business rule "Set Conn to Up and Run Post-Onboarding" fires and marks the connection as active. Both instances now have connection records pointing at each other with valid credentials stored in sn_sb_identity records. Step 6 — Remote Task Definitions Delivered The producer pushes its configured Remote Task Definitions to the consumer. The consumer receives them as sn_sb_con_remote_task_def records. Field mappings are replicated to the consumer side. Step 7 — Remote Record Producers Delivered The producer pushes any Remote Record Producers that match the consumer's criteria. The consumer receives them as sn_sb_con_remote_record_producer records. The consumer's users can now see these as options to create work. 3.4 IMPORTANT TABLES INVOLVED IN REGISTRATION TABLEPURPOSEsn_sb_pro_registrationRegistration record of the producersn_sb_pro_consumer_connectionProducer's record of the consumer connectionsn_sb_con_provider_connectionConsumer's record of the producer connectionsn_sb_identityEncrypted OAuth credentials on both sides 3.5 WHAT THE CONTACT FIELD ON REGISTRATION MEANS Every registration record has a Contact field. This is the designated authorized contact user from the consumer organisation on the producer instance. This person: - Is the default assignee for remote tasks created for this consumer connection - Receives status notifications about the connection - Must be active, have a valid email address, and hold the sn_sb.consumer role If this user is deleted, deactivated, or missing their email, registration validation fails with "Not authorised contact user" (see Section 9.7). 4. AUTHENTICATION AND CREDENTIAL MANAGEMENT================================================================================ Service Bridge uses OAuth 2.0 for all instance-to-instance communication. Every HTTP request the transport layer makes to a remote instance is authenticated using an OAuth token. This section explains where credentials live, how they are generated, and what breaks them. 4.1 WHERE CREDENTIALS ARE STORED All OAuth credentials are stored in the sn_sb_identity table, encrypted using the instance's internal encryption keys. A single identity record holds: - The OAuth access token - The OAuth refresh token - Token expiration timestamp - Encrypted password or client secret - Reference to the connection it belongs to Both the producer and the consumer have sn_sb_identity records — one for each active connection. When the transport layer needs to call the remote instance, it retrieves the token from sn_sb_identity, decrypts it, and passes it in the Authorization header. 4.2 TOKEN GENERATION DURING REGISTRATION During the onboarding flow, the producer generates a new set of OAuth credentials specifically for this consumer. This is handled by SBTokenGenerationUtil and SBIdentityUtil. The business rule "Generate OAuth registry" participates in this step. The credentials are encrypted and transmitted to the consumer, where they are stored in the consumer's own sn_sb_identity record. 4.3 TOKEN REFRESH OAuth tokens expire. The transport layer (app-transport) handles token refresh automatically. When a token is near expiry or when a request fails with 401Unauthorized, the transport layer uses the refresh token to obtain a new access token. The business rule "Sync Expiration to Client Token" keeps the expiration timestamp on the identity record in sync. 4.4 WHAT BREAKS AUTH AND HOW TO DIAGNOSE Credential problems appear as connection state "Slow and Down" or "Connection Down" with authentication errors in sn_sb_error. Common causes: Expired credentials with no refresh token The refresh token itself may have expired if the instance was offline for a long period. Result: every transport attempt fails with 401. Fix: re-run onboarding or manually regenerate credentials. Post-clone credential mismatch (see Section 9.4) Cloning an instance replaces the encryption keys. Credentials encrypted with the old keys cannot be decrypted. The sn_sb_identity records are unreadable. Manual deletion of sn_sb_identity record If someone deletes the identity record, the transport layer has no credentials. The connection immediately goes to Connection Down. The user account behind the credentials was disabled or deleted If the OAuth client user account on the producer was disabled, the access token is revoked. Fix: re-enable the user and regenerate tokens. 4.5 TABLES TO CHECK FOR AUTH ISSUEE TABLEPURPOSEsn_sb_identity Find the record for the affected connection. Check if it exists. Check expiry date.sn_sb_errorLook for 401 or authentication error entries.sn_sb_pro_consumer_connectionOn producer — is the connection active?sn_sb_con_provider_connectionOn consumer — is the connection active? 5. REMOTE TASK DEFINITIONS (RTD)================================================================================ A Remote Task Definition is a contract defined by the producer that specifies exactly which task table gets synced, which fields flow in which direction, andWhat features are enabled for that sync relationship? 1 WHAT AN RTD DEFINES Source and target tables Which producer table (e.g., incident, change_request) is being shared, and which consumer table will receive the data. Inbound field mappings Fields flowing from producer to consumer. Stored in sn_sb_pro_inbound_field on the producer, replicated as sn_sb_con_inbound_field on the consumer. Outbound field mappings Fields flowing from consumer to producer. Stored in sn_sb_pro_outbound_field on the producer, replicated as sn_sb_con_outbound_field on the consumer. Attachment sync The send_attachments flag controls whether file attachments sync across. Journal Field Framework (JFF) eligibility RTDs with compatibility level 2.2.x or higher support syncing journal entries (comments and work notes) in addition to field values. Consumer criteria Which consumers are allowed to use this RTD. Configured via sn_sb_pro_remote_record_producer_consumer_criteria. Compatibility level The RTD version, auto-set by the business rule "Set RTD to Customer Active Version." This controls which features the RTD can use. Lower compatibility levels cannot use JFF or other newer features even if both instances are on a newer release. 5.2 RTD LIFECYCLE Created on producer Admin creates an RTD in sn_sb_pro_remote_task_def, configures tables and field mappings. Activated When activated, the business rule "Retry Errored RT on RTD Activation" fires and retries any remote tasks that previously failed due to an inactive RTD. Delivered to consumer The RTD and its field mappings are pushed to the consumer as sn_sb_con_remote_task_def records. Archived or Retired When an RTD is archived or retired, the business rule "Disconnect RT when RTD Archived/Retired" fires and disconnects all remote tasks that were using that RTD. Syncing stops for those tasks. 5.3 TABLES TABLEPURPOSEsn_sb_pro_remote_task_defRTD definition on producersn_sb_con_remote_task_defRTD delivered to consumersn_sb_pro_inbound_fieldInbound field mappings (producer view)sn_sb_con_inbound_fieldInbound field mappings (consumer view)sn_sb_pro_outbound_fieldOutbound field mappings (producer view)sn_sb_con_outbound_fieldOutbound field mappings (consumer view) 6. REMOTE RECORD PRODUCERS (RRP)================================================================================ A Remote Record Producer is a form template that appears on the consumer instance, letting consumer users create records on the producer instance without having a login there. Think of it as a service catalog item, but the record it creates lands on a different instance. 6.1 HOW AN RRP WORKS Producer creates the template In sn_sb_pro_remote_record_producer, the producer admin defines: - Which producer table the record should be created in (e.g., incident) - What fields are available to the consumer user - Variable sets for collecting additional data - Consumer criteria — which consumers can see and use this RRP - Persona criteria — which personas can use it Template delivered to consumer The RRP is pushed to the consumer during sync and stored in sn_sb_con_remote_record_producer. Consumer user fills the form A consumer user navigates to the RRP, fills in the fields defined by the producer. Variable responses are captured in the vars_json field. Request sent to producer The consumer's transport layer serialises the form data, applies any configured transforms (CSBTransportPayloadTransformer), and sends it to the producer via the transport queue. Producer creates the record The producer receives the payload, creates the actual task record in the target table, maps variable values to fields, and fires relevant business rules. A Remote Task record is created on the producer side pointing back to the consumer, and a corresponding Remote Task record is created on the consumer for tracking. 6.2 ENTITLEMENTS AND ACCESS CONTROL ON RRP Not every consumer user can see every RRP. Entitlement processing controls visibility through several layers: Consumer Criteria The producer specifies which consumer organisations can access each RRP. Stored in sn_sb_pro_remote_record_producer_consumer_criteria. Persona-Based Filtering On the consumer, each authorized user is associated with a persona. Only RRPs that match the user's persona are shown. CSBPersonaEntitlementProcessorPoint and CSBRRPEntitlementProcessorPoint apply these filters. Variable Set Entitlements Even within a single RRP, some variable fields may be hidden from certain users. PSBVariableSetEntitlementGeneratorPoint on the producer and CSBVariableSetEntitlementProcessorPoint on the consumer controls this. 6.3 TABLES TABLESPURPOSEsn_sb_pro_remote_record_producer RRP template on producersn_sb_con_remote_record_producerRRP delivered to consumern_sb_pro_remote_record_producer_consumer_criteriaWhich consumers can use each RRP 7. AUTHORIZED USERS AND PERSONAS================================================================================ Service Bridge uses a two-layer access control model: Authorized Users define who can interact with the connection at all, and Personas define what those users can see and do within that connection. 7.1 AUTHORIZED USERS An authorized user is a named ServiceNow user who has been explicitly granted access to a Service Bridge connection. Both producer and consumer sides maintain their own authorized user lists. sn_sb_pro_authorized_user - Producer's list of authorized users sn_sb_con_authorized_user - Consumer's list of authorized users For a user to interact with a remote task or use an RRP, they must be in the authorized user list for that connection. The system checks this viaCSBAuthorizedUserUtil.isValidAuthorizedUser(), which verifies: - The user exists in the authorized user table for this connection - The user is active (not disabled) - The user has a valid email address - The user holds the minimum required role (sn_sb.consumer or sn_sb.provider) 7.2 THE CONTACT USER The Contact field on sn_sb_pro_registration designates one specific authorized user as the primary point of contact for this consumer connection. This user: - Is automatically used as the default assigned-to for new remote tasks received from this consumer - Receives connection health and status notifications - Must remain active for the connection to function correctly If the contact user becomes invalid (deactivated, missing email, deleted), remote task creation for that consumer will fail with "Not authorised contactuser." The business rule "Abort authorized user if missing info" enforces this on save. 7.3 PERSONAS A persona is a named grouping that bundles together a set of RRPs, RTDs, and other entitlements. Personas are defined on both the producer and consumer sides. sn_sb_pro_persona - Producer personas sn_sb_con_persona - Consumer personas sn_sb_pro_entitlement - Entitlements granted to each producer persona sn_sb_con_entitlement - Entitlements granted to each consumer persona When a consumer user accesses the Service Exchange portal, the system: 1. Looks up the user in sn_sb_con_authorized_user 2. Reads the user's assigned persona 3. Passes the persona through the entitlement processors (CSBPersonaEntitlementProcessorPoint, CSBRRPEntitlementProcessorPoint) 4. Returns only the RRPs and RTDs that match the user's persona A user without a matching persona sees nothing, even if they have the right roles. 7.4 ROLES REQUIRED ROLESPURPOSEsn_sb.admin Full Service Bridge administration on either sidesn_sb.producerProducer-side management of RTDs and RRPssn_sb.consumerConsumer-side access to remote tasks and RRPssn_sb_pro.producerProvider-specific producer featuressn_sb_con.consumerConsumer-specific consumer featuressn_sb.journal_processorRequired for ITIL non-admin users to sync the journal entries (comments/work notes) — see Section 9.1 8. DATA SYNCHRONIZATION — HOW RECORDS AND FIELDS SYNC================================================================================ Once a connection is Up and Running and RTDs are active, Service Bridge continuously monitors both instances for changes and synchronises them. 8.1 WHAT TRIGGERS A SYNC Changes are detected by business rules that run on the task tables covered by active RTDs. These business rules are async or async_always so they do not block the user's save operation. When a relevant change happens: - A payload is built by CSBTransportPayloadSerDes / PSBTransportPayloadSerDes - The payload is placed in the sn_transport_queue table - The transport layer (app-transport) picks it up and delivers it to the remote instance via an authenticated HTTPS REST call - The remote instance processes the incoming payload through its own TransportInboundRecordProcessor and applies the field changes 8.2 FIELD SYNC For every field change that matches an outbound or inbound field mapping on the active RTD, Service Bridge creates a transport payload. The payload includes: - The sys_id of the record that changed - The field names and new values - Metadata about the connection and RTD version SBTransportPayloadTransformer applies any configured transforms to field values before the payload is sent and after it is received. 8.3 COMMENT AND WORK NOTE SYNC Comments (customer-visible notes) and work notes (internal notes) are special. They are stored in the sys_journal_field table, not as regular fields. ServiceBridge handles them separately through the Journal Field Framework (JFF). How it works: When a user adds a comment or work note to a task that has an active remote task connection, an insert fires on sys_journal_field. The async business rule "Sync journal entries for task" catches this insert and calls SBJournalUtil.syncTaskJournalsOnFly(current) to transport the journal entry to the connected instance. The business rule condition is: current.canRead() && new SBJournalUtil().shouldJournalFieldSync(current) The shouldJournalFieldSync() method checks that: - The task table is rooted in the task hierarchy - The user adding the entry is not the transporter user (to prevent loops) - The user is not in a blocked list (system user) - The task has an active remote task connection JFF requires RTD compatibility level 2.2.x or higher. Connections using older RTD compatibility levels do not sync journal entries via this mechanism. 8.4 ATTACHMENT SYNC The business rule "Service Exchange Attachment sync from Task" monitors the sys_attachment table for inserts and updates on records that have active Service Exchange connections. When an attachment is added: - CSBTransportAttachmentManager builds the attachment payload - Binary content is included in the transport - The receiving instance stores the attachment under the corresponding record 8.5 THE SCRATCHPAD sn_sb_scratchpad is a staging table used for sync operations that need temporary storage during processing - for example, holding data between multiple transport hops or during the handshake for new remote tasks. Scratchpad entries for inactive or deleted tasks are cleaned up automatically based on thesn_sb.scratchpad.autodelete.days property (default: 3 days). 8.6 ERROR HANDLING When a sync attempt fails, the error is recorded in sn_sb_error with: - The affected remote task and connection - The error message and error code - A timestamp of when it occurred The sn_sb_known_error_code table provides documented descriptions for common error codes, which appear on the connection and error detail screens to help admins understand what failed without diving into logs. Repeated sync failures cause the connection health monitor to move the connection state to "Slow and Down" (see Section 8.7). 8.7 CONNECTION HEALTH MONITORING The scheduled script "Validate Slow and Down Connection" runs periodically and performs an HTTP health check against the remote instance. CSBHealthUtil manages this. Results are recorded in sn_sb_health_issue. If the health check passes, the connection state returns to "Up and Running." If it fails repeatedly, it stays in "Slow and Down" and admins are notified. Connection states: Not Onboarded ---> Initial state; no sync possible Onboarding ---> Registration flow is running Up and Running ---> Connection active; sync normal Slow and Down ---> Health checks failing; degraded or no connectivity Suspended ---> Manually suspended; sync paused Release<!-- /*NS Branding Styles*/ --> .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } All