Cityworks Asset Management Connector

Overview#

The Cityworks Asset Management Connector links your existing Cityworks deployment to the Argus platform so that work orders, service requests, and outage events move between the two systems without anyone re-keying data.

Utilities, municipalities, and public-works agencies that run the Cityworks Asset Management System already hold their maintenance backlog, crew assignments, and citizen-reported issues inside Cityworks. The connector reads that data into Argus and writes operational events back, so a single team can see Cityworks work orders alongside the rest of the operational picture. Outage events detected in Argus open Cityworks service requests automatically, removing the manual hand-off that normally sits between an operations centre and a field-maintenance platform. Every read and every write is scoped to your organisation and recorded in an interoperability audit trail, so the activity is fully accountable for compliance reviews.

Key Features#

Bidirectional Connectivity: Reads Cityworks work orders into Argus and writes Argus outage events back to Cityworks as new service requests, keeping both platforms aligned from a single configuration.
Encrypted Credential Storage: Each Cityworks endpoint credential is encrypted at rest with AES-256-GCM and bound to its own record, so stored secrets cannot be transplanted between rows or organisations.
Connectivity Testing With Latency: A one-click test authenticates against the Cityworks endpoint and reports success or failure together with a measured round-trip latency, so operators can confirm a connection before relying on it.
Paginated Work Order Ingest: Work orders are fetched page by page and upserted into Argus, with deduplication on the external Cityworks identifier so repeated runs update existing records rather than creating copies.
Operational Picture Enrichment: Each ingested work order is emitted as a geolocated operational entity with normalised status and a confidence score, placing Cityworks assets on the same map and timeline as everything else.
Automatic Service Request Creation: An Argus outage event raises a matching Cityworks service request with the originating reference attached, so field teams act on the same event the operations centre is tracking.
Inbound Status Webhooks: Cityworks status changes arrive over a signed webhook, update the linked Argus work order, broadcast a real-time event, and can auto-restore an outage once all of its work orders are complete.
Full Interoperability Audit Trail: Every register, ingest, and export action is logged with the acting user, the organisation, and the affected record, giving compliance teams an end-to-end record of cross-platform activity.

Use Cases#

Electric, water, and gas utilities connect an existing Cityworks Asset Management System to Argus so that crew work orders appear in the unified operational view, and outage events raised in Argus open Cityworks service requests for the responding field teams without a phone call.

Municipal public-works departments bring street, drainage, and facilities work orders into Argus for a combined view across departments, while citizen-reported issues continue to live in Cityworks as the system of record.

Emergency and outage operations centres rely on the inbound webhook so that when field crews close every Cityworks work order tied to an outage, the outage is automatically advanced to restored and the change is broadcast to every connected console in real time.

Compliance and accountability teams review the interoperability audit trail to demonstrate exactly which records were read from or written to Cityworks, by whom, and when, satisfying inter-agency data-handling obligations.

Integration#

Cityworks Service Layer: The connector speaks to the Cityworks Asset Management and CRM service layer over asynchronous HTTPS, using token-based session authentication obtained from the Cityworks authentication service. This is the vendor's own service interface rather than an open standard.
REST and Webhooks: Outbound calls are JSON over REST. Inbound Cityworks status changes are received at /webhooks/cityworks/{org_id}/work-order-updated, validated, mapped to internal status, and applied to the matching work order.
Programmable Operations: Connection registration, connectivity testing, work order ingest, and outage export are all driven through the platform API so they can be scripted, scheduled, or wired into existing operational tooling.
Normalised Operational Model: Ingested Cityworks records are mapped into the platform's shared operational entity model with consistent status values and geolocation, so they behave identically to records from any other connected source.
OAuth2 and JWT Sessions: Access to the connector follows the platform-wide authentication pattern, with every operation requiring an authenticated session and scoped to the caller's organisation.
Customer Plug-In Benefit: A customer supplies only a Cityworks base address and login; the platform handles encryption, pagination, deduplication, status normalisation, and audit, so a working two-way link is established without bespoke development.

Open Standards#

AES-256-GCM (NIST SP 800-38D): Cityworks endpoint credentials are encrypted at rest with authenticated AES-256-GCM, with additional authenticated data binding each ciphertext to its own record.
HMAC SHA-256 (FIPS 198-1): Inbound Cityworks webhooks are verified with an HMAC SHA-256 signature using the shared secret, following the widely adopted signed-webhook convention with a sha256= signature prefix and constant-time comparison.
HTTP/1.1 over TLS (RFC 9110 and RFC 8446): All connector traffic to and from Cityworks runs over HTTPS, so credentials and payloads are protected in transit.
JSON (RFC 8259): Request and response bodies exchanged with the Cityworks service layer, and the stored connection metadata, use JSON as the interchange format.
OAuth 2.0 and JSON Web Token (RFC 6749 and RFC 7519): Platform access to the connector uses bearer authentication with JSON Web Tokens issued under the platform OAuth 2.0 flow.
WebSocket (RFC 6455): Work order status changes and outage restoration are broadcast to connected operational consoles over WebSocket for live updates.
WGS 84 (EPSG:4326): Work order latitude and longitude values are carried as WGS 84 decimal-degree coordinates when emitting each record into the operational picture.
UUID (RFC 9562): Connections, organisations, and synced records are identified with universally unique identifiers for stable cross-system referencing.

Security & Compliance#

Every connector operation is scoped to a single organisation, so one tenant can never read or write another tenant's Cityworks data. Stored credentials are encrypted with authenticated AES-256-GCM and bound to their own record, and inbound webhooks are rejected unless they carry a valid HMAC SHA-256 signature. Each register, ingest, and export action writes an interoperability audit entry capturing the acting user, the organisation, the affected record, and the action taken, giving compliance and accountability teams a complete, reviewable history of all cross-platform activity.

Last Reviewed: 2026-05-26 Last Updated: 2026-05-26