Automating Work Order Creation in Trimble Unity with FME and TrimbleUnityConnector

Introduction

Organizations using Trimble Unity Maintain or Permit for asset and work order management often receive requests from external systems, such as 311 platforms, asset management tools, field inspection apps, and other databases. Manually re-entering that data is slow, error-prone, and hard to scale.

This article covers using FME and the TrimbleUnityConnector to automate Work Order creation from a source data file. The connector supports Work Orders, Service Requests, Cases, and Inspections across both Maintain and Permit. The example uses Excel, but the same approach works with any format or system FME can read.

The article also covers using FME's HTTPCaller transformer to call Trimble Unity API endpoints not exposed by the connector, so you're never limited to what the connector dialog shows.

The TrimbleUnityConnector works with both Trimble Unity and Cityworks. Cityworks is still in active use and fully supported, and the steps in this article apply to both.

Requirements

• TrimbleUnityConnector, download from FME Hub (free, requires an FME Hub account)
• A Trimble Unity Web Connection (included in the above package)
• Trimble Unity account with API access enabled and permissions to create Work Orders.

Step-by-Step Instructions

The article is split into three parts: preparing your source data, building the workspace in FME Workbench, and extending it with a direct API call using the HTTPCaller.

Download the example workspace and source Excel file before starting. The Excel file (WorkOrders.xlsx) contains five sample work order requests for a Lead Pipe Mitigation project, and is used throughout this article.

Part 1: Prepare Your Source Data

Before building the workspace, review your source data and determine how its fields map to Trimble Unity's Work Order API.

1. Review the Source Excel File

Open WorkOrders.xlsx in Excel or FME's Visual Preview. The file has two header rows and five data rows:

The column names in Row 1 come from the source system that generated the file. They won't match Trimble Unity's field names, and that's fine. FME handles the mapping inside the connector.

Part 2: Build the Workspace in FME Workbench

The finished workspace is straightforward: Excel Reader → TrimbleUnityConnector → Inspector. This part walks through setting it up step by step.

1. Open FME Workbench and Create a New Workspace

Start FME Workbench and click New to open a blank workspace.

2. Add the Excel Reader

Drag the Excel file onto the canvas, or open the Add Reader dialog, set:

• Format: Microsoft Excel 
• Dataset: WorkOrders.xlsx
  • Click on the ellipses to navigate to the location on your computer

Click OK. 

3. Add the TrimbleUnityConnector

From the canvas, start typing "Trimble" and select TrimbleUnityConnector from the results. If you’ve never used it before, a download may start (from the FME Hub). 

Connect the Excel reader's Output port to the connector's Input port.

4. Configure the Web Connection

Double-click the TrimbleUnityConnector to open its parameters. 

In the Connection field, click the dropdown and select your Trimble Unity Web Connection. If none is available, create one using your Trimble Unity credentials. 

5. Set Service Type and Action

With the Web Connection set, configure the Request section:

• Service Type: Work Order
• Action: Create

The dialog updates to show the Create Options section with all available Work Order fields.

The same connector supports Case, Inspection, Service Request, and Work Order. For each type, available actions include Create, List, Update, Close, Cancel, and Delete. To automate updates or closures instead of creation, just select Update or Close from the Action dropdown. The field-mapping approach remains the same.

6. Configure Static Fields in the Connector

Some fields are the same for every Work Order in this batch. Click the “...” to see all options for your Trimble Unity configuration.

Set these directly in the connector dialog; they don't need to come from the Excel data. For example:

• Domain: NAPERVILLE (Naperville)
• Entity Type: Naperville Water - WA Pipes
• Work Order Template: Replace

This tutorial uses the Naperville demo configuration, so the template and entity type names shown here are specific to that instance. Your dropdown options will reflect your own Trimble Unity setup. Choose whatever template and entity type match your project.

7. Map Per-Row Fields from the Excel Attributes

For fields that vary per row, click the dropdown next to each field and select the matching Excel attribute:

• Address: Site Address
• Status: Status
• Priority: Urgency
• Projected Start Date: Target Start

FME reads the value from the Excel attribute for each feature (row) and passes it to the corresponding Trimble Unity field when creating the Work Order.

8. Add ProjectSid via Additional Parameters

The Trimble Unity API is extensive, and some fields are not exposed directly in the connector dialog. Use the Additional Parameters section to pass these. Expand the Additional Parameters section at the bottom of the dialog and add a row:

• API Parameter Name: ProjectSid
• Parameter Value: 22019

This value is hardcoded; the same ProjectSid applies to every Work Order in this batch. 

