> ## Documentation Index
> Fetch the complete documentation index at: https://help.propops.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings & Configuration

> Configure branches, branding, third-party integrations, and organisation-wide settings in the PropOps admin panel to match your workflow.

This guide covers the key configuration tasks for setting up and customising your PropOps instance.

***

## Branch setup

Branches represent physical offices or operational divisions within your organisation. Each branch has its own job pool, SLA targets, and staff assignments.

### Creating a branch

<Steps>
  <Step title="Open branch settings">
    Go to **Admin → Branches** and select **Add Branch**.
  </Step>

  <Step title="Enter branch details">
    Fill in the branch name, address, phone number, and email. Upload a branch logo if you want a visual identifier.
  </Step>

  <Step title="Set SLA targets">
    Configure SLA targets for each priority level (Urgent, High, Normal, Low). These determine when SLA warnings and breach alerts are triggered for jobs in this branch.
  </Step>

  <Step title="Save the branch">
    Select **Save**. The branch is now available for job assignment and staff allocation.
  </Step>
</Steps>

### Branch sharing

By default, agents can only see jobs within their own branch. To allow cross-branch visibility, enable **branch sharing** in the branch settings. This lets agents view and manage jobs from other branches they have been granted access to.

***

## Branding

Customise the look of your PropOps instance to match your organisation's brand.

### Application logo

1. Go to **Admin → Settings → Branding**.
2. Upload your organisation's logo as an SVG file.
3. The logo appears in the navigation bar and on generated documents.

### Login page

Customise the login page with:

* **Background image** — uploaded from admin settings.
* **Slide images** — a carousel of images shown alongside the login form.

File type restrictions are enforced from your environment configuration.

### Colour theme

PropOps Web supports dynamic theming. Your administrator can adjust the primary brand colour under **Admin → Settings → Branding**. The colour is applied across buttons, links, and accent elements throughout the interface.

***

## Job types

Job types categorise maintenance work (e.g. Plumbing, Electrical, Gas Safety, EICR, General Maintenance).

### Configuring job types

1. Go to **Admin → Settings → Job Types**.
2. Select **Add Job Type** or edit an existing one.
3. Enter the type name and optionally attach a document template and title suggestion.
4. Save — the job type is now available in the job creation form.

Job types can carry approval gate requirements — if enabled, jobs of that type must pass through a management review before progressing.

***

## Priority levels and SLA

Priority levels (Urgent, High, Normal, Low) determine the SLA target for each job. SLA targets are set per branch under **Admin → Branches**.

When a job approaches its SLA deadline:

* A warning appears on the job card.
* Automated alerts are sent to the assigned agent.
* Once the deadline passes, the job is recorded as an SLA breach in the audit log.

***

## Payment statuses

Customise the available payment statuses to match your finance workflow.

1. Go to **Admin → Settings → Payment Statuses**.
2. Add or edit statuses (e.g. Awaiting Invoice, Invoiced, Payment Received, Payment Complete).
3. These statuses appear on the job's Financial tab and in the jobs list filter.

***

## VAT rate

Set the default VAT rate under **Admin → Settings → VAT Rate**. The default is 20% (standard UK rate). This rate is applied automatically when calculating invoice totals.

***

## Data retention

Configure how long personal data is retained before automatic purge.

1. Go to **Admin → Settings → Data Retention**.
2. Set the retention period for tenant, landlord, and job data.
3. PropOps automatically purges records after the configured period, in line with UK GDPR data minimisation obligations.

***

## Maintenance mode

Take your instance offline for scheduled maintenance:

1. Go to **Admin → Settings → Maintenance Mode** or use the API (`POST /api/system/maintenance-mode`).
2. Enable maintenance mode with an optional user-facing message.
3. Authenticated staff can still access the platform; all other users see the maintenance screen.
4. Disable maintenance mode when you're done.

***

## Integrations

### Xero (accounting)

PropOps integrates with Xero for financial data synchronisation. Configure the integration under **Admin → Settings → Integrations → Xero**.

### Mapbox (coverage map)

The contractor coverage map uses Mapbox for mapping and isochrone visualisation. Your Mapbox access token is configured in the `.env` file.

### WhatsApp Messaging

WhatsApp message templates are managed in **Admin → WhatsApp Templates**. No external API credentials are required — see the [Setting Up Notifications](/guides/setting-up-notifications) guide for details.

***

## Environment configuration

The environment configuration panel in **Admin → Settings → Environment** allows you to view, edit, and back up your `.env` file and manage encryption keys without direct server access.

<Warning>
  Only staff members with the **SysOps** or **Director** role can access the environment configuration panel. Changes to encryption-related variables can cause data issues if not handled carefully.
</Warning>

### Viewing and editing environment variables

1. Go to **Admin → Settings → Environment**.
2. All variables are displayed in a key-value editor alongside their comments from `.env`.
3. **Secret variables** (like `DB_PASS`, `API_KEYS`) are masked for security — only administrators with permission can edit them.
4. Edit any variable, then **Save** to write the changes back to your `.env` file.
5. Every change is logged in the audit trail (`env_change_log` table) with the user, timestamp, and action.

### Backing up your environment

Backups of your `.env` are automatically created before any changes. You can also:

1. Go to **Admin → Settings → Environment**.
2. Select **Backup** to create a manual snapshot of the current `.env` file.
3. The backup is encrypted at rest (AES-256-CBC) and stored in `data/env-backups/`.
4. View previous backups and restore an older version in the **Backup History** section.

<Warning>
  Backups are encrypted but still contain sensitive information (API keys, database passwords). Treat backup files as secrets — never commit them to version control or share them publicly.
</Warning>

### Rotating PII encryption keys

If you suspect your `PII_ENCRYPTION_KEY` or `PII_HMAC_KEY` has been compromised, or as part of a regular security audit, you can rotate these keys directly from the environment panel.

<Steps>
  <Step title="Open environment settings">
    Go to **Admin → Settings → Environment** and find the **Rotate PII Keys** button.
  </Step>

  <Step title="Initiate the rotation">
    Select **Rotate PII Keys**. PropOps will:

    * Generate new `PII_ENCRYPTION_KEY` and `PII_HMAC_KEY` values
    * Decrypt all personal data in the database using the old keys
    * Re-encrypt all personal data using the new keys
    * Decrypt all job files (documents, photos, videos, GDPR reports) using the old keys
    * Re-encrypt all job files using the new keys
    * Update the `.env` file with the new keys
    * Create an automatic backup of the old `.env` for recovery purposes
  </Step>

  <Step title="Verify completion">
    Once the operation completes, all personal data and job files remain accessible to authorised users. The system transparently decrypts data on access — no user-facing changes occur.
  </Step>

  <Step title="Archive the old keys">
    The old encryption keys are backed up automatically. You can securely delete or archive them according to your organisational policy.
  </Step>
</Steps>

<Warning>
  PII key rotation is a resource-intensive operation. It processes:

  * All encrypted database fields across 6 tables
  * All job documents, photos, videos, and thumbnails
  * All GDPR data exports

  Plan key rotations during off-peak hours. The operation may take several minutes depending on your data volume. Do not stop the Docker container or interrupt the process.
</Warning>