--- id: FEAT-CRM-ENT-05 title: Organization Compliance product_area: crm module: entities revision: 1 status: approved product_intent: proposed source_sha: services-crm: 7ea48a414c42eade10d60753b8bcc323b1dd726f react-console: da63075876b2c5f4a6af07d457bb24ea8bf4c0c7 purpose: >- Staff identify gaps in an organization’s required roles and prepare notices about them. This feature groups compliance review and communication. outcomes: - Staff identify gaps in an organization’s required roles and prepare notices about them. concepts: - CON-CRM-ENT-035 actors: - ACT-CRM-001 - ACT-CRM-002 - ACT-CRM-003 - ACT-CRM-004 - ACT-CRM-005 acceptance: FAS-CRM-ENT-05 capabilities: - CAP-CRM-ENT-012 journeys: [] related_concepts: - CON-CRM-ENT-002 - CON-CRM-ENT-005 approved_by: Andrew approved_at: 2026-10-22T00:00:00.000Z narrative: status: verified review: NARRATIVE-REVIEW-2026-10-23 narrative_sources: - section: Why It Exists provenance: inferred source: CAP-CRM-ENT-012 note: >- Operational consequences are the reviewer’s reading of the child contracts, not attributed historical motivation. The affiliation milestone supplies the current-membership distinction where named. - section: Decisions and Tradeoffs provenance: inferred source: "CAP-CRM-ENT-012" note: The tradeoffs interpret the child contracts; no historical motive is attributed. - section: How It Works provenance: observed source: >- services-crm:modules/entities/tests/integration/services/organizations/compliance/organization-compliance.integration.spec.js#with a type that holds it to no rule, or with no type: no status and no violations; services-crm:modules/entities/tests/integration/services/organizations/compliance/organization-compliance.integration.spec.js#with a type that holds it to rules: not in compliance, every rule with a minimum violated (it has no contact yet); services-crm:modules/entities/tests/integration/services/organizations/compliance/organization-compliance.integration.spec.js#brings an organization into compliance for a role held on a current affiliation that is not primary; services-crm:modules/entities/tests/integration/services/organizations/compliance/compliance-change-events.integration.spec.js#a contact saved with the notes DISABLE_CONTACT_ROLE_COMPLIANCE_CHECK: nothing (its delete still records); services-crm:modules/entities/tests/integration/services/organizations/compliance/organization-compliance.integration.spec.js#writes nothing for a duplicate delivery, or a second run on an unchanged organization; services-crm:modules/entities/tests/e2e/organization-compliance.e2e.spec.js#keep them against a PUT that sends others back; services-crm:modules/entities/tests/integration/services/organizations/compliance/organization-compliance.integration.spec.js#is not submitted again while the organization stays out of compliance, nor for a type that does not notify; services-crm:modules/entities/tests/integration/services/organizations/compliance/compliance-reads.integration.spec.js#leaves out the contact whose addresses sit past the primary slot, no secondary address standing in; services-crm:docs/entities-api.md#`compliance_notification_template`: the e-mail the type sends; services-crm:modules/entities/tests/integration/services/persistence/compliance-reprocesses.integration.spec.js#refuses a second running run for the tenant; services-crm:modules/entities/tests/e2e/email-previews.e2e.spec.js#answers 403 to a caller who may administer types but may not read the records the answer contains; services-crm:modules/entities/tests/e2e/organization-compliance.e2e.spec.js#answers 400 for a template both named and typed in, or neither; services-crm:modules/entities/services/persistence/organization-types.ts:organizationTypeProblems; services-crm:modules/entities/tests/integration/services/persistence/organization-attention-items.queries.integration.spec.js#answers the organizations out of compliance by id, and no other; services-crm:modules/entities/services/templates/compliance-notification-template.ts:effectiveTemplateChange; services-crm:modules/entities/services/persistence/organization-types.ts:updateOrganizationType; services-crm:modules/entities/tests/integration/services/templates/compliance-notification-template.integration.spec.js#keeps the delete and logs the type id when Platform cannot clear it: the type is gone either way acceptance_suite: FAS-CRM-ENT-05 --- # Organization Compliance ## Overview Organization Compliance assesses whether an organization has the contact-role coverage expected by its type. For an association, this can mean checking that a member firm has a billing representative or that a chapter has the required officers. The assessment explains gaps or excess holders through violations. The feature also supports preparing notices and reevaluating organizations after expectations change. Assessment, notice submission, and mail delivery have distinct responsibilities and timing; a stored compliance change is not itself evidence that an e-mail reaches a recipient. ## Why It Exists Our reading is that configured representative requirements are useful only when staff can compare them with effective people. A chapter may require a billing contact while a firm requires several officer roles. Manually checking every contact's affiliation and role dates can miss a departing holder, double-count one person with several ties or mistake a future appointment for present coverage. A calculated assessment identifies the specific shortage or excess for staff to address. Notices can accompany a deterioration, and reprocessing lets changed expectations reach organizations already on file. Neither a saved policy nor a submitted notice proves the whole chain has completed: assessments need reevaluation and Platform owns delivery. Keeping those boundaries visible helps staff interpret a displayed violation without promising immediate recalculation or a delivered message. ## Who Uses It The CRM Administrator configures organizational rules, notification roles, and notice content, previews examples, and requests reprocessing. The CRM Editor changes the affiliations and responsibilities that supply coverage. The CRM Reader inspects organization status and violations. The CRM System recalculates affected organizations and submits notices through Platform's communication boundary. ## How It Works An organization type enables compliance and states minimum or maximum holder counts for selected contact roles. Recalculation counts distinct people holding each role on current affiliations, including secondary affiliations, and compares those counts with the configured bounds. A changed assessment updates the organization's stored violations and version; repeated evaluation of the same result avoids redundant writes. A transition into noncompliance can submit a notice for the configured recipients. Submission is transactionally deduplicated with the written assessment. Platform owns the template and delivery. Administrators can preview a draft without storing or sending it, make a test send to a specified address, or request a resumable workspace reprocess when existing assessments need reevaluation. The administrator expresses expectations on Organization Type, using Contact Role as the vocabulary for the responsibility to count. A minimum of one Billing Contact asks for a person holding that responsibility, not one affiliation row. A person with two qualifying ties to the same body still contributes one holder for that role. A future or ended responsibility does not supply today's coverage, and a secondary affiliation can qualify just as a primary one can. Maximum counts also matter: too many holders can be a violation as well as too few. An organization without an enabled role policy has no compliance assessment to satisfy. Recalculation clears its stored compliance information instead of treating absence of policy as a failed requirement. For a governed organization, the evaluator reads current committed information and compares the calculated violations with the stored result. A changed result is written under system attribution and can make an open organization edit stale. Repeated evaluation of an unchanged result avoids another revision. Contact changes feed asynchronous reevaluation rather than making notice delivery part of a coordinator's contact save. Notices concern a transition into noncompliance. Continued noncompliance does not send the same transition notice again, even when staff revisit the organization. Recipient selection uses the type's notification roles and eligible contacts with e-mail information. CRM records the submission with the assessment; Platform accepts and delivers it afterwards. A committed submission is consequently a durable request, not a delivered-message receipt. Policy maintenance has another boundary. Saving changed expectations does not prove every existing organization has been recalculated. Administrators can request a durable workspace reprocess and inspect its progress and result. Draft preview renders sample content without changing policy or sending; a test send uses a specified destination and Platform's test path. Neither is the organization's real transition notice, so staff use them to inspect wording and delivery configuration rather than infer that member recipients were notified. ## Examples A member firm type requires one billing contact. The firm's sole current billing role ends, and recalculation records the missing holder. If the type enables notices, the transition submits a notice to current affiliates selected by its notification roles. Correcting the responsibility later restores coverage; continuing noncompliance does not repeatedly submit the same transition notice. Harbor West Chapter's type requires at least two Officers and one Billing Contact. Ruth Kim holds Officer through two current chapter affiliations and Lena Park holds it through one. The officer count is two people, not three rows. Daniel Ruiz supplies Billing Contact until October 23. After that inclusive final day, a relevant recalculation can find the missing billing holder and persist the violation. If enabled notice conditions apply, the transition submits a notice for eligible configured recipients. The administrator previews the wording with Harbor West's data and test-sends it to her own address before changing notice content. She then changes the type to require three Officers and requests reprocessing of existing organizations. Harbor West's reassessment can identify an officer shortage too. That changed violation does not imply another transition into noncompliance while the chapter remains noncompliant. Assigning another effective officer and billing holder lets later reevaluation restore coverage; the staff inspect the stored result separately from Platform's delivery outcome. ## Decisions and Tradeoffs Our reading is that distinct-person counting protects a business expectation about representatives from being inflated by duplicate relationship rows. Date-sensitive coverage prevents a future appointment from concealing a present gap. Separating no policy from satisfied policy also makes an organization's displayed result interpretable: blank assessment is not a certificate of coverage. Transition notices limit repeated mail while preserving the first deterioration as a durable communication request. Transactional submission ties that request to the committed assessment, but delivery remains an independent Platform responsibility. Explicit reprocessing makes the operational cost and progress of applying changed expectations visible. It also means a policy save and a current assessment are separate milestones staff must check, rather than assuming an instantaneous workspace-wide rewrite. ## Scope and Boundaries This feature owns role-count assessment, violation storage, reprocess orchestration, and notice preparation. Affiliations and Roles owns the source responsibilities and dates. Classification Types and CRM Settings owns type administration, including the policy choices consumed here. Platform notifications owns templates, requests, and sending. Other applications' financial or membership eligibility policies are separate from this role-compliance assessment. ## Outcomes Staff can identify the organizational roles that need attention and revisit assessments after policy changes. The Organization Compliance acceptance suite connects policy configuration, effective coverage, stored results, previews, and notice behavior. Its contracts distinguish calculation from communication delivery and retain the recorded integration gaps rather than treating a displayed status as proof of the whole process. ## Its Capabilities Review organization role compliance and prepare notices calculates coverage, exposes violations, and coordinates previews, test sends, and durable reprocessing. It supplies the complete feature behavior while relying on the separately owned affiliation, role, organization-type, and Platform notification contracts for the information and delivery it needs.