Affiliation

What It Models

An affiliation models one episode of a person’s connection to an organization. Ruth can work for Harbor Engineering and serve Harbor West Chapter at the same time, with distinct responsibilities and dates on each tie. The contact owns each affiliation and its nested role periods even when staff edit from the organization page.

Our reading is that an episode needs its own identity so an employer change can retain the prior stay without changing which body that earlier connection describes. Affiliation Type supplies the relationship meaning and sharing defaults; Contact Role supplies the vocabulary for responsibilities held during the episode.

Identity and Attributes

The values below distinguish identities returned by a read from creation inputs. Ruth’s integration can choose a valid, unused affiliation identity before submitting the contact. A new Billing Contact role period instead omits its identity and receives one from the service. Returning that saved role identity later identifies the existing period; supplying an invented role identity does not create another responsibility.

Each affiliation has a workspace-unique identity, accepting a valid lowercase time-ordered client value on creation. An idless entry matching an existing organization, type and start date reuses that affiliation. Role periods have separate identities scoped to their affiliation.

The table describes logical properties. Optional values can be absent; a required collection member is distinct from requiring the collection itself. Examples illustrate association information and do not establish new defaults. Service-owned values remain separate from fields that staff or integrations supply.

Property	Meaning and writer	Constraints	Example
id	Staff can supply an unused lowercase UUIDv7 for a new affiliation; an existing affiliation retains its saved identity.	Creation accepts an unused identity appearing only once in the submitted list.	019a0f10-0000-7000-8000-000000000001
contact	The contact owns the affiliation permanently. Set by staff.	The contact owns the affiliation permanently.	Ruth Kim
organization	The destination is a workspace organization and cannot change after creation. Set by staff.	The destination is a workspace organization and cannot change after creation.	Harbor Engineering
affiliation type	The affiliation classification is workspace-local. The Organization command uses the configured default. Set by staff.	The affiliation classification is workspace-local. The Organization command uses the configured default.	Employer
primary	One affiliation at most may be primary. It must have started and have no end date. Set by staff.	One affiliation at most may be primary. It must have started and have no end date.	true
job title	The primary affiliation and contact share this title. Whitespace-only content is absent. Set by staff.	The primary affiliation and contact share this title. Whitespace-only content is absent.	Executive Director
start date	The first eligible day of the relationship. Set by staff.	Optional ISO calendar date; absence is unbounded in the past.	2026-10-01
end date	The last eligible day of the relationship. Set by staff.	Optional inclusive ISO calendar date; cannot precede start; primary is open-ended.	2026-10-31
effective state	The workspace date determines whether the relationship is future, effective or ended. Set by system.	The workspace date determines whether the relationship is future, effective or ended.	current
notes	Whitespace-only content is normalized to absence. Set by staff.	Whitespace-only content is normalized to absence.	Represents the member firm.
role periods	An affiliation can contain at most 25 catalogue role periods, each dated within the enclosing relationship. Set by staff.	An affiliation can contain at most 25 catalogue role periods, each dated within the enclosing relationship.	Billing Contact from 2026-10-01
automatic roles due	This pending marker schedules automatic-role assignment once a future relationship becomes due. Set by system.	This pending marker schedules automatic-role assignment once a future relationship becomes due.	true
pending default links	The saved default-link choice waits until a future affiliation becomes effective. Set by system.	The saved default-link choice waits until a future affiliation becomes effective.	Work address when effective
default link choice	Creation-only selection: omission chooses all type mappings, while an empty array chooses none. Set by staff.	Creation-only selection: omission chooses all type mappings, while an empty array chooses none.	Work address selected
archived organization information	Organization label and archive timestamp are added when reading the relationship. Set by system.	Organization label and archive timestamp are added when reading the relationship.	Harbor Engineering, archived on 2026-10-23
type · default mappings	A type defines at most 20 source-to-destination address and phone mappings. Set by staff.	A type defines at most 20 source-to-destination address and phone mappings.	Main address to Work address
role catalogue · settings	The role catalogue supplies name, description, availability, order, locking and automatic or first-contact settings. Set by staff.	The role catalogue supplies name, description, availability, order, locking and automatic or first-contact settings.	Billing Contact, active, automatic
role period identity	The service assigns the identity when it creates a responsibility episode; later edits return that saved identity.	Unique within the nested save; an existing identity remains in its owning affiliation.	019a0f10-0000-7000-8000-000000000002
role definition	The workspace responsibility held in this episode. Set by staff.	Workspace contact role; new assignments obey organization-type restrictions.	Billing Contact
role start date	The first day of this responsibility. Set by staff.	Optional date bounded by the parent affiliation; omission follows its bound.	2026-10-01
role end date	The final day of this responsibility. Set by staff.	Inclusive date within the affiliation; same-role periods cannot overlap.	2026-10-31
element lock	The customer restriction on the relationship or responsibility. Set by staff.	Aggregate safeguard checks apply to protected nested elements.	deletes

