Appearance
Connectors
This page covers the screens for ready-made and provider-specific connectors: Connector Directory (the list of systems the platform aims to reach), Connector Catalog (ready-made HTTP connectors you can set up), External Connectors (finance, integration, calendar, LDAP and identity provider accounts), Payment Gateway (the finance tab of the same screen), and Email, SMS and WhatsApp (the one Communications screen, opened on three Explorer nodes). Readers are administrators and implementers who set up a connection to a provider. For how connectors differ from connections, see Overview.
Connector Directory
A search index of the systems the platform aims to connect to. It is a roadmap, not an installer: every entry is "Listed", which means planned. A system stays listed until a connector for it is built and tested. Any web service can already be reached today with the generic web call, through a connection and a flow, or with the "Generic REST call" in the Connector Catalog.
Where to find it
Studio Explorer > Workspace > Integrations > Connector Directory. Page key connector-directory.
Screen
A banner reads "N systems are on the roadmap. Listed means planned..." with a Browse templates button. The shipped directory holds 1870 systems in 73 categories. The left column offers All systems, then groups (for example "Communication and marketing", "Sales, CRM and commerce", "Finance, payments and tax", "People, recruitment and learning"), and a group opens its categories with their counts. The search box ("Search systems, for example Gmail or SAP") waits 300 milliseconds, then queries. Results are paged 50 at a time. Each result shows the system name, its category chips (selecting one filters by it), a green "Template available" chip when a template exists for that vendor, and a "Listed" chip.
Actions and API
The screen has no write actions. GET /api/v1/provider-connectors/directory?group=&category=&q=&page=&size= returns {items:[{name, categories}], total, page, size}; GET /api/v1/provider-connectors/directory/categories returns totalSystems, categories (title, group, listed) and groups. Permission integration.connector / view. No erp command.
Connector Catalog
Ready-made HTTP connectors to start from, and the connectors this tenant has set up. A connector is a stored description of one call to a provider: address, sign-in, request template and response mapping. Only what is honestly usable can be installed.
Where to find it
Studio Explorer > Workspace > Integrations > Connector Catalog. Page key connector-catalog.
Key concepts
| Status | Meaning |
|---|---|
ready | Verified by the platform's own tests. |
untested | A starting template not yet run against the real service; try it before relying on it. |
planned | Not installable. |
The shipped catalog has 14 entries: ready - Generic REST call (generic-rest-post); untested - Slack incoming webhook, Microsoft Teams incoming webhook, SendGrid email, Razorpay order, Stripe checkout, Stripe refund; planned - Microsoft Entra ID, Okta, Google Workspace, WhatsApp Cloud, Salesforce, SAP OData, ADP.
Screen
Chips: My connectors, Ready, Untested, Planned. The My connectors grid shows Connector (name and key), Address (base address and path), Sign-in and Status (On, or "Off (review first)"). Below, cards grouped by category (Enterprise, Communication, Finance, Identity, HR ecosystem) with a status chip, a description and Use this for non-planned entries.
Set up dialog
| Field | Type | Default | Required | Description |
|---|---|---|---|---|
| Name | text | the entry's name | Yes | The key is derived from it. |
| Address | text | the entry's usual address | Yes unless the entry has one | "Must be a public https address." |
| User name | text | empty | When the sign-in is basic | Label comes from the entry. |
| Secret | password | empty | When the sign-in is not none | "Stored encrypted on the server and never shown again." |
An untested entry shows "This template has not been run against the real service. Use Try after saving." Save connector stores the secret as the tenant secret connector.KEY and saves the definition referring to it as secret:connector.KEY. The connector is saved switched on from this dialog.
Actions
| Action | Effect | API |
|---|---|---|
| Switch on, Switch off | Toggles the connector. A connector drafted by the assistant starts off until a person turns it on. | POST /api/v1/provider-connectors/definitions/integration/{key}/active |
| Try | Opens a form with one field per placeholder found in the request template and makes one real call. Result "Worked (HTTP 200) - reference X - status Y" or the error. Enabled only when on. | POST .../definitions/integration/{key}/invoke with {"fieldValues":{...} } |
| Delete | Removes the connector. | DELETE .../definitions/integration/{key} |
| Export, Import | Downloads or previews/applies the tenant's integration bundle. See Move between environments. | GET, POST /api/v1/integration/bundle... |
Connector definition
Stored in external_provider_definition with domain integration. Schema connector-definition (see connector-definition).
| Field | Allowed values | Description |
|---|---|---|
domain, providerKey, name, connectorKind | DIRECT or HTTP | Required. DIRECT makes no outbound call. |
baseUrl, requestPath | HTTP only. A missing base URL fails: provider "X" is connectorKind=HTTP but has no baseUrl configured. | |
httpMethod | POST, PUT | Default POST. |
requestEncoding | JSON, FORM | Default JSON. FORM is application/x-www-form-urlencoded, for example Stripe. |
authType | NONE, API_KEY_HEADER, BEARER_TOKEN, BASIC | |
authConfig | object | headerName, username, and secretRef of the form secret:connector.NAME (tenant secret) or env:VAR_NAME. The literal secret is never stored in the row. |
requestTemplate | object | Any JSON; string values may carry placeholders written with double curly braces around a field name, filled from the caller's field map. |
responseMapping | object | providerReferencePath, statusPath, signingUrlPath: dot paths into the provider's JSON answer. |
statusMapping | object | Provider status to the caller's status. |
completionMode | MANUAL_CONFIRM, POLL, WEBHOOK | Only MANUAL_CONFIRM is operational; POLL and WEBHOOK are accepted but no poll sweep or receiver exists for them. |
active, isDefault, notes, ownerPlugin |
json
{
"domain": "integration",
"providerKey": "slack-alerts",
"name": "Slack alerts",
"connectorKind": "HTTP",
"active": true,
"baseUrl": "https://hooks.slack.com",
"requestPath": "/services/T000/B000/XXXX",
"httpMethod": "POST",
"authType": "NONE",
"authConfig": {},
"requestTemplate": { "text": "{{message}}" },
"responseMapping": { "providerReferencePath": "ts", "statusPath": "ok" },
"statusMapping": {},
"completionMode": "MANUAL_CONFIRM"
}Behaviour and limits
The call has a 10 second connect timeout and a 20 second request timeout, does not follow redirects, and accepts an answer of at most 2 MB ("provider X answered with more than 2 MB, which is not accepted"). A non-2xx answer fails as provider "X" returned HTTP N. A secret that does not exist fails as the stored secret "X" does not exist. Addresses must be https and public.
Permissions
integration.connector: view (catalog, list), manage (save secrets, switch, and, when the operator has enforcement on, save and delete definitions). Run from outside through POST /api/v1/integration/run with integration.run / execute; see REST APIs.
API and CLI
| Purpose | Request |
|---|---|
| Catalog | GET /api/v1/provider-connectors/catalog |
| List | GET /api/v1/provider-connectors/definitions |
| Save | PUT /api/v1/provider-connectors/definitions/{domain}/{providerKey} |
| Secret | PUT /api/v1/provider-connectors/secrets/{name} with {"value":"..."}; names are lower-case letters, digits and dashes |
| Contract connectors | GET /api/v1/integration/connectors, GET /api/v1/integration/connectors/{key} (read-only list of the shipped connector contracts: Slack, Teams webhook, SendGrid, HubSpot, Jira and the web call) |
| Command | Purpose |
|---|---|
erp connector catalog | The templates and their status. |
erp connector validate <file> | Schema-check a definition. |
erp connector create <file> | Validate and save. |
erp connector list [--domain <domain>] | List. |
erp connector secret set <name> [--from-file <path>] | Store a credential; the value comes from a file or stdin, never an argument. |
erp connector test <domain> <providerKey> [--body <json-string-or-@file>] | Invoke the definition. |
erp integration run connector <key> [--input ...] | Run through the application endpoint. |
Errors and troubleshooting
| Message | Cause |
|---|---|
| "a secret needs a lower-case name and a value" | Bad secret name or empty value. |
| "requestEncoding must be JSON or FORM" | |
| "could not save provider definition: ..." | Validation failed. |
| "provider X is inactive" (409) | Switched off. |
| "malformed request_template_json: ..." | The stored template is not valid JSON. |
External Connectors
One screen with five tabs for provider accounts of the built-in connector families: Finance, Integration, Calendar, LDAP and Identity. An account holds the credentials for a provider; credentials are encrypted at rest, write-only, and "leave blank to keep the current ones" when editing.
Where to find it
Studio Explorer > Workspace > Integrations > External Connectors. Page key connectors; the node opens on the Finance tab. Payment Gateway opens the same screen on the Finance tab; GraphQL opens it on Integration (see GraphQL).
Tabs and credential fields
| Tab | Account list | Connector types | Credential fields |
|---|---|---|---|
| Finance | Provider Accounts with Name, Family, Connector Type, Status; a "No credentials" chip when none are stored | PAYMENT: RAZORPAY, STRIPE, PAYPAL. BANKING: OPEN_BANKING_GENERIC. GOVERNMENT: IN_GST_EINVOICE, IN_EWAY_BILL | See the Payment Gateway section and the table below. |
| Integration | GraphQL, SOAP and SFTP connections | See GraphQL. | |
| Calendar | External Calendar Sync Accounts | GOOGLE_CALENDAR, MS_GRAPH_CALENDAR | Google: Access Token, Calendar ID (default primary), API Base URL. Microsoft Graph: Access Token, User ID / UPN, API Base URL. |
| LDAP | LDAP / Active Directory Accounts | LDAP URL (for example ldap://host:389), Service Bind DN, Service Bind Password, User Base DN, User Search Filter (for example (uid={0})), Username Attribute (for example uid). | |
| Identity | Identity Provisioning Accounts | GOOGLE_WORKSPACE, MICROSOFT_ENTRA_ID | Google Workspace: Access Token, Customer ID (default my_customer), API Base URL. Entra ID: Access Token, API Base URL. |
Every account dialog has Account Name (required), Status (ACTIVE or INACTIVE) and Priority where shown. Calendar tokens are pre-obtained access tokens: neither connector performs the OAuth consent flow. Calendar accounts push a native calendar event from the event's own "Sync to..." action on the Calendar page, not from this screen.
Row actions on LDAP accounts (expand the row): Test Connection (Connected or Failed), List Users, Find User, Authenticate (username and password; Authenticated or Rejected). Authentication looks up the user's DN with the service bind and then attempts a new bind with the person's password; the directory verifies the password. Per the integration contract note, an LDAP account is not wired into the login page in this release. Identity accounts offer Test Connection and List Users (email, display name, suspended).
Permissions and API
| Family | Base path | Permission |
|---|---|---|
| Finance | /api/v1/finance/provider-accounts (GET, POST, PUT /{id}, DELETE /{id}) | finance: view, manage |
| Calendar | /api/v1/authoring/calendar/sync-accounts and /api/v1/authoring/calendar/events/{eventId}/sync/{syncAccountId} | none enforced by the calendar module |
| LDAP | /api/v1/security/ldap-accounts with POST /{id}/test-connection, GET /{id}/users, GET /{id}/users/{username}, POST /{id}/authenticate | |
| Identity | /api/v1/security/identity-accounts with GET /connector-types, POST /{id}/test-connection, GET /{id}/users |
Not available in this release: dedicated Studio forms beyond those above for other government or banking connectors.
Payment Gateway
Provider accounts for payment, banking and government e-invoicing connectors. The node opens External Connectors on the Finance tab.
Where to find it
Studio Explorer > Workspace > Integrations > Payment Gateway. Page key payment-gateway.
New Finance Provider Account dialog
| Field | Type | Default | Required | Description |
|---|---|---|---|---|
| Family | select | PAYMENT | Yes | PAYMENT, BANKING or GOVERNMENT. Disabled when editing. |
| Connector Type | select | RAZORPAY | Yes | Depends on the family. Disabled when editing. |
| Account Name | text | empty | Yes | |
| Priority | number | 1 | No | |
| Credentials | per type | empty | Per type | Left blank on edit to keep the current ones. |
| Connector type | Credential fields |
|---|---|
RAZORPAY | Key ID, Key Secret, Webhook Secret (optional), API Base URL (optional) |
STRIPE | Secret Key, Webhook Signing Secret (optional), API Base URL (optional) |
PAYPAL | Client ID, Client Secret, Webhook ID (optional), API Base URL (optional) |
OPEN_BANKING_GENERIC | OAuth2 Token URL, Client ID, Client Secret, API Base URL, and optional endpoint templates for Balance, Statement, Payment and Payment Status |
IN_GST_EINVOICE | Username, Password, Client ID, Client Secret, GSTIN, Auth URL, IRN Generate URL |
IN_EWAY_BILL | Username, Password, Client ID, Client Secret, GSTIN, Auth URL, Generate E-Way Bill URL |
Row actions (expand an account)
| Family | Actions | API |
|---|---|---|
| PAYMENT | Create Link (Amount default 100.00, Currency INR, Description, Reference ID) shows the payment address and reference; Check payment status by reference | POST /api/v1/finance/payments/{accountId}/links, GET .../{accountId}/status?reference= |
| BANKING | Bank Account ID, Get Balance (available and ledger balance), Get Statement (From and To dates, listing transaction, amount, type, reference) | GET /api/v1/finance/banking/{accountId}/balance, .../statement; payments POST .../{accountId}/payments, GET .../payments/status |
| GOVERNMENT | A connector-specific JSON payload and Submit | POST /api/v1/finance/government/{accountId}/submit |
A panel Bank Reconciliation (standalone - no live bank account needed) takes bank transactions (a JSON array with transactionId, valueDate, amount, type, description, reference) and ERP open items (an object of reference to amount) and reports "Matched N, unmatched bank N, unmatched ERP N". It matches by reference first, then by amount only when exactly one open item ties; it never guesses when ambiguous. POST /api/v1/finance/banking/reconcile.
Inbound payment webhooks
POST /api/v1/finance/payments/webhooks/{tenantId}/{providerAccountId} receives the provider's callback. The signature is verified through the connector (Razorpay HMAC, Stripe signature with timestamp tolerance, PayPal verification call). A bad signature returns 401 "signature verification failed" and is audited; a connector without inbound support returns 501. A valid call returns {"status":"PROCESSED","event":{...} }.
Permissions
Resource finance: view (lists, status, balance, statement, reconcile), manage (accounts), send (create links, initiate bank payments, submit government documents). The GST connectors implement the National Informatics Centre session-key handshake; endpoint paths and field names must be confirmed against current provider documentation before use against a real GSTIN.
Errors
Messages follow actor "X" lacks finance.ACTION permission. Provider failures return the provider's error as Failed: ... in the screen.
Email
Email, SMS and WhatsApp share one Communications screen (page key communications); the three Explorer nodes open it. This section describes the whole screen and the email specifics. SMS and WhatsApp follow with only what differs.
Where to find it
Studio Explorer > Workspace > Integrations > Email (or SMS, or WhatsApp).
Key concepts
| Term | Meaning |
|---|---|
| Channel | A delivery medium: EMAIL, SMS, WHATSAPP, PUSH, IN_APP, SLACK, MS_TEAMS, GOOGLE_CHAT. |
| Provider | A built-in connector for a channel: SMTP (connector EMAIL_SMTP), GENERIC_SMS (SMS_GENERIC, Twilio-compatible), WHATSAPP_CLOUD_API, FCM_PUSH (PUSH_FCM), IN_APP, SLACK_WEBHOOK, TEAMS_WEBHOOK, GOOGLE_CHAT_WEBHOOK. |
| Provider account | Credentials and priority for a provider in this tenant. |
| Template | A named message with versions per language. |
| Routing rule | Chooses the provider account for a channel, optionally by country. |
| Rate limit | A per-minute and per-day cap on a channel or an account. |
| Category | SECURITY, TRANSACTIONAL, SYSTEM, WORKFLOW, MARKETING, REMINDER. People can opt out of categories per channel in My Preferences. |
Tabs
| Tab | Content |
|---|---|
| Dashboard | The channel catalog as chips. Above all tabs: Pending, Sent, Delivered, Failed, Today. |
| Messages | Filters by status and channel; grid Subject, Channel, Priority, Status, Created, 20 per page. Selecting a row opens the detail drawer with Recipients (address, type, status), Delivery Attempts (number, status, error code, start) and, for a FAILED message, Retry. |
| Templates | Grid Code, Channel, Category, Status. New Template: Code, Channel, Category. Selecting a row opens versions: New Version (Language default en, Subject, Body (text) with placeholders, Body (HTML, optional)), Activate a version. |
| Providers & Accounts | New Provider Account: provider select ("Select a provider (connector)"), Account Name, Priority (default 1), Active switch and the credential fields of the provider. Row actions: Test connection (Healthy or Unhealthy), Edit, Delete. |
| Routing & Limits | Routing Rules: channel, optional Country Code, Provider Account, Priority, Add Rule ("No routing rules - sends use provider priority by default."). Rate Limits: channel, account or "Channel-wide (all accounts)", Limit / minute, Limit / day, Add Limit, with Current Usage ("No rate limits configured - sends are unrestricted."). |
| Conversations | Two-way threads, filter All, Open, Closed. A thread opens in a drawer with sent and received messages, a reply box (Enter sends) and Close conversation. A conversation opens automatically the first time a counterparty replies through a webhook-enabled channel. |
| Webhook Events | An audit trail of every inbound provider call: connector, event type, signature (Verified or Rejected), processing (RECEIVED, PROCESSED, IGNORED, REJECTED, ERROR) and the raw payload. |
Template placeholders are written with double curly braces around a name, as in this version body:
text
Hello {{name}}, your order {{orderNo}} has shipped.Message statuses
CREATED, QUEUED, PROCESSING, SENT, DELIVERED, READ, RETRYING, FAILED, CANCELLED, EXPIRED. Priorities: URGENT, HIGH, NORMAL, LOW. Recipient types: USER, EMPLOYEE, CUSTOMER, EXTERNAL. A delivery attempt is SENT, DELIVERED, READ or FAILED. Retry is only offered when the message is FAILED, and re-queues the failed job through the job engine.
Email provider account fields
| Field | Type | Description |
|---|---|---|
| SMTP Host | text | |
| Port | number | |
| Username | text | |
| Password | password | |
| From Address | text |
Email supports text, HTML, attachments, cc, bcc and reply-to.
Sending a message
http
POST /api/v1/communications/messages
X-Tenant-Id: 1
Content-Type: application/json
{
"channel": "EMAIL",
"templateCode": "order-shipped",
"language": "en",
"category": "TRANSACTIONAL",
"priority": "NORMAL",
"data": { "name": "Ada", "orderNo": "SO-1001" },
"recipients": [ { "recipientType": "EXTERNAL", "address": "ada@example.com" } ],
"idempotencyKey": "order-shipped-SO-1001"
}Other request fields: pluginId, eventId, subject, scheduledAt, preferredProviderAccountId, attachments (fileId or externalUrl, fileName, mimeType, sizeBytes) and regionId. The response is {"messageId":N,"status":"...","deduplicated":false}; a repeated idempotencyKey returns the first message with deduplicated true. Errors: 400 "channel is required", 400 "at least one recipient is required", 400 "data must be JSON-serializable: ...".
Permissions
Resource communication: view, manage (retry, conversation close), manage-providers (accounts), manage-templates, manage-routing (rules and limits), and for sending send.<channel> such as send.email, with send as the blanket fallback. Without a grant the call returns 403 actor "X" lacks communication.send permission for EMAIL.
API
| Purpose | Request |
|---|---|
| Catalog | GET /api/v1/communications/channels, GET .../providers |
| Accounts | GET, POST, PUT /{id}, DELETE /{id} on .../provider-accounts; POST .../provider-accounts/{id}/test-connection |
| Messages | GET .../messages?status=&channel=&pageIndex=&pageSize=, GET .../messages/{id}, GET .../messages/monitoring, POST .../messages/{id}/retry?executionId=N |
| Templates | GET, POST .../templates; PUT .../templates/{id}/status; GET, POST .../templates/{id}/versions; POST .../templates/{id}/versions/{versionId}/activate |
| Routing and limits | GET, POST .../routing-rules, PUT .../routing-rules/{id}/status, DELETE; GET, POST .../rate-limits, PUT, DELETE |
| Conversations | GET .../conversations, GET .../conversations/{id}/messages, POST .../conversations/{id}/reply, POST .../conversations/{id}/close |
| Inbound | POST /api/v1/communications/webhooks/{tenantId}/{providerAccountId}; log at GET .../webhook-events |
Campaigns (/api/v1/communications/campaigns), analytics, in-app feed and preferences are served by the same module; their screens are Engagement Studio and My Preferences, not this one. There is no erp command for communications.
Errors and troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Account shows Credentials "Not set" | Created without credential fields. | Edit the account and fill the fields. |
| Test connection shows Unhealthy | Wrong host, port or credentials. | Correct the credentials. |
| "message N is not FAILED (status=X)" (409) | Retry on a message that is not failed. | |
| Webhook event Rejected | The inbound signature did not verify. | Check the app secret or signing secret on the account. |
| Messages stay QUEUED | No active provider account for the channel, or a rate limit is reached. | Add an account or raise the limit. |
SMS
SMS uses the same screen as Email (page key communications).
| Item | Value |
|---|---|
| Provider | GENERIC_SMS, connector SMS_GENERIC, a Twilio-compatible API. |
| Account fields | Account SID, Auth Token (password), From Number, API Base URL (optional). |
| Capabilities | Text, one-time passwords, delivery reports. |
| Inbound | A webhook-enabled account lets replies open a conversation; calls are recorded under Webhook Events. |
| Routing | Add a routing rule with a Country Code to send to different accounts per country. |
Send with "channel":"SMS" and a recipient address that is a phone number. Permission communication.send.sms.
WhatsApp
WhatsApp uses the same screen as Email.
| Item | Value |
|---|---|
| Provider | WHATSAPP_CLOUD_API, connector WHATSAPP_CLOUD_API. |
| Account fields | Access Token (password), Phone Number ID, API Base URL (optional), App Secret (for inbound webhook signature verification). |
| Capabilities | Text, templates, images, documents. |
| Inbound | Register https://HOST/api/v1/communications/webhooks/TENANT_ID/ACCOUNT_ID as the callback in the provider console; the app secret verifies each call. Replies appear under Conversations. |
Send with "channel":"WHATSAPP". Permission communication.send.whatsapp. The Connector Catalog lists a WhatsApp Cloud connector as planned; WhatsApp messaging itself is delivered through this Communications screen.
Related
Overview, Connections, APIs, Move between environments, Connect to another system, connector-definition.