Connector actions: presets, custom requests and testing
Add a Connector from Page actions → Add action to use a documented external service recipe. A Connector is one action, with one result, normal trigger timing and execution conditions.
Choose the recipe and authentication
Select a provider and a supported preset, then read its setup, input and result guidance in Builder. An On request entry is a request for a connection, not an executable recipe. A resolved support request does not itself configure or authorise the action.
Choose an existing compatible library connection for managed authentication, or select the named Properties and Secrets required by a manual recipe. Administrators can create shared values inline where offered. Keep credentials out of literal request values.
Connector settings reference
| Setting / property | Meaning |
|---|---|
type | platformApi; the stored action type for a Connector. |
providerId, definitionRevision | The documented provider and positive Govform recipe revision. This revision is separate from the external API version. Preserve it when editing unless deliberately upgrading. |
operationId | The exact preset identifier. Empty only for a recipe without presets or an awaiting-documentation request. |
connectionId | An existing compatible named connection in this library, where managed authentication is supported. |
providerInputs | Preset and connection inputs. Each has exactly one source: a library propertyRef, a secretRef, or a value. Dynamic values use a literal or Liquid wrapper as documented for that question. |
requestMode, customRequest | preset or custom. A custom request belongs to this action; returning to a preset replaces it. |
scenarioId, apiMockResponse | Documented simulation outcome and optional mock body. Blank mock content uses the recipe example. |
simulateInNonProduction | A JSON boolean. True explicitly simulates this action in QA/Staging; Production never simulates. New Connectors normally use a real QA connection. |
apiRequestTimeoutMs | Overall deadline in milliseconds; default 10 seconds, shared by authentication and the business request. |
For example, a dynamic preset record ID can be {"value":{"liquid":"{{ recordId }}"}}. A non-dynamic value remains directly inside value. Use the selected recipe's exact input keys and applicable authentication mode.
Custom request reference
Where offered, choose a method and a path starting with / relative to the approved API base. Put query parameters in mappings, not the path; do not include a host, fragment or backslash.
| Item | Accepted configuration |
|---|---|
| Method | GET, POST, PUT, PATCH, DELETE or HEAD. |
| Query / headers | At most 32 rows each. Unique names, with text values supplied as {"literal":"..."} or {"liquid":"..."}. Header names are unique without regard to case. |
| Body | Use mappings for JSON/form bodies or a text template with the selected body format. Up to 100 mappings; each row names a field and selects string, number, boolean, null or JSON. |
| Authentication / content type | Controlled by the selected connection and body format. Do not override authentication or Content-Type in custom headers. |
| Response format | Use a format supported by the recipe. Binary response support does not provide file-upload automation. |
Test in the correct environment
User view always simulates. Outcomes are examples, with no persistent external CRUD state, consent testing or retry simulation. New Connectors default to real QA execution where implemented and configured. An explicitly selected simulation, requested recipe or missing mandatory connection setup can simulate that action in QA/Staging; invalid settings or failures from a configured real connection remain errors. Production never falls back to mocks.
QA-pilot managed definitions execute live only in QA until verified. Design-only/requested entries are not live recipes. Test the actual deployed QA service and destination account before relying on consent, permissions, external writes or refresh.
Use results and failures
Later actions/templates can read actions.actionId.body, responseCode and the usual result/error data. Native bodies are not automatically normalised or fully paginated. A Connector has no automatic business-request retries or redirects. A redirect action placed before the Connector skips the remaining work.
See Save action results into form fields. File-provider recipes for metadata/folders do not imply binary uploads; service fees use Payment settings, and analytics tracking belongs in service settings.