Policy and audit properties

These properties belong to the catalogue or safeguard facet named in the property column. They explain the implementation’s exposed policy and audit context without allocating another domain object. System attribution is read-only; catalogue policy is administered through its own permitted operation and is not changed by an ordinary record edit.

Property	Meaning	Example
Role catalogue / id	Stable workspace role identity used by periods and policy.	billing-contact
Role catalogue / name	Staff-facing responsibility label.	Billing Contact
Role catalogue / description	Optional explanation of the responsibility.	Receives dues correspondence
Role catalogue / is_active	Availability of the definition, separate from a saved period’s dates.	true
Role catalogue / display_order	Optional administrator order, with alphabetical fallback for unordered definitions.	2
Role catalogue / administrative_contact	Saved administrative-contact classification; the built role editor does not expose a switch for this property.	true
Role catalogue / assign_automatically	Requests automatic assignment for people joining an organization.	true
Role catalogue / assign_automatically_to_first_contact	Requests assignment for the first eligible person; evaluation remains deterministic system work.	false
Affiliation type / id	Stable classification identity for a relationship.	employee
Affiliation type / name	Staff-facing classification name.	Employee
Affiliation type / description	Optional explanation of this kind of tie.	Works for the association member
Affiliation type / is_active	Availability for new selection, without invalidating retained references.	true
Information default / kind	Address or phone mapping kind.	address
Information default / source type	Organization purpose supplying the default.	headquarters
Information default / destination type	Compatible contact purpose receiving the link.	work

Relationships

Many affiliations belong to one contact, and many can name one organization. The contact is the write owner, so editing a tie requires contact update authority and the contact’s read version. The organization reference remains fixed for an existing affiliation; a later employer is a different connection.

Archiving either record preserves the tie and historical context. Deleting the contact cascades affiliation and role rows; organization deletion is blocked while the tie exists. Removing a tie through an explicit contact list also requires settling any contact detail still linked through it. Locks and revisions operate through the owning contact rather than an independent relationship edit version.

Lifecycle

The affiliation lifecycle derives upcoming, current and past from inclusive calendar dates in the workspace timezone. Primary is an additional designation available to an effective open-ended tie. Passing a boundary changes read interpretation without requiring a midnight write to the relationship itself.

Pending automatic roles and default links are separate work. An effective affiliation can still await that work because of locks, bounded passes or a disabled reconciliation path. The lifecycle model distinguishes those effects from the calendar classification, and ending the primary tie does not silently nominate another one.

Invariants

The affiliation preserves the identity of one tie between a person and an organization. Reusing an existing role-period identity means editing that episode; inventing an identity cannot move another affiliation’s responsibility into this tie. The organization reference remains fixed after creation, so changing employers creates distinct relationship context rather than rewriting an old employer into a new one.

The primary designation coordinates prominent organizational context with the person’s title. Effective dates and the open-ended primary requirement prevent a future or ended relationship from being presented as the person’s current primary employer. A secondary effective tie can still contribute people to organization rosters and compliance. Primary prominence is therefore separate from whether the relationship counts today.

Role policy and date validation keep responsibility periods interpretable. Automatic assignment uses saved pending state and eligible definitions; it does not turn a role label into a security grant. Contact ownership and version comparison make these nested changes part of one guarded save. Staff working from an organization page still change the person’s relationship aggregate, and organization update permission does not substitute for authority to edit the contact.

Permissions

The CRM authorization model separates workspace access from permission for a particular action.

The service checks these grants at the corresponding operation boundary. Additional record guards still apply: grants do not bypass archive, customer restrictions, dependencies, version comparison or Rhythm protection. An organization-page relationship action changes the contact, so organization update authority alone is insufficient.

How It Is Stored and Shared

Affiliation and role-period rows remain part of contact persistence. Current and query views expose effective organizational membership without reducing it to the primary label. The primary tie supplies the contact’s organizational subtitle and coordinates its title; secondary effective ties still contribute to applicable people discovery and role compliance.

Type and role catalogues are maintained through the configuration service hosted by CRM. They do not acquire custom-field storage simply because contact and organization records have it. Relationship changes capture a contact event, while organization compliance is normally reevaluated after commit.

Open Design Questions

The observed aggregate-save route for ending and removal still differs from the explicit-operation requirement recorded by Platform. Save-time role eligibility, scheduled assignment and the default-link backlog also have existing findings. This design preserves their evidence and does not turn the present implementation into an approved replacement contract.