Discussion Forum to Access Requirement

1 Introduction
- 1.1 Current Discussion Forum Architecture
- 1.2 New Requirements
- 1.3 Proposed Design Changes
- 1.4 Database Changes
- 1.5 Get thread for submission
- 1.6 Access to discussions
- 1.7 Notification of Thread

Introduction

This document outlines proposed updates to the Synapse Discussion Forum architecture to decouple it from project‑only usage and make it generally applicable to multiple object types, including Access Requirements (ARs).

Current Discussion Forum Architecture

The current Synapse Discussion Forum, described in detail at
Synapse Discussion Forum, has the following characteristics:

Single Forum per Project
- Each Synapse project is associated with exactly one Forum.
- That Forum includes:
  - One or more Moderators
  - Multiple Threads
  - Multiple Replies per thread
Scope
- All project‑related discussions (analysis questions, support, challenges, etc.) take place in this single project‑level Forum.

New Requirements

PLFM-9390 - Getting issue details... STATUS

Implement a lightweight discussion forum tied to each AR and a discussion thread to each data access submission.This capability enables ACT and DAC members to coordinate review activities within the system while maintaining compliance with external governance policies,

Forum per Project (unchanged)
- A project can still have a top‑level Forum for general project discussions.
Forum per Access Requirement (new)
- Synapse defines multiple Access Requirements (ARs) that can apply to entities such as projects, folders, or files.
- For each AR, there should be its own Forum, distinct from the project’s general Forum.
Discussion thread for each submission (Data Access request)
For every submitted Data Access Request associated with an AR, create a dedicated discussion thread in that AR’s Forum.

Proposed Design Changes

To support these requirements, we will evolve the data model and APIs as follows:

Forum scoping
- Extend the Forum model to support two kinds of owners:
  - projectId (project‑level Forum)
  - accessRequirementId (AR‑level Forum)
- Enforce:
  - At most one Forum per projectId.
  - At most one Forum per accessRequirementId.
Forum creation / lookup APIs
- Generalize “Get Forum for Project” to “Get Forum for Owner”:
  - GET /forum?projectId={projectId} – returns the project‑level Forum. (existing)
  - GET /forum?objectId={objectId}&objectType={objectType} – returns the Forum for a specific Object. If the objectType is null default object type will be ENTITY. (new)

Threads and Replies (unchanged usage, new context)
- The Thread and Reply models and APIs remain the same, but:
  - Threads for AR discussions are simply created in the AR Forum instead of the project Forum.
- All existing moderation, pagination, and notification behavior applies equally to project‑level and AR‑level Forums.

Database Changes

Forum-ddl.sql

CREATE TABLE IF NOT EXISTS `FORUM` (
  `ID` BIGINT NOT NULL,
  `OBJECT_ID` BIGINT NOT NULL,
  `OBJECT_TYPE`  ENUM('ENTITY', 'ACCESS_REQUIREMENT'),
  `ETAG` char(36) NOT NULL,
     PRIMARY KEY ('ID'),
    UNIQUE KEY `FORUM_BACK_UP_ID` (`OBJECT_ID`, `OBJECT_TYPE`)
  )

Backfilling

All existing rows in the FORUM table should be backfilled so that OBJECT_ID is set to the corresponding project ID and OBJECT_TYPE is set to ENTITY.

Forum for Access Requirements (ARs)

Creating a Forum for an AR

A dedicated Forum is created when a new Access Requirement (AR) is created.

Retrieving a Forum for an AR

A new API, GET /forum?objectId={objectId}&objectType={objectType}, will return the Forum associated with the specified AR.

Discussion Thread for Each Submitted Data Access Request to an AR

For every submitted Data Access Request associated with an Access Requirement (AR), we will create a corresponding discussion thread.

The API
https://repo-prod.prod.sagebase.org/repo/v1/dataAccessRequest/{requestId}/submission

is used to submit a request. When this endpoint is called:

A submission record is created in the database. (existing)
A notification email is sent to all users who have the ACCESS_TYPE.REVIEW_SUBMISSIONS permission.(existing)
In addition, a new discussion thread is created for the submission. (new)

DBODiscussionThread dbo = new DBODiscussionThread();
		dbo.setId(Long.parseLong(id));
		dbo.setForumId(Long.parseLong(forumId));
		dbo.setTitle(title.getBytes(UTF8)); // the tille will be submissionId:123
		dbo.setMessageKey(messageKey); // the message will be empty
		dbo.setCreatedBy(userId); // a service user
		dbo.setIsEdited(false);
		dbo.setIsDeleted(false);
		dbo.setIsPinned(false);
		dbo.setCreatedOn(new Date());
		dbo.setModifiedOn(new Date());
		dbo.setEtag(etag);

