Skip to content

ABS Platform Object Model Documentation

Overview

The ABS (Asset-Based Subscription) Platform is designed to manage subscription services that are tied to physical assets. This document provides a comprehensive explanation of the core object model and how the different entities interact.

Actors in the ABS Platform

The following actors are recognized in the current ABS Platform model:

  • ABS-Hub: The central broker that routes all signals and interactions between ecosystem actors. Provides service bundling functionality and orchestrates all workflow routing.
  • Client / Customer: The individual or entity requiring asset-as-a-service and/or paying for it. (Client = Customer)
  • Asset-Owner: Title owner/investor with financial stake. Can also act as Asset-Manager in self-management scenarios. Examples: Swap Network, Battery Circulator, Tricycle Fleet.
  • Asset-Manager: Organization managing assets. May be the same as Asset-Owner in self-managed scenarios.
  • Service-Agent: Personnel/robots performing physical activities.
  • Infra-Provider: Infrastructure services.
  • Pay-Portal: Payment processing services.
  • Assets: IoT-enabled smart assets.

Notes: - Service Bundling is a function of the ABS-Hub, not a separate actor. - Asset-Owner and Asset-Manager roles may overlap in self-management scenarios. - Swap Network, Battery Circulator, and Tricycle Fleet are specific instances of Asset-Owner.

Core Entities

Service

A Service represents an access-controlled offering tied to physical assets. Examples include: - Battery swap services - Vehicle rental services - Equipment leasing services

Key Properties: - asset_type: The type of physical asset (e.g., "battery", "vehicle", "equipment") - access_control: JSON configuration defining who can access the service and under what conditions - status: Current operational status of the service

Service_Plan

A Service_Plan defines a subscription that combines one or more Service_Usage instances with payment and lifecycle terms.

Key Properties: - service_usages: Array of services included in this plan - plan_terms: Pricing, duration, and renewal policies - status: Current status of the plan (draft, active, suspended, cancelled)

Service_Usage

A Service_Usage references a specific Service with per-user runtime configuration.

Key Properties: - service: The service being used - current_asset: The specific asset instance currently assigned to the user - usage_limits: JSON configuration defining usage constraints

Plan_Terms

Defines the commercial terms of a service plan.

Key Properties: - pricing: JSON structure defining pricing model (flat rate, usage-based, etc.) - duration: Contract duration (e.g., "30 days", "1 year") - deposit_required: Whether a security deposit is required - renewal_policy: How the plan renews (automatic, manual, etc.)

Asset Types and ERM IoT Microservices Integration

Asset Classification

Assets in the ABS Platform are managed through the ERM IoT Microservices (Thing Microservice) and are classified into exactly two types:

1. FLEET Objects

  • Definition: Collections of related ITEM objects managed as a unit
  • Business Model: Service rendered across a collection (like Hertz rental, hotel chains)
  • Examples:
  • Battery fleet (all batteries in a swap network)
  • Vehicle fleet (all vehicles in a rental fleet)
  • Equipment fleet (all tools in a service fleet)
  • Thing Microservice Reference: Fleet container object that contains multiple ITEMs
  • Asset Assignment: Non-deterministic - specific ITEM selected at service rendering time

2. ITEM Objects

  • Definition: Individual, discrete pieces of equipment or devices
  • Business Model: Service tied to a specific asset
  • Examples:
  • Individual batteries (BAT001, BAT002, etc.)
  • Single vehicles (VEH001, VEH002, etc.)
  • Individual tools or equipment pieces
  • Thing Microservice Reference: Direct object reference to individual item
  • Asset Assignment: Deterministic - same ITEM throughout service lifecycle

Asset Reference Resolution

Service Object Asset References

In the Service object, the asset reference can point to either: - FLEET: A collection of ITEMs managed as a unit - ITEM: A single, specific asset

Key Concept: The asset reference in Service is deferred - it cannot be fully resolved until the asset_type is known (ITEM vs FLEET).

Service_Usage Object Asset References

In the Service_Usage object, the current_asset field behavior depends on the Service's asset_type:

2.1 FLEET-based Services (asset_type = "FLEET"): - Initial State: current_asset is undefined/null when Service_Usage is created - Dynamic Assignment: current_asset is populated at the point of service rendering - Runtime Resolution: Points to a specific ITEM selected from the FLEET at service time - Non-deterministic: Different ITEMs may be assigned on different service requests

2.2 ITEM-based Services (asset_type = "ITEM"): - Initial State: current_asset is set immediately upon Service_Usage creation - Static Assignment: current_asset value is the same as the ITEM reference - Deterministic: Same ITEM reference throughout the entire service lifecycle - Direct Mapping: current_asset = ITEM reference (one-to-one relationship)

