Service Desk Configuration

The service desk feature requires ClickHouse and JSM API credentials, plus at least one organization mapping.

Environment Variables

ClickHouse Connection

Variable	Required	Default	Description
PROXIMA_CLICKHOUSE_HOST	Yes	—	ClickHouse HTTP interface hostname
PROXIMA_CLICKHOUSE_PORT	No	443	ClickHouse HTTP port
PROXIMA_CLICKHOUSE_USER	No	default	ClickHouse username
PROXIMA_CLICKHOUSE_PASSWORD	Yes	—	ClickHouse password
PROXIMA_CLICKHOUSE_TLS_SKIP_VERIFY	No	false	Skip TLS certificate verification

JSM API Connection

Variable	Required	Default	Description
PROXIMA_JSM_BASE_URL	Yes	—	Jira Cloud base URL (e.g., https://yoursite.atlassian.net)
PROXIMA_JSM_API_EMAIL	Yes	—	Service account email for JSM API
PROXIMA_JSM_API_TOKEN	Yes	—	API token for the service account
PROXIMA_JSM_FIELD_CACHE_TTL	No	24h	How long to cache request type field definitions
PROXIMA_TICKETING_REQUEST_TYPE_ID	No	—	Request type of tickets Console opens itself (maintenance windows). Without it the "Create service desk ticket" option says "Ticket creation is not configured"

Feature Settings

Variable	Required	Default	Description
PROXIMA_SERVICE_DESK_PENDING_TTL	No	30m	How long optimistic pending writes are shown before expiry

tip

If PROXIMA_CLICKHOUSE_HOST or PROXIMA_JSM_BASE_URL are empty, the service desk feature is disabled and the sidebar section is hidden. The backend returns 503 Service Unavailable for any service desk endpoint.

Organization Mappings

Organization mappings link Proxima Console clients to Jira organizations and ClickHouse project labels. Without at least one mapping for a client, that client's users see an empty service desk.

Fields

Field	Type	Description
client_id	UUID	The Proxima Console client
jira_organization_id	string	Jira organization ID (from JSM admin)
jira_organization_name	string	Display name shown in the org picker
project_label	string	ClickHouse project_label value used to scope queries
service_desk_id	string	JSM service desk ID for creating tickets

Constraints

• Each (client_id, jira_organization_id) pair must be unique
• Each project_label must be globally unique (prevents cross-client data leakage)
• client_id cannot be changed after creation (delete and recreate instead)

Managing Mappings

Mappings are managed via the Admin > Service Desk page (/admin/service-desk), which requires the servicedeskconfig:read/write/delete permissions.

You can also manage mappings via the API:

# List all mappings
curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/api/v1/service-desk/admin/organizations?page=1&per_page=50"

# Create a mapping
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "uuid-here",
    "jira_organization_id": "42",
    "jira_organization_name": "Acme Corp",
    "project_label": "acme-sup-1-010125",
    "service_desk_id": "1"
  }' \
  "$BASE_URL/api/v1/service-desk/admin/organizations"

Database Migrations

The service desk spans several migrations:

Migration	Description
000061	Creates service_desk_org_mappings (with its UNIQUE(project_label)) and service_desk_pending_writes
000063	Creates service_desk_actions audit table for write operation traceability
000064	Adds the chk_sd_action_type CHECK on service_desk_actions.action (create, comment, attachment, transition, approval)

Run make migrate-up to apply all migrations. Each migration is idempotent and safe to run on existing databases.

ClickHouse Data Requirements

The following ClickHouse tables must exist. Dagster is the sole writer — it mirrors Jira roughly every minute and refreshes the marts hourly.

Database	Table	Purpose
analytics_marts	mart_kpi__service_desk_tickets	The ticket read path. Curated ticket data, scoped by jsm_org_id, with a normalized status_category (done / in_progress / to_do).
analytics_marts	mart_kpi__sla_compliance	Per-request SLA metrics
analytics_marts	mart_kpi__delivery_issue_metrics	Per-request delivery metrics
jira	jira_issues	Raw mirror. Ticket reads have migrated off this to the mart above; two reads still use raw — ListProjects (joins to cdm.jira_applications, which the mart has no bridge to) and the FP-project view.
jira	status_changes	No longer read. The ticket detail timeline is served from the Postgres read model (service_desk_ticket_status_changes); this table is listed only so an operator does not go looking for a reader that no longer exists.

Reads are scoped by the client's JSM organization id (service_desk_org_mappings.jira_organization_id), not the older text project_label.

Required Columns in jira.jira_issues

In addition to standard Jira fields, the following columns must be present:

Column	Type	Description
reporter_email	String	Email of the request reporter; used by the My Requests filter
linked_issue_key	String	Cross-linked issue key (e.g., PXD engineering reference)

info

The ClickHouse client uses parameterized queries via the HTTP interface (JSONEachRow format). Queries are read-only — the backend never writes to ClickHouse.