Referral Link

[srenault-meeds]

Rationale

We'd like to help our community managers to easily grow their audience thanks to a Referral System.
Indeed, it is possible to use a single link to invite people, using the URL of the space.
However, space admins are not notified when a user joins the space using the URL (when open to join).

In addition, users need to know they can use the URL of the space to invite people.

❓Why now?

• This will ease the onboarding process for community managers (by adding the link in a global email, in a website)
• This will improve the traction of the product and the community at large
• This can also leverage engagement to their community

🎯 What is the goal?

• From members list, it is possible to use a link to share for invitation
• This link will be uniquely designed for each user
• Hence, each new user joining the community using a link will be rewarded thanks to gamification feature
• And space admins will be notified of users joining the space using an invitation link

1. Functional Requirements

Top User Stories

Suggest users to invite people using link

A new option will be suggested in the members management (and in the members list drawer).

Admins will access it from the current option:

Members will see the "Invite" button, only if the space is open or approval-request.
If this is closed (invited-only), then the option is not suggested as it is not possible to join it.

Once they select this option, then they will get a unique link with no expiration date.

Onboard the community using this link

When I use this link to onboard a community
Once I am logged in or once I have signed up
Then I will access the space-access page so they can:

• freely join it,
• request to join.

In case the space access has been closed, then the space-access page for closed space is displayed to the user.

Notify user inviting

A new notification will be added in the spaces ones.

• Name: Used Referral Link
• Channel: Onsite / Email

Once a user joins a space using an invitation link, then a new notification is sent to users sharing the link

Reward & track invitations

For analytics purpose, invitation links must be tracked as follow:

• Module (Social)
• sub module (spaces)
• operation: Invite user (already existing), joined (already existing)
  - Invitation Type: User, Email, Link
• Social: User ID (user profile of the inviter)
• Entity ID: (profile of the invited user when possible)

To boost community growing, a new gamification event will be created. It will be triggered only when the link is used AND the user actually joins the space.

• Name: Spaces: Invite people to join using a link
• Icon: layers-group

Only the user who has shared the link will get the point, not the user who joins the space.

Impacts

Gamification

New automatic action to get points for each new user using an invitation link

Notifications

New notification to users sharing a link and for which a new user joins a space

Analytics

Track each time an invitation link is created and then used.

Unified Search

N/A

2. Technical Requirements

Security

Token Generation & Validation

• Token payload: {inviterId, spaceId, nonce}
  • nonce: 12-character cryptographically secure random string
• Encoding: Base64 URL-safe
• Token is permanent (does not expire by default)
• Token verification does not require storage and must not compromise the secret key

Validation Rules

• Space ID in token must match target space
• Token signature must be valid
• User must not already be a member
• Token verification relies solely on asymmetric key pair

Permanent Link

• Invitation link must be a permanent link
  • Resolves consistently to the correct space
  • Bookmarkable and shareable externally
  • Integrates with existing permanent link infrastructure

3. Software Architecture

1. Space Invitation Link Feature Overview

This feature enables space managers to generate secure, shareable invitation links that allow external users to join spaces directly. The implementation uses symmetric encryption to secure invitation tokens and integrates with existing SpaceService and permanent link infrastructure.

Link Format:

/portal/s/{spaceId}?invitation_id={encryptedToken}

User Flow

1. Manager clicks "Send Invitation Link" in space menu → UI drawer displays generated link
2. User clicks invitation link → SpacePermanentLinkHandler intercepts and validates token
3. Handler sets session attributes with invitation context
4. Space access page (including public spaces) reads session →
   If invitation token exists, automatically attach it to send/join requests triggered by user actions
5. SpaceMembershipRest validates token and applies join logic based on space visibility
6. Event fired for analytics/gamification tracking

Existing Features

Modifications Required:

1. Space Actions Menu

   • Add "Send Invitation Link"
   • Visible only to space managers
   • Opens SpaceInvitationLinkDrawer.vue

2. space-access.jsp

   • Read SPACE_INVITATION_TOKEN from session
   • Auto-populate join request
   • Pass token to frontend

3. SpaceMembershipRest

   • Extend addSpacesMemberships to handle invitationToken
   • Add endpoint: GET /invitationLink

4. SpaceMembershipUpdateEntity

   • Add invitationToken field

5. SpacePermanentLinkHandler

   • Extract invitation_id
   • Validate token
   • Set session attributes
   • Allow hidden space access with valid token

---

API

Generate Invitation Link

• GET /v1/social/spacesMemberships/invitationLink?spaceId={id}
• Response:

{ "invitationLink": "https://.../portal/s/123?invitation_id=xyz" }

Join Space (Extended)

• POST /v1/social/spacesMemberships

{
 ....
  "invitationToken": "encryptedToken"
}

---

Session Attributes

• SPACE_INVITATION_CONTEXT (String) - JSON string containing all invitation data:

{
  "token": "encryptedToken",
  "spaceId": "123",
  "inviterId": "john.doe"
}

4.Data and Persistence

• No new database tables required
• Transient token storage in HTTP session
• Optional cache for one-time use enforcement (token hash → used flag)

Clustering

• Session replication required
• Symmetric key must be identical across nodes
• Store in shared filesystem or distributed configuration

Integrations

• Analytics: social.space.invitationUsed event
• Gamification: award points/badges for successful invitations

5. Annexes

Technical Reasoning

• Permanent links avoid token expiration issues and allow external sharing
• Tokens do not require database storage; validation is stateless
• Session storage ensures transient context only during access flow

[srenault-meeds]

@margondicco @Julien-Dubois-eXo to check please

[plamarque]

we need referals to be usable as triggers for quests

[srenault-meeds]

we need referals to be usable as triggers for quests

Actually, it is already included in the spec. Please check again.

[Julien-Dubois-eXo]

@srenault-meeds for analytics, instead of having 2 operations, Share invitation link and invite user, don't you think it could be better to have one operation "Invite user" but with an attribute "Invitation type". This attribute may have 3 values:

• invite platform user
• invite by email
• invite by link.

In this case, we need to define also the action that will be tracked:

• the action of invitation or
• the action of accepting the invitation.

IMO here it better to track the action of invitation to overview the invitations of the platform. However the only action we can track for the link is copy/past. It may be not really accurate as a user may click several time on copy/paste.

In addition, we can have another measuring point to track the action of accepting the invitation with the same attribute "Invitation type" to easily identified the most used option.

WDYT?

We can discuss it.

[srenault-meeds]

Yes right. I will update this accordingly.
Thanks for this suggestion.

[srenault-meeds]

MIP updated after internal discussion @Julien-Dubois-eXo @margondicco

[Julien-Dubois-eXo]

@srenault-meeds validated from my side.