New FME tools for Cityworks integrations
FME has been a staple in municipal GIS departments for a long time, shuffling data from system to system, format to format, and performing spatial and non-spatial transformations along the way. But the potential of the FME platform is not fully realized until we take into account all the non-traditional or non-GIS formats and systems to which FME can communicate — most often through a simple HTTP call to an API.
Working closely with a number of North American municipalities (both new and existing FME users), we have been exploring this domain in earnest, researching and prototyping application integrations for common data systems. Our first project was the asset management system Cityworks. Through a couple of custom transformers, a template workspace, and an FME Server Project now available on FME Hub, we’ve developed a boilerplate for Cityworks application integrations that can be run stand-alone from FME Desktop, scheduled, or triggered responsively within FME Server.
Authoring Cityworks API calls in FME Desktop
The Cityworks custom transformers and template, designed in FME Desktop, interact with your Cityworks instance using calls from the extensive and well-documented Cityworks REST API. Inside the FME template, you’ll see that after authenticating a Cityworks instance with the CityworksConnector, each subsequent call to the API is handled quite simply with an HTTPCaller (to make the call) and a JSONExtractor (to handle the response).
We’ve wrapped one of the most common calls — creating a work order in Cityworks — in a custom transformer for ease of use:
Use the WorkOrderCreator transformer in FME to create a work order in Cityworks.
Take a look inside the custom transformer to see the nuts and bolts:
What’s going on inside FME’s WorkOrderCreator custom transformer.
This pattern can be reused for many Cityworks REST API calls. All you need to do is tailor the data parameter in the HTTPCaller for your specific call and Cityworks data structure.
With one foot still in the GIS realm, the template workflow also pulls street centrelines from an ArcGIS Server Feature Service, which are spatially joined to the incoming Cityworks data and attached as an entity to the work order being processed through the REST API. Of course, FME could connect to any number of databases or formats, spatial or non-spatial, so the beauty of this integration is that it has the potential to mix numerous applications or data silos, whether they are for asset management, permitting, GIS, finance, engineering, or something else!
Scaling Up and Automating in FME Server
Enterprise settings require large-scale and responsive implementations of these kinds of integration workflows. For example, you might want to reduce manual data entry by making a series of Cityworks API calls (creating parent and child work orders, adding tasks, etc.) in response to some other Cityworks event, such as a new service request. Or you might want an email or directory watch to trigger an integration automation based on incoming data or files. These are possible in FME Server.
For the FME Server Cityworks Project, the Cityworks webhook framework, called Action Templates and Events, along with the FME Server Notification Service, are used together to trigger FME Server workflows automatically with data sent from Cityworks. Data in the form of an HTTP Post with JSON is sent automatically to an FME Server topic, which is subsequently consumed by an FME workspace that interacts with the Cityworks REST API.
The diagram below is a visual abstraction of the process. Starting from top left, JSON is sent to the FME Server Notification Service from Cityworks. Once in FME Server, the engine ingests the JSON and runs the workspace which will consume it. During the workflow, the engine running the workspaces pulls from an external database and makes a series of REST API calls back to Cityworks. When the whole process is complete, FME Server sends an email summarizing the job.
Automating Cityworks integration workflows with the FME platform.
Cityworks and FME at work in the City of Omaha
We created these tools through a collaboration with the GIS department at the City of Omaha, who came to us with this problem: a series of existing manual processes within Cityworks needed to be automated and integrated with their existing GIS; these processes need to be responsive and automated; and other systems will need to be integrated in the future with an easily readable and maintainable script. FME was up for the job. The City of Omaha implemented an FME Server Project that now runs in their FME Cloud instance. Since many of their planned integrations rely on cloud-based systems and web APIs rather than on-premises data warehouses, and because the overhead to get started is so low, FME Cloud turned out to be the perfect solution for the city. Omaha has a few other integration projects on the go, working with municipal permitting and accounting systems and organizing snow plow routing for the winter. We’re looking forward to continued work with the City of Omaha and others in this domain as they find new uses for FME as an integration platform in their enterprises.
FME Hub
If you’re looking to complete your own FME Server integration with Cityworks, to publish an example of an integration you’ve done, or if you’re just interested in how we put together a responsive workflow in FME, head on over to FME Hub. This is our platform for custom content available to all FME users. Anyone can upload or download, so it’s a great place to post ideas and share FME content or workflows.
