Moving to ServiceNow REST and SOAP Integrations: Migration Considerations

A move to REST and SOAP integrations means replacing older connections between ServiceNow and other systems with designed REST or SOAP contracts, in stages. This page helps the migration team decide which legacy integrations to upgrade, keep, wrap or retire, and how to cut over without losing data.

Cataloguing Existing Integrations and Protocol Assessment

Before migrating to REST and SOAP integrations, audit all existing integrations connecting to or from ServiceNow. Document which systems are connected, what data flows (inbound, outbound, bidirectional), what protocols are currently used (legacy APIs, file transfers, custom connectors, middleware), and how business-critical each integration is. Some organisations operate dozens of integrations; others have hundreds. Each represents potential migration work and risk if something breaks.

Assess which legacy integrations can be upgraded to REST or SOAP and which must continue as-is due to source system limitations. Older on-premise systems may not support modern APIs; SaaS applications typically have REST endpoints. Integrations to systems that won’t be upgraded should remain on legacy protocols or use middleware as a translation layer. Prioritise integrations to modern systems that support REST as high-priority migration candidates; integrations to legacy systems can wait or be shelved indefinitely.

API Capability Mapping and Authentication Strategy

For each integration candidate, review the target system’s API documentation. Do available endpoints provide the functionality your current integration relies on, or would migration require workarounds? Some systems expose data via REST but lack bulk operations your integration performs; others support batch APIs not exposed via REST. Detailed API review prevents discovering incompatibilities during migration.

Plan authentication approach. REST and SOAP integrations typically use OAuth, API keys, certificates, or HTTP basic auth. Understand what the target system supports and what your security policies require. If your current integration uses basic auth over HTTP, upgrading to OAuth and HTTPS improves security; if transitioning to certificate-based auth, plan certificate management and rotation. Authentication complexity often underestimated in migration timelines.

Data Mapping and Transformation Strategy

Legacy integration formats often differ from REST/SOAP APIs. Data field names, structures, formats, and validation rules may be different. Create detailed mapping documents showing how data from the legacy format transforms to the new API format. Handle edge cases: what if a field in the old format has no equivalent in the new API, or vice versa? Incomplete mapping often causes data loss or corruption during migration.

Test data transformation with real samples from production. Transform a representative set of records (successes and edge cases) and validate output. Common issues include date format mismatches, numeric precision differences, character encoding problems, and special characters in text fields. Discovering these issues during testing is far better than discovering them in production after integration is live.

Cutover Strategy: Phased vs Parallel vs Big-Bang

Three primary cutover approaches exist. Phased migration (cutover one integration at a time) distributes risk but requires managing both old and new integrations simultaneously, increasing complexity. Parallel operation (run both integrations, compare results) validates correctness before switching but doubles infrastructure load temporarily. Big-bang migration (cutover everything simultaneously) is simplest operationally but highest risk—if issues arise, many systems are affected at once.

Choose based on integration criticality and your risk tolerance. High-criticality integrations benefit from parallel operation; low-criticality integrations can use big-bang. Most organisations choose a hybrid: parallel operation for critical integrations, phased for others, and big-bang only for rarely-used integrations.

Error Handling and Data Reconciliation Planning

REST integrations can fail in many ways: network timeouts, API rate limits, authentication failures, server errors, malformed responses. Design error handling before migration: which errors are transient (retry later) versus permanent (escalate to support)? Configure retry logic with exponential backoff to handle transient failures without overwhelming the target system. Set up alerting for permanent failures so support teams know issues occurred.

Plan data reconciliation procedures. After cutover, compare data in both systems to detect loss, duplication, or corruption. Reconciliation scripts can systematically check record counts, sample data values, and transaction logs. If issues are found, being able to rollback to the previous integration depends on having good reconciliation data. Budget time for reconciliation; don’t assume cutover is complete until reconciliation confirms data integrity.

Monitoring and Rollback Procedures

Set up comprehensive monitoring before migration. Track integration success/failure rates, data latency (how long between transaction in source and appearance in target), and data volumes processed. Establish normal baselines for these metrics; anomalies signal issues. Monitor the minutes immediately after cutover closely; most problems surface within the first hour of live traffic.

Document rollback procedures and test them. If the new integration experiences critical issues, can you quickly switch back to the old integration? Rollback procedures should be documented, practiced, and fast: the time from detection to rollback complete should be agreed in advance. If rollback isn’t feasible, consider extending parallel operation period until you’re more confident in the new integration.

