Cx Web Services – Updating a Repair Works Order Status
- Jim Walker
- 18 minutes ago
- 4 min read
In previous posts we looked at how to retrieve repair works orders and then pull back full works order details from Civica Cx. If you have not already seen that post, I suggest you read that first.
That’s great, but only a piece of the whole picture.
Typically Cx is the client system, and a 3rd party contractor is using their own in house, or off the shelf software. I refer to this as the external system. Once the external system has received a works order and started doing something with it, Cx must be kept in step. If your system thinks a job is live, on site, delayed, or cancelled — but Cx doesn’t — things unravel very quickly - not in a good way!
This post looks at the method used to keep Cx aligned with reality:
UpdateRepairWorksOrderStatus
Why status updates matter more than you think
Cx is still the authoritative system for repairs, even when the day-to-day management happens elsewhere. Its important you recognise it as the master/golden/reliable source of order information.
If you don’t update Cx correctly:
Customer Services Teams (CST) see out-of-date or misleading information
Orders appear stuck or “lost”
SLA reporting becomes meaningless
Subsequent web service calls start failing in non-obvious ways
Cx is unforgiving at the best of times, but in this scenario, you actually want that rigidity. If you try and do things to an Order Cx disapproves of, it will quietly refuse to cooperate. Worse, it will only tell the requesting system about this. If you don't handle that feedback, you will not know about it.
RepairStatusCode vs RepairMasterStatusCode (this matters)
When updating a works order status, you must use RepairStatusCode, not RepairMasterStatusCode.
RepairStatusCode - These are the configurable, organisation-specific statuses used by integrations.
RepairMasterStatusCode - These represent Cx’s internal fixed workflow.
You cannot override the master workflow via web services.
If you try to move a works order in a way that violates the master status flow, Cx will reject the update — even if the status code you supplied looks valid. Remember also status codes have Effective Dates.
You control RepairStatusCode. Cx controls RepairMasterStatusCode.
Where do valid status codes come from?
If you’re unsure which status codes are valid for works orders, they can be queried directly:
select *
from RepairStatusCode
where WorksOrderApplicable = 1
This gives you the only set of statuses that should ever be sent via UpdateRepairWorksOrderStatus.
Hard-coding values without understanding the workflow defined in this table is a common source of bugs...the simple way round this is test in the front end - you can't do something in the web services if you can't do it in the front end.
When should UpdateRepairWorksOrderStatus be called?
Any time your system moves a job to a new meaningful state, or when you need to pass back valuable information, such as:
Received by contractor/accepted
Live / in progress
On route
Awaiting materials
Delayed
No access
Practically complete (in cases when you want to move manually on to complete)
Its up to you how you set up Repair Status Codes, but generally the above are all considered Work In Progress as far as Cx is concerned.
⚠️ Cx will not allow you to move an order from one status to the same status. Doing so will return an error.
What you must send
At a minimum, each request must include:
Authentication token
WorkOrderId
WorkOrderUid
RepairStatusCodeId (the new status)
StatusDate – when it actually happened
StatusSetDate – when Cx was informed (can be blank)
StatusSetByUserId – mandatory, but not used
You can also send:
Free-text comments / reason - These are visible to Cx users and are extremely useful for CST.
If the order is late at the point you update it, a late completion reason must be supplied in the same call.
Example UpdateRepairWorksOrderStatus request
<soapenv:Envelope>
<soapenv:Header/>
<soapenv:Body>
<civ:UpdateRepairWorksOrderStatus>
<civ:request>
<civ1:Token>YOUR_TOKEN</civ1:Token>
<civ2:NewStatus>
<civ2:Comments>Engineer on site</civ2:Comments>
<civ2:StatusCodeId>11</civ2:StatusCodeId>
<civ2:StatusDate>2022-10-06T20:40:00</civ2:StatusDate>
<civ2:StatusReasonId>0</civ2:StatusReasonId>
<civ2:StatusSetByUserId>0</civ2:StatusSetByUserId>
<civ2:StatusSetDate xsi:nil="true"/>
</civ2:NewStatus>
<civ2:WorkOrderId>113427</civ2:WorkOrderId>
<civ2:WorkOrderUid>0eb0a7b8-8e0d-45b4-bd73-d7ec9c9b5bc9</civ2:WorkOrderUid>
</civ:request>
</civ:UpdateRepairWorksOrderStatus>
</soapenv:Body>
</soapenv:Envelope>
What happens if you don’t update statuses correctly?
This is where integrations quietly break.
1. You stop seeing new orders
Many integrations filter orders by status after calling GetRepairWorkOrders.
If Cx thinks an order is cancelled or complete — but your system doesn’t — it may never be returned again.
2. You don’t know an order was cancelled
If a client user cancels a job in Cx and your system keeps trying to move it to WIP, every subsequent update will fail. From Cx’s point of view, the order is no longer valid to progress.
3. You can’t move the order forward
Cx enforces its master workflow. If you attempt to jump states or move backwards, updates are rejected.
4. Customer Services end up working with bad information or worse sharing it
If statuses aren’t flowing back:
Call handlers give incorrect updates to tenants
Jobs appear “live” when they’re not
Confidence in the system erodes...fast
Always check the response (seriously)
One of the most important rules with web services is that its a 2 way conversation - You call Cx and ask it to do something, it responds with a very technical response, with words to the effect of:
"Yes okay i've done that"
"No, I couldn't" (and if you're extremely lucky it might even tell you why!)
Some form of error because you basically got your request wrong - missing or extra data, wrong data types, wrong 'SOAPAction' or wrong endpoint.
In short, never assume a status update worked.
The external system must:
Check the response
Log failures and raise them to staff for action
Stop sending follow-on updates if one fails
If a status update is rejected, subsequent calls are unlikely to work, because Cx does not believe the order can legally move to that status.
A common real-world example:
Contractor system moves job to WIP
Client user cancels the job in Cx
Integration continues sending WIP updates
Every call fails
Handling these conflicts properly is critical — and we’ll cover that in a future post.
Summary
UpdateRepairWorksOrderStatus is not just a courtesy call to Cx — it’s a gatekeeper.
Used correctly, it:
Keeps everyone informed
Maintains system and reporting integrity
Allows completions and invoicing to work cleanly
Used incorrectly, it:
Breaks downstream integrations
Hides jobs
Leaves systems permanently out of sync
In a future post, we’ll look at what happens when things go wrong — and how to detect, recover from, and handle invalid status transitions safely.
Check out other articles in this series:
Comments