GetUserDocumentByIdQuery

Overview

The GetUserDocumentByIdQuery retrieves a single user document with its full content (base64 data) for download. Use this query when you need to download or display a specific user document.

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

Use Cases

Download document for viewing
Export document to local file system
Display document in PDF viewer
Print document
Forward document via email

Key Difference from GetUserDocumentsQuery

Query	Returns Data	Use Case
GetUserDocumentsQuery	❌ No	List documents (fast)
GetUserDocumentByIdQuery	✅ Yes	Download single document

Request Parameters

Required Parameters

Parameter	Type	Description
`selfServiceUserId`	long	The ID of the SelfService user
`documentId`	string (GUID)	The unique identifier of the document

Request Example

{
  "cmd": "GetUserDocumentByIdQuery",
  "data": {
    "selfServiceUserId": 250,
    "documentId": "b2c3d4e5-f6g7-8901-bcde-f12345678901"
  }
}

Response Format

Success Response

{
  "statusCode": "00",
  "statusMessage": "SUCCESS",
  "data": {
    "documentId": "b2c3d4e5-f6g7-8901-bcde-f12345678901",
    "documentName": "Passport.pdf",
    "documentType": 2,
    "documentTypeName": "INTERNATIONAL_PASSPORT",
    "description": "International passport - bio page",
    "documentNumber": "A12345678",
    "documentExpiry": "2030-12-31T00:00:00Z",
    "documentIssueDate": "2020-06-15T00:00:00Z",
    "documentIssuer": "Immigration Service",
    "documentData": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL...",
    "createdDate": "2026-01-12T11:30:00Z",
    "createdBy": {
      "userId": 250,
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "jane.smith@example.com"
    }
  }
}

Error Responses

Document Not Found:

{
  "statusCode": "01",
  "statusMessage": "Document not found for the specified user",
  "data": null
}

Invalid GUID Format:

{
  "statusCode": "01",
  "statusMessage": "Invalid documentId format",
  "data": null
}

User Not Found:

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

Response Fields

Field	Type	Description
`documentId`	string (GUID)	Unique identifier
`documentName`	string	File name
`documentType`	int	Document type enum
`documentTypeName`	string	Type name
`description`	string	Description
`documentNumber`	string	Official number
`documentExpiry`	DateTime	Expiration date
`documentIssueDate`	DateTime	Issue date
`documentIssuer`	string	Issuer
`documentData`	string	Base64 encoded file content ✅
`createdDate`	DateTime	Upload timestamp
`createdBy`	object	Uploader details

JavaScript Usage Example

Download Document

const downloadUserDocument = async (userId, documentId) => {
  try {
    const result = await api.query({
      cmd: "GetUserDocumentByIdQuery",
      data: JSON.stringify({
        selfServiceUserId: userId,
        documentId: documentId
      })
    });
    
    if (result.statusCode === "00") {
      const doc = result.data;
      
      // Convert base64 to blob
      const blob = base64ToBlob(doc.documentData, getMimeType(doc.documentName));
      
      // Create download link
      const url = URL.createObjectURL(blob);
      const a = document.createElement('a');
      a.href = url;
      a.download = doc.documentName;
      document.body.appendChild(a);
      a.click();
      document.body.removeChild(a);
      
      // Clean up
      URL.revokeObjectURL(url);
      
      console.log("Document downloaded:", doc.documentName);
    } else {
      alert(`Error: ${result.statusMessage}`);
    }
  } catch (error) {
    console.error("Download failed:", error);
    alert("Failed to download document");
  }
};

// Helper function to convert base64 to blob
const base64ToBlob = (base64, mimeType = 'application/octet-stream') => {
  const byteCharacters = atob(base64);
  const byteNumbers = new Array(byteCharacters.length);
  
  for (let i = 0; i < byteCharacters.length; i++) {
    byteNumbers[i] = byteCharacters.charCodeAt(i);
  }
  
  const byteArray = new Uint8Array(byteNumbers);
  return new Blob([byteArray], { type: mimeType });
};

// Helper function to get MIME type from filename
const getMimeType = (filename) => {
  const ext = filename.split('.').pop().toLowerCase();
  const mimeTypes = {
    'pdf': 'application/pdf',
    'jpg': 'image/jpeg',
    'jpeg': 'image/jpeg',
    'png': 'image/png',
    'doc': 'application/msword',
    'docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
    'xls': 'application/vnd.ms-excel',
    'xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
  };
  return mimeTypes[ext] || 'application/octet-stream';
};

Display PDF in Browser

const displayUserPdfInViewer = async (userId, documentId) => {
  try {
    const result = await api.query({
      cmd: "GetUserDocumentByIdQuery",
      data: JSON.stringify({ selfServiceUserId: userId, documentId })
    });
    
    if (result.statusCode === "00") {
      const doc = result.data;
      
      // Convert to blob URL
      const blob = base64ToBlob(doc.documentData, 'application/pdf');
      const url = URL.createObjectURL(blob);
      
      // Display in iframe
      const iframe = document.getElementById('pdfViewer');
      iframe.src = url;
      
      // Or open in new tab
      // window.open(url, '_blank');
      
    }
  } catch (error) {
    console.error("Display failed:", error);
  }
};

