Building Apps

Build your own Javascript & React apps that embed directly into the Flowgear Console to create rich user experiences.

Flowgear Apps are able to invoke native and Site-specific Flowgear API's via current users' security context. This permits the Web App to act as a pure front-end with virtually no business logic while Flowgear Workflows provide the business logic and data layers.

These apps can serve a wide variety of use cases within your organization, for example, you might build:

Custom dashboards for your integrations
Utility apps to help diagnose and resolve errors received via email
Office administrative apps

This article describes how to build and publish Flowgear Apps.

Warning: This app is published to a publicly accessible blob, meaning that anyone with the URL can access it. When developing web applications, ensure that any integrations with external systems account for this exposure.

If invoking Flowgear Workflows, you must use Cookie-Based Keys tied to the user instead of Token-Based Keys. Using Token-based Keys could allow unauthorized access, as anyone with the public URL would be able to trigger Flowgear Workflows.

Requirements

NodeJS and NPM (Download)
Visual Studio Code or another text editor
Bootstrap NPM package
Typescript NPM package
Flowgear permissions:
- To publish an App, app-publisher or account-admin permissions are required.
- To invoke Workflows via the web app, create an API Key of Type Cookie and assign users and Workflows to it.
Git (if you are planning to start with the sample)
OpenSSL (for generating a self-signed development certificate). You can also use Git Bash, which includes OpenSSL.

Run the sample App

Clone the Flowgear Samples repository and open custom-apps/sample-app-vite in Visual Studio Code.
Run npm install in the project directory (this may take a while as it installs dependencies).
Create a Workflow in your Site and configure the API Binding (reach out to support if your domain has not been configured).

Add a Variable Bar and choose FgResponseBody. Use this sample data:

[
  {
    "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
  }
]

Add FgResponseCode and set it to 200 for an OK response.
Add FgResponseContentType with the value application/json.
Save the Workflow.
Create an API Key of Type Cookie, and assign which Users are allowed to invoke which Workflows. This is done per environment.
Update the following environment files in the root of your project:
```
.env.development
.env.production
```
and set the following values (replace with your Environment URLs):
```
VITE_API_URL=https://example-dev.flowgear.net
```
```
VITE_API_URL=https://example.flowgear.net
```
Create a certs folder in the root directory and generate self-signed certificates using OpenSSL (you can run this in Git Bash):
```
openssl req -x509 -newkey rsa:2048 -nodes -keyout localhost-key.pem -out localhost-cert.pem -days 365 -subj "//CN=localhost"
```
Place the generated localhost-key.pem and localhost-cert.pem files in the certs folder.
Update your .gitignore file to exclude the certs folder:
```
certs/
```

Your vite.config.ts file should be as follows:

import fs from "fs";
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

// https://vite.dev/config/
export default defineConfig({
  base: './',
  plugins: [react()],
  server: {
    allowedHosts: true,
    port: 3000,
    cors: true,
    headers: {
      "Access-Control-Allow-Origin": "*",
    },
    https: {
      key: fs.readFileSync("./certs/localhost-key.pem"),
      cert: fs.readFileSync("./certs/localhost-cert.pem"),
    },
  },
});

Run npm run dev to start the development server.
Optionally, trust the self-signed certificate if prompted.
To debug the web app, open this URL (replace placeholders):

https://app.flowgear.net/#t-{tenantKey}/sites/{siteKey}/apps/debug/?debugUrl=https%3A%2F%2Flocalhost%3A3000%2F

Replace {tenantKey} with your tenant key and {siteKey} with your Site Key.

When opened, the Sample App should load with sample data from your custom API-bound Workflow.

Building your own App

We recommend starting from the sample app, but you can also start from a new React project.

If you're starting with a new project, first create a directory, then run the following command to bootstrap a React app using Vite and TypeScript:

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

Be sure to set the base property in vite.config.ts to:

base: './',

Initializing the App

Ensure the flowgear-webapp npm package is installed using:

npm i flowgear-webapp

Open src/main.tsx and add the following code before rendering the top-level React component:

Flowgear.Sdk.init();

Be sure to reference the SDK via NPM by adding the following to the top of the file:

import { Flowgear } from 'flowgear-webapp';

This code initializes messaging between the App and the Console and then configures stylesheets so that the UI of your App is consistent with the Console.

Using the SDK

The SDK client library installed via NPM contains wrapper functions for all supported capabilities. The following functions are supported:

init() - called when your App initializes to configure the messaging interface with the Console
invoke() - provides API calls into Flowgear. This API is used to call custom APIs that have been published from workflows (for example https://example.flowgear.net/someendpoint). You do not need to add authentication information, but you will need to create an API Key of type Cookie and assign the users that are allowed to invoke the backing Workflows.
Note: If you encounter a CORS error, ensure the appropriate host is listed in the Allowed Origins field of the Site Detail Pane.
confirmModal() - displays a modal with a custom prompt that enables the user to confirm or cancel an action
getTextModal() - displays a modal with a custom prompt that enables the user to input text
setAlert() - displays a standard Flowgear alert as either informational, warning or error
openUrl() - opens the specified URL in a new browser tab

Debugging the App

This Flowgear Web App should run embedded in the Console. Use the following URL to debug:

https://app.flowgear.net/#t-{tenantKey}/sites/{siteKey}/apps/debug/?debugUrl=https%3A%2F%2Flocalhost%3A3000%2F

Copy the URL into a new browser tab. Replace {tenantKey} with your tenant key and {siteKey} with your Flowgear Site Key.

Publishing your App

Prepare your App for publishing by adding the file app.json to the public folder.

Example content:
```
{
  "Name": "SampleApp",
  "Version": "1.0.0.0",
  "DisplayName": "Sample App",
  "Rank": 1
}
```
- Name should be unique across Flowgear (e.g., your-company.your-app)
- Version should be incremented with each publish
- DisplayName is shown in the Console
- Rank indicates where the App should embed into the Console relative to other Apps published on the Site.
Add an SVG icon named icon.svg in your publish root. This icon is used in the menu and when the App is focused.
Obtain the publish assets by running:
```
npm run build
```
Navigate to the output folder — for Vite, this is the dist folder.
Zip the files in the dist folder, then in Flowgear navigate to:
```
Current Site → ⚙️ Settings → Manage Apps
```
Click + Publish App, select the Flowgear Account, upload the ZIP, and click Submit.
Once published, your App will appear in the Apps list. Click to open it.
On the right-hand pane, select and add the Sites you’d like the App to be published to. Refresh the Console to see it embedded.