Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.
Preserved from source baseline
d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.
Connectors
Start with the four objects that are easy to confuse
A connector supplies a transport/executor and an operation contract. A connected system binds an actual service/account configuration under its own permission and version lifecycle. An Integration is a consultant-authored, versioned business operation using a connected system. An execution record is evidence of one attempt, not a reusable connector definition. Choose which object you are working with before changing configuration or running a test.
The catalog and capability reports describe what the platform knows how to attempt. Readiness additionally depends on admitted destination policy, credentials, operation metadata and the actual running executor. A catalog entry, connection ping or syntax check does not prove that a specific production query or external mutation succeeded. Treat external reads as provider work with their own authority; a nominal GET can still disclose information or incur a provider cost.
| Reader task | First object/evidence to inspect | Next decision |
|---|---|---|
| Find an operation | Connector catalog, capabilities and actual operation metadata | Is this operation available and visible to this actor? |
| Configure a real endpoint | The connected system and its admitted credential/destination policy | Who owns the secret, environment and immutable version? |
| Reuse a business call | Exact published Integration contract | What are its input/output shape, retry and confirmation rules? |
| Investigate a failed/unknown call | Exact execution record, safe error and retained custody | Was it admitted/dispatched, and is its remote outcome known? |
| Write SQL safely | Approved query and admitted JDBC dialect/source | Which placeholders/types/limits are supported, without string concatenation? |
Nadia’s teaching example reads an employee by its actual fixture identifier from an explicitly admitted service. The documentation supplies no credentials and performs no outbound calls. For a connected journey use Integration and published API tutorial.
Worked examples
Example DATA-CONNECTOR-01 — Choose an operation from capability and readiness evidence
Scenario and inputs. Nadia has permission to inspect one teaching connected system and wants a read operation for employee details. Several connector families appear in the catalog, but her chosen service still needs valid configuration and an authorized destination. A provider label alone does not establish availability.
Procedure. 1. Open the actual catalog and inspect the selected connector’s capabilities and supported operations. 2. Read the applicable readiness report and separate missing configuration from an unsupported executor or denied destination. 3. Inspect the operation’s type, input/output contract and mutating behavior rather than inferring it only from its HTTP method. 4. Check Nadia’s connector/connected-system permissions before opening operation detail or execution history. 5. Choose a small synthetic input only after the real owner has admitted the service and credential path.
Expected result. The author can explain why this exact operation is selectable and what remains required before a call. A readiness problem stays visible as a dependency/configuration issue; it is not converted into a fake successful preview.
Failure and recovery. If a catalog item exists but the required executor or destination is unavailable, choose a genuinely supported operation or request the accountable owner’s specific admission/configuration action. Do not change network allowlists, use another actor’s credential or enable an unsafe fallback merely to make an example run.
Sources. ConnectorController.java, ConnectorController.java.
Example DATA-CONNECTOR-02 — Send one mapped read without forging internal options
Scenario and inputs. An admitted direct connector operation reads an employee from the isolated fixture service. Nadia has the actual connector/operation IDs and execution permission, including the connected-system guard when the connector is bound to one. The body is a complete direct-execute request; input names must match that actual operation. Here input binds the serialized VariableMap record, so those business names belong inside input.values; it is not one of the endpoints that explicitly accepts a flat map.
Procedure. 1. Confirm this is a direct connector operation rather than a published Integration proxy. 2. Send the body to POST /api/connectors/{connectorId}/operations/{operationId}/execute using the actual IDs and normal authenticated context. 3. Retain the returned execution identity and inspect the exposed safe result/history under the same authorized owner. 4. Keep input data separate from options and do not add reserved retry/deadline/protocol or connected-system provenance fields. 5. Use the exact versioned Integration endpoint instead when the selected operation is backed by a published Integration.
{
"input": {
"values": {
"employeeId": "actual-employee-fixture-id"
}
},
"options": {}
}
Expected result. The native controller applies connector and underlying system permission checks, removes caller-forged internal options and exposes a result through its normal receipt policy. The input does not select a different connected system merely by adding an options field.
Failure and recovery. An Integration-backed direct call is refused because its exact immutable version must be invoked through the Integration surface. Do not route around that refusal with a hidden operation ID. Wrong input shape or unavailable destination requires correcting the selected contract/admission, not widening options until the call appears accepted.
Sources. ConnectorController.java, ConnectorController.java.
Example DATA-CONNECTOR-03 — Prepare a typed approved query instead of interpolating SQL
Scenario and inputs. The teaching environment has an admitted JDBC connection containing leave-balance data. Nadia wants one employee’s current approved balance. The database account and dialect already exist under operator ownership; the authoring task does not authorize creating users, changing shared schemas or exploring arbitrary tables.
Procedure. 1. Inspect the connected system’s approved-query and schema-discovery capabilities under the actual actor. 2. Use the supported written-query authoring surface and its declared parameter mechanism for the employee selector. 3. Keep the SQL text and typed parameter values separate; never concatenate a user-supplied identifier or value into SQL. 4. Validate against the selected dialect and explicitly bounded result shape. 5. Test only the admitted fixture query when the owner permits execution, retaining its exact request and safe receipt. 6. Publish/reuse the supported approved query through the owning contract.
Expected result. The query’s business question and parameter contract are reviewable without embedding credentials or arbitrary client SQL in an application screen. A syntax/connection success is recorded only for that boundary, not relabeled as successful live data retrieval or runtime qualification.
Failure and recovery. If discovery is denied or a dialect/type is unsupported, keep the limitation explicit and ask for the actual schema/contract from its owner. Do not use unrestricted credentials, bypass destination policy or treat an empty preview as proof that an external employee has no leave balance.
Sources. ApprovedQueryController.java, ConnectorController.java.
Example DATA-CONNECTOR-04 — Reconcile an unresolved attempt while preserving uncertainty
Scenario and inputs. A connector call has a retained execution ID but the client disconnected before a reliable outcome was shown. The remote system may already have acted. An authorized operator has to distinguish the platform’s recorded evidence from an operator’s later assertion about the external outcome.
Procedure. 1. Load the exact execution through its owning connector/system context and retain its status, timestamps and safe admission/dispatch evidence. 2. Confirm whether it is an unresolved STARTED execution eligible for the current reconciliation path and lease timing. 3. Obtain concrete remote/custodian evidence for the original attempt before choosing any reconcile action. 4. Use the native reconcile surface only within the operator’s existing authority and record the basis for the decision. 5. Re-read the same execution and keep original outcome-known/dispatched evidence distinct from reconciliation attribution.
Expected result. The record can retain who reconciled it and when without retroactively converting an uncertain original remote outcome into independently observed success. The application does not issue a new external request simply because the old response was missing.
Failure and recovery. If the original outcome cannot be distinguished safely, preserve the uncertainty and name the accountable external owner’s next action. Do not bulk-mark executions successful, mint a new idempotency intent or repeat a potentially mutating provider call to make the history look complete.
Sources. ConnectorController.java, ConnectorController.java.
Detailed reference
Task-oriented consultant and operator workflows for discovery, SAP, OpenAPI/WSDL, Rules, Process, Fabric, Interfaces, refresh, credentials, and secret-safe troubleshooting live in Consultant and operator Integration workflows. This manual remains the connector catalog and executor reference.
Connectors are the platform extension layer for calling external systems from workflows, service tasks, reports, AI agents, and Fabric datasets.
They are intentionally separate from Fabric:
- Connectors describe how to reach a system and which operations are available.
- Fabric describes business meaning: sources, objects, entities, relationships, datasets, governance, cache policy, and AI exposure.
flowchart LR
A["XML Connector Catalog"] --> B["ConnectorCatalogLoader"]
B --> C["ConnectorRegistryService"]
C --> D["ConnectorExecutionService"]
D --> E["ConnectorExecutor"]
E --> F["External System"]
C --> G["Fabric Query Service"]
G --> H["Reports, Workflows, AI Agents"]
Configuration Folder
Connector definitions are loaded from:
conf/connectors/
The default platform catalog is:
conf/connectors/platform-connectors.xml
Additional XML files can be added to the same folder. The loader reads all .xml files in sorted order.
Java Services
ConnectorCatalogLoader: loads XML catalog files.ConnectorCatalogImporter: validates duplicates and imports definitions.ConnectorRegistryService: stores connector definitions and operations.ConnectorCapabilityService: derives capability summaries from protocol, metadata, and operation types.ConnectorCatalogService: derives the operational connector catalog, readiness warnings, executor coverage, and rollout report.ConnectorReadinessService: correlates connector definitions with workflow service tasks and Fabric sources so admins can see what is production ready and what setup work remains.ConnectorExecutionService: resolves a connector operation and dispatches it to a Java executor.ConnectorExecutor: Java implementation point for REST, JDBC, SDK, webhook, event stream, AI provider, or custom protocols.
Authenticated API
The connector layer is exposed through authenticated platform APIs. All calls go
through AccessGuard, so the service layer receives the current authenticated
actor before execution.
Connector catalog:
GET /api/connectors
GET /api/connectors/search?q=google
GET /api/connectors/capabilities
GET /api/connectors/catalog
GET /api/connectors/catalog/{connectorId}
GET /api/connectors/catalog/report
GET /api/connectors/readiness
GET /api/connectors/executions
GET /api/connectors/executions/{executionId}
GET /api/connectors/{connectorId}
GET /api/connectors/{connectorId}/capabilities
GET /api/connectors/{connectorId}/executions
GET /api/connectors/{connectorId}/operations
GET /api/connectors/{connectorId}/operations/{operationId}
Execute a connector operation:
POST /api/connectors/{connectorId}/operations/{operationId}/execute
Connector templates used by the Studio connect wizard are exposed separately:
GET /api/connector-templates
GET /api/connector-templates/{templateId}
POST /api/connector-templates/refresh
Template XML files live under conf/connector-templates/. The runtime catalog
checks a content fingerprint on reads, so editing or adding a template file is
picked up by the next list/detail request without an API restart. A super
administrator can also call the refresh endpoint to force an immediate reload
and validation pass.
REST templates expose an Advanced setting, Send standard Idempotency-Key header
on writes. Inflow always keeps an internal execution key for receipts, live-test
confirmation, and rule retries. The IETF Idempotency-Key header is attached to
POST/PATCH/PUT/DELETE only when that Advanced setting is on, the published
capability outboundIdempotencyHeader is Idempotency-Key, or the integration
retry policy selects the standard header source. Salesforce sObject REST and
ServiceNow Table API default off: those APIs do not support the header.
Request body:
{
"input": {
"values": {
"queryId": "platform.echo",
"parameters": {
"value": "hello"
}
}
},
"options": {
"bypassCache": false
}
}
The API builds a ConnectorExecutionRequest with:
- the connector id from the URL
- the operation id from the URL
- the authenticated actor from
AccessGuard inputas aVariableMapoptionsas execution hints
Execution History
Every connector execution is recorded by DefaultConnectorExecutionService
before the result leaves the service layer. This is intentionally done above
individual executors, so REST, JDBC, event-stream, AI-provider, SDK, and future
custom connectors all get the same execution history.
Each record carries the current workspace id. All repository and HTTP history reads require that same workspace, and an existing execution id cannot be reassigned to another workspace. Integration Designer diagnostics add the owning draft and exact published version as an additional concealment boundary.
flowchart LR
A["API, Workflow, Agent, or Fabric"] --> B["ConnectorExecutionService"]
B --> C["ConnectorExecutor"]
C --> D["ConnectorExecutionResult"]
B --> E["ConnectorExecutionRecordRepository"]
E --> F["connector_execution_records"]
The PostgreSQL migration is:
migrations/postgres/000018_create_connector_execution_records.up.sql
History records include:
- connector id and operation id
- authenticated actor id and actor type
- status:
SUCCEEDEDorFAILED - success flag
- external reference
- error code and message
- duration in milliseconds
- input, options, output, and metadata JSON
- started and completed timestamps
Read history:
GET /api/connectors/executions?limit=100
GET /api/connectors/executions?actorId=worker&limit=100
GET /api/connectors/executions/{executionId}
GET /api/connectors/{connectorId}/executions?limit=100
Example response:
{
"connectorId": "postgresql",
"operationId": "run-approved-query",
"actorId": "worker",
"status": "SUCCEEDED",
"success": true,
"durationMs": 42,
"input": {
"values": {
"queryId": "platform.echo"
}
},
"output": {
"values": {
"queryId": "platform.echo",
"rows": []
}
}
}
Failures are recorded too. For example, a missing connector operation stores
status=FAILED and errorCode=CONNECTOR_OPERATION_NOT_FOUND before the
original connector exception is returned to the caller.
Outbound destination policy
REST, MongoDB, Redis, and OAuth client-credentials destinations are checked by the shared outbound URL policy before each request. HTTPS is required by default, redirect following is disabled in the shared transport, and loopback, private, link-local, multicast, CGNAT, benchmarking, unspecified, and IPv6 ULA addresses are blocked unless an operator explicitly allows the exact host or CIDR.
Operators may configure these process environment variables:
INFLOW_CONNECTOR_OUTBOUND_ALLOWLIST: comma-separated exact host names and/or CIDRs. This is deployment policy and is not editable by Integration authors.- Canonical
connector.outbound.allow-http=truepermits HTTP destinations that otherwise pass the address policy. It defaults false and requires a restart;INFLOW_CONNECTOR_OUTBOUND_ALLOW_HTTPis retired. Set the value through the canonical file or authorized native flag API/MCP. See Feature switches.
Every pagination URL is validated again and credentials are never placed in diagnostic URLs. The current check validates DNS answers immediately before the non-redirecting transport call; transport-level DNS pinning is still required before complete DNS-rebinding resistance can be claimed.
Approved-query catalog and cache management:
GET /api/approved-queries
GET /api/approved-queries/{queryId}
POST /api/approved-queries/cache/invalidate
Cache invalidation body:
{
"scope": "all"
}
Supported scopes:
key: remove one exactcacheKey.prefix: remove every entry whose key starts withcacheKeyPrefix.all: clear the approved-query result cache.
API Permissions
The connector API uses these permissions:
CONNECTOR_VIEW: list and inspect connector definitions and operations.CONNECTOR_EXECUTE: execute a connector operation.APPROVED_QUERY_VIEW: list and inspect approved SQL query definitions.APPROVED_QUERY_CACHE_MANAGE: clear or evict approved-query result cache entries.
The development seed roles grant connector view/execute permissions to
designer and worker. Cache management is granted to worker; root has
all permissions.
Capability Summaries
The connector registry exposes a derived capability view for designers, Fabric planners, service-task catalogs, and future extension marketplaces. This view does not require extra XML fields. It is calculated from:
- connector
protocol - connector
authType - connector
metadata.category - operation
type - metadata flags such as
supportsWebhooks
Example response:
{
"connectorId": "kafka",
"provider": "Apache Kafka",
"category": "event-stream",
"protocol": "EVENT_STREAM",
"authType": "CUSTOM",
"operationCount": 1,
"operationTypes": ["PUBLISH"],
"capabilities": ["event", "write", "publish"],
"databaseCapable": false,
"apiCapable": false,
"eventCapable": true,
"automationCapable": false,
"aiProviderCapable": false,
"readCapable": false,
"writeCapable": true,
"triggerCapable": false
}
Capability labels include:
databaseapifileeventautomationai-providerreadwritetriggersubscribepublishai-inference
Operational Catalog Report
The operational connector catalog is the deployable view of connector readiness. It combines the XML connector definitions, derived capability summaries, and registered Java executors.
flowchart LR
A["conf/connectors/*.xml"] --> B["ConnectorRegistryService"]
B --> C["ConnectorCapabilityService"]
B --> D["Registered ConnectorExecutors"]
C --> E["ConnectorCatalogService"]
D --> E
E --> F["GET /api/connectors/catalog"]
E --> G["GET /api/connectors/catalog/report"]
Each catalog entry includes:
- protocol and authentication type
- category and capability flags
- operation count and operation types
- whether a Java
ConnectorExecutorsupports the connector operationalStatus:READY,NEEDS_ATTENTION, orDISABLED- readiness warnings
Example entry:
{
"connectorId": "n8n",
"category": "automation",
"protocol": "REST",
"authType": "API_KEY",
"operationCount": 2,
"automationCapable": true,
"triggerCapable": true,
"executorSupported": true,
"operationalStatus": "READY",
"readinessWarnings": []
}
The report endpoint returns rollout counters and grouped inventory:
{
"connectorCount": 34,
"enabledConnectorCount": 34,
"operationCount": 68,
"executorSupportedCount": 18,
"executorMissingCount": 16,
"byProtocol": {
"REST": 16,
"JDBC": 6,
"AI_PROVIDER": 4
},
"byCategory": {
"automation": 2,
"database": 4,
"ai": 4
},
"connectorsMissingExecutor": ["kafka", "rabbitmq"],
"readinessWarnings": [
"kafka: No registered Java ConnectorExecutor supports protocol EVENT_STREAM."
]
}
Readiness warnings are not startup blockers. They are an implementation and deployment checklist. A connector can be defined before its executor is ready, which lets architects model integrations early while engineering adds executor coverage in controlled increments.
Fabric uses the same connector catalog when building relationship plans.
For example, a connector:n8n source can resolve to connector id n8n,
protocol REST, category automation, and trigger capability. A PostgreSQL
source resolves to database/read capability, while Kafka resolves to
event/publish capability.
Production Readiness Report
The readiness report answers a different question from the catalog report: whether a connector is ready to be used in real platform designs.
GET /api/connectors/readiness
It is still database-agnostic. The service derives the report from:
- connector XML under
conf/connectors - service-task XML under
conf/service-tasks - Fabric XML under
conf/ai-fabric - registered Java
ConnectorExecutorimplementations
flowchart LR
A["Connector Catalog"] --> D["ConnectorReadinessService"]
B["Workflow Service Tasks"] --> D
C["Fabric Sources and Objects"] --> D
E["ConnectorExecutors"] --> A
D --> F["GET /api/connectors/readiness"]
Each connector readiness item includes:
operationalStatus:READY,NEEDS_ATTENTION, orDISABLEDexecutorSupportedcredentialConfiguredoperationCount- workflow service-task references
- Fabric source and object references
setupActions- readiness warnings from the operational catalog
Example response fragment:
{
"connectorCount": 33,
"readyConnectorCount": 33,
"workflowReadyConnectorCount": 18,
"aiFabricReadyConnectorCount": 4,
"executableConnectorCount": 33,
"connectors": [
{
"connectorId": "n8n",
"operationalStatus": "READY",
"executorSupported": true,
"credentialConfigured": true,
"workflowServiceTasks": ["service.n8n.webhook.trigger"],
"aiFabricSources": ["n8n"],
"aiFabricObjects": ["n8n.workflow-runs"],
"setupActions": []
}
]
}
Use this report during rollout planning:
- If
executorSupported=false, implement or enable a JavaConnectorExecutor. - If
credentialConfigured=false, add a credential reference such asenv:OPENAI_API_KEY,secret:n8n-api-key, oroauth:salesforce. - If
workflowServiceTaskCount=0, the connector exists but is not yet mapped to a BPMN-callable service task. - If
aiFabricSourceCount=0, the connector is not yet part of Fabric relationship discovery or dataset planning.
This is the admin checklist for making connectors usable by workflows, reports, agents, and Fabric.
REST Executor
RestConnectorExecutor is the first concrete executor.
It supports connectors where:
protocol="REST"
HTTP Timeouts
Outbound REST calls ride the shared platform HTTP request factory, whose
connect timeout and read timeout (the wait for response headers) are bounded,
so a downstream that never answers cannot park the calling thread forever
(which would also keep the circuit breaker from ever tripping). Both default to
30 seconds — matching the SOAP executor's call timeout — and are configurable
in conf/custom_config.properties.
The read timeout does not bound reading the response body: measured on spring-web 6.1.16 / JDK 17, a downstream that sends headers and then stalls or trickles its body holds the caller until it gives up. AI provider calls add their own whole-attempt deadline (see the AI gateway manual); connector calls currently do not.
platform.http.connectTimeoutSeconds=30
platform.http.readTimeoutSeconds=30
Request Mapping
For an operation path such as:
/workflows/{workflowId}/trigger
the executor reads workflowId from ConnectorExecutionRequest.input, URL-encodes it, replaces the path placeholder, and removes it from the remaining payload.
For GET and DELETE, remaining input values are sent as query parameters.
For POST, PUT, and PATCH, remaining input values are sent as the JSON body. A caller may override the body by putting body in ConnectorExecutionRequest.options.
Custom outbound headers can be passed with option keys prefixed by:
header.
For example:
Map.of("header.X-Correlation-Id", "trace-123")
Supported Authentication
The REST executor currently supports:
NONEAPI_KEYBEARER_TOKENOAUTH2OIDCSAML2BASICHMACas a first placeholder header strategy
Credentials are resolved through AiCredentialResolver, so connector
credentialReference values may use the same forms as AI providers:
env:OPENAI_API_KEY
secret:n8n-api-key
vault:<id> (stored through the credential vault)
Resolution is fail-closed (see the upgrade note in
docs/manuals/ai-gateway.md): only env: and secret: resolve from the
environment and vault: through the vault. Any other reference — including
older verbatim secrets or foreign schemes such as oauth: — resolves to
empty and must be migrated before upgrade.
Redis template v1 remains immutable and keeps its original redis:// defaults
for existing drafts and versions. Template v2 remains for systems already
published on it. New authoring uses Redis template v3, which keeps rediss://
and port 6380 and leaves the user name optional. Authenticated Redis health
probes require TLS; the probe pins the policy-approved address, verifies the
certificate against the original DNS name or IP address, and then runs AUTH,
SELECT, and PING. Plaintext redis:// health probing is accepted only with
authentication mode NONE.
SOAP connection tests use the exact WSDL source URL retained by specification
import, or a catalog-provided metadata probe path. Query parameters already on
that URI are preserved when a wsdl query flag is added. Credentials are sent
only to a normalized same-origin metadata URI. Cross-origin metadata is fetched
without credentials; it can validate an unauthenticated connection but cannot
satisfy a credentialed publication gate. A manually authored SOAP connection
without a governed metadata URI records endpoint reachability only as failed,
partial evidence and cannot publish until the consultant configures a safe
metadata probe.
Connected systems created through the integration API store their material in
the credential vault and carry an opaque vault:<id> reference. References
are not exclusive: two connected systems may carry the same vault:<id>
(or secret:) reference. Rotation or revocation applies to the
single stored credential, so it takes effect for every system that shares
the reference at the same time — revoking a shared credential silently cuts
off all of them. Use one vault entry per connected system unless that
coupling is a deliberate choice.
For API_KEY, the default header is:
Authorization: Bearer <credential>
The connector metadata can override this:
{"apiKeyHeader":"X-N8N-API-KEY","apiKeyPrefix":""}
For bearer-style auth types, the executor sends:
Authorization: Bearer <credential>
Amazon S3 bucket discovery
Amazon S3 template version 1 can discover the configured bucket through the
pinned s3-buckets provider. The template is a single virtual-hosted bucket;
discovery GETs the bucket root as ListObjectsV2 (?list-type=2) with the
published credentials and does not enumerate every bucket in the AWS account.
It emits bounded list/get operations for that bucket, and emits put only when
discoveryApprovedWrites is explicit. Access-denied responses do not include
inaccessible bucket names.
GraphQL introspection discovery
GraphQL template version 1 can discover queries and mutations through the pinned
graphql-introspection provider. Introspection is off by default and runs only
when discoveryApprovedIntrospection is explicit. Disabled introspection is
fail-closed. Recursive object types are not expanded into additional operations.
Mutations are always UNVERIFIED; confirmation and idempotency are required and
mutation safety is never inferred from the schema.
GraphQL template version 2 offers three sign-in choices. None is the default.
API key and Basic are the other two. An API key is sent only in a header. The
default header is Authorization: Bearer <key>, the same header GraphQL calls
already used. apiKeyHeader and apiKeyPrefix override that header and the
text in front of the key. Saving an API key with location query is refused
with "For a GraphQL system, the key must be sent in a header." and nothing is
saved. The key itself stays in the credential vault.
Test connection sends query InflowConnectionCheck { __typename } to the
system address, with that sign-in, through the same outbound policy as a
normal call. It succeeds only when the answer contains a non-blank
data.__typename, and then reads "Connection test succeeded. The GraphQL
service answered." Other results stay distinct: sign-in refused (HTTP 401 or
403), plain http, a private or internal address, a host that cannot be
reached, the five-second timeout, a problem on the service, a GraphQL error,
an answer that is not GraphQL (often an address that does not end in
/graphql), and other rejected settings. A GraphQL error can append one
redacted sentence, "The system said: …", bounded to 300 characters. Codes,
empty text, and credential material are not shown.
Allow schema discovery is off until a consultant turns it on and publishes the
system. The switch is labeled "Allow schema discovery". While it is off,
discovery says to turn it on, publish, and try again. A service that itself
refuses introspection says "This GraphQL service does not let its schema be
read. Add operations by hand with New integration." An address the platform
network rules refuse says "The platform's network rules do not allow calls to
this address." Any other failure to read the schema says "The GraphQL schema
could not be read. Check that the service is running, then try again." Those
messages do not include the address, the transport error, or the HTTP status.
A discovered operation maps data.<field>. A list publishes that list, an
object publishes that object, and a float publishes the exact decimal text.
A discovered object or interface selects up to 16 of its own scalar and enum
fields, including a list of those types, and leaves nested objects out. An
object with none of those fields, including a union, still selects
{ __typename }. The country query asks for code, name, native, and
capital.
An HTTP 200 body that contains GraphQL errors and no usable data is a
failure. Usable data together with errors completes the step. The process
output integrationStatus is SUCCEEDED_WITH_WARNINGS, and
integrationFailure.code is GRAPHQL_PARTIAL_DATA. The workbench says "Test
succeeded with warnings". A gateway condition
integrationStatus == "SUCCEEDED_WITH_WARNINGS" routes that case to review.
A condition that matches only SUCCEEDED does not take this path.
A Generic HTTP system that posts to a GraphQL URL is still judged by HTTP
status. A JSON errors field on that path is not a GraphQL failure. Use a
GraphQL connected system when the service speaks GraphQL.
Redis key discovery
Redis template v2 can use the pinned redis-keys provider. Key enumeration is
off by default: discovery emits a generic get-key operation and never sends
KEYS. Bounded SCAN runs only when discoveryApprovedScan is explicitly true
and discoveryScanPattern is a safe MATCH glob. SCAN is limited by count,
result, round, and time budgets, and stops when cancelled. Discovery may send
TYPE and PTTL but never fetches values. Authenticated Redis still requires
rediss://. Key enumeration can increase Redis load and expose key names;
consultants should use the narrowest pattern.
MongoDB collection discovery
MongoDB template version 1 can discover collections through the pinned
mongodb-collections provider. Discovery lists authorized non-system.*
collections and prefers $jsonSchema validators for typed field suggestions.
Bounded sampling runs only when the connected system capability
discoveryApprovedSampling is explicitly true. Sample document values are
never retained; inferred fields are labeled with origin and confidence.
MongoDB, Redis, and Amazon S3
Release note. MongoDB connections now use the same outbound address policy
as REST and Redis. A MongoDB system on a private or internal host, including a
replica-set member the driver discovers later, stops until an operator adds
that exact host or CIDR to INFLOW_CONNECTOR_OUTBOUND_ALLOWLIST. The
connection test says: "This system's address points to a private or internal
network, which Inflow doesn't reach unless your administrator has allowed it."
Plain http:// stays refused. Keep canonical connector.outbound.allow-http=false in production.
Docker and Windows hosts. When the API runs in Docker and MongoDB or Redis
runs on the Windows host, set the host to host.docker.internal, not
localhost. That name is still a private address, so it also needs an
allow-list entry. This guidance used to sit in the MongoDB template.
Consultants now see plain field help. Operators set the host and the
allow-list.
MongoDB reads. Current template operations carry mongodb.find and
mongodb.ping. Older integrations without a kind keep the previous inference.
A Find matches a field to one exact text or number. Operator keys are refused.
A discovered Find is pinned to its collection: a later run cannot pass a
different collection. Collections whose names start with system. are refused.
Dates become UTC instants, exact decimals keep their scale, and an ObjectId
becomes 24-character hex text. A value Inflow cannot store fails the call, and
the execution receipt is recorded as failed.
Redis reads. A password is sent only over rediss://. A password-only
server leaves the user name blank. Reads cover a string, a hash, a list, a
set, or a sorted set. A discovered read is pinned to its key. Lists, sets, and
sorted sets return at most 100 items, and one value larger than 64 KB is
refused. The reply stays under 1 MB. Inflow sends only AUTH, SELECT,
PING, GET, TYPE, PTTL, EXISTS, HLEN, HGETALL, HSCAN, LLEN,
LRANGE, SCARD, SSCAN, ZCARD, ZRANGE, and SCAN. SCAN runs only
during an approved discovery scan. KEYS is never sent.
Amazon S3. Authentication "AWS access key" asks for an access key ID, a
secret access key, and an optional session token. The secret and the token
stay in the credential vault. Requests are signed with Signature Version 4 for
the S3 service and the configured region. Template version 2 adds a free-text
region (default us-east-1), an optional https:// endpoint, a path-style
switch, and the bucket. With no endpoint, requests use
https://<bucket>.s3.<region>.amazonaws.com, or
https://s3.<region>.amazonaws.com/<bucket> when path-style is on. With an
endpoint, path-style uses <endpoint>/<bucket>. Plain http:// is refused
because it would send the access key unencrypted. List objects takes an
optional prefix, returns at most 1,000 keys (default 100), and can continue.
Read JSON object accepts one key and at most 1 MB of JSON. Template version 2
does not offer a write. An object key cannot be empty, ., .., or contain a
control character, and each segment is encoded.
ServiceNow Table API discovery
ServiceNow template version 1 discovers tables from sys_db_object and field
dictionaries from sys_dictionary through the pinned servicenow-table
provider. Each authorized table becomes a resource with:
- typed read (
GET /api/now/table/{table}/{sysId}) - bounded search (
GET /api/now/table/{table}withsysparm_queryandsysparm_limit) - typed create (
POST /api/now/table/{table}JSON body) when the dictionary exposes non-read-only, non-sys_fields
ServiceNow dictionary metadata does not publish table CRUD ACL flags. Discovered
operations are labeled authorizationStatus=UNVERIFIED. Tables whose dictionary
request is unauthorized are omitted without leaking names. Password dictionary
types are excluded from read and create contracts. Discovery stays bounded and
redacts diagnostics.
Salesforce Describe discovery
Salesforce template version 1 can discover integrations from the REST Describe API. Discovery uses the selected connected-system version and the exact published credential reference; it does not substitute an administrator or catalog credential. Stable integration and field identities come from Salesforce API names, while localized labels remain presentation text.
Only successfully described objects become resources. Relationship targets are included only when that target was also successfully described, so an object that the principal cannot describe is not disclosed indirectly. When a bounded search omits a catalog-visible relationship target, the response marks coverage partial and explains that the target must be searched separately; it never claims relationship closure. JSON metadata is accepted only from application/json or a structured +json media type. Other discovery providers retain XML-only metadata negotiation.
The curated preview deterministically inspects at most 200 catalog objects and 500 fields per object. When the Salesforce catalog contains more than 200 objects, the response explicitly reports partial global coverage instead of pretending that omitted objects were inspected.
Consultants can submit an explicit Search Salesforce catalog query against
the bounded root catalog. Matching is a normalized, case-insensitive substring
of API name or label; at most 50 matches are described. Blank search returns
the curated preview. Search responses have filtered coverage, including
no-match responses, and never infer that existing operations outside the
filter were removed. Coverage is part of the availability fingerprint. Apply
replays the normalized search and rejects stale or mismatched fingerprints.
A rejected Describe request, invalid metadata, or Salesforce rate limit marks the preview incomplete. Successfully described operations remain selectable and apply replays their exact scoped fingerprint; failed or omitted objects are not included. A preview with no usable operations keeps an ERROR diagnostic and is not selectable. Retry preserves the active normalized server search. Only a complete global catalog may infer removal of previously discovered operations; partial or filtered previews preserve omitted provenance.
Response Mapping
The REST executor returns:
success=trueoutput.response: parsed JSON response mapexternalReference: best-effort id from fields such asid,runId,executionId,key, orsid- metadata containing method, sanitized URL, and completion timestamp
Remote errors are wrapped as:
REST_CONNECTOR_CALL_FAILED
Missing path variables are rejected before a remote call:
REST_CONNECTOR_PATH_VARIABLE_MISSING
Event Stream Executor
EventStreamConnectorExecutor supports connectors where:
protocol="EVENT_STREAM"
It currently supports PUBLISH operations. Instead of publishing directly to
Kafka or another broker from the workflow thread, it writes a durable
OutboxMessage through MessageOutboxService. The existing outbox publisher
worker then claims pending rows and sends them to the configured broker. This
keeps workflow execution database-transactional and lets the platform scale
publish throughput by adding more publisher workers.
flowchart LR
A["Workflow, Agent, or API"] --> B["ConnectorExecutionService"]
B --> C["EventStreamConnectorExecutor"]
C --> D["message_outbox row"]
D --> E["OutboxPublisherWorker"]
E --> F["Kafka / broker"]
Request Mapping
For a Kafka-style connector operation:
<operation id="publish-event" type="PUBLISH">
<method>PRODUCE</method>
<path>{topic}</path>
</operation>
execution input can be:
{
"topic": "inflow.integration.commands",
"key": "customer-100",
"messageName": "CustomerSynced",
"payload": {
"customerId": "C-100"
},
"headers": {
"correlationId": "corr-1"
}
}
The executor maps this to:
channel: from input/options, connector metadata, orkafkafor the Kafka connector.topic: from input/options or the expanded operation path.messageKey: frommessageKeyorkey.messageName: from input/options, operation metadata, operation name, or operation id.aggregateType: from input/options or connector id.aggregateId: from input/options orkey.payload: frompayload; if omitted, remaining input values become the payload.headers: explicit headers plus connector id, operation id, and authenticated actor metadata when available.
Example response:
{
"connectorId": "kafka",
"operationId": "publish-event",
"success": true,
"output": {
"values": {
"messageId": "5a4d...",
"channel": "kafka",
"topic": "inflow.integration.commands",
"status": "PENDING"
}
},
"externalReference": "5a4d..."
}
Missing path variables are rejected before enqueue:
EVENT_STREAM_PATH_VARIABLE_MISSING
Unsupported operation types are rejected with:
EVENT_STREAM_OPERATION_UNSUPPORTED
AI Provider Executor
AiProviderConnectorExecutor supports connectors where:
protocol="AI_PROVIDER"
It currently supports AI_INFERENCE operations. The connector executor does
not call model providers directly. It converts the connector request into an
AiGatewayRequest and lets the AI Gateway apply model routing, data-residency
rules, redaction policy, provider clients, token-usage recording, and audit logging.
flowchart LR
A["Workflow, Agent, or API"] --> B["ConnectorExecutionService"]
B --> C["AiProviderConnectorExecutor"]
C --> D["AiGatewayService"]
D --> E["Routing + Redaction + Audit"]
E --> F["Provider Client"]
F --> G["OpenAI / Anthropic / Gemini / Ollama / Local Runtime"]
Request Mapping
Example connector execution input:
{
"purpose": "summarize-content",
"preferredModelId": "my-openai-chat",
"requiredCapabilities": ["CHAT", "STRUCTURED_OUTPUT"],
"prompt": "Summarize the payload.",
"input": {
"content": "long text"
},
"responseFormat": "json",
"maxTokens": 500
}
The executor maps this to:
purpose: from input/options, operation metadata, or connector id plus operation id.preferredModelId: frompreferredModelIdormodelId.requiredCapabilities: from a list or comma-separated string; defaults toCHAT.prompt: fromprompt,text, options, operation description, or a generated fallback.input: remaining request input plus nestedinputvalues.constraints: nestedconstraintsplus keys such asdataClass,responseFormat,temperature,maxTokens, andtopP.requestedBy: the authenticated actor from connector execution.
Example response:
{
"connectorId": "openai",
"operationId": "chat-completion",
"success": true,
"output": {
"values": {
"text": "summary text",
"structuredOutput": {},
"modelId": "my-openai-chat",
"providerId": "my-openai",
"usage": {
"totalTokens": 120
},
"auditId": "ai-call-id"
}
}
}
Unsupported operation types are rejected with:
AI_PROVIDER_OPERATION_UNSUPPORTED
XML Shape
<connectorCatalog version="1">
<connectors>
<connector id="n8n" protocol="REST" authType="API_KEY">
<name>n8n</name>
<provider>n8n</provider>
<baseUrl>https://n8n.example.local/api/v1</baseUrl>
<credentialReference>secret:n8n-api-key</credentialReference>
<enabled>true</enabled>
<metadata>{"category":"automation","supportsWebhooks":true,"apiKeyHeader":"X-N8N-API-KEY","apiKeyPrefix":""}</metadata>
<operations>
<operation id="trigger-workflow" type="TRIGGER">
<method>POST</method>
<path>/workflows/{workflowId}/trigger</path>
<inputSchema>{"workflowId":"string","payload":"object"}</inputSchema>
<outputSchema>{"runId":"string","status":"string"}</outputSchema>
</operation>
</operations>
</connector>
</connectors>
</connectorCatalog>
Connector Extension Authoring
Connector extension packs are authored as XML files under conf/connectors.
The platform also exposes a preview service so designers and administrators can
generate a valid starter connector definition before saving it to the catalog
folder.
flowchart LR
A["Designer or Admin"] --> B["POST /api/connectors/extension-pack/preview"]
B --> C["ConnectorExtensionAuthoringService"]
C --> D["Generated connector XML"]
D --> E["conf/connectors/{packName}.xml"]
E --> F["XmlConnectorCatalogLoader"]
F --> G["ConnectorRegistryService"]
Preview endpoint:
POST /api/connectors/extension-pack/preview
The endpoint is authenticated and currently requires CONNECTOR_VIEW because
it does not write files or mutate the runtime registry. A later administration
permission can separate connector authoring from connector viewing.
Example request:
{
"packName": "document-platform",
"connectorId": "document-platform",
"name": "Document Platform",
"provider": "Internal Documents",
"protocol": "REST",
"authType": "OAUTH2",
"baseUrl": "https://docs.example.com/api",
"credentialReference": "oauth:document-platform",
"category": "document",
"supportsWebhooks": false,
"metadataJson": "{\"owner\":\"solutions\"}",
"operationId": "generate-document",
"operationName": "Generate Document",
"operationType": "EXECUTE",
"method": "POST",
"path": "/documents/generate",
"description": "Generate a document from a template and data payload.",
"inputSchemaJson": "{\"templateId\":\"string\",\"data\":\"object\"}",
"outputSchemaJson": "{\"documentId\":\"string\",\"url\":\"string\"}",
"operationMetadataJson": "{\"rateLimitGroup\":\"documents\"}"
}
Example response fields:
{
"packName": "document-platform",
"connectorPath": "conf/connectors/document-platform.xml",
"connectorXml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>...",
"nextSteps": [
"Review generated metadata, schemas, and credentialReference.",
"Save connectorXml to conf/connectors/document-platform.xml.",
"Add or reuse a ConnectorExecutor for protocol REST if one does not already exist.",
"Reference connector document-platform from service tasks, Fabric sources, agents, or reports.",
"Run .\\scripts\\container-test.ps1."
]
}
The preview service validates:
- pack name, connector id, category, operation id, and method tokens
- connector protocol and authentication type through Java enums
- operation type through Java enums
- connector metadata JSON
- operation input/output schema JSON
- operation metadata JSON
The generated XML is escaped and can be loaded by XmlConnectorCatalogLoader.
This keeps connector extension packs portable across database engines because
the definitions live in configuration files first. Later, the same artifact can
be stored in a database, Git repository, or marketplace registry without
changing the runtime connector model.
Extension Readiness Checks
The operational catalog report also acts as the connector extension-pack quality gate. It now checks both deployability and authoring quality:
- enabled connectors need a supporting Java
ConnectorExecutor - authenticated connectors need a
credentialReference - REST, GraphQL, SOAP, webhook, and AI-provider connectors need a
baseUrl - REST-like operations need a
methodandpath - every connector should declare
metadata.category - authored extension packs, identified by
metadata.extensionPack, should give every operation a description,inputSchema, andoutputSchema - JDBC read operations should go through approved query ids
- AI provider connectors should expose
AI_INFERENCEoperations
These checks appear as readiness warnings in:
GET /api/connectors/catalog
GET /api/connectors/catalog/report
GET /api/connectors/readiness
Warnings are not startup blockers. They are release gates for connector packs.
During early modeling, a connector may intentionally be incomplete. Before it
is used by BPMN service tasks, agents, reports, or Fabric datasets, the
connector should be READY and its setup actions should be empty.
Adding a Connector Pack Manually
- Call the preview endpoint with the connector and first operation.
- Review the generated XML, metadata, schemas, and credential reference.
- Save the
connectorXmlresponse to the suggestedconnectorPath. - Add more
<operation>entries if the connector has multiple capabilities. - Make sure a
ConnectorExecutorsupports the connector protocol. - Run the platform test script.
Example test command:
.\scripts\container-test.ps1
Extension Design Rules
- Use stable connector ids such as
google-sheets,sap, ordocument-platform. - Put business grouping in
metadata.category; Fabric and capability summaries use it for planning. - Use
credentialReferenceinstead of raw secrets. - Keep raw SQL out of connector operation input. Database connectors should use approved query ids.
- Prefer one connector per external platform and many operations per connector.
- Add Java executors only when the protocol is not already supported.
Service Task Integration
Workflow service tasks can call REST connectors through the connector-rest
service-task implementation.
The generic catalog task is:
service.connector.rest.call
It expects configuration such as:
{
"connectorId": "n8n",
"operation": "trigger-workflow",
"workflowId": "onboard-customer",
"payload": {
"customerNumber": "C-100"
}
}
Several common service tasks have built-in connector-operation defaults, such as
service.n8n.webhook.trigger, service.make.webhook.trigger,
service.google.sheets.read, service.google.sheets.append,
service.slack.message, and service.teams.message.
Service tasks can also declare defaults in XML metadata:
<metadata>{"defaultConnectorId":"google-calendar","defaultOperationId":"create-event"}</metadata>
When metadata supplies both values, workflow configuration only needs the business fields required by the connector operation:
{
"calendarId": "primary",
"event": {
"summary": "Review workflow"
}
}
If metadata does not declare defaultConnectorId, connector-rest can infer
the connector from:
<authRequirement>connector:salesforce</authRequirement>
In that case the workflow still supplies the operation:
{
"operation": "create-record",
"objectName": "Lead",
"record": {
"Company": "Inflow AI"
}
}
The platform seed tasks now use metadata defaults for common enterprise actions including Google Drive upload/share, Google Calendar event creation, Microsoft Graph calendar events, Salesforce lead/case actions, HubSpot and Zoho CRM creation, ServiceNow incidents, Jira issues, Stripe and PayPal payments, DocuSign and Adobe Sign agreements, WhatsApp messages, and signed webhooks.
Written read queries
On a database connected system, a system manager enables Allow written read queries, chooses the allowed schemas, and publishes the system. Create a manual SQL integration, write one SELECT or WITH query, and use named inputs such as :category. Inputs are bound as values. Set the row cap from 1 to 1,000; the result reports whether more rows were available.
Saving keeps an invalid query editable and displays its field finding. Test and publication refuse invalid queries. Test uses the existing LIVE confirmation and an idempotency key; written queries do not use safe preview. Publish only after a successful test for the current saved request and matching captured output. Changing the SQL or row cap is audited with redacted old/new values and invalidates earlier request evidence. Generated discovery and template drafts cannot adopt written-query metadata.
Publishing a newer system version with written queries switched off stops subsequent written-query runs, including integrations pinned to an older system version. Pinned endpoint, credential and allowed schemas stay versioned: removing a schema from a newer system version does not change the permissions of an older pin. Existing saved server-query catalogs keep their existing path. Use a database account with only the access required for the data; SQL Server has the additional account requirement below; Oracle written queries require a read-only database or PDB.
A database refusal while choosing the allowed schema keeps its classified problem and safe database diagnostic; the execution evidence records that no query was sent. A connection-close failure after query execution retains its separate cleanup and outcome evidence. Use the stored diagnostic to distinguish these stages when reviewing a failed run.
Reviewing historical database receipts
Written queries run through their integration, where permissions, version pins and system policy are checked. The system-owned run-approved-query key cannot be used as an integration key.
An older database receipt may not identify whether it came from a written integration or a trusted server query. Inflow refuses replay of these ambiguous receipts, including old trusted-query receipts, and returns the original execution ID for review. Changing or deleting the current connector does not remove that refusal. The original receipt remains unchanged. Do not automatically resend with a new key: first review the original execution and its outcome. New trusted server-query receipts continue to replay normally.
The same review requirement applies when an older non-database receipt lacks trustworthy historical protocol evidence. The review response is HTTP425 with the original execution/correlation ID, stored status, reviewRequired=true and retryable=false. Any recorded dispatch/outcome facts are preserved; missing facts are not inferred from today’s connector. Inspect the original execution and saved receipt before deciding the next action. Do not send the action again with a new request key. Proven historical non-database receipts retain their replay behavior; existing records are never rewritten to manufacture provenance.
PostgreSQL, MySQL and MariaDB connections for written queries
Use a dedicated account with only the required read access. Written-query execution must establish its own read-only transaction on the same connection; a JDBC read-only flag alone is insufficient. PostgreSQL connections configured to ignore that flag and MySQL connections that disable propagation cannot supply the required server proof. A writable, unavailable or ambiguous mode is refused before the written SQL runs. Existing server-owned query catalogs retain their execution path.
MySQL and MariaDB session defaults do not prove an already-open transaction's access mode. Written queries require a fresh transaction boundary and an explicit read-only start; they cannot reuse or implicitly commit a pre-existing transaction. Connection state is rolled back and restored when the attempt finishes.
Read-only mode protects local persistent writes. It does not certify elevated application routines, wrappers around remote database links, temporary/session changes or external network/file effects. Known direct unsafe calls are refused by the lexical policy, but database operators must also restrict unnecessary callable routines and external access. Keep this residual boundary in the account and deployed-schema review.
Oracle destinations for written queries
Use an Oracle database or pluggable database (PDB) opened READ ONLY for written queries. Oracle's JDBC read-only hint does not enforce this on the server; an application function can otherwise commit a local write independently of the query transaction. Keep ordinary server-owned query catalogs on their existing path.
An Oracle administrator prepares the destination and grants the query account only the data access it needs, plus narrow visibility of the current container's open mode (SYS.V_$PDBS for a PDB, or SYS.V_$DATABASE for a non-CDB database). Do not grant database administration or a broad catalog role for this check. Inflow checks the actual execution connection on every written-query run and refuses unavailable, ambiguous or writable destinations before preparing the user's SQL. Provision a separate read-only destination if the application database must remain writable.
This protects local persistent database data. Temporary/session data, remote database links, external network/file effects and privileged changes to the destination's mode remain operator and deployed-schema responsibilities. Keep unnecessary callable routines and external access unavailable to the query account. A mode check does not certify arbitrary application code as side-effect-free.
SQL Server accounts for written queries
Use a dedicated database login that can only read the required schemas. An administrator provisions this account; do not store administrator credentials on a system that allows written queries. Grant SELECT on the required schemas without database-owner, write, schema-management, role-management, grant or impersonation privileges. Test the account by confirming that reads succeed and updates are denied.
The SQL Server JDBC driver ignores its read-only flag. Written queries therefore check the effective account permissions before preparing SQL and refuse accounts with write or impersonation authority. Read-only metadata visibility, including SQL Server 2022 permissions implied by VIEW DEFINITION, does not grant permission to change data and is accepted by this check. Permission changes are checked on each execution. The fixed refusal says “Use a read-only database account for written queries.” Existing saved server-query catalogs keep their existing execution behavior.
SQL discovery
Leave Schema empty to discover the account's default schema. For MySQL and MariaDB, Default database optionally chooses the discovery catalog; an empty value uses the connection's database. Inflow resolves a configured schema by exact name first, then by an unambiguous case-insensitive match, and reports the name it used. A missing schema must be corrected in Settings.
Discovery generates List reads for tables and views, including tables without a primary key. A list returns at most 100 rows. Tables with a usable primary key also offer a read by key. Database names outside Inflow's supported identifier grammar are omitted with a summary.
A partial preview reports how many tables were described. If enumeration did not finish, its total is a lower bound, shown as “at least”; it does not claim a complete catalog. Tables that have not been described remain pending and offer no operation until a fresh discovery search describes them.
New JDBC template versions support This account has no password. Select it explicitly in the credential form only when the database account requires no password. The username remains required. Optionality comes from the system's trusted template version; older versions keep their existing requirements. Changing a template does not rewrite existing published systems.
JDBC Approved Queries
JDBC connectors execute database reads through approved query definitions, not raw SQL from workflow variables.
Approved query XML files are loaded from:
conf/queries/
The seed catalog is:
conf/queries/platform-approved-queries.xml
Example:
<query id="identity.active-users">
<connectorId>postgresql</connectorId>
<readOnly>true</readOnly>
<maxRows>100</maxRows>
<sql><![CDATA[
SELECT id, username, display_name, email, active
FROM user_accounts
WHERE active = :active
ORDER BY username
]]></sql>
<parameters>
<parameter name="active" type="boolean" required="false">
<defaultValue>true</defaultValue>
</parameter>
</parameters>
</query>
The JDBC connector operation is:
run-approved-query
Execution input:
{
"queryId": "identity.active-users",
"parameters": {
"active": true
},
"maxRows": 50
}
Safety rules:
- The query id must exist in the approved-query catalog.
- If the query declares
connectorId, it can only run through that connector. - Required parameters must be present.
- The JDBC executor admits permitted
SELECTandWITHqueries through its lexical gate.WITHremains classified as potentially writing for confirmation and outcome reporting; a failed or unprovable outcome is never treated as a harmless read. - Row count is capped by the approved query
maxRows; caller-requestedmaxRowscannot exceed it. - The executor does not append dialect-specific SQL such as
LIMIT, so approved SQL remains portable across engines. - Result masking and AI exposure are controlled by approved-query metadata.
Approved-query metadata supports these policy keys:
{
"category": "identity",
"pii": ["email", "display_name"],
"aiExposure": "masked",
"maskingEnabled": true,
"cacheSeconds": 300
}
pii
Lists result columns that contain sensitive values. Matching is
case-insensitive. When masking is enabled, those columns are returned as
[MASKED].
aiExposure
Controls whether rows can flow into workflows, reports, connectors, and AI tasks:
safe: rows are allowed as-is unlesspiialso declares columns.masked: rows are allowed, but declaredpiicolumns are masked.metadata-only: row data is suppressed; metadata still reports the original row count.blocked: execution is rejected withAPPROVED_QUERY_AI_EXPOSURE_BLOCKED.- missing or
internal: rows are allowed, withpiimasking still applied when configured.
maskingEnabled
Defaults to true. Set it to false only for approved derived values that are
safe to expose even if their column names overlap with a sensitive field name.
cacheSeconds
Enables connector-level result caching for the approved query. The cache key is
derived from connector id, query id, normalized parameters, and effective
maxRows. Set cacheSeconds or ttlSeconds to 0 or omit it to disable
caching.
Callers can force a fresh database read by passing bypassCache=true or
noCache=true in execution input or options.
Workflow designers can invalidate approved-query cache entries with:
service.data.cache.invalidate
Supported scopes are:
key: remove one exactcacheKey.prefix: remove every entry whose key starts withcacheKeyPrefix.all: clear the approved-query result cache.
JDBC execution metadata includes aiExposure, piiColumns,
maskedColumns, maskingApplied, rowsSuppressed, originalRowCount,
cacheKey, cacheTtlSeconds, cacheHit, and cacheBypassed.
Workflow service task:
service.data.query
uses implementation:
connector-jdbc
Seed Coverage
The starter catalog includes connectors for:
- automation: n8n, Make
- CRM and work systems: Salesforce, HubSpot, Zoho CRM, ServiceNow, Jira, GitHub
- collaboration and documents: Slack, Microsoft Teams, Microsoft Graph, Google Sheets, Google Drive, Google Calendar, Microsoft Excel, SharePoint, DocuSign, Adobe Acrobat Sign
- commerce and communication: Stripe, PayPal, Shopify, Twilio, SendGrid, WhatsApp Business, signed webhooks
- ERP: SAP, Oracle Fusion, Dynamics 365
- databases and warehouses: PostgreSQL, MySQL, SQL Server, Oracle Database, Snowflake, MongoDB
- messaging: Kafka, RabbitMQ
- AI providers and runtimes: OpenAI, Anthropic, Gemini, Ollama
This is a catalog foundation, not a claim that every external API executor is finished. Each connector entry is a contract that a Java ConnectorExecutor can implement.
Authoring validation diagnostics
Every Integration consumer shares AuthoringValidationDiagnostic: stable code,
severity (ERROR/WARN/INFO), category (syntax, type, nullability,
cardinality, pin, readiness, output, idempotency), consumer, typed location,
sanitized message, and required corrective guidance. Locations route Studio to
the exact mapping, control, or node. The sanitizer never returns stack frames,
Java exception types, or secret-bearing text. Existing Integration finding JSON
is unchanged; IntegrationValidationDiagnostics adapts it onto the shared
envelope.
Authoring test evidence
Rule, Interface, and later Process/Fabric authoring tests share one evidence
envelope (AuthoringTestEvidence) and one policy (AuthoringTestPolicy):
- Discriminated
FIXTUREandLIVEmodes. - Resolved inputs, sanitized request, response summary, mapped output, exact pins, duration, and redacted diagnostics.
- Surface-specific fields belong in
context(surface=RULEorINTERFACEtoday). - Policy redacts secrets, caps each stage at 1 MB, requires explicit confirmation before a mutating live dispatch, uses a 30-second live timeout, and publishes the fixture retention budgets (50 MiB per Integration, 250 MiB per workspace).
Existing Rule and Interface JSON fields remain. Those records also emit the
shared evidence object so Studio and later surfaces can render one trace.
Extension Rules
When adding a connector:
- Give every connector a globally unique
id. - Give every operation inside a connector a unique
id. - Keep secrets out of XML. Use
credentialReference, such assecret:...,oauth:..., orenv:.... - Set
metadata.categoryconsistently so capability summaries can classify connectors. Common values includeautomation,database,warehouse,file,event-stream,message-queue,ai,crm,erp, andspreadsheet. - Use operation types deliberately:
READ/SEARCHfor read capability,CREATE/UPDATE/DELETE/PUBLISHfor write capability,TRIGGERorEXECUTEfor trigger capability, andAI_INFERENCEfor AI provider capability. - Put vendor-specific behavior in a Java
ConnectorExecutor. - Put business relationships in Fabric, not in the connector definition.
Failure Modes
Startup/import validation rejects:
- duplicate connector ids
- duplicate operation ids inside one connector
- malformed JSON in
metadata,inputSchema, oroutputSchema
Execution fails fast when:
- the connector does not exist
- the operation does not exist
- the connector is disabled
- no Java executor supports the connector protocol
Next Steps
- SDK executor template for vendor-specific clients.
- Webhook subscription and inbound event mapping.
- Connector-backed service task executor.
Publishing a connection version
Publish version saves unsaved edits, then publishes the tested draft as the next immutable version. The new version appears in Published connection versions and the toast says "Published version N".
If published consumers depend on this connection, the server asks for an impact review first. The review opens; choose what happens to each pinned consumer and select Publish. Studio commits the review and publishes once more. Cancelling the review publishes nothing.
When publishing fails, the page says what happened and the latest version stays as it was:
- "The version was not published. The server could not complete the request. Try again." — the server or the network failed.
- "The version was not published. This is not available to you." — the connection, or your access to it, is not available.
- "The version was not published. Check the draft and test the connection again, then publish." — the server refused this draft.
- A newer server version opens the conflict dialog: reload or reapply, then publish again.
After a publish, Publish version stays disabled with "No changes since version N." until the draft is changed and saved; a draft that already equals the latest version shows the same. If the server finds nothing new it answers "The version was not published. Nothing changed since the latest version." and no version is created.
Nothing in the browser blocks a later attempt. A lost response can be retried; if the first attempt did publish, the retry is refused because nothing changed. Publication without an impact review requires connection-management access; an impact review also requires integration-management access. Publication controls are absent when management access is denied, and the server authorizes every request.
Oversized text in SQL results
A returned text value beyond the storage limit is refused rather than truncated. The test result names the returned column, for example: “Column ‘notes’ holds more text than Inflow can store in one value.” Change the query to return a smaller value. Binary or collection-size refusals keep their existing general guidance. Failed execution evidence contains the field path and fixed size rule, never the refused value.