Web services, and why you should care

This is the first of a series of blog posts about how to integrate to the Civica Cx Housing Management System using the Web Services API.

Why do I need an API?

Housing management systems are there to help housing organizations manage various aspects of their operations, such as property management, maintenance, leasing, tenant management, and accounting. Typically there is a need for the housing management system to 'talk' to other related systems, be that a Repairs Management System, Asset Management System, Payment provider. This can be to keep information up to date e.g. pass in repair status updates, to keep asset registers in sync between systems, and many other scenarios.

Web services integration can reduce or remove human effort in otherwise manually updating two systems, it reduces errors and introduces real-time updates. It encourages data to flow in a controlled way in accordance with the business rules on both systems.

An Application Programming Interface (API) is a way for different software systems to 'talk' to each other over the internet. In the case of Civica's Cx, the housing management system provides a Web Services API using the SOAP protocol, which allows other software systems to connect and interact with it.

SOAP in this case (unlike the bar you keep in your bathroom) standards for Simple Object Access Protocol. Imagine speaking to someone in the wrong language, or assembling a sentence in the wrong order, or for that matter humming different notes rather than using words. SOAP is just a standardised way of talking to one another so that both systems are talking the same language.

Do Web Services simply solve all my problems?

An important concept to grasp if you have not used web services before is that they don't 'push' data out to other systems. You can 'get' data, and you can 'push' data in to them... but they will not go off and find the other stream system and push the data in to that system.

Let's look at a real example. A tenant rings in to customer services to log a new repair. The agent logs that repair in the housing management system. The repairs contractor using their own workforce management system. But nothing will make that repair magically jump from one system to the other. The housing management system will sit there very happily knowing about the new repair, and the contractor will never know about it.

One of 3 things needs to happen:

1. A bespoke function( interface) needs to be created in the housing management system that would actually push the information out as and when needed,

2. Or, bespoke functionality needs to be added to the contractor system to periodically 'call' the housing system to 'get' any new repair jobs,

3. Or, bespoke functionality needs to be developed in a middleware application that sits between the two systems, essentially brokering conversation between the two systems.

Each has its own merits and drawbacks, and the requirements of the project would help inform the best way to go.

Developers can write code to call the web services API to pass in or get data from the housing management system. They can write code that can automate various tasks, like getting repair jobs, property warnings, sending letters, or creating new tenants. As we've said already, we do this using an API to avoid the manual effort in users updating both systems. It reduces errors, and can even check the data is valid before doing something with it. For example, don't create an email address if it doesn't have an @ symbol in it, because that would be wrong.

Some basic terminology you need to know...

Before we go into the details, let's quickly go over some basic terminology of web services:

• XML stands for eXtensible Markup Language. It is just text, but laid out in a structured form, an example for an XML file about books might look like the below.

<book>
    <title>The Great Gatsby</title>
    <author>F. Scott Fitzgerald</author>
    <year>1925</year>
</book>

• WSDL (Web Services Description Language) is an XML-based language used for describing web services. It's a way of describing how the web services can be called, what it can do, what data you can pass in, and what you can get from it. Developers can import the WSDL file in to their development environment and be able to see all the functions or methods the web services provides. Web services can only do specific things, they cannot do something that they were not written to do in the first place. The WSDL will tell them what the method is called, what data has to be passed in and in what format, e.g. some will want a date passing in, and others may want a number, or text.

• SOAP (Simple Object Access Protocol) is a protocol for exchanging structured information in the implementation of web services. It uses XML for its message format and typically uses HTTP or SMTP as the transport protocol.

• Endpoint: An endpoint is the URL where the web service is available. Such as http://www.google.co.uk or https://www.bbc.co.uk

• Request: A request is a message sent by a client to a web service to trigger a particular operation. e.g. Get repair jobs

• Response: A response is the message sent by the web service to the client in response to a request. It typically involve whether the call was successful, and includes information relevant to the specific request.

• Token: When a user or application authenticates with a web service API, they are issued a token by the service. They pass in username and password, and are provided with a token, which is simply a text string. Any subsequent requests to the web service pass in that known token to avoid having to re-authenticate every time. It's like a secret word...but one that changes after a certain amount of time.

With the basic terminology covered, let's take a look at how we can use SOAP web services to communicate with a housing management system.

How does this work in practice?

Let's say that we want to pass new repair jobs from the housing management to a third party contractor system.

1. Periodically, say every 2 hours, the contractor system calls the housing system to firstly authenticate. Username and password are passed in.

2. The housing management system checks the username and password against the user register and if it matches, will reply with the token to use.

3. The contractor system then calls the housing system passing in the token, and requests all repair jobs.

4. The housing management system identifies all repair jobs for that contractor and returns information about each in the response.

5. The contractor system then reads the response and adds those new repair jobs to its own database.

This is a simple process flow, but it illustrates how 'calling' a webservice is a 2-way conversation involving both passing in, and receiving data from.

That's all for now

So to wrap up, using web services APIs to communicate with a housing management system is a powerful way to perform various tasks like adding tenants and viewing rental history, improving efficiencies, reducing human error and opening up new possibilities.

We'll pick up in the next post the first steps of authenticating with the Civica Cx housing management system.