Skip to main content

Service Desk Admin Guide

This guide covers day-to-day administration: setting up clients, managing organization mappings, configuring stakeholder access, understanding the data flow, and troubleshooting common issues.

Setting Up a New Client​

To give a client access to the service desk:

  1. Create the client in Admin > Clients (if not already done)
  2. Identify the Jira organization — find the organization ID in Jira Admin > Organizations
  3. Identify the organization — ticket reads are scoped by the client's JSM organization id (service_desk_org_mappings.jira_organization_id), read from analytics_marts.mart_kpi__service_desk_tickets. The older text project_label scoping on raw jira.jira_issues has been replaced.
  4. Create the org mapping — go to Admin > Service Desk and click "Add Mapping":
    • Select the client
    • Enter the Jira organization ID and name
    • Enter the ClickHouse project label
    • Enter the JSM service desk ID (usually 1)
  5. Assign permissions — ensure the client's role includes servicedesk:read (and servicedesk:write if they should create/comment)
warning

The project_label must be unique across all mappings. If two clients share a label, one client could see the other's requests. The database enforces this with the UNIQUE(project_label) constraint from migration 000061.

Organization Mapping Management​

Viewing Mappings​

Navigate to Admin > Service Desk (/admin/service-desk). The table shows all mappings with client name, Jira org, project label, and service desk ID. Filter by client using the dropdown.

Creating a Mapping​

Click Add Mapping and fill in all fields. A client can have multiple mappings (e.g., support + premium tiers mapped to different Jira organizations).

Editing a Mapping​

Click the edit icon on a row. You can change the Jira org ID, name, project label, and service desk ID. The client cannot be changed — delete and recreate instead.

Deleting a Mapping​

Click the trash icon and confirm. This immediately removes the client's access to requests under that project label.

info

Deleting a mapping does not affect requests in Jira or ClickHouse. It only removes the client's ability to see those requests in Proxima Console.

Data Flow​

Optimistic Pending Writes​

When a user creates a request or transitions a status, the change is written to Jira immediately but takes until the next Dagster sync to appear in ClickHouse. To avoid confusion, the backend:

  1. Stores a pending write in PostgreSQL with the action details
  2. When listing requests, merges pending writes into the ClickHouse results:
    • create_ticket actions are prepended as synthetic rows with status "Pending"
    • transition actions update the status of matching requests
  3. Pending writes expire after PROXIMA_SERVICE_DESK_PENDING_TTL (default 30 minutes)
  4. A background goroutine cleans up expired rows every 60 seconds

All write actions (create, transition, comment) are also recorded in the service_desk_actions audit table for traceability.

Stakeholder User Access​

Stakeholder users (e.g., account managers, engineers raising requests on behalf of clients) can access the service desk with the same servicedesk:read/servicedesk:write permissions as regular client users. Key considerations:

  • My Requests filter: Stakeholder users will only see requests where reporter_email matches their own email. To see all client requests, they should leave the My Requests toggle off.
  • Raising on behalf of: When a stakeholder creates a request for a specific end user, the raiseOnBehalfOf field in the create request API body sets the JSM reporter to that user. The reporter_email stored in ClickHouse reflects the end user after the next Dagster sync.
  • Org scope: Stakeholder users must have an org mapping that includes the relevant client's project labels, or be granted access through the client's organization.

Request Types​

The create request form currently supports two Jira request types:

IDNameRequired Fields
10Planned Tasksummary
12Incident Reportsummary, severity (customfield_10049)

Field definitions are fetched from the JSM API and cached for 24 hours (configurable via PROXIMA_JSM_FIELD_CACHE_TTL).

Troubleshooting​

Requests not appearing for a client​

  1. Check org mapping exists — Admin > Service Desk, verify the client has a mapping
  2. Verify the org scope — query ClickHouse directly: SELECT DISTINCT jsm_org_id, org_name FROM analytics_marts.mart_kpi__service_desk_tickets and confirm the mapped organization id matches
  3. Check the Dagster sync — if recently created requests are missing, the Jira mirror or the mart refresh may be delayed or failing
  4. Check permissions — ensure the user's role includes servicedesk:read

"Super admins must filter by organization" error​

Super admin accounts have no automatic org scope. They must select an organization in the org picker dropdown, or use a non-admin account for testing.

Create request fails with "service desk not accessible"​

The service_desk_id in the create request body must match a mapping for the caller's client. Verify the mapping's service_desk_id field.

Stale data / recently created request shows as "PENDING"​

This is expected until the next sync. The request was created in Jira and appears with full data after the next Dagster sync. If it persists well beyond that, check:

  • The Dagster job is running and healthy
  • The request was actually created (check Jira directly)
  • The pending write TTL hasn't been set too low

"My Requests" shows no results​

The My Requests filter matches on reporter_email in ClickHouse. If it returns no results:

  • Confirm the Dagster sync populates reporter_email in the ticket mart
  • Verify the user's email in Proxima matches the reporter email stored in Jira
  • Check that the user has actually created requests (not just viewed them)

JSM rate limiting (429 errors)​

The backend rate-limits JSM requests to 50/second. If you see 429 errors, either:

  • Too many concurrent users are performing write operations
  • The JSM API is applying its own rate limits

The backend propagates 429 as-is to the frontend with a "please retry" message.

CSV export is empty​

  • Verify the user's org scope has requests matching the current filters
  • Super admins must select an organization first
  • Check that the date range filter isn't excluding all results