> 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/v2.1/design/architecture/low-level-design/services/health-services/console-services/boundary-management/process-api-auto.md).

# Process API - Auto

### Endpoint

* Endpoint: /boundary-service/v1/\_process
* Method: POST

### Request Structure

Query Parameters:

* tenantId: Tenant identifier
* referenceId: Reference identifier (optional)

Body Parameters:

* RequestInfo: Object containing request information
* ResourceDetails: Object containing the details of the boundary data to be processed
  * tenantId: Tenant identifier
  * hierarchyType: Type of hierarchy (e.g., ADMIN, MICROPLAN)
  * fileStoreId: File store ID of the uploaded Excel file
  * action: Action type (create)
  * referenceId: Reference identifier (optional)

### Request Example

```
{
    "RequestInfo": {
      "apiId": "Rainmaker",
      "authToken": "{{authToken}}",
      "userInfo": {
        "uuid": "dd885ccb-f91d-4bf2-adb8-46fb66217797",
        "userName": "ADMIN",
        "tenantId": "mz"
      },
      "msgId": "1761036073664|en_MZ"
    },
    "ResourceDetails": {
      "tenantId": "mz",
      "hierarchyType": "ADMIN",
      "fileStoreId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "action": "create",
      "referenceId": "CAMP-001"
    }
  }
```

### Response Structure

Success Response:

* ResourceDetails: Object containing the details of the process request
  * id: Unique identifier for the process request (UUID)
  * tenantId: Tenant identifier
  * hierarchyType: Type of hierarchy
  * fileStoreId: Original uploaded file store ID
  * processedFileStoreId: Processed file store ID (populated when status is 'completed')
  * action: Action type (create)
  * status: Current status (accepted, started, completed, failed, invalid)
  * referenceId: Reference identifier
  * auditDetails: Audit information
    * createdBy: User UUID who created
    * createdTime: Creation timestamp
    * lastModifiedBy: User UUID who last modified
    * lastModifiedTime: Last modification timestamp
  * additionalDetails: Additional details including error information if failed
    * fileName: Original file name
    * error: Error details (present only if status is 'failed')

### Response Example

```
{
    "ResponseInfo": {
      "apiId": "egov-bff",
      "ver": "0.0.1",
      "ts": 1761036103664,
      "status": "successful"
    },
    "ResourceDetails": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenantId": "mz",
      "hierarchyType": "ADMIN",
      "fileStoreId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "processedFileStoreId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "action": "create",
      "status": "completed",
      "referenceId": "CAMP-001",
      "auditDetails": {
        "createdBy": "dd885ccb-f91d-4bf2-adb8-46fb66217797",
        "createdTime": 1761036073664,
        "lastModifiedBy": "dd885ccb-f91d-4bf2-adb8-46fb66217797",
        "lastModifiedTime": 1761036103664
      },
      "additionalDetails": {
      }
    }
  }
```

### Flow

1. Client Initiates Request: The client sends a process request to the Boundary Management service with Excel file already uploaded to FileStore.
2. Fetch Localization Maps: Service fetches localization maps for hierarchy-specific and boundary management modules.
3. Validation of Request: The service validates the request and performs pre-processing validations: - Validates tenantId - Validates hierarchyType - Validates fileStoreId - Validates action is "create"
4. Generate Unique ID: Generate a unique UUID for the process request.
5. Set Audit Details: Enrich ResourceDetails with audit details: - Set createdBy and lastModifiedBy from RequestInfo userInfo - Set createdTime and lastModifiedTime to current timestamp
6. Persist Initial Record: - Set status to 'accepted' - Persist the initial ResourceDetails record to database via Kafka (save topic)
7. Return Immediate Response: Return to client with status 'accepted' and HTTP 200.
8. Start Background Processing: - Download Excel file from FileStore - Get current flow from database (auto/manual) - Get hierarchy definition from Boundary Service - Validate Excel sheet headers and data - Segregate data (withBoundaryCode, withoutBoundaryCode, manualBoundaryCode) - Validate flow consistency
9. Auto-Generate Boundary Codes (Auto Flow): - Build code mappings from existing boundaries - Build child-parent relationships - Call IdGen service to generate boundary codes - Create boundaryMap
10. Create Boundary Entities: - Check existing entities in chunks of 20 - Create new entities in chunks of 200 - Wait 2 seconds for persistence
11. Create Boundary Relationships: - Build modified child-parent map using codes - Confirm parent exists (retry up to 6 times) - Create boundary relationships
12. Create Localization Messages: - Create French localization messages - Create Portuguese localization messages - Create default (English) localization messages
13. Generate Processed Excel File: - Add generated codes to data - Create Excel workbook with headers and data - Upload to FileStore
14. Update Status: - Success Case:
    * Set status to 'completed'
    * Set processedFileStoreId with 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 processedFileStoreId to null
    * Enrich additionalDetails with error information (errorCode, errorMessage)
    * Update lastModifiedTime and lastModifiedBy
    * Persist to database via Kafka (update topic)
15. Trigger Generate API: After 30 seconds, trigger `/v1/_generate` API with determinedCurrentFlow for downloadable file creation.

### Flow Diagram

```
 ┌──────────┐
  │  Client  │
  └─────┬────┘
        │
        │ POST /v1/_process
        │ (ResourceDetails)
        ▼
  ┌──────────────────────────────────┐
  │  Boundary Controller             │
  └────────────┬─────────────────────┘
               │
               │ processBoundaryService()
               ▼
  ┌──────────────────────────────────┐
  │  Boundary Service                │
  └────────────┬─────────────────────┘
               │
               ├─► 1. Fetch Localization Maps
               │
               ├─► 2. Validate Process Request
               │
               ├─► 3. Generate UUID
               │
               ├─► 4. Set Audit Details
               │   (createdBy, createdTime)
               │
               ├─► 5. Push to Kafka Save Topic
               │   (Status: ACCEPTED)
               │   │
               │   └──► Persister saves to DB
               │
               ├─► 6. Return Response
               │   (Status: ACCEPTED, HTTP 200)
               │
               └─► 7. Start Background Processing
                   │
                   ├─► Download Excel from FileStore
                   │
                   ├─► Get Current Flow from DB
                   │
                   ├─► Get Hierarchy Definition
                   │
                   ├─► Validate Excel Data
                   │
                   ├─► Segregate Data
                   │   (withBoundaryCode, withoutBoundaryCode)
                   │
                   ├─► Auto-Generate Codes (IdGen)
                   │
                   ├─► Create Boundary Entities
                   │   (Chunks of 200)
                   │
                   ├─► Create Boundary Relationships
                   │   (With parent validation)
                   │
                   ├─► Create Localization Messages
                   │   (EN, FR, PT)
                   │
                   ├─► Generate Processed Excel
                   │
                   ├─► Upload to FileStore
                   │
                   ├─► Push to Kafka Update Topic
                   │   (Status: COMPLETED)
                   │
                   └─► Trigger Generate API (30s delay)
```

### Status States

The process goes through the following status states:

* accepted: Initial state when the process request is received and validated. Processing is queued for background execution.
* started: Processing has begun (used for non-create actions).
* completed: Boundary data successfully processed. Entities created, relationships established, and processed file uploaded. The processedFileStoreId field contains the file identifier.
* failed: The processing encountered an error. Error details are available in additionalDetails:
  * error: Stringified JSON containing status, code, description, and message
* invalid: Data validation failed but processing continues with some errors.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.digit.org/health/v2.1/design/architecture/low-level-design/services/health-services/console-services/boundary-management/process-api-auto.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
