Real-time Automations with Cityworks Webhooks

Sanae Mendoza
Sanae Mendoza
  • Updated

FME Version

  • FME 2023.0

Introduction 

Consider common workflow chains on an asset management platform: fulfilling work orders, conducting inspections, or managing projects. 

Many tasks rely on an employee or supervisor to manually complete some part of the process, which is often repetitive and time-consuming. These points of manual intervention also leave room for error, such as duplicate data entry or incomplete records. 

FME provides a solution by responding to Cityworks events in real-time with automated workflows. Cityworks webhooks send a message to FME the moment an event occurs, like a file upload or new comment. That message instantly triggers a workflow in an FME Flow. 

What that workflow does is entirely up to you. Perhaps you’d like to connect the Cityworks data with other systems, validate data, complete a process in Cityworks, or send a reminder to an employee. Whatever it is, you can create fully hands-off Cityworks workflows with FME and webhooks. 

In previous exercises, we used FME Form to send requests to Cityworks. In this exercise, we use Cityworks to send requests to FME Flow. The result is a complete, bidirectional integration between Cityworks, FME, and any other systems or data that you wish to connect. 
 

Requirements

 

Step-by-Step Instructions

In this exercise, we will use FME to automate the creation of inspections from manhole repair work orders. When a work order status is updated in Cityworks, a webhook will trigger an FME Flow automation workflow to create inspections. This process enhances efficiency and accuracy in tracking repairs. 

This exercise steps through the basic workflow for setting up Cityworks webhooks with FME Flow. However, there are limitless possibilities for Cityworks webhook events and FME workflows. It is more than likely you'll want to build on this example workflow to better suit the needs and requirements of your organization. 

 

Please note that these instructions use example Cityworks configurations (e.g. templates) that may differ from those found in your organization's Cityworks. If you are unsure where to find your specific configurations, please refer to the Cityworks documentation or reach out to an administrator.

 

Part 1: Create an FME Automation to Receive Webhook Messages

To begin the workflow, create a simple FME Flow Automation that can receive a webhook message from Cityworks. 


1. Create an FME Flow Automation
The first step to creating a webhook in Cityworks begins in FME Flow.

Ultimately, we want FME to receive a message from Cityworks. So we first construct a basic automation that can receive messages received from our eventual Cityworks webhook.

Launch FME Flow from a browser. From the sidebar menu, expand Automations and select “Create Automation”. 

Create Auto


2. Add a Webhook Trigger
Add a Webhook Trigger (via the green lightning bolt) to the automation canvas.



Until the automation is saved, the Webhook Trigger will be unpopulated, we complete this in step 4. 

3. Add a Logger Action
Add a Log a Message Action (via the orange wrench) to the canvas. Connect it to the Webhook Trigger, via the success (checkmark) port. 

To set a value for the Log Action’s Formatted Message parameter, use the drop-down menu. Expand Webhook and select Message Content

Add Logger

4. Save the FME Flow Automation to Obtain a Webhook URL 
Save the Automation as “CityworksWOReceiver”. 

Once saved, double-click the Webhook Trigger to see its parameters. You’ll notice that the Webhook URL value is now populated. Copy it to your clipboard.

Webhook URL

Later in our exercise, Cityworks will use this URL to send messages to this automation.


5. Start the FME Flow Automation
Click “Debug” to start the Automation in debug mode. 

Once the automation is running, our Webhook Trigger is able to receive incoming messages. Note that a running automation does not consume any FME Flow Engine or system resources. 


 

Part 2: Create a Cityworks Webhook to Send Messages to FME

Part 2 uses Cityworks' Admin Action Manager to create a webhook. 

Every time a street light work order’s status is updated in Cityworks, the webhook sends a message to the “CityworksWOReceiver” Automation created in Part 1

1. Open Cityworks Admin
Open Cityworks* in a new browser tab or window. 

*We’ll be using Cityworks Respond for this tutorial, but the same settings can be found in Cityworks Office (albeit with a different web user interface). 

