> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fusioncore.us/llms.txt
> Use this file to discover all available pages before exploring further.

# Affiliations for Base Salesforce

> Model many-to-many relationships between Accounts and Contacts that standard Salesforce can't capture natively.

## Overview

Standard Salesforce lets a Contact belong to only one Account (`Contact.AccountId`). The **Affiliations for Base Salesforce** accelerator adds a dedicated junction object, `FS_Affiliation__c`, so you can track many-to-many relationships — an employee at more than one organization, a partner or supplier relationship between two Accounts, or a family relationship between two Contacts — each with a role, a date range, and a status. It targets organizations on base Salesforce (not Fonteva or NPSP) that need relationship history, not just a current snapshot.

This accelerator is not installed by default with fusionCore — it's an add-on package installed separately.

<Info>
  The current version verified against source is 1.0.1. Confirm the version installed in your org before relying on details below.
</Info>

## Key Concepts

* **Affiliation** (`FS_Affiliation__c`) — one relationship record, in one of three shapes set by its record type: **Account to Contact** (roles: Admin, Employee, Manager), **Account to Account** (Partner, Supplier), or **Contact to Contact** (Spouse, Parents).
* Every affiliation carries a `FS_Start_Date__c`, an optional `FS_End_Date__c`, and a `FS_Status__c` (`Active`, `Past`, `Future`) that a nightly batch job keeps current based on those dates.
* `FS_Is_Default__c` marks a Contact's one "home" affiliation — the automation keeps this in sync with the Contact's standard `AccountId`.
* `FS_Is_Primary_Account__c` / `FS_Is_Primary_Contact__c` mark the primary Account for a Contact, or the primary Contact for an Account (synced to `Account.FS_Primary_Contact__c`).

<Warning>
  Automatic syncing (primary/default flags, the write-back to `Contact.AccountId`, and the nightly activation batch) only runs for the **Account to Contact** record type. Account-to-Account and Contact-to-Contact affiliations are data-model only — their status still updates, but nothing else syncs automatically.
</Warning>

## Prerequisites

* A "bucket" Account already created in your org — a generic holding Account for Contacts that lose their active primary affiliation.
* The package ships no permission set. Plan to grant Create/Read/Edit/Delete on `FS_Affiliation__c` and its fields, plus access to the three record types, to any profile or permission set that needs it.

## How to Configure

<Steps>
  <Step title="Set the bucket Account">
    Open the Custom Metadata record **Affiliations Accelerator Settings** (`FS_Affiliations_Accelerator_Settings__mdt`, Setup → Custom Metadata Types → Affiliations Accelerator Settings → Manage Records) and set `FS_Bucket_Account_ID__c` to the real Account Id you created above. The shipped record ships with a placeholder Id from the build org — leaving it unchanged breaks re-parenting when a Contact's primary affiliation expires.
  </Step>

  <Step title="Decide the sync behavior">
    On the same settings record, set:

    * `FS_Use_Default_Account__c` — checked to keep a Contact's `AccountId` following its default affiliation's Account; unchecked to fall back to the bucket Account instead.
    * `FS_Support_Primary_Contact__c` — checked to write affiliation changes back to `Account.FS_Primary_Contact__c` and `Contact.AccountId`.
    * `FS_Support_Affiliation_Creation__c` — checked to auto-create an affiliation record whenever a Contact is inserted with an Account, or `Account.FS_Primary_Contact__c` / `Contact.AccountId` is edited directly.
    * `FS_Default_Relationship__c` and `FS_Batch_Size_for_Nightly_Job__c` (keep this between 1 and 200).
  </Step>

  <Step title="Grant access">
    Assign Create/Read/Edit/Delete on `FS_Affiliation__c`, its fields, and the three record types to the relevant profiles or permission sets. Assign the four shipped page layouts (one general, one per record type) to match.
  </Step>

  <Step title="Expose affiliations on Account and Contact pages">
    Add the `Affiliations` related lists and the `Account.FS_Primary_Contact__c` field to your Account and Contact page layouts, and add the `FS_Affiliation__c` tab to the relevant app.
  </Step>

  <Step title="Confirm the nightly batch is scheduled">
    On a managed-package install, `FS_Affiliation_InstallScripts` automatically schedules `FS_AffiliationsBatch` nightly at 1 AM (job name `FS_Affiliation_Nightly01`). If your team deployed this as unmanaged source instead of installing a package, the install script never runs — check **Setup → Scheduled Jobs** and schedule `FS_AffiliationsBatch` manually if it's missing.
  </Step>
</Steps>

## Limitations and Common Pitfalls

* **Parent Account and Child Contact are locked after creation.** Once both are set on an affiliation, you can't change them — create a new affiliation instead of editing an existing one.
* **A default affiliation can't be deactivated directly.** Un-flag `FS_Is_Default__c` first if you need to expire a Contact's default affiliation.
* **You can't resurrect an expired affiliation by editing its status.** If `FS_End_Date__c` is in the past, change the dates — moving the status field back to Active or Future is blocked.
* **Primary flags are locked during a status change.** You can't toggle `FS_Is_Primary_Account__c` / `FS_Is_Primary_Contact__c` in the same edit that expires or defers an affiliation.
* **The nightly batch only activates and deactivates Account-to-Contact affiliations**, and only those with both a Parent Account and Child Contact populated — it does not touch Account-to-Account or Contact-to-Contact records.
* **`FS_Batch_Size_for_Nightly_Job__c` isn't range-validated.** A non-numeric value falls back to 50, but an out-of-range number (for example, over 200) is accepted as-is — keep it between 1 and 200 yourself.