Run a Workspace in Response to Incoming Email

Introduction

This article will set up an automation in FME Flow (formerly FME Server) to run when an email with a specific keyword in the subject line arrives, using a shapefile attached to the email as workspace input.
 

Requirements

• Access to an email with IMAP OR Access to an FME Instance with a DNS record 
• Licensed FME Flow and FME Form (formerly FME Desktop)

Step-by-Step Instructions

1. Create a New Automation
Log into FME Flow. On the left-hand menu, expand Automations and select Create Automation. 


 
2. Configure the Trigger to Check for Received Email
A Trigger will be already on the canvas when starting a new automation, ready to configure. Double-click on the Trigger to open the parameters. Choose one of the following two protocols to monitor email:

1. FME Flow email via SMTP protocol
2. External email account via IMAP protocol 

Method 1: FME Flow email via SMTP protocol

This method will cause emails sent directly to FME Flow to initiate a workflow using the SMTP protocol.
 
The SMTP protocol will only work if you use an FME Flow instance with a proper DNS record (the server is accessible over the internet). This includes any FME Flow Hosted (formerly FME Cloud) instance. See Tutorial: Email in FME Flow for more details.
If your instance of FME Flow is running locally or on an intranet, you must use IMAP below.
 
On the Automations canvas, double-click the Trigger node. Set your Trigger to Email - SMTP (received). Populate the Email User Name parameter with the local part of the email address you would like the user to send to. The domain does not need to be included in this parameter. For example, if your FME Flow service which is accessible online through the site “http://myflowinstance.com/fmeserver” was given the Email User Name of “RunMyWorkspace”, any time a user sends an email to “RunMyWorkspace@myflowinstance.com” the automation will be triggered.

Note: If you are using a separate server which relays emails to FME Flow, the same Email User Name rules above still apply.
 
Click the ellipsis button to the right of the Download Attachments To field and specify a Resource folder to house any incoming email attachments (e.g., Data/IncomingEmail/). Click Validate and (if valid) Apply.

Additional actions can be performed using the output attributes of an SMTP Trigger by adding an action to the success port of the trigger, such as a Filter or Log.

Method 2: External email account via IMAP protocol

This method will poll an external email account for new mail using the IMAP protocol.
 

To ensure that the email account you intend on using will properly work with IMAP, please ensure that IMAP is enabled in your email settings. It is also recommended to create and use an application password for the email account you are monitoring. This will reduce the likelihood of failures to poll by FME Flow, as the email provider may consider it a security concern. Each email provider should have instructions on how to create this password. Refer to your provider’s documentation for details.

On the Automations canvas, double-click the Trigger node. Select Email - IMAP (Received) from the Trigger drop-down menu.  You will need to enter details of the IMAP server to which you wish to connect; the Load Template button allows you to populate the required fields with information from several popular providers.

Input an IMAP Email Account to poll for new mail and enter its associated IMAP Email Password. If you created an application password, use that password instead of the email’s usual password. You may want to change the polling interval, as external email providers may refuse the connection if FME Flow polls too frequently.

 
Accept the default to fetch New Emails Only and set the Subject Filter to the word "Shapefile". If you use your external email account for purposes other than this automation, it is critical to include an identifier in the subject line of any email meant to trigger this automation; otherwise, you will be overrun with failed jobs!
 
Since this automation will pass a shapefile that is attached to an email to a workspace on FME Flow, we need a home for those attachments. Click the ellipsis button to the right of the Download Attachments To field and specify a Resource folder to house any incoming email attachments (e.g., Data/IncomingEmail/). FME Flow will store all attachments from an email in a single directory.
Click Validate and (if valid) Apply.

 

3. Publish a Workspace to FME Flow
Download the ShapefileToGeoJSON.fmwt workspace from the Files section of this article (it's contained within the GettingStartedWithAutomations folder). This workspace can accept zipped Shapefiles as an input and then outputs them as GeoJSON. 



Open the workspace in FME Workbench, then publish the workspace to FME Flow. To learn how to publish a workspace to FME Flow, see the Publish a Workspace to FME Flow and Run It article. Publish the workspace to a Repository called Automations, and ensure Job Submitter is enabled as the Service. 
When supplying data for this workspace, it is important to archive (zip) your shapefile (any single-file archive supported by FME will do) because the attachment file path passed from the Trigger to Actions downstream will only point at the first attached file.

If multiple files must be accessed from the same incoming email, you can create an automation to download all files to a directory and then another automation to watch for and route the files created there.



4. Configure an Action to Run the Workspace
Return to the automation in FME Flow. Double-click the silhouetted Next Action component if you have guides enabled to open the parameters.



If Hide Guides was previously selected from the Automations menu, you’ll need to click on the component tray in the lower left of the canvas and drag out an orange Action component.



In the Action parameters, select Run a Workspace as the Action. Then select Automations as the Repository and ShapefileToGeoJSON.fmw as the Workspace. 



Now to set the published parameters. Click on the drop-down arrow next to Source Esri Shapefiles, expand Email, and select Email Attachment. This is an upstream message, and it will use the data incoming from the Email Trigger component email attachment. 



Next, select a destination folder for the GeoJSON file. Create a new resource folder in the Data folder called Output. Click Apply to save the parameters. 


 
5. Save Your Work and Start the Automation
To preserve your progress, click Menu above the Automations canvas, then Save As. Save the automation as Run Workspace from Email, then optionally add some descriptive tags, then click OK. Finally, click Start Automation in the upper right.


 
6. Test Email and View Log
Send an email with a zipped shapefile (buildingupdate.zip is provided above in the GettingStartedWithAutomations.zip available for download in the Files section) to the email account monitored by your Trigger. Ensure that the email subject contains the word “Shapefile” so it will pass the filter.

 
 
Wait for at least one polling interval, in this case, one minute, then check the Automation log. One way to do this is through Menu > View Log File when your Automation is displayed on the screen. You can also navigate to Automations > Manage, check the box next to the automation and select Actions > View Log File. It can be helpful to click the clock icon above the log to show timestamps for each log entry.


 
If you check the Automation log file, you should see a tag <PUBLISHED_PARAMETER name="SourceDataset_ESRISHAPE"> that contains the file path of the shapefile fed into your workspace. Paste the text above into the log search bar if you’re having trouble locating the entry. 



You can confirm the attached file was downloaded successfully by navigating to the Resource folder you specified in the Trigger and looking for a new subfolder named in the log entry.
 

Conclusion

Well done! You created an automation that is triggered by incoming email and runs a workspace. Now you’re ready to add any number of your own workspaces or other tasks to an email-based workflow!
 

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.