Inflow.aiDocs

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
  • input as a VariableMap
  • options as 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: SUCCEEDED or FAILED
  • 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=true permits HTTP destinations that otherwise pass the address policy. It defaults false and requires a restart; INFLOW_CONNECTOR_OUTBOUND_ALLOW_HTTP is 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 exact cacheKey.
  • prefix: remove every entry whose key starts with cacheKeyPrefix.
  • 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:

  • database
  • api
  • file
  • event
  • automation
  • ai-provider
  • read
  • write
  • trigger
  • subscribe
  • publish
  • ai-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 ConnectorExecutor supports the connector
  • operationalStatus: READY, NEEDS_ATTENTION, or DISABLED
  • 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 ConnectorExecutor implementations
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, or DISABLED
  • executorSupported
  • credentialConfigured
  • operationCount
  • 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 Java ConnectorExecutor.
  • If credentialConfigured=false, add a credential reference such as env:OPENAI_API_KEY, secret:n8n-api-key, or oauth: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:

  • NONE
  • API_KEY
  • BEARER_TOKEN
  • OAUTH2
  • OIDC
  • SAML2
  • BASIC
  • HMAC as 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} with sysparm_query and sysparm_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=true
  • output.response: parsed JSON response map
  • externalReference: best-effort id from fields such as id, runId, executionId, key, or sid
  • 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, or kafka for the Kafka connector.
  • topic: from input/options or the expanded operation path.
  • messageKey: from messageKey or key.
  • messageName: from input/options, operation metadata, operation name, or operation id.
  • aggregateType: from input/options or connector id.
  • aggregateId: from input/options or key.
  • payload: from payload; 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: from preferredModelId or modelId.
  • requiredCapabilities: from a list or comma-separated string; defaults to CHAT.
  • prompt: from prompt, text, options, operation description, or a generated fallback.
  • input: remaining request input plus nested input values.
  • constraints: nested constraints plus keys such as dataClass, responseFormat, temperature, maxTokens, and topP.
  • 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 method and path
  • every connector should declare metadata.category
  • authored extension packs, identified by metadata.extensionPack, should give every operation a description, inputSchema, and outputSchema
  • JDBC read operations should go through approved query ids
  • AI provider connectors should expose AI_INFERENCE operations

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

  1. Call the preview endpoint with the connector and first operation.
  2. Review the generated XML, metadata, schemas, and credential reference.
  3. Save the connectorXml response to the suggested connectorPath.
  4. Add more <operation> entries if the connector has multiple capabilities.
  5. Make sure a ConnectorExecutor supports the connector protocol.
  6. Run the platform test script.

Example test command:

.\scripts\container-test.ps1

Extension Design Rules

  • Use stable connector ids such as google-sheets, sap, or document-platform.
  • Put business grouping in metadata.category; Fabric and capability summaries use it for planning.
  • Use credentialReference instead 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 SELECT and WITH queries through its lexical gate. WITH remains 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-requested maxRows cannot 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 unless pii also declares columns.
  • masked: rows are allowed, but declared pii columns are masked.
  • metadata-only: row data is suppressed; metadata still reports the original row count.
  • blocked: execution is rejected with APPROVED_QUERY_AI_EXPOSURE_BLOCKED.
  • missing or internal: rows are allowed, with pii masking 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 exact cacheKey.
  • prefix: remove every entry whose key starts with cacheKeyPrefix.
  • 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 FIXTURE and LIVE modes.
  • Resolved inputs, sanitized request, response summary, mapped output, exact pins, duration, and redacted diagnostics.
  • Surface-specific fields belong in context (surface = RULE or INTERFACE today).
  • 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 as secret:..., oauth:..., or env:....
  • Set metadata.category consistently so capability summaries can classify connectors. Common values include automation, database, warehouse, file, event-stream, message-queue, ai, crm, erp, and spreadsheet.
  • Use operation types deliberately: READ/SEARCH for read capability, CREATE/UPDATE/DELETE/PUBLISH for write capability, TRIGGER or EXECUTE for trigger capability, and AI_INFERENCE for 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, or outputSchema

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.

Try “document generation”, “integrations” or “first form”.