# Boundary

## Overview

The Boundary service in DIGIT manages hierarchical location data for the Complaints Management, ensuring each complaint is accurately geo-tagged and routed. It organises boundaries into configurable levels (Example: State → District → ULB → Zone → Ward → Locality), enabling dynamic retrieval and validation.

| Boundary Type    | Description                        |
| ---------------- | ---------------------------------- |
| REVENUE-LOCALITY | Urban boundary data (Cities, ULBs) |

This helps the system route complaints more accurately based on whether they belong to urban or rural areas.

**Services Required**

To use Boundary V2 in your environment, the following DIGIT microservices must be deployed and running:

<table><thead><tr><th width="233.237548828125">Service Name</th><th>Purpose</th></tr></thead><tbody><tr><td>boundary-bulk-bff</td><td>Handles bulk upload of boundaries</td></tr><tr><td>boundary-service-db</td><td>Stores and manages boundary data</td></tr></tbody></table>

Release Update Highlights

* Location boundaries are now handled via two separate hierarchies.
* Enables better service routing and area-specific workflows.
* Supports bulk creation and Excel-based uploads for managing boundaries easily.

## Pre-requisites

Before starting, make sure the following are ready:

* ✅ **Postman** is installed
* ✅ Your DIGIT app base URL (e.g., `https://dev.digit.org`)
* ✅ **AuthToken** of a superuser (from installation)
* ✅ The target `tenantId` where the boundary is to be set (e.g., `pg.citya`)

***

## Configure Boundary

{% stepper %}
{% step %}

### Import Postman Collection

* Copy the provided [**Postman collection URL**](https://api.postman.com/collections/23418568-beff7b61-d0f2-447b-a675-4df1da6b9c00?access_key=PMAT-01K06TNXJZ8ZND8JJ60XNPGGR8).
* Open Postman.
* Click the **Import** icon.
* Paste the URL and click **Continue** → **Import**.
* The collection will now appear on the **left side** in Postman.

> Before running any APIs, **update your Postman environment** with:
>
> * `baseUrl` = your DIGIT app domain (e.g., `https://dev.digit.org`)
> * `authToken` = superuser token
> * `tenantId` = state + city ULB (e.g., `pg.citya`)
>   {% endstep %}

{% step %}

### Create a Hierarchy Type

API: `POST /boundary-service/boundary-hierarchy-definition/_create`

* This defines the type of boundary you’re setting up.
* Common types: `ADMIN`, `REVENUE`, etc.

{% hint style="info" %}
Example: To set up localities, use `hierarchyType = ADMIN`.
{% endhint %}
{% endstep %}

{% step %}

### Generate Excel Template

API: `GET /boundary-bulk-bff/v1/boundary/generate?tenantId=as&hierarchyType=TestNew4`

* This will generate a boundary upload Excel template specific to the chosen hierarchy.
* It will return a fileStoreId in the response.
  {% endstep %}

{% step %}

### Download the Template

API: `GET /filestore/v1/files/url?tenantId=as&fileStoreIds=<fileStoreId>`

Replace `<fileStoreId>` with the value from Step 2.

* The response contains a file URL — open it to download the Excel file.

{% hint style="info" %}

* Example Files: locality.xlsx – for urban boundaries
  {% endhint %}
  {% endstep %}

{% step %}

### Fill in Boundary Details

Open the downloaded Excel file and fill in boundary data, such as:

* Region name
* Boundary code
* Parent-child relationships
* Latitude/Longitude (if applicable)
* Boundary type (Ward, Locality, Village, etc.)

{% hint style="info" %}
Important: Ensure no formatting is changed. Stick to the given format.
{% endhint %}
{% endstep %}

{% step %}

### Upload the filled Excel file

API: `POST /filestore/v1/files`

* Upload the updated Excel file.
* This will return a new fileStoreId that contains your boundary data.
  {% endstep %}

{% step %}

### Create Boundaries in the System

API: `POST /boundary-bulk-bff/v1/boundary/createw4`

* Use the new fileStoreId from Step 4 to trigger boundary creation in the system.
* This API reads the file and creates the location hierarchy in the backend database.

{% hint style="info" %}
The system will now save the boundary data into the backend database.
{% endhint %}
{% endstep %}
{% endstepper %}

***

### Sample Reference Files

* ✅ [locality.xlsx](https://docs.google.com/spreadsheets/d/1zXjWWicpMnkiblrrTDKoOaU179Dw4CjgQz5LMwcDu5I/edit?gid=0#gid=0) – Urban boundaries

(Provide internal links or shareable URLs if hosting these templates in your internal system.)

***

## &#x20;Summary

<table><thead><tr><th width="86.95001220703125">Step</th><th width="247.04058837890625">Task</th><th>API/Tool Used</th></tr></thead><tbody><tr><td>1</td><td>Create boundary hierarchy</td><td>/boundary-service/boundary-hierarchy-definition/_create</td></tr><tr><td>2</td><td>Generate Excel template</td><td>/boundary-bulk-bff/v1/boundary/generate</td></tr><tr><td>3</td><td>Download the template</td><td>/filestore/v1/files/url</td></tr><tr><td>4</td><td>Fill Excel with boundary data</td><td>Use Excel locally</td></tr><tr><td>5</td><td>Upload filled file</td><td>/filestore/v1/files</td></tr><tr><td>6</td><td>Create boundaries from the file</td><td>/boundary-bulk-bff/v1/boundary/createw4</td></tr></tbody></table>

***

{% hint style="info" %}

### Tips

* Always use the correct tenantId (e.g., pb, uk, as) across all requests.
* Don’t modify the template structure when filling in the Excel.
* If the hierarchy already exists, you can skip Step 1.
* If you encounter errors during boundary creation, check:
  * Hierarchy names are consistent
  * Excel fields are not empty
  * Uploaded Excel matches template format
    {% endhint %}