Unions - Millenium Potters

What are Unions?

Unions are organizational groups that contain union members who share a common identity, location, or are managed by the same credit officer. Every union is assigned to a specific credit officer who manages its members and loan operations.

Unions must be created before adding members. Each union is tied to one credit officer.

Union Data Model

Based on the Prisma schema, the Union model contains:

model Union {
  id              String   @id @default(cuid())
  name            String
  location        String?
  address         String?
  creditOfficerId String   // Required: Credit Officer assignment
  
  // Relations
  creditOfficer   User     @relation("OfficerUnions")
  unionMembers    UnionMember[]
  loans           Loan[]
  
  createdAt DateTime  @default(now())
  updatedAt DateTime  @updatedAt
  deletedAt DateTime? // Soft delete support
}

Key Fields

Field	Type	Required	Description
`id`	String	Yes	Unique identifier (auto-generated)
`name`	String	Yes	Union name (must be unique)
`location`	String	No	Geographic location or area
`address`	String	No	Physical address details
`creditOfficerId`	String	Yes	Assigned credit officer ID
`deletedAt`	DateTime	No	Soft delete timestamp

Viewing All Unions

Access the unions list from the sidebar:

Navigate

Click Business Management → Unions

View List

See all unions you have permission to access

List Features

Search

Type union name in the search box to filter results

Filter

Filter by credit officer or status (Active/Inactive)

Sort

Click column headers to sort by name, officer, or date

Export

Download union list as CSV or Excel

Role-Based Access

Administrator

Can view and manage all unions in the system

Supervisor

Can view unions assigned to credit officers under their supervision

Credit Officer

Can only view and manage their own assigned unions

Creating a New Union

Start Creation

Go to the Unions page and click + Add Union button (top right)

Fill Required Fields

Required:

Union Name - Enter a unique, descriptive name
Credit Officer - Select the officer who will manage this union

Optional:

Location - Geographic area or region
Address - Physical address or meeting place

Save

Click Create Union to save

Field Guidelines

Union Name Best Practices:

Use clear, descriptive names (e.g., “Market Women Group”, “Potters Association Zone A”)
Avoid duplicate names
Include location if helpful (e.g., “Lagos Traders Union”)

API Endpoint

// POST /api/unions
const createUnion = async (data: {
  name: string;
  creditOfficerId: string;
  location?: string;
  address?: string;
}) => {
  // Creates new union and assigns to officer
}

Viewing Union Details

Click any union in the list to view:

Basic Information

Union name
Location and address
Assigned credit officer
Creation date

Member Statistics

Total members count
Active members
Recent additions

Loan Portfolio

Total loans issued
Active loans
Outstanding balance

Performance

Collection rate
Overdue loans
Repayment trends

Editing a Union

Only Administrators and Supervisors can edit union details

Find Union

Locate the union in the list

Open Editor

Click the Edit icon (pencil) in the Actions column

Update Fields

Modify the information as needed:

Change name
Update location/address
Reassign credit officer (see below)

Save Changes

Click Save Changes to update

Reassigning Credit Officers

When reassigning a union to a different officer, all members automatically move with the union

Reassignment Process

Access Reassignment

From union details or list, click Reassign Officer

Select New Officer

Choose the new credit officer from the dropdown

Add Reason

Provide a reason for the reassignment (optional but recommended)

Confirm

Review the changes and click Confirm Reassignment

What Happens During Reassignment?

Union’s creditOfficerId is updated to the new officer
Assignment history is recorded in UnionAssignmentHistory
All union members remain in the union
All loans stay connected to the union
New officer gains access to all union data

Assignment History Tracking

model UnionAssignmentHistory {
  id              String   @id
  unionId         String
  oldOfficerId    String?
  newOfficerId    String
  changedByUserId String
  reason          String?
  changedAt       DateTime @default(now())
}

View Assignment History

Each union details page shows a history log of all officer assignments with dates and reasons

Deleting a Union

You cannot delete a union that has:

Active members
Active or pending loans

Delete or reassign these first, or deactivate the union instead.

Soft Delete Process

Locate Union

Find the union in the list

Delete Action

Click the Delete icon (trash can) in the Actions column

Confirm Deletion

Review the confirmation popup and click Confirm

Unions are soft deleted (marked with deletedAt timestamp) rather than permanently removed, preserving historical data

Alternative: Deactivate

Instead of deleting:

Edit the union
Mark as inactive
This hides it from active lists while preserving data

Adding Members to a Union

See Members documentation for details on creating members within a union.

Creating Loans for Union Members

When creating a loan:

Select the union first
Then select a member from that union
The loan is automatically associated with both