Display Image Preview

const showUserImagePreview = async (userId, documentId) => {
  try {
    const result = await api.query({
      cmd: "GetUserDocumentByIdQuery",
      data: JSON.stringify({ selfServiceUserId: userId, documentId })
    });
    
    if (result.statusCode === "00") {
      const doc = result.data;
      
      // Create data URL
      const mimeType = getMimeType(doc.documentName);
      const dataUrl = `data:${mimeType};base64,${doc.documentData}`;
      
      // Display in image element
      const img = document.getElementById('documentPreview');
      img.src = dataUrl;
      img.alt = doc.documentName;
    }
  } catch (error) {
    console.error("Preview failed:", error);
  }
};

Complete Download Component

class UserDocumentDownloader {
  constructor(userId) {
    this.userId = userId;
  }
  
  async download(documentId, documentName = null) {
    try {
      // Show loading indicator
      this.showLoading(true);
      
      const result = await api.query({
        cmd: "GetUserDocumentByIdQuery",
        data: JSON.stringify({
          selfServiceUserId: this.userId,
          documentId: documentId
        })
      });
      
      this.showLoading(false);
      
      if (result.statusCode === "00") {
        const doc = result.data;
        this.triggerDownload(
          doc.documentData, 
          documentName || doc.documentName
        );
        return true;
      } else {
        this.showError(result.statusMessage);
        return false;
      }
    } catch (error) {
      this.showLoading(false);
      this.showError("Network error: " + error.message);
      return false;
    }
  }
  
  triggerDownload(base64Data, filename) {
    const blob = this.base64ToBlob(base64Data, this.getMimeType(filename));
    const url = URL.createObjectURL(blob);
    
    const a = document.createElement('a');
    a.style.display = 'none';
    a.href = url;
    a.download = filename;
    
    document.body.appendChild(a);
    a.click();
    
    // Cleanup
    setTimeout(() => {
      document.body.removeChild(a);
      URL.revokeObjectURL(url);
    }, 100);
  }
  
  base64ToBlob(base64, mimeType = 'application/octet-stream') {
    const byteCharacters = atob(base64);
    const byteArray = new Uint8Array(byteCharacters.length);
    
    for (let i = 0; i < byteCharacters.length; i++) {
      byteArray[i] = byteCharacters.charCodeAt(i);
    }
    
    return new Blob([byteArray], { type: mimeType });
  }
  
  getMimeType(filename) {
    const ext = filename.split('.').pop().toLowerCase();
    const types = {
      'pdf': 'application/pdf',
      'jpg': 'image/jpeg',
      'jpeg': 'image/jpeg',
      'png': 'image/png',
      'gif': 'image/gif',
      'doc': 'application/msword',
      'docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
    };
    return types[ext] || 'application/octet-stream';
  }
  
  showLoading(show) {
    const spinner = document.getElementById('downloadSpinner');
    if (spinner) {
      spinner.style.display = show ? 'block' : 'none';
    }
  }
  
  showError(message) {
    alert(`Download Error: ${message}`);
  }
}

// Usage
const downloader = new UserDocumentDownloader(250);

// In your button click handler
document.getElementById('downloadBtn').addEventListener('click', () => {
  const documentId = "b2c3d4e5-f6g7-8901-bcde-f12345678901";
  downloader.download(documentId);
});

Validation Rules

selfServiceUserId: Must exist in database
documentId: Must be valid GUID format
Document Association: Document must be associated with the specified user

Error Codes

Status Code	Description
00	Success - document retrieved with data
01	Document not found
01	Invalid GUID format
01	User not found
99	General error

Performance Considerations

File Size: Larger files take longer to retrieve and transfer
Base64 Overhead: ~33% larger than original file
Network: Consider compression for large documents
Caching: Cache document metadata, fetch data only when needed

Security Notes

Validate user has permission to access their own documents
Validate user has permission to download documents
Log all document downloads for audit
Consider implementing download limits/throttling
Scan downloaded files for viruses (client-side)

GetUserDocumentsQuery - List all documents (without data)
CreateUserDocumentCommand - Upload new document
GetLoanQuoteDocumentByIdQuery - Download loan quote documents

Testing Checklist

Browser Compatibility

The download implementation uses:

Blob API (IE 10 and above, all modern browsers)
URL.createObjectURL() (IE 10 and above, all modern browsers)
atob() for base64 decoding (IE 10 and above, all modern browsers)

For older browsers, consider using a polyfill like js-base64.

Overview​

Use Cases​

Key Difference from GetUserDocumentsQuery​

Request Parameters​

Required Parameters​

Request Example​

Response Format​

Success Response​

Error Responses​

Response Fields​

JavaScript Usage Example​

Download Document​

Display PDF in Browser​

Display Image Preview​

Complete Download Component​

Validation Rules​

Error Codes​

Performance Considerations​

Security Notes​

Related Commands​

Testing Checklist​

Browser Compatibility​