# MEGA™ bulk municipal planning setup

Use **Bulk setup** in the top navigation, download `planning_template.xlsx`, complete the **three worksheets**, upload, review errors/counts, and click **Confirm and import**. The process is controlled by administrator accounts and uses the existing login/CSRF session.

## Workbook structure (headers must remain unchanged)

**Departments:** `department_code`, `department_name`, `parent_department_code` (optional; validated as a reference, but the current departmental database has no parent field, so the hierarchy is not yet persisted).

**Strategic Objectives:** `code`, `objective`, `financial_year`, `department_codes`.

**Operational Objectives:** `code`, `objective`, `strategic_code`, `department_codes`, `financial_year`.

Separate multiple department codes with `;`, e.g. `BTO;SCM`. Use the *same stable department codes* on all sheets. An operational `strategic_code` must exist as an IDP objective for the same financial year, either already saved or in this upload.

**Important:** The template includes clearly illustrative rows. Replace those with approved municipal data before importing. Do not upload the examples as real objectives.

## Import behaviour

- Maximum 2 MB per workbook, 1,000 data rows per worksheet.
- Validates all required fields, codes, financial year format, departmental links and strategic parents before committing anything.
- Uses a database transaction: failures roll back all changes.
- Departments with the same *import code* are updated; a department with the same name can be adopted and assigned a code.
- Existing strategic/operational objectives are updated by their code and financial year, preserving existing risk references.
- Imported objective-department associations are replaced with the associations from the uploaded file.
- Existing data not listed in the workbook is not deleted.
- PHP `ZipArchive` and `SimpleXML` extensions are required, along with the existing MySQL/PDO extensions.
- `app/config.php` is **not modified** by the patch or import.

## Database migration

The import page creates two supporting tables on first use: `department_import_codes` and `objective_department_links`. The existing `departments`, `objectives`, `risks`, and `app/config.php` remain unchanged.

## Limitations

This update changes the **setup/import workflow only**. The current application's workshop/risk form still allows selecting any operational objective; filtering this choice by the linked departments is a separate enhancement. Department parent codes are accepted and validated but the pre-existing department schema does not store hierarchy. Existing objectives entered manually without codes will remain; use a cautious backup and audit before replacing any such records. Do not expose imported SDBIP information to unauthorised users.