Dockless Vehicles Developer Guide

DDOT Workflows

The below information is provided to give some background/context about how the data starts at 311 and eventually is provided to an operator.

Step A:  311 Request for Dockless Vehicle Issue

The process kicks off with a dockless vehicle complaint/issue request in the DC 311 system.  The resident will submit a request and provide information on the issue they see.  These requests are called "Service Requests". The user shall provide; 

• the vehicle type;
• the address or XY coordinates;
• the company responsible for the vehicle; 
• the issue with the vehicle; and 
• may provide a picture.

Step B:  DDOT Processes Dockless Vehicles Issues

As part of an established process, DDOT accesses the 311 system and captures all service requests which fall under DDOT's responsibility.  This will now include dockless vehicle complaints.  In this step, DDOT inspects the service request for the dockless vehicle operator (a required field from 311) and will create a Work Order at the same location for that specific operator.  (note:  in the diagram to the right, we use the hypothetical operator 'XYZ')

Dockless Operator Workflows

Review the Documentation

Review the introductory API documentation.  This will give you guidance and examples on how to authenticate, make requests and what responses you should expect.

See official Cityworks API documentation.  This is the current documentation available on our public-facing 'Demo' server.  The CW Demo server be your test environment prior to building for production.

Step 0:  Authentication

Use the Authentication/Authenticate method, passing in your username and password to retrieve a token.  You will pass this token with every request you make to the Cityworks API.

Step 1: Find all open work orders

Using the WorkOrder/Search method, you can provide your specific template IDs and Status = Open as a filtering attribute to get a list of all Open Work Orders. You should store this work order ID in your internal system to reference it later.

Now that you have a listing of all open work orders, you can use WorkOrder/byIds to access the detailed information on your work orders in JSON format.

Step 2:  Acknowledge Receipt of the Complaint

Now that you have all the details about each work order, you must update the status for each work order to Pending.  This status change essentially signals to DDOT that you acknowledge the request and that action will be taken.

To change the status of a Work Order, you must use the by using the WorkOrder/Update method, passing in WorkOrderId = "the Work Order ID"

Step 3:  Operator Investigates the Problem

At this step, the dockless operator will go to the location, using the X,Y geographic location provided in the work order. 

• Take a picture of the problem location, even if the vehicle is not there.  (this will prove that an investigation was done)
• If the vehicle in question belongs to the Dockless Operator, they will resolve the issue.  Notes/comments are optional.
• If the vehicle belongs to another operator, the Dockless Operator will make a note of which operator the vehicle belongs to and provide a comment/note about the misassigned issue.

Step 4:  Update the Work Order with the Resolution

• Upload Picture to Work Order.  Each work order must have a picture uploaded showing the investigation.  Preferably, this is a picture of the status of the vehicle prior to the resolution.  For example, a 311 complaint is submitted for a scooter that is hanging on a fence.  DDOT would like a picture of the location prior to removing the scooter from the fence.  See the Cityworks API documentation for guidance on posting work order attachments:  https://cwdemo.ddot.dc.gov/cityworksdemo/apidocs/#/service-info/Ams/Attachments

• Add a comment (conditional).  Operators are welcome to provide a comment in Cityworks about the work that was performed.  For typical cases, this is not required.  However if in your investigation you find that the vehicle belongs to a different operator, you are required to add a comment and note which operator it belongs to.  To make a comment on the work order, you must use WorkOrder/AddComments method, passing in WorkOrderId = "the Work Order ID" as well as Comments = "Your work order comments." 

Step 5:  Close the Work Order

Once you have resolved the dockless vehicle complaint, you must close the work order in the Cityworks system.  In order to close a work order, you must use WorkOrder/Close

Step 6:  Reroute Misdirected Work

If you have visited a complaint location in which the dockless vehicle belonged to another operator, you must send the original work order information to the primary contact for that operator. 

DEVELOPING

Workflow Diagram

Below is a draft diagram of the workflow