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.

This article describes how to build and publish Flowgear Apps.

Requirements

NodeJS (available for download at https://nodejs.org/en/download/current ).
Visual Studio Code or other text editor.
Bootstrap NPM package.
Typescript NPM package.
Flowgear permissions. To be able to publish an App, app-publisher or account-admin permissions for an Account is required. Then to be able to invoke Workflows via the web app, an API Key of Type Cookie is needed. This should be created, and all Workflows and User should be assigned to this.
Git (if you are planning to start with the sample).

Run the sample App

Clone the Flowgear Samples repository, then open custom-apps\sample-app-refresh in Visual Studio Code.
Run command npm install via the CMD or Terminal in the project directory (it may take some time as it will need to install packages).
Create a Workflow in your Site, and create the API Binding (reach out to support if your domain has not been configured).
Add a Variable Bar, and choose FgResponseBody. Add 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 a OK response.
Add FgResponseContentType, with the value application/json.
Save the Workflow.
Create a API Key of Type Cookie, and assign which Users are allowed to invoke which Workflows. This is done per environment.
Update the URL in config.ts to your specific API Binding.
Create a new file in the project source directory called .env and set the contents to HTTPS=true
Run command npm start (starts the development server).
Optionally trust the self signed client certificate for development.
To debug the web app, you would need to open the URL (depending on your Site):

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

Copy the URL provided in to a new browser tab. Replace {tenantKey} with your specific tenant key used to sign in, and replace {siteKey} with the Key of one of your Flowgear Sites.
When that URL is opened, you should see a Sample App with some Sample data loaded using your custom API bound Workflow.

Building your own App

We recommend building your own app by starting with the sample app but you can also start with 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: npx create-react-app my-directory --typescript

and be sure to add the following line to the generated package.json file:
"homepage": "./"

Initializing the App

Ensure the flowgear-webapp npm package is installed using npm i flowgear-webapp

Open sample-app-refresh/src/index.tsx and add the following code before you instantiate the top-level React component:

Flowgear.Sdk.init();

Be sure to reference the SDK via NPM at flowgear-webapp 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 in to Flowgear. This API is used to call custom API's that have been published from workflows (for example https://yourcompany.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 that if you encounter a CORS (cross-origin resource sharing) error, ensure you've set the appropriate host in the Allowed Origins field of the Site Detail Pane. This is set for each environment.
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. The alert can be configured to auto-hide or require explicit dismissal
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 provided in to a new browser tab. Replace {tenantKey} with your specific tenant key used to sign in, and replace {siteKey} with the Key of one of your Flowgear Sites.

Publishing your App

Prepare your App for publishing by adding the file app.json in to the sample-app-refresh/public folder.

Below is a specimen of the expected content of the file:

{
	"ManifestVersion": 1,
	"Name": "SampleApp",
	"Version": "1.0.0.0",
	"DisplayName": "Sample App",
	"EmbedMode": "menu",
	"EmbedParameters": {
		"After": "workflows"
	}
}

ManifestVersion should be set to 1
Name should contain a camel-case internal name for the App that is unique across Flowgear. Consider applying a namespace to this - for example your-company.your-app. As this name must be unique across all tenants, you will need to change the name of the Sample App before you'll be able to publish it
Version should be incremented each time the App is going to be published. It is not possible to re-publish the same version of an App
DisplayName will be presented as the name of the App in the front-end in both the Pane title area and in the menu (if the App is embedded into the menu)
EmbedMode indicates how the App should embed into the Console. Currently this property can be left blank (user must know the URL to the app in order to open it) or menu which indicates that the App will embed in to the left-hand menu.
EmbedParameters specifies parameters pertaining to the EmbedMode property. Where EmbedMode is set to menu, a parameter named After may be specified. The value on this parameter indicates which menu item the App icon should embed after

Add an SVG icon named icon.svg in to your publish root. This icon is used when the App is focused and also shown in the menu when the App is embedded in the menu.
Obtain the App publish assets by running the command: npm run build
Navigate to the publish location (the default location for the Sample App will be sample-app-refresh/build).
Zip the files in this location, then within Flowgear, click Settings and Apps from the left-hand menu.
Click + and choose the Flowgear Account you would like to publish the App through then upload the Zip file created earlier and click Submit.
Once the App has published it will show up in the Apps list. Open the App by clicking it in the list.
On the right-hand pane, select and add the Sites you would like the App to be published to. Switch to the Site or refresh your Console in order for the App to embed.