This is the second part of our three part blog series about our Polonious Integration journey. We hope it’s useful for IT teams and businesses seeking to develop their integration practices, integrate with Polonious or hopefully both. If you haven’t read part 1 yet, it is here.

When the light bulb went on

Around 5 years ago, our transition started to a newer, more flexible integration capability. Most importantly for our team, this also meant less time spent on integration and a whole lot less stress on the projects involved.
The reduced IT spend on Integration meant smaller invoices for customers and more time for core UI and micro service developments that are starting to really bear some fruit.
We still encounter integration challenges, however they are quicker to resolve with minimal interactions. Once all parties understand how to operate, we can break down these project meetings into three to four distinct groupings:

  1. Business discussions between our business facing experts and the customers front-line business people to determine the business requirements. In particular – what data needs to be transferred between which systems and what should the high-level workflow look like.
  2. Technical integration discussions with client IT systems owners to discuss the business requirements and discuss the technical approach. This includes determining the relevant endpoints, the communication methods / protocols to use, and what authentication methods are supported.
    We also have some internal discussions in case we need to write an adaptor to deal with translating the other parties preferred communication method to ours. We then work with the systems owners to determine the technical details to implement the adaptor.
  3. IT Security and network discussions. No business users needed. Generally these are fairly rapid as we are well across all security / technical needs and are ISO27001 certified, which means we follow best security practices and generally have great solutions for security related questions.

How we made the transition

To move to this better place, we needed to create tools that allowed the business users to have discussions about ‘what goes where’ without any IT involvement.

This required building secure, flexible REST capabilities for our primary integration driver. In our world, this was ‘Create Case’.

REST APIs actually date to the early 2000’s. It wasn’t until 2014 that they became widely acceptable as an alternative to XML Web Services and other protocols commonly used by large corporations. The reasons for this change were the ease of adoption by other teams, the speed, simplicity and flexibility of the specification.

We started around this time to look very closely at REST capabilities and decided to re-develop our case ingestion to have a REST API.

Flexible REST

Most REST APIs are fixed in nature, you get a few fixed parameters, well documented and defined which you can POST (in the case of creating things) but these are not very adaptable.
To meet our need to ensure the ‘what goes where’ conversations could happen without our IT team involved, we had to develop a very adaptable, configurable, Web User Interface for this crucial service.

So our Create Case REST API is actually up to the customer. What fields are POSTable, is defined in a web interface, how our POST api responds to these is also up to the customer. By doing this, we can handle 95% of create case needs. For the rest, there are adaptors.

The upside for our customers

Since this capability is now an easy to use part of our user interface, it’s really easy not to involve internal IT teams (from both sides) in the many of the conversations required to get business data transferred between systems. Here is how the conversation generally goes:

Polonious: “Send me a JSON example of what you want to send to us”

Customer: “What’s JSON?”. A short discussion of this format ensures, usually we send a simple example over like this:

{

“claimNumber”: “GHT202320”,

“referralReason”: “Claim initiated within 7 days of policy inception”

}
Customer: “Ah, I get it!”… sends example of data to be used to create case.

Polonious: “Here’s a few things we need to alter and discuss” this is usually a short discussion about types of fields, how fields should be formatted etc. This can involve customer IT, or that can be deferred to an adaptor we write to absorb whatever is easiest to send from the customer’s end.

Customer: “OK, that’s it, we’re ready, here’s some examples of what to load”

Polonious: “I’ve mapped them using our create case api tool, here’s the URL for your team to test it, here’s some test credentials to use, here’s where it will appear”.

Customer IT and our IT then usually get involved if there are firewall/network/other issues with data. This is often a fast process as it’s a simple port 443 request (secure TLS 1.3).

Polonious: “Looks like the cases you send created successfully, let’s get back to talking about the process you need to follow up these cases, and what the feedback loop looks like”

If everyone is available, networks are in place, this process can be over in hours. This used to take days, weeks, months of elapsed time depending on availability of many parties to the discussion.

Learning: As REST services expand, integration projects shorten

The rather unscientific graph on the right shows effectively what’s been happening for the last 5 years at Polonious. As we invest more time and effort into our REST services, the time taken to integrate to new platforms decreases.

Crucial to this transformation was understanding the best way to structure our REST services. There are conventions for naming and versioning REST services that are important to provide these advantages:

  • Conventional naming of APIs means quicker adoption by IT teams wanting to integrate to your services. This book was a lot of help: https://www.manning.com/books/irresistible-apis
  • REST service versioning means IT teams do not need to re-develop their integration to your software every time you alter the API. Believe me, they don’t want to.
  • Documentation. Great API documentation greatly speeds adoption of your APIs to other IT teams. We invested a considerable amount of time in explaining, in documentation what our services do and how to use them. We even wrote an SDK in Spring Boot to demonstrate using them in Javascript.

For us, the first step of the API journey was making our own ‘case intake’ web forms use REST APIs instead of requiring Java engineers to bespoken write each of them in our chosen tool (Java/JSP).

Doing this, expanded our public APIs to cover most GET requirements an external team might need. This further shortened integration projects.

We can now hand over web form development to any client team willing to invest a little in learning our REST APIs. Of course we’re still available if clients don’t have capacity. Many client IT teams have done this. We hear all the time of IT teams building REST calls to our system with web forms or other means. This is great for all concerned as it saves ours and our client’s time and effort. Since our key system updates and reads are now wrapped in REST calls, we are pleasantly surprised by the capabilities client’s teams have developed with these APIs. A recent example was a team developing a button on a sales force mobile app, this button was used by sales reps in the field to photograph potential fraud and have immediate cases created in Polonious to process the leads from the field.

Learning: As external teams need more information, add that to your REST APIs first

We integrate to our own client’s internal systems, but also to other partners in the vendor space. With each information need a client expressed, our process became ‘REST FIRST’ which meant we expanded our REST APIs as these needs evolved over the last 5 years. This has had a profound impact on how easy it is for a customer to integrate to our software.

In the third and final part of this series, we will go over the integrations we have developed to other systems and where we’re expecting to take this capability in the future. Thanks for reading so far, I hope you enjoy part 3.