A Basic Guide to Scoping an Integration

Updated on 18th August 2023 by Daniel Twigg

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

The lack of clarity in an integration request can stem from a number of factors. Therefore, we are aiming to unpack the language behind integration requests. This includes, what you should be asking to ensure your integration project has the best chance of ‘first-time delivery’ success.

Breaking Down Integration Requests

On a daily basis, SaaS companies regularly receive ‘Integration Request’ tickets in their helpdesk inbox. However, the ways in which they are conveyed can vary vastly.

For example, a common message may simply be:

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

Therefore it is an almost near-impossible brief because popular applications like Zendesk offer a vast array of services. As there is no indication of 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.

Now if they sent this example:

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’ll be able to unpack this to get the barebones view of what the integration would look like. However, there is still work to do because as a minimum there is a need to further define what data fields within the contacts are required. As these will be used to update data between the applications. 

Therefore the integration can be improved further, for instance:

This request builds upon the previous type of request received. It offers 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. 

Therefore, the more detail the better for scoping an integration.

Scoping an Integration: The language behind the request

One of the first stumbling blocks in scoping 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.

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

Term	Definition
Automation	The term often used to describe a background task to improve productivity, typically with an automated trigger and a defined action
Connection	Indicates that a data link between systems is required, with non-specific requirements
Sync / Integration	Two-way data integration, ensuring records in both SaaS applications match
Workflow	Indicates 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’, and ‘automation’ but means ‘workflow’.

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, but the main information you need when scoping an integration and then building it is around their real-life use case.

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 for scoping an integration?

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

• the application’s 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 in 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 any exceptions to the data movement?
• are there custom data fields that need to be accessed?

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

Extrapolating a User’s Use Case

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

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

The more you 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 upfront. 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

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

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

For example, you want 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:

Is it really that Simple? Sadly not always.

Not all CRMs directly provide the contact details of those attached to a deal. Therefore, you’ll need to amend this flow to something like this:

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:

Therefore, something that on the face of it looked relatively simple needed to be unpacked further based on the system you are working with. However, by familiarising yourself with how an application interacts with itself you will be able to formalise these integrations far more quickly. 

Lesser Thought of Integration Requirements

There are a few other things worth bearing in mind when spacing 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’, and ‘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 rewritten. 

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 user’s needs.

Other SaaS Resources