How to Flawlessly Ship Integrations with Third Parties

As a product manager, one way to increase functionality in your product development process (and also attract new users) is to integrate your product with another product. For example, Google Calendar has an integration with Zoom, where you can instantly set up a Zoom video meeting through Google Calendar.

Google Calendar benefits from the Zoom integration because it easily enables its users to set up video calls within a seamless workflow. Zoom benefits from the Google Calendar integration because its users can spin up video meetings much more quickly.

Integrations are beneficial to both products. Both products gain new capabilities and new users by integrating with one another. In other words, integrations bring the best of both products to end users, and provide them with new superpowers that they didn’t have before.

As another example, Nifty and Zoom have an integration with one another as well. Nifty, a project management and remote collaboration software benefits from this because its users can easily leverage video conferencing even without a Zoom account, which means that its users can be even more effective in collaborating with one another.

And, Zoom benefits because it can serve Nifty’s users from a coordination and project management perspective. On top of that, Zoom can also upsell Nifty users on its Pro plan for persistent video recordings.

While integrations are incredibly powerful for unlocking new functionality within your products, they require you to work with others outside of your company. That coordination challenge can be an incredibly difficult task to overcome. No matter what, you have to work with a third party to ship an integration, and working with third parties can be challenging.

For example, let’s say that you’re a product manager for Salesforce. You might work with one of the three kinds of integrations below.

• Customers: for example, a Salesforce integration with its customer Rolls-Royce to enable community management
• Third-party developers: for example, enabling the developer Bluewolf to build on top of Salesforce for Bluewolf’s customers
• Third-party product partners: for example, a Salesforce integration with Slack to enable posting Salesforce updates in Slack

I’ve had the opportunity to work through dozens of integrations initiatives, for all three of the integration types above. While each one requires a different skill set and a different approach, they all share the same basic concepts.

I’d love to share some best practices on ensuring that you and your integration partners successfully ship your integration on time with as little heartburn as possible, regardless of what kind of integration it is.

Below, I’ll talk through: how to craft a compelling integrations charter, how to kick off the project together, how to plan for the integration, and how to execute as a team.

Before I discuss each one in detail — you might be surprised to see that all of the items I mentioned are based on soft skills. You might ask, “Aren’t integrations mostly technical? Shouldn’t I be more worried about the technical challenges?”

In my experiences, I’ve found that the hardest technical challenges come from a lack of coordination and alignment. You cannot address coordination and alignment through technical skills; you can only address those through soft skills.

If you want to be a rockstar integrator as a product manager, you’ll need to focus on the soft skills, because integrations rely on deep partnership with your implementation partner. So let’s get started!

Crafting the Charter

The single biggest factor for integrations success is an aligned charter. And, the single biggest factor for integrations failure is a misaligned charter.

Before you even begin working on the project timeline, first begin with the objectives of the integration. What is the intended user-facing objective?

I’ve seen too many integrations fail because one (or both) parties didn’t clearly understand the purpose of the integration from the user’s perspective.

If the end user doesn’t get any benefit from the integration, then there’s no point building the integration. It doesn’t matter if you believe that you’ll gain market share or you’ll gain more revenue. If the user has nothing to gain from it, then you’re wasting everyone’s time.

After all, the basic premise of product management is that you must first create value for the user before you can capture value for your business.

What new superpowers will you unlock by integrating these two products together? If there’s nothing new, then don’t do it.

For example, Google Docs has a huge user base, and Apple iMessages has a huge user base. Imagine if the two of them wanted to build an integration where iMessages automatically compile into a Google Doc.

That’s not valuable to the end user. The end user has no need for such a capability. So, while both Google and Apple are huge companies, this particular integration makes no sense because it unlocks no value.

So, now let’s say that you and your partner have identified what benefit the end user is going to get. It’s time to talk incentives: are both of you correctly incentivized to ship this integration?

Another point of failure I regularly see is that one party stands to gain disproportionate value from the integration, and the other party doesn’t gain much at all.

Then, the party that won’t gain much will keep deprioritizing the initiative, leading to failure.

