Phase 2 – Boundary Master Upload

Overview

Boundary data defines the complete administrative hierarchy of a State or City tenant. In the Jupyter Notebook, Phase-2 guides the administrator through:

1. Selecting or creating the boundary hierarchy

2. Downloading the boundary template

3. Filling hierarchy-level values

4. Uploading the Excel file

5. Schema validation, processing, and error handling

This section documents the full instruction set exactly as required in the implementation.

1. Understand Boundary Model

A boundary represents the administrative geographic divisions of a tenant.

Define your own Hierarchy

Typical hierarchy:

City → Zone → Ward → Block → Locality

The hierarchy levels are configurable and may differ across deployments. Administrators must define the boundary hierarchy before uploading boundary data.

2. Boundary Workflow

The boundary selection in the Jupyter Notebook includes the following steps:

Step 1 – Select Tenant

Enter the exact tenant code (e.g., PG.CITYA) for which the boundary values will be created.

Step 2 – Create or Select Boundary Hierarchy Definition

The notebook provides two options:

Option A: Create New Hierarchy

Used for a new tenant with no existing boundaries.

The admin enters:

• Hierarchy Type (e.g., ADMIN)

• Levels in order (e.g., City → Zone → Ward → Locality)

Example structure:

Level Order	Level Name
1	City
2	Zone
3	Ward
4	Locality
5	Block (if applicable)

The system registers the hierarchy using: /boundary-service/hierarchy-definition/v1/_create

Option B: Use Existing Hierarchy

If the hierarchy is already defined, the admin selects it from the dropdown.

3. Download Boundary Template

After hierarchy selection, the notebook displays: “Generate Boundary Template” “Download Template”

The downloaded file contains one worksheet:

Sheet Name: Boundary Master Template

The template is dynamically generated based on hierarchy levels. Columns are created based on the levels configured by the admin.

4. Boundary Template Structure

The boundary sheet contains the following columns (structure depends on the number of levels):

Example Template Structure

Column Name	Description	Mandatory	Example
Country	Country name	Yes	India
State	State name	Yes (if hierarchy starts at State)	Punjab
City	City Name	Yes	City A
Zone	Zone Name	No	Zone 1
Ward	Ward Name/Number	No	Ward 12
Block	Sub-ward division	No	Block A
Locality	Area/Locality Name	No	Shastri Nagar
Code	Unique boundary code	Yes	PG_CITYA_ZONE1
Parent Code	Boundary code of immediate parent	Required except at level 1	PG_CITYA

Important:

• The first hierarchy level (City) does not have a parent.

• All lower levels must reference a valid parent code.

5. API-Level Validation (Layer 1)

Boundary Service performs final validations:

• Parent code exists in the database

• Duplicate boundaries

• Invalid tenant-level hierarchy

• Non-existent hierarchy type

• Illegal child-level assignment

Only validated rows proceed to insertion.

API used: /boundary-service/boundary/v1/_create

The processing is asynchronous. The notebook displays:

• Processing Started

• Processing In Progress

• Processing Completed