A useful smart-lighting integration lets staff follow one problem from the original report to the completed field work. GIS supplies the spatial asset reference, the maintenance system manages the work order, and 311 handles the service request and communication. A shared asset reference connects those jobs.
Before discussing APIs, take one streetlight report and ask each team to locate the same physical asset. If the answers differ, automation will move the disagreement faster.
Give each system a clear job
Esri’s geodatabase documentation explains the spatial datasets and attributes behind a GIS record. For the workflow below, use GIS as the location reference, a computerized maintenance management system (CMMS) for maintenance execution, and 311 for public intake. This is a suggested division of responsibilities; an agency’s actual software and governance may differ.
Follow one record all the way through
Illustrative example: a resident reports a dark light beside the northbound bus stop. The following IDs and records are invented to show the handoff, not an existing integration.
Keep the location and measurement method with the reading
FHWA’s study collected mobile lighting data at 20 Hz and integrated the records with GIS. Figure 4 retains four directional channels over an approximately one-mile segment; the readings were smoothed with a moving window.
The left, front, right and rear traces give different views of the same route. A single route average loses that local variation. For an integration pilot, preserve route position, time, instrument orientation and processing history before relating a reading to an asset or service event.
A peak is not automatically a faulty light, and a nearby map point is not proof that one fixture caused a measurement. These are historical research measurements, not LEOTEK network telemetry. Use the example to define the evidence your own workflow must retain.
| Step | Record | What must carry forward |
|---|---|---|
| 311 intake | Request SR-8041 | Original description, reported location and request time. |
| Asset match | Agency asset SL-1042 | Verified location or an explicit uncertain-match status. |
| Maintenance | Work order WO-219 | Asset ID, linked requests, assignment and work status. |
| Field closeout | Completion on WO-219 | Action performed, verification and unresolved exceptions. |
| Service response | Update to SR-8041 | The approved public-facing status, using the existing link. |
The streetlight ID, controller ID, request ID and work-order ID should remain distinct. Each identifies a different thing. The cross-reference is what allows staff to trace the whole story.
Decide what “closed” means
A work order might be closed because the repair is complete, because the asset belongs to another owner or because the report was a duplicate. Those outcomes should not all produce the same message to a resident.
Write a small status-mapping sheet with maintenance and service-center staff. Identify the source status, the receiving status, when it may be sent and which exceptions need review. This decision is often more important to the user experience than whether the exchange runs in real time.
Handle the awkward records deliberately
- Two reports, one fault: link the requests to the same reviewed issue or work order while retaining each communication record.
- Unclear location: hold the match for review instead of silently assigning the nearest pole.
- Replaced controller: update the device association without losing the streetlight’s maintenance history.
- Another owner’s asset: route the report using the agreed responsibility process.
- Failed exchange: keep the failure visible, with an owner for retry or manual completion.
Also distinguish a controller that cannot communicate from a luminaire confirmed to be dark. The network-outage guide explains why those conditions need separate handling.
Start the pilot with one service workflow
Choose a bounded issue type or district and review actual records end to end. Measure successful asset matches, unmatched-request age, duplicates, work-order links and status-sync exceptions. Define each measure before interpreting improvement.
Test a completed repair, a duplicate, an uncertain match and a failed handoff. A successful “happy path” does not establish that the integration can recover from the cases dispatchers will encounter.
Before expanding, confirm which system owns each field and who approves mapping changes. Verify supported interfaces and security requirements with the relevant vendors; a connected-lighting platform description does not establish compatibility with every GIS or CMMS.
The closest map point is not always the reported streetlight
A resident may describe a light beside a bus stop while the closest mapped pole serves the opposite roadway. A nearest-coordinate match can be a useful candidate, but it does not establish ownership, circuit or the precise asset being reported. Preserve the original report and the uncertainty until the match is verified. Otherwise, a technically functioning integration can create a work order for the wrong equipment.
An illustrative matching record should contain the candidate asset, the method used, confidence or unresolved status, and the person or process that confirmed it. Avoid overwriting the resident's location with the candidate coordinate before confirmation. The two locations answer different questions: where the report was made and where the identified asset is recorded.
Coordinate conventions are another quiet failure point. RFC 7946 specifies longitude followed by latitude for positions in GeoJSON. A receiving application expecting the reverse can produce an obviously wrong location or a subtler mismatch, depending on the values. Define the coordinate reference and field order at the interface instead of treating two columns called X and Y as self-explanatory.
A retry should not create a second repair
Interfaces fail between sending and acknowledgement. The sender may retry because it does not know whether the receiving system created the work order. If each retry produces a new order, one public report becomes several maintenance jobs. The integration needs a documented duplicate-handling rule tied to the source record and operation.
For a proposed acceptance test, send one approved test request, interrupt the acknowledgement path in a controlled environment, then repeat the operation. The expected outcome is whatever the agreed interface specifies, with the resulting records reconciled. This article does not prescribe a universal API design or claim a particular vendor supports idempotency. It identifies a failure case that normal successful-path demonstrations can miss.
Separate a duplicate request from a repeated fault. Two residents may report one outage, while the same asset may experience a new outage after an earlier repair. Those situations need different links and status decisions. The system should retain enough timing and history for the maintainer to distinguish them.
Closing a workflow needs a reason, not only a status
Map the internal completion reason to the public response deliberately. Repair verified, no fault found, duplicate, wrong owner and referred for further work are not equivalent outcomes. A simple closed flag can conceal that distinction. The approved public message should reflect the actual disposition without exposing internal notes or sensitive diagnostic information.
Open311 provides an external reference for civic issue tracking, while FHWA's asset-management primer, Chapter 4 discusses information-system integration for transportation assets. Neither establishes that a given streetlight platform implements a complete GIS-CMMS-311 workflow. The agency and suppliers still need to agree on the actual fields, permissions and supported transactions.
Test the exceptions that make maintenance records drift
Use a pilot containing a missing asset ID, an asset moved or corrected on the map, a controller replacement, a duplicate report and a repair reopened after verification. For each case, identify which system owns the change and which systems receive an update. The purpose is to find conflicting authority before the data becomes difficult to reconcile.
A useful maintenance history preserves the asset even as its components change. A controller serial number should not silently become the permanent identifier of a pole or lighting location. Effective-dated associations allow the old device's events and the new device's events to remain traceable to the same asset. This is an information-model recommendation; local governance determines the authoritative asset definition.
The integration is working well when a supervisor can follow one report from intake to verified field outcome, understand exceptions and reconcile costs to the correct asset. That is a more meaningful acceptance result than showing identical map symbols in three applications. It tests the service process the technology is supposed to support.
Decide which system can change each field
Two systems updating the same location or status can create a loop in which yesterday's value repeatedly overwrites today's correction. Assign a responsible source for each shared field. The maintenance system may own work disposition, while GIS owns the authoritative asset location. The lighting platform may supply observations without being authorized to move the asset on the map. The allocation must reflect the city's actual operations.
In an illustrative workflow, a field technician corrects a pole location after a repair. Decide where that correction is entered, who validates it and how the accepted value reaches the other systems. If the correction remains only in a work-order note, the next citizen report may be attached to the same incorrect point. If every receiving system can overwrite the location independently, the correction may not persist.
FHWA's asset-management primer, Chapter 4 discusses the practical difficulties created by isolated asset systems and mismatched information. The proposed field-ownership method addresses that problem without assuming that one application must own every kind of record. A connected workflow can have several authoritative sources, provided their responsibilities and synchronization rules are clear.
Treat time and delivery order as part of the interface
Messages can arrive after the event they describe. Suppose a repair closes at 14:00, but an older alarm generated at 13:40 reaches the platform at 14:10. A simple arrival-order rule could reopen the issue as though the fault occurred after the repair. The integration needs the event's time meaning and an agreed rule for evaluating late information. The exact handling should be documented for the implemented systems.
Keep event time, received time and work-order change time distinct. Those fields answer different questions during an investigation. Also determine how a corrected record is represented: a new event, an update to an existing event or an explicitly linked correction. Otherwise the receiving application may count a correction as another fault, or silently erase the original sequence needed to understand the service history.
For a pilot, deliberately include a delayed message and a repeated delivery alongside the ordinary successful case. Verify that the result matches the agreed workflow. These are proposed integration scenarios, not guarantees supplied by Open311 or a GIS format. A civic issue standard and a geometry format do not, by themselves, define the city's work-order lifecycle.
Measure the work the integration is supposed to remove
An integration can be technically active while staff still copy asset numbers and reconcile duplicate tickets manually. Choose a few operational measures before expanding it: the proportion of reports confidently linked to an asset, duplicate work orders requiring review and closed repairs with a usable disposition. Define the denominators and examine exceptions rather than celebrating only the number of transmitted messages.
A hypothetical test of 100 reports might link 85 automatically, send 12 for review and reject three as outside the inventory. That result is more informative than claiming 85-percent accuracy without explaining the other cases. The reviewed records may reveal incorrect locations, ambiguous citizen descriptions or missing assets. Each finding points to a different improvement. The purpose is a more reliable maintenance process, not automation of every decision regardless of uncertainty.
Integration FAQs
Which ID should connect the systems?
A persistent agency asset ID is a useful common reference when the agency can maintain it. Retain each system’s native IDs and document the cross-reference.
Should every 311 report automatically create a work order?
Only where the agreed rules support it. Duplicate, uncertain-location and non-agency reports may need review before dispatch.
What should we ask the lighting-platform supplier?
Ask for supported interfaces, available fields, event/status definitions, authentication requirements and failure/retry behavior for the proposed configuration.
Review data access and export rights alongside the workflow. Bring LEOTEK one sample service journey and your system list to make the integration discussion concrete.
