> For the complete documentation index, see [llms.txt](https://docs.digit.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digit.org/health/design/architecture/low-level-design/services/health-services/console-services/excel-ingestion/generate-api.md). # Generate API ### Endpoint * **Endpoint**: `/excel-ingestion/v1/data/generate/_init` * **Method**: POST ### Request Structure #### Body Parameters: RequestInfo: Object containing request information. GenerateResource: Object containing the details of the resource to be generated. * type: unified-console * tenantId: Tenant identifier. * hierarchyType: Type of hierarchy. * referenceId: Reference identifier for the resource (e.g., campaign ID, project ID). * referenceType: Type of reference (e.g., campaign, project). * locale: Locale for the generated file ### Request Example ``` { "RequestInfo": { "apiId": "Rainmaker", "authToken": "{{authToken}}", "userInfo": { "id": 34602, "uuid": "dd885ccb-f91d-4bf2-adb8-46fb66217797", "userName": "CAPTAIN", "name": "Ritik Verma", "mobileNumber": "9437584392", "emailId": "ritik.kumar@egovernments.org", "locale": null, "type": "EMPLOYEE", "roles": [ { "name": "Campaign Managers", "code": "CAMPAIGN_MANAGER", "tenantId": "dev" } ], "active": true, "tenantId": "dev", "permanentCity": null }, "msgId": "1761036073664|en_IN", "plainAccessRequest": {} } , "GenerateResource": { "tenantId": "dev", "type": "unified-console", "hierarchyType": "{{hierarchyType}}", "referenceId": "{{referenceId}}", "referenceType": "campaign", "locale" : "en_IN" } } ``` ### Response Structure Success Response: GenerateResource: Object containing the details of the generation request. * id: Unique identifier for the generation request (UUID). * tenantId: Tenant identifier. * type: unified-console * hierarchyType: Type of hierarchy. * referenceId: Reference identifier. * referenceType: Type of reference. * status: Current status of generation (pending, in\_progress, completed, failed, expired). * locale: Locale for the generated file. * fileStoreId: File store identifier (populated when status is 'completed'). * additionalDetails: Additional details including error information if failed. * errorCode: Error code if generation failed * errorMessage: Error message if generation failed * auditDetails : show the audit description ### Flow 1. **Client Initiates Request:** The client sends a `generate/_init` request to the Excel Ingestion service with the GenerateResource details. 2. **Validation of Request:** The Excel Ingestion service validates the request schema and performs pre-generation validations: * Validates tenant ID * Validates resource type * Validates hierarchy type * Validates reference ID and reference type * Validates boundary data if present in additionalDetails * Validates locale 3. **Expire Previous Records:** Before starting generation, the service expires any previous completed records with the same `referenceId + type` combination by setting their status to 'expired'. This ensures only the latest generation is active. 4. **Generate Unique ID:** Generate a unique UUID for the generation request. 5. **Set Audit Details:** Enrich the GenerateResource with audit details: * Set createdBy and lastModifiedBy from RequestInfo userInfo * Set createdTime and lastModifiedTime to current timestamp * Extract and set locale from RequestInfo if not provided 6. **Persist Initial Record:** * Set status to 'pending' * Persist the initial GenerateResource record to the database via Kafka (save topic) * This ensures the record is saved even in central instance deployments 7. **Start Async Generation:** * Start the actual Excel generation process in a background thread (using @Async) * Return immediately to the client with status 'pending' and HTTP 202 (ACCEPTED) 8. **Async Processing:** * The background thread calls `ExcelWorkflowService.generateAndUploadExcel()` * This performs the actual Excel file generation based on the type and configuration * The generated file is uploaded to filestore 9. **Update Status:** **Success Case:** * Set status to 'completed' * Set fileStoreId with the uploaded file ID * Clear any error details from additionalDetails * Update lastModifiedTime and lastModifiedBy * Persist to database via Kafka (update topic) **Failure Case:** * Set status to 'failed' * Set fileStoreId to null * Enrich additionalDetails with error information: * errorCode: Error code identifier * errorMessage: Human-readable error message * Update lastModifiedTime and lastModifiedBy * Persist to database via Kafka (update topic) ### Flow Diagram ``` ┌──────────┐ │ Client │ └─────┬────┘ │ │ POST /generate/_init │ (GenerateResourceRequest) ▼ ┌──────────────────────────────────┐ │ Excel Ingestion Controller │ │ (IngestionController.java:67) │ └────────────┬─────────────────────┘ │ │ initiateGeneration() ▼ ┌──────────────────────────────────┐ │ Generation Service │ │ (GenerationService.java:47) │ └────────────┬─────────────────────┘ │ ├─► 1. Generate UUID │ ├─► 2. Perform Validations │ (ExcelGenerationValidationService) │ ├─► 3. Expire Previous Completed Records │ (Same referenceId + type) │ ├─► 4. Set Audit Details │ (createdBy, createdTime, locale) │ ├─► 5. Push to Kafka Save Topic │ (Status: PENDING) │ │ │ └──► Persister saves to DB │ ├─► 6. Start Async Generation │ (AsyncGenerationService) │ └─► 7. Return Response (Status: PENDING, HTTP 202) │ ▼ ┌──────────┐ │ Client │ ◄── Response with pending status └──────────┘ ┌────────────────────────────────────────────────────────────┐ │ ASYNC BACKGROUND PROCESSING │ └────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────┐ │ Async Generation Service │ │ (AsyncGenerationService.java:36)│ └────────────┬────────────────────┘ │ ├─► Call generateAndUploadExcel() │ (ExcelWorkflowService) │ - Generate Excel based on type │ - Fetch data from services │ - Apply templates │ - Upload to filestore │ ├─► SUCCESS CASE: │ - Set status = 'completed' │ - Set fileStoreId │ - Clear error details │ - Update audit details │ - Push to Kafka Update Topic │ └─► FAILURE CASE: - Set status = 'failed' - Set fileStoreId = null - Enrich error details: * errorCode * errorMessage - Update audit details - Push to Kafka Update Topic │ ▼ ┌────────────┐ │ Persister │ ◄── Update Topic └─────┬──────┘ │ ▼ ┌────────────┐ │ Database │ (Final status: completed/failed) └────────────┘ Client polls /generate/_search to check final status ``` ### Status States The generation process goes through the following status states: 1. **pending:** Initial state when the generation request is accepted. The Excel generation is queued for processing. 2. **completed:** The Excel file has been successfully generated and uploaded to filestore. The `fileStoreId` field contains the file identifier. 3. **failed:** The generation process encountered an error. Error details are available in `additionalDetails`: * `errorCode`: Identifier for the error type * `errorMessage`: Human-readable error description 4. **expired:** Previous completed records are marked as expired when a new generation request is made for the same `referenceId + type` combination. This ensures only the latest generation is active. #### Generation Configuration Below is the MDMS configuration used during the `generate/_init` process. Based on the sheet name and generation class, the corresponding sheet is generated. ``` [ { "sheets": [ { "order": 1, "visible": true, "sheetName": "HCM_ADMIN_CONSOLE_FACILITIES_LIST", "schemaName": "facility-microplan-ingestion", "generationClass": "FacilitySheetGenerator", "isGenerationClassViaExcelPopulator": false }, { "order": 2, "visible": true, "sheetName": "HCM_ADMIN_CONSOLE_USERS_LIST", "schemaName": "user-microplan-ingestion", "generationClass": "UserSheetGenerator", "isGenerationClassViaExcelPopulator": false }, { "order": 3, "visible": true, "sheetName": "HCM_CONSOLE_BOUNDARY_HIERARCHY", "generationClass": "BoundaryHierarchySheetGenerator", "isGenerationClassViaExcelPopulator": true } ], "applyWorkbookProtection": true, "excelIngestionGenerateName": "unified-console" } ] ``` ### Error Handling Errors during generation are captured and stored in the `additionalDetails` field: #### Error Response Example: ``` { "GenerateResource": { "id": "550e8400-e29b-41d4-a716-446655440000", "tenantId": "mz", "type": "microplan", "status": "failed", "fileStoreId": null, "additionalDetails": { "errorCode": "BOUNDARY_SERVICE_ERROR", "errorMessage": "Failed to fetch boundary data: Connection timeout" }, "lastModifiedTime": 1672531500000 } } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.digit.org/health/design/architecture/low-level-design/services/health-services/console-services/excel-ingestion/generate-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.