Global WatchGlobal Watch Docs
Use Cases

Asset Tracking

Asset Tracking Use Cases

This document describes real-world scenarios for asset tracking in Global Watch, including creating assets, managing templates, and working with the asset catalog.

UC-201: Create Asset

Description

User creates a geolocated asset within a project. Assets represent physical items like trees, equipment, structures, or markers that need to be tracked.

Actors

  • Primary: Project Member
  • Secondary: Map System

Preconditions

  • User is authenticated
  • User has access to the project
  • Project exists and is active

Postconditions

  • Asset created with unique ID
  • Asset location stored as geometry
  • Asset visible on project map
  • Usage tracking updated

Main Flow

  1. User navigates to project map
  2. User clicks "Add Asset" button
  3. User clicks on map to set location
  4. User enters asset details:
    • Name: "Tree #1234"
    • Type: Tree (from template)
    • Description: Optional notes
  5. System validates asset data
  6. System creates asset record
  7. System updates map display
  8. Asset appears on map with marker

Alternative Flows

A1: Use Template

  1. User selects asset template
  2. Form fields pre-populated from template
  3. User modifies values as needed
  4. Continue from step 5 of main flow

A2: Use Catalog Item

  1. User selects template type
  2. User selects catalog item
  3. Form fields pre-populated from catalog
  4. User modifies specific values (e.g., actual measurements)
  5. Continue from step 5 of main flow

Business Rules

IDRule
BR-AST-001Asset must have valid geometry
BR-AST-002Asset name required
BR-AST-003Template fields validated against schema

UC-202: Create Asset Template

Description

Account owner creates a custom template for tracking specific types of assets. Templates define the fields and validation rules for assets.

Actors

  • Primary: Account Owner/Admin

Preconditions

  • User is authenticated
  • User has account owner or admin role
  • User is on account settings page

Postconditions

  • Template created and available
  • Template fields defined
  • Template available for catalog items and assets

Main Flow

  1. User navigates to Account Settings → Templates
  2. User clicks "New Template"
  3. User enters template details:
    • Name: "Water Source"
    • Description: "Track water sources like rivers, lakes, and wells"
    • Icon: "droplet"
    • Color: "#3B82F6" (blue)
  4. User adds fields:
    • Type (select): Options = ["River", "Lake", "Well", "Spring", "Pond"]
    • Flow Rate (L/min) (number): Min = 0
    • Quality (select): Options = ["Excellent", "Good", "Fair", "Poor"]
    • Last Tested (date): Required = false
    • Notes (text): Required = false
  5. User arranges field order via drag-and-drop
  6. User clicks "Save Template"
  7. Template appears in account templates list

Alternative Flows

A1: Duplicate Template Name

  1. User enters name that already exists
  2. System shows error: "A template with this name already exists"
  3. User enters different name
  4. Continue from step 4 of main flow

A2: Invalid Field Configuration

  1. User configures field incorrectly
  2. System shows validation error
  3. User corrects field configuration
  4. Continue from step 5 of main flow

Business Rules

IDRule
BR-TPL-001Template name must be unique within account
BR-TPL-002Field names must be unique within template
BR-TPL-003Global templates cannot be modified
BR-TPL-004At least one field required

Field Types

TypeDescriptionOptions
textSingle-line text inputmaxLength
textareaMulti-line text inputmaxLength
numberNumeric inputmin, max, step
selectDropdown selectionoptions array
dateDate picker-
booleanCheckbox-

UC-203: Populate Catalog

Description

User adds items to the asset catalog for quick asset creation. Catalog items are pre-configured instances of templates.

Actors

  • Primary: Team Member (with projects.manage permission)

Preconditions

  • User is authenticated
  • User has projects.manage permission
  • Template exists (global or account)

Postconditions

  • Catalog item created
  • Item available for asset creation
  • Item grouped by template type

Main Flow

  1. User navigates to Account → Catalog
  2. User clicks "New Item"
  3. User selects template: "Tree"
  4. User enters item details:
    • Name: "Eucalyptus grandis"
    • Species: "Eucalyptus grandis"
    • Scientific Name: "Eucalyptus grandis W.Hill"
    • Family: "Myrtaceae"
    • Origin: "Exotic"
    • Height: 45
    • DAP: 80
  5. User adds optional media:
    • Thumbnail URL: Image for preview
    • 3D Model URL: GLB file for 3D view
  6. User clicks "Save Item"
  7. Item appears in catalog under "Tree" category

Alternative Flows

