Integrate as a vendor

The whole journey on one page, from an access request to a results statement you can share with a publisher. After RND approves your request, every step is yours to do in the portal and over the API: no request to RND and no deploy. Each step links to its full page.

Short on time?

On the bus in about 15 minutes is the same journey as five missions, one block to copy each. This page has the detail behind every step.

It's for vendors whose product produces SOM messages (an NCS, a graphics system, a skill executor), consumes them, or both. Not sure which parts apply to you? See Which parts apply to you. What the publishers you work with do on their side is in the publisher track.

1. Request access Via RND

Send the Request access form. RND reviews it and, on approval, creates your organisation and its first workspace. See Request access.

2. Join your workspace Available now

Sign in with the temporary password from your approval email, set up multi-factor sign-in and accept the invitation to your workspace. Its Overview then shows a checklist of first steps that ticks itself as you go. See Your workspace in the portal.

3. Create an app and get its credentials Available now

On Apps and credentials, a developer, admin or owner creates an app with New app and presses Connect on it, choosing the system_ids it stamps and the message types it may publish. The portal shows its client id and client secret once. See Credentials.

Systems that run in AWS can sign with their IAM role instead, and organisations with their own identity provider can use its clients: see Authenticate.

4. Get a token Available now

TOKEN=$(curl -s https://api.sombus.rnd-solutions.net/v1/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" -d grant_type=client_credentials | jq -r .access_token)

A token lasts one hour. Reuse it for its whole hour and fetch a new one shortly before it expires; don't fetch one per message. See Token service and workspace API.

5. Dry-run, then publish Available now

Want to receive these messages too? Create the consumer connection first

A consumer connection receives only what is published after it exists. If you'll read your own messages back, do step 8 first and wait until the connection is ready: until then the pull API answers 503 consumer.queue_unavailable (usually a minute, at most about 10). Messages you publish before that are never delivered to it.

$WORKSPACE below is your workspace id (the tenant claim of your token). POST /v1/tenants/{t}/validate runs every check with your app's own grants and your workspace's story state, and publishes nothing. POST /v1/tenants/{t}/messages publishes.

A first story, built from the upstream SOM 1.0 example (the hurricane run). Use one of your own system_ids:

SOM=https://raw.githubusercontent.com/storyobjectmodel/som/7297fef9adc6d14a74bdd7550c78decaa099a1ad/examples/hurricane-run
curl -sO $SOM/hurricane-01.json
curl -sO $SOM/hurricane-02.json

STORY=acme-ncs-$(date +%s)            # a new story_id per run
CORR=$(uuidgen | tr A-Z a-z)          # one correlation_id for the whole story
envelope() {  # $1 = payload file
  jq --arg mid "$(uuidgen | tr A-Z a-z)" --arg cid "$CORR" --arg story "$STORY" \
     --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg sys acme-ncs-01 \
    '{som_version: "1.0.0", message_id: $mid, correlation_id: $cid, message_type: "story.context",
      timestamp: $ts, originating_system: {system_id: $sys, system_type: "ncs"},
      topic: "som.story.context", payload: (. + {story_id: $story})}' "$1"
}
envelope hurricane-01.json > msg-1.json
envelope hurricane-02.json > msg-2.json

API=https://api.sombus.rnd-solutions.net/v1/tenants/$WORKSPACE
curl -s -X POST "$API/validate" -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' --data-binary @msg-1.json
# {"accepted":true,"dry_run":true,"message_id":"...","message_type":"story.context","family":"story-context"}
curl -s -X POST "$API/messages" -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' --data-binary @msg-1.json
# {"accepted":true,"message_id":"...","message_type":"story.context","family":"story-context"}
curl -s -X POST "$API/messages" -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' --data-binary @msg-2.json

Send msg-1.json again and you get 200 with "duplicate":true: a retry is safe. Send msg-1.json rebuilt with a new message_id after msg-2.json and you get 409sequence_number.not_increasing.

The bus remembers every story's sequence state (not its payload) in your workspace with no expiry, so each test run needs a new story_id (the date +%s suffix above).

