Operations: Link Migrations & Runbooks
Relevant source files
The following files were used as context for generating this wiki page:
GoGovSG provides administrative operations for managing link ownership and performing bulk data migrations. These operations allow authorized users to transfer single links or entire user accounts to new email addresses and perform complex batch tasks like bulk QR code generation via serverless infrastructure.
Sources: README.md:213-214, src/server/modules/user/tests/UserController.test.ts:241-245
Link Ownership Migration
Authorized administrators manage link transfers through the AWS Lambda console or internal API controllers. Ownership migration updates the userId associated with short links in the PostgreSQL database, ensuring that all related data—including click statistics and tags—moves to the new owner.
Sources: README.md:216-220, test/end-to-end/DrawerLogin.spec.ts:167-175, test/end-to-end/LinkAudit.spec.ts:74-85
Migration Procedures
You can perform migrations using two primary methods depending on the scope of the transfer:
- Single Link Transfer: Transfers one specific
shortUrlto a target email address. - Account-wide Transfer: Migrates every link owned by one email address to another email address.
The following sequence diagram illustrates the logic flow for a link transfer initiated via the user interface or API.
The transfer process updates the ownership record while maintaining the integrity of the original link's metadata and history.
Sources: src/server/modules/user/tests/UserController.test.ts:251-260, test/server/repositories/UrlRepository.test.ts:100-110, test/end-to-end/DrawerLogin.spec.ts:182-185
Manual Lambda Triggers
For production environments, specific Lambda functions handle these migrations. You must provide a JSON event body to the relevant function (e.g., gogovsg-production-migrate-url-to-user).
| Operation Type | Event Body Key 1 | Event Body Key 2 |
|---|---|---|
| Single Link | shortUrl | toUserEmail |
| Full Account | fromUserEmail | toUserEmail |
Sources: README.md:223-241
Bulk Operations and Serverless Jobs
The system utilizes serverless functions to process resource-intensive tasks such as bulk QR code generation and link data exports. These functions operate outside the main Express server to prevent performance degradation during large-scale operations.
Sources: README.md:65-67, src/server/serverless/bulk-qrcode-generation/index.js:10-15
Bulk QR Code Generation
The bulk-qrcode-generation Lambda processes batches of short links to generate QR codes in multiple formats (SVG and PNG). It follows a structured pipeline:
- Input Validation: Receives
mappingsand ajobItemIdfrom an SQS queue. - CSV Generation: Creates a manifest of the link mappings.
- Image Processing: Generates QR code files in
/tmpdirectories for both SVG and PNG formats. - S3 Archiving: Zips the generated images and uploads them to a designated S3 bucket.
- Cleanup: Removes temporary files and sends a completion message via HTTP.
Sources: src/server/serverless/bulk-qrcode-generation/index.js:16-56
This flowchart describes the internal logic of the bulk QR code generation Lambda function.
Sources: src/server/serverless/bulk-qrcode-generation/index.js:10-58
Link Auditing and History
Operation-level changes are tracked in a link history log. This ensures that every migration or state change is auditable.
- Change Sets: When a link is transferred, a "Link Owner update" change set is recorded.
- State Changes: Disabling or enabling a link triggers a "Link Status" update.
- Metadata Changes: Updates to the long URL or tags are captured as specific audit events.
Sources: test/end-to-end/LinkAudit.spec.ts:25-30, 47-52, 102-108
Infrastructure Requirements for Operations
The successful execution of migration and bulk operations depends on specific AWS infrastructure and environment variables.
| Variable | Type | Description |
|---|---|---|
DATABASE_URL | SecureString | Connection string for the PostgreSQL database used by Lambdas. |
BULK_GENERATION_BUCKET | String | S3 bucket for storing generated QR code zip files. |
EB_CALLBACK_ENDPOINT | String | Endpoint used by Lambdas to notify the main server of job completion. |
SQS_REGION | String | AWS Region for the bulk QR code generation queue. |
Sources: README.md:144-150, 196-200
Operations in GoGovSG prioritize data integrity and auditability. By separating long-running tasks into serverless functions and providing clear runbooks for link transfers, the system maintains high availability while allowing for complex administrative interventions.