Asset Assignment Patterns

FLEET-Based Services (Non-deterministic Assignment)

Business Model: Service rendered across a collection

Examples: - Hertz Rental: Any car from the fleet can be assigned - Hotel Chain: Any room from the hotel can be assigned - Battery Swap: Any battery from the swap station can be assigned

Workflow: 1. Service references a FLEET object 2. Service_Usage is created with current_asset = null/undefined 3. At service rendering time, a specific ITEM is selected from the fleet 4. Service_Usage.current_asset is dynamically updated to the selected ITEM 5. Different service requests may result in different ITEM assignments

ITEM-Based Services (Deterministic Assignment)

Business Model: Service tied to specific asset

Examples: - Dedicated Vehicle: Same vehicle throughout subscription - Dedicated Equipment: Same tool throughout rental period - Dedicated Battery: Same battery throughout service

Workflow: 1. Service references a specific ITEM object 2. Service_Usage is created with current_asset immediately set to the ITEM reference 3. current_asset value remains the same throughout the entire service lifecycle 4. No dynamic assignment occurs - same ITEM reference is maintained

Current_Asset Field Behavior Specification

Field Definition

  • Type: String (nullable)
  • Purpose: References the specific ITEM currently assigned to the customer
  • Nullability: Can be null for FLEET services before first service rendering

Behavior by Asset Type

FLEET Services (asset_type = "FLEET"): - Initial Creation: current_asset field is null/undefined when Service_Usage is first created - First Service Rendering: current_asset is dynamically assigned to a specific ITEM from the fleet - Subsequent Rendering: current_asset may change to different ITEMs based on availability and business rules - Dynamic Nature: The assigned ITEM can vary across different service requests

ITEM Services (asset_type = "ITEM"): - Initial Creation: current_asset is immediately set to the specific ITEM reference - Service Lifecycle: current_asset remains constant throughout the entire service lifecycle - Static Assignment: No dynamic changes occur - same ITEM reference is maintained - Direct Mapping: current_asset value equals the ITEM reference (one-to-one relationship)

Integration with ERM IoT Microservices

State Management Integration

  • Thing Microservice: Manages ITEM and FLEET object states
  • ABS Platform: References Thing Microservice objects and tracks usage
  • Real-time Synchronization: Thing Microservice state changes reflected in ABS Platform

Service Rendering Workflow

  1. FLEET Services:
  2. Query Thing Microservice for available ITEMs in fleet
  3. Select appropriate ITEM based on availability and business rules
  4. Dynamically update Service_Usage.current_asset with selected ITEM

  5. Current_asset may change on each service request

  6. ITEM Services:

  7. Verify ITEM availability in Thing Microservice
  8. Use same ITEM reference throughout service lifecycle
  9. Current_asset remains constant and never changes

Payment and Billing

Payment_Record

A Payment_Record represents individual payment transactions within the ABS Platform.

Key Properties: - amount: Payment amount in specified currency - payment_method: Method used (credit_card, bank_transfer, wechat, etc.) - transaction_id: External payment processor transaction ID - timestamp: When the payment was processed - status: Current status (pending, completed, failed, refunded) - service_plan_id: Associated service plan - federation_id: External system reference (Odoo account.payment)

Service_Record

A Service_Record represents individual service usage events within the ABS Platform.

Key Properties: - event_type: Type of service event (swap_completed, service_accessed, etc.) - event_data: JSON payload with event-specific details - timestamp: When the service event occurred - service_plan_id: Associated service plan - federation_id: External system reference (Odoo sale.order.line)

Billing Cycle Management

Plan_Terms Billing Configuration

The Plan_Terms object contains comprehensive billing configuration:

Core Pricing Structure: - plan_duration: Contract duration ("1 year", "2 years", "unlimited") - recurring_amount: Amount per billing cycle - billing_cycle: Frequency ("monthly", "quarterly", "yearly") - currency: Payment currency ("USD", "EUR", "CNY")

Commitment & Renewal: - commitment_period: Contract commitment ("1 year", "month-to-month") - auto_renew: Whether plan automatically renews - billing_cycle_count: Number of billing cycles in commitment

Payment Processing: - payment_methods: Accepted payment methods - late_payment_fee: Fee for late payments - grace_period_days: Days before late fees apply

Deposit Management: - deposit_required: Whether security deposit is required - deposit_amount: Deposit amount - deposit_refundable: Whether deposit is refundable

Cancellation & Changes: - cancellation_notice_days: Notice required for cancellation - early_termination_fee: Fee for early termination - proration_enabled: Whether changes are prorated