Cx Web Services – Retrieving Repair Work Order Details

In previous posts, we looked at how to retrieve a list of repair work orders using the Cx Repair Contractor web services. That approach works well for queues, dashboards, and summary views, but most real integrations quickly reach the point where a single work order needs to be fully interrogated or used by third parties.

Cx provides several closely related SOAP methods for this purpose. They all accept the same identifiers but return different levels of detail depending on intent and audience.

In this post we’ll cover:

• GetRepairWorkOrderDetails

• GetRepairWorkOrderDetailsDescription

• GetRepairWorkOrderDetailsWithClient

  
  

Prerequisites and security behaviour

Before diving into the methods themselves, it’s important to restate some fundamentals that apply to all Cx web service calls:

• A valid authentication token is required

• The token user’s Cx roles are enforced

• Functional Unit security is honoured

• If a user cannot see a work order in the Cx UI, they will not be able to retrieve it via SOAP

  
  

This becomes particularly important when working with WithClient, as access to client-related data can vary significantly depending on role configuration and organisational setup.

WorkOrderReference vs WorkOrderUid

All of the methods discussed here require a WorkOrderReference and a WorkOrderUid in the request schema.

In practice:

• The UID field is mandatory, so it must always be present in the request

• If you know the real WorkOrderUid, you should pass it

• In many integrations, only the reference is known

• In those cases, passing an empty GUID is common and generally works

• When both are supplied, Cx will usually resolve the order using the reference, and the UID is often ignored

• I've left out namespaces again as it just clutters the examples.

A very common request pattern therefore looks like this:

<rep:WorkOrderReference>WO123456</rep:WorkOrderReference>
<rep:WorkOrderUid>00000000-0000-0000-0000-000000000000</rep:WorkOrderUid>

This behaviour should be treated as implementation detail rather than guaranteed contract, so you should always test in your own environment.

1️⃣ GetRepairWorkOrderDetails

This is the primary “full detail” method. It returns almost everything Cx knows about a work order, including:

• Header information

• Address and asset

• Alerts

• Tasks and SORs

• Costs, priorities, and key dates

Request

<soapenv:Envelope 
  <soapenv:Body>
    <civ:GetRepairWorkOrderDetails>
      <civ:request>
        <sec:Token>abc123-token-value</sec:Token>
        <rep:WorkOrderReference>WO123456</rep:WorkOrderReference>
        <rep:WorkOrderUid>00000000-0000-0000-0000-000000000000</rep:WorkOrderUid>
      </civ:request>
    </civ:GetRepairWorkOrderDetails>
  </soapenv:Body>
</soapenv:Envelope>

Response (trimmed)

Repeated elements such as alerts or tasks have been reduced to a single representative example, but tags are retained so you can see the structure.

<GetRepairWorkOrderDetailsResult>
  <OrderReference>WO123456</OrderReference>
  <OrderStatusDescription>Complete</OrderStatusDescription>
  <PriorityDescription>Urgent</PriorityDescription>
  <ContractorName>Example Repairs Ltd</ContractorName>
  <Address>
    <Address>10 Example Street, Exampletown, EX1 2AB</Address>
  </Address>
  <Asset>
    <AssetReference>AST000123</AssetReference>
    <AssetTypeDescription>Flat</AssetTypeDescription>
    <Bedrooms>1</Bedrooms>
  </Asset>
  <Description>Repair door lock to communal entrance. Key sticking intermittently.</Description>
  <EstimatedCost>45.00</EstimatedCost>
  <ActualCost>0.00</ActualCost>
  <RepairTasks>
    <RepairTaskDetail>
      <TaskId>1</TaskId>
      <TradeName>Joiner</TradeName>
      <TaskStatusDescription>Complete</TaskStatusDescription>
      <EstimatedCost>45.00</EstimatedCost>
      <SorCode>9000</SorCode>
    </RepairTaskDetail>
  </RepairTasks>
</GetRepairWorkOrderDetailsResult>

When should you use this?

Use GetRepairWorkOrderDetails when you need:

• Task-level detail

• SOR and trade information

• Alerts and priorities

• Asset and address context

