A Basic Guide to Scoping an Integration | Blog

SaaS Integration, Embedded iPaaS and API news for SaaS teams.

6th December 2019

The key to creating a successful integration more often than not hinges on its original definition. While on the face of it this should seem like a simple enough task, often high-level requirements miss the low-level detail required to create a fully optimised integration.

The lack of clarity in a definition can stem from a number of factors. In this blog we are aiming to unpack the language behind integration requests, and what you should be asking, to ensure your integration project has the best chance of ‘first time delivery’ success.

Breaking Down Integration Requests

SaaS companies regularly receive ‘Integration Request’ tickets in their helpdesk inbox, but the ways in which they are conveyed can vary vastly. For example a common message may simply be:

“I want an integration with Zendesk”

While this identifies a need for an integration between the host application and, in this case, Zendesk, it is the lowest level of request, offering little insight into what they want to integrate. 

It is an almost near-impossible brief. Popular applications like this offer a vast array of services. With no indication as to the basics of what the user is trying to achieve, creating an integration without some back-and-forth makes responding quickly to this request a lottery.

“I want to sync my contacts with Zendesk”

Now at least there is some detail as to the areas of the application that need to be worked with. From this statement it tells you:

  • the application to connect to
  • the methods to be used to create the integration
  • that it’s a two-way integration

You can unpack this to get a barebones view of what the integration will look like. However there is still work to do. As a minimum there is a need to further define what data fields within the contacts are required to update between the applications (read more on this below). 

“I want to create a new ticket in Zendesk when a deal reaches a certain stage”

Requests like these build upon the previous type of request, offering up more detail in order to perform a more complex bespoke task. On top of the initial requirements you have discovered:

  • a trigger (a deal reaching a certain stage
  • an action (create a ticket in Zendesk)

This also tells you that you will have to include some form of logic in your integration so it will only run when a record meets a certain parameter. 

The more detail the better…….

The Language Behind an Integration Request

One of the first stumbling blocks in defining an integration is the language used. Depending on the technical competence of the person requesting the integration you may find verbs such as “sync”, “automation”, “connection”, “workflow” or even branded terms such as Zap or Cycle. (Yes we’re guilty of using our own term for integration, however you can change it to whatever you like inside the Cyclr Console 😉 )

While they mostly all refer to the same concept, there are hidden details to be found within them:

TermDefinition
AutomationTerm often used to describe a background task to improve productivity, typically with an automated trigger and a defined action 
ConnectionIndicates that a data link between systems is required, with non-specific requirements  
Sync / IntegrationTwo-way data integration, ensuring records in both SaaS applications match
WorkflowIndicates a full process, often with multiple systems and the need for logic

Therefore don’t take the terminology at face value. We regularly have conversations where the individual says ‘sync’ but means ‘automation’, ‘automation’ but means ‘workflow’……. We get caught-out and we live in this world.

Who is asking for the integration?

More often than not, the person requesting an integration is trying to solve a problem on the front line, often without the technical insight to define it fully. This is by no means a deal breaker. The main information you need to build an integration is around their real-life use case. So as long as they can supply enough detail to give you a rough outline of what they require you can ask the right questions to get the full picture.

What use case information do you need to define an integration spec?

At a base level, you are going to need to know the following information to fully design an integration:

  • the applications data is transferred between
  • what the trigger for the integration should be
  • which data points are needed to be accessed

These may be unpacked from an initial request (as the examples above), but you may need a deeper level of understanding, including:

  • who the integration is aiming to help?
  • what key data is required to be extracted/sent to another source?
  • are there are any exceptions to the data movement?
  • are there custom data fields that need to be accessed?

These pieces of information can help you hone the areas of a system you’ll be working with.

Extrapolating a User’s Use Case

For example, if you are told that the integration is to help sales team members manage their deals, you know that within a CRM system you’ll be working with objects such as deals, organisations and contacts as a minimum. 

This can then be further fleshed out with additional use case information such as “the need to keep their customers in the loop about their deal”. This would mean adding some form of communication application (via email, chat message or existing marketing list) into the workflow, extending the bones of the template to add more functionality. 

The more you can dig into the practical use of the integration the more value you are able to add in the form of functionality. As an integrator it is a good idea to ask these questions up front. This allows you to avoid the endless back-and-forth of integration definition. Leaving you to get to work delivering something that offers your users a lot of value.

Unpacking Use Cases to Create Workable Integrations

So you’ve managed to get a complete integration use case defined by your user, great job! The next challenge is translating that into how the applications you want to integrate work. 

If you haven’t noticed, applications vary, a lot. So while you may know the areas and objects you want to interact with not all APIs will ready baked to give you the necessary data from a single endpoint.

For example, you want to be able to automatically send a user a message when the deal they are attached to in your CRM has been marked “won”. This use case could look something like this:

“Get Updated Deals” → See if deal is marked “won” → If yes, send customer an email

Simple. 

Sadly not always.

Not all CRMs directly provide the contact details of those attached to a deal. You may need to amend this flow to something like this:

“Get Updated Deals” → See if deal is marked “won” → “Get Deal Contact” (matching DealIDs) →  If yes, send customer an email

But what if there are multiple contacts on a deal? With some CRMs you can define a “Primary Contact”, so you can extend this workflow like so:

“Get Updated Deals” → See if deal is marked “won” → “Get Deal Contacts” (matching DealIDs) → “Get Primary Deal Contact” –> If yes, send customer an email

So something that on the face of it looked relatively simple needed to be unpacked further based on the system you’re working with. By familiarising yourself with how an application interacts with itself you will begin to be able to formalise these integrations far quicker. 

Lesser Thought of Integration Requirements

There are a few other things worth bearing in mind when specing out an integration from a use case.

That Syncing Feeling

With any “sync” request, you’ll have to define a mechanism to identify data coming from one application to the other. If this is not managed within the integration you could find yourself creating data errors such as: 

  • Infinite loops – EG: Application A sends record 1 to Application B, Application B then sends record 1 back to Application A as it was an update, triggering Application A to send it again.
  • Data duplication

Embedded iPaaS platforms such as Cyclr have in-built ‘anti-loop’, ‘anti-crossfire’ functionality – but if you are building it yourself you will need to code this directly.

Custom Data

Custom fields are increasingly common in modern SaaS applications. If you’re building a custom SaaS integration for a customer you will need these fields to be defined before work can commence. It also means that if another customer asks for a near identical integration, but with their own custom fields, the integration will have to be re-written. 

This isn’t the case if you’re using an iPaaS solution. As well as simplifying the building process, you are able to make a reusable integration template. These templates will include the most important parts of the integration: 

a) the data flow 

b) standardisation of data structure 

c) trigger event/interval 

d) key data mapping across applications

The iPaaS solution should then be able to manage custom fields when your user comes to install it. At this point they can define custom values themselves, once their applications have been authenticated. This method allows you to build once and let your users deploy multiple times. 

Run Frequency

Not all users need integrations to be instant.

By gauging the volumes of data to be transferred, the importance of timeliness and the availability of actions within an application’s API you can look to suggest a suitable trigger period to match your users needs.

Found this content useful? Then why not share it!