The full walk-through: Send your first message and Run a whole story. What the gateway expects of every message: The envelope and Snapshots, not deltas.

6. Read the response Available now

Every response is JSON. A refusal names each problem with a source and a stable rule id:

{"accepted":false,"violations":[{"source":"sequence","rule":"sequence_number.not_increasing",
  "path":"/payload/sequence_number","message":"sequence_number 2 -> 1: must strictly increase; ..."}]}

What each status means and what your product should do: Handle the bus's answers and Retries and idempotency. What each rule means: the rule catalogue.

7. Check your work in the portal Available now

• Playground: paste a message, or load an example, and press Validate. It checks the message against your workspace's story state and, with a producer chosen under Send as, that app's grants. It also lists the consumer connections that would receive it. See The Playground.
• Activity: the gateway's decisions for the last 7 days, with outcome, status, producer, message type, story and rule ids. Never payloads.
• Story timeline: each story of your workspace in the last 7 days, with its messages in order and what changed between snapshots.

8. Consume Available now

On Consumer connections, create a connection for one of your consumer or skill apps, with the message types it receives. The bus makes its own queue and dead-letter queue, usually within a minute and at most about 10; until then the pull API answers 503 consumer.queue_unavailable. The connection receives only what is published after it exists, so create it before you publish the messages you want to read. Press Get client secret and read it over HTTPS, with no AWS account:

curl -s -H "Authorization: Bearer $CONSUMER_TOKEN" \
  "https://api.sombus.rnd-solutions.net/v1/tenants/$WORKSPACE/consumers/$CONSUMER_ID/messages?wait=20"

Handle each message, then acknowledge it. See Consumer connections, the HTTPS pull API, and what every consumer must do: Order, duplicates and snapshots.

9. Test and share what passed Available now

In a vendor workspace, Test runs play consumer scenarios and skill cases into your workspace and grade every case. A results statement then says exactly which cases passed, against which suite, and you share it with a publisher or by link. It states what passed in the sandbox, never a certification.

Known limits

• One AWS reader role per consumer connection. You register it yourself and it proves control first; for an IAM user or more roles on one queue, ask RND. See Consumer connections.
• Changing a connection's system_ids or message types isn't in the portal: revoke it and connect again.
• Requests signed with an AWS role share one rate limit across every AWS signer on the bus, instead of your connection's own allowance. See Authenticate.
• Message types without a SOM 1.0 schema are accepted with the envelope checked and the payload not (payload.unvalidated). Many skill recall_on topics are in this group.
• The skill library's sample warnings don't validate. The 0.2.2 samples use a wrn-… warning_id, a null skill_warning_ref and, in one skill, a system_type outside the enum. SOM 1.0 refuses all three; see A warning that validates.
• Questions go to RND through Ask RND in the portal. See Ask RND.

Apps RND manages for you Via RND

Before workspaces, RND registered apps in the bus configuration by hand, and some still run that way. If RND set up an app for you like this:

• It gets tokens from a token URL RND sent you, with HTTP Basic and scope sombus/publish, and publishes to POST /v1/jwt/messages. A system in AWS may instead sign POST /v1/messages with SigV4, with a role RND registered. Same body, same answers.
• All such apps share one tenant: a consumer RND set up there receives every such producer's messages of its types, including RND's own tests. Prefix your story_ids and ignore traffic that isn't yours (the producer_id attribute).
• Its traffic isn't in your workspace, so it doesn't show in your portal pages; ask RND for its activity.
• Changes to it wait for a reviewed deploy by RND.

To move to your workspace, create and connect the app yourself (step 3). Everything else on these pages applies unchanged.

What's still coming

Coming None of this is available yet, and none of it has a date.

• Changing a connection's system_ids and message types in place.
• A per-connection allowance for requests signed with an AWS role.
• Submitting a consumer's test-run end state from your app with its own credentials, instead of from the portal.
• SDKs on a package registry (a TypeScript first slice is in the dev kit repository), and the skill dev kit.

Once you're signed in, What's next in the portal shows what RND is building. What has shipped is on the changelog.