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 project label — this is the project_label value in your ClickHouse jira.jira_issues table that corresponds to this client's requests
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 a unique constraint (migration 000064 adds an explicit CHECK constraint).

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 ~2 minutes 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 5 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 will reflect the end user after the next n8n 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:

ID	Name	Required Fields
10	Planned Task	summary
12	Incident Report	summary, 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 project label — query ClickHouse directly: SELECT DISTINCT project_label FROM jira.jira_issues and confirm the label matches
3. Check n8n sync — if recently created requests are missing, the n8n sync 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 for the first ~2 minutes. The request was created in Jira and will appear with full data after the next n8n sync. If it persists beyond 5 minutes, check:

• n8n workflow 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 n8n sync populates the reporter_email column in jira.jira_issues
• 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