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.

Consultant and operator Integration workflows

Build one explicit business contract

An Integration turns an actual connected-system operation into a reusable, versioned contract: named typed inputs, request bindings/mapping, output mapping/shape, paging and retry behavior. It is not a credential container and it is not an invitation to call any URL the browser supplies. Keep the service’s admitted address/credential ownership in the connected system; keep the business operation’s immutable meaning in the published Integration.

Use a safe teaching employee lookup before trying a mutating purchase or payroll operation. The operation should return only the fields needed by the application, use an admitted synthetic employee ID and expose an authoritative collection or single-record shape. An imported OpenAPI/WSDL description or successful discovery is a draft proposal; it does not publish an Integration or qualify the provider.

Step Retain Avoid confusing it with
Discover/import Source contract/fingerprint and selected operation A live execution or an authorization grant.
Create/update draft Actual draft ID, declared inputs and expected update token A published contract version.
Authoring test Exact input, request revision/fingerprint and safe execution evidence A reusable fake success response.
Save fixture Applicable exact draft/version/execution provenance Fresh provider execution.
Publish Actual immutable Integration version and any selected fixture Permission for every consumer/control.
Consume Supported exact versioned invocation and current actor/disclosure context A direct connector proxy with arbitrary internal options.

The reference below contains transport-specific details. The four complete cases teach operation selection, import, test/publication and change review. Continue with Integration and published API after the basic contract is clear.

Worked examples

Example DATA-INTEGRATION-01 — Discover an employee read with an explicit input/output worksheet

Scenario and inputs. Nadia’s owner-admitted teaching connected system exposes a nonmutating employee lookup. The application needs only an employee reference, display label and remaining-day data; it does not need the provider’s entire personnel record. The user’s visible name is not the provider’s or Inflow’s account ID.

Procedure. 1. Open the permitted connected system and select its actual discovered READ operation. 2. Record the operation identity, exact connection version and authoritative input names/types. 3. Define a minimal output shape and response mapping for only the admitted employee fields. 4. Review required inputs, defaults and any one-attempt preview limitations before connecting a consumer. 5. Create the Integration draft through the supported authoring surface, then read back its actual ID and request-validation findings. 6. Keep credentials out of the payload, output schema and documentation.

Expected result. The saved draft explains a specific business call whose required inputs and output shape can be reviewed. It does not automatically execute the provider, publish a version or let an application user choose another connection by typing a different label.

Failure and recovery. If output shape is unknown, a required selector has no admitted value or the service lacks a supported nonmutating operation, keep the consumer unavailable. Correct the actual discovered contract or ask its owner for the missing capability; do not invent example response rows or add a hidden live lookup.

Sources. IntegrationController.java, IntegrationController.java.

Example DATA-INTEGRATION-02 — Import only a reviewed OpenAPI selection as drafts

Scenario and inputs. A service owner provides an authorized OpenAPI document for the synthetic employee service. Nadia wants to import one lookup rather than every operation and credential hint in that description. The source may be inline content or an admitted URL; the example does not authorize fetching an arbitrary external address.

Procedure. 1. Use the actual OpenAPI preview surface at /api/connected-systems/import-openapi/preview with the approved content/url choice. 2. Review proposed system/operation shapes, transport addresses and any unsupported findings. 3. Select only the intended READ operation and retain the returned preview fingerprint. 4. Apply through /import-openapi/apply with that exact source, fingerprint and selected draft objects, including explicit changed-operation decisions when applicable. 5. Read the resulting drafts, complete their actual credential/default/mapping requirements and review them before any provider test.

Expected result. Preview proposes unsaved drafts; Apply persists the reviewed selection as drafts and never publishes them. A fingerprint/source mismatch cannot be solved by pretending a newly fetched contract is the one Nadia previously reviewed.

Failure and recovery. If an address is denied, operation unsupported or source changed, preserve the original preview and resolve the actual owner/source decision. Do not bypass egress policy with a proxy or apply an unreviewed entire specification just to make import report success. Publication and live execution remain separate later actions.

