ServiceNow integration setup

ServiceNow ITSM and CSM are common at state agencies and larger municipalities. The adapter creates a ServiceNow **Incident** for every routed report and PATCHes it to `state=6 Solved` on resolution.

You can use either basic auth or OAuth2 — basic is simpler to start with, OAuth is the right answer for production.

**Basic auth path:**

1. Have your ServiceNow admin create a service account with the `itil` role (enough to create + update incidents).
2. In Turtini: `/civicreports` → **Integrations** → **ServiceNow** kind.
3. Fields:
- **Instance URL** — `https://acme.service-now.com`
- **Auth mode** — Basic
- **Username** + **Password** for the service account
4. Save.

**OAuth2 path:**

1. ServiceNow: **System OAuth → Application Registry → New → Create an OAuth API endpoint for external clients**. Save the **Client ID** + **Client Secret**.
2. Have an admin grant your service account a refresh token via the password OAuth flow once (use Postman or curl against `/oauth_token.do`; the response carries `refresh_token`).
3. Turtini integration:
- **Instance URL** — same as above
- **Auth mode** — OAuth2
- **Client ID** + **Client Secret** + **Refresh Token**
4. Save.

Custom fields the adapter populates (configure these on the Incident table for reporting + filtering):
- `u_turtini_report_id` (string, indexed)
- `u_turtini_jurisdiction` (string)
- `u_turtini_category` (string)

Other fields the adapter sets:
- `short_description` = report title
- `description` = report description
- `urgency` / `impact` = derived from Turtini priority (urgent → 1, high → 2, normal → 3)
- `caller_id` = reporter email (use a Caller-Lookup business rule on your side if you want to attach this to a Citizen record)
- `contact_type` = `self-service`
- `location` = reverse-geocoded address (falls back to `lat,lng` string)

On resolution the adapter PATCHes `state: '6'`, `close_code: 'Solved (Permanently)'`, and `close_notes` from your resolution note. The Incident `sys_id` from create is persisted on the Turtini report as `externalCaseIds.servicenow`.

Common gotchas:
- **401 on every call** with basic auth = check the username has the `itil` role and an unexpired password.
- **OAuth refresh failed** = your refresh token may have expired (ServiceNow refreshes can have configurable lifetimes). Re-issue and re-save.
- **State change doesn't stick** = your instance has a State Flow that overrides PATCH writes. Talk to your ServiceNow admin about exempting Turtini's integration user from that flow.