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.
Introduction
In previous exercises, we've authored workflows that can be automated to fully integrate and transform our Cityworks data. But sometimes, it is more convenient to allow other users to run these processes. It is even better if we can make these processes accessible to non-technical users, saving us from the common task of responding to individual requests.
Using FME Flow Apps, FME workspaces can be made into user-friendly, shareable web and mobile apps. The end result is a customized interface that enables end users to submit requests, request information, or trigger processes. The best part? No coding required.
This tutorial creates an FME Flow App from the workspace created in the previous exercise. The final Flow App allows end-users to submit their own Excel spreadsheet data for processing. The Flow App takes the submitted data to automatically create work orders in Cityworks.
Requirements
- A Cityworks Web Connection
- FME Flow
- FME Form
Step-by-Step Instructions
This tutorial uses example data, "Chipseal_BestPractices.pdf"
1. Adding an Attachment to a Work Order
In FME Workbench, open the workspace completed in the previous exercise. Or, open the provided workspace file: SelfServeApps_Start.fmw
Run the workspace to make sure it’s working correctly. If there are any issues, review the workspace parameters and refer to the Sending a Work Order to Cityworks with FME exercise for configuration.
Please note that the Cityworks REST API requires an Entity Type to be included with every WorkOrder > Create request. Once again, you'll need to refer to your Cityworks instance or to your administrator to identify the entity types specific to your organization. "WHYDRANT" is specific to the Cityworks instance used for the tutorial. Just like the template IDs, this value is for example only, and your Cityworks instance may not have this specific entity type.
FME can manage documents and files on Cityworks. In this example, we'll attach a generic "Chip Seal" document to each new work order. The WorkOrderAttachmentAdder custom transformer can do this for us.
Add a WorkOrderAttachmentAdder to the canvas.
Insert it between the WorkOrderCreator and the HTMLReportGenerator transformers.
2. Configure WorkOrderAttachmentAdder
Open the WorkOrderAttachmentAdder.
For Web Connection, select your Cityworks Web Connection from the drop-down list.
For Cityworks Instance, enter your own Cityworks URL.
For Work Order ID, from the drop-down menu, select Attribute Value > "_work_order_id"
For Attachment, select User Parameter > Create User Parameter from the drop-down menu. Uncheck the "Required" setting, then press OK to accept the remaining default values.
The new "_attachment" user parameter will allow users to upload their own files at runtime. Their uploaded files will be attached to each new work order.
Your final WorkOrderAttachmentAdder configuration will look like the following:
3. Publish the Workspace to FME Flow
We can make edits to the workspace to improve flexibility in FME Flow.
First, embed the WorkOrderCreator and WorkOrderAttachmentAdder (if they aren't already). Right-click on each transformer and click "Embed". The transformer will change color from dark green to light green when it is embedded.
Save the workspace with a new name, "CreateAWorkOrder_With_Attachments.fmw".
Click the Publish button in the FME Workbench ribbon.
Next, create a new repository named “Cityworks”
In the Connections dialog, make sure only the Cityworks connection is checked.
In the Register Services dialog, we will select two:
- Job Submitter: Simple workflow submission.
- Data Streaming: Returns data in specific formats directly to the browser for live review. The HTML Writer used in this workspace is compatible with this service.
Publish.
4. Test the Workflow
From a browser, navigate to the FME Flow > Flow Apps > Create Workspace App.
Type in a Name, Title, and Description for your app.
Choose the "Cityworks" Repository and "CreateAWorkOrder_With_Attachments.fmw" Workspace.
Set the Service to "Data Streaming".
Leave the remaining parameters as the default.
Note that the Customize section, towards the bottom of the page, is where FME Flow Apps can be configured with custom headers and footers, logos, and background colors.
Click OK. Copy the Workspace App URL to your clipboard.
5. Configure the Flow App Permissions
FME Flow does not, by default, extend access to dependent web and database connections. Therefore, we must manually grant the app permission to use the Cityworks Web Connection.
Click on the Admin icon at the top right of the FME Flow web interface, and choose Manage Tokens from the dropdown.
From the list of API Tokens, find the token named after your new app.
When open, expand the Connections category. Find your Cityworks web connection and give the token Access. Click OK to finish.
End-users can now leverage this Cityworks web connection for their own processes without needing access to credentials or even awareness of the underlying mechanisms.
6. Run the FME Flow Workspace App
Paste the Workspace App URL in a browser tab (or reopen the app from the Manage Workspace Apps page).
In the opened app, note the two available parameters: one for the Source Microsoft Excel File and another for an attachment. Published parameters that we created in FME Form allow end users to specify workflow configurations at run-time.
Browse Resources to find the provided example data for each.
Source Excel File: WorkOrderAddresses.xlsx
Attachment: Chipseal_BestPractices.pdf
Click the "Run" button to run the app. If the job is successful, an HTML table is returned to the browser immediately.
Open Cityworks in a browser and search for one of the work order ID values returned in the HTML table. In the work order attachment fields, find the file submitted to the FME Flow App.