City Requests

Module Definition

Auburn FixIt (Rock Solid OneView, a Granicus product) is a hosted front door over the Cityworks APIs the city already licenses: it imports the active service request templates, walks a citizen through issue → location → the template's questions, creates the SR through the Cityworks REST API, and reflects status back. This module brings that front door into the City Viewer, on integration plumbing that already exists in MyGov:

• CityworksService — the API chokepoint (token auth, Ams/ServiceRequest/Problems, /Create, /ById, raw passthrough).
• CityworksHandler (workflow V2) — CreateServiceRequest with a full field whitelist (ProblemSid, Answers/DateAnswers, X/Y/WKID, the Caller* contact block) and entity tracking (Cityworks/ServiceRequest ids in the workflow logs).
• The Teams bot's conversation engine — a working, DB-configured guided intake over the same service (ProblemSelect → Location → DynamicForm steps, ArcGIS-backed location strategies). The PWA flow is the same state machine wearing a citizen skin.
• ArcGisService — address search / nearby queries for the location step.
• The cityworks webhook ingest — the future hook for "your request was closed" notifications.

1 · Curation & Data

One new persistent thing: the curated issue list. It lives in the DataList system (data.List slug cityapp-report-issues) — the same staff-editable store that drives the website nav and the City Viewer's services menu, edited on the same portal page with the same icon picker.

Options considered

Submission tracking needs no new table. The FormResponse is the transaction record; entity tracking stores the created SR id. The citizen's status lookup is authorized by a stateless token — HMAC(requestId, server secret), nothing persisted, nothing enumerable. The generic forms endpoint can't mint module tokens, so right after submit the app exchanges its { formResponseId, requestId } pair (both in the submit response) at POST /city-requests/claim: the pair must match the stored form data and be recent, closing the enumeration hole.

2 · API & Endpoints

Spike findings (validated live, 2026-07)

• Auth: CW 23.13 requires the Authorization: cityworks {token} header — a query-string token alone returns Status 3 (unauthenticated). CityworksService already sends it.
• Endpoint: template Q&A is Ams/ServiceRequest/QA with a singular ProblemSid; ~222 active templates (ProblemSid, DomainId, ProblemCode, Description) come from Ams/ServiceRequest/Problems.
• The Q&A model is a branching graph. Example (ProblemSid 17094, "Garbage Service Interrupt"): questions carry sequence; each answer carries AnswerFormat (DATE — a date input; THISTEXT — a fixed choice; FREETEXT — free text), optional TellCaller guidance ("must be submitted one week prior…"), and NextQuestionId (0 = done). "Other → explain" is expressed as a THISTEXT choice branching to a FREETEXT question.
• Still to confirm at first live create (internal testing, not design-blocking): the exact Answers/DateAnswers submit payload shape (AnswerId + text pairs), and WKID 4326 acceptance on create.

3 · Cityworks Integration & Boundary

• One chokepoint: every call goes through CityworksService (token, error typing). New method for this module: GetTemplateQuestionsAsync; everything else exists.
• Reads are direct (issues list, questions, status, nearby — low latency, not transactions); the write runs through the workflow engine (system Form + CityworksHandler.CreateServiceRequest) for the durable trail. Identical split to the library module.
• Nearby duplicate check adds two typed reads to the ICityworksService chokepoint — SearchServiceRequestsAsync (Ams/ServiceRequest/Search → RequestIds) and GetServiceRequestsByIdsAsync (ByIds → RequestBase) — plus a shared CityworksSr field-name constants block the status read also adopts. Returned SRX/SRY are reprojected to WGS84 by GeometryHelper.ToWgs84 (gained ProjectFromWebMercator + ProjectFromAuburn + magnitude classification). Server-side ExtentXY spatial prefilter is deferred (a scale optimisation; today's fetch-by-type + in-code distance filter suits transition volumes).
• Attachments: a second workflow action on the same form (AddRequestAttachment, new handler op) consumes the create's RequestId — attachment failure must not fail the SR (photos are best-effort; the SR comments note a failed attach).
• Photos are not portal "Attached Files". Citizen photos ride their own store (/city-requests/photos) and land in Cityworks via AddRequestAttachment — they are never FormResponseUpload rows, so the portal's response-detail gallery shows only the PhotoIds GUIDs. Deliberate (Cityworks is the image system of record); rendering thumbnails in the portal is an optional later enhancement, not a gap in the write path.
• InitiatedByApp: stamp InitiatedByApp = "MyGov City Viewer" (whitelisted field) so staff can tell app-sourced SRs from FixIt/phone intake during the transition.
• Licensing: citizen-sourced SRs ride the same service account Rock Solid would use — confirm with the Cityworks rep that the license covers it (one email, before production cutover).
• Status push (v2): the cityworks webhook ingest already receives SR events; closing the loop is a notification fan-out (eNotifier email first, app push later), not new ingestion.

4 · Location UX

The location step is the module's one genuinely new capability: the City Viewer's first city-wide map (the facility viewer renders indoor floor plans from our own geometry; this needs the city itself). Built as a center-pin picker (cv-location-picker): the pin is fixed at the viewport center and the MAP moves under it — the touch-friendly inversion of a draggable pin — so the chosen point is always whatever sits under the pin's tip. Three entries converge on it: use my location (geolocation flies the map there), search an address (ArcGIS geocode → candidates → fly there; the address stays as the human-readable label while the pin coords stay live, so fine-tune panning refines the point without losing the words), or just pan/zoom the map directly. Coordinates convert map-center (State Plane) → WGS84 client-side (js/geo.js's inverse projection).