What’s the value proposition for your company to take on this integration? And what value proposition is your partner getting for this integration?

It has to make sense for both of you, or else you won’t jointly prioritize the work and ensure that the integration happens.

One way to help level the playing field is to set up a revenue-sharing clause in the partnership contract. That way, the party who “wins” the most will share some of those winnings with the other party, so that both sides are ready to act as a single team.

Kick Off

Okay, so you’re both going to create massive value for the end user, and you’ll both stand to gain from completing the integration. Now, it’s time to get down to the actual mechanisms of the integration work!

Set up a kickoff meeting between you and your partner, and include engineering leaders from both sides. You want as much information to flow between all parties as possible.

Make sure you answer these key questions in the kickoff:

• What is the value of this integration to the end user?
• What is the value of this integration to both companies?
• Which system is in charge of what functionality?
• Which team is responsible for what work?
• Who gets to make which kinds of decisions?
• What timeline are we working with?
• What’s the process for escalating, if either party is not meeting expectations?

The more alignment you can get upfront, the easier the work is going to be later. Trust me, I’ve been burned by these questions repeatedly, and having an upfront kick off means fewer confrontations, less friction, and faster delivery.

Be explicit with these decisions, record them somewhere, and distribute your records immediately after the kickoff.

Upfront Planning

Great, so now you have a compelling integration charter in place, and you know who’s responsible for what.

Is it time to roll up our sleeves and dive in yet? No, not yet. We need to plan ahead.

With integrations, I’ve found that the devil really is in the details. A minor missed detail upfront can literally cost months of development effort to fix.

Here’s a real life example: I was building an integration alongside one of my customers, so that I could integrate my product into their internal systems.

For more than two months, we had issues where neither of us could successfully call each other’s APIs, and we were both mystified. No matter how many emails we sent back and forth, we couldn’t get to an answer. We were both sure that our respective APIs were being called with the right set of parameters and with the right logic.

That is… until one particularly astute engineer noticed that our product had case-sensitive parameters, whereas our customer’s system was case-insensitive.

In other words, something like “userName” had to be spelled exactly that way for our system to work, whereas our customer might try to call our functions with “UserName” or “username” and those calls would fail.

It took so long for us to find the problem, and all of that could have been avoided if we had spent time planning upfront and digging into the details!

So please, spend disproportionate time upfront on the technical details. Even if you’re not a technical product manager yourself, lean on your engineering team to surface as many assumptions and questions as possible.

Here’s what I’ve found to be useful.

First, have your team draw out the proposed architecture diagram and the sequence of network calls (which module is talking to which module, and when?).

Then, walk through it with your integration partner.

You’ll frequently find that some modules need to be combined together, and others need to be separated out. Or, you’ll find that some of the calls are sequenced in the wrong way. It’s so crucial to ensure that you’ve got the right foundation in place!

Note that I’ve made the assumption that both teams have already agreed to the scope and the user stories that they’ll jointly be tackling, as part of the charter.

If you haven’t done that yet, then do that first. After all, your architecture must be based on the scope (and the shape) of the functionality that you’re providing to your joint end users.

Once you know which system is talking to which system, then it’s time to get into the weeds.

You don’t want to write a single line of code until you’ve gotten all of these questions answered:

• For each call, what does the request schema look like? What does the response schema look like?
• What are the parameters, and which ones are optional vs. required? What is the data type of each parameter (e.g. array, object, string, int)? Are there enumerations or is it free text? Is it valid for multiples of the same parameter to be sent or received?
• What is the naming convention for functions and data elements? Which systems are case-sensitive? Will you be using camel case or sentence case?
• What does the data structure look like within the databases on either side?
• Are the calls synchronous or asynchronous? What is the retry behavior, if any? What is the logging behavior, if any?
• Which environments will each party be using? Does everyone have all of the credentials they need to talk to each environment?
• Who’s in charge of error monitoring and logging?
• Who’s in charge of production support once the integration goes live?

The general principle: during the planning phase, get into the details and document your decisions for posterity.

That way, if your integration succeeds (and hopefully it will!), you and your partner can build even more integrations together, and your past work will already be cleanly documented for both of you to work off of.

