Automating FME Flow App Customization

This tutorial was last updated using FME 2023.0, the interface may be different but the concepts are the same. Please note not all features listed are available in earlier versions of the FME Flow REST API.  

Introduction

With the latest version of the FME Flow REST API (V4), you have even more control and flexibility in tailoring FME Flow visual elements to align with your brand and design preferences. In this article, we will explore the versatile capabilities of the FME Flow REST V4 API and provide you with step-by-step instructions on how to leverage its features to seamlessly customize various aspects of your application. Whether you are a developer looking to automate the customization process or a system administrator seeking to streamline branding efforts, this guide will empower you to make dynamic and visually appealing changes to your FME Flow application. Before starting this tutorial, we recommend exploring the Getting Started with FME Flow Workspace Apps tutorial if you are new to FME Flow Apps. 
 

Overview of the FME Flow REST API

The FME Flow V4 REST API enables users to programmatically execute operations to endpoints like apps, engines, jobs, and much more, allowing organizations to get even more use out of their deployment. This article will focus on the apps endpoint and how a simple FME Workspace can update the customization files associated with FME Flow Apps. If you are new to working with APIs in FME, please go ahead and review the Getting Started with APIs tutorial in order to become even more familiar with the concept of using FME to interact with APIs. 

To view all of the FME Flow V4 REST API capabilities, please visit:

<yourFMEFlowHost>/fmeapiv4/docs/index.html

Obtaining App IDs

In this article, we will exclusively focus on FME Flow Workspace Apps; however, the process is similar for both Gallery and Automation Apps as well.


1. Add a Creator and HTTPCaller
Open a blank workspace in FME Workbench. Add a Creator to the canvas. Next add an HTTPCaller and connect it to the Creator. In the HTTPCaller Transformer, set the Request URL to:
Next, set HTTP Method to GET. Lastly, enable the Use Authentication parameter, set the Authentication Method to Web Connection, and select your existing FME Flow Web Connection or create a new FME Flow Connection if needed. After these parameters have been configured, the HTTPCaller is ready to return a list of Workspace Apps and their corresponding IDs using the FME Flow REST API.

<basename>/fmeapiv4/apps/workspaces?limit=1000

Next, set HTTP Method to GET. Lastly, enable the Use Authentication parameter, set the Authentication Method to Web Connection, and select your existing FME Flow Web Connection or create a new FME Flow Connection if needed. After these parameters have been configured, the HTTPCaller is ready to return a list of Workspace Apps and their corresponding IDs using the FME Flow REST API.

Note: if your organization has over 1000 FME Flow Apps, you can obtain the remaining apps on subsequent pages by extracting the totalCount attributes from the JSON Response body and using a Cloner to create a new feature for subsequent pages. Alternatively, if you want to do this in separate calls, you can set the limit to 0 to obtain the number of pages, then a Cloner to create the appropriate number of features to return the App ID's from all pages (i.e. Cloner > Number of Copies = @Value(_creation_instance)/<pagesSize>). In this case, it is simpler to Clone features than it is to create a looping Custom Transformer.

2. Expose App Ids
Once we have the output from the request we can fragment the JSON response to expose the App Ids. Add a JSONFragmenter to the canvas and connect it to the output port HTTPCaller, set the JSON Attribute to _response_body, and set the JSON Query to json["items"][*]. Lastly, set the Flatten Query Results into Attributes Parameter to Yes and set the Attributes to Expose to id and name. Click OK to exit the JSONFragmenter.
 

 Uploading Files for Apps

3. Upload File
Now that the workspace has been configured to obtain the FME Flow App IDs, another HTTPCaller can be added to the canvas. Configure the second HTTPCaller to use the PUT Method and set the Upload Data parameter to Multipart / Form Data. Create a single entry in the Multipart Upload called "file" and set the type to File Upload. Lastly, create a new Published Parameter in the "Value" column (by default this will be named SOURCE_FILE). 



Create a Conditional Value for the Request URL parameter. FME Flow Apps allow several elements to be customized, including a heading banner, heading logo, footer banner, footer logo, and browser icon. All of which require the use of a different endpoint, i.e.:

<hostname>fmeapiv4/apps/workspaces/<AppID>/files/<type>

Later on in this tutorial, we will configure the Automation to watch a directory on FME Flow for any changes to files. In order to allow the Automation to determine which endpoint needs to be used, a conditional value will be used to allow the file path to determine which endpoint the HTTPCaller will submit the PUT request to. Create six conditional values by clicking the down arrow by the Request URL and selecting Conditional Value. Then enter the following values ensuring to replace <hostname> with your FME Flow hostname:​​​​​​

This will allow the Automation to upload every FME Flow App when a new image for either a heading banner/logo, footer banner/logo, or icon is uploaded to an FME Flow repository that we will configure in the next steps. 
 

Lastly, enable the Use Authentication parameter, set the Authentication Type to Web Connection. With Authentication set to Web Connection, you can now select an existing FME Flow Web Connection. 
 
At this point, your workspace should look similar to the image below. The next step in FME Form is to publish the workspace to FME Flow and log into the FME Flow Web UI to configure the directory structure and Automation. 
 

 Utilizing FME Flow Automations for FME Flow App Customization

4. Configure Resource Folders
To enable this Automation, you need to configure a few Resource Folders on your FME Flow instance. In this case, the Flow App Customization folder was created in $(FME_SHAREDRESOURCE_TEMP)/ with five subfolders (one for each customization element (i.e. Footer Banner, Footer Logo, Heading Banner, Heading Logo, Icon). 
 

 Configuring the Automation

5. Watch Directory
Once the Resource Folders have been configured, you can build an FME Flow Automation that will watch for modifications to the Flow App Customization Folder (including subfolders). 



6. Run Workspace Action
Next, add a new Action to the Automations canvas and point it to the workspace that we published earlier. Configure the Action to Run a Workspace and set the value of the Upload File Published Parameter to the File Path value (drop-down arrow > Directory > File Path).

 Detecting Newly Created Flow Apps

Currently, there is no mechanism (i.e. system event) to detect newly created apps. Instead, you can either use a separate Automation and the V4 REST API to modify the file names at your preferred frequency (daily, weekly, monthly), use a manual Trigger, or add a Schedule Trigger to the Automation and publish a job that downloads the images saved to the temp repository and uploads them using the REST API (re-using most of the logic from the workspace built in this tutorial).