From the sidebar menu, navigate to Admin.

Cityworks Admin

From Admin, select the Configure tab. Under Validation, select Action Manager.



2. Action Manager Interface
Action Manager is where webhooks are configured in Cityworks. 

Webhook configuration is divided into two tabs: ACTION TEMPLATES and ACTION EVENTS. 

  • An "action event" is responsible for triggering a webhook message based on various events such as status updates, inspection creation, attachment activity, and more.
  • An "action template" defines the content and destination of the webhook message. Here, we can point to a specific FME Flow Automation and include specific details such as the work order ID, employee name, contact information, or cost updates associated with that event.


Start at the ACTION TEMPLATES tab. 

  • In the Action drop-down, select “Webhook”. 
  • Use the “+” button at the bottom of the list to add a new action template record. 


Action Templates

3. Create an Action Template
An Add Action Template window opens.

  • From the Source list, select “Work Order”. 
  • In the Description field, enter “FME Automation: CityworksWOReceiver”. 




4. Configure Action Template Details
The Webhook Details panel will appear to the right. This is where we set the destination details and contents of the message. 

  • In the URL field, paste the Webhook URL copied from the FME Flow Automation Webhook Trigger in Part 1, Step 5.
  • Make sure the URL is using the correct domain name for your FME Flow instance (e.g. not ‘localhost’)

image.png

Continue filling out the Action Template

  • Leave the Method as POST. 
  • Credentials allows the webhook to authenticate with FME before the webhook message is received. This is recommended for secure environments. For this tutorial, just leave it blank.
  • Select the Urgent box to make sure our webhook message is sent in real-time. Leaving this unchecked sends the message at a later time.

2023-08-21_12-43-28.png

Select the Custom Configuration box so we can customize the content of our webhook message.

In the CUSTOM tab, that message is defined. 

  • Header: Content-Type=application/json
  • Template:
{"WorkOrderId":"~~WorkOrderId~~", "Comments":"~~Comments~~", "ApplyToEntity": "~~ApplyToEntity~~"}

2023-08-21_12-44-14.png

Pay special care to the webhook message JSON formatting, it must be precise (with all quotes, commas, and colons). It's best practice to copy/paste when possible. 

Save. 

TIP: The Cityworks API documentation is a useful reference for which parameters can be sent in the webhook message template. The Data Types page (e.g. https://<your cityworks instance>/apidocs/#/data-type-info) lists parameters available for each Cityworks object.

For example, our newly created work order webhook can include any parameter listed under the WorkOrderBase. As well, their data types tell us how the Action Template’s JSON must be formatted. 

2023-08-21_12-44-26.png

5. Create an Action Event
Now that our webhook’s Action Template is configured, we need to specify the type of events that will trigger the message to be sent. Select the ACTION EVENTS tab to start.

  • If not already selected, use the Action drop-down menu to select Webhook.
  • Use the “+” button at the bottom of the list to create a new event record. 

2023-08-21_12-45-19.png

6. Create an Action Event
The Add Action Event window will open. 

  • Select “Work Order Status Changed” under Event Types. Scrolling through the list, just consider that each of these event types represents opportunities for real-time integrations with FME!) 
  • In the Description field, enter “FME Automation: CityworksWOReceiver” 




7. Configure Action Event Details
An Event Details window will open to the right. 

From the Action Templates drop-down, find and select the template we just created: “FME Automation: CityworksWOReceiver”.

2023-08-21_12-46-16.png


The Work Order Template field allows us to select which types of work orders will trigger the webhook. In our case, we’re interested in manhole work orders. 

Start typing “SWMANHOLE” and select the  “SWMANHOLE ~ Replace”  template*: 


*may differ, depending on your Cityworks configuration. 

Conditions allow us to build in more logic. 

In this workflow, we only want to send messages when the work order is completed. 

  • WorkOrder Field: Status
  • Operator:
  • Value*: MOBILE COMPLETE

