App Console SDK v2

The flowgear-webapp package connects an embedded Flowgear App to its Console host. Use it to initialize Console theme support, read the current App context, invoke Workflow-backed endpoints, display Console feedback, and synchronize App navigation.

The SDK methods work when the App is embedded in the Flowgear Console. They exchange asynchronous messages with the parent Console and do not provide direct access to Connection values, API-key credentials, or other protected platform data.

The easiest way to get started with an app is to use a sample app, see Apps.

Import and initialize

The downloadable sample App already includes flowgear-webapp. Import Flowgear, then initialize the SDK before rendering the App:

import { Flowgear } from "flowgear-webapp";

await Flowgear.Sdk.init();

init() reads the Console theme and applies it to the document body:

  • data-theme contains the current Console theme identifier.
  • The body receives either theme-light or theme-dark.

Run the App over HTTPS and inside the Console. When it runs as a top-level page, the SDK logs development guidance but cannot complete host requests.

Method summary

Method Purpose
init() Initializes the embedded connection and applies Console theme attributes.
getContext() Returns the current Tenant, Site, user, Account, theme, and Environment context.
invoke<T>() Invokes a published Workflow endpoint through the Console and returns its typed response.
setAlert() Displays a Console alert.
confirmModal() Opens a Console confirmation dialog.
getTextModal() Opens a Console text-entry dialog.
openUrl() Opens a Console-relative or external URL.
setParentPath() Synchronizes a safe in-App route with the parent Console URL.

Read the App context

Call:

const context = await Flowgear.Sdk.getContext();

getContext() is currently typed as Promise<unknown>. The Console returns these fields:

Field Description
tenantKey Current Tenant key.
siteKey Current Site key.
username Signed-in Console username.
accountKey Account that owns the published App. It can be unavailable for a locally debugged App.
theme Simplified theme value: theme-light or theme-dark.
consoleTheme Complete Console theme identifier.
environments Environments available to the current user for this Site.
selectedEnvironmentKey Environment currently selected by the Console App host.

Treat context as environment and presentation information, not authorization. A signed-in username and selected Environment do not grant access to every Workflow.

Invoke a Workflow

Use this signature:

Flowgear.Sdk.invoke<T>(
  method,
  relativePath,
  payload?,
  headers?,
  tenant?
)
Argument Description
method HTTP method. Use uppercase values such as GET, POST, PUT, or PATCH. It defaults to GET.
relativePath Published Workflow route, including any path or query values. Use a path that begins with /.
payload Optional request body. Its shape must match the Workflow receive contract.
headers Optional string header map, including Content-Type when the payload requires one. Do not supply an authorization header.
tenant Optional Tenant target for an authorized cross-Tenant call. Omit it for the current Tenant.

Example:

type CustomerSummary = {
  id: string;
  name: string;
  status: string;
};

const customer = await Flowgear.Sdk.invoke<CustomerSummary>(
  "GET",
  `/customers/${encodeURIComponent(customerId)}`
);

The Console sends the request to the Environment selected by the App host. A Cookie-based Key must permit both the signed-in user and target Workflow.

When the Workflow call fails, invoke() rejects with the error returned by the Console request. Handle it and show a useful state; do not assume every rejection means the Console session expired.

Use the generated openapi.yml to discover methods, paths, payloads, and responses. Do not call embedded Workflow endpoints directly with fetch or axios.

Display alerts

Call:

await Flowgear.Sdk.setAlert(
  "Customer updated.",
  Flowgear.Sdk.AlertMessageTypes.Success,
  Flowgear.Sdk.AlertDismissOptions.Auto
);

AlertMessageTypes provides:

  • Info
  • Warning
  • Error
  • Success
  • Help
  • Running

AlertDismissOptions provides:

  • ViewChange — dismiss when the Console view changes.
  • Auto — dismiss automatically.
  • Tap — remain until the alert is selected or dismissed.

Ask for confirmation

Use a Console confirmation before a consequential action:

const result = await Flowgear.Sdk.confirmModal(
  "Retry invoice?",
  "This will submit the invoice to the ERP again.",
  "Retry"
);

if (result === Flowgear.Sdk.ConfirmResult.Yes) {
  await retryInvoice();
}

The result is ConfirmResult.Yes or ConfirmResult.No.

Ask for text

Call:

const result = await Flowgear.Sdk.getTextModal(
  "Add a note",
  "Explain why this invoice is being retried.",
  ""
);

if (result.result === Flowgear.Sdk.GetTextResult.Ok) {
  console.log(result.text);
}

The returned object contains:

Field Description
result GetTextResult.Ok or GetTextResult.Cancel.
text Text entered in the dialog.

Open a URL

Call:

await Flowgear.Sdk.openUrl("#t-acme/sites/site-key/workflows");
await Flowgear.Sdk.openUrl("https://example.com/help", "_blank");

Same-origin paths beginning with / and Console hash routes beginning with # can open within the current browser context. External URLs always open in a new tab, regardless of the supplied target.

Synchronize App navigation

Use setParentPath() after client-side navigation so the Console URL can preserve the App route:

const result = await Flowgear.Sdk.setParentPath(
  "/invoices?status=failed"
);

The path must:

  • Be a non-empty string no longer than 2,048 characters.
  • Begin with one /, not //.
  • Contain no backslashes or URL scheme.

The method resolves to { success: true } when the parent path is updated. An unsafe path returns { success: false, error } from the Console host.

Use a client-side router and call setParentPath() only when the route changes. Do not use it to trigger Workflow calls or create a render loop.

Security boundaries

The SDK provides a controlled bridge to the Console; it does not make browser code trusted. Validate all input again in the backing Workflow, keep secrets in server-side Connections, and scope Cookie-based Keys to the minimum users and Workflows.

See also

See App security model, Flowgear Apps, and Build an App with an agent for the surrounding architecture and delivery process.