Sources. OpenApiImportController.java, OpenApiImportController.java.

Example DATA-INTEGRATION-03 — Retain an exact test fixture and publish its contract

Scenario and inputs. Nadia has a saved employee-read Integration draft with typed inputs, an output shape and an admitted synthetic test identity. The operator has allowed the specific provider test. A useful fixture must identify the actual saved request/execution state rather than borrowing a successful response from a different draft or connection.

Procedure. 1. Review the draft’s /test-readiness and /request-validation findings and complete required defaults/mappings. 2. Execute only through the supported draft/version test path and honor any server-authored live confirmation challenge. 3. Retain the actual execution ID, request revision/fingerprint and sanitized result. 4. Save a fixture through the owning draft fixture surface with the exact supported provenance; do not fabricate the validation message or success. 5. Publish using /drafts/{draftId}/publish-version, passing the actual selected fixtureId where needed. 6. Read the immutable published contract and version for downstream consumers.

Expected result. The published Integration has a coherent input/output contract and reviewed provenance from its actual authored/tested state. A saved fixture is evidence for that state; it does not prove every future provider call or grant runtime consumers a broader permission.

Failure and recovery. If the draft/connection changed after the test, re-evaluate the specific changed request and review requirements instead of reusing an unrelated old success. An uncertain test outcome requires exact execution reconciliation, not repeated provider attempts or a new confirmation/idempotency intent invented by the client.

Sources. IntegrationController.java, IntegrationController.java.

Example DATA-INTEGRATION-04 — Review changed discovery without rewriting published history

Scenario and inputs. The external service adds a new field and changes one operation while an existing published Integration is used by rules and screens. Nadia needs to refresh discovery and decide what to adopt. A currently working consumer must not silently start using a new draft or connection because the display key stayed the same.

Procedure. 1. Preserve the exact published Integration and connection coordinates used by each consumer. 2. Run the supported discovery/import diff on the approved source and inspect additive changes, removals and changed operations. 3. Make explicit decisions for the selected drafts and review any lifecycle/consumer impact. 4. Create a new draft from the supported prior version when rollback-style authoring is needed, using its actual concurrency token rather than rewriting history. 5. Validate/test/publish the reviewed replacement and intentionally update only compatible consumers. 6. Retain old versions and retirement evidence under their existing policy.

Expected result. Published contracts remain immutable historical coordinates. A new field in discovery is not automatically a new exposed field in an old interface; consumers move only through their supported publication/lifecycle path.

Failure and recovery. If a source or consumer is denied, treat it as unavailable instead of enumerating hidden dependencies. A stale timestamp, changed fingerprint or incompatible shape requires reload/review, not a blind update or deletion of prior versions. Coordinate the exact affected owner before retiring a version still used by admitted consumers.

Sources. IntegrationController.java, IntegrationController.java, OpenApiImportController.java.

Detailed reference

Status: Current reference

Audience: consultants who connect business systems, and operators who recover failed connections without collecting secrets.

This page is the task-oriented guide. Technical catalogs, executor APIs, and architecture specifications stay in the linked manuals. When this page and a historical specification disagree, current code and this current-reference manual win.

What you will do here

  1. Connect an exact published system version.
  2. Discover or import operations into Integration drafts.
  3. Test, publish, and consume those Integrations from Rules, Process, Fabric, and Interfaces.
  4. Refresh discovery, review impact, and recover failures without exposing credentials.

Before you start

You need a workspace and access to the Connected System you will change. Discovery preview requires Connected System Viewer plus the three permissions below. Apply, import, and draft mutation require Connected System Editor.

  • CONNECTED_SYSTEM_MANAGE on the exact Connected System
  • CONNECTOR_EXECUTE on that same system (discovery preview and apply)
  • INTEGRATION_MANAGE for Integration drafts

Runtime consumers additionally need permission to run the calling artifact, INTEGRATION_EXECUTE on the Integration, and CONNECTOR_EXECUTE on the pinned system. Catalog visibility is not execution permission.