*may differ, depending on your Cityworks configuration. 


2023-08-21_12-46-41.png

Save.

8. Test the Webhook
When both the Action Template and Action Event are configured, the webbook is complete. 

Now, we can do a quick test to make sure that it is connected to our FME Flow Automation. 

At the bottom of the Action Event, click the TEST button*. 

2023-08-21_12-46-47.png

*If the Test button doesn’t become available or doesn't respond: refresh the page or navigate away. Make sure that all the required parameters are filled out. 




After submitting the test, navigate back to the FME Flow Automation we created: “CityworksWOReceiver”. 

From the Menu dropdown, select View Debug Log. 



In the Automation Log, notice a new webhook message. Since it was only a test, the values of our webhook message are empty. 

2023-08-21_12-47-05.png

The presence of a logged message confirms that Cityworks and FME Flow are successfully connected. Now, let's try the real thing.

However, If the automation did not receive the webhook message, run through these problem-solving steps: 

  • Is the FME Flow Automation running?
  • Is your FME Flow instance publicly accessible?
  • Did you copy the Webhook URL from the FME Flow Webhook Trigger to the Action Template?
  • Did you update the Webhook URL with a valid FME Flow address? 
  • Compare the parameters for both the Action Template and Action Event to the exercise images.


9. Create a New Work Order
Navigate to Cityworks Respond in a browser tab.

From the sidebar menu, select Create > Work Order



From Select a Work Order Asset Type, select the assets our webhook is configured for, e.g.  

  • Asset Group: Stormwater
  • Asset Type: sw Manhole


Recall, our example webhook is configured to respond to “DMANHOLE ~ Replace Manhole” work orders. Therefore, we will choose this template from Select a Work Order Template:

  • Category: Corrective
  • Work Order Template: Replace

 


In the Work Order Details window to the right, fill out a comment, e.g. “Created by an FME Automation” or “Testing my FME Flow Webhook workflow”

2023-08-21_12-47-44.png

Select Create 1 Work Order. 

10. Update the Work Order Status to Trigger the Webhook 
In the newly created work order that opens, use the Status drop-down menu to select the status configured in our Action Event's Conditions. In this example, this is “Mobile Complete”.



Save the work order.



11. View the Webhook Message
After creating the Work Order, navigate back to your FME Flow Automation.

Once again, check your automation log to view the new message. This time, there is information specific to the webhook event. 



Well done! You’ve successfully connected a Cityworks webhook to an FME Flow Automation. 

Before proceeding to the next part, copy the contents of the automation log’s webhook message to a clipboard, e.g. 

{"WorkOrderId":"147223", "Comments":"By%20%28ad%29%20Admin%2C%20Public%20Works%20%3A%204%2F5%2F2024%209%3A13%3A10%20PM%20Default%20CommentsBy%20%28ad%29%20Admin%2C%20Public%20Works%20%3A%204%2F5%2F2024%209%3A13%3A10%20PM%20Testing%20my%20FME%20Flow%20Webhook%20workflow", "ApplyToEntity": "SWMANHOLE"}

 

Part 3: Respond to a Webhook Message by Running a Workflow

In this part, we build a workspace in FME Form that completes the automated inspection creation.

When the automation receives a webhook message from Cityworks, the workspace will automatically create an inspection from the new work order. 

1. Create a New Workspace in FME Form
Open FME Workbench and start a new blank workspace.

Add a Creator and ParameterFetcher transformers to the canvas. 


TIP: In workspaces that use web-based data sources, like APIs, a Creator is often used to initiate the workflow in lieu of a format-based Reader.  

2. Create a User Parameter 
In this workspace, the Cityworks webhook message will act as our 'data source'.  We need to create a User Parameter that can receive that data.

From the Navigator window, right-click User Parameters and select Manage User Parameters…



In the Parameter Manager, select the “+” button and choose “Text”.

Note the other types of parameters we can create for end-users and clients. Rich parameter options allow for endless integration and self-serve possibilities!



