Skip to content

Workflow Design Guideline

1. Introduction

This guideline establishes the principles and structure for designing, documenting, and implementing workflows in the ABS Platform. It ensures clarity, consistency, and maintainability, especially in event-driven, multi-party systems.

2. 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: The title owner or investor with a financial stake in the assets. Can also act as Asset-Manager in cases of self-management. Examples include Swap Network, Battery Circulator, and Tricycle Fleet.
  • Asset-Manager: The organization or party responsible for managing assets. May be the same as Asset-Owner in self-managed scenarios.
  • Service-Agent: Personnel or robots performing physical activities related to the assets or services.
  • Infra-Provider: Providers of infrastructure services required for asset operation.
  • Pay-Portal: Services responsible for payment processing.
  • Assets: IoT-enabled smart assets managed and tracked by the platform.

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.

2. Event Triggers

2.1 Definition

An event trigger is any occurrence that initiates a workflow.

2.2 Types of Event Triggers

  • External Triggers:
  • Originate from outside the system (e.g., user actions, third-party integrations, hardware events).
  • Example: Customer scans QR code on swap cabinet using ovAPP.
  • Internal Triggers:
  • Originate from within the system, typically as signals/events emitted by other workflows or system components.
  • Example: BatteryReserved event emitted by the Swap Cabinet Service.

2.3 Specification

For each event trigger, document: - Event Name - Triggering Mechanism (how/where it originates) - Type (External/Internal) - Initiating Actor (if applicable) - Input Data

3. Workflow Structure

  • Linear, Short Steps:
  • Design workflows to be as linear and concise as possible.
  • Step-by-Step Documentation:
  • List each step, the responsible actor/service, and data involved.

4. Signals (Events)

4.1 Definition

Signals are events emitted during a workflow, published to the event bus for other workflows or services to consume.

4.2 Specification

For each signal, document: - Event Name - Payload Structure - Intended Subscribers/Downstream Workflows

5. Workflow Termination

5.1 Definition

The condition or event that marks the end of a workflow.

5.2 Specification

Clearly state the termination criteria for each workflow.

6. Design Validation

  • Blocking and Circular Loops:
  • Explicitly check for and document any potential for blocking (deadlocks) or circular event chains (infinite loops).
  • Event Bus Monitoring:
  • Implement logging or tracing on the event bus to observe event flows and diagnose issues.

7. Workflow Documentation Template

Workflow Name:

Triggering Event: - Event Name: - Triggering Mechanism: - Type: (External/Internal) - Initiating Actor: - Input Data:

Workflow Steps: 1. Step 1 (Actor, Action, Data) 2. Step 2 (Actor, Action, Data) 3. ...

Signals Emitted: - Event Name(s), with payload structure

Downstream Workflows Triggered: - List and describe

Involved Parties: - List of actors/services

Termination Criteria: - Describe what marks the end of the workflow

Validation Notes: - Potential for blocking/circularity? How is it prevented?