Suma comprises a set of tools, including a mobile tablet-based (i.e. Apple iPad) data collection application, that will allow library staff to collect, aggregate, and interactively analyze real-time data about the usage of physical space and services. This tool will support the collection of more fine-grained data about physical space usage patterns by supporting the annotation of users with "activities." The data that this tool provides will allow the libraries to build on existing assessment practices by significantly improving our ability to analyze physical space usage trends against various milestones, as well as generating more dynamic and current data visualizations. As a result, this data can be both collected and utilized more frequently and at a much wider scope than before with relative ease.
This project has been in use at NC State University Libraries since 2011. Examples of the current and planned uses for this toolkit include the collection and analysis of data relating to:
- Building headcounts
- Reference desk transactions
- Experimental technology usage
- Media production activities
- Experimental furniture usage
We have worked hard to make the code as stable as possible, but are eager to receive feedback on any issues you discover. While we at NC State University Libraries have been using it in a production capacity since July 2011 with great success, and several other institutions have successfully implemented this code, you should still take appropriate precautions when deploying this application. These include but are not limited to carefully backing up databases, monitoring error logs, maintaining close relationships with users, and reporting any problems back to the project team. Thank you for helping to ensure that this project continues to grow.
As a safeguard, all JSON input from the client is logged. This will lead to large log files, but it allows for data recovery in the case of database problems or improperly rejected data. See the information about "JSON INPUT" entries in LOGS.md for more information. We at NC State University Libraries have never needed to make use of this recovery feature.
Suma and the Session Manager run as a single container, served from one Apache virtual host:
| Path | Application | Access |
|---|---|---|
/suma/client |
Tablet data collection client | Public |
/sumaserver |
Sync and query server | Public |
/suma/analysis |
Analysis reports | Public |
/suma-session-manager |
Session Manager | HTTP Basic auth |
/sumaserver must stay unauthenticated because the tablet clients cannot send
Basic credentials; only /suma-session-manager is password protected, using
SUMA_ADMIN_USER / SUMA_ADMIN_PASS.
To run it:
cp .env.example .env # then edit .env
docker compose up -d --buildAll configuration files (service/config/config.yaml,
session-manager/config.php, etc.) are generated from .env by
docker-entrypoint.sh on first start, and are not overwritten if they exist.
The Session Manager (see session-manager/) is part of this repository and this repository is its source of truth; the former standalone project (kstatelibraries/Suma-Session-Manager) is frozen.
Every timestamp is stored in UTC. Conversion to local time happens only when data is displayed or filtered:
- The container, PHP, and the MySQL connection are all explicitly pinned to UTC, so storage never depends on the host clock.
SUMA_ANALYTICS_TIMEZONE(an IANA name such asAmerica/Chicago) is the timezone that reports and the Session Manager present times in. It is also the timezone that day and hour report boundaries are evaluated against, so a "9am–5pm" report means 9am–5pm local, not UTC.- Conversion uses MySQL's named timezone tables, which the
init-dbservice loads on startup. Named zones are used rather than a fixed offset so daylight saving transitions are handled correctly.
Set SUMA_ANALYTICS_TIMEZONE=UTC to disable conversion entirely.
Every displayed datetime is annotated with the timezone abbreviation it is
shown in (e.g. CDT, UTC): the Session Manager and Analysis reports append
the SUMA_ANALYTICS_TIMEZONE abbreviation to each timestamp, and the tablet
client appends the device's local timezone abbreviation. The abbreviation is
resolved per timestamp so daylight-saving transitions are labeled correctly.
For help installing Suma, creating data collection initiatives, etc., please start by posting to our Google Group.
Do you want to contribute some code? Maybe some data reports, bug fixes, new clients, or even new core features? Awesome! Just contact us or fork the code on GitHub and create a pull request.
- Bret Davidson – Project lead.
- Jason Casden – Project founder, currently Head, Software Development at the University of North Carolina Chapel Hill University Libraries.
- Joyce Chapman – Community development and data analysis specialist, currently Assessment Analyst & Consultant at Duke University Libraries.
- Rob Rucker – Project team member and our first stakeholder.
- Niqui O'Neill – Developer.
- Jason Raitz – Developer.
- Luke Aeschleman – Developer.
- Eric McEachern – Developer, responsible for much of the development of the server-side components.
- Rusty Earl – Developer and technical consultant.