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

Feature Settings

Variable	Required	Default	Description
PROXIMA_SERVICE_DESK_PENDING_TTL	No	5m	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 and service_desk_pending_writes tables
000063	Creates service_desk_actions audit table for write operation traceability
000064	Adds CHECK constraint to service_desk_org_mappings for data integrity

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 and be populated by your n8n sync:

Database	Table	Purpose
jira	jira_issues	Raw request data (issue_key, summary, status, reporter_email, linked_issue_key, etc.)
jira	status_changes	Status transition history
analytics_marts	mart_kpi__sla_compliance	Per-request SLA metrics
analytics_marts	mart_kpi__delivery_issue_metrics	Per-request delivery metrics

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.