Skip to content

setup-guide.md

Latest commit

 

History

History
140 lines (93 loc) · 4.09 KB

setup-guide.md

File metadata and controls

140 lines (93 loc) · 4.09 KB
Raw

Setup Guide — Recent Activity Widget

End-to-end setup for the Recent Activity widget — auth, dev harness, and deployment to Rally.

Prerequisites

  • Node 18+ and npm
  • A Rally workspace and project you can access
  • A Rally API key (instructions below)

1. Generate a Rally API key

  1. Sign in to Rally.
  2. Open the API key page: https://rally1.rallydev.com/#/api_key (or click your avatar → API Keys).
  3. Click Create, give the key a name (e.g. widget-dev), pick the workspaces it can access, and copy the full key. It starts with _ and is ~43 chars long.
  4. Treat it like a password — don't paste it into anything that gets committed.

2. Configure auth (pick one)

The Vite dev server proxies /slm/* to Rally. It needs a server URL and an API key.

Option A — auth.json (per-widget, gitignored)

Create auth.json in the widget folder:

{
  "server": "https://rally1.rallydev.com",
  "apiKey": "_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

auth.json is in the root .gitignore — it never gets committed.

Option B — environment variables

Set them in your shell or in a gitignored .env.local file:

RALLY_SERVER=https://rally1.rallydev.com
RALLY_API_KEY=_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Restart npm run dev after changing either source.

3. Run the dev server

npm install
npm run dev

Open http://localhost:5173 in a browser. The widget starts in mock mode by default — no Rally connection needed.

To switch to live Rally data, append ?live=true to the URL:

http://localhost:5173?live=true

4. What you'll see

Mock mode (default)

18 simulated discussion posts spanning multiple artifact types and 5 fictional team members. Posts span 10 days of "history" — useful for validating the relative-time formatting and artifact type filter logic.

Live mode (?live=true)

ConversationPost records from your Rally project, sorted newest-first, scoped to the project set in the dev-harness project picker (top of page).

5. Settings

Click the gear icon (or open Edit Mode) to configure:

Setting Default Range Notes
Max Items 20 5–100 WSAPI pagesize — increase for busier projects
Artifact Types All checkbox list Leave all checked for an unfiltered stream
Show Artifact Detail On toggle Hides the FormattedID + name row if you want a compact feed

6. Build

npm run build         # Production bundle (live Rally data)
npm run build:mock    # Mock bundle (no Rally credentials needed at runtime)
npm run typecheck     # TypeScript check only (no output)

Both builds emit dist/app.js — an IIFE that inlines all CSS. Drop it into a Rally Custom HTML Widget.

7. Deploy to Rally as a Custom View

npx widget-ai deploy

Requires auth.json (or env vars) and rally.config.json to specify the target page and widget slot. The CLI builds, uploads, and prints the Custom View URL.

Manual alternative:

  1. npm run build
  2. Copy the contents of dist/app.js
  3. In Rally, create a Custom HTML Widget on a Custom View page and paste the built code

8. Notes on the ConversationPost endpoint

The widget queries /slm/webservice/v2.0/conversationpost, which returns discussion posts from across all artifact types. A few things to know:

  • Scope: Posts are filtered by the current project. Child-project scope follows the ProjectScopeDown setting from the rally context.
  • Artifact types: The filter uses Artifact.TypePath. If a type path isn't listed in the settings, its posts won't appear even if they exist in the project.
  • Rich text: ConversationPost.Text may contain HTML from Rally's rich-text editor. The widget renders it with dangerouslySetInnerHTML — this matches the legacy ExtJS behavior. Ensure your deployment environment trusts Rally's content.
  • No auto-refresh: The widget does not poll. To see new posts, reload the page or the Custom View. This matches the Broadcom endorsed-widget behavior.