docs: Document Contact and Owner field tokens in Email link URLs - #852
docs: Document Contact and Owner field tokens in Email link URLs#852promptless-for-oss wants to merge 2 commits into
Conversation
Owner field tokens (and Contact field tokens) now resolve inside link URLs at click/redirect time, not just in Email body text. Document the syntax, the tracked-link requirement, and the empty-value behavior when a Contact has no Owner. Ref: mautic/mautic#15924
|
|
||
| Mautic redirects a Contact whose Owner's first name is 'Alex' to ``https://blog.example.com/author/Alex/``. | ||
|
|
||
| Owner field tokens resolve to the field value of the Contact's assigned Owner, who is a Mautic User. The available Owner field tokens are ``{ownerfield=firstname}``, ``{ownerfield=lastname}``, ``{ownerfield=email}``, ``{ownerfield=position}``, and ``{ownerfield=signature}``. See :doc:`/configuration/variables` for the full list of tokens. |
There was a problem hiding this comment.
Documented the five available Owner field tokens (firstname, lastname, email, position, signature) from the OWNER_COLUMNS allowlist in OwnerSubscriber.php, and that they resolve against the Contact's assigned Owner (a Mautic User) — the token pattern is built from '{ownerfield=%s}'.
Source: https://github.com/mautic/mautic/blob/7.x/app/bundles/LeadBundle/EventListener/OwnerSubscriber.php
|
|
||
| .. note:: | ||
|
|
||
| Mautic resolves link URL tokens when the Contact clicks the link, so this only applies to tracked links. If you turn off tracking for a link, Mautic doesn't resolve the tokens in its URL. |
There was a problem hiding this comment.
Stated that link URL tokens resolve at click time and only on tracked links: PR #15924 makes owner-token URLs trackable via TrackableModel::isContactFieldToken() and does the substitution in OwnerSubscriber::onUrlTokenReplace(), which fires from the redirect controller (PublicController::redirectAction()) only when a valid clickthrough (ct) is present.
Source: mautic/mautic#15924
There was a problem hiding this comment.
(Line 386)
Documented the empty-value behavior (missing Owner or empty field yields an empty string, producing a malformed URL like author//) from OwnerSubscriber::getOwnerTokens() returning getEmptyTokens() when owner_id is empty, confirmed by the functional test asserting {ownerfield=firstname} becomes // when no Owner is assigned.
| .. note:: | ||
|
|
||
| Mautic resolves link URL tokens when the Contact clicks the link, so this only applies to tracked links. If you turn off tracking for a link, Mautic doesn't resolve the tokens in its URL. | ||
|
|
||
| .. note:: | ||
|
|
||
| If the Contact has no Owner, or the Owner field is empty, Mautic replaces the token with an empty string. This can produce a malformed URL, such as ``https://blog.example.com/author//``. Account for missing Owner values when you build link URLs with Owner field tokens. |
There was a problem hiding this comment.
We can avoid the same back to back admonitions. It can be overwhelming. Use unordered list instead in one admonition.
| .. note:: | |
| Mautic resolves link URL tokens when the Contact clicks the link, so this only applies to tracked links. If you turn off tracking for a link, Mautic doesn't resolve the tokens in its URL. | |
| .. note:: | |
| If the Contact has no Owner, or the Owner field is empty, Mautic replaces the token with an empty string. This can produce a malformed URL, such as ``https://blog.example.com/author//``. Account for missing Owner values when you build link URLs with Owner field tokens. | |
| .. note:: | |
| * Mautic resolves link URL tokens when the Contact clicks the link, so this only applies to tracked links. If you turn off tracking for a link, Mautic doesn't resolve the tokens in its URL. | |
| * If the Contact has no Owner, or the Owner field is empty, Mautic replaces the token with an empty string. This can produce a malformed URL, such as ``https://blog.example.com/author//``. Account for missing Owner values when you build link URLs with Owner field tokens. |
Address review comment on PR mautic#852: merge two back-to-back note admonitions into one note with an unordered list to reduce overwhelming stacked callouts. Ref: mautic/mautic#15924
|
Thanks @adiati98 — done. We combined the two back-to-back notes about tokens in link URLs into a single |
2 participants
Open this suggestion in Promptless to view citations and reasoning process
Documents that Contact field and Owner field tokens now resolve inside Email link URLs at click/redirect time (not just in body text), per mautic/mautic#15924. Adds a 'Tokens in link URLs' subsection to the Email Tokens docs covering the syntax, the tracked-link requirement, and the empty-value behavior when a Contact has no Owner.
Trigger Events
Tip: Tag @Promptless in GitHub PR comments to guide documentation changes during code review 🐙