Emailing a Survey123 Report using FME Server

Matt Meeboer
Matt Meeboer
  • Updated

FME Version

  • FME 2022.0

Introduction

As demonstrated in the article Automating ArcGIS Survey123 Workflows using FME Server, FME Server Automations can process survey form data in near real-time. This tutorial will show how an Automation can also email a link to a formatted Survey123 report for a single response. This approach can be helpful when external parties, who may not have access to ArcGIS Online or Survey123, need to be notified of a survey submission and provided with the details.
  

Requirements

 

Step-By-Step Instructions

This tutorial uses an existing survey and Automation created in the Automating ArcGIS Survey123 Workflows using FME Server article. Please ensure you have completed that first. 
 

Part 1: Modify the Survey123 Webhook

We need the Survey123 webhook payload to include the survey information necessary to run the report. 

1. Open the Invasive Species Reporting Survey
Open ArcGIS Online and navigate to Survey123. Open the Invasive Species Reporting survey. If you do not see the Invasive Species Reporting survey, ensure you have completed Automating ArcGIS Survey123 Workflows using FME Server

2. Edit Webhook
In the survey, click on Settings, then click Webhooks. Next, click the pencil to edit the Invasive Species webhook.
Webhook

3. Add Survey Info
Under Event data, enable Survey info and click Save
SurveyInfo

4. Log the New Webhook Payload
With the Survey123 webhook modified, let’s take a look at the new payload in FME Server by logging the entire webhook message content.

In a new browser tab, open FME Server and log in. Open the Invasive Species Automation that was completed as part of the article Automating ArcGIS Survey123 Workflows using FME Server. If the Automation is running, stop it. 

Connect a log action to the Webhook trigger success port. For the Formatted Message, from the drop-down menu, choose Webhook > Message Content. Click Apply.
LogPayload

Start the Automation. 
StartAutomation

5. Submit a Test Invasive Species Survey in Survey123 
Back in Survey123, submit a test Invasive Species survey. The test survey will trigger the webhook. View the Automation Log File in FME Server.
ViewLogFile

The webhook message now contains a surveyInfo key with the information we need to create a report from the response data.
SurveyLog
 

Part 2: Configure the Workspace

1. Open the InvasiveSpeciesReport.fmw Workspace
Download the InvasiveSpeciesReport.fmw workspace from the Files section of this article and open it in FME Workbench. The workspace has one parameter: webhook_message. It takes the webhook_message JSON, extracts the attributes needed to create the report from the JSON, and uses a custom transformer, the Survey123ReportGetter, to run and get a link to the report. The link is passed back to the FME Server Automation using an FME Server Automations Writer at the end.
Workflow

2. Configure the Survey123ReportGetter Transformer
Open the Survey123ReportGetter parameters and set them as follows:

  • Select an ArcGIS Online Web Connection: select the web connection you created in Part 4 of the Automating ArcGIS Survey123 Workflows using FME Server article
  • Service URL, Survey123 Object ID, Survey123 Form Item ID: Leave the attributes chosen that were exposed from the JSON earlier in the workspace
  • Survey123 Template ID: Copy the ID from the template item’s URL in ArcGIS Online

      TemplateID

  • Maximum Credits to Spend: single-record reports use 0.5 credits, although this is subject to change by ESRI at any time. Leave the value as 0.5
  • Report Filename: enter a filename for the report. You can use the text editor to access FME Functions. In this example, we’ll append the current datetime to the end of the report filename using the @DateTimeNow() function
  • Output format: pdf
  • Persist Report File: leave unchecked. This will produce a temporary link valid for 24 hours
  • ArcGIS Online Output Folder ID: this can be left blank since the report file is not being persisted


Click OK.
ReportGetter

3. Copy/Paste the Webhook Message into FME Workbench
Copy the entire webhook message JSON from the FME Server Automation log file in Part 1, Step 4, from the opening curly brace to the closing curly brace, and paste it into the webhook_message value. We will use this to test the workspace.
WebhookMessage

4. Run the workspace 
The workspace may take a minute to run, as Survey123 takes time to create the report file. Confirm the workspace finished successfully with no errors and then in Visual Preview, inspect the Survey123ReportGetter output feature. You should see the report filename, filesize and url.
VisualPreview

5. Publish to FME Server
Before publishing, let’s embed the Survey123ReportGetter, since it is a custom transformer. To learn more about working with custom transformers in FME Server, please read Custom Transformers and FME Server.

Right-click on the Survey123ReportGetter and choose Embed.
Embed


The transformer will turn green, indicating that it has been embedded. 
 
In FME Workbench, click Publish to connect to your FME Server. In the publish wizard, choose a repository to upload the workspace to (or create a new repository) and click Next.
Repository
 
You should have already published an ArcGIS Online Web Connection in the article Automating ArcGIS Survey123 Workflows using FME Server. If not, click the checkbox beside the connection to publish it to FME Server. Click Next.
AGOL

Finally, register the workspace with the Job Submitter service and click Publish
RegisterServices

Check the Translation Log to make sure everything was published to FME Server successfully.
 

Part 3: Complete the Automation

With the workspace published to FME Server, we can now modify the Automation to use it.

1. Add the InvasiveSpeciesReport.fmw Workspace to the Automation 
Open the Invasive Species Automation. Delete the Log action created in Part 1 that is connected to the Webhook trigger success port. Add a new action to the canvas and connect it to the InvasiveSpecies workspace action. 

Configure the new action to run a workspace. Choose the InvasiveSpeciesReport.fmw that was published in Part 2. For the webhook_message parameter, click the drop-drop and choose Webhook > Message Content. Click Apply.
WorkspaceAction

2. Add an Email Action to the Automation
Since the InvasiveSpeciesReport.fmw workspace contains an FME Server Automation Writer, there is a “Report” output port available below the action. The port outputs a feature with the report URL that we can pass to an external email action.

Add an external action to the canvas and connect it to the Report port. Choose Email (send) as the Action and configure the SMTP settings for your outgoing email. In this example, we’ve loaded a Gmail template and entered the SMTP Account and Password.
EmailAction

Enter your email address in Email To and the SMTP Account Email in Email From. For the Email Subject, enter “Invasive Species Reported”. 
EmailConfig

For the Email Body, open the Text Editor.
EmailBody

In the Text Editor, enter some body text for the receiver and then add the report_url. The report_url can be accessed by expanding Workspace > Report. Click OK.
ReportURL

Click Validate, confirm the email action configuration is valid, and then click Apply to save the changes.
Validate


Save the Automation.
Save


3. Start and Test the Automation

Click Start Automation.
SaveAutomation

With the Automation running, submit another test Invasive Species survey in Survey123. Wait a couple of minutes, and then check your email. You should see an email containing a link to a report. 
EmailSample

Click the link in the email to view the report. Below is a sample.
Report

If you do not receive an email, check the Automation Log File for any errors. 
Troubleshoot

 

Additional Resources

Was this article helpful?

Comments

0 comments

Please sign in to leave a comment.