# Contact Person Management

## Overview

Contact Person Management enables organizations to track individual people who represent a business partner organization. Each contact person is a sub-entity linked to exactly one ORGANIZATION-type partner — they are not business partners themselves, but named individuals who act on behalf of that organization. Contact persons carry their own identifying information (name, and at least one of email or phone, plus optional job title and department) and maintain an independent ACTIVE/INACTIVE status.

One contact person per organization can be designated as the primary contact, providing a single point of first contact for that partner relationship.

## Business Purpose

Business interactions with partner organizations are typically conducted through specific individuals. Tracking contact persons enables:

- **Named communication**: Sales, procurement, and support teams can reach the right person at a partner organization rather than relying on generic email addresses or phone numbers
- **Role clarity**: Job title and department fields identify who is responsible for purchasing, accounts payable, technical escalation, and other functional areas
- **Primary contact designation**: Each organization has one primary contact, reducing ambiguity about who to contact first for general enquiries
- **Status tracking**: Contacts who leave or change roles can be marked INACTIVE without losing historical records tied to past transactions or communications
- **CRM alignment**: Mirrors industry-standard models (SAP BP relationships, Odoo child contacts, Salesforce Contact-Account) for interoperability and familiarity

## Process Flow

The relationship between a partner organization and its contact persons:

```mermaid
flowchart TD
    A[ORGANIZATION-type Partner] -->|has zero or more| B[Contact Person]
    B --> C{Is primary contact?}
    C -->|Yes| D[Designated as primary contact\nfor the organization]
    C -->|No| E[Regular contact person]
    D -->|another contact promoted| F[Primary designation transferred]
```

Contact person lifecycle:

```mermaid
stateDiagram-v2
    [*] --> Active: createContactPerson
    Active --> Inactive: deactivateContactPerson
    Inactive --> Active: reactivateContactPerson
    Active --> [*]: deleteContactPerson (only when not primary)
```

## Scenario Patterns

- **New supplier onboarding**: When a new supplier partner is registered, the procurement team adds the account manager's name, email, and phone as a contact person and marks them as primary contact
- **Multiple contacts per organization**: A customer organization has separate contacts for accounts payable and technical support — both are recorded with distinct job titles and departments
- **Primary contact change**: The existing primary contact leaves the organization; their record is marked INACTIVE, and a newly added colleague is designated as the primary contact
- **Contact details update**: A contact person's phone number or job title changes; the record is updated without affecting their link to the parent organization or their primary status
- **Departed contact retention**: A contact person who has left the partner organization is deactivated rather than deleted, preserving references in historical correspondence and past transactions
- **Organization type enforcement**: Attempting to link a contact person to an INDIVIDUAL-type partner is rejected; contact persons may only belong to ORGANIZATION-type partners

## Test Cases

- A contact person can only be linked to an ORGANIZATION-type partner; linking to an INDIVIDUAL-type partner must be rejected
- Contact person fields firstName and lastName are required; email, phone, jobTitle, and department are optional. At least one communication channel (email or phone) must be provided
- Email format must be validated on creation and update
- A contact person is created with ACTIVE status by default
- An ACTIVE contact person can be deactivated; an INACTIVE contact person can be reactivated
- At most one contact person per organization may hold primary contact designation at any given time
- Designating a new primary contact automatically removes the designation from the previous primary contact
- A contact person marked as primary cannot be deleted; the primary designation must be transferred first
- Deactivating a primary contact person removes their primary designation; the organization has no primary contact until one is explicitly set
- Multiple contact persons with distinct roles may exist under the same organization
- Updating a contact person's details does not change their organization association or primary status
- Listing contact persons for an organization returns only those linked to that specific organization

## Reference Links

- [SAP Business Partner Relationships](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/7b24a64d9d0941bda1afa753263d9e39/4e4dece7db1b59cde10000000a42189b.html)
- [Odoo Contacts as Child Partners](https://www.odoo.com/documentation/19.0/applications/general/contacts.html)
- [Salesforce Contact Object](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_contact.htm)
