Admin

App Authentication (SSO, Password, etc)

Site Access Sync Feature

Change Company Feature

Worker Messaging

Site Messaging

Forms

Inventory

Device Config

Delivery Tracking

Messaging

Mass Texting

Reports

Safety

Safety Dashboard

Scanner

Zone Restriction

Training

Workforce

Worker Safety Notes

Ban Worker Feature

General

User Roles & Product Features

New Feature Implementation Checklist

Documentation for Customers

Sitemetric SSO Setup.pdf

Sitemetric SAML SSO Integration Guide.pdf

📞 Point of Contacts:

Engineers: @Mike Spector, @Cooper Hurt, @Daniel Stepp

Product Questions:

🔐What is authentication?

Authentication in an application is the process of verifying who a user is before allowing access. It’s like checking someone's ID before letting them in.

Sitemetric app supports multiple ways for users to prove who they are—by entering a password, using a phone number with a code, or signing in through another trusted service with Single Sign-On (SSO), like Google or Microsoft.

NOTE: *This is different then authorization which is the process of saying ok your authenticated and we know who you are, but CAN you do this action.*

❓How do we use Authentication?

Inside of our application we have a couple different means of being able to authenticate a user. Those are password and sso or code

How to configure a user w/ Password:

TODO: Fill out

Configuring a User with SSO with their own provider:

Currently we are only supporting SSO for three different companies, those are Amazon (amazon_a2z , sitemetric_entra , holder_entra). Right now with how the feature has been built engineering has to manually add the configuration

sitemetric_entra - This is a configuration that allows Sitemetric users within the organization ( sitemetric.com emails) to be able to sign in with Microsoft, or more specifically a Microsoft product called Microsoft Entra.

holder_entra - This is a configuration that allows Holder users within the organization ( holder.com emails) to be able to sign in with Microsoft, or more specifically a Microsoft product called Microsoft Entra.

amazon_a2z - This is a configuration that allows users with `amazon.com` email to be able to login with their provider as well.

To configure an existing user you need to go to:

