Home Features Building Apps

Building Apps

This is for the 2023 Refresh, for the legacy platform see:
Building Apps (Legacy)

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

  1. NodeJS (available for download at https://nodejs.org/en/download/current ).

  2. Visual Studio Code or other text editor.

  3. Bootstrap NPM package.

  4. Typescript NPM package.

  5. 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.

  6. Git (if you are planning to start with the sample).

Run the sample App

  1. Clone the Flowgear Samples repository, then open custom-apps\sample-app-refresh in Visual Studio Code.

  2. 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).

  3. Create a Workflow in your Site, and create the API Binding (reach out to support if your domain has not been configured).

  4. 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
  }
]```

5. Add FgResponseCode, and set it to 200 for a OK response.

6. Add FgResponseContentType, with the value `application/json`.

7. Save the Workflow.

8. Create a API Key of Type Cookie, and assign which Users are allowed to invoke which Workflows. This is done per environment.

9. Update the URL in `config.ts` to your specific API Binding.

10. Create a new file in the project source directory called .env and set the contents to HTTPS=true

11. Run command `npm start` (starts the development server).

12. Optionally trust the self signed client certificate for development.

12. 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`

13. 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.

14. 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 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](/articles/concepts/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

1. 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

2. 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.

3. Obtain the App publish assets by running the command: `npm run build`

4. Navigate to the publish location (the default location for the Sample App will be` sample-app-refresh/build`).

5. Zip the files in this location, then within Flowgear, click `Settings` and `Apps` from the left-hand menu.

6. Click `+` and choose the Flowgear Account you would like to publish the App through then upload the Zip file created earlier and click `Submit`.

7. Once the App has published it will show up in the Apps list. Open the App by clicking it in the list.

8. 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.