Define Comment Handling

[philipashlock]

Comments or other updates are crucial to enable collaboration around around issue reporting without generating duplicate reports. This could potentially be merged with #51 (ticket history) much like Trac handles comments and revisions in the same way.

This has been discussed on the following thread:
http://lists.open311.org/groups/discuss/messages/topic/2L05gDVaunVQpQzcqdLDpT

[philipashlock]

Comment handling with Accela Open311 is documented at https://github.com/Accela-Inc/accela-open311#get-comments-for-a-service-request

[zbeat]

bump

@philipashlock Perhaps we could revisit support for comments on one of the next monthly calls?

[peterwtux]

For reading existing info, we've always include comments in the status_notes field. Currently they're strings with string timestamps, but we're about to adopt an extension to clean that up for GET /requests.FMT and GET /requests/NNN.FMT and present each comment as a unquie object in the response.

We have a UI use case that would benefit from status_notes being structured data (so the UI could highlight new comments on requests of interest to the user).

If the querystring argument "x_structured_notes" is passed with a value of "true", then we will fill <status_notes> with individual <status_note> objects, each having elements <text> (textual content of the note), <created_utc> and <updated_utc> (integer number of seconds after the Unix Epoch UTC), and <updated_string> (textual display of updated_utc). created_utc and updated_utc are proposed as simple, machine-friendly integers to reduce processing cost on the client side. Example:

<status_notes> <status_note> <created_utc>1407437225</created_utc> <text>Contractor has returned and cleaned pavers. Issue has been resolved</text> <updated_string>Thursday, August 7, 2014 2:47 PM</updated_string> <updated_utc>1407437225</updated_utc> </status_note> </status_notes>