Skip to content

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 ​

PropertyTypeMeaning
name requirednamesnake_case, never renamed once released
pattern ^[a-z][a-z0-9_]{0,62}$
label requiredlabelA label in Bahasa Indonesia (required) and optionally English.
label.id requiredstring
label.enstring
summarylabelOne sentence in plain words for the catalogue (contract 0036)
summary.id requiredstring
summary.enstring
categorysales · purchasing · stock · finance · tax · people · operations · messaging · payments · marketplace · otherCatalogue group (contract 0036)
iconstringA Remix icon name from the design system, e.g. store-2-line (contract 0036)
pattern ^[a-z0-9]+(-[a-z0-9]+)*$
version requiredstring
pattern ^[0-9]+\.[0-9]+\.[0-9]+$
vendorstring
docsstring
authobject
auth.type requiredtoken · oauth2 · basic · hmac · none
auth.token_urlstringoauth2: where the kernel refreshes the access token with refresh_token, client_id and client_secret (contract 0017 §8)
pattern ^https://
auth.fieldslist of object
auth.fields[].name requirednamesnake_case, never renamed once released
pattern ^[a-z][a-z0-9_]{0,62}$
auth.fields[].labellabelA label in Bahasa Indonesia (required) and optionally English.
auth.fields[].label.id requiredstring
auth.fields[].label.enstring
auth.fields[].helplabelA label in Bahasa Indonesia (required) and optionally English.
auth.fields[].help.id requiredstring
auth.fields[].help.enstring
auth.fields[].typestring
auth.fields[].requiredboolean
auth.fields[].secretbooleanStored with the secrets driver; never returned by the API
auth.fields[].generateboolean
auth.fields[].defaultCELA CEL expression (plus Rangka helpers)
auth.signobjectSign 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.alghmac-sha256 · sha256 · hmac-sha1 · sha1 · hmac-sha512 · sha512
auth.sign.key requiredstringauth field holding the HMAC key
auth.sign.encodinghex · base64
auth.sign.header requiredstringheader that carries the signature
auth.sign.prefixstringtext before the signature, e.g. HMACSHA256=
auth.sign.lines requiredlist of stringjoined with \n, no trailing newline
at least 1
auth.sign.headersmap of stringheaders sent with the request, each a line template (Request-Id: '{request.id}')
triggerslist of object
triggers[].name requirednamesnake_case, never renamed once released
pattern ^[a-z][a-z0-9_]{0,62}$
triggers[].labellabelA label in Bahasa Indonesia (required) and optionally English.
triggers[].label.id requiredstring
triggers[].label.enstring
triggers[].via requiredwebhook · poll
triggers[].everystringpoll: how often, 5m by default and 1m at least (contract 0002 §A.1)
pattern ^[0-9]+(s|m|h)$
triggers[].actionnamepoll: 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[].inputmap of stringpoll: the action's input, each value CEL over cursor (the stored cursor, null on the first poll) and settings
triggers[].eachobjectpoll: 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 requirednamethe action that lists the items, called without input
pattern ^[a-z][a-z0-9_]{0,62}$
triggers[].each.items requiredstringCEL over the list action's answer: the list of items
triggers[].each.as requirednamethe name an item has in input and emit (outlet)
pattern ^[a-z][a-z0-9_]{0,62}$
triggers[].each.key requiredstringCEL over the item: its stable id, which keys its cursor
triggers[].cursorstringpoll: CEL over the answer giving the next cursor (for example next_page_token); empty keeps the cursor
triggers[].nextstringpoll: 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[].verifyobject
triggers[].for_eachstring
triggers[].emitmap of string
actionslist of object
actions[].name requirednamesnake_case, never renamed once released
pattern ^[a-z][a-z0-9_]{0,62}$
actions[].labellabelA label in Bahasa Indonesia (required) and optionally English.
actions[].label.id requiredstring
actions[].label.enstring
actions[].request requiredobject
actions[].request.method requiredGET · POST · PUT · PATCH · DELETE
actions[].request.url requiredstring
actions[].request.headersmap of string
actions[].request.body
actions[].request.queryobject
actions[].inputlist of object
actions[].input[].name requirednamesnake_case, never renamed once released
pattern ^[a-z][a-z0-9_]{0,62}$
actions[].input[].labellabelA label in Bahasa Indonesia (required) and optionally English.
actions[].input[].label.id requiredstring
actions[].input[].label.enstring
actions[].input[].helplabelA label in Bahasa Indonesia (required) and optionally English.
actions[].input[].help.id requiredstring
actions[].input[].help.enstring
actions[].input[].typestring
actions[].input[].requiredboolean
actions[].input[].secretbooleanStored with the secrets driver; never returned by the API
actions[].input[].generateboolean
actions[].input[].defaultCELA CEL expression (plus Rangka helpers)
actions[].outputobject
actions[].retryobject
actions[].retry.maxinteger
min 0, max 25
actions[].retry.backofffixed · exponential
actions[].retry.onlist of integer
actions[].idempotencystring
actions[].allow_secret_inlist of queryLets 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)
settingslist of object
settings[].name requirednamesnake_case, never renamed once released
pattern ^[a-z][a-z0-9_]{0,62}$
settings[].labellabelA label in Bahasa Indonesia (required) and optionally English.
settings[].label.id requiredstring
settings[].label.enstring
settings[].helplabelA label in Bahasa Indonesia (required) and optionally English.
settings[].help.id requiredstring
settings[].help.enstring
settings[].typestring
settings[].requiredboolean
settings[].secretbooleanStored with the secrets driver; never returned by the API
settings[].generateboolean
settings[].defaultCELA CEL expression (plus Rangka helpers)
hostslist of stringHosts 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).
limitsobject
limits.ratestring
limits.notelabelA label in Bahasa Indonesia (required) and optionally English.
limits.note.id requiredstring
limits.note.enstring

setting ​

PropertyTypeMeaning
name requirednamesnake_case, never renamed once released
pattern ^[a-z][a-z0-9_]{0,62}$
labellabelA label in Bahasa Indonesia (required) and optionally English.
label.id requiredstring
label.enstring
helplabelA label in Bahasa Indonesia (required) and optionally English.
help.id requiredstring
help.enstring
typestring
requiredboolean
secretbooleanStored with the secrets driver; never returned by the API
generateboolean
defaultCELA 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].title

Generated from the schema by website/scripts/gen-reference.mjs. Edit the schema, not this page.

Rangka OS is source-available under the Elastic License 2.0 (ELv2). Free to self-host.