Connecting to Cityworks with a Web Connection

Introduction

Connect FME to Cityworks for seamless communication between applications.

FME leverages the Cityworks REST API for direct access to your data. Once connected, FME can run automated workflows and processes in Cityworks using tools like custom transformers or the HTTPCaller.

The Cityworks Web Connection uses token authentication for secure, repeatable transactions. For more details on the token configuration, refer to your Cityworks REST API Documentation and the Cityworks Web Service Read Me.

This article provides step-by-step instructions for creating your own Cityworks Web Connection in FME Workbench.

 

Requirements

• A Cityworks account 
• Access to the Cityworks REST API
• FME Form

 

Step-by-Step Instructions

Creating a Cityworks Web Connection is a short, two-part process.

First, the Cityworks Web Service is downloaded into FME Workbench. Second, a Web Connection is created from your own Cityworks credentials. This tutorial will walk you through both parts of the process.

There are two options for downloading the Cityworks Web Service: 

• Direct download directly from FME Workbench (used in this exercise)
• Download from FME Hub and import the Cityworks.xml into FME Workbench. 

1. Download the Web Service 
Open FME Workbench. 

From the FME Workbench main menu, find FME Options (Tools > FME Options…)

From FME Options, select Web Connections from the left menu. Select the Manage Services… button.


From the list of Web Services, scroll until you reach the list of downloadable options (i.e. the orange "arrow" icons). 

Select Cityworks > Download...


The Cityworks Web Service will open. If your Cityworks is configured for SSL, make sure the “Verify SSL” box is ticked.

Press Close (or Apply) to return to the main FME Options menu. 

2. Create a Cityworks Web Connection
Now that the Web Service has been downloaded, we can create a Web Connection for your Cityworks instance.

Select the “+” button under the list of connections. 


Select Cityworks. 


A dialog box will prompt you to enter your Cityworks URL, username, and password. 

Once completed, press OK. Successful authentication automatically closes the dialog.

Your new Cityworks connection will be listed in your Web Connections list.
 

 FAQ

What if my Cityworks credentials change?

Update the Web Connection from the FME Workbench > FME Options... > Web Connections menu. Upload the new Web Connection to FME Flow (if applicable). All processes that use this Cityworks web connection will be updated. 
 

How do I share my Web Connection with others?

From the Web Connections menu, right-click your Cityworks Web Connection and select “Export…”
 

What kind of Authentication does the Cityworks Web Connection use?

The Cityworks web service token request is configured according to the Authentication request found in the Cityworks REST API Documentation. Please consult your Cityworks' specific REST API Documentation section on Authentication to confirm the requirements for your version and build. 

Important Note for "Cityworks 23" or Higher
Cityworks changed their authentication requirements in Cityworks 23.
"The authentication token should be passed in the Authorization header using the format cityworks {token}.

The token will be ignored if it is in the query string, i.e. ?data={Id:1}&token=eyJFbXBsb3llZVNpZCI6NTg4OSwiSXNzdWVkVGltZSI6MTQ"

Safe Software's Cityworks Web Service has been updated to reflect those changes. However, for compatibility with all versions of Cityworks, the web service passes authentication parameters in both the Header and Query String.

If you wish to use just one method of passing the authentication parameters, refer to the "Notes on Token Configuration" in the Cityworks web service Read Me on the FME Hub. 
 

Can I use other Authentication methods with Cityworks, like SAML?

The Web Service is only configured to use the token authentication method as outlined in the Cityworks REST API documentation (pictured above). The Cityworks Support team would be the best resource for authentication questions unaddressed by the documentation. 
 

Additional Resources

• Webinar: Automated Application Integration with FME & Cityworks
• Tutorial: Getting Started with Cityworks