A1: Duplicate Item Name

  1. User enters name that already exists
  2. System shows error: "An item with this name already exists"
  3. User enters different name
  4. Continue from step 5 of main flow

Business Rules

IDRule
BR-CAT-001Item name must be unique within account
BR-CAT-002Item must reference valid template
BR-CAT-003Item data validated against template schema

UC-204: Create Asset from Template

Description

User creates an asset using a pre-configured catalog item, with fields pre-populated from the catalog.

Actors

  • Primary: Field Technician

Preconditions

  • User is authenticated
  • User has access to project
  • Catalog item exists

Postconditions

  • Asset created with template item link
  • Asset data includes inherited and modified values
  • Asset appears on project map

Main Flow

  1. User navigates to Project → Assets
  2. User clicks "New Asset"
  3. User enters basic details:
    • Name: "Tree #1234"
    • Location: (click on map)
  4. User goes to "Template" tab
  5. User selects template type: "Tree"
  6. User selects catalog item: "Eucalyptus grandis"
  7. Form fields pre-filled:
    • Species: "Eucalyptus grandis"
    • Scientific Name: "Eucalyptus grandis W.Hill"
    • etc.
  8. User modifies specific values:
    • Height: 38 (actual measured height)
    • DAP: 65 (actual measured diameter)
  9. User clicks "Create Asset"
  10. Asset created with template item reference

Business Rules

IDRule
BR-AST-004Asset data independent of catalog item
BR-AST-005Changes to catalog item don't affect existing assets
BR-AST-006Template item ID stored for reference

UC-205: Override 3D Model

Description

User overrides the default 3D model for a specific asset with a custom model.

Actors

  • Primary: Team Member (with asset edit permission)

Preconditions

  • Asset exists and is linked to template item
  • Template item has default 3D model

Postconditions

  • Asset's 3D model URL updated
  • Custom model displayed instead of default
  • Template item's model unchanged

Main Flow

  1. User navigates to Project → Assets → [Asset]
  2. User clicks "Edit"
  3. User goes to "Template" tab
  4. User enters custom 3D model URL:
    • https://cdn.example.com/models/custom-tree-1234.glb
  5. User clicks "Save"
  6. Asset displays custom 3D model

Model Resolution Priority

1. Asset.model_3d_url (override) → Used if set
2. TemplateItem.model_3d_url (default) → Used if asset override is null
3. null → No 3D model available

UC-206: Search Catalog

Description

User searches for items in the asset catalog.

Actors

  • Primary: Account Member

Preconditions

  • User is authenticated
  • Catalog contains items

Postconditions

  • Search results displayed
  • Results filtered by query and template

Main Flow

  1. User navigates to Account → Catalog
  2. User enters search query: "John Deere"
  3. Results filter in real-time
  4. User optionally filters by template: "Equipment"
  5. User clicks on item to view details

Search Behavior

  • Searches item name
  • Searches JSONB data fields
  • Case-insensitive matching
  • Partial word matching

Business Rules

IDRule
BR-CAT-004Search debounced (300ms)
BR-CAT-005Results paginated for large catalogs
BR-CAT-006GIN index ensures fast JSONB search

UC-207: Archive Catalog Item

Description

User archives an outdated catalog item while preserving it for historical reference.

Actors

  • Primary: Account Owner

Preconditions

  • User is authenticated
  • User has account owner role
  • Catalog item exists

Postconditions

  • Item marked as archived
  • Item hidden from default view
  • Existing assets linked to item remain valid

Main Flow

Archive:

  1. User navigates to Account → Catalog
  2. User finds item to archive
  3. User clicks item menu (⋮)
  4. User selects "Archive"
  5. User confirms action
  6. Item hidden from default view

Restore:

  1. User toggles "Show Archived" filter
  2. User finds archived item
  3. User clicks item menu (⋮)
  4. User selects "Restore"
  5. User confirms action
  6. Item available again

Business Rules

IDRule
BR-CAT-007Archived items hidden from default view
BR-CAT-008Archived items cannot be selected for new assets
BR-CAT-009Existing assets linked to archived items remain valid
BR-CAT-010Restored items become available again

UC-208: Edit Template Fields

Description

Account owner adds or modifies fields in an existing custom template.

Actors

  • Primary: Account Owner

Preconditions

  • User is authenticated
  • User has account owner role
  • Custom template exists (not global)

Postconditions

  • Template updated with new fields
  • Existing catalog items retain data
  • New field appears in forms

