ServiceNow Integration best practices

Every integration needs a named owner on both sides, a documented payload contract and an agreed error path. Most integration incidents are really ownership incidents: something changed and nobody told the other team.

The reason to start with contracts rather than technology is that integrations outlive the people who built them. Three or four years later, something breaks at two in the morning, and the questions are always the same: what does this integration do, who owns the system at the other end, and who is allowed to decide whether to turn it off.

So the minimum worth writing down for each integration, before any code: the business purpose in one sentence, the direction and who initiates, the data it carries and who owns each field, the volume and frequency you expect, what happens when it fails, and who to call on both sides.

That fits on a page. Integrations without one are the ones that get discovered during an incident, and the discovery takes longer than the fix.

Ownership is the half that decays fastest. The named owner leaves, the team reorganises, and the contact in the document is somebody who has not worked there for two years. So the useful form is a role or a group rather than a person, on both sides, and a review of that list once a year. It sounds bureaucratic until the first time an integration fails and nobody at either end will claim it.

The platform offers several ways to move data and teams often pick the one they used last time rather than the one that fits. The distinctions that matter:

Inbound REST to the Table API writes straight to a target table. Simple, fast, no mapping. Right when the sender already speaks your data model.

Inbound REST to the Import API goes through a staging table and a transform, so you get mapping, coalescing and a record of what was sent. Right when the payload needs translating.

IntegrationHub spokes are prebuilt actions for common systems, used from a flow. Right for outbound work against a system somebody has already built a spoke for.

Scripted REST APIs are your own endpoints with your own contract. Right when the external system cannot be changed and needs an interface shaped its way. Also the most code to maintain.

MID Server when the target is inside a network the instance cannot reach.

The decision rule: use the least code that meets the requirement. Every scripted endpoint is something somebody has to understand at three in the morning, and a spoke or a transform map is not.

A short list of defaults prevents most production problems.

• Dedicated integration user with least privilege, never a personal account
• Connection alias and credential records, never hard coded endpoints or secrets
• Timeouts on every outbound call and retry policy for transient errors
• Idempotent operations keyed on a client reference so replays are safe
• Payload limited to fields you use, so upstream changes break less

Three of those defaults deserve expanding, because they are the ones that decide whether an integration survives contact with production.

Idempotency. Networks time out, senders retry, and a retry that creates a second record is a data quality incident. The answer is a key the sender controls, stored on your record, and used to coalesce. Without it, every integration is one timeout away from duplicates.

Backoff. A target that is down does not benefit from being called every ten seconds. Retries should space out, and there should be a point at which the integration stops and tells somebody rather than retrying forever.

Payload size and batching. Small, frequent batches fail in small pieces and recover quickly. One enormous batch fails entirely and takes an argument to restart.

Authentication deserves the same treatment. Each integration gets its own account, with only the roles it needs, and credentials stored in the platform's credential store rather than in a script. A shared account across five integrations means an incident in one forces you to rotate credentials for all five, and volume in the logs cannot be attributed to anything. Where the target supports it, prefer OAuth to a stored password, because rotation stops being a manual exercise somebody has to remember.

Log a correlation id on both sides, alert on error rate rather than single failures, and keep a dashboard that shows volume and latency per integration. When something breaks at 2am, the person paged needs to see which integration and how long it has been failing.

The distinction worth drawing is between logging and alerting. Every integration logs. Very few alert, and alerting is what turns a log into something operationally useful. The trigger should be a rate rather than a single event: one failure is noise, and twenty in an hour, or zero successes in a period where you expected hundreds, is a signal.

That second case is the one teams forget. An integration that stops being called entirely produces no errors at all, so error based monitoring is silent precisely when the integration has disappeared. A check on expected volume catches it and nothing else does.

Version note: the toolkit has grown substantially. Older integrations were built as scripted REST endpoints and web service imports because there was nothing else; current instances have IntegrationHub spokes, Flow Designer and robust transform tooling that between them cover a great deal of what used to be hand written. When reviewing an old integration, part of the question is whether it should exist in that form at all. See scripting practices, update sets and catalog practices.

Retention is the last piece and it is cheap to get right. Keep enough transaction history that you can answer a question about last month, and clear it aggressively beyond that, because integration logs are among the fastest growing tables on any busy instance.

This is the exercise to run on something already in production, and it usually finds something.

1. Pick an integration and find its documentation. If there is none, that is the first finding.
2. Find the account it authenticates as. Check whether it is dedicated to this integration and what roles it holds. A shared account with broad roles is the second finding.
3. Send a request that should fail: a bad reference, a missing mandatory field. Read what comes back and ask whether the sender could act on it.
4. Find where failures are recorded. Then find out who looks at that place.
5. Send the same successful request twice and check whether you now have two records.
6. Look at the volume over the last month against what was expected.

Step four is the one that most often has no answer. An integration whose failures are logged where nobody looks is indistinguishable from one that is working. See CMDB practices for what happens when this goes wrong at scale.

• No idempotency key. One timeout produces duplicates.
• A shared admin account. Volume, errors and blame are all unattributable.
• Alerting on errors only. Silence looks like health when the integration has stopped.
• Scripted endpoints where a spoke exists. More code, no more capability.
• No written contract. Discovered during an incident, at the worst possible time.

The checklist above takes an afternoon to apply, and designing an integration that somebody can still operate three years later is the work the course covers.