Files
Introduction
This tutorial shows municipalities how to integrate 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 uses the Cityworks REST API to exchange information between applications.
This tutorial demonstrates workflows using custom transformers and manual
API
calls to interact with Trimble Unity / Cityworks.
These workflows are still applicable to both Cityworks and Trimble Unity
Maintain,
and the overall concepts remain valid. However, the custom transformers shown
here are no longer being actively maintained, and will be deprecated in FME
2026.2.
In FME 2025.2 and newer, these workflows are supported through
the
TrimbleUnityConnector,
which simplifies authentication and request configuration.
If you are starting a new workflow, it is recommended to use the TrimbleUnityConnector
instead of building custom API integrations.
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 that lets citizens submit information about a pothole. To build an FME Flow Workspace App, you must first design a workspace and upload it 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, 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, FME Flow runs the workspace. 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 submission confirmation 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 to FME Flow so the Workspace App runs 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 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 Cityworks can read it.
“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 lets users 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 demo. This avoids 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 to the reporter and include the pothole details. Finally, we can write an HTML output file and stream it 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
Create an FME Flow Workspace App from the CitizenReporting.fmw workspace using the “Create Workspace App” function in FME Flow.
1. Publish your workspace to FME Flow
Publish your workspace to FME Flow and include your Cityworks and Email web connections. Register the Data Streaming service so the HTML report can stream 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. Select the Data Streaming service.
Create Workspace App
3. Run the Workspace App
When you run the workspace, Cityworks creates a Service Request for the pothole. 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 building 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 information exchange between the applications. Please see this article on Real-time Automations with Cityworks Webhooks for ideas on triggering workspaces to run responsively in FME Automations.
The Application Integration for Municipalities pothole reporting demo showcases some 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 with useful API endpoints, or make your own using the HTTPCaller. Keep reading for more information on Cityworks and FME.