See Loans documentation for complete workflow.

Search and Filters

Search Bar

The search function looks for matches in union name and location fields

// Search example
searchTerm: "market" 
// Finds: "Market Women Group", "New Market Traders", etc.

Filter by Credit Officer

Open Filter

Click the filter dropdown

Select Officer

Choose a credit officer from the list

Apply

View only unions assigned to that officer

Filter by Status

Active - Shows all active unions
Inactive - Shows deactivated unions
All - Shows both active and inactive

Export Options

CSV Export

Download as comma-separated valuesBest for Excel or Google Sheets

Excel Export

Download as .xlsx fileIncludes formatting and headers

Copy to Clipboard

Copy data for pasting elsewhereQuick data sharing

Export Includes

Union name
Location and address
Assigned credit officer name
Member count
Loan statistics
Creation date

Best Practices

Naming Conventions

Use consistent naming patterns
Include location if managing multiple areas
Avoid abbreviations that aren’t clear
Example: “Ikeja Market Women Union” not “IMW”

Officer Assignment

Assign unions to officers familiar with the area
Balance workload across officers
Consider geographic proximity
Document reassignment reasons

Data Management

Keep location and address updated
Review inactive unions periodically
Archive old unions instead of deleting
Maintain assignment history

Performance Monitoring

Track union-level metrics
Compare performance across unions
Identify high-performing groups
Address struggling unions proactively

Troubleshooting

Cannot create union

Possible causes:

Union name already exists
Credit officer not selected
Insufficient permissions (not Admin/Supervisor)

Solution: Check name uniqueness and verify required fields

Cannot delete union

Reason: Union has active members or loansSolution:

Reassign members to other unions
Close or cancel all loans
Or mark union as inactive instead

Cannot see all unions

Reason: Role-based access restrictionsExplanation:

Credit Officers only see their assigned unions
Supervisors see unions of their team
Only Admins see all unions

Reassignment not working

Check:

You have Admin or Supervisor role
New officer exists and is active
You provided required information

API Reference

Endpoints

// Get all unions
GET /api/unions?page=1&limit=20&search=keyword&creditOfficerId=xxx

// Get union by ID
GET /api/unions/:id

// Create union
POST /api/unions
Body: { name, creditOfficerId, location?, address? }

// Update union
PUT /api/unions/:id
Body: { name?, location?, address?, creditOfficerId? }

// Delete union (soft)
DELETE /api/unions/:id

// Reassign officer
POST /api/unions/:unionId/assign
Body: { creditOfficerId, reason? }

// Export unions
GET /api/unions/export?creditOfficerId=xxx&search=keyword

Summary

Unions provide:

✅ Organizational structure for members
✅ Credit officer assignment and management
✅ Loan portfolio grouping
✅ Performance tracking by group
✅ Assignment history and audit trail
✅ Role-based access control

Next Steps

Add Members to your unions
Create Loans for union members
Monitor Reporting by union

Get Started

Core Features

User Roles

Guides

​What are Unions?

​Union Data Model

​Key Fields

​Viewing All Unions

​List Features

Search

Filter

Sort

Export

​Role-Based Access

​Creating a New Union

​Field Guidelines

​API Endpoint

​Viewing Union Details

Basic Information

Member Statistics

Loan Portfolio

Performance

​Editing a Union

​Reassigning Credit Officers

​Reassignment Process

​What Happens During Reassignment?

​Assignment History Tracking

​Deleting a Union

​Soft Delete Process

​Alternative: Deactivate

​Union-Related Operations

​Adding Members to a Union

​Creating Loans for Union Members

​Search and Filters

​Search Bar

​Filter by Credit Officer

​Filter by Status

​Export Options

CSV Export

Excel Export

Copy to Clipboard

​Export Includes

​Best Practices

Naming Conventions

Officer Assignment

Data Management

Performance Monitoring

​Troubleshooting

​API Reference

​Endpoints

​Summary

Next Steps

Build docs developers (and LLMs) love

What are Unions?

Union Data Model

Key Fields

Viewing All Unions

List Features

Role-Based Access

Creating a New Union

Field Guidelines

API Endpoint

Viewing Union Details

Editing a Union

Reassigning Credit Officers

Reassignment Process

What Happens During Reassignment?

Assignment History Tracking

Deleting a Union

Soft Delete Process

Alternative: Deactivate

Union-Related Operations

Adding Members to a Union

Creating Loans for Union Members

Search and Filters

Search Bar

Filter by Credit Officer

Filter by Status

Export Options

Export Includes

Best Practices

Troubleshooting

API Reference

Endpoints

Summary