Skip to main content

​
Overview

The Admin Module is the government-facing administrative panel for the CCDigital platform. It provides comprehensive control over citizen identity management, document review workflows, access governance, and blockchain synchronization operations.

Person Management

Create and manage citizen records with physical folder creation

Document Review

Approve or reject documents uploaded by issuers

Access Control

Manage user access states and sync with Indy credentials

Blockchain Sync

Synchronize data to Hyperledger Fabric and issue Indy credentials

​
Security & Authentication

Role Required: ROLE_GOBIERNO Access Path: /admin/** and /login/admin All administrative endpoints are protected by Spring Security and require government role authorization.

​
Key Features

​
Person Management

Create and manage citizen records in the system. Each person gets a physical folder on the filesystem for document storage.
The person creation workflow handled by PersonService#createPersonAndFolder:
  1. Validates person data (ID type, ID number, name, email, etc.)
  2. Persists person record to MySQL database
  3. Creates normalized folder structure in filesystem
  4. Returns the created person entity
Endpoint: POST /admin/personsController: AdminController (src/main/java/co/edu/unbosque/ccdigital/controller/AdminController.java:269)
Access comprehensive person information including:
  • Personal identification details
  • Associated documents with review status
  • User access state (if registered)
  • Document upload history
Endpoint: GET /admin/persons/{id}Controller: AdminController (src/main/java/co/edu/unbosque/ccdigital/controller/AdminController.java:292)

​
Document Management

Administrators can upload documents on behalf of citizens and review documents submitted by issuers.
1

Upload Document

Navigate to person details and use the upload form. Documents are stored in the person’s physical folder.Endpoint: POST /admin/persons/{id}/uploadDocuments enter PENDING review status by default.
2

Review Document

Review pending documents and update their status:
  • APPROVED - Document is valid and accessible
  • REJECTED - Document failed validation
  • PENDING - Awaiting review
Endpoint: Available through person detail view
3

Track Changes

All document state changes are logged to the audit trail and can be traced through blockchain integration.
Documents must be reviewed before they become available to end users or included in access requests.

​
Access State Control

Manage user access permissions with three-state control integrated with Hyperledger Indy for verifiable credential status updates. Available States:
  • ENABLED - User has full access to the system
  • SUSPENDED - Temporary access restriction
  • DISABLED - Permanent access revocation
Endpoint: POST /admin/persons/{id}/access-state Controller: AdminController (src/main/java/co/edu/unbosque/ccdigital/controller/AdminController.java:308) Indy Synchronization: When access state changes, the system attempts to synchronize the new state to the user’s Indy connection metadata via UserAccessGovernanceService. The result indicates:
  • Whether sync was attempted
  • Whether sync succeeded
  • Any error messages from the Indy integration
Access state changes affect user login capabilities. Suspended or disabled users cannot authenticate via Indy proof even with valid credentials.

​
Blockchain Synchronization

The admin module provides direct access to blockchain synchronization operations for both Hyperledger Fabric and Indy.

​
Fabric Synchronization

Synchronize the entire database to the Fabric ledger.Endpoint: POST /admin/sync/fabric/allController: AdminController (src/main/java/co/edu/unbosque/ccdigital/controller/AdminController.java:392)Service: ExternalToolsService#runFabricSyncAllScript: Calls Node.js script sync-db-to-ledger.js configured via environment variable FABRIC_SYNC_ALL_SCRIPT
Synchronize a specific person’s data to the Fabric ledger.Endpoint: POST /admin/sync/fabric/personController: AdminController (src/main/java/co/edu/unbosque/ccdigital/controller/AdminController.java:409)Service: ExternalToolsService#runFabricSyncPersonParameters: ID type and ID numberScript: Calls Node.js script configured via environment variable FABRIC_SYNC_PERSON_SCRIPT

​
Indy Credential Issuance

Issue Hyperledger Indy verifiable credentials to eligible users based on database records.Endpoint: POST /admin/sync/indy/issueController: AdminController (src/main/java/co/edu/unbosque/ccdigital/controller/AdminController.java:426)Service: ExternalToolsService#runIndyIssueFromDbScript: Calls Python script issue_credentials_from_db.py configured via environment variable INDY_SCRIPTThis operation:
  1. Queries eligible users from the database
  2. Establishes connection with Indy holder agent
  3. Issues credentials containing user attributes (id_type, id_number, name, email)
  4. Returns execution results including success/failure counts
Access Sync Page: GET /admin/sync Controller: AdminController (src/main/java/co/edu/unbosque/ccdigital/controller/AdminController.java:378)

​
Reports & Analytics

Generate comprehensive administrative reports with blockchain traceability. Endpoint: GET /admin/reports Controller: AdminController (src/main/java/co/edu/unbosque/ccdigital/controller/AdminController.java:123) Features:
  • Date range filtering (defaults to last 30 days)
  • Granularity selection (DAY/WEEK/MONTH)
  • Analytics view with trends and metrics
  • Blockchain traceability view with Fabric and Indy references
  • PDF export capability
Analytics Metrics:
  • Person creation trends
  • Document upload and review statistics
  • Access state distribution
  • System activity over time
Blockchain Traceability:
  • Fabric document references with block details
  • Indy proof exchange tracking
  • Full technical detail lookup via GET /admin/reports/block-detail
PDF Export:
  • Same filters as dashboard view
  • Generated via AdminReportPdfService
  • Endpoint: GET /admin/reports/pdf
  • Filename format: ccdigital-reporte-trazabilidad-{from}-{to}.pdf

​
Endpoint Reference

HTTP MethodEndpointDescriptionController Line
GET/admin/dashboardAdmin dashboard homeAdminController.java:103
GET/admin/personsList all personsAdminController.java:239
GET/admin/persons/newNew person formAdminController.java:253
POST/admin/personsCreate new personAdminController.java:269
GET/admin/persons/{id}Person detail viewAdminController.java:292
POST/admin/persons/{id}/uploadUpload document for personAdminController.java:354
POST/admin/persons/{id}/access-stateUpdate access stateAdminController.java:308
GET/admin/syncSync operations pageAdminController.java:378
POST/admin/sync/fabric/allSync all to FabricAdminController.java:392
POST/admin/sync/fabric/personSync person to FabricAdminController.java:409
POST/admin/sync/indy/issueIssue Indy credentialsAdminController.java:426
GET/admin/reportsReports dashboardAdminController.java:123
GET/admin/reports/block-detailBlockchain detail lookupAdminController.java:157
GET/admin/reports/pdfExport report as PDFAdminController.java:198

​
Integration Points

​
MySQL Database

Primary transactional data store for all person, document, and audit records. Key Tables:
  • persons - Citizen identity records
  • person_documents - Document metadata
  • files - Physical file references with SHA-256 hashes
  • audit_events - System audit trail

​
Filesystem Storage

Documents are stored in a normalized folder structure configured via CCDIGITAL_FS_BASE_PATH environment variable. Service: FileStorageService

​
Hyperledger Fabric

Document registry and access audit trail stored on distributed ledger. Services:
  • ExternalToolsService - Script execution
  • FabricLedgerCliService - Ledger queries
  • FabricAuditCliService - Audit operations
  • BlockchainTraceDetailService - Detail resolution

​
Hyperledger Indy / ACA-Py

Verifiable credential issuance and access state synchronization. Services:
  • IndyAdminClient - ACA-Py admin API client
  • UserAccessGovernanceService - Access state sync

​
Configuration

Key environment variables for the admin module: 
# Filesystem
CCDIGITAL_FS_BASE_PATH=/path/to/document/storage

# Fabric Integration
FABRIC_WORKDIR=/path/to/fabric/client
FABRIC_NODE_BIN=/usr/bin/node
FABRIC_SYNC_ALL_SCRIPT=sync-db-to-ledger.js
FABRIC_SYNC_PERSON_SCRIPT=sync-person.js

# Indy Integration
INDY_TOOLS_WORKDIR=/path/to/indy/tools
INDY_SCRIPT=issue_credentials_from_db.py
INDY_ISSUER_ADMIN_URL=http://issuer:8021
INDY_USER_ACCESS_SYNC_ENABLED=true
See README.md section 9 for complete configuration reference.

​
Best Practices

  1. Person Creation: Always create person records before allowing issuer document uploads
  2. Document Review: Review documents promptly to enable access request workflows
  3. Access Control: Document the reason when changing access states for audit purposes
  4. Blockchain Sync: Run Fabric sync operations during low-traffic periods
  5. Credential Issuance: Verify Indy network connectivity before issuing credentials
  6. Reporting: Use date range filters to optimize report performance

Build docs developers (and LLMs) love

Get started for freeTalk to us