Skip to main content

API User Manual

This is the complete user manual for the PlantPulse Java API client library (plantpulse-api). Through 13 domain services, you can access all master and operational data on the platform — sites, assets, tags, alarms, work orders, and more.

Library Features​

  • Standard REST — GET/POST/PUT/PATCH/DELETE methods used according to their intended semantics
  • Typed DTOs — All requests and responses are automatically mapped to *RequestV5 / *ResponseV5 classes (no manual JSONObject parsing)
  • Per-tab PATCH — Supports 10 kinds of partial updates for Tag: alarm, metadata, calculation, aggregation, and more
  • 13 domain services — system, site, customer, employee, product, asset, opc, tag, alarm, order, calendar, path, flow
  • Safe defaults — Returns null or an empty list on failure (no exceptions thrown)

Who is this manual for? It is a full reference for developers building external systems (MES, ERP, custom dashboards, etc.) that integrate with the PlantPulse platform in Java.

Quick Tour​

AreaGuidance
If you are just startingRead in this order: 1. Getting Started → 2. Domain ID Rules → 3. Response Formats and Error Handling.
If you need a specific domainJump straight to the relevant service (e.g. Tag, Order) from the table of contents below.
If you call REST directlyThe full endpoint list maps every URL to its method.
If you need workflow examplesSee the collected integration examples for end-to-end scenarios.

Key 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: Every method returns a typed class (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: SITE_, ASSET_, OPC_/API_, TAG_ prefixes enforced (server-side validator)
  • Base path: All calls target endpoints under /api/v5

Manual Contents​

Getting Started and Basic Rules​

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

Infrastructure and Model Domains​

  1. System Service — Health check
  2. Site Service — Site (plant) 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
  2. Collected Integration Examples — End-to-end workflows

Inquiries: webmaster@kopens.com