GraphQL Workspaces grid migration (Private Cloud)

This runbook describes how to run a grid migration for the graphql-workspaces service in a Private Cloud deployment.

Overview

Grid migration is a backfill operation for workspace GenGrid and GenSearch projects. It converts eligible GenGrid projects to GenSearch (creates a GenSearch conversation and updates the project reference), and ensures GenSearch conversations include the correct workspace reference. Projects already marked as successfully migrated are skipped.

Run this for a whole-environment migration when directed by AlphaSense support or after an upgrade that requires workspace grid migration.

TL;DR: Port-forward to graphql-workspaces → POST /migrate/grids with {"allWorkspaces": true} → save the 202 response → GET uploadedLocation when the job finishes.

Prerequisites

• kubectl access to the cluster
• graphql-workspaces image tag 2.41.0 or later (required for the /migrate/grids API)

Open a port-forward to the graphql-workspaces service (keep this terminal open while you run the migration):

kubectl -n applications port-forward svc/graphql-workspaces 8080:80

Run migration

1. With the port-forward running, send a whole-environment migration request:

   curl --location 'http://localhost:8080/migrate/grids' \
     --header 'Content-Type: application/json' \
     --data '{"allWorkspaces": true}'

2. The API returns HTTP 202 immediately and continues processing in the background. Save the response fields runId, uploadedLocation, totalWorkspaceCount, and totalBatches.

Item	Value
Method	POST
Path	/migrate/grids
Body	{"allWorkspaces": true}

Optional parameters

Use these only when you need to adjust scope or batching:

• batchSize (query) — positive integer, maximum 100. Default is 10 if omitted.
• includeSkipped (query) — set to true or 1 to re-process projects previously marked as skipped.
• Scoped body — for partial reruns, send {"userIds": ["..."]} or {"workspaceIds": ["..."]} instead of allWorkspaces.

Verify outcome

The 202 response includes uploadedLocation: the URL where migration status JSON is stored after the run finishes.

1. Save runId and uploadedLocation from the 202 response.

2. Wait for the job to finish — the status file is written after processing completes, not when the 202 is returned. Allow time proportional to totalBatches and environment size, or follow runId in graphql-workspaces logs until you see completion for that run.

3. Download the status JSON — HTTP GET to uploadedLocation:

   curl --location '<uploadedLocation-from-202-response>'

4. Read the payload — JSON with:

   • meta — includes durationMs and batchSize for the run.
   • records — success, failure, and skipped arrays. Each entry includes userId, workspaceId, and referenceId where applicable; failure entries may include an error string.

   Use the three arrays to confirm scope and spot failures.

5. If the GET is not yet available — retry after a short wait. If uploadedLocation is null, check graphql-workspaces pod logs using runId to confirm outcome.