Asset access URLs

Permanent short URLs for QR stickers — generate, claim, and wire workflows.

Asset Permanent Access URLs (Short URLs)

Permanent access URLs (also called “short URLs” or Asset Access URLs in the admin UI) provide a durable, physical way to link QR stickers to an asset. Once claimed, a code grants long-lived access so visitors can start work without a prior task assignment.

End-user overview: For plain-language use cases (dispatch vs self-service vs public feedback), see QR codes and asset tags — use cases.

Short URLs work with two workflow patterns (see Workflow Types):

Self-startable workflows — field engineers and other visitors with a profile open the asset page and pick a workflow from Start a New Task (e.g. routine inspection, filter replacement).
User workflows — anonymous public flows, often wired for direct launch from the QR (e.g. Send feedback about this place, Report an issue with this charger). No sign-in; submissions land in the asset Feedback tab.

Use case (self-startable): A technician scans a sticker on an HVAC unit and starts Monthly Visual Inspection from the asset page.

Use case (user workflow): A visitor scans Something wrong? Tell us on a kiosk; the QR opens the feedback form immediately—no asset picker, no login.

How It Works

The Concept

A permanent access URL is a short, human-readable URL that:

Points to a specific asset (once claimed)
Never expires
Can be encoded as a QR code for physical labeling
Routes scanners to the asset (and optionally straight into a chosen user workflow)

URL Format

Short URLs follow the format:

https://mntl.at/PPPABC123

(Production uses config.qr_service_host, currently mntl.at; development often uses qr.localhost.)

Where:

The host is the environment’s QR service domain
PPP is a 3-character organization prefix (automatically assigned, e.g., “ACM” for “Acme Corp”)
ABC123 is a 6-character unique code using an unambiguous character set

The character set excludes visually similar characters (0/O, 1/I/l) to ensure codes are easy to read and type manually if needed.

Workflow for Administrators

1. Generate a Batch of Short URLs

Administrators generate short URLs in batches before physical labeling:

Go to Admin → Asset Access URLs
Click Generate new access URLs
Enter the number of codes to generate (1–1024 per batch)
Optionally give the batch a name (e.g., “Building A - Floor 2”)
Optionally select a published User Workflow to pre-assign to every URL in the batch (direct launch when scanned—ideal for feedback or CTA stickers)
Click Generate

Each batch is assigned a unique batch number in the format PPP-YYYY-N (e.g., “ACM-2026-1”), where PPP is your organization prefix, YYYY is the year, and N is a sequential number within that year. The system also tracks which user generated the batch.

2. Export for Printing

After generating, open the batch and export labels for your printer:

Action	Format	Use when
Export CSV	CSV	Custom label tools, legacy `qr_generator` imposer, or spreadsheets
Download Batch PDF	PDF (async)	One file with one printable label per URL in the batch
Download label PDF (per row)	PDF (async)	A single URL’s label only

PDF exports are generated in the background (ShortUrlPdfExportJob). The admin UI polls until the file is ready, then downloads it via a presigned URL. Labels use an SVG template at app/services/short_url_pdf/template.svg (55×91 mm cards on A4 with cut marks): required ids #qrcode (rect), #url, #batch_id (text). Runtime fills placeholders (e.g. {{url}}, {{batch_id}}) and preserves Inkscape layout attributes (text-anchor, tspans, fonts). Optional #url attribute data-max-width (mm) enables shrink-to-fit. The scan URL uses config.qr_service_host (same host as the live resolver).

The CSV includes:

Organization name
Batch number
Code (the full short URL code)
Status (unclaimed/claimed/invalidated)
Asset information (once claimed)

3. Create Physical Labels

Common approaches:

QR Code Stickers: Print durable stickers with QR codes encoding the short URL. Apply to asset housing, control panels, or other accessible locations.
Asset Displays: For assets with screens, display the QR code digitally (e.g., on an EV charger screen or kiosk).
Documentation: Include in user manuals, maintenance guides, or posted instructions kept with the asset.

Tip: Use weatherproof labels with UV protection films for outdoor assets. Consider placing multiple labels on large assets for convenient access. Multiple non-identical short URLs can be active for an asset simultaneously.

4. Claim (Associate with Asset)

Before a short URL works, it must be “claimed” — associated with a specific asset:

Option A: Scan and Claim (Recommended)

While logged in to the admin interface, physically visit the asset
Scan the QR code with your phone
The system detects you’re an admin with an unclaimed code
Select the asset from the dropdown to associate the code

Option B: Manual Claim via Admin UI

Go to Admin → Asset Access URLs, expand the batch, and use Claim on an unclaimed row
Select the asset (and optionally a User Workflow for direct launch)

You can also set or change the direct-launch workflow on a claimed URL from the row actions without re-claiming.

Once claimed, the short URL creates a permanent, non-expiring access key linked to that asset.

The claim process allows pre-printing stacks of asset tags without having to keep track of which tag is intended for which asset. This also means that if an asset tag gets lost or destroyed a field engineer can easily attach a new one without requiring an extra truck roll.

5. Wire a User Workflow (optional)

For feedback or public CTAs, associate a published User Workflow with a short URL (at claim time, when generating a batch, or via Set workflow on a claimed row). When that URL is scanned:

The resolver redirects straight to the workflow launch URL (no asset landing page first).
The visitor completes the form anonymously; the task appears under Admin → Asset → Feedback.

