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:

Workspaces

get

/v2/fleet/workspaces

Returns the list of all workspaces available

Authorizations

x-access-tokenstringRequired

Generate a JWT when you log in. Use it in your following requests in the header as x-access-token: your-token-here

Responses

200

List of equipment

application/json

401

Unable to authenticate the token

application/json

get/v2/fleet/workspaces

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 Equipment to Workspaces

post

/v2/fleet/equipment/assetWorkspaces/linkAssetToWorkspaces

Add asset workspaces data with assetId or (serialNumber AND make) of Asset and workspace names

Authorizations

x-access-tokenstringRequired

Generate a JWT when you log in. Use it in your following requests in the header as x-access-token: your-token-here

Body

assetIdnumberOptional

serialNumberstringOptional

makestringOptional

workspaceNamesstring[]Optional

Responses

200

Equipment has been added

application/json

statusstringOptionalExample: OK

400

Missing parameters or invalid parameters

application/json

401

Unable to authenticate the token

application/json

500

An error occurred while processing the request

application/json

post/v2/fleet/equipment/assetWorkspaces/linkAssetToWorkspaces

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

{
  "assetId": 1,
  "workspaceNames": ["Construction Site A", "Heavy Equipment"]
}

Example: Using manufacturer identification

{
  "serialNumber": "YVR001988",
  "make": "Caterpillar",
  "workspaceNames": ["Project Alpha", "Earthmoving Division"]
}

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.

Remove Equipment from Workspaces

delete

/v2/fleet/equipment/assetWorkspaces/linkAssetToWorkspaces

delete link asset and workspaces data with assetId or (serialNumber AND make) of Asset and workspace names

Authorizations

x-access-tokenstringRequired

Generate a JWT when you log in. Use it in your following requests in the header as x-access-token: your-token-here

Body

assetIdnumberOptional

serialNumberstringOptional

makestringOptional

workspaceNamesstring[]Optional

Responses

200

Equipment has been unlink between asset and workspace

application/json

statusstringOptionalExample: OK

400

Missing parameters or invalid parameters

application/json

401

Unable to authenticate the token

application/json

500

An error occurred while processing the request

application/json

delete/v2/fleet/equipment/assetWorkspaces/linkAssetToWorkspaces

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

{
  "assetId": 1,
  "workspaceNames": ["Project Beta"]
}

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:

{
  "assetId": 123,
  "workspaceNames": ["Construction Division"]
}

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:

{
  "assetId": 789,
  "workspaceNames": ["North America", "Canada Operations", "Alberta Projects"]
}

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:

{
  "assetId": 101,
  "workspaceNames": ["Construction Division", "Site A", "Heavy Equipment"]
}

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

PreviousManaging Equipment Identity NextAdding Custom Fields to Equipment

Last updated 1 year ago

Was this helpful?