Hub / Build

Build a New Integration

Start here if your platform has no TSANet connector, or you are wiring Connect into something of your own. One question decides which of four routes fits, the routes are ordered by how much you have to build, and the tools you use on any of them are one page away.

Routes 4, in order of effort Decides between them one question about your platform Before anything is real Beta, test-flagged
The Question Four Routes The First Week Tools Worked Examples

Settle this first

Will the Platform Run Your Code Inside the Member's Own Tenant?

It is a property of the platform, not a choice you get to make.

The answer decides who operates the integration, where credentials live, whether connector faults are isolated to one member or shared across all of them, and whether shipping a fix means asking every member to upgrade. Ask it before scoping anything, because it is what makes route one or route two the natural fit — and the platforms that answer "sort of" are where the design work is.

Yes — in-tenant Salesforce and Dynamics say yes and get managed packages the member installs. You build against the API or the SDK, and the member operates it.
No — gateway Intercom says no, so the adapter runs as a service on the Connect Gateway, hosted by TSANet or by the member. You write only the half that talks to your platform.

The taxonomy, the consequences of each class, and what to do when a platform answers both ways: Two Ways to Build a Connector. The worked case of an ambiguous answer is the ServiceNow assessment.

Options

Four Routes, in Order of Effort

Work in progress · v3.0.0

Build on the Connect Gateway

TSANet supplies the engine, the contract and a conformance harness that certifies the seam; you write only the half that talks to your own platform — and never touch the Connect API or its errors. The least effort, and the route for any platform that will not run your code in the member's tenant. The repository is private; adapter authors get access at onboarding.

Design & adapter guide → v3.0.0 · Java

Use the SDK

A Java client over the Connect API with typed facades, validation and both auth modes, published as a public package. The shortest path on the JVM that is not hand-rolled HTTP, and the one that already encodes the API's sharp edges.

Library reference → Pattern

Build Against the API

The translation-service pattern: your platform's events in, Connect API calls out, updatedAfter polling back. For any stack that is not the JVM. Read the behaviour guide before you design; the reference alone will not tell you about the default error mode or the webhook version trap.

Working with the API → Wish list

Tell Us the Platform

Which platform your team runs on is the single most useful thing you can say to us — it is what decides which connector gets built next. If yours is common among members, the right route may be to wait for a connector rather than build one.

Community →

Sequence

The First Week, Whichever Route

  1. Get a Beta account from membership@tsanet.org, and if you will use OAuth client credentials, have TSANet provision your service principal at the same time — an app-only token is not accepted until they have.
  2. Call GET /v1/me and confirm the company your credentials resolve to. Every call is scoped to that identity.
  3. Fetch a partner's process form fresh and submit a case with testSubmission: true. Nothing you send reaches a real partner while the flag is set, and the documentId you must submit comes from that fetch.
  4. Read it back. The shape you write is not the shape you read, and responded, not the status name, is what gates the SLA. TSANET-2026-001 is the map.
  5. Send the Accept header on every call — Accept: application/json, application/problem+json — or every rejection arrives as HTTP 500 and looks like an outage.
  6. Persist the token at creation, before anything else in your flow can fail. There is no idempotency key on create; a blind retry is a second case.
  7. Subscribe to webhooks on v2, verify the signature before processing, fast-ack, and keep a poll behind the push — delivery is at-least-once and the fetch is what establishes truth.

Each of those is a section of Working with the API, which exists because the reference does not say them.

Tools

What You Use Along the Way

All tools →
Public

Beta and the Test Flag

The environment to build on, and the flag that keeps partners out of it until you mean it.

 Public

Reference and Postman

The generated endpoint reference and a collection that exercises every path with your credentials.

 Public

connect-library

The Java client as a public package; the console app and web demo behind it.

 Access at onboarding

Test Suites

The Gateway conformance harness for adapter authors; the connector test harness is not public yet.

 Public

Agent Skills

Four skills that load into any assistant that reads the open skill format, two of them public today.

 Questions

Where to Take What

Trackers for connector bugs, membership for credentials, the discussions for everything else.

Worked examples

The Shipped Integrations, Read as Examples

Four connectors and one assessment. Each page shows the class it landed in, what it installs, and how it maps the canonical case onto its platform's data model — which is the part to read before you design your own mapping. The comparison matrix puts the four side by side.

GA · in-tenant

Salesforce

Managed package; collaboration state in first-class custom objects; a Flow library as the extension point.

 GA · in-tenant

Microsoft Dynamics

Managed solution; six Dataverse tables; field mapping as a configuration table rather than code.

 GA · partial

Zendesk

A sandboxed app plus declarative flows; state in ticket fields and tags; the three-audience note model.

 Early access · gateway

Fin / Intercom

The first gateway-class adapter: TSANet-hosted or self-hosted, the engine holds the state, the taxonomy parks ambiguity.

 Not built · assessment

ServiceNow

What scoping looks like before code exists: every claim tagged, every open question named with what it blocks.