Configure the text parameter:

  • Parameter Identifier: webhook
  • Prompt: Webhook Message

In the Default Value, paste the webhook message copied from our "CityworksWOReceiver" FME Flow Automation Log File in the previous step. Default Value*:

{"WorkOrderId":"147223", "Comments":"By%20%28ad%29%20Admin%2C%20Public%20Works%20%3A%204%2F5%2F2024%209%3A13%3A10%20PM%20Default%20CommentsBy%20%28ad%29%20Admin%2C%20Public%20Works%20%3A%204%2F5%2F2024%209%3A13%3A10%20PM%20Testing%20my%20FME%20Flow%20Webhook%20workflow", "ApplyToEntity": "SWMANHOLE"}

*Example only. Make sure to copy the value from your automation log. 

2023-08-21_12-48-40.png

Select OK to exit the Parameter Manager window. 

3. Use the Webhook Message as Data
The ParameterFetcher creates attributes from user parameters. Double-click the ParameterFetcher on the workspace canvas. 

  • Under Parameter Name, select the newly created “webhook” parameter. 
  • The Target Attribute column will automatically populate with a modified name. 




Select OK to return to the canvas.  


4. Test the Workflow
It's a good idea to test a workflow often to reduce errors. FME Workbench allows us to run a workspace in sections. 

From the FME Workbench ribbon menu, select the drop-down menu next to the Run button. Make sure Feature Caching is enabled.



On the canvas, click and hover over the ParameterFetcher and select the “Run to This…” button. 

It should only take half a second to complete the translation. Select the magnifying glass on the ParameterFetcher to view the data in the Visual Preview window.
 
Expand the "_webhook" attribute column to view our sample webhook message. 



5. Decode the Webhook Message
In the last step, you might've noticed that the webhook message is URL encoded, which doesn’t make it easy to read. 
Luckily, there's an FME transformer for that. 

Add a TextDecoder to the canvas and connect it to the ParameterFetcher. Open it to configure. 

  • Encoding Type: URL (Percent Encoding) 
  • For String to Decode, click the drop-down menu to select Attribute Value > _webhook
  • Replace the default Decoded Text value with “_webhook”




Select OK to save and return to the canvas. 

Feel free to select “Run to This…” again on the TextDecoder to view the newly decoded webhook message. 



6. Parse the Webhook Message
Cityworks webhook messages are JSON formatted. We can use JSON transformers to parse this message into attributes that may be used downstream. 

Add a JSONFlattener to the workspace and connect it to the TextDecoder. Open it up to configure. 

  • For JSON Document, click the drop-down menu to select Attribute Value > _webhook
  • Attributes to Expose:
WorkOrderId ApplyToEntity Comments




Select OK to exit. 

Select “Run to This…” on the JSONFlattener to view our webhook message… now as attributes!



7. Create an Inspection from Work Order
We’ve arrived at the crux of the workflow: creating an Inspection in Cityworks from our Work Order.

You’re likely already aware that there are a number of pre-built tools available to interact with Cityworks, like the WorkOrderCreator. In this step, we'll use the InspectionCreatorFromWO

Add the InspectionCreatorFromWO custom transformer to the canvas.



Connect it to the JSONFlattener.

Right-click the InspectionCreatorFromWO transformer and select Embed. This will change the color of the transformer from dark green to light green.



Open the InspectionCreatorFromWO to configure its parameters*. 

  • Web Connection: <Your Cityworks Web Connection> 
  • Cityworks Instance: HTTP://<Cityworks Public IP>/cityworks
  • Entity Type: ApplyToEntity
  • Inspection Template ID: 2
  • Work Order ID: WorkOrderId

*Some values may vary depending on your Cityworks configuration



Select OK to save and return to the canvas. 

8. Pass Inspection Details Back to the Automation
Run the workspace to completion. A successful translation will return an Inspection ID (_inspection_id) that corresponds to the related Work Order Id (_work_order_id). 



