Anchored Conversations, Typed Record Comments & Field Suggestions Guide
MemberJunction provides a unified Anchored Conversations, Typed Record Comments & Field Suggestions architecture built on top of MJ: Conversations, MJ: Conversation Types, MJ: Comments (IS-A MJ: Conversations), MJ: Comment Types, and MJ: Field Suggestions (IS-A MJ: Comments).
Instead of bolting separate comment or AI-suggestion tables onto individual domain entities, record discussions and structured field proposals are modeled once in MJ Core as typed, anchored conversations:
- Multi-message threading (
MJ: Conversation Details) — created on demand only when someone posts a note or clicks Discuss on a suggestion - User and AI agent
@mentionautocomplete and in-app notifications (MJ: User Notifications) - Shared resolution tracking (
IsResolved,ResolvedByUserID,ResolvedAtonMJ: Conversations) - Row-Level Security (RLS) and Field-Level Security (FLS) enforced uniformly across
MJ: Conversations,MJ: Comments,MJ: Field Suggestions, andMJ: Conversation Details - Declarative IS-A Subtype Chaining (
Entity.SubtypeSelector) — saving anMJ: Field Suggestionsentity writes theConversation,Comment, andFieldSuggestionrows atomically in one transaction
1. Entity Model & Two-Level IS-A Chain
Section titled “1. Entity Model & Two-Level IS-A Chain”erDiagram
ConversationType ||--o{ Conversation : "TypeID (Type is virtual)"
Conversation ||--o| Comment : "IS-A (PK = ID)"
CommentType ||--o{ Comment : "CommentTypeID"
Comment ||--o| FieldSuggestion : "IS-A (PK = ID)"
ConversationType {
uuid ID PK
string Name
string Code UK
string ExtensionEntity
string DriverClass
}
Conversation {
uuid ID PK
uuid TypeID FK
string Type "Virtual from TypeID"
uuid LinkedEntityID FK
string LinkedRecordID
string AnchorType
string AnchorKey
json AnchorMetadata
bit IsResolved
uuid ResolvedByUserID FK
datetimeoffset ResolvedAt
}
Comment {
uuid ID PK,FK
uuid CommentTypeID FK
}
CommentType {
uuid ID PK
string Name
string Code UK
string ExtensionEntity
string DriverClass
string UIDriverClass
json AllowedAnchorTypes
}
FieldSuggestion {
uuid ID PK,FK
string SuggestedValue
decimal Confidence
string Source
string Outcome
uuid AIPromptRunID FK
}
1.1 Schema Entities (Migrations v6.2.x & V202611091230__v6.3.x)
Section titled “1.1 Schema Entities (Migrations v6.2.x & V202611091230__v6.3.x)”| Entity | Relationship | Key Columns | Purpose |
|---|---|---|---|
MJ: Conversation Types | Lookup / Type Table | Name, Code (unique), Description, ExtensionEntity, DriverClass | Seeded with Chat (CHAT), Skip (SKIP), Routine (ROUTINE), Meeting Room (MEETING_ROOM), and Comment (COMMENT, ExtensionEntity = 'MJ: Comments'), plus any custom legacy Conversation.Type values migrated during upgrade. |
MJ: Conversations | IS-A Root | TypeID (FK), virtual Type, LinkedEntityID, LinkedRecordID, AnchorType, AnchorKey, AnchorMetadata, IsResolved, ResolvedByUserID, ResolvedAt | Declares SubtypeSelector (Path: "TypeID.ExtensionEntity", AutoEnsureOnSave: true, Driver: { Path: "TypeID.DriverClass", BaseClass: "ConversationTypeDriver" }). |
MJ: Comments | IS-A MJ: Conversations | ID (PK/FK to Conversation.ID), CommentTypeID (FK) | Extension entity for the Comment conversation type. Declares SubtypeSelector (Path: "CommentTypeID.ExtensionEntity", AutoEnsureOnSave: true, Driver: { Path: "CommentTypeID.DriverClass", BaseClass: "CommentTypeDriver" }, UIDriver: { Path: "CommentTypeID.UIDriverClass" }). |
MJ: Comment Types | Lookup / Type Table | Name, Code (unique), ExtensionEntity, DriverClass, UIDriverClass, AllowedAnchorTypes (JSONType = 'CommentTypeAllowedAnchorTypes') | Seeded with Comment (COMMENT, plain note) and Field Suggestion (FIELD_SUGGESTION, ExtensionEntity = 'MJ: Field Suggestions', DriverClass = 'FieldSuggestionCommentDriver', UIDriverClass = 'FieldSuggestionCardComponent', AllowedAnchorTypes = ['Field']). |
MJ: Field Suggestions | IS-A MJ: Comments | ID (PK/FK to Comment.ID), SuggestedValue, Confidence, Source (LLM, Integration, Agent, Person), Outcome (Accepted, Rejected, Superseded), AIPromptRunID | First shipped structured comment subtype. Stores proposed field values without overwriting record truth until accepted by an authorized user or superseded by authoritative data. |
1.2 Virtual Conversation.Type & Release / GraphQL Migration Note
Section titled “1.2 Virtual Conversation.Type & Release / GraphQL Migration Note”In MJ 6.3 (V202611091230__v6.3.x__Conversation_Types_Comments_And_Field_Suggestions.sql), the physical Conversation.Type column was replaced by Conversation.TypeID (NOT NULL, referencing MJ: Conversation Types):
- Reads & Filters Stay Unchanged: Because the foreign key is named
TypeID, CodeGen exposesTypeonvwConversations(and inherited IS-A viewsvwCommentsandvwFieldSuggestions) as a read-only virtual column. ExistingRunViewfilters such asType = 'Skip'orType = 'Comment'and property reads (conversation.Type) continue to work identically. - TypeScript Writers Use
TypeID+CONVERSATION_TYPE_CODES:ConversationEngine.Instance.TypeByCode(CONVERSATION_TYPE_CODES.ROUTINE)resolves the cachedMJConversationTypeEntityrow without magic strings. WhenTypeIDis omitted on a new conversation,MJConversationEntityServerdefaultsTypeIDtoCommentwhenAnchorType IS NOT NULLand toChatotherwise. - ⚠️ Breaking Change for External GraphQL Mutation Callers: Because
Conversation.Typeis now a virtual view column (IncludeInGeneratedForm = 0, no stored-procedure parameter),CreateMJConversationInputandUpdateMJConversationInputno longer includeType. External GraphQL clients that previously sentTypeinCreateMJConversationorUpdateMJConversationmutations must either omitType(to accept the server default) or passTypeID.
1.3 Constraints & Indexes
Section titled “1.3 Constraints & Indexes”CK_Conversation_AnchorType: Enforces validAnchorTypevalues (NULL,'Contribution','DocBlock','Field','Group','Record','Section','SheetRange','SlideRegion').CK_Conversation_AnchorLinkBinding: EnforcesAnchorType IS NULL OR (LinkedEntityID IS NOT NULL AND LinkedRecordID IS NOT NULL).IDX_Conversation_LinkedRecord_Anchor_Type: Composite index on(LinkedEntityID, LinkedRecordID, AnchorType, TypeID)(plusAnchorKey,IsResolved) for sub-millisecond anchored note/suggestion loading while keeping anchored threads isolated from main AI chat lists (AnchorType IS NULL AND LinkedEntityID IS NULL).
2. Strongly-Typed JSON Metadata (IConversationAnchorMetadata)
Section titled “2. Strongly-Typed JSON Metadata (IConversationAnchorMetadata)”Defined in metadata/entities/JSONType-interfaces/IConversationAnchorMetadata.ts and generated onto MJConversationEntity.AnchorMetadataObject (inherited by MJCommentEntity and MJFieldSuggestionEntity):
export interface IConversationAnchorMetadata { /** Friendly display label of the anchor target at the time the comment was created */ anchorDisplayName?: string; /** Target field code name when AnchorType is 'Field' */ fieldName?: string; /** Collapsible panel SectionKey containing the target field or section */ sectionKey?: string; /** Friendly display name of the section */ sectionDisplayName?: string; /** Left-nav rail group key containing the target section */ groupKey?: string; /** Friendly display name of the rail group */ groupDisplayName?: string; /** Formatted snapshot of the field's value at the moment the thread was started */ quotedValue?: string; /** Field names on the linked entity whose FLS read permission is required to view this thread */ restrictedFields?: string[]; /** Optional character/block range for rich-text or document blocks */ selectionRange?: { startOffset?: number; endOffset?: number; blockId?: string; };}Type Derivation Rule: Always derive value-list unions from generated entity types (
MJConversationEntity['AnchorType'],MJFieldSuggestionEntity['Source'],MJFieldSuggestionEntity['Outcome']) rather than hand-copying string unions.
3. Comment Type Drivers & Field Suggestion Lifecycle
Section titled “3. Comment Type Drivers & Field Suggestion Lifecycle”Each MJ: Comment Types row can name a server/shared behavior driver (DriverClass, extending CommentTypeDriver -> EntitySubtypeDriverBase) and an Angular card renderer (UIDriverClass, extending EntitySubtypeUIDriverBase).
3.1 CommentTypeDriver & FieldSuggestionCommentDriver
Section titled “3.1 CommentTypeDriver & FieldSuggestionCommentDriver”FieldSuggestionCommentDriver (@RegisterClass(CommentTypeDriver, 'FieldSuggestionCommentDriver') in @memberjunction/core-entities) implements the full lifecycle for MJ: Field Suggestions:
- Anchor & Entity Opt-In Validation (
Validate&MJFieldSuggestionEntityServer):- Verifies
AnchorType === 'Field'(matchingCommentType.AllowedAnchorTypes = ['Field']), a validAnchorKeynaming an existingEntityFieldon the linked entity, and that the linked entity allows'FIELD_SUGGESTION'inEntityInfo.AllowedCommentTypeCodes.
- Verifies
- Accept (
ConversationEngine.AcceptFieldSuggestion->FieldSuggestionCommentDriver.OnAccept):- Loads the linked target record as
acceptingUser, verifiesentityInfo.AllowUpdateAPI, entityCanUpdatepermission, and FLSIsFieldUpdatableByUser(field, acceptingUser). - Coerces
SuggestedValueto the field’s MJ scalar/boolean/numeric/date type and saves the target record normally asacceptingUser— soMJ: Record Changesauditing, server-side entity hooks, and FLS apply identically to a manual user edit. - Marks the suggestion
Outcome = 'Accepted',IsResolved = true,ResolvedByUserID = acceptingUser.ID,ResolvedAt = new Date().
- Loads the linked target record as
- Reject (
ConversationEngine.RejectFieldSuggestion->FieldSuggestionCommentDriver.OnReject):- Requires the exact same entity and field update permissions on the target field as
Accept. - Marks the suggestion
Outcome = 'Rejected',IsResolved = true,ResolvedByUserID = rejectingUser.ID,ResolvedAt = new Date()without modifying the target record.
- Requires the exact same entity and field update permissions on the target field as
- Automatic Superseding (
AfterSave&FieldSuggestionPostSaveHook):- Newer Suggestion Supersedes Older: When a new open
MJ: Field Suggestionsrow is saved for(LinkedEntityID, LinkedRecordID, AnchorKey),FieldSuggestionCommentDriver.AfterSave()automatically marks any older unresolved suggestion on that same field asOutcome = 'Superseded'andIsResolved = true. - Direct Field Edit Supersedes Pending Suggestions (
PostSaveHook):@memberjunction/coreprovides a generic'PostSave'provider hook (PostSaveHook, fired afterBaseEntitycommits a create or update withChangedFieldNames).FieldSuggestionPostSaveHook(@memberjunction/core-entities-server) listens for saves on entities that opt intoFIELD_SUGGESTION, resolves each open comment’sCommentTypeDriver, and invokesOnRecordChanged(), automatically marking pending suggestions for modified fields asOutcome = 'Superseded'andIsResolved = true(skipping the suggestion currently being accepted viaAcceptFieldSuggestion).
- Newer Suggestion Supersedes Older: When a new open
- Zero-Noise Discussion (
Discuss):- Creating a
Field Suggestiondoes not require creating anMJ: Conversation Detailsmessage row. Message rows exist only if a user or agent clicks Discuss on the suggestion card to start a thread inside that suggestion’s conversation.
- Creating a
3.2 Entity-Level Opt-In (MJ: Entities.Configuration.Comments)
Section titled “3.2 Entity-Level Opt-In (MJ: Entities.Configuration.Comments)”Administrators and Open Apps configure commenting and allowed comment types per entity in MJ: Entities.Configuration:
{ "Comments": { "Enabled": true, "RequiredPermission": "Read", "AllowedRoles": ["Developer", "Reviewer"], "AllowedCommentTypes": ["COMMENT", "FIELD_SUGGESTION"] }}Enabled(boolean, defaulttrue): Set tofalseto disable all record commenting on the entity (EntityInfo.AllowRecordComments === false).RequiredPermission('Read' | 'Update', default'Read'): Controls whether starting/replying to plain comments requiresCanReadorCanUpdate(EntityInfo.CanUserComment(user)). Accepting or rejecting aField Suggestionalways requires update permission on both the entity and the target field regardless ofRequiredPermission.AllowedRoles(string[], optional): Restricts commenting to users holding at least one listed role name or ID.AllowedCommentTypes(string[], default['COMMENT']): Lists theMJ: Comment Types.Codevalues permitted on this entity (EntityInfo.AllowedCommentTypeCodes,EntityInfo.IsCommentTypeAllowed(code)). Plain notes ('COMMENT') are enabled by default; structured types such as'FIELD_SUGGESTION'are opt-in per entity (e.g.,MJ_BizApps_Tasks: Tasks,GitHubIssueTask,GitHubPullRequestTask).
4. Security Architecture: RLS & Two-Stage FLS Protection Across All IS-A Views
Section titled “4. Security Architecture: RLS & Two-Stage FLS Protection Across All IS-A Views”Anchored conversations, comments, and field suggestions share one defense-in-depth security pipeline across @memberjunction/core-entities and @memberjunction/core-entities-server:
4.1 Server-Side PostRunView Enforcement (AnchoredConversationPostRunViewHook)
Section titled “4.1 Server-Side PostRunView Enforcement (AnchoredConversationPostRunViewHook)”Registered via RegisterProviderHook('PostRunView', AnchoredConversationPostRunViewHook) in @memberjunction/core-entities-server and MJServer, every server-side RunView against MJ: Conversations, MJ: Comments, MJ: Field Suggestions, or MJ: Conversation Details automatically filters out any row whose linked record fails UserCanReadLinkedRecord (RLS) or whose target/stamped fields fail IsConversationHiddenByFieldSecurity (FLS) for contextUser — even when callers request narrow Fields projections that omit AnchorType, AnchorKey, or LinkedEntityID.
4.2 Field-Level Security (FLS) — Read Gate & quotedValue Redaction
Section titled “4.2 Field-Level Security (FLS) — Read Gate & quotedValue Redaction”When entityInfo.FieldLevelSecurityApplies === true, IsConversationHiddenByFieldSecurity(entityInfo, user, anchorType, anchorKey, anchorMetadata) computes denied = entityInfo.GetDeniedReadFields(user) and hides the note or suggestion in 0ms when:
AnchorType === 'Field'anddenied.has(anchorKey.toLowerCase())— aField Suggestionon a field the user cannot read is completely invisible, ORAnchorMetadataObject.fieldNameis indenied, OR- Any field listed in
AnchorMetadataObject.restrictedFieldsis indenied.
Both client-side (<mj-form-field> and <mj-record-comments>) and server-side (MJConversationEntityServer.Save()) strip AnchorMetadataObject.quotedValue whenever the target field has HasFieldPermissions === true or Encrypt === true.
4.3 Write-Time Unanchored Comment Classifier (InspectAndStampRestrictedFieldsForComment)
Section titled “4.3 Write-Time Unanchored Comment Classifier (InspectAndStampRestrictedFieldsForComment)”On every MJConversationDetailEntityServer.Save() belonging to an anchored thread (AnchorType != null) on an FLS-governed entity, InspectAndStampRestrictedFieldsForComment() runs the two-stage lexical/author-readable-value + governed AIPromptRunner classifier ('Anchored Comment Restricted Field Classifier'), rejecting unauthorized restricted-field references with a generic non-oracle error and stamping authorized references into AnchorMetadataObject.restrictedFields.
4.4 @Mention Notifications with FLS/RLS Gating
Section titled “4.4 @Mention Notifications with FLS/RLS Gating”DispatchConversationMentionNotifications() verifies both IsConversationHiddenByFieldSecurity and UserCanReadLinkedRecord before dispatching MJ: User Notifications, ensuring restricted comment or suggestion discussions never leak via notification previews.
5. Angular Form UX (@memberjunction/ng-base-forms)
Section titled “5. Angular Form UX (@memberjunction/ng-base-forms)”Generated and custom forms inherit the unified Notes & suggestions UX automatically through <mj-record-form-container>, <mj-form-toolbar>, <mj-collapsible-panel>, and <mj-form-field>:
- Per-Type Field Badges (
<mj-form-field>):- Fields with open plain notes show the note badge (
fa-solid fa-comment,.mj-forms-field__comment-pill). - Fields with pending
MJ: Field Suggestionsshow a distinct suggestion badge (fa-solid fa-wand-magic-sparkles,.mj-forms-field__comment-pill--suggestion). - Clicking either badge opens the anchored popover pre-filtered (
PreferredTypeFilter) to'COMMENT'or'FIELD_SUGGESTION'. Fields with open notes or suggestions are never collapsed away as empty in read mode.
- Fields with open plain notes show the note badge (
- “Notes & suggestions” Drawer & Popover (
<mj-record-comments>):- Toolbar action (
RecordCommentsToolbarAction, key'comments') is labeled Notes & suggestions and displays the combined open thread + pending suggestion count. - When the entity allows multiple comment types (
AvailableTypeFilterCodes.length > 1), an accessible type filter pill bar (role="group"+aria-pressed) lets users filter between All, Notes, Suggestions, and any additional customMJ: Comment Types, alongside Open / Resolved / All status filters.
- Toolbar action (
- Dynamic Card Rendering via
UIDriverClass(<mj-comment-card-driver-host>&FieldSuggestionCardComponent):- Plain comments (
UIDriverClass == null) render with the standard threaded note card. - When a comment’s
MJ: Comment Typesrow declares aUIDriverClass(such asFieldSuggestionCardComponent, registered via@RegisterClass(EntitySubtypeUIDriverBase, 'FieldSuggestionCardComponent')),<mj-comment-card-driver-host>instantiates that component dynamically viaMJGlobal.Instance.ClassFactory. FieldSuggestionCardComponentdisplays:- Source badge (
LLM,Integration,Agent,Person) and confidence percentage pill - Current field value vs. ghost Suggested value diff block (or outcome pill
Accepted/Rejected/Supersededonce closed) - Accept, Reject (enabled only when
CanUserUpdateTargetFieldis true), and Discuss (revealing and focusing the inline reply composer on demand; genericResolveis suppressed on suggestion cards so resolution always flows through Accept/Reject/Supersede)
- Source badge (
- Accepting a suggestion through
FormRecordCommentsCoordinatorService.AcceptFieldSuggestionreloads the clean server record into the open form (InnerLoad+FormRecordRefreshCoordinator.NotifyRemoteUpdate), and saving the form directly reloads open suggestions so auto-superseded items update immediately on screen.
- Plain comments (