Off Hours Report App

This repository contains a simple proof‑of‑concept web application for building off‑hours utilization reports from Cisco Spaces Firehose telemetry. Building operations teams can use these reports to identify conference rooms that were used after janitorial service hours and prioritize them for cleaning.

Overview

The application streams telemetry events from the Cisco Spaces Firehose API (people count per room over time) and rolls them up into nightly after‑hours “sessions.” Each session records the start and end time of occupancy, the maximum number of people observed and the total occupied minutes.

On the front end, a simple UI lets an administrator:

• Configure the off‑hours window (start and end time).
• View a table of past reports showing the number of sessions, total occupied minutes and peak headcount for each room.
• Provide a comma‑separated list of email recipients who should receive the daily report.

The UI and the processing pipeline are deliberately minimal so that you can extend them easily. In a production deployment you would persist data to a database, automatically fetch telemetry events from the Firehose API, and send reports by email via a service such as SendGrid.

Quick start

1. Install the dependencies and start the server:

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   python app.py

2. Navigate to http://localhost:5000 in your browser. Use the form on the home page to set the off‑hours window and recipient emails.

3. Visit the Reports link to see automatically generated data sourced from the Firehose stream. Each table row rolls up the telemetry for a room and exposes the raw sessions underneath the room name.

Firehose API configuration

The application expects a Cisco Spaces Firehose API key to be provided in an environment variable named FIREHOSE_API_KEY.

export FIREHOSE_API_KEY="your‑firehose‑api‑key"
python app.py

Optional environment variables let you tailor how the collector runs:

• FIREHOSE_STREAM_URL – override the default Cisco Spaces Firehose people count stream URL.
• REPORT_LOOKBACK_DAYS – number of days of telemetry to include on the report page (defaults to 3).
• SESSION_GAP_MINUTES – how many minutes of inactivity are allowed before a new session is started (defaults to 15).

Project structure

off_hours_report_app/
├── app.py               # Flask application with routes, telemetry ingestion and reporting
├── requirements.txt     # Python dependencies (Flask plus streaming helpers)
├── README.md            # This file
├── templates/
│   ├── index.html       # Form for configuring off‑hours window and emails
│   └── reports.html     # Table displaying telemetry reports with session details
└── static/
    └── styles.css       # Basic CSS styling

Extending this prototype

This repository is a starting point. To build a production‑ready solution you may wish to:

• Persist configuration and report data in a database (e.g. PostgreSQL, SQLite or BigQuery).
• Ingest Firehose events continuously via a webhook or polling service using the provided API key.
• Define utilization more accurately by weighting total occupied minutes, peak headcount and number of sessions (see the utilization_score function in app.py). Adjust the weights to match janitorial priorities.
• Send daily emails containing the top rooms to clean using an email delivery service.
• Create a nicer front end (for example using React or Vue) that consumes a JSON API exposed by the Flask app.

Feel free to adapt and expand the code to suit your organization’s needs.