Slide set describes use cases for issue tracking system for Helsinki. It also lists items where we want feedback from developers. Give us feedback so that we can develop the best possible interface for developers! We will discuss more about these in this event https://www.facebook.com/events/273621356063332

1. Helsingin kaupungin
kehittäjätilaisuus
CitySDK use cases and request
for developer feedback
Slide set for discussion before Helsinki 10.5.2012 meetup
00.0.2008 Esitelmän pitäjän nimi
Jaakko Rajaniemi

2. Reading guidelines
• Slide set lists supported use cases for issue tracking /service request
interface.
– slide set also lists use cases which are under discussion
• Use cases are planned to use Open311 standard version 2.0 (or 2.1 if
available)
– All use cases under discussion are not compliant with Open311.
• New proposed parameters are marked with green color
– We would like to have these parameters
– These are not compliant with Open311 standard.
• Other parameters which have been proposed but not adopted are
marked with red color
• Developer feedback is asked on new and proposed parameters and
other topics listed in the slide set
18.4.2012 Jaakko Rajaniemi 2

3. Content
• Motivation for Open311
• Supported use cases
• Where we need developer feedback
• Use cases under consideration
00.0.2008 Jaakko Rajaniemi

4. Motivation for Open311
• It is the only standard on this area.
• It is used in several cities in USA.
• It has quite an active community behind.
⇒It’s good enough and has potential to become
globally used standard.
http://www.open311.org/
00.0.2008 Esitelmän pitäjän nimi

5. Supported use cases
• Use case 1: Submitting a service request
• Use case 2: Quering individual service request
• Use case 3: Quering service requests
• Use case 4: Listing service request types
• Use case 5: Mobility of user
18.4.2012 Jaakko Rajaniemi 5

6. Use case 1: Submitting a service request
• Service request can be submitted with following info:
– Description and title
– Location (not obligatory)
• lat/long (WGS-84), address, City specific data identiying service request object , e.g.
Helsinki Service Map
– Service request type
– Contact information
• Name, e-mail address, phonenumber
– Media attachment
• Photo and possibly other document formats
– Web link to external serive where service request originates (e.g. Omakaupunki)
– PROPOSED: Priority of the service request, Geometry (e.g. lines, polygons)
• Response includes
– Service request identification (ID)
– Web link to city’s own web page where service request is published
– PROPOSED: related_service_request_id
18.4.2012 Jaakko Rajaniemi 6

7. Use case 2: Quering individual service
request
• Individual service request can be queried using service request
identification ID. Response includes:
– Description and title
– Location
• lat/long (WGS-84), address, City specific data identiying service request object , e.g.
Helsinki Service Map
– State (open, closed)
• PROPOSED: Option to have more status values
– Response text
– Submission date and time
– Update date and time
– Expected date and time when fixed
– Government agency responsible for the service request
• PROPOSED: Option to have multiple agencies
– Service request type
– URL address of attachment
– PROPOSED: Priority of the service request, Geometry (e.g. lines, polygons)
18.4.2012 Jaakko Rajaniemi 7

8. Use case 3: Quering service requests
• Service requests can be queried
– Submission date and time (start and endtime)
– Location (bounding box and/or lat/long+radius)
– Status (all, closed or open)
– Service request type
• Response includes:
– Description and title
– Location
• lat/long (WGS-84), address, City specific data identiying service request object , e.g.
Helsinki Service Map
– State (open, closed)
• PROPOSED: Option to have more status values
– Response text
– Submission date and time
– Update date and time
– Expected date and time when fixed
– Government agency responsible for the service request
• PROPOSED: Option to have multiple agencies
– Service request type
– URL address of attachments
– PROPOSED: Priority of the service request, Geometry (e.g. lines, polygons)
18.4.2012 Jaakko Rajaniemi 8

9. Use case 4: Listing service request types
• External application can query list of service request types which are
supported by the city.
– Name of service request type
– Description of service request type
– Group of service request type
18.4.2012 Jaakko Rajaniemi 9

10. Use case 5: Mobility of service user
• Service user who sends service request may move
between cities and use same application to submit service
requests. Service requests are routed to the correct city
endpoint without the help of the requestor.
– No solution yet.
– We try to have solution which is compliant with Open311
standard
– Solution may no have any impact on service request interface
18.4.2012 Jaakko Rajaniemi 10

11. Where we need developer feedback (1/5)
• Media upload
– Support for photos and what else?
– Synchronous Multipart/Form upload
• Service request types and groups
– Different types like potholes, trash bins, traffic
signs, parks, roads, parking, …
– How to decide types and groups in the best
way?
00.0.2008 Jaakko Rajaniemi

12. Where we need developer feedback (2/5)
• Status values for service requests
– Open, closed
– New values needed?
• New location parameters
– How to use Service Map unit ids as location
parameter?
– Any use for more complex geomerty like lines
and polygons?
00.0.2008 Jaakko Rajaniemi

13. Where we need developer feedback (3/5)
• Accurate address parameter
– Manually typed addresses are not accurate
– Lat,Lon mapped to accurate address or some
other mean to verify the address
• Push notifications on changes
– Currently only pull model supported, enough?
– Pull vs. Push model and how to do push
notifications
00.0.2008 Jaakko Rajaniemi

14. Where we need developer feedback (4/5)
• Mobility between cities
– How to detect where the user is and where to
send service request?
– Helsinki vs. Espoo vs. Vantaa
• How to use user identification parameters?
– Current plan is not to have user accounts on city’s
service
– How to use device_id and author_id parameters?
00.0.2008 Jaakko Rajaniemi

15. Where we need developer feedback (5/5)
• Language support is missing
– How to indicate the preferred language?
– New language parameter is considered.
• How to organise interface testing and usage?
– Test interface is required where developers can see
sent parameters and responses
– API key will required for posting service requests
00.0.2008 Jaakko Rajaniemi

16. Use cases under consideration
• Commenting on service requests
• Editing and removing service requests
• Account handling for users
• Voting for service requests
18.4.2012 Jaakko Rajaniemi 16

17. Use case: Commenting on service requests
• People can comment on service requests. Comment can
include following information:
– Comment text
– Comment title
– Contact info
• Name, email address, phonenumber
18.4.2012 Jaakko Rajaniemi 17

18. Use case: Editing and removing service
requests
• Person can modify or delete own service request after it
has been submitted.
18.4.2012 Jaakko Rajaniemi 18

19. Use case: Account handling for users
• Users have an account for service . The account allows
users to search and modify own service requests.
• Account may be same as the account, which city also
provides.
18.4.2012 Jaakko Rajaniemi 19

20. Use case: Voting on service requests
• Person can vote for favourite service requests.
18.4.2012 Jaakko Rajaniemi 20

21. Contact
• Jaakko.Rajaniemi@hel.fi
• +358 40 516 5931
• Twitter: @jaakko
• Facebook:
https://www.facebook.com/CitySDKHelsinki
00.0.2008 Esitelmän pitäjän nimi