# 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 %}


---

# Agent Instructions: 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:

```
GET https://docs.digit.org/complaints-management/complaints-resolution-v2.10/deploy/configure/boundary.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.