Sources and Keys
Read a catalog or write an order to an external service: save its address and access key, then configure a reaction request.
در این صفحه
If your products are stored on your website, the bot can request the catalog from it, then send order details back. The service needs an API, an interface for programs to exchange data.
Under Sources, save a service connection, called a connector, with its API address and request settings. Under Keys, add the access credentials. In reactions, choose that connection in Query source or Write to source. For services with ready-made setup, check Integrations first.
Connectors (Sources)
Go to Sources → Connectors. Each connector has a Name, Type, Base URL, attached credentials, and headers:
- REST: any HTTP/JSON API.
- OzmaDB: an OzmaDB/FunDB instance; the base URL points to the REST API root of the instance, for example
https://ozma.example.com/api. Named views and insert/update operations have a dedicated action editor. - IMAP: no new IMAP connectors can be created. Saved ones stay in the list marked "not supported" and can be deleted as usual.
The Test button makes a test request and shows the status and latency (or error): a convenient way to confirm that the URL and key are correct.
Credentials (Keys)
Go to Keys → Credentials. Choose the access method required by the external service. Secrets are stored encrypted. Available methods:
- API key: key + header name (defaults to
Authorization). - Bearer token: token in the
Authorization: Bearerheader. - OAuth2 (password): Token URL, Client ID/Secret, username, password, scope.
- OAuth2 (refresh): Token URL, Client ID/Secret, refresh token, scope.
For OAuth2, the platform automatically fetches and caches tokens, refreshing them on expiry and on a 401 response; refresh token rotation is persisted. When editing, leaving a secret field empty means "do not change".
Reading and writing from reactions
- Query source (
ds_query): reads data through a connector intoctx: specify the path, a JSONPath to the array, and thectxkey for the result. For example, save a product list underproductsand pass it to dynamic buttons or a list loop. - Write to source (
ds_write): sends data (POST/PUT/DELETE) with a JSON body.
Request body, retries and response checks
The body of a POST/PUT request in Web request and Write to source can be built as a JSON tree: each leaf has its own type (string, number, boolean, JSON, null) and substitutions, so a number does not turn into a string and nested objects need no manual escaping. An order example:
{
"customer": { "name": "{{param.name}}", "phone": "{{user.phone}}" },
"amount": 4900,
"paid": false
}
Old text bodies keep working; the body mode switch shows the current one and does not lose what you entered.
Retries (retry_count) fire only on transport errors, 429 and 5xx; 4xx responses are never retried. GET, HEAD, OPTIONS, PUT and DELETE are retried, while POST and PATCH are retried only when you set an Idempotency-Key header yourself, which asserts that the receiving API deduplicates by that key. The platform always sends its own per-execution key too, but that alone does not enable POST or PATCH retries: otherwise the first failure is final, so an order is not created twice. The platform does not retry a write with an unknown outcome on its own for integration and CRM writes; the only exception is a web request with your own Idempotency-Key header.
Check a connector response. A REST connection has a Check the connection response block in the editor: it sends one GET through the saved connection with the given path and query (no substitutions) and shows the status, type and up to 64 KiB of the body. Nothing is written. If the response is JSON, you can take it as a sample for response parsing.
Response parsing is available on every action with external data: web request, query and write to a source, AI, Google Sheets, Google Drive, GetCourse and the CRM actions. The "Action result" source is the normalized action result, "Full response" is the body before processing. Rules apply atomically: if one of them fails, no variable is written.
For one-off requests without a saved connector, use the Web request action; for downloading page text, use Load URL (see Actions).
Named OzmaDB views and entities
Save an OzmaDB connection, then select it in Query source or Write to source. Choose OzmaDB mode. Existing HTTP requests keep their generic mode and parameters; you can switch explicitly. Switching keeps the HTTP fields and restores the Ozma configuration while the editor stays open.
Read: enter the static Schema and View names, or use Load catalog. Load more appends further catalog pages without changing the selected target. Load arguments and fields offers metadata suggestions. Add arguments by name, select a type, and enter a value. Catalog or metadata access can be denied independently of target access; manual target and value entry stays available.
A view is a saved query that can combine tables and calculate values. Select it for reading. To create or update a record, select a writable Entity table separately.
For a view usr.people_by_team with a numeric team_id argument, the action parameters are:
{
"connection": "ozma",
"ozma": {
"schema": "usr",
"view": "people_by_team",
"args": { "team_id": { "type": "number", "value": "42" } },
"limit": 100,
"offset": 0
},
"save_to_ctx": "people"
}
The result is an array of objects, such as [{"id":7,"name":"Alex"}], in ctx.people. Use it in a list loop or subsequent actions. The default page size is 100, maximum 500; offset is 0–100000. Define a stable order in the view when reading multiple pages.
Preview read sends a read-only request capped at 20 rows. Arguments must be literal values: event substitutions are not available in preview. To preview an action containing variables, temporarily replace them with test literals. Writes have no preview.
Write: enter Schema, Entity, and choose Insert or Update. Add typed fields; for update, provide a positive Record ID, including a substitution from a previous action:
{
"connection": "ozma",
"ozma": {
"schema": "usr",
"entity": "person",
"operation": "update",
"id": "{{ctx.person_id}}",
"fields": {
"name": { "type": "string", "value": "{{text}}" },
"active": { "type": "boolean", "value": "true" },
"details": { "type": "json", "value": "{\"tags\":[\"member\"]}" },
"note": { "type": "null", "value": "" }
}
},
"save_to_ctx": "saved_person"
}
The optional result key stores the transaction response; the first resulting ID is available as ctx.saved_person.results[0].id. Use insert without id to create a record. An insert with an empty fields object uses entity defaults; an update must include at least one field. Metadata suggestions omit computed fields and fields denied for the selected operation; OzmaDB performs the final permissions and constraints checks.
The supported types are string, number, boolean, json, and null. Their value is always a string in action JSON. Runtime applies the selected type after substitution. Number text preserves precision; string never turns into JSON syntax. json accepts valid JSON or an exact variable containing JSON. Invalid JSON is an error. Target names are static and cannot use substitutions.
If the response is lost after a write, the outcome may be unknown. Check OzmaDB before retrying. Automatic retries are unsafe without a confirmed deduplication contract. Explicit batch transactions remain available in HTTP request mode.
Extract any JSON value from a response
Open Parse response in either source action, including HTTP request mode. Enable extraction and choose Action result (after result_path or Ozma normalization) or Full response (before these transformations). The original result context key keeps working; extraction rules add explicit context keys.
After Preview read, rows automatically appear in the Response parser tree. Viewing the sample does not enable or change the parser. Select a field to create a named variable, or choose Collect from all records beside a field to save its values across rows. For example, selecting id across all records creates an ids list. New rules append to existing rules and names receive unique suffixes. Edit the proposed name or copy its token.
Whole response, First record and All IDs cover common selections; array presets require a matching sample. Created record ID creates a required created_id variable without a write request. A new parser uses the raw response; an existing configured parser keeps its source. Switch the source explicitly when needed. Manual samples and advanced JSONPath, mode and JSON-string decoding controls remain available. Large trees are shown only in part. Samples stay outside action parameters and scenario analysis. Check parsing processes the example locally without contacting the source.
For this nested response:
{
"results": [{ "id": 9007199254740993 }],
"groups": [
{ "members": [{ "name": "Alex", "active": false }] },
{ "members": [{ "name": "Sam", "active": true }] }
],
"extra": "{\"status\":{\"ready\":false}}"
}
Add the following top-level action configuration:
{
"response_parser": {
"source": "raw",
"decode_json_strings": true,
"rules": [
{ "path": "$.results[0].id", "save_to_ctx": "created_id", "mode": "value", "required": true },
{ "path": "$.groups[*].members[*].name", "save_to_ctx": "member_names", "mode": "list" },
{ "path": "/extra/status/ready", "save_to_ctx": "ready", "mode": "value" }
]
}
}
The rules preserve the exact created_id, produce ["Alex","Sam"], and retain boolean false. After a successful create request, use {{ctx.created_id}} as the Record ID of a following update. Strings, numbers, booleans, objects, arrays and null can all be selected, including an entire root $. Parse JSON inside strings is optional and also expands valid encoded JSON in the example tree.
Paths support .name, ["a.b"] with JSON escaping, positive and negative indexes ([0], [-1]), wildcards ([*], .*), slices ([1:3]) and RFC 6901 JSON Pointer. For a literal key a/b, use /a~1b; a literal ~ becomes ~0; / selects an empty key. Filters, expressions and scripts are not supported.
One value fails if the path has several matches; choose List of values for wildcards. A required rule fails when there is no match. Optional missing values become null, optional missing lists become []; a found null is distinguished from missing in preview. All rules are evaluated before assigning context values. Limits: 32 rules, 1024 bytes per path, 1 MiB input/output, 1000 matches per rule, plus bounded depth and work.
Ozma row IDs and reference labels
The read switches Include main record ID (mainId) and Include reference labels (pun) are optional. include_main_id: true retains the row's mainId; parse_pun: true keeps a cell with a label as { "id": 42, "data": "Label" }. A conflicting view column named mainId fails explicitly. These options do not change the full raw response.
You can switch the sample source between rows and the full response in Advanced parser settings. A configured raw parser automatically receives the matching raw sample. Changing the read target, arguments or flags clears the old automatic sample. The tree is available immediately; JSON sample and JSON response expand on demand. An oversized sample automatically reveals its error and editor.
In a following action, open Substitutions, search for created_id under From previous actions, and choose Insert beside {{ctx.created_id}} in Record ID or a typed argument. The token is inserted at the caret. Only preceding datasource outputs in the current action scope are suggested; reorder, rename and deletion update the list immediately.
Catalog search and object metadata
For a new Ozma read, Result context key appears before the object controls. Selecting Ozma proposes ozma_rows, with a suffix when a response-parser rule already uses that name. Existing names and manually cleared fields are preserved. Reading requires a result key; writing can leave it empty. A missing read key shows an inline correction beside the field.
Choose Load catalog to load 50 views for reading or 50 entities for writing. Open Object from catalog and search by schema.name across the full remote catalog. Search is a literal, case-insensitive substring: _ and % are ordinary characters. Load more continues the same search using the server's next offset. The selected object stays visible during other searches, and manual schema/name fields remain available if metadata access fails. Change the search or retry a failed page without re-entering the target.
Load arguments and fields shows required/optional view arguments, reference targets, column value types and the main entity. Additional metadata expands unknown fields and valid JSON-encoded objects or arrays. Numeric values retain their exact tokens. Large or deeply nested metadata shows a display-limit message; viewing metadata does not change the action or its response-parser rules.
Editing the complete Ozma flow
The Ozma connection form separates connection identity from the instance address and saved credential. Optional Additional HTTP headers stay collapsed when empty and open for configured headers. The connection check remains available beside its inline status; credentials remain selected by reference. Changing an Ozma draft clears the previous check status; a late reply for the old draft cannot validate the new settings.
In source actions, connection and mode align together, the result context key stays near the beginning, and the chosen schema.view or schema.entity is shown above the object controls. Manual schema/name fields are in Enter schema and name manually, collapsed for a configured target and revealed for missing/invalid names or an access failure. Arguments and fields use aligned name/type/value rows; required metadata suggestions remain visible. Types and substitutions expands the longer help.
Read settings groups pagination and optional ID/reference-label flags. Default settings start collapsed; configured non-default values and paging errors reveal the controls. Read preview displays normalized records in a table before JSON response. Empty reads explain what to check, exact values remain intact, and the normalized JSON and Full OzmaDB response stay available on demand.
The Ozma response parser groups quick selections, output variables, advanced selectors, the local example/tree and validation results. Existing HTTP actions retain their parser presentation and behavior. Additional metadata opens directly into its fields without an extra root disclosure.
What's next
- Actions: the
Query sourceandWrite to sourceactions. - Substitutions and formulas: using the result from
ctx. - Integrations: ready-made connectors for popular services.