Cx Web Services Step by Step - Get me a token!

Jim Walker
Jun 1, 2023
6 min read

Updated: Mar 13

In an earlier post, web-services-and-why-you-should-care we talked through what web services are and what you can do with them. We then also learned in soap-vs-rest, how Civica are due to rebuild all the current web services on the REST protocol.

All that said, SOAP remains a valid candidate on which to build your integration project and so over a number of posts, I'll be talking through how each of the important web services work, and how they can be used.

What language should I use?

No self respecting consultant would get through a blog post without saying 'it depends', and in this case it very much does. Personally, I use different languages depending on what i'm trying to achieve, what I have access to, what is easiest, and hopefully the quickest and best to get to the end result.

I regularly find myself using different languages for different purposes: C# for web applications, javascript for front end UI, VB for desktop applications, VBA for automation, M and DAX for Power BI and all flavours of SQL in SSIS and SSRS and if you're really brave enough to admit others like Arduino for home automation projects. You can make a web services call in most of those in one way or another. Some will be easier and some will help you more than others.

But this comes down to personal choice, the project at hand and often you will be restrained by the language in which the systems you use and how they were built. I don't really care about that, that's up to you. But what I am going to cover here is how to use Cx Web Services. What goes in to each method, what you must provide, and what you get back. On occasion I may even say why you might need to do something specific, and I may go so far as to actually recommend a particular approach, but again no project is the same. I'd love to hear in the comments how you have done something cool with them.

Authentication or Authorisation?

So let's talk about authentication and authorisation. Authentication is who you are, Authorisation is what you can do. When we connect to Cx we need to firstly authenticate, so that only trusted users/organisations can actually pass data in and out of Cx. Once we've authenticated and Cx knows who we are, we then need to consider what we are actually allowed to do. For example, one user can view repair information only, but another might actually m need to be able to update it.

We can very quickly discount Authorisation because Cx already handles this for you in Quick Menu > Roles. In here, you lay out permission for whether a user can view a screen, edit a screen and what buttons they can click. This makes things a lot more simple when we come to opening up access to Cx's API. Lets say we're setting up a new contract with Ohm Sweet Ohm Electrics Ltd, our new electrical contractor. They have their own flashy work management system and want to get work orders from us via an API rather than email, or god-forbid printed jobsheets.

We would first set up the Contractor in Cx alongwith a Contract and Definition for what work they can do. For a contractor to connect to our API, you would then need to create a Security User, ticking that 'API user' box. Importantly, we now assign a role. This role contains permissions for what we want them to be able to do. The same as how you would set it up if they used the front end of the application. Cx then applies that same role permissions matrix to any requests done via the API. Pretty cool eh.

Where are these web services then?

Cx web services are installed at the same time as Cx is installed. They are actually just part of the actual application....at the time of writing, you get them whether you like it or not.

As of Cx version 23.1, there are 21 of these top level services, such as WSRepairService, WSAssetService, WSAllocationsService. Each one of those services contains a group of related functionality with different 'things' you can do. The biggest service in terms of functionality being the WSRepairContractorService offering a whopping 164 different 'methods'. Before you get excited though, some are really very boring, like getVATCodes that returns an array of VAT Codes set up in Cx.

If you havn't already got a copy, now is the time to ask Civica for a copy of the Cx Web Services Integration document. A whopping 2,030 pages that one should never ever read cover to cover, but it is useful for looking at what methods exist. From that you can look at how you can take advantage of that functionality in your business.

So if you don't believe they actually exist, simply add 'webservice/wstokenservice' on to your usual Cx URL. If your Cx application were this for example:

https://mysitecxtest.civica-cx.co.uk/cx

...then to hit the token service, the URL would be:

https://mysitecxtest.civica-cx.co.uk/cx/webservice/wstokenservice

...and you should land on a page that looks a bit like this:

Very underwealming, but we know they are there, and we can now talk to them. If you don't land on this page, and more importantly if Ohm Sweet Ohm Electrical can't hit that page, then the first port of call is to get your networking team to check if firewall rules allow this. By default they won't (shouldn't).

The Civica document we referred to earlier at this stage proves useful. We know that we can hit the WSTokenService, but how do we start to use it. Each web service is itemised, along with the all important 'methods'. For the WSTokenService, this is shown below.

The one we care about when connecting to Cx is the GetUserWSToken.

So now what?

