docs: document map endpoint behavior — JSON only, one finding per call, UUID resolution flow

docs/ivanti-api-reference.md

@@ -74,6 +74,68 @@ Key details:
 
 Returns HTTP 200 or 202 (Accepted — async job creation). Response contains a numeric `id` (the workflow batch job ID) and `created` timestamp. No `generatedId` or `uuid` in this response.
 
+### Map Findings to Existing Workflow (tested 2026-04-13)
+
+```
+POST /client/{clientId}/workflowBatch/falsePositive/{workflowBatchUuid}/map
+Content-Type: application/json
+```
+
+Maps additional host findings to an existing FP workflow batch. Used by the FP submission editing feature to add findings after initial creation.
+
+**Critical: one finding per call.** The map endpoint only reliably maps one finding per request. Sending multiple finding IDs via the `IN` operator or comma-separated values results in only the first finding being mapped. The multipart/form-data format (used by the create endpoint) returns 500 on this endpoint.
+
+#### Request body
+
+```json
+{
+  "subject": "hostFinding",
+  "filterRequest": {
+    "filters": [
+      {
+        "field": "id",
+        "exclusive": false,
+        "operator": "EXACT",
+        "value": "2283734550"
+      }
+    ]
+  }
+}
+```
+
+Key details:
+- Must be `application/json` (NOT multipart/form-data — returns 500)
+- Use `EXACT` operator with a single finding ID per call
+- `IN` operator with comma-separated IDs only maps the first finding
+- Loop through findings and make one API call per finding
+- The `workflowBatchUuid` in the URL is the UUID from the search endpoint (not the numeric batch ID from create)
+
+#### Response (200)
+
+Returns the updated workflow batch object on success.
+
+#### UUID resolution
+
+The `workflowBatchUuid` required in the URL is NOT returned by the create endpoint. To obtain it:
+
+1. Search via `POST /client/{clientId}/workflowBatch/search` with `{ field: 'name', operator: 'EXACT', value: '<workflow_name>' }`
+2. Use `projection: 'internal'` to get full batch objects
+3. The UUID is in the `uuid` field of the returned batch object
+4. Cache the UUID locally after first resolution (stored in `ivanti_fp_submissions.ivanti_workflow_batch_uuid`)
+
+#### Implementation in dashboard
+
+The `resolveWorkflowBatchUuid()` helper in `backend/routes/ivantiFpWorkflow.js` handles UUID resolution:
+- Returns cached UUID if available in the local submission record
+- Otherwise searches Ivanti by workflow name, extracts `batch.uuid`, and caches it for future use
+
+The findings map loop in the `POST /submissions/:id/findings` endpoint:
+- Iterates through each finding ID individually
+- Makes one JSON POST per finding with `EXACT` operator
+- Tracks which findings succeeded vs failed
+- Only marks queue items as complete for successfully mapped findings
+- Returns both `addedFindings` and `failedFindings` arrays in the response
+
 ### Other Workflow Endpoints (from Swagger)
 
 These are available but not all are currently used by the dashboard: