The Community Blog for Business Analysts

System Analysts who work with integration processes should formulate user stories in a way that diverges from the traditional structure. This is primarily due to the need for a more technical and structured description, which allows for the inclusion of integration-specific details.

The user story might need to specify exactly what kind of data should be retrieved via an API, from which system, using what HTTP method, and so on.
Additionally, such user stories can incorporate validation requirements.
For instance, before sending the data to an external system through an API, certain transformations or formatting might be required.

As a result, the structure of a user story in this context tends to differ significantly.

Here’s an example of how a story might look:

story_map:
epic: "Invoice Integration"

user_stories:

• id: US001
  title: "Obtain AR invoice"
  as_a: "Application X"
  i_want: "obtain AR invoices from ERP {{X}} via API"
  so_that: "I can handle this invoice and send to the client"
  source_system: "ERP {{X}}"
  target_system: "Application X"
  direction: "pull"
  api_call:
  method: "GET"
  endpoint: "/api/invoices"
  auth_required: true

• id: US002
  title: "Validate data"
  as_a: "Application X"
  i_want: "validate the fields of the received invoice"
  so_that: "I don't sync the invoice with errors"
  validation:
  invoice_number: "required"
  invoice_id: "required"
  invoice_total_amount: "should be > 0"
  invoice_status: "should be 'posted'"

• id: US003
  title: "Push invoice payment"
  as_a: "Application X"
  i_want: "push the invoice payment created in Application X to the ERP"
  so_that: "the payment is approved in the ERP and synchronized back"
  source_system: "Application X"
  target_system: "ERP {{X}}"
  direction: "push"
  api_call:
  method: "POST"
  endpoint: "/api/payments"
  auth_required: true