UVE: Investigate `fireRule` query param in Page API

[fmontes]

Task description

As a dotCMS developer, I need to research how the ⁠fireRule query param works in the Page API because it is not functioning as expected. This will help me determine if there is a bug in the system or if there is a misunderstanding on how to use this parameter effectively.

The ⁠fireRule query params enable dotCMS implementers to render personalized pages in their headless web apps, providing a customized user experience based on page rules.

https://github.com/user-attachments/assets/9dedbfa2-3f93-4f3f-b0b3-4062ad6a7595

Acceptance Criteria

• Investigate the documentation related to the fireRule query param in the Page API.
• Test the usage of the fireRule query param in various scenarios to understand its behavior.
• Compare the expected outcome with the actual outcome when using the fireRule query param.
• Provide a detailed report outlining the findings and recommendations for any necessary actions.

External Links

• dotCMS Documentation on Page API: link

Assumptions & Initiation Needs

• Assume that the issue with the fireRule query param is not related to any recent code changes or updates.
• Ensure access to the dotCMS instance to perform tests and investigations.
• Collaborate with the team to gather insights and feedback on the usage of the fireRule query param.

Quality Assurance Notes & Workarounds

N/A

[valentinogiardino]

Research work

After thoroughly reviewing the documentation, debugging the code, and testing various scenarios, I have concluded that the fireRule query parameter is functioning as expected, despite some documentation discrepancies and potential misunderstandings on my part. I have documented my findings in detail in this document.

Regarding the Behavior in the Ticket Video

The issue shown in the ticket video occurs because the user is running dotCMS on a local instance without a public IP address. In this setup, the method to retrieve the user's location or country based on their IP address fails, preventing the rule condition from being met, which stops the associated action from firing.

As outlined in the investigation report, It's also important to note that the Persona assignment action sets the persona in the visitor's session. This explains why, if we call the Page API twice in succession—once with fireRules=true and once without—it returns the same persona in both cases, reflecting the last persona that was set.

Video

https://github.com/user-attachments/assets/df587b90-fe2f-4c9b-8a01-9cc1ecfd3ce6