Skip to content

Runbook: Quick Links Management

Manage the Quick Links list displayed in the Research Assistant sidebar. Quick links give users direct access to frequently used external resources without leaving the application.

Prerequisite: complete CLI Setup before proceeding.

Note: Quick links are only displayed when the ENABLE_QUICK_LINKS environment variable is set to true for the deployment. Contact a developer if the sidebar list is not visible after adding links.

All commands below target PROD. Swap --profile prod for --profile uat to target UAT.

altaforge-ra-cli --profile prod api admin quick-link list

Output is a JSON array ordered by sortOrder. The id field is the LINK_ID required by other commands.

[
  { "id": 1, "name": "Benefits Portal", "url": "https://benefits.example.com", "sortOrder": 0 },
  { "id": 2, "name": "Policy Library", "url": "https://policy.example.com", "sortOrder": 10 }
]

altaforge-ra-cli --profile prod api admin quick-link add "Display Name" "https://example.com"

To control display position, pass --sort-order. Links are shown in ascending order; the default is 0.

altaforge-ra-cli --profile prod api admin quick-link add "My Link" "https://example.com" --sort-order 20

At least one of --name, --url, or --sort-order must be provided:

altaforge-ra-cli --profile prod api admin quick-link update <LINK_ID> --name "New Display Name"
altaforge-ra-cli --profile prod api admin quick-link update <LINK_ID> --url "https://new-url.example.com"
altaforge-ra-cli --profile prod api admin quick-link update <LINK_ID> --sort-order 5

Multiple fields can be updated in a single command:

altaforge-ra-cli --profile prod api admin quick-link update <LINK_ID> \
  --name "Updated Name" \
  --url "https://updated.example.com"

altaforge-ra-cli --profile prod api admin quick-link delete <LINK_ID>

Common Workflows

Links are displayed in ascending sortOrder. Assign non-overlapping integers with gaps (e.g. 10, 20, 30) so future insertions fit without renumbering the whole list.

Move a link to the front (appears first):

altaforge-ra-cli --profile prod api admin quick-link update <LINK_ID> --sort-order 0

Insert a link between two existing ones (e.g. between sort order 10 and 20):

altaforge-ra-cli --profile prod api admin quick-link update <LINK_ID> --sort-order 15

Apply the same change to UAT first

Replace --profile prod with --profile uat in any command above. UAT and PROD are independent; changes to one do not affect the other.

Bulk Load

Use the bulk script when loading an initial dataset or replacing all quick links from a file. Unlike the sites and escalation scripts, this script talks to the backend API — no database access or VPN is required, but you must supply a bearer token when targeting a deployed environment.

Supported format: JSON only.

1. Prepare the JSON file

Top-level array of objects. name and url are required; sort_order is optional (defaults to 0):

[
  { "name": "Benefits Portal", "url": "https://benefits.example.com", "sort_order": 0 },
  { "name": "Policy Library", "url": "https://policy.example.com", "sort_order": 10 }
]

2. Obtain a bearer token (deployed environments only)

export TOKEN=$(altaforge-ra-cli --profile prod auth ms get-token)

This uses the MSAL token from the configured profile — the same token the CLI uses for all other commands. If no cached token exists you will be prompted to sign in via device code flow.

For UAT, swap --profile prod for --profile uat.

Not required for local dev when DISABLE_AUTH=true.

3. Load the data

Warning: CLEAR=--clear permanently removes all existing quick links before loading. Any link not present in the file will be lost. Before running, confirm that the file is the complete and authoritative dataset — not just the links you are adding or changing.

Always use CLEAR=--clear unless you have been explicitly told to append.

PROD

BASE_URL must be the same api_base_uri you configured for the profile in the CLI Setup runbook (e.g. https://my-app.example.com/api).

make load-quick-links \
  FILE="path/to/quick_links.json" \
  BASE_URL="https://<prod-frontend-hostname>/api" \
  TOKEN="$TOKEN" \
  CLEAR=--clear

UAT

export TOKEN=$(altaforge-ra-cli --profile uat auth ms get-token)
make load-quick-links \
  FILE="path/to/quick_links.json" \
  BASE_URL="https://<uat-frontend-hostname>/api" \
  TOKEN="$TOKEN" \
  CLEAR=--clear

The script prints the number of links seeded on success:

Seeded 5 quick link(s).

Append mode (avoid unless instructed)

Omitting CLEAR=--clear adds links without removing existing ones. This creates duplicates if the same file is loaded more than once. Only use append mode if a developer has explicitly instructed you to.

4. Verify the load

After loading, run the list command and confirm the count matches the file:

altaforge-ra-cli --profile prod api admin quick-link list

Escalation

If a command returns an unexpected error, escalate to the development team with:

  • The exact command run.
  • The full error output.
  • The environment (UAT or PROD) and approximate time.