Best Practices for Defining API Integration User Stories

By Hannah Shain in How-To, Cooperative Apps Posted Aug 5, 2014

Product managers are responsible for deciding on which integrations to build into their application to create a “cooperative” experience with the services and applications used by their customers. To guide the development of these integrations you’ll need to write integration user stories that provide a clear picture of the cooperative experience you envision for your end-customers. Integration is a means to an end; a connected, cooperative experience where data flows seamlessly between your app and the other apps you customers are using is the end result that you are seeking through integration.

cooperative-app-series-banner

USER PERSONAS VS. SYSTEM PERSONAS

There are two common approaches for writing integration user stories. A common, but limited approach, is to write the user stories in terms of system personas. For example, an integration user story to connect a webinar management application to a marketing automation system may look like this:

The Webinar Management Application will automatically create leads and associate them with accounts in the selectedMarketing Automation System so that …

 By developing user stories in the system persona, we as Product Managers can become too focused on the technical aspects of the integration instead of the collaborative user experience that we’re trying to establish.  System based integration stories don’t enable the Product Manager 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 great user persona is written from the point-of-view of an end user. That is contrary to a system persona, 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 3 practices our product owners follow when developing integration user stories:

  1. 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. Capture the cooperative user experience through these stories.
  2. Refer to the target and source systems that you’re integrating to clarify how the data is moving between your application and the service(s) you’re integrating and cooperating with.
  3. Only write user stories with a system persona when you need to elaborate on the behind the scenes integration tasks that don’t involve users.
Mary Marketing

In our webinar model (mentioned in 5 Steps to Cooperative Apps Guide)  we first write user stories based on an the actual user persona, Mary Marketing, for our application. The majority of your cooperative app user stories will be written from the user and/or administrator personas. In addition, you will include a reference to the service your application is cooperating with (e.g. the Marketing Automation Service in this case). 

As Mary Marketing, I can 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 can automatically create leads from webinar attendees and associate them with existing accounts in my selected Marketing Automation Service so that the appropriate sales person(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.

Webinar AppTo further clarify the use case above, we create 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 match leads to the selected Marketing Automation Service in an intelligent manner so as not to 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.

In summary, your goal is not integration, it’s cooperation. Provide an application that works seamlessly with the other cloud services used by your clients. And start by writing stories from your typical user personas and then elaborate with system personas to better visualize a cooperative user experience.

Need help creating a killer cooperative app? Download our free eBook, 'The Definitive Guide to API Integrations'.

the-definitive-guide-to-API-Integrations-eBook

Learn more from this Cooperative Apps blog series: