Building Apps

Build JavaScript and React apps that embed directly into the Flowgear Console to create rich user experiences. Apps run in an iframe at https://app.flowgear.net and all data access goes through Flowgear Workflows via the SDK.

Flowgear Apps invoke native and Site-specific APIs through the current user's security context. This lets the web app stay mostly front-end while Workflows provide business logic and data access.

Use cases you might build:

1. Custom dashboards for your integrations
2. Utilities to diagnose and resolve integration errors
3. Office administrative apps

The sample app repository can be reached at Flowgear Sample App or from your console at: https://app.flowgear.net/#t-{tenantKey}/apps (Settings → Manage Apps → Clone a Sample App).

---

Requirements

1. Node.js and npm (download)
2. Visual Studio Code (or another editor)
3. Git (if cloning the sample)
4. Flowgear permissions:
   • To publish an App: app-publisher or account-administrator
   • To add an App to a Site: site-administrator
   • To invoke Workflows: create an API Key of type Cookie and assign users and Workflows per environment
5. Valid Flowgear environment hostname configured (Settings → Site settings → Environments → Allowed Origins / Host names)
6. NPM packages used by the sample (installed via npm install):
   • React 19 + React DOM 19
   • Vite 7, TypeScript 5.9, @vitejs/plugin-react, @vitejs/plugin-basic-ssl
   • flowgear-webapp (Flowgear SDK), Bootstrap 5.3, Sass

Optional helper: Codex AI

• Use ChatGPT Codex (CLI or VS Code extension) for “vibe coding” with the project automation guidance in AGENTS.md.
• Open AGENTS.md to give Codex the Flowgear-specific rules (always call Flowgear.Sdk.invoke with relative URLs, etc.).
• Codex can read openapi.yml to discover available endpoints; download that file from the Cookie-based API Key detail page in the console and place it in the repo root.

---

Run the sample app

1. Clone the Flowgear Sample App repository.
2. Run npm install in the project directory.
3. Ensure your Site has a Workflow with an API Binding (reach out to support if your domain is not configured). Use relative paths that match the HTTP Binding when invoking.
4. Add a Variable Bar with FgResponseBody and sample data such as:

   [
     { "Id": 325, "Description": "Order A1455", "Status": "shipped", "OrderNumber": "A1455", "OrderDate": "2023-10-26", "OrderTotal": 500.23 },
     { "Id": 328, "Description": "Order A1458", "Status": "placed", "OrderNumber": "A1458", "OrderDate": "2023-10-27", "OrderTotal": 260.5 }
   ]
   

5. Add FgResponseCode = 200 and FgResponseContentType = application/json, then save the Workflow.
6. Create an API Key of Type Cookie, assign the allowed users and Workflows per environment.
7. Create .env.local in the project root with at least:

   FG_DEV_TENANT=yourTenantKey
   FG_DEV_SITE=yourSiteKey
   

   Optional overrides: FG_DEV_PROTOCOL (https default), FG_DEV_HOST (localhost), FG_DEV_PORT (3000).
8. Run the dev server:

   npm run dev
   

9. The dev server uses a self-signed cert via @vitejs/plugin-basic-ssl. Two tabs auto-open:
   • Local app URL (accept/trust the certificate here first).
   • Flowgear Console debug URL: https://app.flowgear.net/#t-{tenant}/sites/{site}/apps/debug/?debugUrl={encoded-local-url}.
10. If the app does not load immediately in the console, refresh after trusting the cert.

---

Building your own app

We recommend starting from the sample, but you can bootstrap a new project with Vite + React + TypeScript if preferred:

npm create vite@latest my-directory -- --template react-ts

Set base: './' in vite.config.* and add @vitejs/plugin-basic-ssl if you need HTTPS locally.

Initializing the app

Install the Flowgear SDK:

npm i flowgear-webapp

In src/main.tsx or src/index.tsx (entry point), register with the console before rendering:

import { Flowgear } from 'flowgear-webapp';

Flowgear.Sdk.init();

Using the SDK

• init() configures messaging between the iframe and the console.
• invoke(method, relativeUrl, payload?, headers?, tenant?) calls published Flowgear Workflows. Use the HTTP method and relative URL from your HTTP Binding (do not include the base host). No manual auth headers are needed.
• UI helpers: confirmModal, getTextModal, setAlert, openUrl.
• If you hit CORS issues, ensure the environment hostname is listed in Allowed Origins/Hostnames for the Environment.

Debugging in the console

Use the Flowgear debug URL (with your tenant and site keys):

https://app.flowgear.net/#t-{tenantKey}/sites/{siteKey}/apps/debug/?debugUrl={encoded-local-url}

The sample’s dev server opens this automatically when FG_DEV_TENANT and FG_DEV_SITE are set.

---

Publishing your app

1. Prepare public/app.json (manifest). Example:

   {
     "Name": "SampleApp",
     "Version": "1.0.0.0",
     "DisplayName": "Sample App",
     "Rank": 1
   }
   

   • Name must be globally unique (e.g., your-company.your-app).
   • Increment Version every publish.
   • Rank controls embed order within the console.
2. Add public/icon.svg (menu + focus icon).
3. Build:

   npm run build
   

4. Zip the dist directory contents (Vite output).
5. In Flowgear: Settings → Manage Apps → + Publish App, pick the account, upload the ZIP, submit.
6. After publish, open the app entry, add target Sites, and refresh the console to see it embedded.