# UAT Test Finding — Form Spec & Build Guide

**Project:** ESUP (Jira Service Management)
**Request type name:** UAT Test Finding
**Issue type:** Service Request
**Portal group:** UAT
**Prepared:** 2026-06-08

> **Purpose:** This document serves two roles:
> 1. Build guide for the UAT Test Finding form in JSM (current system).
> 2. Migration reference — field definitions, keys, and automation patterns for transfer to a future work item tracking or support system replacement.

---

## Form Spec

### Section 1 — What Happened

| Field | Field Key | Type | Required | Notes |
|---|---|---|---|---|
| **Finding type** | `finding-type` | Radio | Yes | **First field.** See choices below. Drives the rest of the form (defect vs. comment). |
| **Test Plan Section** | `test-plan-section` | Dropdown | Yes | See choices below. Always shown. |
| **Test Step Reference** | `test-step-reference` | Short text | Yes | Always shown. Hint: "Enter the section and step number from the test plan (e.g. 4.5 – Step 3)" |
| **Impact on testing** | `impact-on-testing` | Radio | Conditional | **Show only when Finding type = Defect.** See choices below. |
| **What you expected to happen** | `expected-result` | Paragraph | Conditional | Show only when Finding type = Defect AND Impact = Blocks or Workaround needed |
| **What did you observe?** | `actual-result` | Paragraph | Conditional | **Show only when Finding type = Defect.** Hint: "Describe exactly what you saw. Copy any error messages word for word." |
| **Your comment or idea** | `comment-idea` | Paragraph | Conditional | **Show only when Finding type = Comment / idea.** Hint: "What do you not like, or what is your idea? The feature works — this is feedback for making it better." |

**Finding type — radio choices:**

```
Defect — something is wrong (a step failed or partly failed)
Comment / idea — it works, but I have feedback or a suggestion
```

> **Mapping to test-plan result values:** the web test plan's **FAIL** and **FAIL - PARTIAL** results correspond to **Defect** here; the **PASS - Added Comment** result corresponds to **Comment / idea**. A clean **PASS** generates no finding.

**Test Plan Section — dropdown choices:**

```
1 – Onboarding
2 – Navigation
3 – Ammo
4 – DOPE Screen
5 – Conditions
6 – Results
7 – Print
8 – Settings
9 – Advanced Settings
10 – Keyboard
11 – Contrast
12 – Edge Cases
```

**Impact on testing — radio choices** (Defect only):

```
Blocks — I cannot continue this section
Workaround needed — I found a way to continue
Observation only — testing continued normally
```

---

### Section 2 — Reproduction Context

> **Conditional:** Show this entire section only when **Finding type = Defect** AND Impact = "Blocks — I cannot continue this section" OR "Workaround needed — I found a way to continue". Hide for Comment / idea findings, and when Impact = "Observation only — testing continued normally". (A comment/idea has nothing to reproduce.)

| Field | Field Key | Type | Required | Notes |
|---|---|---|---|---|
| **App version** | `app-version` | Short text | Yes | Default value: `0.9.6-beta4` |
| **Device** | `device` | Short text | Yes | Default value: `Samsung Galaxy A16 5G` |
| **How often does this happen?** | `frequency` | Radio | Yes | See choices below |
| **Steps to reproduce (if different from the test plan step)** | `repro-steps` | Paragraph | No | Hint: "Leave blank if following the test plan step exactly reproduces the issue." |

**How often does this happen? — radio choices:**

```
Every time
Sometimes - Mechanism Unknown
Sometimes - Mechanism Known
Once - Unreproducible
```

---

### Section 3 — Supporting Evidence

> **Always shown.**

| Field | Field Key | Type | Required | Notes |
|---|---|---|---|---|
| **Screenshot or screen recording** | `evidence` | File attachment | No | Hint: "A screenshot or short recording is very helpful but not required." |
| **Anything else?** | `notes` | Paragraph | No | Hint: "Any other observations that do not fit the fields above." |

