External Portal Coordination
Feature Detail
Description
This feature manages the relationship and boundary delineation between the Likeperson app and HLF's separately maintained Dynamics-based member portal ('Min Side'). It provides configuration tooling to define which features belong to each platform, prevents functional overlap that would confuse users or create double-entry situations, and implements webhook-based coordination to keep shared state consistent. The feature ensures that the two systems are complementary rather than competing, with clear handoff points and no duplication of critical workflows.
Analysis
HLF is actively redesigning its Dynamics-based member portal in parallel with this app, creating a real risk of feature overlap, user confusion, and wasted development effort if the two systems are not explicitly coordinated. Without clear delineation, volunteers and coordinators may encounter conflicting data, duplicate forms, or uncertainty about which system is authoritative for a given task. Establishing formal coordination at the platform level protects HLF's investment in both systems, enables a coherent user journey that spans app and portal, and prevents the app from inadvertently replicating portal features that would then need to be maintained in two places. This also future-proofs the integration as the HLF portal evolves.
The portal integration config screen allows HLF admins to toggle which app features are active versus deferred to the portal, effectively acting as a feature flag layer per organization. The portal sync service subscribes to webhooks from the Dynamics portal for events such as membership updates and course enrollments, updating local state accordingly. The portal webhook infrastructure receives inbound Dynamics webhook payloads via a Supabase Edge Function endpoint, validates signatures, and enqueues processing. Deep links between the app and the portal (e.g., 'view full profile in portal') are configured via the integration config repository. Overlap prevention is enforced at the UI level: features flagged as 'portal-owned' are hidden or replaced with deep links rather than disabled with error messages, providing a seamless handoff experience.
Dependencies
Definition of Done
Components (4)
User Stories (10)
As a As an administrator
I want I want to view the current sync status between the app and the Dynamics portal, including recent sync events and their outcomes
So that So that I can confirm that shared state (membership updates, course enrollments) is flowing correctly between systems and quickly identify if synchronization has failed or fallen behind
- Given an administrator views the portal integration config screen, when the sync status panel loads, then it displays the timestamp of the last successfully processed webhook event
- Given the portal sync service has processed events, when an administrator views the sync log, then they see a chronological list of recent events with status (success/error/skipped) and event type
- Given a webhook event failed to process, when an administrator views that event in the sync log, then they see a human-readable error description and the raw event type
- +2 more
As a As an administrator
I want I want to view the current sync status between the app and the Dynamics portal, including recent sync events and their outcomes
So that So that I can confirm that shared state (membership updates, course enrollments) is flowing correctly between systems and quickly identify if synchronization has failed or fallen behind
- Given an administrator views the portal integration config screen, when the sync status panel loads, then it displays the timestamp of the last successfully processed webhook event
- Given the portal sync service has processed events, when an administrator views the sync log, then they see a chronological list of recent events with status (success/error/skipped) and event type
- Given a webhook event failed to process, when an administrator views that event in the sync log, then they see a human-readable error description and the raw event type
- +2 more
As a As a Global Administrator
I want I want to monitor the health of the portal webhook infrastructure, including endpoint availability, payload rejection rates, and processing queue depth
So that So that I can detect degraded integration health before it impacts users and take corrective action — such as reprocessing failed events or investigating signature mismatches — without requiring direct Supabase dashboard access
- Given a global admin opens the webhook health view, when it loads, then they see the active webhook endpoint URL, total payloads received in the last 24 hours, and rejection count with rejection reason breakdown
- Given webhook payloads are being rejected at a rate above 10% in a rolling hour, when a global admin views the health dashboard, then a high-rejection-rate alert is prominently displayed
- Given the webhook infrastructure is unreachable or the Edge Function has error-exited, when a global admin views the health dashboard, then an infrastructure outage alert is shown with the last-known healthy timestamp
- +2 more
As a As a Global Administrator
I want I want to configure the complete portal integration setup for a newly onboarded HLF organization, including feature ownership flags, deep links, and webhook routing
So that So that a new organization's Likeperson app instance is correctly coordinated with their Min Side portal from day one, without requiring manual database configuration or developer intervention
- Given a global admin is onboarding a new organization, when they open the portal integration setup for that organization, then all configuration fields start pre-populated from the platform default template
- Given a global admin customizes the feature ownership flags for the new organization, when they save the configuration, then those flags apply only to that organization and do not affect other organizations' configurations
- Given a global admin enters the organization's webhook source identifier, when a Dynamics webhook payload from that organization arrives, then the infrastructure correctly routes and scopes it to that organization's data context
- +2 more
As a As an administrator
I want I want to configure the deep link URLs that the app uses when directing users to specific sections of the Min Side Dynamics portal
So that So that handoff navigation from the app lands users directly on the relevant portal page rather than the portal homepage, reducing friction and ensuring users complete their tasks without confusion about where to go
- Given an administrator opens the portal integration config screen, when they navigate to the deep link configuration section, then they see a list of configurable link mappings with their current URL values
- Given an administrator enters a new deep link URL for a portal-owned feature, when they save the configuration, then the app immediately uses that URL for all future handoff navigation from that feature context
- Given a configured deep link is triggered in the app, when the user taps the handoff button, then the portal URL opens in the device browser with any required context parameters appended
- +2 more
As a As an administrator
I want I want to toggle which app features are designated as app-owned versus portal-owned for my organization
So that So that users experience a coherent, non-overlapping journey across the Likeperson app and HLF's Min Side portal without encountering duplicate forms or conflicting data entry points
- Given an administrator is on the portal integration config screen, when they toggle a feature flag from 'app-owned' to 'portal-owned', then that feature is immediately hidden from the app UI and replaced with a deep link to the configured portal URL
- Given a feature is flagged as 'portal-owned', when a user navigates to that section of the app, then they see a clear handoff card with a button linking to the Min Side portal — not a disabled button or error
- Given an org admin saves a feature ownership configuration, when another user in that organization opens the app, then the updated ownership flags are reflected within one sync cycle
- +2 more
As a As a Organization Administrator
I want I want membership changes made in the HLF Min Side Dynamics portal (such as new members, role changes, and deactivations) to be automatically reflected in the Likeperson app without manual re-entry
So that So that coordinators always work with current membership data and I do not need to duplicate administrative changes across two separate systems
- Given a new member is added in the Min Side portal, when the portal publishes the membership-created webhook event, then within two minutes the new member's profile is available in the Likeperson app under the correct organization
- Given a member's role is changed in the Min Side portal, when the role-updated webhook event is processed, then the member's access level in the Likeperson app reflects the updated role on their next app session
- Given a member is deactivated in the Min Side portal, when the membership-deactivated webhook event is processed, then the member can no longer access the Likeperson app and is marked inactive in coordinator views
- +2 more
As a As an administrator
I want I want to configure the deep link URLs that the app uses when directing users to specific sections of the Min Side Dynamics portal
So that So that handoff navigation from the app lands users directly on the relevant portal page rather than the portal homepage, reducing friction and ensuring users complete their tasks without confusion about where to go
- Given an administrator opens the portal integration config screen, when they navigate to the deep link configuration section, then they see a list of configurable link mappings with their current URL values
- Given an administrator enters a new deep link URL for a portal-owned feature, when they save the configuration, then the app immediately uses that URL for all future handoff navigation from that feature context
- Given a configured deep link is triggered in the app, when the user taps the handoff button, then the portal URL opens in the device browser with any required context parameters appended
- +2 more
As a As an administrator
I want I want to toggle which app features are designated as app-owned versus portal-owned for my organization
So that So that users experience a coherent, non-overlapping journey across the Likeperson app and HLF's Min Side portal without encountering duplicate forms or conflicting data entry points
- Given an administrator is on the portal integration config screen, when they toggle a feature flag from 'app-owned' to 'portal-owned', then that feature is immediately hidden from the app UI and replaced with a deep link to the configured portal URL
- Given a feature is flagged as 'portal-owned', when a user navigates to that section of the app, then they see a clear handoff card with a button linking to the Min Side portal — not a disabled button or error
- Given an org admin saves a feature ownership configuration, when another user in that organization opens the app, then the updated ownership flags are reflected within one sync cycle
- +2 more
As a As a Global Administrator
I want I want to configure the HMAC signature secret used to authenticate inbound webhook payloads from the HLF Dynamics portal
So that So that the webhook infrastructure only processes payloads that originate from the legitimate HLF portal, preventing unauthorized actors from injecting false sync events into the platform
- Given a global admin navigates to the webhook configuration section, when they enter a new HMAC secret and save, then the Edge Function immediately uses the new secret for all subsequent payload verification
- Given the HMAC secret is configured, when a global admin triggers the validation test, then the system sends a sample signed payload to the webhook endpoint and reports whether verification succeeded or failed
- Given the HMAC secret is not configured, when the webhook endpoint receives an inbound payload, then it rejects the payload with a 401 response and logs the rejection
- +2 more