Credentials stay in the vault. Discovery resolves them only for the audited CONNECTED_SYSTEM_DISCOVERY purpose. Never paste passwords, tokens, cookies, API keys, or Authorization headers into drafts, tests, tickets, or logs.

Studio entry points:

  • Systems gallery: /workspaces/{workspaceKey}/integrations
  • Connected System: /workspaces/{workspaceKey}/integrations/systems/{systemKey}
  • Integration workbench: /workspaces/{workspaceKey}/integrations/{integrationKey}

Discover operations

Use this path when the Connected System already exists and the provider can describe its contract (OData, Salesforce Describe, ServiceNow tables, JDBC schema, Mongo collections, S3, Redis, GraphQL introspection, and similar catalogs).

  1. Open the exact Connected System version you intend to change. Discovery is workspace- and version-scoped. A missing or foreign version is hidden as not found.
  2. Preview the catalog. Preview does not create drafts. Search, if offered, is a filter; it is not stored on the discovery audit event.
  3. Review coverage. An ERROR catalog blocks apply (OPERATION_DISCOVERY_CATALOG_INCOMPLETE). Partial coverage may still apply the operations that were successfully described; it never infers removals.
  4. Select operations and apply. Apply refuses a stale snapshot: if the external contract changed after preview, rediscover first.
  5. Review impact for revised or retired operations. Published consumer contracts stay immutable; unsafe impact blocks the batch.

Discovery attempts record INTEGRATION_DISCOVERY_ATTEMPTED with actor, exact system/version, provider, outcome, counts, and duration only. Credentials, headers, search strings, sample rows, URLs, and unrestricted schema content are not retained. Successful apply still also records the mutation summary INTEGRATION_DISCOVERY_APPLY_RECONCILED.

GraphQL introspection is opt-in. Mutations discovered that way stay UNVERIFIED until a consultant confirms risk and idempotency.

Connect a GraphQL service

Use a GraphQL connected system. A Generic HTTP system that happens to post to a /graphql address is still judged by HTTP status and will not apply these rules.

  1. Connect the system with GraphQL template version 2. Set the address (it usually ends in /graphql) and a sign-in of None, API key, or Basic. None is the default. An API key is sent in a header, by default Authorization: Bearer <key>. A key placed in the query string is refused and is not saved. Store the key in the vault.
  2. Test the connection. A success reads "Connection test succeeded. The GraphQL service answered." Publish stays closed until that test succeeds. A refused sign-in, an address that is not GraphQL, and a private or http address each have their own sentence. Fix that sentence before publishing.
  3. Allow schema discovery only when you want Inflow to read the service's list of queries and changes. The switch is off by default. It takes effect when you publish the system.
  4. Publish the system.
  5. Discover operations, or add one by hand. Discovered mutations stay UNVERIFIED until you confirm risk and idempotency. If the service does not allow its schema to be read, the message tells you to add operations with New integration.
  6. From Add template operations, pick Run a query. That creates an integration with a required text input query and an optional record input variables. A change document (a mutation) in that query is refused. There are no request bindings to fill in.
  7. Map the response, publish the integration, and call it from a lifecycle step. When the service returns usable data together with errors, the step completes and integrationStatus is SUCCEEDED_WITH_WARNINGS. Route a review path with integrationStatus == "SUCCEEDED_WITH_WARNINGS". The workbench shows "Test succeeded with warnings" for the same result.

Connect SAP Gateway

SAP ABAP Gateway appears as an OData Connected System.

  1. Publish the system with the SAP OData template and a vault credential reference, not a pasted password.
  2. Discover entity sets and operations from the exact version.
  3. Create only the READ/SEARCH/CREATE operations you need. Writes stay UNVERIFIED until tested with an explicit mutation intent.
  4. Map Integration inputs to OData keys and fields. Do not copy CSRF tokens, cookies, or raw URLs into Integration metadata.

If discovery returns nothing, treat it as an authorization or catalog bound — not as permission to invent operations.

