Working with the FME Server Runtime Parameters

Introduction

FME Server Workspace Apps can be configured to require authentication, in FME 2022 two new FME Server 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: Name of the user who authenticated the FME Server workspace app to run the workspace.
FME_SERVER_RUNTIME_ID: The UUID of the user who authenticated the FME Server workspace app to run the workspace.

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

In this scenario, your FME Server 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 make use of the FME Server runtime parameters to fetch the email address for the logged-in user. 

Content Overview

• Step-by-step Instructions
  • Part 1: Building the Workspace App
  • Part 2: Editing the Workspace to use FME Server Parameters
  • Part 3: Verifying the setup
• Additional Resources

Step-by-step Instructions

Part 1: Building the Workspace App

1. Publish the workspace to FME Server
   1. Download ConstructionNotifier_Start.fmw and open it in FME Workbench.
   2. Publish the workspace to FME Server using the following information:

      Repository	AppDemo
      Workspace Name	ConstructionNotifier.fmw
      Registered Service	Job Submitter

2. Upload the source dataset to FME Server
   1. Open FME Server in a web browser, log in and navigate to Resources > Data.
   2. Upload Addresses.gdb.
      
3. Build the Workspace App 
   1. Find the Server Apps menu item and select Build Workspace App.
      
   2. In the Create App window set the following parameters:

      Name	ConstructionNeighbours
      Title	Locate Addresses to Notify of Upcoming Construction
      Description	Select the Area that you will be performing construction work in and receive via email a list of addresses that need to be notified.
      Repository	AppDemo
      Service	ConstructionNotifier.fmw
      Require Authentication	Enabled
      Allowed Users	<User/Role that should have access to the app>

      
      
      Note: To learn more about customization options, check out Getting Started with Workspace Apps. 
   3. Select OK and copy the App URL.
      
4. Test the App
   1. Paste the URL from 3c into a new browser tab and check you are presented with the login window. 
      Note: If you granted the account used to create the app access to run the app then you will need to first log out of FME Server, or open the workspace app in an incognito browser to be presented with the login page again.
   2. Log in and select OK to run the App.
      
5. Check the Ran By user
   1. Return to the FME Server home page.
   2. Go to Jobs > Completed and look for the Ran By field.
      

Note: If the Ran By field isn’t visible, click on ‘Customize Columns’ and move the field from the Hidden to Displayed Columns list. 

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

Part 2: Editing the Workspace to use FME Server Parameters

1. Return to FME Workbench 
   The starting workspace needs to be modified to make use of the FME Server parameters if you closed FME Workbench after publishing the workspace in part 1.
2. Replace the Writer with a Feature Writer
   1. To be able to send an email after the writer is complete it needs to have an output port, the FeatureWriter transformer can be used in place of a writer to write files mid-translation. Add a FeatureWriter to the canvas and set the following parameters:

      Format	Microsoft Excel
      Dataset	$(FME_SHAREDRESOURCE_TEMP)/Addresses.xlsx

      
      
      Note: We have set the Dataset to FME Server’s Temp Resource Folder. Files in this folder are frequently removed by a system cleanup task. Writing here will avoid cluttering FME Server. 
   2. Connect the FeatureWriter to the output port of AttributeKeeper and disable/remove the original Excel Writer.
3. Fetch the User Email Address
   To be able to send the user an email we first need to retrieve the user's email address. Since we know the username and ID, we can make a call to the REST API to fetch this information. 
   1. Add an HTTPCaller to the Summary port of the FeatureWriter and set the following parameters: 

      Request URL	http://<HOSTNAME>/fmeapiv4/accounts/$(FME_SERVER_RUNTIME_USER_ID)?ldap=false
      HTTP Method	GET
      Use Authentication	Yes (Basic or Web Connection)

      
       
   2. Note: REST API V4 is in tech preview for FME 2022, to see the documentation go to http://<FMEServerHost>/fmeapiv4/swagger-ui/index.html. To perform this task with REST API V3 you should use the GET /security/accounts/< account > endpoint and use the $(FME_SERVER_RUNTIME_USER) parameter as the <account>.
   3. Add JSON Flattener to the Output port of the HTTPCaller and set the following parameters: 

      JSON Document	_response_body (attribute)
      Attribute to Expose	email

      
      
4. Send Email 
   Add an Emailer and connect it to the output port of the JSONFlattener with the following parameter settings: 

   From	<sender email address>
   To	email (attribute)
   Subject	List of Addresses Neighbouring Construction Area
   Body	Hi $(FME_SERVER_RUNTIME_USER),  Please find attached the results of your recent data request through the Austin Download portal.
   Attachments	Source File: _dataset (attribute) Content ID: Addresses.xlsx MIME Type: autodetect
   Service	<Your email server details>

   
   
   Note: Your users must have an email address assigned to them in FME Server to be able to complete this tutorial. We are making use of the parameter $(FME_SERVER_RUNTIME_USER) to personalize the email response.
   1. Test the Workspace
      Your final workspace should look as follows: 
      
      Before publishing to FME Server you should always run your workspace in FME Workbench to double-check it runs as expected. FME Server Parameters are only populated when the workspace is run on FME Server, therefore to test the workspace we must provide all the FME Server parameters referenced in our workspace with dummy values. 
      In the Navigator set the following parameters: 

      FME_SERVER_RUNTIME_USER	<your fmeserver username>
      FME_SERVER_RUNTIME_USER_ID	<your fmeserver user ID>
      FME_SHAREDRESOURCE_TEMP	<A filepath to write the output file>
      FME_SHAREDRESOURCE_DATA	<A local filepath to Addresses.gdb>

      
      Run the workspace and confirm that you receive an email.
      Note: See ConstructionNotifier_Complete.fmw for the finished version of this workspace.

Part 3: Verifying the setup

1. Publish the Workspace to FME Server 
   From FME Workbench go to File > Publish to FME Server… or use the Publish button from the icon ribbon . Make sure you overwrite the workspace that was published in part 1.
   Note: Since we’ve added a Package and two Web Connections, you’ll need to run through the publishing wizard again rather than re-publishing to make sure these additional items are uploaded. 
2. Fetch the App URL and run  
   Re-open the App, if you do not have it open, you can find the URL from Server Apps > Manage Server Apps and click on the ‘View’ Icon . Once the job is completed check your email and make sure the dataset is attached. 
   

Note: If you are using ConstructionNotifier_Complete.fmw you should edit the app so the connection published parameters are not visible before 

Additional Resources

[Article] Getting Started with Workspace Apps
[Webinar] Creating No Code Web Apps with FME Server
[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.