View source for QPR Task Recorder for Web Apps

QPR TaskRecorder is a Chrome/Edge browser extension for '''task mining'''. It records user interactions on web applications — clicks, form inputs, navigation, and more — and exports them as a CSV file compatible with '''QPR ProcessAnalyzer'''.

== Installation ==

=== Chrome (using Developer Mode) ===
# Extract the <code>.zip</code> to a folder (e.g., <code>C:\Extensions\qpr-taskrecorder</code>)
# Open <code>chrome://extensions/</code>
# Enable '''Developer mode''' (toggle in the top-right corner)
# Click '''Load unpacked''' and select the extracted folder
# Click the '''puzzle piece icon''' (Extensions) in the toolbar, find QPR TaskRecorder, and click the '''pin icon''' to pin it to the toolbar

=== Edge (using Developer Mode) ===
# Extract the <code>.zip</code> to a folder
# Open <code>edge://extensions/</code>
# Enable '''Developer mode''' (toggle in the left sidebar)
# Click '''Load unpacked''' and select the extracted folder
# Click the '''puzzle piece icon''' (Extensions) in the toolbar, find QPR TaskRecorder, and click the '''eye icon''' to show it in the toolbar

=== Enterprise Deployment ===
For organization-wide deployment via Group Policy or Intune, use the <code>ExtensionInstallForcelist</code> policy to install from a <code>.crx</code> file hosted on an internal server. See the [[#Enterprise Policy|Enterprise Policy]] section for configuring default settings via managed policy.

== Quick Start ==
# Click the TaskRecorder icon in the toolbar and '''enable''' recording
# Open '''Settings''' and add at least one '''target URL pattern''' (e.g., <code>*://app.example.com/*</code>)
# Navigate to the target web application and interact normally
# Click the TaskRecorder icon → '''Preview Events''' to verify recording
# Click '''Export CSV''' to download the captured events

== Configuration ==
Open Settings via the toolbar icon → '''Settings''' button, or right-click the extension icon → '''Options'''.

=== Target URL Patterns ===
Define which websites are monitored. One pattern per line. Use <code>*</code> as a wildcard.

{| class="wikitable"
|-
! Pattern !! Matches
|-
| <code>*://app.example.com/*</code> || Any page on app.example.com (HTTP and HTTPS)
|-
| <code>https://portal.example.com/orders/*</code> || Only the /orders/ section over HTTPS
|-
| <code>*://*.example.com/*</code> || All subdomains of example.com
|}

Only pages matching at least one pattern will be recorded. If no patterns are configured, nothing is recorded.

=== Case ID Strategies ===
The Case ID groups related events into a single process instance. Choose the strategy that best fits your scenario:

{| class="wikitable"
|-
! Strategy !! When to Use !! How It Works
|-
| '''Per tab''' || General-purpose; each tab is one case || Each browser tab gets a unique Case ID. New tab = new case.
|-
| '''Page element''' || The page displays a case identifier (e.g., order number) || Reads the Case ID from a DOM element matching CSS selectors you provide. Multiple selectors supported in priority order.
|-
| '''Time-based''' || Users work on multiple cases in the same tab || A new Case ID is generated after an idle period (configurable, default 5 minutes).
|-
| '''Recording session''' || You want explicit control over case boundaries || Click '''Start Session''' / '''Stop Session''' in the popup. Events are only captured during active sessions.
|}

Tip: If none of these strategies perfectly match your data, you can remap Case IDs after import using QPR ProcessAnalyzer's ETL scripts or expressions.

=== Finding a CSS Selector for Page Element Strategy ===
# Right-click the ID value on the page → '''Inspect'''
# In DevTools '''Elements''' tab, look at the highlighted element's attributes
# Right-click the element → '''Copy''' → '''Copy selector''' (or build one manually)
# Test in the '''Console''' tab: <code>document.querySelector('YOUR_SELECTOR').textContent</code>
# Paste the working selector into the extension's CSS Selector field

'''Example selectors:'''

{| class="wikitable"
|-
! Page Element !! CSS Selector
|-
| <code><span id="order-number"></code> || <code>#order-number</code>
|-
| <code><span class="selectable"></code> inside <code><span class="title-id"></code> || <code>.title-id .selectable</code>
|-
| <code><input name="caseId"></code> || <code>[name="caseId"]</code>
|-
| <code><div data-testid="ticket-id"></code> || <code>[data-testid="ticket-id"]</code>
|}

Prefer <code>#id</code> selectors when available — they are short and stable. Avoid long auto-generated paths with <code>:nth-child()</code> as they break when the page layout changes.

=== Multiple Selectors (Priority Order) ===
You can configure multiple CSS selectors for the page-element strategy, one per line. The extension tries each selector in order and uses the first one that returns a non-empty value. This is useful when:

* Different pages show the Case ID in different locations
* You have a primary selector that works most of the time, with fallbacks for edge cases

Example configuration:
<pre>
#order-number
.title-id .selectable
[data-case-id]
</pre>

=== Case ID Autodetector ===
The Autodetector helps you find the correct CSS selector without using DevTools manually.

# Open Settings → Case ID strategy → "Extract from page element" → click '''Open Case ID Autodetector'''
# Enter one or more example Case IDs you know appear on your pages
# Choose a detection mode:
#* '''Point & Click''' — Navigate to a page, then click the element containing the Case ID. The extension generates a selector from your click.
#* '''Auto-Scan''' — Browse your application normally. The extension scans every page for elements matching your examples and records selectors automatically.
# Found selectors appear in real-time in the Autodetector panel
# Click '''Stop''' when done
# Select which selectors to add to your configuration, and which new URL patterns to add
# Click '''Apply Selected''' — the configuration is updated automatically

=== Case ID Gap Fill ===
When the page-element strategy cannot find the Case ID (e.g., during modal dialogs, loading screens, or SPA transitions), the event receives a <code>_noid-</code> prefixed fallback ID instead of being left empty. This ensures CSV imports always succeed.

The '''Fill Case ID gaps on export''' setting (enabled by default in Settings) automatically resolves these fallback IDs during CSV export:

* If an event has a <code>_noid-</code> fallback (or empty Case ID), and the nearest preceding and following events (within the same tab) share the same real Case ID, the event is assigned that Case ID.
* This only fills "gaps" — it does not assign Case IDs to events at the start/end of a tab session, nor to events between different Case IDs.
* Disable this setting if you prefer to handle <code>_noid-</code> events in your own ETL pipeline.

To preview gap-filled data before exporting: open the full-page Event Preview ("View All") and toggle '''Fill Case ID gaps'''. Filled rows are highlighted in yellow. The preview toggle is independent of the export setting.

=== User ID ===
A random anonymous ID is auto-generated on first install. You can override it with a custom identifier (e.g., employee ID or username) in Settings. This value appears in the <code>UserId</code> column of the CSV.

=== Field Value Exclusions ===
By default, values of form fields (text inputs, dropdowns, etc.) are captured. To protect sensitive data, configure exclusion rules:

'''Glob patterns''' — match field identifiers (id, name, aria-label). One per line.
<pre>
*password*
*ssn*
*credit*card*
*secret*
</pre>

'''CSS selector exclusions''' — match elements directly. One per line.
<pre>
input[type=password]
.sensitive-data
[data-private]
</pre>

Excluded fields still generate events (so you know the user interacted with them), but the value is omitted.

=== Icon Flash ===
When enabled (default), the toolbar icon briefly flashes amber each time an event is captured, providing visual confirmation that recording is active. Disable this in Settings if you find it distracting.

=== Configuration Import / Export ===
Settings can be saved to a JSON file and imported on other machines — useful for distributing a standard configuration to a team.

# '''Export''': Settings → '''Export Config JSON''' → saves a <code>.json</code> file
# '''Import''': Settings → '''Import Config JSON''' → select a previously exported <code>.json</code> file

== Enterprise Policy ==
Administrators can push default settings via Chrome/Edge managed storage policy. Policy values take priority over locally saved settings.

=== Policy Properties ===
{| class="wikitable"
|-
! Property !! Type !! Default !! Description
|-
| <code>enabled</code> || boolean || <code>true</code> || Whether event recording is enabled
|-
| <code>targetUrls</code> || string[] || <code>[]</code> || URL patterns to monitor
|-
| <code>userId</code> || string || ''(auto-generated)'' || User identifier for CSV output
|-
| <code>flashOnEvent</code> || boolean || <code>true</code> || Flash icon on event capture
|-
| <code>fieldExclusions</code> || string[] || <code>[]</code> || Glob patterns for field value exclusion
|-
| <code>fieldExclusionSelectors</code> || string[] || <code>[]</code> || CSS selectors for field value exclusion
|-
| <code>caseId.strategy</code> || string || <code>"per-tab"</code> || One of: <code>per-tab</code>, <code>page-element</code>, <code>time-based</code>, <code>recording-session</code>
|-
| <code>caseId.pageElementSelector</code> || string || <code>""</code> || CSS selector for page-element strategy
|-
| <code>caseId.idleTimeoutMinutes</code> || integer || <code>5</code> || Idle timeout for time-based strategy (1–120)
|}

=== Example: Windows Registry ===
For Chrome, create keys under: HKLM\SOFTWARE\Policies\Google\Chrome\3rdparty\extensions\<extension-id>\policy

For Edge: HKLM\SOFTWARE\Policies\Microsoft\Edge\3rdparty\extensions\<extension-id>\policy

=== Example: JSON Policy File (Chrome) ===
<syntaxhighlight lang="json">
{
  "enabled": true,
  "targetUrls": ["*://erp.company.com/*", "*://crm.company.com/*"],
  "userId": "${windows_username}",
  "caseId": {
    "strategy": "page-element",
    "pageElementSelector": "#case-number"
  },
  "fieldExclusions": ["*password*", "*ssn*"],
  "fieldExclusionSelectors": ["input[type=password]"]
}
</syntaxhighlight>

== Using the Extension ==

=== Toolbar Popup ===
Click the TaskRecorder icon to open the popup:

* '''Enable/Disable toggle''' — turns recording on or off globally
* '''Status''' — shows whether recording is active, the event count, User ID, and Case ID strategy
* '''Start/Stop Session''' — visible only when using the "Recording session" strategy
* '''Export CSV''' — downloads all captured events as a CSV file (events are cleared after export)
* '''Preview Events''' — shows the 50 most recent events in a table without exporting
* '''Settings''' — opens the full settings page

=== Icon Colors ===
{| class="wikitable"
|-
! Color !! Meaning
|-
| '''Green''' || Actively recording on this tab (target URL matches, extension enabled)
|-
| '''Grey''' || Not recording (non-target URL, extension disabled, or session not active)
|-
| '''Amber flash''' || An event was just captured (brief flash, ~200ms)
|}

=== CSV Export ===
Clicking '''Export CSV''' triggers a file download (<code>qpr-taskrecorder-export.csv</code>). After a successful export, all stored events are cleared. The file is ready for import into QPR ProcessAnalyzer.

== CSV Output Format ==
The exported CSV uses:
* '''Encoding:''' UTF-8
* '''Separator:''' comma (<code>,</code>)
* '''Text qualifier:''' double quote (<code>"</code>)
* '''Line ending:''' CRLF
* '''First row:''' column headers

=== Columns ===
{| class="wikitable"
|-
! # !! Column !! Description
|-
| 1 || <code>CaseId</code> || Process instance identifier
|-
| 2 || <code>EventType</code> || Action type: <code>Click</code>, <code>TextInput</code>, <code>SelectChange</code>, <code>PageNavigation</code>, <code>FormSubmit</code>, <code>FileUpload</code>, <code>KeyboardShortcut</code>
|-
| 3 || <code>Timestamp</code> || UTC with millisecond precision (<code>yyyy-MM-ddTHH:mm:ss.fffZ</code>)
|-
| 4 || <code>PageUrl</code> || Full URL where the event occurred
|-
| 5 || <code>PageTitle</code> || Page title (<code><title></code>)
|-
| 6 || <code>ElementSelector</code> || CSS selector or identifier of the element
|-
| 7 || <code>ElementLabel</code> || Visible text or label of the element
|-
| 8 || <code>ElementType</code> || HTML tag and type (e.g., <code>BUTTON</code>, <code>INPUT[text]</code>, <code>SELECT</code>)
|-
| 9 || <code>ElementValue</code> || Captured value (empty for excluded fields)
|-
| 10 || <code>TabId</code> || Browser tab identifier
|-
| 11 || <code>UserId</code> || User identifier
|}

=== Example ===
<pre>
CaseId,EventType,Timestamp,PageUrl,PageTitle,ElementSelector,ElementLabel,ElementType,ElementValue,TabId,UserId
case-abc123,PageNavigation,2026-04-23T09:01:12.000Z,https://app.example.com/orders/new,New Order,,,,,,agent01
case-abc123,Click,2026-04-23T09:01:15.234Z,https://app.example.com/orders/new,New Order,#product-dropdown,Product,SELECT,,tab-1,agent01
case-abc123,SelectChange,2026-04-23T09:01:18.567Z,https://app.example.com/orders/new,New Order,#product-dropdown,Product,SELECT,Premium Plan,tab-1,agent01
case-abc123,TextInput,2026-04-23T09:01:25.890Z,https://app.example.com/orders/new,New Order,#quantity-field,Quantity,INPUT[number],5,tab-1,agent01
</pre>

=== Importing into QPR ProcessAnalyzer ===
# In ProcessAnalyzer, create a new datatable or use an existing one
# Import the CSV file — the auto-detection should pick up comma separator and UTF-8 encoding
# Map the columns: <code>CaseId</code> → Case ID, <code>EventType</code> → Event Type, <code>Timestamp</code> → Timestamp
# Additional columns are imported as event attributes for filtering and analysis

== Troubleshooting ==
{| class="wikitable"
|-
! Problem !! Cause !! Solution
|-
| Icon stays grey on target site || URL doesn't match any target pattern || Check Settings → Target URLs. Patterns must match the full URL.
|-
| No events captured || Extension is disabled || Click the popup and toggle '''Enable'''.
|-
| No events with recording-session strategy || No active session || Click '''Start Session''' in the popup before interacting.
|-
| SPA navigation not detected || Rare edge case with custom routing || The extension monitors History API and DOM mutations. If a specific SPA framework bypasses both, navigation events may be missed.
|-
| Events captured inside iframes || Expected behavior || The content script runs in all frames by default. Target URL patterns apply to the top-level page.
|-
| Export produces empty file || No events stored || Interact with the target application first. Check the event count in the popup.
|-
| Settings reset after update || Extension was reloaded in developer mode || Settings persist in <code>chrome.storage.local</code>. Reloading the extension preserves them. Reinstalling (remove + add) clears them.
|}

== Privacy ==
* All captured data is stored '''locally''' in the browser's IndexedDB. No data is sent to external servers.
* Events are cleared after each CSV export.
* Use '''field exclusion rules''' to prevent capture of sensitive values (passwords, personal identifiers, etc.).
* The <code>UserId</code> is an anonymous auto-generated ID by default. It can be overridden in Settings.
* The extension only captures interactions on pages matching configured '''target URL patterns'''.