---

### Work Item Field Mappings

| Form field | Field Key | Maps to work item field |
|---|---|---|
| What did you observe? | `actual-result` | Description (Defect findings) |
| Your comment or idea | `comment-idea` | Description (Comment / idea findings) |
| All others | — | Form-only (no custom field needed) |

> Map **both** `actual-result` and `comment-idea` to Description. Only one is populated per submission (they are mutually exclusive via the Finding type condition), so whichever the tester filled becomes the Description.

### Auto-Summary Pattern (Automation rule — see Step 10)

Lead the summary with the finding type so defects and comments are distinguishable at a glance. Two rules (or one rule with a conditional branch):

**Defect:**
```
UAT DEFECT [{{issue.forms.last.test-plan-section}}] {{issue.forms.last.test-step-reference}} — {{issue.forms.last.impact-on-testing}}
```
Example: `UAT DEFECT [4 – DOPE Screen] 4.5 – Step 3 — Blocks`

**Comment / idea:**
```
UAT COMMENT [{{issue.forms.last.test-plan-section}}] {{issue.forms.last.test-step-reference}}
```
Example: `UAT COMMENT [4 – DOPE Screen] 4.5 – Step 3`

> **Migration note:** The `{{issue.forms.last.*}}` tokens are JSM-specific. A replacement system must map these field keys to equivalent variables in its own automation syntax.

---

## Build Steps (JSM)

### Prerequisites

- **Project Administrator** role on ESUP. Confirm: Project settings → People → your account shows Project Administrator.
- **Forms feature enabled.** Confirm: Project settings → Features → Forms toggle is ON.

---

### Step 1 — Create the Request Type

1. In the ESUP project, go to **Project settings** (bottom of the left sidebar).
2. Click **Request types**.
3. Click **Create request type**.
4. Fill in:
   - **Name:** `UAT Test Finding`
   - **Issue type:** `Service Request`
   - **Icon:** choose any (bug icon recommended)
   - **Description:** `Report a test finding from UAT testing. Use for any result that is not a clean Pass.`
5. Click **Save**.

---

### Step 2 — Create the UAT Portal Group

1. On the Request types page, click **Groups** or **Portal groups** in the left navigation.
2. Click **Create group**.
3. **Name:** `UAT`
4. Save.
5. Find **UAT Test Finding** in the request type list and assign it to the **UAT** portal group.

---

### Step 3 — Open the Form Builder

1. Click **UAT Test Finding** to open its detail view.
2. Click the **Form** tab (alongside the Fields tab).
3. Click **Add form** → **Create new form**.
4. **Form name:** `UAT Test Finding`
5. Click **Create**. The form builder opens.

---

### Step 4 — Build Section 1

> **For every field below:** after adding the field, click it to open its settings panel and set the **Field key** to the value shown. Do this immediately — before adding the next field.

1. Click into the canvas. Add a **Heading**: `What Happened`

2. Add a **Radio buttons** field (this is the **first** field — it drives the rest):
   - Label: `What kind of finding is this?`
   - **Field key:** `finding-type`
   - Required: **Yes**
   - Choices (add exactly as written):
     ```
     Defect — something is wrong (a step failed or partly failed)
     Comment / idea — it works, but I have feedback or a suggestion
     ```

3. Add a **Dropdown** field:
   - Label: `Test Plan Section`
   - **Field key:** `test-plan-section`
   - Required: **Yes**
   - Choices (add one by one):
     ```
     1 – Onboarding
     2 – Navigation
     3 – Ammo
     4 – DOPE Screen
     5 – Conditions
     6 – Results
     7 – Print
     8 – Settings
     9 – Advanced Settings
     10 – Keyboard
     11 – Contrast
     12 – Edge Cases
     ```

4. Add a **Short text** field:
   - Label: `Test Step Reference`
   - **Field key:** `test-step-reference`
   - Placeholder: `Enter the section and step number from the test plan (e.g. 4.5 – Step 3)`
   - Required: **Yes**

5. Add a **Radio buttons** field:
   - Label: `Impact on testing`
   - **Field key:** `impact-on-testing`
   - Required: **No** (conditional — shown only for Defect; set in Step 7)
   - Choices (add exactly as written):
     ```
     Blocks — I cannot continue this section
     Workaround needed — I found a way to continue
     Observation only — testing continued normally
     ```

6. Add a **Paragraph text** field:
   - Label: `What you expected to happen`
   - **Field key:** `expected-result`
   - Placeholder: `Describe the expected result stated in the test plan step.`
   - Required: **No** (conditional visibility set in Step 7)

7. Add a **Paragraph text** field:
   - Label: `What did you observe?`
   - **Field key:** `actual-result`
   - Placeholder: `Describe exactly what you saw. Copy any error messages word for word.`
   - Required: **No** (conditional — shown only for Defect; set in Step 7)

8. Add a **Paragraph text** field:
   - Label: `Your comment or idea`
   - **Field key:** `comment-idea`
   - Placeholder: `What do you not like, or what is your idea? The feature works — this is feedback for making it better.`
   - Required: **No** (conditional — shown only for Comment / idea; set in Step 7)

---

### Step 5 — Build Section 2

> **Set the field key for every field immediately after adding it.**

1. Add a **Heading**: `Reproduction Context`

2. Add a **Short text** field:
   - Label: `App version`
   - **Field key:** `app-version`
   - Default value: `0.9.6-beta4`
   - Required: **Yes**

3. Add a **Short text** field:
   - Label: `Device`
   - **Field key:** `device`
   - Default value: `Samsung Galaxy A16 5G`
   - Required: **Yes**

4. Add a **Radio buttons** field:
   - Label: `How often does this happen?`
   - **Field key:** `frequency`
   - Required: **Yes**
   - Choices:
     ```
     Every time
     Sometimes - Mechanism Unknown
     Sometimes - Mechanism Known
     Once - Unreproducible
     ```

5. Add a **Paragraph text** field:
   - Label: `Steps to reproduce (if different from the test plan step)`
   - **Field key:** `repro-steps`
   - Placeholder: `Leave blank if following the test plan step exactly reproduces the issue.`
   - Required: **No**

---

### Step 6 — Build Section 3

> **Set the field key for every field immediately after adding it.**

1. Add a **Heading**: `Supporting Evidence`

2. Add a **File upload** field:
   - Label: `Screenshot or screen recording`
   - **Field key:** `evidence`
   - Placeholder: `A screenshot or short recording is very helpful but not required.`
   - Required: **No**

3. Add a **Paragraph text** field:
   - Label: `Anything else?`
   - **Field key:** `notes`
   - Placeholder: `Any other observations that do not fit the fields above.`
   - Required: **No**

---

### Step 7 — Add Conditional Logic

The form branches on **Finding type**. Defect findings show the full defect flow; Comment / idea findings show only the comment field. Add each condition via the field's (or section's) conditions/visibility option — usually a funnel icon or "Add condition" link.

**Driven by `Finding type` = `Defect`:**

1. **Impact on testing** field:
   - **Show when:** `Finding type` is `Defect — something is wrong (a step failed or partly failed)`

2. **What did you observe?** field:
   - **Show when:** `Finding type` is `Defect …`

3. **What you expected to happen** field:
   - **Show when:** `Finding type` is `Defect …` AND (`Impact on testing` is `Blocks …` OR `Workaround needed …`)
   - *(If the builder cannot nest AND/OR, approximate with: show when Impact is Blocks OR Workaround — Impact only exists for Defects anyway.)*

4. **Reproduction Context** (entire Section 2):
   - **Show when:** `Finding type` is `Defect …` AND (`Impact on testing` is `Blocks …` OR `Workaround needed …`)
   - *(Hide-when fallback:)* **Hide when** `Finding type` is `Comment / idea …`, and when `Impact on testing` is `Observation only …`

