Plan your integration

No code yet. Write down what your product says and hears. You use it to set up your apps in the portal, and as your test plan.

1. List your systems

One row per system the bus should see, usually one per product. A product with two separable services (an ingest service and a skill executor, say) gets two.

App name	system_type	system_ids on the Sandbox	Signs in with
acme-ncs	ncs	acme-ncs-test	Client secret
acme-skills	skill_worker	acme-skills-test	AWS role

• App names are lowercase with hyphens.
• system_type must be one of SOM 1.0's values (see The envelope). If none fits, use custom and set system_name.
• Keep system_id configurable in your product. Each publisher assigns its own.
• A system_id belongs to one app on the whole bus, first come, first served. Prefix it with your organisation.
• Systems that run in AWS can sign with their IAM role instead of a secret, and your own identity provider's clients can sign in too. See Authenticate.

2. Declare what each system produces and consumes

This is your integration profile. SOM expects every system to be able to say which families it produces and consumes. The bus enforces the "produces" half: a message type your app isn't granted is refused with producer.message_type_not_allowed.

App	Produces	Consumes
acme-ncs	story.context, system.audit	skill.warning.raised, telling.*
acme-skills	skill.warning.raised	story.context

Message types are exact (story.context), a family (telling.*) or everything (*). Ask only for what you send: the refusal is useful evidence that your product doesn't send what it shouldn't.

3. Pick your test stories

Build them from synthetic content. The published SOM 1.0 examples are a good start; they're in the SOM repository.

Story	Exercises	Start from
Breaking story: seven snapshots, from developing to confirmed	Snapshots, sequence, assets, gates, compliance	examples/hurricane-run/
Killed story: active, then KILLED	Terminal states: reviving it must be refused	Snapshot 1 of the hurricane run
Story with a telling: a snapshot, a link commit, then a telling	Messages of several families under one correlation_id	examples/link/, examples/telling/
Media arrival	delivery.media_available with a reference, never media	examples/delivery/
Skill warning	causation_id pointing at the snapshot that triggered it	examples/skill-warning/

Give every run its own story_id and correlation_id: the bus remembers where every story in your workspace stands (its sequence state, not the payload), with no expiry. Prefixing story ids with your app name keeps them apart when several of your apps publish into one workspace.

4. Decide what "done" looks like

Copy the readiness checklist into your test plan now and strike out the lines that don't apply to you. Every line left should have a test by the end.

Set it up Available now

Once you're in your workspace, the tables from 1 and 2 become your apps: create each app, connect the producers with their system_ids and message types (Credentials), and create a consumer connection for each system that consumes.

Next: Credentials.