Skip to content

FOUR-34335: Add Responder Tracking and Personalized Email Links for Actions by Email - #9169

Open
sanjacornelius wants to merge 31 commits into
story/FOUR-34301from
subtask/FOUR-34335
Open

sanjacornelius wants to merge 31 commits into
story/FOUR-34301from
subtask/FOUR-34335

Conversation

@sanjacornelius

@sanjacornelius sanjacornelius commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

This PR adds optional responder tracking for ABE, allowing the system to track which recipient clicked and completed an email action. When enabled, each recipient receives a personalized signed link and responder information is captured in request data. This work also introduces staggered email delivery to help reduce provider rate limiting and preserves responder tracking through Require Login scenarios.

Changes:

  • Added optional responder tracking controlled by the trackResponder setting.
  • Sends one personalized email per unique recipient when responder tracking is enabled.
  • Continues using a single shared email when responder tracking is disabled.
  • Adds signed responder information to action links:
    - abe_email
    -abe_user_id
    - abe_groups
    - abe_sig
  • Captures responder details in a nested abe_responder object within request data.
  • Added support for preserving signed ABE parameters through Require Login using abe_click_ticket.
  • Detects forwarded email scenarios where a different user authenticates and records:
    - email
    - authenticated_email
    - identity_mismatch
  • Action execution continues even when an identity mismatch is detected.
  • Added configurable email dispatch staggering via abe_email_stagger_seconds to reduce provider throttling and rate limiting.
  • Merges group memberships when recipients belong to overlapping groups or shared inboxes to prevent duplicate sends.
  • Added documentation:
    - docs/abe-responder-tracking.md

Dependencies:

How to Test

Responder Tracking Disabled

  1. Configure an ABE task with Track Responder Identity disabled.
  2. Send the email.
  3. Verify only one shared email is sent.
  4. Complete the action from the email link.
  5. Verify no abe_responder data is written to the request

Responder Tracking Enabled

  1. Configure an ABE task with Track Responder Identity enabled.
  2. Send the email to multiple recipients.
  3. Verify each unique recipient receives their own email.
  4. Verify action links contain signed responder parameters:
    • abe_email
    • abe_user_id
    • abe_groups
    • abe_sig
  5. Complete the action from an email link.
  6. Verify request data contains a populated abe_responder object.

Request Data Validation

  1. Complete an ABE action using a signed link.
  2. Verify responder information is stored under abe_responder.
  3. Verify responder data is not written to top-level fields such as:
    • user_id
    • acted_at

Group Deduplication

  1. Create a user that belongs to multiple groups receiving the same email.
  2. Trigger the ABE task.
  3. Verify only one email is sent to that user.
  4. Verify group information is merged correctly within the signed payload.

Large Recipient Groups

  1. Configure an ABE task targeting a large user group.
  2. Trigger email delivery.
  3. Verify emails are queued with staggered delays.
  4. Monitor email provider activity and verify no unexpected throttling or rate-limit failures occur.

Require Login / Forwarded Email Scenario

  1. Enable Require Login.
  2. Send an ABE email to User A.
  3. Forward the email to User B.
  4. Open the email in a private/incognito session.
  5. Authenticate as User B.
  6. Complete the action.
  7. Verify:
    • email contains User A's email.
    • authenticated_email contains User B's email.
    • identity_mismatch is set to true
  8. Verify the action completes successfully.

Related Tickets & Packages

ci:connector-send-email:subtask/FOUR-34335
ci:package-actions-by-email:subtask/FOUR-34335
ci:deploy

Code Review Checklist

  • I have pulled this code locally and tested it on my instance, along with any associated packages.
  • This code adheres to ProcessMaker Coding Guidelines.
  • This code includes a unit test or an E2E test that tests its functionality, or is covered by an existing test.
  • This solution fixes the bug reported in the original ticket.
  • This solution does not alter the expected output of a component in a way that would break existing Processes.
  • This solution does not implement any breaking changes that would invalidate documentation or cause existing Processes to fail.
  • This solution has been tested with enterprise packages that rely on its functionality and does not introduce bugs in those packages.
  • This code does not duplicate functionality that already exists in the framework or in ProcessMaker.
  • This ticket conforms to the PRD associated with this part of ProcessMaker.

@cursor

cursor Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

PR Summary

Medium Risk
Changes ABE send/click completion, request data shape when tracking is on, and Require Login cookie/cache behavior; large groups multiply email jobs though legacy path is unchanged when tracking is off.

Overview
Adds optional Track responder identity for Actions by Email (trackResponder in configEmail). When enabled, assignees get one email each with HMAC-signed action links (abe_email, abe_user_id, abe_groups, abe_sig); when disabled, behavior stays the single shared comma-joined send.

On click with tracking on, request data gains a nested abe_responder object (signed recipient, groups, IP/UA heuristics, logged-in user, identity_mismatch for forwards) instead of leaking those fields at the top level. TokenRepository resolves and dedupes self-service recipients (overlapping groups, shared inboxes) and staggers queue dispatches via abe_email_stagger_seconds. TaskActionByEmail renders the screen once per batch and rewrites only /tasks/update_variable/ links per recipient.

Require Login now parks the full click query in cache behind an unencrypted abe_click_ticket cookie so signed params survive login; failed restores return 422 validation errors instead of 500s. Includes docs/abe-responder-tracking.md and broad unit/feature coverage.

Reviewed by Cursor Bugbot for commit 0f1bfca. Bugbot is set up for automated code reviews on this repo. Configure here.

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous run.

Comment thread ProcessMaker/Mail/TaskActionByEmail.php Resolved
@nolanpro

Copy link
Copy Markdown
Contributor

QA server K8S was successfully deployed https://tenant-1.ci-654cabc8d7.engk8s.processmaker.net

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 0f1bfca. Configure here.

return [];
}

$decoded = json_decode(base64_decode($encoded, true) ?: '', true);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Base64 query params break signatures

Medium Severity

abe_groups is standard Base64 placed in a query string and bound into the HMAC. Base64 + is a space in query parsing, and many email clients decode %2B back to + before the click. Strict base64_decode then fails, verification returns null, and email, user_id, and groups are all dropped even though the action still completes.

Additional Locations (1)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 0f1bfca. Configure here.


$pending = Cache::pull(self::ABE_CLICK_CACHE_PREFIX . $ticket);
if (!is_array($pending) || ($pending['abe_uuid'] ?? null) !== $abe->uuid) {
return null;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Click ticket consumed on mismatch

Low Severity

Cache::pull deletes the parked ABE click before the cached abe_uuid is checked. A request that has the ticket cookie but hits a different token still burns the one-shot entry, so the later Require Login return cannot restore varName, varValue, or the signed recipient params and fails validation.

Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 0f1bfca. Configure here.

@sanjacornelius
sanjacornelius changed the base branch from develop to story/FOUR-34301 November 18, 2026 22:07
@decisions-sonarqube

Copy link
Copy Markdown

Quality Gate failed Quality Gate failed

Failed conditions
3 New issues
3 New Maintainability Issues (required ≤ 0)

See analysis details on SonarQube

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE SonarQube for IDE

@nolanpro

Copy link
Copy Markdown
Contributor

QA server K8S was successfully deployed https://tenant-1.ci-654cabc8d7.engk8s.processmaker.net

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants