Product managers are responsible for determining the services and applications that are used by their customers and figuring out how to get their application integrated with them.
To guide the development of these integrations, the place to start is by writing out user stories that provide a clear picture of the experience you envision for your end-customers. With integration, you can create a connected, cooperative experience where data flows seamlessly between your app and the other apps your customers are using.
This post is a follow-on to our updated Definitive Guide to API Integration. Download the full guide for more in-depth content on integration best practices, from pre-build to post-build, or check out the blog series.
API User Stories: User Personas vs. System Personas
There are two common approaches for writing API integration user stories: user personas and system personas. System personas are a common, but limited approach. For example, an API integration user story in the system persona to connect a webinar management application to a marketing automation system may look like this:
As a Webinar Management Application, I want to automatically create leads and associate them with accounts in the selected Marketing Automation System, so that …
By developing user stories in the system persona, we can become too focused on the technical aspects of integration instead of the collaborative user experience we're trying to establish. System-based integration stories don’t enable product managers to fully visualize the workflow that the user will experience — they guide the integration as a technical solution, but not as effectively as a business solution.
A different way to write a user story is through a user persona. A great user persona is written from the point-of-view of an end-user. This is contrary to a system persona, which is designed to specify technical interactions between systems. It’s important to get as much use out of these personas as possible to ensure that your stories relate back to an experience model from the viewpoint of your end-users.
Here are three practices our product owners follow when developing integration user stories:
- Start by developing stories as a user persona whenever possible to provide the clearest perspective on how and why your users will benefit from the integration.
- Next, using the target and source systems you’re integrating, clarify how the data is moving between your application and the service(s) you’re integrating.
- If an integration task doesn't involve users, write API user stories with a system persona so you can elaborate on the behind-the-scenes integration tasks that aren’t user-centric.
Write User Stories Based on User Personas
In this example, we’ll write a user story based on a user persona for our application, who we’ll call Mary Marketing. The majority of your user stories will be written from the user and/or administrator personas. When writing your user story, you’ll also need to include a reference to the service your application is cooperating with (e.g. a Marketing Automation Service, in this case).
At Cloud Elements, we’ve had the best results when adopting the industry best practice format for persona-based stories, which is formatted: As a (Persona), I want (Need), So That (Goal). Here are some stories we created for the Mary Marketing persona.
As Mary Marketing, I want to select the Marketing Automation Service that I would like to connect to my Webinar Application, so that I can create leads from webinar attendees.
As Mary Marketing, I want to automatically create leads from webinar attendees and associate them with existing accounts in my selected Marketing Automation Service, so that the appropriate salesperson(s) can follow up on the leads in a timely manner.
As Mary Marketing, I want to ensure that I don’t create duplicate Accounts and Contacts in my Marketing Automation Service, so that my sales reps are provided with accurate information.
To further clarify the integration use case above, we also created an application-to-application persona (or system persona) to represent background system functions that do not require interaction from the end-user. The purpose of this system persona is to provide an additional level of detail and acceptance criteria beyond the user interaction scenario.
As a Webinar Application, I want to match leads to the selected Marketing Automation Service in an intelligent manner, so that we don’t create duplicate data and confuse the sales team with redundant Account and Contact information.
System-to-system user stories should be limited to providing a more detailed understanding of the behind-the-scenes interactions required between systems, but should not replace the user persona-driven stories.
To Sum It Up
As a product manager, your goal is to provide a seamless experience that meets the expectations of your users. Your starting point is to write stories from your typical user personas and then elaborate with system personas to better visualize the end-to-end user experience. Breaking down your customers into different personas and developing user stories for them using “As a… I want… so that…” statements is an effective way to start creating an integration strategy.
Need help creating a killer, integrated app? Learn how in our comprehensive resource, The Definitive Guide to API Integration.
Even more? Check out the next post in the series on API authentication methods.