connector.rk
Layer 3: an integration (rangka-connectors/<name>/connector.rk): how to authenticate, the events it triggers and the actions flows can call.
Lives in <connector>/connector.rk (rangka-connectors) · Schema connector.json (source) · first line: # yaml-language-server: $schema=https://rangka-os.github.io/rangka-os/schema/0.5/connector.json
Properties
| Property | Type | Meaning |
|---|---|---|
name required | name | snake_case, never renamed once released pattern ^[a-z][a-z0-9_]{0,62}$ |
label required | label | A label in Bahasa Indonesia (required) and optionally English. |
label.id required | string | |
label.en | string | |
summary | label | One sentence in plain words for the catalogue (contract 0036) |
summary.id required | string | |
summary.en | string | |
category | sales · purchasing · stock · finance · tax · people · operations · messaging · payments · marketplace · other | Catalogue group (contract 0036) |
icon | string | A Remix icon name from the design system, e.g. store-2-line (contract 0036) pattern ^[a-z0-9]+(-[a-z0-9]+)*$ |
version required | string | pattern ^[0-9]+\.[0-9]+\.[0-9]+$ |
vendor | string | |
docs | string | |
auth | object | |
auth.type required | token · oauth2 · basic · hmac · none | |
auth.token_url | string | oauth2: where the kernel refreshes the access token with refresh_token, client_id and client_secret (contract 0017 §8) pattern ^https:// |
auth.fields | list of object | |
auth.fields[].name required | name | snake_case, never renamed once released pattern ^[a-z][a-z0-9_]{0,62}$ |
auth.fields[].label | label | A label in Bahasa Indonesia (required) and optionally English. |
auth.fields[].label.id required | string | |
auth.fields[].label.en | string | |
auth.fields[].help | label | A label in Bahasa Indonesia (required) and optionally English. |
auth.fields[].help.id required | string | |
auth.fields[].help.en | string | |
auth.fields[].type | string | |
auth.fields[].required | boolean | |
auth.fields[].secret | boolean | Stored with the secrets driver; never returned by the API |
auth.fields[].generate | boolean | |
auth.fields[].default | CEL | A CEL expression (plus Rangka helpers) |
auth.sign | object | Sign every request with an HMAC over canonical lines (DOKU Non-SNAP; contract 0002, refinement of 11 Nov 2026). Placeholders: {auth.x}, {settings.x}, {request.id} (UUID v4), {request.timestamp} (UTC), {request.method}, {request.target} (path), {request.digest} (base64 SHA-256 of the body; its line is left out without a body) |
auth.sign.alg | hmac-sha256 · sha256 · hmac-sha1 · sha1 · hmac-sha512 · sha512 | |
auth.sign.key required | string | auth field holding the HMAC key |
auth.sign.encoding | hex · base64 | |
auth.sign.header required | string | header that carries the signature |
auth.sign.prefix | string | text before the signature, e.g. HMACSHA256= |
auth.sign.lines required | list of string | joined with \n, no trailing newline at least 1 |
auth.sign.headers | map of string | headers sent with the request, each a line template (Request-Id: '{request.id}') |
triggers | list of object | |
triggers[].name required | name | snake_case, never renamed once released pattern ^[a-z][a-z0-9_]{0,62}$ |
triggers[].label | label | A label in Bahasa Indonesia (required) and optionally English. |
triggers[].label.id required | string | |
triggers[].label.en | string | |
triggers[].via required | webhook · poll | |
triggers[].every | string | poll: how often, 5m by default and 1m at least (contract 0002 §A.1) pattern ^[0-9]+(s|m|h)$ |
triggers[].action | name | poll: the action of this connector sent on each poll; its answer is read like a webhook body pattern ^[a-z][a-z0-9_]{0,62}$ |
triggers[].input | map of string | poll: the action's input, each value CEL over cursor (the stored cursor, null on the first poll) and settings |
triggers[].each | object | poll: send the action once per item (an outlet): the list action is called first on every poll, and each item has its own cursor |
triggers[].each.action required | name | the action that lists the items, called without input pattern ^[a-z][a-z0-9_]{0,62}$ |
triggers[].each.items required | string | CEL over the list action's answer: the list of items |
triggers[].each.as required | name | the name an item has in input and emit (outlet) pattern ^[a-z][a-z0-9_]{0,62}$ |
triggers[].each.key required | string | CEL over the item: its stable id, which keys its cursor |
triggers[].cursor | string | poll: CEL over the answer giving the next cursor (for example next_page_token); empty keeps the cursor |
triggers[].next | string | poll: CEL over the answer giving the next page (a next_url or /path on the action's host, or a page value bound as page for input:); null or empty stops. At most 50 pages per poll; a cut poll keeps its cursor |
triggers[].verify | object | |
triggers[].for_each | string | |
triggers[].emit | map of string | |
actions | list of object | |
actions[].name required | name | snake_case, never renamed once released pattern ^[a-z][a-z0-9_]{0,62}$ |
actions[].label | label | A label in Bahasa Indonesia (required) and optionally English. |
actions[].label.id required | string | |
actions[].label.en | string | |
actions[].request required | object | |
actions[].request.method required | GET · POST · PUT · PATCH · DELETE | |
actions[].request.url required | string | |
actions[].request.headers | map of string | |
actions[].request.body | ||
actions[].request.query | object | |
actions[].input | list of object | |
actions[].input[].name required | name | snake_case, never renamed once released pattern ^[a-z][a-z0-9_]{0,62}$ |
actions[].input[].label | label | A label in Bahasa Indonesia (required) and optionally English. |
actions[].input[].label.id required | string | |
actions[].input[].label.en | string | |
actions[].input[].help | label | A label in Bahasa Indonesia (required) and optionally English. |
actions[].input[].help.id required | string | |
actions[].input[].help.en | string | |
actions[].input[].type | string | |
actions[].input[].required | boolean | |
actions[].input[].secret | boolean | Stored with the secrets driver; never returned by the API |
actions[].input[].generate | boolean | |
actions[].input[].default | CEL | A CEL expression (plus Rangka helpers) |
actions[].output | object | |
actions[].retry | object | |
actions[].retry.max | integer | min 0, max 25 |
actions[].retry.backoff | fixed · exponential | |
actions[].retry.on | list of integer | |
actions[].idempotency | string | |
actions[].allow_secret_in | list of query | Lets this action send a secret in the query string for an API that takes its key there; the validator reports a warning so it stays visible in review (contract 0017 §5) |
settings | list of object | |
settings[].name required | name | snake_case, never renamed once released pattern ^[a-z][a-z0-9_]{0,62}$ |
settings[].label | label | A label in Bahasa Indonesia (required) and optionally English. |
settings[].label.id required | string | |
settings[].label.en | string | |
settings[].help | label | A label in Bahasa Indonesia (required) and optionally English. |
settings[].help.id required | string | |
settings[].help.en | string | |
settings[].type | string | |
settings[].required | boolean | |
settings[].secret | boolean | Stored with the secrets driver; never returned by the API |
settings[].generate | boolean | |
settings[].default | CEL | A CEL expression (plus Rangka helpers) |
hosts | list of string | Hosts the connector talks to, e.g. [graph.facebook.com]. An action that carries a secret may only send it to these hosts (contract 0017 §5). |
limits | object | |
limits.rate | string | |
limits.note | label | A label in Bahasa Indonesia (required) and optionally English. |
limits.note.id required | string | |
limits.note.en | string |
setting
| Property | Type | Meaning |
|---|---|---|
name required | name | snake_case, never renamed once released pattern ^[a-z][a-z0-9_]{0,62}$ |
label | label | A label in Bahasa Indonesia (required) and optionally English. |
label.id required | string | |
label.en | string | |
help | label | A label in Bahasa Indonesia (required) and optionally English. |
help.id required | string | |
help.en | string | |
type | string | |
required | boolean | |
secret | boolean | Stored with the secrets driver; never returned by the API |
generate | boolean | |
default | CEL | A CEL expression (plus Rangka helpers) |
Example
From rangka-connectors/whatsapp_business/connector.rk (first 60 lines):
yaml
# yaml-language-server: $schema=https://rangka-os.github.io/rangka-os/schema/0.5/connector.json
name: whatsapp_business
label: {id: WhatsApp Business}
summary:
id: Terima pesan pelanggan dan kirim pesan template lewat WhatsApp Business.
en: Receive customer messages and send template messages through WhatsApp Business.
category: messaging
icon: whatsapp-line
version: 1.0.0
vendor: Meta WhatsApp Cloud API
docs: https://developers.facebook.com/docs/whatsapp/cloud-api
auth:
type: token
fields:
- name: access_token
label: {id: Access token}
secret: true
- name: phone_number_id
label: {id: Phone number ID}
- name: app_secret
label: {id: App secret}
secret: true
help: {id: Dipakai untuk memeriksa tanda tangan webhook}
- name: verify_token
label: {id: Verify token}
secret: true
generate: true
triggers:
- name: message_received
label: {id: Pesan masuk}
via: webhook
verify:
challenge: hub.verify_token == auth.verify_token
signature:
header: X-Hub-Signature-256
alg: hmac-sha256
key: auth.app_secret
for_each: entry[].changes[].value.messages[]
emit:
message_id: item.id
from: item.from
text: item.text.body
profile_name: value.contacts[0].profile.name
at: item.timestamp
# Delivery receipts of messages we sent (sent, delivered, read, failed), so a reminder can be logged as delivered.
- name: message_status
label: {id: Status pesan terkirim}
via: webhook
verify:
signature:
header: X-Hub-Signature-256
alg: hmac-sha256
key: auth.app_secret
for_each: entry[].changes[].value.statuses[]
emit:
message_id: item.id
status: item.status
to: item.recipient_id
at: item.timestamp
error: item.errors[0].titleGenerated from the schema by website/scripts/gen-reference.mjs. Edit the schema, not this page.