> For the complete documentation index, see [llms.txt](https://docs.sealights.io/knowledgebase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/qtest-integration/commands/manage-user-mapping.md).

# User Mapping

The `manage-user-mapping` command is an interactive tool for discovering qTest users and assigning them to lab IDs. Lab IDs are the environment identifiers SeaLights uses to group test results by testing environment or tester.

```bash
npm run manage-user-mapping
```

## Menu Options

```
Select action:
   0. Fix pending mappings (users with TODO-lab-id)
   1. Edit existing mapping
   2. Add new mapping manually
   3. View all mappings
   4. Refresh user names from reports
   5. Discover users from qTest
   6. Exit
```

## Discovering Users

Users are added to `userLabMapping` in two ways:

1. **Automatically during report generation** — Any user ID found in qTest executions that is not already in `userLabMapping` is added with the placeholder value `TODO-lab-id`.
2. **Manually via the mapping tool** — Use option `5. Discover users from qTest` to scan recent executions for unknown users without running a full report.

After discovery, users with `TODO-lab-id` appear under option `0. Fix pending mappings`.

## Assigning Lab IDs

```
Select action: 0

⚠️  Users pending lab assignment:
   0. John Smith (ID: 226846)  →  TODO-lab-id
   1. Jane Doe (ID: 123456)    →  TODO-lab-id

Select user to assign: 0
Enter lab ID for John Smith: lab-east
✅ Updated: John Smith → lab-east
```

Repeat for each user until all `TODO-lab-id` entries are resolved.

## Lab ID Guidelines

* Use your internal environment naming convention (e.g. `lab-east`, `lab-west`, `qa-1`, `staging`)
* Assign the same lab ID to all testers who work in the same environment
* Be consistent across your organization — the same lab ID string must be used in both qTest integration config and the SeaLights configuration for the application under test

## Ignoring Users

Set a user's lab ID to `IGNORE` to permanently exclude their test executions from all reports:

```json
{
  "userLabMapping": {
    "999999": "IGNORE"
  }
}
```

Use `IGNORE` for automation bot accounts, qTest system users, or testers you intentionally exclude from SeaLights tracking.

## Example Session

```
╔═══════════════════════════════════════════════════════════════╗
║           User Lab Mapping Manager (v3.19.0)                  ║
╚═══════════════════════════════════════════════════════════════╝

✅ Found 5 user names
✅ Loaded discovery cache: 15 users from "MyProject"

📋 Found 12 new user(s) not yet in config.json
Add them now? (y/n): y
✅ Added 12 user(s) with TODO-lab-id

📊 Current Status:
   Total users in mapping: 15
   ✅ Mapped to labs: 3
   ⚠️  Pending (TODO-lab-id): 12
```

## When to Run

* **After the first report** — New users are discovered automatically; run this to assign their lab IDs
* **When new testers join** — Discover and map them before the next report cycle
* **After team reorganization** — Update lab assignments if testers move to different environments


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/qtest-integration/commands/manage-user-mapping.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.