Team Execution

You’ve fleshed out every detail. Now it’s time to ship as a single unified team.

I’ve found that when my integration partner and I treat one another as true teammates, that’s when we ship the highest-quality code at the fastest velocity.

I’ve also found that if my team doesn’t trust my partner’s team, then the entire initiative will quickly fall apart. While it’s important that we hold one another accountable, we also have to trust that each team will get their work done to the best of their ability.

While many product managers are great at leading their own teams, they may struggle to work with external teams. The good thing is that with a bit of mindset tweaking, it’s entirely possible to become effective at leading external teams too.

First, you and your integration partner must commit to tracking your progress together. Give one another full transparency and visibility into your backlogs, velocities, sprint plans, and resource allocations.

By doing so, it’s much easier for you to plan around one another’s constraints. Be proactive and share when you’ll get blocked, and proactively discuss how you can help unblock another other.

One of the most helpful actions either side can take is to provide mock responses for one another. A mock response is simply a “fake” set of data that one party provides to the other, so that the other party can implement without needing to wait for the actual API to be built.

For example, say that I’m on the hook to build a data verification function, and my implementation partner is going to send me a bunch of data to verify. But, let’s say that I haven’t built my verification function yet.

That’s okay. I can let them know that I’ll prepare a set of mock responses, based on a predetermined set of requests that they send me. For example, if they send me Data Set XYZ, I’ll always respond back with a successful response. And, if they send me Data Set ABC, then I’ll send them back a response letting them know that the data cannot be verified.

While I haven’t written my function yet, they can now move forward without needing to rely on me. They can figure out how to continue to building the happy path (where the response is successful) as well as how to deal with graceful degradation (where the response is a failure). They are no longer blocked by my team’s implementation of the actual full-blown functionality.

Of course, a mock response eventually needs to be replaced with the real function, but that’s a cheap and fast way to keep one another moving quickly.

And, while we’re on the topic of execution, remember that you still have to test. Allocate sufficient time in your project plan to jointly run through QA, including performance tests, unit tests, integrations tests, and user acceptance testing.

The second point to keep in mind is that you’re growing and leading both of your teams together. You’re not just executing and tracking velocity; you’re looking to strengthen one another.

So, commit to performing the full set of sprint rituals together too. Groom your sprints together, prioritize your sprints together, kick off your sprints together, have daily standups together, test your tickets together, and hold retrospectives together.

The more you both commit to acting as a single team, the more your teammates will actually act as a single team. That means fewer silos, more trust, more alignment, higher velocity, and better quality.

That leads me to my third point. You’re not just responsible for the operational mechanisms of both teams. You’re also responsible for the joint culture that you’re building together, and that means taking care of real human beings.

Celebrate together! When your joint teams reach particular project milestones, go out for a meal or send a small gift to everyone on both teams.

Remember that integrations can sometimes feel like a slog. I’ve had integration initiatives run for more than 10 months, and that’s a long time to be working with an external party on a day-to-day basis.

That’s why it’s so crucial to keep everyone’s spirits high, and to ensure that you’re all working together as a real team.

At the end of your integrations journey, you will not only have an amazing integrated product, but also have made lifelong friends across companies. Savor the struggle, because that’s what will enable you to genuinely bond with one another.

Final Thoughts

Integrations are so powerful because they enable you to specialize and focus on your product’s core capabilities, while relying on others to further extend your product functionality and your audience.

But, they’re also really hard to turn into reality. Integrations require intense levels of coordination and trust, and you need to be well-organized to actually bring your integration to life.

By ensuring that you have a clear game plan for driving clarity, alignment, and coordination, you’ll dramatically increase the chances for success for both you and your integration partner.

And, by fully leveraging your soft skills, you can make even the toughest, most nuanced technical integrations much easier to bring to life!

—

Clement Kao is a Co-Founder at Product Manager HQ, a community dedicated to providing career advice for aspiring product managers and experienced product managers. He’s written 60+ best practice articles and has been a featured speaker and writer for more than 30 different organizations.