**Driven by `Finding type` = `Comment / idea`:**

5. **Your comment or idea** field:
   - **Show when:** `Finding type` is `Comment / idea — it works, but I have feedback or a suggestion`

6. Save all conditions.

> **Result:** A **Defect** submission shows section/step + impact + observe (+ expected + repro when blocking). A **Comment / idea** submission shows only section/step + the comment field. Supporting Evidence (Section 3) is always shown for both.

---

### Step 8 — Attach the Form to the Request Type

1. After saving the form, return to the **UAT Test Finding** request type → **Form** tab.
2. Confirm **UAT Test Finding** form is listed and status is **Active**.
3. If an **Attach to request type** toggle is present, ensure it is ON.

---

### Step 9 — Map the Description Field

1. Click the **Fields** tab on the UAT Test Finding request type.
2. Find **Description** in the work item fields list.
3. Map it to **both** form fields — `actual-result` ("What did you observe?") and `comment-idea` ("Your comment or idea"). Only one is populated per submission (they are mutually exclusive by Finding type), so the filled one becomes the Description.
   - *(If the builder allows only one field → Description: map `actual-result`, and add an automation action — see Step 10 — that copies `comment-idea` into Description when Finding type = Comment / idea.)*

---

### Step 10 — Create the Auto-Summary Automation Rule

Two summary patterns so defects and comments are distinguishable. Use **one rule with a conditional branch** (preferred) or two rules.

1. In ESUP, go to **Project settings → Automation**.
2. Click **Create rule**.
3. **Trigger:** Work item created.
4. **Condition:** Work item matches → JQL:
   ```
   project = ESUP AND "Request Type" = "UAT Test Finding"
   ```
5. **Branch A — Finding type = Defect.** Condition: `{{issue.forms.last.finding-type}}` contains `Defect`. Action: Edit work item → Summary →
   ```
   UAT DEFECT [{{issue.forms.last.test-plan-section}}] {{issue.forms.last.test-step-reference}} — {{issue.forms.last.impact-on-testing}}
   ```
6. **Branch B — Finding type = Comment / idea.** Condition: `{{issue.forms.last.finding-type}}` contains `Comment`. Action: Edit work item → Summary →
   ```
   UAT COMMENT [{{issue.forms.last.test-plan-section}}] {{issue.forms.last.test-step-reference}}
   ```
   *(Optional, if Description couldn't be dual-mapped in Step 9: in this branch also set Description = `{{issue.forms.last.comment-idea}}`.)*
7. **Rule name:** `UAT Finding — Auto-set Summary`
8. Enable and save.

---

### Step 11 — Test the Form

1. Navigate to your ESUP customer portal.
   - Find the URL at: Project settings → Portal settings.
2. Find the **UAT** group → **UAT Test Finding**.
3. **Test the Defect path:**
   - Select **Finding type = Defect**, a section, a step reference, **Impact = Blocks**.
   - Confirm Impact, "What did you observe?", "What you expected", and Section 2 (Reproduction Context) all appear; "Your comment or idea" does **not**.
   - Switch Impact to **Observation only** → Section 2 and "What you expected" disappear.
4. **Test the Comment path:**
   - Switch **Finding type = Comment / idea**.
   - Confirm Impact, observe, expected, and Reproduction Context all disappear, and only **"Your comment or idea"** (plus section/step and Supporting Evidence) remain.
5. Submit one of each. Confirm both work items are created.
6. Confirm the auto-summary fires with the right prefix:
   ```
   UAT DEFECT [4 – DOPE Screen] 4.5 – Step 3 — Blocks
   UAT COMMENT [4 – DOPE Screen] 4.5 – Step 3
   ```

---

*Prepared by: ScopeDOPE Development Team — 2026-06-08*