At this point, the primary purpose of the workspace is complete: inspections are created from work orders. 

As is, we could now publish the workspace to FME Flow and use it in our automation. However, oftentimes we often want to use the results in a downstream action, like sending a notification. In these cases, it is useful to pass the workspace attribute values back to the Automation. 

Add an FME Flow Automations writer to the canvas. 



In the Add Writer dialog, ensure Feature Type Definition is set to “Automatic…” then click OK. 



In the Feature Type dialog, enter a value for the Feature Type Name. 

  • Feature Type Name: WorkOrderInspections




Connect the “WorkOrderInspections” writer feature type to the InspectionCreatorFromWO

Save the workspace as InspectionFromWO.fmw

9. Publish the Workflow to FME Flow
Open the FME Form Publishing Wizard to upload the workspace to FME Flow. 



Create or use an existing repository named “Cityworks”. 

In the Services dialog, select the Job Submitter Service. Click through the wizard to complete the upload.



10. Add the Workspace to the FME Flow Automation
Navigate to the FME Flow “CityworksWOReceiver” Automation. Stop the Automation. 

Add a new Action to the canvas. Connect the action to the existing Webhook Trigger, in parallel with the existing Log Action



Double-click the new Action to configure the Details: 

  • Action: Run a Workspace
  • Repository: Cityworks
  • Workspace: InspectionFromWO.fmw


2023-08-21_12-51-11.png

Under Parameters, we can replace the default value with the Webhook Trigger content. Next to Webhook Message, use the drop-down menu to select “Message Content” 

2023-08-21_12-51-21.png
Select Apply to close and return to the automation canvas. 


11. Log the Workspace Message 
On the Automation canvas, you might notice that the new ‘Inspection From WO’ Workspace Action has an additional port: WorkOrderInspections. 



Additional ports output the data from the FME Flow Automations writers. We can use this data in a downstream action, like another workspace or email notification. For this tutorial, we’ll simply log the attribute values to see what they look like. 

Add another Action to the automation canvas. Connect it to the “WorkOrderInspections” port. 



Open it up to configure its parameters. Set the Action to "Log a message". 

Beside the Formatted Message parameter, use the drop-down menu to select “Text Editor” 


In the Text Editor, we can formulate a message using any of the sidebar values. Expand Workspace > WorkOrderInspections to view the available attributes from the workspace.

Type in or paste the following message into the text box: 

Work Order Id: {route.WorkOrderInspections.WorkOrderId}
Inspection Id: {route.WorkOrderInspections._inspection_id}




Select OK and Apply to save and return to the canvas. 

At this point, the "CityworksWOReceiver" automation should look like this:



Save and click Start Debug to start the Automation. 


12. Test the Webhook Workflow
First, ensure that the CityworksWOReceiver is running.



Once running, navigate to Cityworks in a browser tab. We need to create an event that will trigger the webhook. There are a couple of ways we can do this: 

  1. Create a new work order: repeat all of Part 2, Step 9-10.
  2. Update the existing work order: return to the same work order created in Part 2, Step 9. Change its status to another value, like “1-Requested”. Save. Change its status back to the value that is associated with the webhook, e.g. “5-Completed“. 

    


Navigate back to the FME Flow “CityworksWOReciver” automation. Open the automation log. 


This time, there is evidence of a complete workflow: 

  1. A logged webhook message
  2. A job submission
  3. A logged work order id and new inspection id. 





Back in Cityworks, refresh the work order. 

From the three dots beside Work Order in the banner, select Related Activities.  



In Cityworks, there is a new inspection created by our FME Flow Automation!



Congratulations! You have successfully created an FME Flow Automation that can receive and process Cityworks webhooks. 

Use this same workflow pattern to build real-time workflows that automate different tasks and procedures in Cityworks, notify employees, or connect systems across your organization. 
 

Additional Resources

Was this article helpful?

Comments

0 comments

Please sign in to leave a comment.