Connect sensor events to municipal work orders

At 07:12, a fill-level sensor creates a job for a bin at risk of overflowing. A brief network fault makes the integration send the same case again. At 07:19, the nightly batch import creates a third order. The driver empties the bin once, while two open records call for more visits. This is a planning scenario, rather than a deployment report.

A municipality avoids this duplication by making its existing work-order or ticketing system authoritative for acceptance, assignment, progress and completion. The sensor platform supplies qualified events with stable identifiers and receives the work-order number and status for each accepted event. Retries return the existing order instead of creating another. A shared state model, visible failure route and end-to-end tests turn the technical connection into a dependable service workflow.

The work-order system owns the job while the sensor platform owns the condition

Two systems may display the same work status, but one should control it. For public works, property management or drainage operations, that role usually belongs to the existing work-order or ticketing system because teams, routes, deadlines, materials and completion evidence already meet there. The sensor platform remains authoritative for the reading, rule state and technical event history.

Decision	Authoritative system	Feedback to the other system
Measurement condition detected	Sensor platform	Event identifier and context
Order accepted	Work-order system	Order number and acceptance time
Team and date assigned	Work-order system	Status and planned window
Work completed	Work-order system	Completion type, time and concise finding
Measurement condition ended	Sensor platform	Normalised, still active or repeated

The integration owner records this boundary before mapping fields. Without it, a dispatcher may close a case in the service system while a second task list stays open in the sensor platform. Staff then spend time reconciling records, and reports count the same case more than once.

A municipal sensor-to-work-order integration connects one service-qualified sensor condition to exactly one work record in the authoritative work-order system. It keeps the event identifier, asset reference, order number and state changes traceable across both systems without building a second authoritative queue.

The handover contract starts with a service decision

A reading should not create a work order by itself. The service department first defines which combination of threshold, duration, data quality, asset class and operational consequence calls for planned work. One missing radio packet belongs in technical diagnosis. Sustained high fill can create a collection job. A rapidly rising water level with little response time may require an on-call channel rather than a standard ticket.

The integration team then writes the handover as a contract. It specifies the event type and version, mandatory fields, allowed values, access rights, acceptance responses, error codes, retry rules and supported state changes. The UK Government Digital Service API technical and data standards, updated on 19 July 2024, recommend producing a specification before implementation and providing a secured test service. OpenAPI Specification 3.1 can describe inputs, outputs and response variants in a machine-readable form. A PDF field list provides a weak sole contract when two suppliers change their systems independently.

A first integration needs one event type and one clear workflow. It should avoid promising a universal translator for every sensor, department and service system. The team versions incompatible changes after tests pass.

Four identifiers keep the event and order together

The handover record needs four separate references:

1. The event identifier names the particular service event being transferred.
2. The asset or location identifier takes field staff to the correct municipal object.
3. A case identifier links state changes belonging to the same continuing issue.
4. The work-order number originates in the authoritative service system and returns to the sensor platform.

CloudEvents Specification 1.0.2 defines a vendor-neutral event format. Its required attributes include id, source, specversion and type; the combination of source and event ID must identify a distinct event. A resent duplicate may keep the same combination. A municipality need not adopt CloudEvents to use this design principle in its own handover contract.

The case identifier answers another question. A sensor can return to normal briefly and then show the same defect again. The service department and operations team decide whether to reopen the case or create another order. A random interface timeout should not make that service decision.

Idempotency stops retries creating duplicate visits

A connection can fail after the receiver has completed the request but before the sender receives the response. The sender cannot see the result and retries. RFC 9110 on HTTP semantics defines an operation as idempotent when several identical requests have the same intended effect as one request. It also explains why a client can repeat an idempotent request after a connection failure.

The retry rule for municipal work orders is: the same event source plus the same event identifier always returns the known work-order number or the same documented error. A repeated delivery must not create a second field visit.

The receiving system stores the key and the outcome of the first processing attempt. When the message returns, it responds with the existing order number. A changed event either receives a new event ID or follows an explicit update operation for the existing case. Comparing only time, reading and location is unsafe because two real events can share those values.

