CreateUserDocumentCommand

Overview

The CreateUserDocumentCommand allows you to upload and associate documents with SelfService users. This is essential for capturing required user documentation such as identification, financial statements, and supporting materials.

Handler File: CB.Administration.Api/Commands/BPM/SelfService/DocumentManagementCommand.cs

Use Cases

• Upload customer identification documents (ID cards, passports, driver's license)
• Attach financial documents (bank statements, tax clearance)
• Store business documents (company registration, certificates)
• Upload supporting materials (utility bills, photographs)
• Maintain document trail for compliance and audit

Request Parameters

Required Parameters

Parameter	Type	Description
selfServiceUserId	long	The ID of the SelfService user to attach document to
documentName	string	Display name of the document (e.g., "National ID Card.pdf")
documentType	int	Document type enum value (see Document Types below)
documentData	string	Base64-encoded document content

Optional Parameters

Parameter	Type	Description
description	string	Additional description or notes about the document
documentNumber	string	Official document number (e.g., ID card number)
documentExpiry	DateTime	Document expiration date (for IDs, licenses)
documentIssueDate	DateTime	Date the document was issued
documentIssuer	string	Organization that issued the document

Document Types

Value	Type	Description
1	NATIONAL_ID	National ID card
2	INTERNATIONAL_PASSPORT	Passport
3	DRIVERS_LICENCE	Driver's license
4	UTILITY_BILL	Utility bill for address verification
5	BANK_STATEMENT	Bank statement
6	COMPANY_REGISTRATION	Company registration certificate
7	TAX_CLEARANCE	Tax clearance certificate
8	CERTIFICATE_OF_INCORPORATION	Certificate of incorporation
14	PHOTOGRAPH	Customer photograph
15	UNIVERSITY_CERTIFICATE	Educational certificate
16	BIRTH_CERTIFICATE	Birth certificate

Request Examples

Example 1: Passport (with all optional fields)

{
  "cmd": "CreateUserDocumentCommand",
  "data": {
    "selfServiceUserId": 250,
    "documentName": "Passport.pdf",
    "documentType": 2,
    "documentData": "JVBERi0xLjQKJeLjz9MK...",
    "description": "International passport - bio page",
    "documentNumber": "A12345678",
    "documentExpiry": "2030-12-31T00:00:00Z",
    "documentIssueDate": "2020-06-15T00:00:00Z",
    "documentIssuer": "Immigration Service"
  }
}

Example 2: Photograph (minimal fields only)

{
  "cmd": "CreateUserDocumentCommand",
  "data": {
    "selfServiceUserId": 250,
    "documentName": "Profile Photo.jpg",
    "documentType": 14,
    "documentData": "iVBORw0KGgoAAAANSUhEU...",
    "description": "Customer profile photograph"
  }
}

Example 3: Company Registration

{
  "cmd": "CreateUserDocumentCommand",
  "data": {
    "selfServiceUserId": 250,
    "documentName": "CAC Certificate.pdf",
    "documentType": 6,
    "documentData": "JVBERi0xLjQKJeLjz9MK...",
    "description": "Corporate Affairs Commission certificate",
    "documentNumber": "RC123456",
    "documentIssueDate": "2019-03-20T00:00:00Z",
    "documentIssuer": "Corporate Affairs Commission"
  }
}

Response Format

Success Response

{
  "statusCode": "00",
  "statusMessage": "SUCCESS",
  "data": {
    "documentId": "b2c3d4e5-f6g7-8901-bcde-f12345678901",
    "documentName": "Passport.pdf",
    "documentType": 2,
    "associationId": 78,
    "selfServiceUserId": 250,
    "createdDate": "2026-01-12T11:30:00Z"
  }
}

Error Response

{
  "statusCode": "01",
  "statusMessage": "User with ID 999 not found",
  "data": null
}

JavaScript Usage Example

// Convert file to base64
const convertFileToBase64 = (file) => {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => resolve(reader.result.split(',')[1]);
    reader.onerror = reject;
    reader.readAsDataURL(file);
  });
};

