Usage Records

Overview

Usage Records are the authoritative record of how resources, processes, configurations, and materials are actually used within Colabmacs.
They sit at the center of analytics, reporting, and billing, and represent completed usage — not intent or scheduling.

To understand Usage Records clearly, it helps to distinguish three related concepts:

Booking / Reservation
        ↓
Usage Session (live)
        ↓
Usage Record (persisted)
        ↓
Charge (optional)

Some usage records may also be created by a Subscription Cycle rather than a live usage session.

• Bookings represent intent to use something.
• Usage Sessions represent a live interaction (check-in → check-out).
• Usage Records represent the finalized, stored record of what actually happened.
• Charges are derived from usage records when billing rules apply.

Core Concepts

Usage Sessions vs Usage Records

• Usage Session

  • A live, in-progress interaction
  • Starts when a user checks in or activates a resource/process
  • Ends when the user checks out or completes the action
  • May generate one or more usage records

• Usage Record

  • A persisted record created when a session completes (or manually by an administrator)
  • May also be created automatically from a recurring subscription cycle
  • Used for:
    • Billing and charge generation
    • Reporting and analytics
    • Audit and compliance
  • This is the source of truth for system metrics

Info

When updating or correcting usage data, administrators should generally edit Usage Sessions directly. This allows the system to automatically recalculate and update associated usage records and charges, ensuring consistency across the board.

The Usable Model

Every Usage Record is associated with exactly one Usable.

A Usable is any entity that can independently generate usage and (optionally) charges.

Supported Usables

Usable Type	Description
Resource	Physical equipment or spaces
Process	A defined recipe or workflow selected at booking time
Configuration	A specific setup or mode applied during use
Material	Consumables recorded via Material Usage

Info

A single usage session may generate multiple usage records — for example:

• One record for the resource
• One record for the selected process
• One record for the applied configuration

Recurring subscriptions can also generate usage records for supported billable items without a live session.

Viewing Usage Records

Navigate to Billing → Usage Records.

The listing provides both high-level insight and detailed drill-down. You may also visit Resource → Usage Records or Materials → Usage Records to see a pre-filtered list of records.

Dashboard Metrics

• Average Daily Usage
• Trends over time
• Aggregations based on the selected time window

Table Highlights

Common fields include:

• User
• Project
• Usable (Resource / Process / Configuration / Material)
• Tags
• Start & End timestamps
• Duration
• Associated booking (if applicable)

Usage Record Detail View

Selecting a record opens the full detail view.

Core Details

• Usable – What was used
• User – Who performed the usage
• Project – Where costs are accumulated
• Tags – Optional labels used for grouping, filtering, workflow classification, or charge-rule targeting
• Started / Ended – Actual timestamps
• Duration – Calculated automatically
• Usage Session – Link to the session that generated this record (if applicable)
• Source – The origin of the record (e.g., usage session, subscription cycle, manual entry, etc...)

Tags

Usage Records can be tagged directly.

This gives administrators a flexible way to mark and organize arbitrary groups of usage, for example:

• in-kind
• failed-run
• internal-review
• no-charge

Tags on Usage Records are useful for:

• Filtering and reviewing related groups of records
• Operational follow-up and exception handling
• Applying Charge Rules through tag-based targeting

This means a tag is not just descriptive metadata. It can also affect how a Charge is generated when a Charge Rule is attached to that Tag.

Parameters

Usage Records can capture Parameters such as:

• Temperatures
• Speeds
• Pressures
• Process-specific values

Parameters create their own type of records and are attached to the Resource at usage time.

Materials

Material consumption can generate a usage record:

• Quantity
• Unit of measure
• Material reference

This enables accurate cost attribution alongside time-based usage.

Comments & Audit

• Free-form comments for context or exceptions
• Action Events provide a full audit trail of changes

How Charges Are Generated

Charges are derived from Usage Records, not bookings.

Charge Lifecycle

1. Usage Session completes
2. One or more Usage Records are created
3. If billing conditions are met, a Charge is generated automatically

Subscription-generated usage records follow the same charge lifecycle once the usage record has been created.

If a Usage Record has Tags, any Charge Rules attached to those Tags are included when the Charge is generated.

Billing Requirements

A charge will be created only if:

• The Usable has an associated Rate
• The Rate exists in the Rate Group assigned to the Project
• The Usage Record does not already have a charge

Example: Tagged In-Kind Usage

A common workflow is to tag a Usage Record as in-kind and attach a Charge Rule to the in-kind Tag that caps billed quantity to 0.

This allows the record to:

• Remain attached to the correct Project
• Preserve the full operational and historical usage record
• Generate a zero-value Charge instead of a normal billable amount

Charge Regeneration

Editing a Usage Record will trigger regeneration of charges. If a charge already exists, it will be updated to reflect the new usage details. If a charge has been marked as paid, an offset charge will be created rather than modifying the original charge.

see Charge Regeneration for more details on charge editing and adjustments.

For full details, see the Billing Guide documentation. For recurring scheduled billing inputs, see Subscriptions.

Processes & Configurations

Process Usage

• Processes are selected at booking time
• Each process creates its own Usage Record
• Processes may:
  • Require training
  • Have independent rates
  • Be analyzed separately from the resource

Configuration Usage

• Configurations also generate distinct Usage Records
• This allows:
  • Tracking setup effort
  • Enforcing configuration-specific rules
  • Applying configuration-specific billing (where enabled)

Lenses (Advanced Views)

Lenses provide powerful, purpose-built views into usage data.

They allow administrators to:

• Reorder data by:
  • Total usage time
  • Number of usage records
• Group usage by:
  • User
  • Project
  • Resource
• Filter by:
  • Date ranges
  • High-usage thresholds

Common Lens Examples

• Top Usage by User
• Top Usage by Project
• High Duration Sessions
• Usage Trends Over Time

Tips

Lenses are read-only analytical tools. They do not affect permissions or billing behavior.

Best Practices

• Ensure users check in and out promptly
• Record parameters consistently for repeatability
• Attach material usage where applicable
• Review unbilled usage regularly
• Use lenses for operational and financial insight

Summary

Usage Records are the foundation of Colabmacs operations:

• They represent what actually happened
• They connect users, projects, and billable activity
• They drive analytics, reporting, and charges

Understanding the flow from Usage Session → Usage Record → Charge is essential for effective system administration.