Log into the Application
Click Admin
Click Users
Search or find the User your looking for and click into their profile. Then click Edit located in the top right. (Also take note of the provider is currently set to password

!image.png

Inside of the modal click into the Provider field and change it to the desired field for SSO.

!image.png

Click Save and verify the changes took affect on the profile.

!image.png

** NOTE ** : Changing this will make the user no longer be able to login with a password rather they will now be required to sign in with SSO next time through.

💻 How to Login in with SSO:

Visit the desired environment (ex. https://us.sitemetric.com) and click `Login. After clicking login you should get a UI similar to the following:

!image.png

Click Sign in with SSO and the user will now be prompted to login with their SSO *(in this example we will go through Sitemetric Entra flow)*
Sign in with Microsoft and after all is completed you should be redirected back into the application IF they are already registered.

!image.png

After signing in through Microsoft completely they should be redirected back into the application with a successful login.

The Change Company feature is a tool designed to give users with admin status the ability to mass change the company for a given set of workers. The user can select a set of workers by choosing the workers of an already existing company, or uploading their own custom set in a CSV file.

Quick Demonstration of How to Use:

change_company.mp4

Availability:

Currently only available on the Web version (not mobile)
Restricted to Admin users

Where to Find the Site Access Sync Tool:

Navigate to the Admin Panel
Click on Workers
Select the Change Company button

How to Use the Site Access Sync Tool:

Go to Admin -> Workers
Click on the Change Company button
A modal will appear with FROM and TO options
- FROM Option:
  - Select an existing company OR upload a custom CSV file of workers
  - If uploading a CSV of workers, it must contain 3 columns with the following headers:
    - worker_id
    - site_id
    - company_id
- TO Option:
  - Select the destination company

(NOTE: if an existing company is chosen for the FROM option, the company for the TO option must be different)

Click Perform Now button to start the process
The system will update each worker’s company accordingly

The Site Access Sync feature is a tool designed to give users with admin status the ability to mass sync site access for a given set of workers. The user can select a set of workers by choosing all workers of an existing site, or uploading their own custom set in a CSV file.

Quick Demonstration of How to Access and Use:

site_access_sync.mp4

Availability:

Currently only available on the Web version (not mobile)
Restricted to Admin users

Where to Find the Site Access Sync Tool:

Navigate to the Admin Panel
Click on Workers
Select the Site Access button

How to Use the Site Access Sync Tool:

Go to Admin -> Workers
Click on the Site Access button
A modal will appear with FROM and TO options
- FROM Option:
  - Select a site OR upload a CSV file of workers
  - If uploading a CSV of workers, it must contain 2 columns with the following headers:
    - worker_id
    - site_id
- TO Option:
  - Select the destination site

(NOTE: if an existing site is chosen for the FROM option, the new site for the TO option must be different)

Click Sync Now to start the process
The system will grant each worker in the FROM option, site access to the TO site

How do messaging work?

Messaging is an opt-in feature, meaning messaging is not enabled by default for a site, rather they need to reach out or enable the feature to be able to work.

Typical process is we will order a number from one of vendors which usually will be one of two which are Telnyx and Bandiwdth

Both of these vendors use a very similar process where we will use a Site’s Address, Point of Contact, and Customer/Company relationship to order a number on their behalf.

Order Number → Activate Voice/Text Configuration → Submit Toll-Free Verification

While a number can fail at any stage typically here are the states pending → We failed before we could activate voice/text or submit TFV

pending_tfv → We

How to Enable Messaging

How Numbers Get Enabled

The Worker Messaging Panel is a component designed to give users with admin status the ability to opt-in or opt-out a worker’s text messaging status for a given site. For context, by default, every worker added to a particular site is also, by default, opted-in to that sites text messaging service (if the worker has a valid phone number); this panel allows an admin user to modify that status, and opt them out or in.

Availability:

Available on Web, iOS, and Android
Restricted to Admin users

Where to Find the Worker Messaging Panel:

The Worker Messaging Panel is located in 2 places currently:

The Worker Details Page in the Admin Module
The Worker Details Page in the Workforce Module

In the Admin Module:

Navigate to the Admin Module
Click on Workers
Find and select a worker
Look for the ‘Messaging’ Panel

In the Workforce Module:

Navigate to the Workforce Module
Click on Workers
Find and select a worker
Look for the ‘Messaging’ Panel

The panel will look like this:

How to Use the Worker Messaging Panel:

The fundamental use of the Worker Messaging component is to provide the ability to opt a worker in or out of a given site’s text messaging service.

1. Ensure the worker has a valid Phone Number

In order to use the Worker Messaging component, the worker must first have a phone number associated to them and that phone number must be valid.

A phone number is considered “valid” if it is a U.S. phone number from any of the 50 states or the District of Columbia. Phone numbers from U.S. territories (e.g., Puerto Rico, Guam, etc.) are not supported. You can use the North American Numbering Plan (NANP) Area Code search tool to check if a given area code is from any of the 50 states or the District of Columbia: https://secure.nanpa.com/public-report/npa/search-area-codes/section/query

If the worker does not have any phone number at all, the panel will look like this: If the worker has a phone number, but it is invalid, the panel will look like this: If the worker has a phone number AND the phone number is valid, the panel will look like this:

2. Opt the worker in or out of a site’s text messaging

You can use the toggle on the right hand side of a site item, to toggle the worker in or out of a particular site’s text messaging service. You can also quickly opt a worker out of ALL their site’s text messaging services by clicking on the ‘Opt-Out All’ option from the 3-dot menu. In either case, you will have to provide a reason for doing so.

If the reason for opting a worker in or out was due to someone else requesting it, include any information you are able to about the requestor (name, company, etc.) and if available, their Sitemetric ID.

Example of using the toggle:

Example of using ‘Opt-All Out’ button:

Some devices, during Installation Add, or by editing their Inventory → Equipment page, allow one to set either a Max RSSI or a Unique Scan Period. A given device will only ever have one or the other of these fields, and they are at the bottom of the Equipment page. Sitemetric Site Sensors all have a Max RSSI, as do some hand scanners. Some other hand scanners will get a unique scan period.

Max RSSI

RSSI stands for ‘received signal strength indicator.’ It’s a measurement of how much interference a receiver (like a Sitemetric Site Sensor) ‘sees’ between it and something it detects. Interference can be caused by distance, and also by structures. So if there was somehow no interference or distance, the RSSI is 0. Right next to the sensor would be -1: the sensor and a badge might be on the same table with little else around them / between them. -63.5 would be some interference, but the receiver would still detect a badge at approximately double that distance, assuming no large structures get in the way. -127 is the maximum amount of interference between the receiver and what it detects; any more interference and no detection would occur.

-127 is the default max RSSI; setting a number closer to 0 tells the sensor to ignore badges which are detected but further away, or more hidden by objects interfering with the radio signal between the receiver and a badge.

So a max RSSI of -63 tells the sensor anything further away than roughly half its actual maximum range can be ignored. Setting it to -31 tells the sensor to only count a detection if it’s within a quarter of its maximum actual range. Things beyond that quarter could be detected, with a different max RSSI, but will be ignored.

At present, max RSSI has to be a whole number. Setting it to 0 or -127 (or more) will simply use the device’s actual maximum detection range.

When adding some devices to an Installation, if the device can have a max RSSI, after device selection, a field will display either the current custom max RSSI, or simply indicate that there is none set, and the device will detect anything it can.

After a device is added to the installation, the max RSSI can be set on the device’s Equipment page.

Max RSSI on the Installation Add page. For this device, Max RSSI would also be editable on its Equipment page.

Unique Scan Period

Unique Scan Period (USP) lets a device ignore multiple requests to allow entry via the same badge. By default it is set to 0, which means one badge could be used at an entry point again and again to allow entry. By setting the USP to 1, the entry scanner must wait 1 minute to allow the badge to be used for re-entry. Set to 5, and five minutes must pass before the badge can be used to re-enter. We probably never want to set this number very high because someone might need to go back to their car or similar after entry, but this does help prevent one badge from being used by multiple folks to enter a site.

It does not affect using a badge for an exit scan.

Unique Scan period on the equipment’s profile page - this would also be seen during Installation Add.

Unique Scan Period on the Edit Equipment popup.

Technical Details

Product Requirements - V1 (ACO Focused)

Product Details - V2 (Back Office)

About the Feature

As a customer I want to be able to track the deliveries that are coming into my site. I want to be able to see the status of the delivery and other miscellaneous information about the information

V1 Timeline

Start Date — When: 04/23/2025; Status: STARTED/COMPLETE
POC Date — When: 05/14/2025; Status: COMPLETE
V1 Date — When: 05/14/2025; Status: COMPLETE
Alpha Group — When: 05/14/2025; Status: COMPLETE
Beta Group — When: 05/20/2025; Status: COMPLETE
GC Group — When: 06/01/2025; Status: ROLLOUT STARTED

Contacts:

Stakeholders: @Erik Hiller, @Collin Reilly, @Tristan Thomas, @Tyler

ACOs on Slack with delivery tracking experience:

@Mariam Imran, @Siawash Purdil @SukuRivera @Kevin Aguilera @Diego Bly @Ivette Mancha

Notes/Meetings about Feature

As a customer I want to be able to track the deliveries that are coming into my site. I want to be able to see the status of the delivery and other miscellaneous information about the information

How is it currently working?

ACO and site workers are typically doing this work by creating items inside of a Slack channel and posting pictures of what is being delivered, and then inside of the threads posting the in and out times.

!image.png

Through additional research we know some sites also have forms that are being used then inserted into Slack as well.

!image.png

Some sites are also using Pen and Paper as well:

!image.png

Goals:

We can track when a delivery got on site, and track when a delivery left the site
Unify how all sites are tracking deliveries
Allow reports to be generated around site deliveries
Get more involved in the back office by allow the back office to interact with the office as well as the front office.

Who is customer for?

The customer of this product will be both ACO Employees and GC contractors. Reason being:

ACO Employees- They will use this for auditing purposes for creating Delivery tracking, goal is to replace or improve the process posted above.

GC Contractors - This if for auditing who is coming in and out of the job site, we are currently doing this to an extent, but it is not automated at all. This allow for auditing purposes, but also will now allow for GC contractors to start getting insights into what is coming in and out, if something is delayed, something is early, etc. This will allow for additional product features in the future.

What will this product do?

The ultimate goal of this project is to unify and streamline how we are keeping track of deliveries. Right now this is a very manual process and has many failure points. This will allow GC’s and ACO’s to create Site Deliveries, which then be tracked when the deliveries come on sites.

This may allow users to be able to see deliveries we never received, missed, and help leave an audit trail.

There are two major flows we want to take account of:

ACO need to manually create deliveries and track when they were onsite/offsite and a optional photo of the delivery
GC need the ability to create deliveries before they reach the job site
- This allows tracking of: was delivery delayed, never delivered, early, etc.

What can we track?

To Company
From Company
Tracking Number/Provider
Driver
Onsite/Offsite times

Where to access the feature:

This feature will live inside of the Inventory Module , once the user clicks into the Module they should see a new option for Deliveries

Once you click into Deliveries the main page will have a list of all the deliveries that are within a given site. within this page towards the top we should also have an option to Add a Delivery

!image.png

How to Add a Delivery

To create a deliver you must have the following information:

Title
Status

Optional Data:

Tracking Number
Tracking Provider (If number is provided provider is required)
Expected delivery date
Description

How the Feature looks

While this is not necessarily the exact what it looks like something similar to this makes the most sense. There will be 3 tabs that user can click to see all deliveries, on-going, and finished.

We need the ability probably towards the top to Add Delivery

!image.png

Assumptions for V1:

The status will be manually changed by the user.
Status will move from Pending → Shipped → Onsite ⇒ Delivered
- While this is a manual process we probably will go from Pending to Onsite , in the future we probably will be able to introduce Shipped via API’s or other various intergrations. Or the user can manually change the status
Deliveries will NOT show items that in that delivery item.
The person changing the status is the person who signed_on (We may need to change this in the future)
If Delivery is created and completed in the same transaction, signed_on will be assumed to be the person creating it.
Driver_Name is not necessarily someone inside of our system so we will assume a free entry form for this and NOT require them to input them into the system.
We will only support 1 photo selection for now.

For On site Delivery tracking will assume:

The ACO worker will create a new delivery on the Fly with the status of Onsite
The ACO worker will fill out the onsite time.
ACO worker can continue to fill out the forms as expected and additional deliveries.

Features to consider for future iterations:

Delivery Acceptance (Have driver/worker sign for the order, confirm all the items were there)
Allow comments to be made on/about the Delivery
Reports for deliveries ontime/delayed/no delivered

Existing delivery products for reference

Previously in Delivery Tracking the feature was primarily focused on ACO’s being able to automate how sites are being able to track deliveries.

What does this mean?

Previously as mentioned here, there was no standardization meaning different sites were all tracking deliveries differently and there was no one way to recommend how we tracked deliveries.

Hopefully ACO’s are now getting some automations and we can now start focusing more on reports, and getting into what I want to call “The Back Office”. Meaning the feature currently is very front lines focused of x, y, and z came. With that it opens up the new opportunities that allows for custom reports like Daily Deliveries , Weekly Deliveries , In Route Deliveries and many more!

Why does that matter? The Back Office.

Notifications V2 (Texting)

We will able to get list from the GC

Calendar View (View all the views of schedules)

Different iteration ability to manage the deliveries

Reporting:

Email Reports, yesterday deliveries (include it in the daily report)

What do we do for sites that are no using site deliveries
- Should we do a separate report (separate excel file), and include it in the daily report email
- *Or we add it as a widget to the Daily Report + dashboard*
  - *NOTE: This would only work for sites using that exact report and not a forked version, we want to try and avoid updating all custom versions of the report.*
  - *Could include it daily report but only in the daily reporting + going forward (meaning lets not update all custom daily reports)*
- Create a new report that is a standalone report but is sent daily but not necessarily `Daily Report`. Could turn this off and on super easily. (Reports team top recommends)
  - Do we need it visible inside of the Reports table in app
  - Would we be ok waiting a month or two until Dashview is ready

Picture

Picture of Delivery

The relationship of Deliveries will be the following:

Site - has many → Deliveries

Deliveries - belongs to → Site

Deliveries - has many → DeliveryStatusHistory

DeliveryStatusHistory - belongs to → Deliveries

ERD Explained

Deliveries has_many → DeliveryItems

has_many → Attachments (These are

has_many → Notes (These are notes about the orders or what some may call comments

has_many → DeliveryStatusHistory belongs_to → Site

belongs_to → Company (To Company, and From Company)

site_id - This is the site the Delivery belongs to
to_company_id - This is the company the delivery is for. (Or Receipt)
from_company_id - This is the company the delivery is from. (Or Sender)
signed_by - This is the worker who acknowledged the order.
driver_name - This is an optional field where we can track the driver who is driving or delivery the package.
tracking_provider - This is the provider who is delivering the product, Fedex, UPS, Freight, etc.
tracking_number - This is the tracking number or reference number for the order.
signed_on - This is the date of when the signed_by signed for the order.
onsite_time - This is the time the driver came onsite to deliver the site.
offsite_time -This is the time the driver left the site after the delivery.
status - This is the current and live status of the delivery. (ex. Shipped , Pending , Onsite , Delivered)

DevlieryIltem

belongs_to → Delivery

delivery_id - This is the delivery it belongs to
item_name - The item that we are expecting
quanity - The number of that item we are expecting

DeliveryStatusHistory

belongs_to → Delivery

has_many → Notes (We may want to put a note of why we are moving the status)

delivery_id - This is the delivery it belongs to
status - This was the previous status it was

System Flow

Flow 1 - Delivery was created before actually being delivered

This flow is the GC is inputting data into the system before it reaches the jobsite, this will be the “preferred” method as it will expedite ACO’s job and ensure better/more accurate data.

This also will allow them to do additional reporting on delieveries that would otherwise not be possible.

(You can imagine a world where we can do internal ranking of companies and if they are usually early, late, on time, etc)

Flow 2 - Delivery is created on the fly on the job site

This will be the flow where there is nothing inside the system and we need to accept the delivery. This will allow the onsite ACO to create the delivery, take notes of the onsite/offsite time, and add additional informations.

Feature Access

In order to have access to this feature inside of the app you need to have the following features assigned to your user:

admin-deliveries - This is an admin privilege, your must have this or superadmin to be able to access the feature.

site-deliveries - This is customer facing UI that will allow the user to access site deliveries.

Supporting Endpoints

Common API
- GET sites/:site_id/deliveries
  - Will return a list of all deliveries that are associated with the site
- POST sites/:site_id/deliveries
  - Will return a list of all deliveries that are associated with the site
- GET sites/:site_id/deliveries/:delivery_id
  - Will return a specified delivery associated with a given site.
- PUT sites/:site_id/deliveries/:delivery_id
  - Will allow the user to update the delivery
- DELETE sites/:site_id/deliveries/:delivery_id
  - Will allow the user to delete the delivery
- GET sites/:site_id/deliveries/:delivery_id/notes
  - Will allow the user to get notes associated with that delivery
- POST sites/:site_id/deliveries/:delivery_id/notes
  - Will allow the user to add a note associated with a given delivery
- GET sites/:site_id/deliveries/:delivery_id/attachments
  - Will allow the user to get attachments that are associated with the deliveries
- GET sites/:site_id/deliveries/:delivery_id/attachments/:attachment_id
  - Will allow you to fetch the attachment for specified delivery.
- POST sites/:site_id/deliveries/:delivery_id/attachments
  - Will allow the user to add attachments associated to a delivery

Context: How is Safety related data currently handled?

Safety data is fragmented
Workers may or may not have required documentation (certifications, PTPs, etc.).
There is no centralized view for GC or Safety Inspectors to audit current safety state.

Goals:

Provide a centralized “Safety Dashboard” within the Safety Module.
Introduce a “Safety Score” to summarize readiness and compliance.
Include modular UI panels (widgets) to surface key safety indicators:
- % of workers with all required certs
- Recent PTPs submitted?
- Active safety notes/opportunities
- Expiring certs or missing docs
Build flexible architecture for future additions (comments, notes, historical tracking)

Who would it serve?

Safety Inspectors – Want visibility into current safety compliance across the site.
GC Admins/Managers – Need quick insights for audits and risk analysis.
Field Workers (limited) – May view high-level safety status (if allowed).

Design Ideas:

Keep UI modular (inspired by Site Pulse)
Add search bar
Respect terminology (“notes” not “incidents”, “opportunities”)
Don’t show raw event logs unless explicitly scoped

Other Ideas / Concepts:

Idea:

What if for the safety dashboard/section, if we had a section where you could see all the worker certifications and who’s are expired or don’t have one, and who’s are going to expire soon, if the certification is online based, there could be a mechanism that maybe integrated with messaging where a user (like superintendent) could send out a message to all those with the expired or about to expire certification with a custom message and a link to renew their certification. Or possibly something along these lines this

Other Information

Safety Competitor Features

Safesite — Key Features: Safety Score / Safety Index Score; Potential Client Benifits: Could provide a quick (fairly) reliable insight for client on the overrall safety
HCSS Safety — Key Features: Certification Tracker / Insights; Potential Client Benifits: Better certification visibility and faster certification insights
AWS — Key Features: Widgets; Potential Client Benifits: AWS has a nice Widget View on the main dashboard which can be helpful for offering quick insights into different parts of data

Safety_Competitor_Features.csv

Iterations

Safety Dashboard - Version 1

This document outlines the MVP for the first iteration of a Safety Dashboard in the Safety Module. The proposed main structure is a dashboard view featuring various widgets.

Safety Index Score

The Safety Index Score provides a quick insight into the overall safety of a given site.

This score could be derived from Worker Certifications.

Safety Compliance

This widget gives an overview of how compliant workers are based on their certifications.

Clicking on the Safety Compliance widget takes the user to a detailed view showing:

Workers with valid certifications
Certifications about to expire
Expired certifications

A messaging component may be integrated into this page to allow users to:

Send text messages to workers
Use filters to target specific groups (e.g. workers with expired certs)

Recent Activity Widgets

Additional larger widgets on the main dashboard will show recent activity from other Safety Module sections:

Recent Safety Scan Records
Recent Safety Conditions
Recent Mustering Events
Recent Roll Call Events

Clicking any of these will navigate to their respective detail pages.

UI Demo

Safety Dashboard Page

Safety Dashboard Page. Showcasing the Recent Activity widgets

Safety Compliance Details page. Detailed widget views of worker certifications

Messaging component in the Safety Compliance Details page

Questions

Should a Safety Index score be included and if so, what data should it be derived from? Or in other words, how should a Safety Score be calculated.
Should a Safety Compliance widget be included? And what data should it be derived from?

Current relevant tables

safety_events
safety_notes
safety_event_attachments
worker_certifications
worker_certification_types
mustering_events
mustering_event_devices
events

Zone Restriction is a system to allow only certain workers access to a specific zone. The configuration requires two steps:

1. Enable zone restriction on the zone

Navigate to the zone you’d like to restrict under Inventory | Zones, and enter Edit mode. Enable the Restricted toggle, which will show the Scanner Label input.

IMPORTANT: the Site ID will automatically be prepended to the Scanner Label, so you should NOT add it

Save your changes and the zone will now be restricted. Only workers who have the same label as configured on the zone will be allowed to enter:

2. Add zone label to workers

Once you have enabled Zone Restriction with a custom Scanner Label on the Zone, you will then need to add the Scanner Label to at least one worker who needs access.

IMPORTANT: if you don’t add the Scanner Label to at least one worker, the Scanner device won’t be updated with the configuration, and won’t apply the restrictions

Save the label and ensure it’s been added to the worker:

At this point, the Zone Restriction is enabled and with at least one worker with the Scanner Label, the Scanner device will be updated and should deny access to all workers except those who have the Scanner label.

Implement common-api endpoint for all safety notes for a worker — Status: Merged, not in prod
Components for Admins to create/edit/view/delete safety notes — Status: merged, not in prod
Components for workforce user to see worker’s site-based notes, create/edit/delete notes for that site — Status: merged, not in prod
Component wired and tested for worker search — Status: merged, not in prod
Product Feature for non-admin users - superintendents, some of safety team. Discovery and assignment of new product feature. — Status: wired into shell-app and common-api. Merged, not in prod
Move over safety-api code to common-api — Status: In progress
AWS changes to aim safety-notes traffic at common api
delete safety-api repo

Current Usage:

Safety notes are accessible only in the Safety module’s Safety Scanner. An admin or user with the right product features can create, edit, delete, and see a worker’s safety notes, for the selected site.

Access Control For New Feature

Any Sitemetric employee, or anyone with the product feature ‘safety-notes,’ should be able to see notes for sites they have access to.

Expected Expansions: Safety Notes in Worker Profiles.

A component in Workforce → Workers → will display all the worker’s safety events for the current site in a list format, and will allow viewing details of any safety note, editing / deletion as well. It should also be possible to create a new safety note. Safety Notes could be edited here by non-admins, but siteId cannot change.

The non-admin version / config of this component should also show up in the worker’s summary seen via Worker Search (top right magnifying glass)

A similar component in Admin → Workers → displaying all the worker’s safety notes, across all sites. Admins can edit/create/delete as well, can pick any site.

Edit: Initially thought the site picker could be limited to the worker’s sites. Can’t easily do this, so Admins can pick from any site. Also expected, based on the existing safety-api, that admins can change a safety note’s site id. This does not seem to work in the dev env; it’s likely the admin would have to delete and recreate, which is not ideal. When we destroy safety-api, we will change the safety note edit to allow changes to the site id.

We need a modal to view the details of a safety event: creation date time, the note’s text, and the site’s short name (Edit: I removed createdBy name. We can re-add if it’s desired). That modal or a similar one will allow editing these, with the admins allowed to pick a valid site for the worker.

No DB changes are expected for this.

Current Product Features / user access control

Right now seeing the Safety Notes requires the Safety product feature, which is given to the Badgers, Clients, DCOs, and the shell app’s SitemetricRole.Display, Reports, and Operations.

Otherwise we can add new product features as needed.

Technical Requirements

Shell changes: New components, wired into to Workforce and Admin, handle creating, editing, deleting safety notes. List them out in such a way mobile and web can view at least *some* of the text of the note. Arrange chronologically, allow admins to see site short name for each note and sort by that as well, if need be.

New API endpoint to get all worker notes, regardless of site - for the Admin module. (Branch exists and tested, starting to develop components against it) (written for common-api, nothing new for safety-api if I can help it). (Pagination is not done yet.) (Integrating locally w/ local shell)

New product feature? Or safety for regular users (+ workforce to see the workforce module). SuperAdmins and regular admins w/ the AdminWorkers feature could see the safety notes across all sites.

No db changes expected for this work.

gitlab / AWS changes: sunset safety-api, a repo.

Sunset safety-api, move its unique code to common-api

Sunset the entire safety-api repo, move its 2 controllers (safety notes and safety events) to common-api. Or at least, move over the safety notes entirely. Seems they could live under the worker and just have a required siteId. The safety events sound like they’d depend more on the site than a given worker, but that is conjecture at present.

Otherwise / either way, the existing api in safety-api will allow creation, editing, and deletion of safety notes sufficient for admins and non-admins. Probably want to remove the ability to update the createdBy field, for record-keeping purposes.

Safety Note From the API

{
	"id": "R0PYF2VT3W",
	"createdAt": "2025-03-14T21:46:13.000Z",
	"createdBy": "BUVGK3MDVW",
	"siteId": "GA05298283",
	"siteShortname": "Charlie Site of Dreams",
	"text": "No PPE while on site.",
	"workerId": "5UASKBMTVN"
}

Right now we allow edits to safety notes, via the safety-api application / repo. We allow createdBy to be edited - I assume we don’t want that for anyone, honestly. Admins shouldn’t be able to change that. I believe all that is needed would be to edit the update DTO for the safety note. Admins and Superadmins could change the siteId - but regular users in the Workforce module shouldn't get that. A given worker has their site access listed in api/v4/workers/ /siteaccess

Product Feature for Non Admin Users (Regarding Worker Safety Notes)

-=-=-=-=-=-=- End Of File

This is a product feature that will allow for customers to be able to ban workers at either a Customer ,Owner , or Site level.

How to use Ban Worker Feature (Customer Support/Admins)

Discovery & Requirements

Identify the problem or opportunity the feature addresses
Define clear success metrics for the feature (how will you know it worked?)
Gather input from stakeholders (users, customers, support, sales)
Document user stories and acceptance criteria
Prioritize requirements (must-have vs. nice-to-have)
Create mockups or wireframes for UI changes
Document any API requirements or changes

Technical Planning

Conduct technical feasibility assessment
Identify potential architecture impacts
Document API changes or additions
Plan database schema changes if needed
Identify performance considerations
Determine security implications
Consider backwards compatibility requirements
Evaluate potential technical debt
Perform complexity and effort estimation
Define milestones for larger features

Design & Documentation

Document the technical approach or design
Create sequence diagrams for complex flows
Define data models and state transitions
Document any dependencies on other systems or teams
Identify potential risks and their mitigations
Prepare API documentation updates

Implementation

Break work into manageable tasks
Create feature branch/implement branching strategy
Implement code with appropriate test coverage
Address edge cases and error handling
Perform code reviews
Update documentation (inline code, READMEs, wikis)
Ensure logging is adequate for debugging
Implement any necessary monitoring/observability

Testing

Write unit tests
Create integration tests
Perform manual testing
Test edge cases and error scenarios
Verify performance meets requirements
Test for accessibility compliance
Test for security vulnerabilities
Conduct UX/usability testing if applicable

Deployment

Create or update deployment plan
Define rollback strategy
Create database migration scripts if needed
Prepare feature flags or toggles if needed
Document any configuration changes
Plan timing to minimize user impact
Consider staging/canary deployments for high-risk changes

Post-Deployment

Monitor feature usage metrics
Monitor for unexpected errors
Gather user feedback
Document lessons learned
Plan follow-up improvements
Update knowledge base or support documentation
Celebrate the successful implementation!

For Complex Features

Consider breaking into smaller, more manageable phases
Plan for incremental delivery of value
Define clear handoffs between team members if needed
Schedule regular check-ins to track progress and address blockers

App Documentation — Feature Reference

Reference guide for admin, messaging, inventory, safety, and workforce features across the Sitemetric app

Admin

Forms

Inventory

Messaging

Reports

Safety

Scanner

Training

Workforce

General

🔐What is authentication?

❓How do we use Authentication?

How to configure a user w/ Password:

Configuring a User with SSO with their own provider:

💻 How to Login in with SSO:

Quick Demonstration of How to Use:

Availability:

Where to Find the Site Access Sync Tool:

How to Use the Site Access Sync Tool:

Quick Demonstration of How to Access and Use:

Availability:

Where to Find the Site Access Sync Tool:

How to Use the Site Access Sync Tool:

How do messaging work?

How to Enable Messaging

How Numbers Get Enabled

Availability:

Where to Find the Worker Messaging Panel:

In the Admin Module:

In the Workforce Module:

How to Use the Worker Messaging Panel:

1. Ensure the worker has a valid Phone Number

2. Opt the worker in or out of a site’s text messaging

Max RSSI

Unique Scan Period

About the Feature

V1 Timeline

Contacts:

How is it currently working?

Goals:

Who is customer for?

What will this product do?

Where to access the feature:

How to Add a Delivery

How the Feature looks

Assumptions for V1:

For On site Delivery tracking will assume:

Features to consider for future iterations:

Existing delivery products for reference

ERD Explained

System Flow

Flow 1 - Delivery was created before actually being delivered

Flow 2 - Delivery is created on the fly on the job site

Feature Access

Supporting Endpoints

Context: How is Safety related data currently handled?

Goals:

Who would it serve?

Design Ideas:

Other Ideas / Concepts:

Other Information

Iterations

Safety Index Score

Safety Compliance

Recent Activity Widgets

UI Demo

Questions

Current relevant tables

1. Enable zone restriction on the zone

2. Add zone label to workers

Current Usage:

Access Control For New Feature

Expected Expansions: Safety Notes in Worker Profiles.

Current Product Features / user access control

Technical Requirements

Sunset safety-api, move its unique code to common-api

Safety Note From the API

Discovery & Requirements