Import OpenAPI

Use this path when the system publishes an OpenAPI document.

  1. Preview the document against the exact active Connected System. Preview is read-only.
  2. Confirm the source fingerprint. Hostile or oversized documents fail closed (size, nesting, YAML alias, and decompressed gzip bounds).
  3. When the document lists more than one server or more than one usable authentication scheme, choose explicitly before apply. A URL or scheme that is not in the reviewed document is rejected. The default proposal is the first documented server and a deterministic non-OAuth2 scheme when both are offered.
  4. Request and response content types, parameter style/explode (OpenAPI 3) or collectionFormat (Swagger 2 arrays), and selected 2xx status are stored on the Integration draft. Unsupported media types, callbacks, links, and ambiguous oneOf/anyOf stay visible as diagnostics; unambiguous allOf object composition is merged.
  5. Apply selected operations. Application is transactional: a later failure leaves no partial drafts.
  6. Generated Integration keys follow the expression-safe key grammar. Credentials from the spec are not copied into Integration metadata.
  7. No import path publishes or registers an operation implicitly. Publish is a separate, authorized step.

Reimport diffs the new fingerprint against the stored source. Stale selections must be revalidated before mutation. New operations may be added. Changed operations show contract diffs and published consumer pins; the consultant keeps or replaces consultant-owned sections (labels, request contract, response mapping, examples) as an explicit draft revision. Removed operations and published versions are never deleted automatically.

Import WSDL

WSDL import uses the same preview / apply / diff contract as OpenAPI.

  1. Preview against the exact Connected System.
  2. Fail closed on XXE, document size, element count, nesting, and parse deadline. Diagnostics stay redacted.
  3. Apply selected operations transactionally.
  4. SOAP credentials remain vault references. Do not paste WS-Security material into drafts or tickets.

SOAP operation settings

A SOAP Integration draft requires an operation name (soapInputElement) before publication: at most 200 characters, starting with an ASCII letter or _, then ASCII letters, digits, ., -, or _. For example, NumberToWords is valid; ns:NumberToWords is not. The optional namespace (soapInputNamespace) must be an absolute http, https, or urn URI when supplied. It identifies an XML namespace; it is not a network destination and does not change outbound address policy.

An incomplete draft can still be saved. Draft validation reports a missing operation name, an invalid operation name, or an invalid supplied namespace, and publication refuses those findings. Existing immutable published versions without soapInputElement keep using the operation identifier as the request element name; this validation does not change or republish them.

Author, test, and publish an Integration

  1. Open the Integration workbench for the draft created by discovery, template, OpenAPI, or WSDL.
  2. Bind inputs and outputs with the shared type vocabulary. Required and nullable facts come from the discovered contract, not from guesswork.
  3. Run a fixture test for safe reads. Live mutations require a short-lived server-minted intent for the exact actor, workspace, pins, and payload. DELETE also requires the exact typed confirmation phrase. A discovered database read rooted at $.rows[*] treats zero rows as a successful empty result, in the workbench and in a case. A record lookup leaves every mapped field empty, including fields marked required, and the call details record that nothing matched, so the case can follow a not-found path. A list lookup returns an empty list. A missing rows entry, a list where one record was expected without a row selector, or an object where a list was expected is still a mapping failure. A database error is still a failed call. Nothing matched is not a new screen or a new business field.
  4. Publish an immutable version. Consumers pin that version. Publishing v2 never changes a consumer still pinned to v1. If the server refuses the publish, the workbench keeps the server's reason in a persistent Publish was rejected callout until the next publish attempt, a reload, or a change to the draft's contract. Mapping problems also open Map the response and focus the failing control. The server reports one problem per attempt, so fix it and publish again to see the next one. For an Integration that returns data, Publish stays disabled, with a Saved example required explanation, until a successful saved example matches the current request.

Immediate errors expose a correlation id, not exception text or request bodies.

Refresh discovery and review impact

Refresh is rediscovery of the same exact system version.

