Self-Serve Cityworks Workflows with FME Flow Apps

Introduction

In the previous exercises, we've authored workflows that can be automated for complete integration and transformation of 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 allows end users to submit and request information or trigger processes. The best part? No coding required. 

This tutorial creates an FME Flow App from the previous exercise's workspace. The final Flow App allows end-users to submit their own Excel spreadsheet data for processing. The Flow App intakes 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, 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 administrator to identify entity types specific to your organization. "WHYDRANT"  is specific to the instance of Cityworks 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, type in your own Cityworks URL.

For Work Order ID, from the drop-down menu, select Attribute Value > "_work_order_id"

For Attachment, from the drop-down menu, select User Parameter > Create User Parameter. Uncheck the "Required" setting, then press OK to accept the rest of the 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 that will allow better 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 certain data formats directly back 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 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 colours. 

Click OK. Copy the Workspace App URL to your clipboard. 



5. Configure the Flow App Permissions
FME Flow does not extend access to dependent web and database connections by default. 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. 

Click the "Run" button to run the app. If the job is successful, an HTML table is immediately returned to the browser. 



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. 

Additional Resources

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