Working with FME Flow Runtime Parameters

Introduction

FME Flow (formerly FME Server) Workspace Apps can be configured to require authentication. In FME 2022, two new FME Flow Parameters have been made available in FME Workbench that store information about the authenticated user who has submitted the workspace run: 

• FME_SERVER_RUNTIME_USER: The name of the user who authenticated the FME Flow workspace app to run the workspace.
• FME_SERVER_RUNTIME_ID: The UUID of the user who authenticated the FME Flow workspace app to run the workspace.

In this tutorial, we’ll use the workspace from Using the Geometry Parameter as a starting point to demonstrate how you can use these new parameters within the workspace behind the app configuration. This workspace allows a construction company to draw on a map of areas undergoing construction and identify a list of residents they will need to notify of this upcoming work.

In this scenario, your FME Flow only has one Engine, which means you cannot guarantee the app will be able to process the request immediately. To work around this, instead of running the app under the data download service, you would like to configure the workspace to send the result data via email. To complete this task, you must use the FME Flow runtime parameters to fetch the logged-in user's email address. 

Step-by-step Instructions

Part 1: Building the Workspace App

1. Publish the workspace to FME Flow

Download the RuntimeParametersTutorial.zip from the files section on the right, and open ConstructionNotifier.fmw in FME Workbench. No edits are required. Publish the workspace to FME Flow using the following information:

Repository: AppDemo
Workspace Name: ConstructionNotifier.fmw
Registered Service: Job Submitter

To create a new repository, click the “New…” button beside the Repository Name dropdown menu

Click next to select registered services and then click Publish.

For detailed instructions on how to publish to FME Flow, including setting up a new FME Flow Connection, please see the information below 

• To publish a workspace from FME Workbench to FME Flow, follow the generic instructions below using the specific details listed in the article. If the article does not have a specific repository name listed, we recommend creating a Training repository. If a specific service is not listed in the article, please use the default Job Submitter.

  1. Click Publish

  From the File menu, click Publish to FME Flow, or from the toolbar ribbon, click Publish.

  Toolbar Ribbon:
  
  
  File Menu:
  

  2. Add a Web Connection

  In the Publish to FME Flow wizard, a FME Flow connection needs to be selected or created. To create an FME Flow connection, click the drop-down under FME Flow Connection and select Connect to FME Flow. For more information on creating or managing web connections, see the documentation.

  
   

  The following instructions are for a basic connection, but if your FME Flow is set up for Microsoft Azure, SAML, or Windows Credentials, please see the Using Web Connections to Connect to FME Flow documentation.

  An FME Flow Connection dialog will appear; here, we will set up the connection. The connection information and credentials can be obtained from your FME Flow Administrator. If you have not yet logged into FME Flow after installing, please do so prior to continuing, as you will be prompted to change the password from the default:
  Username: admin
  Password: admin

  • • Web Service: FME Flow

    • Server URL: http://localhost

    • Connection Name: Training FME Flow

    • Authentication: Basic

    • Username: your username

    • Password: your password

    Click OK. FME will try to authenticate the connection. Once authenticated, this connection will be available whenever you publish a workspace. The connection will only need to be created once.

  • • Web Service: FME Server

    • Connection Name: Training FME Server

    • Server URL: http://localhost

    • Username: your username

    • Password: your password

    Click Authenticate. FME will try to authenticate the connection. Once authenticated, this connection will be available whenever you publish a workspace. The connection will only need to be created once.

    Click Next to move to the Create Repository page of the dialog

  3. Create Repository

  Repositories are used to store groups of related items that have been published to FME Flow (similar to directories). Items such as workspaces, source data, custom formats, custom transformers, and templates can be published to a repository.

  If you need to create a new repository, click on the New button next to Repository Name. Enter the repository name and an optional description. Click OK to close the Create New Repository dialog.
  

  To select an existing repository, click the drop-down next to Repository Name and select the desired repository.
  

  4. Upload Files

  Some workspaces require additional files to run correctly on FME Flow, so these need to be uploaded along with the workspace. To upload files, enable Upload data files at the bottom of the dialog.

  When files are uploaded through the publishing menu, they are stored within the repository. If you want to upload folder files (such as geodatabases) or to specify where the files stored, the Select Files button allows you to do that. For detailed instructions on how to use the Select Files button, see the documentation.

  5. Register Services

  The final step before publishing a workspace is to register services. Services control how the data will be output after the workspace is run.

  

  Services return results in different forms:

  • Data Download Service returns results as a downloadable zip file

  • Data Streaming Service returns results as a data stream

  • Job Submitter Service accepts and runs workspace job requests

  • KML Network Link returns a KML Network Link that can be used in Google Earth

  • Notification Service allows for event-driven messaging

  Typically, the Job Submitter is always enabled, but multiple services can be enabled. Once services have been enabled, click Publish.

  6. Review Translation Log

  To confirm whether or not the workspace was published successfully, check the Translation Log. The Translation log will show which repository you published to, which files were included, and a quick link to run the workspace.

2. Upload the Source Dataset to FME Flow

Open FME Flow in a web browser. Log in and navigate to Resources > Data.

Click the Upload button and select Folder. Navigate to where you downloaded the .zip folder at the start of this tutorial and upload the Addresses.gdb folder.

3. Create the Workspace App 

After uploading the address geodatabase, we will create a Workspace App. Click on Flow Apps in the left menu bar and then select Create Workspace App.

In the Create App window, set the following parameters:

Please see the instructions below for detailed information on fully customizing Workspace and Automation Apps.