Discovery uses a shared wall-clock budget (30 seconds by default) and provider-specific caps. Outbound metadata HTTP does not start after the budget elapses. A node admits a small number of concurrent discovery previews and applies; additional callers receive OPERATION_DISCOVERY_BUSY and should retry shortly. Limit hits emit explicit partial diagnostics and count-only metrics without search strings, URLs, or credentials. Cancelled or overdue discovery does not retry in a loop.

  • Unchanged operations stay put.
  • Changed operations require an explicit revise action and section replacement choices.
  • Removed operations require an explicit retire action. Incomplete coverage never infers removal.
  • Impact review lists published Rules, Processes, Fabric sources, and Interfaces that pin the current version. Unsafe consumer impact blocks apply.

If apply reports OPERATION_DISCOVERY_SNAPSHOT_STALE, rediscover. Do not retry the old fingerprint.

Go back to an earlier connection version

On the connection page, "Published connection versions" lists every published version of the connection.

  1. Choose Create draft from v<n> on the version you want. A confirmation explains what happens. Confirm with Replace draft.
  2. The connection's own draft takes that version's settings. The connection keeps its key, and its Integrations keep using it. No second connection is created.
  3. Test the draft, then publish it. It becomes the next version. Earlier versions, and the processes and Integrations that pin them, do not change.

If the version uses a different sign-in method, enter its credentials before testing.

To make a separate connection from a version, open the row's More actions menu and choose Copy as a new system. The copy has its own key. The Integrations of the original connection do not use the copy.

Use a published Integration in Rules

Pick the immutable published Integration version, map typed Rule inputs, and execute through the shared Integration runtime. Rules do not author raw HTTP, OAuth, or connector registries. Secret-shaped mapped values fail closed before they reach Rule state.

See Integration consumption for the typed contract, and Rule types for kind behavior.

Use a published Integration in Process

Process Designer uses service.integration.invoke with an exact published binding. Publication re-checks pins and fingerprints. Mutations need a stable process-variable idempotency path. Runtime re-authorizes the effective actor or provisioned service account, then calls the same Integration boundary.

A lookup does not ask for a retry-safe key. A published Read or Search — including a POST search, a GraphQL query, and a SOAP read — hides Idempotency key, is not marked as a change, and is called again for every case. A key left on the step from an older workaround is ignored. The same lookup's test does not say it can create or change data and does not ask you to confirm a change.

When you choose an Integration that changes data, the step records that it needs a retry-safe key (SCRUM-4467). Until Idempotency key names one case variable, for example requestId, the step reads Needs setup and Verify reports the same finding Publish refuses (PROCESS_INTEGRATION_IDEMPOTENCY_REQUIRED): The step "Update customer" changes data in another system, so it needs a retry-safe key…. Every Integration step refusal names the step by its name, never by its internal id; a step with no name reads "An unnamed Integration action step". A step saved before this change carries no such record, so Verify cannot tell; choose its Integration again, or Publish refuses it with the same words. The same value on this step of this published lifecycle reuses the first result, including in another case; the case timeline says "Replayed earlier result", and the audit record of that reuse still omits the value.

Unknown remote outcomes park the process token with the durable receipt instead of succeeding or silently retrying.

See Process definition persistence.

Use a published Integration in Fabric

Fabric consumes published Integrations as governed API-backed sources: keyed lookup, collection, or replicated collection. Fabric does not store credentials or treat an arbitrary API as a relational table without an explicit contract.

See Fabric.

Use a published Integration in Interfaces

Interface automations select a published Integration action, map screen or record fields into typed inputs, and store bounded results locally. Drafts cannot be invoked from a published Interface. Publish validation uses the same gates as requirePublishable.

Studio Interface designer: /workspaces/{workspaceKey}/design/interface/{draftId}. The Integration picker is the same shared catalog used by Rules and Process.

See Interface Builder manual.