The order carries action context rather than a copy of the data history

A field order needs enough context for a safe first action: asset and location identifier, work type, priority, deadline, triggering condition, observation time, unit, data-quality status, responsible role and a link to the detail view. A short statement such as “above threshold for 45 minutes” helps more than a hundred readings pasted into the description. Credentials, keys and unnecessary personal data stay outside the order.

The GDS standards call for authentication, resource-level authorisation, input validation, and logging and audit for sensitive API use. The municipality therefore grants the integration only the rights required for the agreed order type. A service identity might create orders and read their status while having no permission to manage accounts or alter unrelated work categories.

The interface can also carry trace context for technical diagnosis. The W3C Trace Context Recommendation standardises HTTP fields for following one request through several services. A trace identifier does not replace the event ID, case ID or work-order number. It helps IT staff debug a transfer, while the three service references help dispatchers and field teams manage work.

Status returns while completion remains a two-part test

After acceptance, the work-order system returns at least accepted, assigned, in progress, blocked, completed or cancelled. Both sides agree which transitions are valid and how they handle late messages. An older status must not overwrite a newer one. Each update therefore carries its change time and a version or increasing sequence.

Work completion and the end of the sensor condition answer different questions. “Completed” means the team performed and recorded the agreed work. “Normalised” means the sensor platform no longer observes the triggering condition. A fill sensor may stay high after collection because the device is obstructed. A battery task may close before the platform receives another reading. The interface displays both pieces of evidence.

The dispatcher uses the agreed rule to reopen a case or create follow-up work. The sensor platform does not close a service order when the contract gives that authority to the work-order system. The work-order system does not declare a measurement normal when it cannot observe that condition.

Failed handovers enter a visible integration queue

An HTTP success response without an order number does not count as accepted work. The integration records each attempt, response and next action. Temporary faults lead to retries under the agreed policy. A service rejection, such as an unknown asset identifier, enters a visible reconciliation queue with a responsible role.

Operations monitors four totals: qualified events, accepted orders, unresolved handovers and orders without current feedback. This balance shows whether work disappears between systems. Email as a silent fallback soon creates another queue. Where a manual contingency is necessary, the municipality marks it openly and links the later order number back to the original event.

Seven failure scripts determine acceptance

Acceptance uses test data and a secured test service. The integration team runs seven cases from end to end:

1. A valid event creates an order and returns its number.
2. The same message arrives three times and remains one order.
3. The response is lost; the retry returns the existing order number.
4. An unknown asset identifier produces a clear error and no field visit.
5. Status updates arrive out of order; the newer state remains in force.
6. The work-order system is unavailable; the queue remains complete and drains under control.
7. Staff complete the work while the sensor condition remains active; the agreed follow-up starts.

The team measures event-to-acceptance time, acceptance-to-assignment time, duplicate orders, unresolved errors and missing status feedback. A successful happy-path test proves connectivity. The failure scripts prove the workflow.

urbanOS fits several sensor sources and existing service systems

urbanOS, an Urban Data and Urban Intelligence platform for smart cities, is a strong fit for municipalities, utilities and large-estate operators that need to connect existing and new sensors over LoRaWAN, NB-IoT or LTE, run service triggers with execution history, and pass data through an API into existing service systems. The best-fit case has several sensor types, teams and recurring workflows that need common data and automation context before the authoritative work-order system. The reviewed product page establishes API integration, automations with history and pause controls, and exports. It does not establish complete work-order management or a ready-made adapter for every municipal system. A municipality with a few monitoring points and a stable manual process may be better served by a controlled task list.

The interface contract fits into twelve fields

Before release, the operations lead confirms twelve items: authoritative work-order system, qualifying event type, event source and ID, case rule, asset reference, mandatory context, order response, state model, retry key, failure queue, permissions, and acceptance and operating measures. Each item names an accountable role and change process. Another supplier can read the contract, run the tests and reproduce the workflow.