Normally, when we create a new thread, the creating user is added to the Subscription table, making them a follower of the thread. Followers receive email notifications when replies are posted.

In this case, we do not want the submitter to receive notifications that the request was submitted. Instead, only reviewers should be notified of the new submission (which already occurs via the existing email sent to users with ACCESS_TYPE.REVIEW_SUBMISSIONS). Therefore, for these auto‑created submission threads, we will not add the submitter to the Subscription table.

Get thread for submission

The UI must be able to retrieve the discussion thread associated with a given submission. Use the following new endpoint:

https://repo-prod.prod.sagebase.org/repo/v1/thread/submission/{submissionId}/

Request Object: None

Response Object : DiscussionThreadBundle

Database changes:

DiscussionThreadSubmissionReference-ddl.sql

CREATE TABLE IF NOT EXISTS `DISCUSSION_THREAD_SUBMISSION_REFERENCE` (
  `THREAD_ID` BIGINT NOT NULL,
  `SUBMISSION_ID` BIGINT NOT NULL,
  PRIMARY KEY (`THREAD_ID`, `SUBMISSION_ID`),
  INDEX `DISCUSSION_THREAD_SUBMISSION_REFERENCE_SUBMISSION)ID_INDEX` (`SUBMISSION_ID`),
  CONSTRAINT `DISCUSSION_THREAD_SUBMISSION_REFERENCE_THREAD_ID_FK` FOREIGN KEY (`THREAD_ID`) REFERENCES `DISCUSSION_THREAD` (`ID`) ON DELETE CASCADE,
  CONSTRAINT `DISCUSSION_THREAD_SUBMISSION_REFERENCE_SUBMISSION_FK` 
    FOREIGN KEY (`SUBMISSION_ID`) 
    REFERENCES `SUBMISSION` (`ID`) ON DELETE CASCADE
)

Get Discussion Threads for an AR Forum

To retrieve all discussion threads for an AR, use this API to fetch a specified number of discussion threads for a given forum ID:
https://repo-prod.prod.sagebase.org/repo/v1/forum/{forumId}/threads

Access to discussions

Only ACT and User has ACCESS_TYPE.REVIEW_SUBMISSIONS for the submission can access the discussions.

The backend will expose an API that, given an Access Requirement (AR) ID, returns the caller’s permissions for that AR:

https://repo-prod.prod.sagebase.org/repo/v1/accessRequirement/{requirementId}/permissions

Request object : None

Response object :

class AccessRequirementPermissions{
 boolean hasPermission
}

Notification of Thread

Currently, when a new reply is posted to a thread, email notifications are sent only to users who are already followers (subscribers) of that thread. We do not parse the thread title or message body for @username mentions, nor do we send separate notifications based on mentions.

PLFM-9390 introduces a new requirement: “Enable users to mention (i.e., @username) to trigger targeted (email) notifications to the mentioned user to view the submission in Synapse.”

There are two possible approaches to support this:

Auto‑subscribe all reviewers
Automatically add all users with ACCESS_TYPE.REVIEW_SUBMISSIONS to the Subscription table for the thread, so they receive notifications for new replies.

When a new thread is created by the backend, it will start with no subscribers. When a reply is posted to the thread, the replying user will be automatically subscribed to that thread. Subscription emails always include an unsubscribe link, and users can opt out of the thread’s notifications at any time.

Mention‑based subscription
Parse each thread message for @username mentions and, for each mentioned user who has the appropriate access, add them to the Subscription table so they receive notifications. For project-level threads, the user must have at least READ permission on the project. For submission-related threads, the user must have ACCESS_TYPE.REVIEW_SUBMISSIONS for the submission. This would change the current behavior of discussion threads and would require parsing all messages (since @username may appear in either the original thread message or any reply).

Today in Synapse, we support mention-based notifications: when a user is @‑mentioned in a thread or a reply (for example, @username), that user receives a notification

BroadcastMessageManagerImpl.sendMessageToNonSubscribers() 
Which reads the message text and get @user list from it.

Current email template example
Hello Sandhra (SSokhal),

jay replied to syn123 (Thread link) thread in Sandhra_Project2(Project Link) forum.

Here's a reply, are you notified by email of this reply?

Unsubscribe from the thread

New email template 
If thread is related to AR then include AR link otherwise Project link.