The Canonical Case Model, and How Connectors Map onto It

1Background

TSANet Connect exposes one canonical case model. A collaboration between two members is a single case in the platform, and each side sees it through their own connector — as a Salesforce custom object, a Zendesk ticket, a Dataverse row, or an Intercom back-office ticket. The connectors differ in almost everything except this: they all map to and from the same canonical shape.

That makes the canonical model the one contract worth understanding before any platform-specific work. It also makes its sharp edges worth writing down, because every connector has independently had to discover them.

2Two Schemas, One Case

The most consequential property of the model is that the shape you write is not the shape you read. Case creation takes a request schema; retrieval returns a status schema; the field names differ between them. This is not a defect, and it is not documented as a mapping anywhere — an integrator meets it when a read-back returns nothing under the names they just sent.

2.1 Field-Name Divergence

2.2 Fields That Only Exist on Read

The status schema carries lifecycle state the write schema has no concept of: token, status, direction, createdAt and updatedAt, respondBy, and responded. Two of these deserve particular attention.

• token is the join key for everything. It appears in every subsequent URL and in every webhook payload. Persist it at creation, before anything else in your flow can fail.
• responded is a boolean, and it — not the status name — is what gates the response SLA. Once it is true the platform has stopped tracking respondBy, so any countdown built on the status name alone will display a deadline nobody is measuring.

3Custom Fields Are Data, Not Schema

Beyond the canonical fields, each partner defines their own intake form. Those fields arrive as a typed template from the form endpoints and are submitted back as a customFields[] array. No connector hardcodes them — the mapping is driven by the template fetched at submission time.

3.1 Form Sections

The template groups fields into sections, which is what lets a connector lay the form out sensibly rather than as a flat list:

That third section is the mechanism for identifying the end customer a collaboration is about. Because it is a partner-defined section rather than a fixed field, a connector that wants to resolve an incoming case to a local account record has to read it as a custom field and map it — there is no canonical endCustomer to bind to.

3.2 Field Types the Template Can Specify

Custom fields are typed — STRING, TEXT, EMAIL, PHONE, INTEGER, URL, SELECT and HIDDEN among them — and a connector is expected to render each appropriately rather than treating everything as free text.

4Where Connectors Put the Data

The canonical model says nothing about storage, and the shipped connectors have made genuinely opposite choices. Both are correct; the difference is worth understanding before designing a new one.

The second approach has proven easier to reason about at scale, mostly because it keeps a member's existing queues and reporting untouched. The first is lighter to install. Neither is a platform requirement.

5Known Mapping Gaps

Two mappings were not cleanly expressible on the platform until October 2026. Both are recorded here so integrators design around them deliberately rather than discovering them mid-build. The second is solved in the specification both environments now serve, and §5.2 and §5.3 say how. On Production that rests on the specification alone, which it has served since 2026-10-26; nothing there has been probed.

5.1 Priority Is Three Levels; Most Members Use Four

The canonical model has LOW, MEDIUM and HIGH. Members commonly run a four-level severity scale (S1–S4), so a three-to-four mapping is required in both directions, and it has to stay synchronised across the case lifecycle for both sides' service levels to hold. There is no canonical answer; each connector currently decides its own collapse, which means a case can read as a different severity to each party.

5.2 Note Direction: from a Case Property to a Note Property

In the earlier specification, which Production served until 2026-10-26, the note object carries no direction field. Notes are written under a synchronisation identity, so author fields are identical regardless of who sent one. The only available signal is companyName, which is ambiguous when both organisations have similar names. Direction is reliably derivable from the case, not from the note. A connector that labels notes "sent" or "received" should derive that from case direction and its own record of what it posted. Keep that fallback until direction has been seen on Production notes.

In the current specification, the gap is closed. Beta served it first. Production has served the same specification since 2026-10-26, spec-read and not probed. The note object there carries:

Because direction is relative to whoever reads the note, the same note reads as one direction to the submitter and the opposite to the receiver. Store it per side; never copy it across.

5.3 Note Types Replace a Convention

Before note types, the only way to tag a note was a convention both sides had to agree to: a structured event type in the note summary ("status change", "severity change", "new public note") and the human content in description. Until Production's specification changed on 2026-10-26, that convention was the only option there. Keep it readable until note types have been seen working on Production.

In the current specification, the platform carries the tag itself. GET /v1/note-types lists the available types, which on Beta today are partner, public, escalation and status. Creating a note takes an optional type: {code}, matched case-insensitively. An unknown code, system, or an empty object is rejected with 400, and leaving the type out creates the note with none. Those answers were seen on Beta; Production's list and answers have not been read.

6Revision History