Main Flow

  1. User navigates to Account Settings → Templates
  2. User finds template to edit
  3. User clicks "Edit"
  4. User clicks "Add Field"
  5. User configures new field:
    • Name: "Maintenance Date"
    • Type: "date"
    • Required: false
  6. User drags field to desired position
  7. User clicks "Save Template"
  8. Template updated

Important Notes

  • Removing a field does not delete data from existing items
  • Changing field type may cause validation issues
  • Field order changes reflected in forms

Global Templates

Global Watch provides global templates that are available to all accounts:

TemplateIconDescription
Tree🌳Track trees with species, height, diameter
Equipment🔧Track equipment and machinery
Structure🏗️Track buildings and structures
Marker📍Generic location markers

Global templates:

  • Cannot be edited or deleted
  • Show "Global" badge in UI
  • Available to all accounts automatically

Edge Cases

EC-1: Duplicate Template Name

Scenario: User tries to create template with existing name.

Expected Behavior:

  • Form validation error displayed
  • Template not created
  • Error: "A template with this name already exists"

EC-2: Delete Template with Items

Scenario: User tries to delete template that has catalog items.

Expected Behavior:

  • Confirmation dialog warns about existing items
  • If confirmed, template soft-deleted
  • Existing items remain but cannot create new ones

EC-3: Invalid Field Data

Scenario: User enters data that doesn't match field type.

Expected Behavior:

  • Real-time validation error on field
  • Form cannot be submitted
  • Clear error message

Scenario: Catalog contains 10,000+ items.

Expected Behavior:

  • Search debounced (300ms)
  • Results paginated
  • GIN index ensures fast search
  • Loading indicator during search

EC-5: 3D Model URL Invalid

Scenario: User enters invalid 3D model URL.

Expected Behavior:

  • URL format validated on save
  • If URL inaccessible at runtime, fallback to 2D view
  • Error logged but doesn't break asset display

Error Handling

Template Errors

ErrorCodeMessage
Template not foundTEMPLATE_NOT_FOUND"Template not found"
Name already existsTEMPLATE_NAME_EXISTS"A template with this name already exists"
Cannot modify globalGLOBAL_TEMPLATE_MODIFICATION"Global templates cannot be modified"
Field validation failedFIELD_VALIDATION_ERROR"Invalid field configuration: {details}"
Duplicate field nameDUPLICATE_FIELD_NAME"Field names must be unique"

Catalog Item Errors

ErrorCodeMessage
Item not foundITEM_NOT_FOUND"Catalog item not found"
Validation failedITEM_VALIDATION_ERROR"Invalid data: {details}"
Item archivedITEM_ARCHIVED"Cannot modify archived item"
Name already existsITEM_NAME_EXISTS"An item with this name already exists"

Testing Checklist

Asset Creation

  • Asset created with valid geometry
  • Template fields populated correctly
  • Catalog item pre-fills form
  • Asset appears on map
  • Usage tracking updated

Templates

  • Custom template created
  • Fields added and ordered
  • Field validation works
  • Global templates read-only
  • Template deletion handled

Catalog

  • Items created and listed
  • Search works correctly
  • Archive/restore works
  • Items grouped by template
  • Pagination for large catalogs

3D Models

  • Default model from template item
  • Override model on asset
  • Fallback when model unavailable

On this page

Asset Tracking Use CasesUC-201: Create AssetDescriptionActorsPreconditionsPostconditionsMain FlowAlternative FlowsBusiness RulesUC-202: Create Asset TemplateDescriptionActorsPreconditionsPostconditionsMain FlowAlternative FlowsBusiness RulesField TypesUC-203: Populate CatalogDescriptionActorsPreconditionsPostconditionsMain FlowAlternative FlowsBusiness RulesUC-204: Create Asset from TemplateDescriptionActorsPreconditionsPostconditionsMain FlowBusiness RulesUC-205: Override 3D ModelDescriptionActorsPreconditionsPostconditionsMain FlowModel Resolution PriorityUC-206: Search CatalogDescriptionActorsPreconditionsPostconditionsMain FlowSearch BehaviorBusiness RulesUC-207: Archive Catalog ItemDescriptionActorsPreconditionsPostconditionsMain FlowBusiness RulesUC-208: Edit Template FieldsDescriptionActorsPreconditionsPostconditionsMain FlowImportant NotesGlobal TemplatesEdge CasesEC-1: Duplicate Template NameEC-2: Delete Template with ItemsEC-3: Invalid Field DataEC-4: Large Catalog SearchEC-5: 3D Model URL InvalidError HandlingTemplate ErrorsCatalog Item ErrorsTesting ChecklistAsset CreationTemplatesCatalog3D ModelsRelated Documentation