Skip to main content

API User Manual

This is the complete user manual for the PlantPulse Java API client library (plantpulse-api). You can access all master and operational data of the Platform, including sites, assets, tags, alarms, and work orders, through 13 domain services.

Library Features​

  • Standard REST — Uses GET/POST/PUT/PATCH/DELETE methods according to their semantic purpose.
  • Typed DTOs — All requests and responses are automatically mapped to *RequestV5 / *ResponseV5 classes (no manual JSONObject parsing required).
  • Tab-based PATCH — Supports 10 types of partial updates for Tag alarms, metadata, formulas, and aggregations.
  • 13 Domain Services — system, site, customer, employee, product, asset, opc, tag, alarm, order, calendar, path, flow.
  • Safe Defaults — Returns null or an empty list upon failure (no exceptions thrown).

Who is this manual for? This is a comprehensive reference for developers building external systems (MES, ERP, custom dashboards, etc.) that integrate with the PlantPulse Platform using Java.

Quick Navigation​

AreaGuide
Getting StartedPlease read in this order: 1. Getting Started → 2. Domain ID Rules → 3. Response Formats and Error Handling.
Need a Specific DomainNavigate directly to the corresponding service (e.g., Tag, Order) in the table of contents below.
Direct REST CallsThe Full Endpoint List contains the URL and method mappings.
Workflow ExamplesCheck end-to-end scenarios in the Integration Example Collection.
AI Assistant IntegrationMCP Server — Allows clients like Claude to query tags, alarms, and assets in natural language and even verify alarms.

Core Concepts​

  • Entry Point: new APIClient_V5(proto, host, port, user, token, debug) → connect()
  • 13 Services: client.system(), client.site(), client.customer(), client.employee(), client.product(), client.asset(), client.opc(), client.tag(), client.alarm(), client.order(), client.calendar(), client.path(), client.flow()
  • Typed DTO Returns: All methods return type classes (SiteResponseV5, TagResponseV5, etc.) instead of JSONObject.
  • Safe Defaults on Failure: create/update/get → null, list → empty list, delete/exists → false, count → 0.
  • Error Response Extraction: BaseServiceV5.getErrorCode(env), getErrorMessage(env), getHttpStatus(env) static methods.
  • Domain ID Validation: The server verifies a designated prefix for each domain. Levels are determined by asset_type rather than prefixes — Domain ID Rules.
  • Base Path: All calls are made to endpoints under /api/v5.

Table of Contents​

Getting Started and Basic Rules​

  1. Getting Started — Client Creation and Connection
  2. Domain ID Rules ⭐ Please read this first
  3. Response Formats and Error Handling

Infrastructure and Model Domains​

  1. System Service — Health checks
  2. Site Service — Site (factory) master
  3. OPC Service — Data collection channels
  4. Asset Service — Asset hierarchy (Area · Line · Equipment)
  5. Tag Service — Tag definitions + 10 PATCH types
  6. Path Service — Asset path lookup

Operational Domains​

  1. Alarm Service — Alarm event lookup
  2. Calendar Service — Schedules (inspection, downtime, etc.)
  3. Order Service — Work orders + lifecycle

Master Data​

  1. Customer Service — Customers
  2. Employee Service — Employees
  3. Product Service — Products

Automation​

  1. Flow Service — Flow / Flow Node lookup

Appendix​

  1. Full Endpoint List — URL mapping, maintenance orders, CMMS webhooks, alarm performance
  2. Integration Example Collection — End-to-end workflows
  3. MCP Server — Channel for AI assistants to query field data in natural language

Inquiries: webmaster@kopens.com