Options considered — the map

5 · User Interface

A new routed screen, cv-report (?view=report), presented as a stepper in the app shell: Issue → Location → Details → Review → Done. The Services menu's "Report an issue" tile flips from href (FixIt) to view: "report" — a Data List edit, and the rollback is the same edit.

• Issue — the curated grid (groups as section titles), same tile components as Home; an emergency item short-circuits to the call-this-number interstitial.
• Location — the map step above; the confirmed point echoes as an address label.
• Details — a branching wizard, not a flat form (the live Q&A model branches per answer — see §2's spike findings): one question at a time, following the chosen answer's nextQuestionId until terminal. Kinds map to controls (choice → radio pills, date → date input, freetext → textarea); an answer's guidance (Cityworks TellCaller) renders inline the moment it's selected. Then free-text description, up to N photos, and the contact block (name/email/phone; optional "anonymous" per template policy). Back within the wizard rewinds the answer path. A signed-in drawer session prefills contact when city accounts exist.
• Review — everything on one card; submit shows the workflow result honestly (the engine returns synchronous success/failure).
• Done — reference number + a "check status" link carrying the HMAC token (also copyable); status view renders the minimal status payload.

6 · Anti-abuse & Privacy

• Rate limiting on submit + photo upload (per-IP, ASP.NET rate limiter) — v1 requirement.
• Turnstile-style challenge — wired as a config knob (/city-requests/config returns the site key when enabled); off at launch, flipped without an app release if abuse appears.
• Photos: image-only, size-capped, re-encoded through ImageProcessor (which also strips EXIF — location comes from the pin, deliberately, not from photo metadata).
• PII: the contact block lands in Cityworks (system of record) and transiently in the FormResponse payload — same retention story as every other workflow form; note it in the app's privacy policy page (also needed for Play).

7 · Build Sequence

Dependency order — each step independently shippable/testable. The detailed task list below hangs off these.

1. Spike Built — staff-auth dumps of live problems + template Q&A; validates the question shapes, the WKID, and the curation candidates.
2. Reads Built — /issues + /issues/{sid} shaping + tests; list seeded with the 17094 example (the full staff curation pass remains).
3. Write path Built — handler attachment op, photos, config/claim/status endpoints, per-IP rate limiting. Remaining: staff author the system Form and bind its id in cityapp-config.
4. App flow Built — cv-report (?view=report, Services-tab umbrella): issue grid → location (GPS / geocoder search / manual text) → the branching question wizard → details (description · photos · optional contact) → review → done, with the claim exchange, a local "your reports" memory, and the status view. Verified end-to-end against stubbed endpoints; first live submit still pending the form binding.
5. Map Built — the center-pin aerial-tile picker (cv-location-picker, §4) upgraded the location step in place: GPS/geocode fly the map, panning fine-tunes, the pin's spot is what submits (+ the MapLocation portal-map field).
6. Cutover — menu flip, FixIt link demoted to the website; transition monitoring via InitiatedByApp.

8 · Dev Task List

Living checklist — remove items as they land (don't mark them done). Tags: api app my data/config

• api Next test create (internal testing): confirm the photo actually landed on the SR in Cityworks — AddRequestAttachment ran on the first live create (7/13), but that SR was deleted before the attachment was checked. The create itself validated: SR created, WKID 4326 accepted, reference number returned via trackedEntities.
• data/config Curation pass — the list exists with one validated example (17094, via db/seed-cityapp-report-issues.sql); staff pick the remaining ~10–15 citizen issues from the spike's problem dump (labels, icons, groups; flag any emergency items) in the Data List Manager.
• api Turnstile server-side verification on submit — lands when the challenge is first enabled (the site-key knob and config plumbing already exist; off by default).
• data/config Author the system Form ("Citizen service request") with the Cityworks CreateServiceRequest + AddRequestAttachment actions; put its form id in the cityapp-config DataList (cityRequestsFormId — seeded empty).
• my Map the request form's MapLocation field as type location in the form schema so ResponseDetailPage renders the embedded map (§4's portal-map contract).
• data/config Decide whether City Requests' precision warrants targeted L01–L03 aerial regeneration in dense areas (the open item flagged in lightning-proximity §6a).
• app After first live create: reconcile the submitted Answers/DateAnswers mapping with what Cityworks actually recorded (the Comments transcript is the safety net until then).
• my Nothing new required — curation uses the Data List Manager (icon picker shipped). Optional later: a spike-fed "issue browser" to speed the curation pass.
• data/config Cutover: flip the services-menu item to view: "report"; keep FixIt linked from the website until the retirement decision.
• api Post-cutover: delete the spike endpoints; confirm Cityworks licensing email is on file.

9 · Roadmap (post-v1)