The review where someone offers the whole Case object

The proposal arrives in the design review with good intent. The Service Cloud team will publish a platform event whenever a case changes, carry every field on the Case object, and the ServiceNow team can pick what they need. Nobody has to come back and ask for another field. I have sat through that pitch a dozen times, and the interface that ships from it is the one that hurts most a year later.

What follows is predictable. The ServiceNow flow starts reading a field it was never promised. Someone in Salesforce renames a picklist value during a clean-up. Incidents stop being created on a Tuesday afternoon with no error on either side, and the two teams discover they never agreed on anything. They agreed to share a table.

A contract is the short list of things one system promises to send and the other promises to act on. Keeping it small is what lets both teams read the whole thing in one sitting and say yes to it. Most of the integration failures I get asked to look at trace back to a contract nobody could read in one sitting. This is what I ask for before an interface between the Salesforce Platform and ServiceNow Workflow Automation is allowed to widen.

Name the business event before you name a field

The first thing I write on the whiteboard is the event in the words the business uses. Case escalated to IT. Change approved. Supplier record changed. If the best anyone can offer is Case updated, there is no event yet, only a table sync with an event name on it.

Naming the event does two useful things. It tells the receiving team what they are meant to do when it arrives, which is the part they can test. And it draws a line around the data. Case escalated to IT needs the case number, the customer account key, the priority, a short description, and the assignment group it should land in. It does not need the last modified date, the owner's manager, or the forty custom fields support added over five years.

In the meeting I ask one question about every field someone wants in the payload, which is what the receiver does with it on arrival. If the answer is that they will store it in case it turns out to be useful, the field stays out. If the answer is that the incident cannot be routed without it, the field goes in and the receiver writes down what they do with it. Those written lines are the contract, and there is usually one page of them.

Version when the meaning changes, not when a field is added

Teams get anxious about versioning because they believe every change needs a new version. Adding an optional field to a platform event payload breaks nobody who ignores it, and the ServiceNow flow that reads the old fields carries on. That is a minor change. I record it in the contract with a date and move on.

A field whose meaning changes is another matter. When the priority picklist in Service Cloud goes from four values to three, or the customer key switches from the Salesforce account ID to the billing customer number, every consumer has to change what it does. That gets a new version, which in practice means a new event name or a new endpoint, and a period where both versions are published so the ServiceNow team can move on their own release calendar rather than yours.

The key rule is the line I guard hardest. Which field identifies the customer, the case, or the change on both sides is what everything else is built on, and choosing a durable business key up front is far cheaper than swapping it later. If that line changes, it is a new contract, and every consumer hears about it before anything ships.

Write down what happens when the receiver is not there

The section of the contract that decides whether an interface is safe to run has nothing to do with fields. It says what happens when ServiceNow is unavailable, what happens when a record cannot be matched, and what happens when the same event arrives twice. Most contracts I review skip all three, and the answers get improvised at two in the morning by whoever is on call.

Consumer unavailable is the easiest of the three to specify and the one most often left blank. Platform events in Salesforce keep a retention window and a replay ID, so a subscriber that was down for an hour can pick up where it left off, provided someone built it to store the last replay ID it processed. If the ServiceNow side is a scripted REST endpoint called directly from a flow, there is no window at all, and the flow needs a retry with a limit and somewhere to record the message that gave up. Write down which of those you have and how long an outage the design survives.

Unmatched records cause the most arguments. A case arrives for an account that ServiceNow has never heard of. The tempting answer is to create the account from the payload, and now two systems create customers. The right answer depends on who owns the account, and the contract should say whether the event is held, sent back to Salesforce, or parked in a queue with a person's name on it. The queue is not the owner of that exception, and the contract is where you say who is.

Duplicates are guaranteed. A retry fires after a timeout, the first call had actually succeeded, and now there are two incidents for one case. The contract names the idempotency key, usually the case number plus the event name, and states what the receiver does with a second copy. In ServiceNow that means a correlation ID on the incident and an update-or-insert step in the flow rather than a plain create. If nobody in the room can say what the second copy does, the interface is not ready.

What one page of contract holds

The contract itself fits on a page. I keep it where both teams already look, which for a platform event is the event definition's description in Salesforce and for a ServiceNow endpoint is the description on the scripted REST resource. A document in a project folder is lost the day the project closes. For every event that crosses the boundary, this is what the page holds.

  • The business event, in the words the business uses, and the team that owns it.
  • The key that identifies the record on both sides, by schema name, and which system issues it.
  • Every field in the payload, with one line on what the receiver does with it.
  • The version, the date it last changed, and how long the previous version stays published.
  • What the receiver does when the record cannot be matched, and who clears that queue.
  • The idempotency key and what happens to a second copy of the same event.
  • How long an outage the design survives and where a message that gave up is recorded.

Say no to the wide payload in the room

The hardest part is the meeting, because the wide payload is offered as help and refusing it sounds unhelpful. What I say is this. We will send the five fields the incident needs today, and when you need a sixth, you will ask and we will add it within a week. That is faster than the alternative, which is both teams reading forty fields nobody promised to keep stable.

Then I ask the ServiceNow lead to describe, without looking at the payload, what their flow does when a case for an unknown account arrives twice during a Salesforce release window. If they can answer, the contract is small enough. If they cannot, the interface is not ready, and it is cheaper to learn that now than the week after go-live, when the integration map gets drawn for the first time on an incident call.

Before your next review, pick the interface that pages people most often and count the fields it carries. Then count the ones the receiving team can explain. The gap between those two numbers is the contract you still need to write.