Note: Additional Parameters accepts any Trimble Unity API field name. If you need to populate a field that is not shown in the connector dialog, add it here. Refer to the Trimble Unity API documentation or your instance's developer console for the full list of parameter names.

Review the TrimbleUnityConnector configuration: 

By default, the TrimbleUnityConnector outputs only a subset of the response attributes. Use the Attributes to Add ellipses to customize which response attributes are returned to the workspace. 

The "_json_response" attribute contains the raw response from Trimble Unity. You can parse this using JSON transformers to create additional attributes.

Select OK to close. 

9. Add an Inspector and Run

Add an Inspector transformer connected to the TrimbleUnityConnector output port. Also note the Rejected port: any features that fail the API call (invalid field values, authentication errors) will appear there with a descriptive error message.

Click Run Workspace. FME reads each Excel row, sends one API call to Trimble Unity per feature, and routes the response to the Inspector.

Open the Inspector on the Output port. Each feature represents a successfully created Work Order. A key output attribute to check is _work_order_sid. Its value will correspond to the work order record in Trimble Unity/Cityworks. 

Note that the “Work Notes” have not been used yet. This is because Work Order “Comments” are not built into the TrimbleUnityConnector and must therefore be configured via a custom API request. 

Part 3: Calling API Endpoints Not Covered by the Connector

The TrimbleUnityConnector handles the most common Work Order, Service Request, Inspection, and Case operations: Create, Update, Close, Delete, and List. But Trimble Unity's REST API has many more endpoints. Anything outside the connector's scope can still be reached from the same FME workspace using the HTTPCaller transformer.

This part adds a step to the existing workspace that posts a comment to each newly created Work Order. The comment is sent via a direct API call, immediately after the connector returns the new Work Order SID.

1. Identify the API Endpoint

Check the Trimble Unity API reference for your instance to find the endpoint and request format for adding a Work Order comment. You will need:

• The HTTP method (typically POST)
• The endpoint URL, which will include the Work Order SID returned by the connector (stored in the _work_order_sid attribute)
• The expected request body format (usually JSON)
• Any required headers, including Authorization

2. Add the HTTPCaller to the Canvas

In the transformer search bar, type HTTPCaller and add it to the canvas. Connect the TrimbleUnityConnector's Output port to the HTTPCaller's Input port. This means the HTTPCaller runs once per feature, receiving the Work Order SID from the connector for each row.

3. Configure the Request URL

Double-click the HTTPCaller to open its parameters. In the Request URL field, enter the comment endpoint URL. 

Example: https://your-instance.trimbleunity.com/Ams/WorkOrder/AddComments

Replace the base URL with your instance's address and adjust the path to match the endpoint your API reference specifies.

4. Set the HTTP Method and Authentication

Set the HTTP Method to POST (or whichever method the endpoint requires). For authentication, use your Trimble Unity Web Connection.

5. Set the Request Body

In the Body section, set the Upload Data to “Multipart” 

In the Multipart Upload form: 

• Content Type: multipart/form-data
• Name: data
• Upload Type: String Upload
• Value: {"Comments": "@Value(Work Notes)","WorkOrderSid": "@Value(_work_order_sid)"}

6. Inspect the Response and Run

Add another Inspector connected to the HTTPCaller Output port. Run the workspace. For each Work Order created in Part 2, the HTTPCaller posts a comment and returns the API response as attributes on the feature.

Check the response_body attribute in the Inspector to confirm the comment was accepted. If any calls fail, they appear on the HTTPCaller's Rejected port with the HTTP status code and error message.

You can also verify the Work Order and comments in Trimble Unity using the Work Order ID. 

Taking It Further: Publishing to FME Flow

Once the workspace is running as expected in Workbench, you can publish it to FME Flow to automate it or make it available to colleagues who don't use FME directly. An FME Flow App lets users upload their own Excel file through a simple web form and triggers the workflow automatically, no Workbench required.

Additional Resources

TrimbleUnityConnector (FME Hub): Official Safe Software package. 

Simplifying Integrations at Scale: FME for Cityworks, Trimble Unity and Beyond: Webinar that explores how FME supports Cityworks and Trimble Unity implementations, powers large-scale migration projects, and replaces fragile SQL triggers with scalable automation.

Getting Started with Trimble Unity Maintain (Safe Software Support): Official tutorial series for connecting FME to Trimble Unity/Cityworks. 

Custom Workflows for Cityworks with FME: In-depth tutorial on using the HTTPCaller for custom requests to Trimble Unity/Cityworks. Uses an Inspection as an example. 

Data Attribution

The example data used in this article (street addresses, project names, and asset IDs) is fictional and used for demonstration purposes only. No real infrastructure or personal data is included.