Credentials

  • Store secrets only in the credential vault. Integrations keep a reference, never the secret value.
  • Discovery uses CONNECTED_SYSTEM_DISCOVERY. Runtime execution uses the connector execution purpose. Treat vault references as ids only; never document or paste the secret value they resolve to.
  • OAuth and OIDC finalization happens on the server. Do not paste callback codes, refresh tokens, or client secrets into this guide, a ticket, or a screenshot.
  • Salesforce live OAuth replay is a gated journey. Do not invent a bypass.

Permissions

Task Required authority
Preview discovery CONNECTED_SYSTEM_MANAGE, CONNECTOR_EXECUTE, INTEGRATION_MANAGE, Connected System Viewer
Apply discovery the preview set plus Connected System Editor
Import OpenAPI or WSDL CONNECTED_SYSTEM_MANAGE, INTEGRATION_MANAGE, Connected System Editor
Publish an Integration version INTEGRATION_MANAGE and workspace Editor on the Integration
Invoke a published Integration caller-artifact permission, INTEGRATION_EXECUTE, CONNECTOR_EXECUTE on the pinned system
Read audit evidence AUDIT_VIEW in the same workspace

Denied discovery still records a sanitized attempt when the HTTP boundary rejects the caller. Foreign or missing versions are not distinguished from not found.

Safe troubleshooting

Share only:

  • workspace id (from the signed-in context, not from a guessed header)
  • Connected System id and version
  • Integration key and published version
  • provider key (odata-v2, salesforce-describe, graphql-introspection, …)
  • stable error code (ACCESS_DENIED, OPERATION_DISCOVERY_SNAPSHOT_STALE, …)
  • correlation id from the error surface
  • outcome and counts from audit (success, denied, partial, failed)

Never share or request:

  • passwords, API keys, tokens, cookies, CSRF headers, or Authorization values
  • vault secret payloads (ids and fingerprints only)
  • sample rows, document bodies, or unrestricted schema dumps
  • raw exception text, stack traces, or rediscovered URLs
  • OAuth codes, refresh tokens, or client secrets

If a mutation test is blocked, re-issue the server intent after any edit. Do not reuse a confirmation phrase from another environment.

Local lab sign-in is documented in the identity manual and is not a production credential. See Identity configuration.

Workflow effectiveness telemetry

Operators may opt in to count-only consultant-workflow effectiveness events. The switch is deployment-scoped and default off:

integration.telemetry.workflow.enabled=true

Set it back to false (or leave it unset) to opt out. No client beacon is sent, and Studio does not collect these events locally.

Event type: CONSULTANT_WORKFLOW_OBSERVED. Schema: consultant-workflow-v1. entityType is consultantWorkflow. entityId is the allowlisted step, not a system or Integration id. Authorized operators query the existing audit surface:

GET /api/audit-events?type=CONSULTANT_WORKFLOW_OBSERVED
Step When it is recorded Outcomes
discovery_preview Server preview of a connected-system catalog completed, partial, denied, failed
discovery_apply Server apply of a reviewed discovery batch completed, partial, denied, failed
manual_fallback Consultant created a draft without discovery, template, or import provenance completed
validation Not recorded on GET .../request-validation (Studio polls that route). Recorded when publish or a consultant test is blocked by a request-contract finding failed plus allowlisted category (finding code only)
test Consultant draft or published-version test actually executed completed, denied, failed plus mode safe or live
publication Publish succeeded or the domain rejected it completed or failed

Abandonment is derived: count discovery_preview minus count discovery_apply in the same workspace and window. There is no session identifier.

Never stored: credentials, headers, payloads, resource names, URLs, search strings, user-entered expressions, Integration keys, or connected-system ids. Unknown steps, outcomes, modes, and categories are dropped. category accepts only platform prefixes (INTEGRATION_, EXPRESSION_, CONNECTED_SYSTEM_, OPERATION_, ACCESS_, ACTOR_, CONNECTOR_). Retention follows audit_events (see Logging and retention); audit legal-hold remains the G4 compliance gap and is not a separate product- analytics store.

Technical appendix

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