Clear the workflow to return to normal asset access (self-startable list + asset details). Only published User Workflows from the same organization are allowed.

How Scanners Use Claimed Short URLs

Behavior depends on whether a User Workflow is wired to the code.

A. No direct-launch workflow (default)

Typical for maintenance stickers used by technicians:

Scan → redirect to the asset page (permanent access key).
See asset info and Start a New Task (published self-startable workflows for the org).
Pick a workflow; a task is created (field engineer profile required for maintenance/self-start flows).

B. User Workflow wired (direct launch)

Typical for Send feedback about this place, Report an issue, or demo CTAs:

Scan → redirect directly into that workflow (launch URL with access key + workflow id).
No login; no profile prompt for user workflows.
Submission lands in the asset Feedback tab (identity recorded silently if the visitor already has a field engineer profile).

If the same workflow is also marked self-startable, enrolled technicians can still start it from the asset page; the QR path remains the anonymous direct-launch experience.

Integration with Workflows

Short URLs supply the physical entry point; workflows supply instructions and forms. Combine them as follows:

Goal	Workflow setup	Short URL setup
Technician self-serve maintenance	Published, `self_startable`, not user workflow	Claim to asset; no direct-launch workflow
Public feedback / issue report	Published user workflow (often also self-startable)	Claim to asset; set user workflow on URL or whole batch
Mixed site (techs + public)	Both types published	Different batches or per-URL workflow assignment

Examples:

Contractor scans a unit sticker → asset page → starts Filter Replacement (self-startable, maintenance log).
Visitor scans Rate this location → Send feedback about this place opens immediately (user workflow, feedback log).
Operator pre-generates a batch of 50 feedback QRs for a rollout, exports a collated batch PDF, and applies stickers before claiming each code on site.

See Self-Startable Workflows and Workflow Types for flag details and admin surfaces.

Managing Short URLs

Viewing Short URLs for an Asset

Go to Admin → Assets
Select an asset
View the Short URLs section

This shows all short URLs associated with the asset, including their status.

Viewing Unclaimed URLs

Expand a batch under Admin → Asset Access URLs to see unclaimed rows, or scan an unclaimed code while logged in as an admin to open the claim flow.

Invalidating a Short URL

If a short URL needs to be deactivated (e.g., label was destroyed, asset decommissioned):

Go to Admin → Asset Access URLs
Find the code (filter by asset if needed)
Click Delete/Invalidate

What happens:

If unclaimed: The code is permanently deleted
If claimed: The code is soft-invalidated (record kept for audit), and the associated access key is revoked

After invalidation, scanning the QR code returns a 404 error.

Security Considerations

What Short URLs Allow

Accessing the associated asset via a permanent access key
Starting any published self-startable workflow from the asset page (when no direct-launch user workflow is set)
Running a wired published User Workflow in one step from the QR (direct launch)
Viewing basic asset information (asset-page path)
Recording work and completing forms per workflow type
Viewing asset diagnostics when an IoT integration is enabled (asset-page path)

What Short URLs Do NOT Allow

Administrative access
Viewing or modifying other assets
Launching draft or unpublished workflows
Wiring non–user-workflows for direct QR launch (maintenance-only workflows must be started from the asset page after self-start rules apply)
Any admin panel functionality

Physical Security

Since short URLs provide permanent access, physical security of the labels matters:

Place QR codes where authorized personnel can access them
For high-security assets, consider placing codes inside access panels or enclosures
Immediately invalidate any codes if labels are stolen or unauthorized access is suspected

Best Practices

Labeling Strategy

One code per asset: Usually sufficient for most assets
Multiple codes: Consider for large assets with multiple access points
Spare codes: Generate extras in each batch for replacements

Batch Organization

Use the batch name field for deployment location or purpose (e.g., “Building A - Floor 2”, “Outdoor Units”)
The batch number automatically includes the year, making it easy to track when batches were created
Export and archive CSVs before deployment
Track which batches are deployed where

Workflow Design

Self-startable (technician-facing):

Clear instructions; optional triage (“Is this an emergency?”)
Accurate required-tools lists

User workflows (public-facing, often direct-launched from QR):

Short forms; plain language (e.g. feedback about a place or asset)
Thank-you / completion messaging—visitors are not routed into maintenance task history
Publish before deploying stickers; use batch pre-assign or per-URL workflow when printing a dedicated feedback run

Frequently Asked Questions

Can I reuse a short URL code if I invalidate it?

No. For security once invalidated, a code cannot be reactivated. Generate new codes if needed.

What happens if someone scans an unclaimed QR code?

If they’re not logged in as an admin, they see a 404 error. If they are logged in, they’re prompted to claim the code.

Can I change which asset a short URL points to?

Not directly. Invalidate the current short URL and claim a new one for the different asset. For special cases (eg. systematic mislabeling of assets) contact support.

How many short URLs can I create?

Up to 1,024 per batch, with no limit on the number of batches. Codes are globally unique, so you’ll never run out.

Do short URLs work offline?

No. The user needs internet connectivity to access the asset page and start workflows.

Can I customize the QR domain for white-labeling?

Contact our support and we will evaluate your needs.

Workflow Types — Self-startable vs user workflows and short URL wiring rules
Self-Startable Workflows — On-asset Start a New Task flows
API reference (short URLs) — see the API reference link in the docs sidebar
Admin User Roles and Permissions — Who can manage access URLs

Last updated on May 28, 2026