Business Role Behaviors

The Business Role (REF::BR) sub-domain manages the role assignments attached to a Business Affiliate. A BusinessRole entity captures a named function that an affiliate performs in the business relationship: VENDOR, CUSTOMER, CARRIER, OPERATOR, or OTHER. An affiliate can hold multiple roles simultaneously, and each role can be added or removed independently over time without affecting the affiliate’s core record. Business Roles enable role-based filtering throughout the system — for example, the AffiliateTypeahead in the Item Supply form filters affiliates by the VENDOR role to ensure only supplier-capable partners appear in the results.

Business Roles implement the GEN::ENTSUB subordinate entity contract. This document parallels the Item Supply Behaviors in the Reference Data taxonomy: Business Roles are the subordinate entity of Business Affiliates, just as Item Supplies are the subordinate entity of Items.

---

REF::BR::0001 — View Business Roles

The Purchasing Manager inspects all roles assigned to a given Business Affiliate from within the Supplier Details Panel.

Persona	David Dealsworth (Purchasing Manager)
Implements	GEN::ENTSUB::0001
Depends	REF::BA::0002
Status	Proposed
Priority	Undefined

REF::BR::0001::0001.UC — View Roles in Supplier Details Panel

Priority: Undefined

Specializes GEN::ENTSUB::0001::0001. The Roles tab displays role cards with:

• Role type as a colored badge (VENDOR in blue, CARRIER in green, CUSTOMER in orange)
• Role name
• Notes (if provided)
• Action buttons: Edit, Remove

The system fetches roles via GET /api/arda/suppliers/{eId}/roles. Empty state: “No roles assigned. Add a role to define this affiliate’s function.”

Postcondition: The user sees all roles currently held by the affiliate with their type, name, and notes.

REF::BR::0001::0002.UC — View Role Details

Priority: Undefined

Specializes GEN::ENTSUB::0001::0002. An expanded view or tooltip shows creation date, last modified date, and the complete notes field.

Postcondition: The user has visibility into the full metadata for a specific role assignment.

---

REF::BR::0002 — Add and Edit Business Roles

The Purchasing Manager adds new roles to a Business Affiliate or updates the details of an existing role assignment.

Persona	David Dealsworth (Purchasing Manager)
Implements	GEN::ENTSUB::0002, GEN::ENTSUB::0003
Depends	REF::BR::0001
Status	Proposed
Priority	Undefined

REF::BR::0002::0001.UC — Add Role to Affiliate

Priority: Undefined

Specializes GEN::ENTSUB::0002::0001. The user clicks ”+ Add Role.” Form fields:

• Role Type (required): dropdown with VENDOR, CUSTOMER, CARRIER, OPERATOR, OTHER
• Role Name (required): auto-populated from the role type, editable
• Notes (optional): free text

Save calls POST /api/arda/suppliers/{eId}/roles. The corresponding colored badge also appears on the affiliate’s row in the main suppliers grid.

Postcondition: A new BusinessRole entity is created for the affiliate.

REF::BR::0002::0002.UC — Add Role with Create-on-the-Fly (from Item Supply Form)

Priority: Undefined

Specializes GEN::ENTSUB::0002::0002. When a new Business Affiliate is created via the ”[+] New supplier” typeahead option in the ItemSupplyFormDialog, the system automatically assigns the VENDOR role based on the creation context. The user does not need to explicitly select the role.

Postcondition: A new Business Affiliate is created with the VENDOR role pre-assigned. See also: Inline Supply Creation.

REF::BR::0002::0003.UC — Edit Role

Priority: Undefined

Specializes GEN::ENTSUB::0003::0001. The user clicks Edit on a role card. The form opens pre-filled. The user modifies name or notes and clicks Save. The system calls PUT /api/arda/suppliers/{eId}/roles/{roleEId}.

Postcondition: The BusinessRole entity is updated with the new values.

---

REF::BR::0003 — Remove Business Roles

The Purchasing Manager removes a role assignment that is no longer valid. Removing a role does not delete the affiliate itself.

Persona	David Dealsworth (Purchasing Manager)
Implements	GEN::ENTSUB::0004
Depends	REF::BR::0001
Status	Proposed
Priority	Undefined

REF::BR::0003::0001.UC — Remove a Role from Affiliate

Priority: Undefined

Specializes GEN::ENTSUB::0004::0001. Confirmation dialog: “Remove the [ROLE_TYPE] role from [affiliate name]?” On confirm, DELETE /api/arda/suppliers/{eId}/roles/{roleEId}.

If this was the affiliate’s only role, an additional note: “This affiliate has no remaining roles.” The affiliate is not deleted; it remains as an untyped partner record.

Postcondition: The specified role is removed. The affiliate retains its remaining roles (if any).

REF::BR::0003::0002.UC — Remove VENDOR Role with Item Supply Warning

Priority: Undefined

Specializes GEN::ENTSUB::0004::0002. When the role type is VENDOR and the affiliate is referenced by Item Supply records, the dialog warns: “This affiliate is referenced as a vendor by N item supply records. Removing the VENDOR role will not unlink the supplies, but the affiliate will no longer appear in vendor-filtered searches.”

On “Remove Anyway,” the role is deleted. The VENDOR badge disappears. Existing ItemSupply records referencing this affiliate via supplierEId remain intact, but the affiliate is excluded from AffiliateTypeahead queries filtered to the VENDOR role.

Postcondition: The VENDOR role is removed. Item Supply linkages are preserved but the affiliate is excluded from vendor-filtered lookups.

---

REF::BR::0004 — View Affiliates by Role

The Purchasing Manager views all Business Affiliates that hold a specific role, enabling cross-referencing between roles and their member organizations.

Persona	David Dealsworth (Purchasing Manager)
Implements	GEN::ENTSUB::0005
Depends	REF::BA::0001
Status	Proposed
Priority	Undefined

REF::BR::0004::0001.UC — Filter Suppliers Grid by Role Type

Priority: Undefined

Specializes GEN::ENTSUB::0005::0001. From the Suppliers page, the user selects a role type filter (for example, VENDOR). The system queries GET /api/arda/suppliers/lookup?role=VENDOR. The filter is combinable with name search.

Postcondition: The grid displays only affiliates holding the selected role, optionally narrowed by name search.

REF::BR::0004::0002.UC — Role Filter with No Results

Priority: Undefined

Specializes GEN::ENTSUB::0005::0002. Empty state: “No suppliers found with the [ROLE_TYPE] role.” Call-to-action: “Add a supplier with this role.”

Postcondition: The user receives a clear empty-state message with guidance rather than a blank or errored view.

---

Summary

Use Case	Scenarios	UC
REF::BR::0001 View Business Roles	2	2
REF::BR::0002 Add and Edit Business Roles	3	3
REF::BR::0003 Remove Business Roles	2	2
REF::BR::0004 View Affiliates by Role	2	2
Total	9	9

---