Organizing Fleet with Workspaces
Workspaces enable you to organize your fleet according to your business structure, manage access permissions, and create logical groupings that align with your operational needs.
This guide covers common scenarios for organizing equipment using workspaces through the Hiboo API.
Overview
Workspaces in Hiboo provide organizational structure and access control for your fleet:
Organization Structure: Map your business units, projects, or geographical locations
Access Management: Control which users can see which equipment
Key Components:
Users: Team members with access to the workspace
Machines (Assets): Equipment assigned to the workspace
Zones: Geographical or operational areas within the workspace
Custom Fields: Business-specific metadata relevant to the workspace
Best Practice: Map workspaces to your organizational structure - one workspace per business unit, project, or operational division.
Important: Workspaces must be created in the Hiboo application before they can be used via the API.
Understanding Workspace Structure
Workspace Hierarchy
Workspaces follow a hierarchical structure that mirrors typical business organizations:
Workspace Root: The top-level workspace named after your organization that contains all your machines
Parent Workspaces: Business units or divisions
Child Workspaces: Projects, sites, or sub-divisions
Equipment Assignment: Machines can belong to multiple workspaces for cross-functional visibility
Note: Every organization has a "Workspace Root" that serves as the master container for all equipment. This root workspace is automatically named after your organization and ensures all machines remain accessible at the top level.
Learn More: Understanding Workspace Hierarchy
Permission Model
Workspaces control data visibility and access:
Users see only equipment in their assigned workspaces
Segments can be created within workspace boundaries
Workspace Discovery
Viewing Available Workspaces
When you need to understand your current workspace structure:
Returns the list of all workspaces available
Token returned by POST /login: a JWT, valid for 10 days. Send it in the x-access-token header, as x-access-token: <token>. The Authorization: Bearer <token> header also works. When a request returns 401, call POST /login again.
List of equipment
Unable to authenticate the token
GET /v2/fleet/workspaces HTTP/1.1
Host: api.hiboo.io
x-access-token: YOUR_API_KEY
Accept: */*
{
"data": {
"total": 1,
"rows": [
{
"name": "All fleet"
}
]
}
}Common scenarios:
Audit workspace structure: Review current organizational setup
Integration planning: Understand workspace boundaries before system integration
User onboarding: Identify appropriate workspaces for new team members
Equipment Organization
Adding Equipment to Workspaces
Problem: You need to organize equipment by business unit, project, or location to match your operational structure.
Solution: Link equipment to appropriate workspaces using the workspace assignment API.
Add asset workspaces data with assetId or (serialNumber AND make) of Asset and workspace names
Token returned by POST /login: a JWT, valid for 10 days. Send it in the x-access-token header, as x-access-token: <token>. The Authorization: Bearer <token> header also works. When a request returns 401, call POST /login again.
Equipment has been added
OKMissing parameters or invalid parameters
Unable to authenticate the token
An error occurred while processing the request
POST /v2/fleet/equipment/assetWorkspaces/linkAssetToWorkspaces HTTP/1.1
Host: api.hiboo.io
x-access-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 75
{
"assetId": 1,
"serialNumber": "text",
"make": "text",
"workspaceNames": [
"text"
]
}{
"status": "OK"
}Example: Assigning equipment to project workspace
Example: Using manufacturer identification
Recommended: Prefer using
assetId(Hiboo's internal ID) when possible, as it provides faster, more reliable equipment identification and avoids potential issues with duplicate serial numbers or manufacturer name variations.
Removing Equipment from Workspaces
Problem: Equipment moves between projects or organizational changes require workspace restructuring.
Solution: Remove equipment from specific workspaces while maintaining other workspace assignments.
delete link asset and workspaces data with assetId or (serialNumber AND make) of Asset and workspace names
Token returned by POST /login: a JWT, valid for 10 days. Send it in the x-access-token header, as x-access-token: <token>. The Authorization: Bearer <token> header also works. When a request returns 401, call POST /login again.
Equipment has been unlink between asset and workspace
OKMissing parameters or invalid parameters
Unable to authenticate the token
An error occurred while processing the request
DELETE /v2/fleet/equipment/assetWorkspaces/linkAssetToWorkspaces HTTP/1.1
Host: api.hiboo.io
x-access-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 75
{
"assetId": 1,
"serialNumber": "text",
"make": "text",
"workspaceNames": [
"text"
]
}{
"status": "OK"
}Example: Removing equipment from completed project
Best Practice: When updating workspace assignments, use differential updates rather than deleting all workspace assignments and recreating them. This approach:
Preserves historical data and audit trails
Reduces API calls and processing overhead
Minimizes risk of data loss during updates
Maintains workspace permissions and relationships during transitions
Note: Removing an asset from a workspace will also remove the history of the machine in this workspace as it has never been in the workspace.
Common Organization Patterns
Business Unit Structure
Scenario: Large organization with multiple divisions operating independently.
Pattern: Create top-level workspaces for each division:
Construction Division → All construction equipment
Mining Division → All mining equipment
Forestry Division → All forestry equipment
Implementation:
Geographical Organization
Scenario: Multi-location operations with regional management.
Pattern: Organize by location hierarchy:
North America → Regional workspace
Canada Operations → Country-level workspace
Alberta Projects → Province/state workspace
Implementation:
Hybrid Organization
Scenario: Complex operations requiring multiple organizational views.
Pattern: Equipment belongs to multiple workspace categories:
Business function (Construction, Mining)
Geographic location (Site A, Site B)
Equipment type (Heavy Equipment, Light Vehicles)
Implementation:
Integration Strategies
ERP/CMMS System Alignment
Problem: Your existing systems have organizational structures that need to map to Hiboo workspaces.
Strategies:
Project Code Integration:
Use project codes to determine workspace assignments
Automate equipment moves when project assignments change
Track equipment utilization by project
Location Hierarchy Sync:
Mirror your CMMS location structure in workspace hierarchy
Sync equipment location changes to workspace assignments
Maintain geographical reporting consistency
Best Practices
Workspace Design Principles
Keep it Simple:
Start with your primary organizational structure
Avoid over-complicating with too many workspace levels
Focus on how your teams actually work
Plan for Change:
Design workspace structure that can evolve with your business
Use descriptive names that won't become outdated
Consider equipment mobility between workspaces
Match User Needs:
Align workspaces with how users need to view and manage equipment
Enable cross-functional visibility where needed
Balance access control with operational efficiency
Workspace Management
Naming Conventions:
Use consistent, descriptive workspace names
Include relevant identifiers (project codes, location codes)
Avoid abbreviations that might be unclear
Assignment Strategy:
Multiple assignments: Equipment can belong to multiple workspaces for different organizational views
Minimal assignments: Don't over-assign - keep it relevant to actual business needs
Regular review: Audit workspace assignments as projects and organizations change
Last updated
Was this helpful?