How Integrations Work
Every Oikapi integration is built from the same handful of building blocks. Understanding them once means each integration’s own page only has to document what’s unique to that service.
The building blocks
Section titled “The building blocks”Integrations are not a separate engine — they compose existing platform features:
- HTTP Client — outbound calls to a third-party API, made from business rules.
- Business Rules — the logic that decides when to call out and what to do with what comes back.
- Workflows — multi-step, approval-aware sequences for anything beyond a single call.
- Tables & Fields — where synced external data lives inside Oikapi.
- Public Forms and webhook endpoints — inbound endpoints that let an external service push events to Oikapi.
- Credentials — encrypted storage for the API keys and tokens an integration needs. Secrets are injected into outbound calls and are never exposed to rule code.
Core concepts
Section titled “Core concepts”Connection
Section titled “Connection”A connection is the authenticated link between Oikapi and one account on a third-party service. It holds the credentials (an API key, an OAuth token, or a connection secret) and any account-specific settings (a workspace, a subdomain, a default channel). You configure a connection once; every action, trigger, and sync for that integration uses it.
Action
Section titled “Action”An action is something Oikapi does in the third-party service — create an invoice, post a message, open a ticket, deactivate a user. Actions are invoked from Business Rules and Workflows and run with the connection’s credentials. Because they cause external side effects, actions are typically gated behind permissions and, where appropriate, an approval step. First-party action handlers already ship for several providers (see the Integrations overview); a generic HTTP action covers any other API.
Trigger
Section titled “Trigger”A trigger is an external event that drives Oikapi — a payment succeeded, a ticket was updated, a form was submitted. Triggers arrive either as inbound webhooks (the service pushes the event to an Oikapi endpoint) or by polling (a scheduled poll trigger periodically asks the service what changed and detects new or changed items by hash or ID). Either way, the trigger fires a business rule or workflow, just like an internal record change would.
A sync keeps a set of external records mirrored into Oikapi tables — customers, contacts, devices, repositories. Syncs are usually incremental (only what changed since last time) and pull data into Oikapi from an external API or provider. Synced data behaves like any other Oikapi data: it’s searchable, governed by permissions, and available to rules and Iris.
Security and governance
Section titled “Security and governance”- Credentials are encrypted at rest and injected into outbound requests at call time. Rule code can use a connection without ever seeing the raw secret.
- Managing connections is permission-gated. Only users with the appropriate role can create, edit, or remove an integration’s connection.
- Actions respect the same permission and audit model as any other write in Oikapi. Every integration-driven change is attributable and recorded in the audit log.
- External side effects can’t be undone by soft delete. A sent message or a created external record lives in the third-party system. Prefer approval gates for high-impact actions.
Glossary
Section titled “Glossary”| Term | Meaning |
|---|---|
| Connection | The authenticated, credentialed link to one third-party account |
| Action | An operation Oikapi performs in the third-party service |
| Trigger | An external event that fires an Oikapi rule or workflow |
| Sync | Ongoing mirroring of external records into Oikapi tables |
| Webhook | An inbound HTTP endpoint a service calls to deliver an event |
Documenting a new integration
Section titled “Documenting a new integration”Every integration page follows the same template so readers always know where to look. If you’re
adding an integration, copy the skeleton in
src/content/docs/integrations/_template.md and fill in each section. The fixed headings are:
Overview, Prerequisites, Connection setup, Data objects & sync, Actions & triggers, Limits &
considerations, and Troubleshooting & uninstall.