• The look and feel of your Automation app can be tailored to your organization’s colors, logo, and images. The parameters below used to customize the application run page are all optional. 

  The Icon, Logo, and Banner parameters only support JPEG and PNG file formats.

  1. Browser Icon (optional): The icon will be visible in the browser tab. There is a 300 KB file size limit for icon images. 
  2. Heading Background Color (optional): You can configure the banner's background color at the top of the app page. If it is transparent, it appears behind the Heading Banner. 
  3. Heading Logo (optional): This will appear above the Heading Banner and Heading Background Color. The image has a 1 MB file size limit. 
  4. Heading Banner (optional): This image will appear at the top of the app page. If transparent, it will be placed over the Heading Background Color. The image has a 1 MB file size limit. 
  5. Footer Text (optional): The text appears below the links on the app page. 
  6. Footer Logo (optional): This appears beneath the Footer Text and behind the Footer Banner if it is transparent. The image has a 1 MB file size limit. 
  7. Footer Banner (optional): An image to comprise the banner at the bottom of the app page. If transparent, it appears over the Footer Logo. There is a 1 MB file size limit for the image. 
  8. Run Immediately: Option to configure the Automation app to run immediately once the URL is invoked without displaying a run page. 
  

Select OK and copy the App URL.

4. Test the App
Paste the URL from the previous step into a new browser tab and check you are presented with the login window. If you're already logged in with the account used to create the app, you must either log out of FME Flow or open the app in an incognito browser to see the login page.

Log in and select OK to run the App.

5. Check the Job Log

Return to the FME Flow home page and go to Jobs > Completed. Look for the Ran By field. If the Ran By field isn’t visible, click Customize Columns at the top right and move it from the Hidden to Displayed Columns list.

Now that we have set up our Workspace App, we can modify it to use the FME Flow runtime parameters to fetch the email address of the user who logged in to run the workspace. We can then share the data via email.

Part 2: Editing the Workspace to use FME Flow Parameters

The starting workspace needs to be modified to use the FME Flow parameters. If you closed FME Workbench after publishing in part 1, please open the ConstructionNotifier.fwm workspace again.

Users must have an email address associated with their user in FME Flow to complete this tutorial. We will use the parameter $(FME_SERVER_RUNTIME_USER) to personalize the email response. To see if a user has an email associated with them, go to User Management > Users. In the image below, only the user named “tandra” has an email address.

1. Replace the Writer with a Feature Writer

The writer must have an output port to send an email after running a workspace. Since generic writers don’t have an output port, we need to use a FeatureWriter transformer.

Add a FeatureWriter to the canvas and set the following parameters:

We have set the Dataset to FME Flow’s Temp Resource Folder. A system cleanup task frequently removes files in this folder, so writing here will avoid cluttering FME Flow.

Connect the FeatureWriter to the output port of AttributeKeeper and disable/remove the original Excel Writer.

2. Fetch the User's Email Address
We first need to retrieve the user's email address to send the user an email. Since we know the username and ID, we can call the REST API to fetch this information. To perform this task, you should use the endpoint and use the $(FME_SERVER_RUNTIME_USER) parameter as the <account>.

Add an HTTPCaller to the Summary port of the FeatureWriter and set the following parameters:

This API call is currently using the FMEFlow Rest API V3. V4 is currently in tech preview and will be available publicly later. The exact URL for this is subject to change.

To access the email address attribute from the HTTPCaller response, we need to flatten the JSON and expose the attribute we need. Add JSON Flattener to the Output port of the HTTPCaller and set the following parameters:

3. Send Email
The Emailer transformer is not included automatically with FME. You need to install the package from FME Hub to add it. The steps to configure the email service vary between Microsoft and Google. For more information on setting up email in FME, please see the following articles: 

How to Connect to Microsoft Exchange Online using OAuth 2.0 (Microsoft Modern Authentication)

Getting Started with Sending and Receiving Email in FME Form and FME Flow

Add an Emailer transformer and connect it to the output port of the JSONFlattener with the following parameter settings:

If you want more space when editing the body, click the ellipsis next to the Body field in the Emailer parameters.

4. Test the Workspace
Your final workspace should look as follows:

Before publishing to FME Flow, you should always run your workspace in FME Workbench to double-check that it runs as expected. FME Flow Parameters are only populated when the workspace is run on FME Flow, so to test the workspace, we must provide all the FME Flow parameters referenced in our workspace with dummy values. In the Navigator, set the following parameters: 

Run the workspace and confirm that you receive an email.

Part 3: Verifying the setup

1. Publish the Workspace to FME Flow
From FME Workbench, go to File > Publish to FME Flow… or use the Publish button from the icon ribbon. Make sure you overwrite the workspace that was published in part 1.
Since we’ve added a Package and two Web Connections, you must run through the publishing wizard again rather than re-publish to ensure these additional items are uploaded.

2. Fetch the App URL and run 
Re-open the App, and if it is not open, you can find the URL from Flow Apps > Manage Flow Apps and click on the ‘View’ Icon . Once the job is completed, check your email and make sure the dataset is attached.

If you use ConstructionNotifier_Complete.fmw, you should edit the app so the connection published parameters are not visible before publishing.

Additional Resources

[Article] Getting Started with Workspace Apps
[Webinar] Creating No Code Web Apps with FME Flow
[Documentation] Workspace Apps  

Data Attribution

The data used here originates from open data made available by the City of Vancouver, British Columbia. It contains information licensed under the Open Government License - Vancouver.