For most integrations, this is the default works order detail call.

2️⃣ GetRepairWorkOrderDetailsDescription

Sometimes you don’t need the full structure — you just want the plain-text description of the job. this is perhaps more useful for say a portal, mobile app or PowerBI dashboard. The good thing about this kind of method is you're not having to pull bac

This method exists specifically for lightweight use cases such as:

• Contractor mobile apps

• Notifications

• Simple downstream integrations

  
  

Request

<civ:GetRepairWorkOrderDetailsDescription>
  <civ:request>
    <sec:Token>abc123-token-value</sec:Token>
    <rep:WorkOrderReference>WO123456</rep:WorkOrderReference>
    <rep:WorkOrderUid>00000000-0000-0000-0000-000000000000</rep:WorkOrderUid>
  </civ:request>
</civ:GetRepairWorkOrderDetailsDescription>

Response

<GetRepairWorkOrderDetailsDescriptionResult>
  <Description>Repair door lock to communal entrance. Key sticking intermittently.</Description>
</GetRepairWorkOrderDetailsDescriptionResult>

There are no assets, tasks, costs, or alerts — just the description.

3️⃣ GetRepairWorkOrderDetailsWithClient

At first glance, GetRepairWorkOrderDetailsWithClient looks very similar to GetRepairWorkOrderDetails. Structurally, they are almost identical.

The difference lies in intent and audience.

This method is designed for scenarios where the repair order needs to be mapped to an external client or contractor system, and therefore includes client-facing identifiers that are not always relevant internally.

Request

<civ:GetRepairWorkOrderDetailsWithClient>
  <civ:request>
    <sec:Token>abc123-token-value</sec:Token>
    <rep:WorkOrderReference>WO123456</rep:WorkOrderReference>
    <rep:WorkOrderUid>00000000-0000-0000-0000-000000000000</rep:WorkOrderUid>
  </civ:request>
</civ:GetRepairWorkOrderDetailsWithClient>

Response (trimmed)

<GetRepairWorkOrderDetailsWithClientResult>
  <OrderReference>WO123456</OrderReference>
  <ContractorName>Example Repairs Ltd</ContractorName>
  <ClientId>0</ClientId>
  <ClientCode/>
  <ClientName/>
  <ClientOrderReference/>
  <Description>Repair door lock to communal entrance. Key sticking intermittently.</Description>
  <EstimatedCost>45.00</EstimatedCost>
</GetRepairWorkOrderDetailsWithClientResult>

How WithClient is different in practice

It does beg the question why didn't these tags just get added to GetRepairWorkOrderDetails. Wouldn't that be simpler - possibly. But bear in mind there are quite a few organisations now using Cx Web Services in production, so Civica should (and whether they do is another story) be sympathetic to not breaking existing code by adding or modifying existing tags. There's also the question of security, however Cx Roles, Functional Units and user configuration should take care of that.

The key differences are not always obvious from the schema alone:

• Client fields may be null, defaulted, or suppressed depending on configuration

• Some organisations do not use client mapping at all

• Others rely on these fields to link Cx orders to external finance or job systems

• Access to client fields is still governed by Cx roles and Functional Units

Because of this, you must test WithClient in your own scenario. Do not assume that the presence (or absence) of client data in one environment will match another.

If you do not need client-side identifiers, the standard GetRepairWorkOrderDetails call is usually simpler and more predictable.

Choosing the right method

Requirement	Recommended method
Full operational detail	GetRepairWorkOrderDetails
Lightweight text only	GetRepairWorkOrderDetailsDescription
External client / contractor mapping	GetRepairWorkOrderDetailsWithClient

Final thoughts

Once you’ve retrieved a list of repair work orders, these methods let you progressively enrich your integration:

• Start with summaries

• Pull detail only when required

• Use the lightest method that meets your needs

Cx’s SOAP services may be lengthy, but they are consistent, security-aware, and powerful once you understand the patterns — especially how roles, Functional Units, and identifiers influence what you actually get back.

We'll continue this series in future with other related calls. As always, if you liked this please do leave a comment and if you would like to see any particular methods discussed, do get in touch.