Testing Scope and Scenarios

Integration testing must cover success paths and error scenarios. Test with realistic data volumes (consider peak volume, not average). Test boundary conditions: very large requests, requests with special characters, requests with unusual field combinations. Test error conditions: target system down, slow responses, rate limit responses, authentication failures. Test data consistency: confirm that records migrated through the new integration match those migrated through the old integration.

Involve system owners and support staff in testing. They understand edge cases and rare scenarios that developers might miss. Allocate sufficient time for testing—compressing test timelines to meet deadlines is a common cause of missed issues that surface in production.

Start with an inventory of what ServiceNow already calls out to

Before any new REST or SOAP design is drawn, list everything the instance already does with the outside world. In a mature platform that list is longer than anyone remembers. It usually includes outbound REST messages configured years earlier, business rules and script includes that call external URLs, transform maps that read from staging tables, scheduled jobs that fetch files, and flow actions that were added to solve one urgent request. Each entry needs a record of its trigger, its identity, the data it moves and the person who would notice if it stopped. Without that record, a migration retires the visible integrations and breaks the hidden one that nobody thought to name.

Decide the fate of each legacy flow

Once the inventory exists, every legacy flow needs one of four outcomes. Keep it as it is, wrap it in a new interface without changing the source, replace it with a REST or SOAP design, or retire it. The choice depends less on technical elegance than on who depends on the output and whether the source system will ever change. The table below sets out how to decide.

Keep a single source of truth during dual running

Parallel operation is where migrations quietly corrupt data. When the legacy and the new flow both write to the same ServiceNow table, duplicate records and conflicting updates are the usual result. Before switching anything on, decide which flow is authoritative for each field and make the other flow read-only for that field, or direct it to a shadow table where its output can be compared without changing live records. Record the decision as a field-level ownership list, because a whole-integration decision hides the fields that overlap.

A cutover order that keeps the business running

1. Freeze the mapping for the first integration and confirm the consumer has approved the new field names and formats.
2. Stand up the new flow in a sub-production copy of the instance and load a representative slice of production records.
3. Run the legacy and new flows side by side, writing the new output to a comparison table rather than live records.
4. Review the differences with the consuming team and classify each one as an expected change, a defect, or an unknown.
5. Switch the authoritative flag for the first integration only, with the legacy flow still scheduled but paused, and keep it that way until the reconciliation owner signs off.
6. Retire the legacy flow once nothing has depended on its output for an agreed review period, then remove its credentials and its scheduled job.

Plan for the things that do not show up in testing

Migrations often fail on behavior that testing did not exercise. Scheduled jobs that ran at a quiet hour can overlap with the new flow’s batch. Time zones on imported dates can shift a record across a day boundary. A legacy flow that silently truncated long text fields may have done so for years, so the new flow will look like it is adding data that users never saw before. Compare volumes, not just samples, and ask the consuming team what they would notice first if a value were wrong.

When a migration should not happen yet

Hold the cutover when the inventory is incomplete, when the consumer has not agreed the new contract, or when nobody can name who will run the reconciliation after go-live. Those gaps are not solved by a faster schedule. A migration that starts without them tends to finish with two integrations running and nobody certain which one is right.

Questions about moving off legacy integrations

Do we have to migrate every legacy flow to REST or SOAP?

No. A flow that serves a stable purpose, reads from a source that cannot change, and has a named owner can stay where it is. The aim is an inventory that is understood, not a platform with no legacy at all.

How do we find integrations nobody documented?

Search the instance for outbound calls and transform maps, review scheduled jobs by last run and by owner, and check the credential store for aliases that no active process references. Ask the teams that use the data what arrives and from where. The answers usually reveal the undocumented flows.

Can we run the old and new flows against the same table during testing?

Only if the new flow writes to a comparison table or the legacy flow is read-only for the duration. Shared writes during testing create records that look like defects and are very hard to unpick afterwards.

Get the inventory checked before cutover

Inventories rarely come out complete on the first pass, and a missed flow is the most expensive surprise in a migration. The implementation roadmap for REST and SOAP integrations sets out the phases of that work across a wider program, and the guide to proving readiness before an integration switch covers the evidence to prepare. If a legacy feed is being replaced by a staged load, the explainer on import sets describes that staging step.