So lets say Ohm Sweet Ohm wants to pick up all new orders every morning at 9am. The very first thing they need to do is make a call to the WSTokenService and specifically the GetUserWSToken. In doing so, they pass in their username and password, and Cx hands back a nice shiny token. A token is simply a string of text. A 'magic word' that in future, whenever they want to do anything, they pass that magic word back to Cx. From this, Cx knows who they are, what user they are and therefore what they are allowed to do. Like any good key, they expire after so long and you will have to prove who you are again to get a new one.

So in whatever development language or IDE you choose, your code needs to first make a request to the WSTokenService, specifically to the GetUserWSToken method.

Here we have to provide both Password, and Username.

<soapenv:Envelope>
  <soapenv:Header/>
   <soapenv:Body>
      <tem:GetUserWSToken>
         <tem:request>
            <civ:Password>HappyB!rthday</civ:Password>
            <civ:UserName>Jim.Walker</civ:UserName>
         </tem:request>
      </tem:GetUserWSToken>
   </soapenv:Body>
</soapenv:Envelope>

When that call is made to Cx, it provides a nicely structured reply from which you can pick out the important elements.

<s:Envelope>
   <s:Body>
      <GetUserWSTokenResponse>
         <GetUserWSTokenResult>
            <a:InvalidReason i:nil=”true”/>
            <a:IsValid>true</a:IsValid>
             <a:Token>diys1t3r0iadxe</a:Token> 
            <a:TokenExpiry>2023-06-01T19:00:16.5718655+01:00</a:TokenExpiry>
         </GetUserWSTokenResult>
      </GetUserWSTokenResponse>
   </s:Body>
</s:Envelope>

The overall request was valid
The Token we need to use in future is diys1t3r0iadxe
The Token will expire on the 1st June 2023 at 7pm (more or less

Conversely, if the username or password was wrong, we would get an 'Invalid' response like the one below.

<s:Envelope>
   <s:Body>
      <GetUserWSTokenResponse>
         <GetUserWSTokenResult>
            <a:InvalidReason>Invalid login. Please try again.</a:InvalidReason>
            <a:IsValid>false</a:IsValid>
            <a:Token i:nil=”true”/>
            <a:TokenExpiry i:nil=”true”/>
         </GetUserWSTokenResult>
      </GetUserWSTokenResponse>
   </s:Body>
</s:Envelope>

We'll see in later posts how to make calls to do something more useful, like getting works orders, or creating appointments but in anyone of those method called, if you pass in a token that has expired, expect to get a response similar to that below. if this happens, you would need to request a new token, and try the method again.

<s:Envelope>
   <s:Body>
      <s:Fault>
         <faultcode>s:Client</faultcode>
         <faultstring xml:lang=”en-GB”>Exception Message:Access denied – Invalid token</faultstring>
      </s:Fault>
   </s:Body>
</s:Envelope>

Erm....where are the namespaces prefixes?

The eagle-eyed will have noticed in my example code that i have chosen to remove the namespace prefixes. This is purely because I want to focus on the actual data elements we care about.

Namespaces are a requirement when constucting an XML document which is what this is. Imagine a large response where AssetId is mentioned multiple times. Namespaces help us group together the data elements so we know which one we are talking about.

You can see the namespace as the prefix to each tag, for example 'soapenv'.

Do your own google search if you want to find out more...there's far more to them and why they're used.

You absolutely need the namespace prefixes, and it won't work without them. Your development environment should help add or populate this for you, and if not, test your code in something like SOAP UI first, and again SOAP UI will add them. We may go in to how SOAP UI can be used for testing later on. You will see from the examples below, it is far easier to read the examples if we omit the namespace. and this is a very simple method.

With:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/" xmlns:civ="http://schemas.datacontract.org/2004/07/Civica.Housing.Cx.WebServices.Contracts.DataContracts.Modules.Security">
   <soapenv:Header/>
   <soapenv:Body>
      <tem:GetUserWSToken>
         <tem:request>
            <civ:Password>HappyB!rthday</civ:Password>
            <civ:UserName>Jim.Walker</civ:UserName>
         </tem:request>
      </tem:GetUserWSToken>
   </soapenv:Body>
</soapenv:Envelope>

Without:

<soapenv:Envelope>
  <soapenv:Header/>
   <soapenv:Body>
      <tem:GetUserWSToken>
         <tem:request>
            <civ:Password>HappyB!rthday</civ:Password>
            <civ:UserName>Jim.Walker</civ:UserName>
         </tem:request>
      </tem:GetUserWSToken>
   </soapenv:Body>
</soapenv:Envelope>

That is all for now

So, we've talked about how we can authenticate with Cx, and how permissions are then handled. We've constructed a call to get that magic Token from Cx, and now we're connected, the world is our oyster! Look out for future blog posts where we'll get in to some actual business functionality.