// Upload user document
const uploadUserDocument = async (userId, file, documentType) => {
  try {
    const base64Data = await convertFileToBase64(file);
    
    const result = await api.query({
      cmd: "CreateUserDocumentCommand",
      data: JSON.stringify({
        selfServiceUserId: userId,
        documentName: file.name,
        documentType: documentType,
        documentData: base64Data,
        description: `Uploaded on ${new Date().toLocaleDateString()}`
      })
    });
    
    if (result.statusCode === "00") {
      console.log("Document uploaded:", result.data.documentId);
      return result.data;
    } else {
      console.error("Upload failed:", result.statusMessage);
      return null;
    }
  } catch (error) {
    console.error("Error uploading document:", error);
    return null;
  }
};

// Example usage
const fileInput = document.getElementById('userDocumentFile');
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  if (file) {
    await uploadUserDocument(250, file, 2); // Upload as INTERNATIONAL_PASSPORT
  }
});

Validation Rules

• selfServiceUserId: Must reference an existing SelfService user
• documentName: Cannot be empty
• documentType: Must be valid enum value (1-23)
• documentData: Must be valid base64 string
• File Size: Consider implementing size limits (e.g., 10MB max)

Optional Fields Usage Guide

Different document types require different metadata. Here's when to use optional fields:

Identity Documents ✅ Use all optional fields

• NATIONAL_ID (1) - documentNumber, documentExpiry, documentIssueDate, documentIssuer
• INTERNATIONAL_PASSPORT (2) - documentNumber, documentExpiry, documentIssueDate, documentIssuer
• DRIVERS_LICENCE (3) - documentNumber, documentExpiry, documentIssueDate, documentIssuer

Financial Documents ⚠️ Limited metadata

• BANK_STATEMENT (5) - Only description
• TAX_CLEARANCE (7) - documentNumber, documentIssueDate (optional)
• SALARY_SLIP (9) - Only description

Supporting Documents ℹ️ Minimal metadata

• UTILITY_BILL (4) - Only description
• PHOTOGRAPH (14) - Only description
• SIGNATURE (18) - Only description

Business Documents 📄 Registration info

• COMPANY_REGISTRATION (6) - documentNumber, documentIssueDate, documentIssuer
• CERTIFICATE_OF_INCORPORATION (8) - documentNumber, documentIssueDate

Best Practice: Only send optional fields that are relevant to the document type. All optional fields accept null/empty values.

Error Codes

Status Code	Description
00	Success - document created
01	User not found
01	Validation error (missing required fields)
99	General error (see statusMessage for details)

Business Rules

1. Document Association: Documents are linked to users via the SelfServiceDocumentAssociation table
2. Unique Identifier: Each document receives a unique GUID (documentId) for retrieval
3. Audit Trail: System automatically records creation timestamp and user
4. Storage: Documents stored as base64 in database (consider MinIO for large volumes)

Related Commands

• GetUserDocumentsQuery - List all documents for a user
• GetUserDocumentByIdQuery - Download specific document
• CreateLoanQuoteDocumentCommand - Upload documents for loan quotes

Database Tables

• SelfServiceDocument ([BPMSelfServiceDocument].[dbo].[SelfServiceDocument])
• SelfServiceDocumentAssociation ([BPMSelfServiceDocument].[dbo].[SelfServiceDocumentAssociation])

Performance Considerations

• Base64 encoding increases file size by ~33%
• Large files (greater than 5MB) may impact API response time
• Consider client-side compression before upload
• For production, consider migrating to MinIO object storage

Security Notes

• Validate file types on client and server
• Implement virus scanning for uploaded files
• Restrict access based on user permissions
• Audit all document uploads
• Consider encryption for sensitive documents

Testing Checklist

• Upload PDF document
• Upload image document (JPEG, PNG)
• Test with invalid selfServiceUserId
• Test with missing documentData
• Test with invalid documentType
• Verify GUID generation
• Verify association record creation
• Test with large file (greater than 5MB)