Cityworks and FME: Pothole Reporting Demo

Introduction

This tutorial demonstrates solutions for municipalities by integrating Cityworks and FME. The workflow entails how to configure an FME Flow Workspace App to report potholes and send the Service Request to Cityworks. FME leverages the Cityworks’ REST API to facilitate the exchange of information between applications.

Requirements

• A Cityworks Web Connection
• An Email Service Web Connection (Optional)
• FME Flow
• FME Form

Step-by-Step Instructions

In this demo, the municipality’s “Citizen Pothole Reporting App” is an FME Flow Workspace App for citizens to submit information about a pothole. To build an FME Flow Workspace App, a workspace must first be designed and uploaded to FME Flow. 


FME Flow App: Citizen Pothole Reporting
 

Part 1: Author Workspace in FME Workbench

The CitizenReporting.fmw workspace powers the “Citizen Pothole Reporting App”. In this workspace, Published User Parameters are defined for the Date, Location, Email Address, and Pothole Size, which become available as user input in the FME Flow Workspace App. When the user submits their selections, the workspace is run by FME Flow. The workspace is authored in FME Workbench and uses HTTPCaller and prebuilt Cityworks custom transformers to send pothole information to Cityworks. The workspace streams an HTML page back to the end user in the web browser as a confirmation of submission and also sends a confirmation email to the user via the Emailer transformer. All custom transformers and HTTPCaller transformers require your Cityworks instance URL and Web Connection. 

Pothole Demo Workflow
 

1. Create the Workspace in FME Workbench

Import this Flow Project to follow along or try it yourself: CityworksPotholeReportingDemo.fsproject*

*Requires FME Flow Build 24187 or newer.

Please note that the if you are importing the project as a non-admin user that you will need to have an Admin grant permissions to the project and contents before you can proceed. Please see Known Issue: Importing a fsproject File Requires an Admin to Grant Permissions to the Project for more information. 

The Flow Project contains a workspace and an FME Flow Workspace App. Download and open the workspace in FME Workbench. You will need to edit the workspace with your own Cityworks and Email Service web connections before republishing back to FME Flow for the Workspace App to run as expected. 


2. Create User Parameters and Use Transformers to Format Them for API Call

Starting with the “Format user parameters for API Call” bookmark, the ParameterFetcher transformer creates attributes from the User’s Published Parameters to pass into downstream transformers. The pothole’s location is brought in as GeoJSON point geometry. GeoJSON X, Y coordinates are retrieved using the JSONExtractor. DateTimeConverter translates the user’s date from FME format to ISO so that it can be read by Cityworks.

“Format user parameters for API Call” bookmark
 

3. Add the ServiceRequestCreator Custom Transformer

The attributes are then passed to Cityworks using the ServiceRequestCreator, a custom transformer available on the FME Hub. ServiceRequestCreator wraps up a Cityworks API endpoint for creating Service Requests. The transformer parameter “Additional Request Parameters” also gives the user the option to customize their calls. To find valid parameters, please consult your Cityworks instance API Documentation.

With ServiceRequestCreator, the user email address, pothole location coordinates, date, pothole size, and tag for the demo are stored using the Service Requests’ extra “Text” and “Num” fields. The parameters are stored in these auxiliary fields for the purposes of the demo. This is to circumvent using the demonstration Cityworks instance’s geography, calendar, and contacts. When building your own workflow, use the API endpoint’s dedicated parameters.

“Creating Service Request” bookmark

4. Send out Notification and Create HTML Report

We can use the Logger transformer to log the Service Request ID in the job log. We can also use the Emailer transformer to email a confirmation email to the reporter and detail the pothole information. Finally, we can write an HTML output file to be streamed back to the end user in the web browser using the Data Streaming service.


"Send out Notification" and "Create HTML output" bookmarks

Part 2. Create the FME Flow Workspace App

An FME Flow Workspace App was created from the CitizenReporting.fmw workspace using the “Create Workspace App” function on FME Flow. 

1. Publish your workspace to FME Flow

Publish your workspace to FME Flow and include your Cityworks and Email web connections. Ensure you register the Data Streaming service so that the HTML report can be streamed back to the user in the web browser.


Register Services

2. Create a Workspace App

To run a workspace as an FME Flow Workspace app, upload the workspace to your instance of FME Flow and
follow this guide to build an FME Flow App. Ensure the Data Streaming service is selected as the service.


Create Workspace App

3. Run the Workspace App

When the workspace is run, a Service Request for the pothole is created in Cityworks. A confirmation email is sent to the reporter, and an HTML confirmation page is streamed back to the reporter in the web browser.


HTML Report Output

Congratulations, you've successfully created a Citizen Reporting App using FME Flow Workspace Apps to create a Service Request with Cityworks.

Additional Resources

Optionally, you can continue to build out the workflow to create a Work Order from the submitted Service Request by using FME to leverage the Cityworks’ REST API and webhooks to facilitate the exchange of information between the applications. Please see this article on Real-time Autoamtions with Cityworks Webhooks for ideas on how to trigger workspaces to run responsively in FME Automations. 


The Application Integration for Municipalities pothole reporting demo showcases just some of the integration possibilities for connecting data across applications in FME. Connect to Cityworks in FME and get started building your own workflows. Explore the FME Hub for more Cityworks custom transformers prebuilt to with useful API endpoints, or make your own using the HTTPCaller. Keep reading for more information on Cityworks and FME.