Documentation for a newer release is available. View Latest

Guía de user stories para proyectos de implementación IPF

El propósito de este artículo es ofrecer orientación sobre cómo escribir user stories al definir requisitos para una solución construida con IPF. Se asume que el lector ya tiene conocimiento de user stories en el contexto del desarrollo ágil de software.

Cuando se escribe una user story en el contexto de una solución construida con IPF, debe referirse explícitamente a componentes y conceptos de IPF. Lo más habitual es que esto implique la definición del flow en IPF Studio, pero también puede referirse a otros servicios core de IPF y business functions (Reachability Service, SEPA CT STEP2 scheme pack, etc.). Aunque las historias de IPF deben proporcionar tanto detalle como sea razonable, deben seguir los principios ágiles habituales INVEST:

  • Independent

  • Negotiable

  • Valuable

  • Estimable

  • Small

  • Testable

Proceso típico de escritura de user stories para IPF

1. Definir el alcance

El/los squad(s) ágiles acuerdan un alcance para una pieza de trabajo definida que creen alcanzable dentro de un par de sprints, normalmente dentro de un único épico. Este épico define el alcance y proporciona el contexto necesario; el contexto puede ir desde texto simple que describe necesidades de negocio, a diagramas o incluso a modelos de casos de uso según el nivel de complejidad y reutilización funcional.

Una implementación IPF consiste en servicios débilmente acoplados definidos por un cliente (a menudo conteniendo uno o más flows), así como algunos servicios predefinidos proporcionados por IPF.

Un posible servicio definido por el cliente con un flow es un 'Payment Execution Service': este podría recibir una solicitud de pago en formato Pain001 y luego gestionar la orquestación de la solicitud interactuando con funciones bancarias como contabilidad, FX, sanciones y fraude. Este tipo de servicio de orquestación tendría un conjunto amplio de flows para manejar devoluciones y otros edge cases.

Otro posible servicio definido por el cliente con un flow es un "Payment Recall Service": este podría manejar todo el procesamiento Camt056 y, si hay que enviar una devolución, iniciar un flow en el Payment Execution Service para enviar un Pacs004 al scheme.

Un ejemplo de servicio predefinido sin flow es el Notification Service: este envía informes de estado de pago (Pain002s) a canales para proporcionar el estado de una transacción en etapas definidas del procesamiento.

El diseño de la solución describe los límites de los servicios, cómo interactúan los servicios y qué ocurre dentro de esos servicios (por ejemplo, flows). Normalmente se crea junto con el alcance y se consulta al crear las user stories.

2. Escribir user stories

2.1 Crear un servicio nuevo

A medida que se construye la solución, se añadirán nuevos servicios. Es buena idea tener una user story de "puesta en marcha" cada vez que se vaya a crear un nuevo servicio. Esta user story técnica permite a los ingenieros crear el proyecto, configurar el repositorio, etc., y debe describir los límites e interfaces del servicio definidos en el diseño de la solución, incluyendo los criterios de entrada (p. ej., un tipo de mensaje específico requerido para el primer flow) y los criterios de salida (p. ej., una notificación) para el servicio. Las actualizaciones a un servicio merecen sus propias user stories.

Es probable que se use la configuración del servicio para almacenar parámetros utilizados durante el procesamiento. Documenta y mantiene toda la información sobre los ajustes de configuración (config de negocio y técnica) en un espacio que se use para compartir información entre equipos, como Confluence o SharePoint.

2.2 Crear un flow inicial

Si se está creando un flow por primera vez, es sensato tener una historia dedicada para crear una versión esqueleto del flow. El esqueleto debe:

  • Definir todos los DSL states conocidos por los que puede pasar una transacción en su happy path

  • Tener al menos un estado DSL terminal para el happy path

  • Tener un estado DSL terminal genérico de fallo o rechazo; esto puede reemplazarse más tarde por varios estados específicos de fallo si es necesario

  • Definir los domain events que impulsarán las transiciones de estados DSL

  • Definir las respuestas que generarán los domain events

  • Definir los resultados de todas las decisiones (si las hay) usadas en el happy path

  • No tener errores en IPF Studio; es decir, que initiation behaviour, input behaviour y event behaviour estén definidos hasta un punto que haga que el flow sea válido y que una transacción pueda procesarse a través del flow hasta un estado DSL terminal. En esta etapa no necesitas crear subflows, aunque puede que quieras crear un estado DSL temporal para representar un subflow que se definirá en una etapa posterior.

Debes asegurarte de que:

  • Los DSL States se nombren en presente y representen una acción que la solución construida con IPF está realizando; generalmente tendrán una palabra con ‘ing’ (p. ej., Validating Payment, Awaiting scheme response)

  • Los domain events se nombren en pasado y representen un hecho sobre algo que ha ocurrido en el flow de pago; generalmente tendrán una palabra con ‘ed’ (p. ej., Payment Validated, Payment Accepted by CSM)

  • Se añadan referencias a campos donde sea posible para que los ingenieros sepan claramente a qué se hace referencia (p. ej., para definir una validación usando participant limits: Payment amount (PmtInf.CdtTrfTxInf.Amt.InstdAmt.value) is less than creditor agent participant limit (Reachability.CSMParticipant.Limit.Amount)

2.3 Actualizar un flow/Añadir historias de subflow

La mayoría de las user stories construirán sobre flows existentes: ya sea un flow inicial (ver arriba) o iteraciones posteriores. Es útil dibujar el flow actualizado en una aplicación de diagramas, marcando el cambio (por ejemplo, un nuevo estado DSL, cambio del nombre de un domain event, etc.) en un color diferente y adjuntarlo a la historia. Esto es más simple que crear una rama en IPF Studio para un usuario de negocio y permite una planificación más independiente, ya que el cambio se resalta claramente y no requiere combinar flows.

Usa los criterios de aceptación en la historia para definir los cambios al flow con más detalle usando la sintaxis gherkin (scenario, given, when, then), haciendo referencia a DSL states y domain events para dejar claro dónde en el flow se ubica el requisito.

2.3.1 Mapping

Al enviar y recibir información con otros sistemas (External Domains en términos de DSL), se requiere mapping desde/hacia el modelo de datos del flow y el sistema externo.

  • Necesitarás referirte a una especificación técnica para requests y responses: esta debe enlazarse desde la historia en lugar de definirse dentro de la historia

  • Necesitarás definir el data mapping para una request (y a veces también para una response)

  • Las especificaciones de mapping deben enlazarse desde la historia, en lugar de definirse dentro de la historia, a menos que sea un mapping muy, muy simple

  • Aunque la hoja de mapping cubrirá todos los datos requeridos en la request, vale la pena incluir los datos más importantes en los criterios de aceptación para ayudar a la legibilidad y proporcionar contexto

2.3.2 Gherkin Scenario

Proporciona una visión general de lo que la historia intenta lograr en una frase breve y el camino que la transacción ha seguido hasta el punto en el que se realiza el cambio.

Ejemplo: Se hace una request desde el Payment Execution flow al CSM service y se maneja la response: la transacción será rechazada o continuará el procesamiento.

2.3.3 GIVEN

Proporciona las precondiciones.

  • Lista el/los flow(s) por los que ha pasado la transacción hasta este punto

  • Especifica los domain events clave en el/los flow(s) que deben haber ocurrido antes de que la historia tenga efecto

  • Lista el/los servicio(s) que son cambiados por la historia

Ejemplo:

GIVEN

a payment has been submitted to the payment execution flow
AND

the last event is transactionValidated
2.3.4 WHEN

Proporciona el disparador del comportamiento requerido (podría ser un domain event, el resultado de una decision, aggregate function o flow / subflow, un tipo específico de response de un sistema bancario, etc.).

Ejemplo:

WHEN

a request is sent to the Reachability service
AND

the request is structured according to the specification (add link to mapping page and specification)
AND

the request contains the Creditor Agent BIC
AND

a response has been received (add link to specification)
2.3.5 THEN

Se utiliza para describir el comportamiento requerido:

  • El nombre del event generado por la response/output debe definirse. Esto corresponderá al event definido en Payments DSL y usado en el Input Behaviour.

  • Si se requiere un response code diferente al output de un external domain (p. ej., el external domain devuelve BANK4532, pero quieres que el flow lo maneje como IPF031), entonces esto debe especificarse en la historia. El response code definido por el usuario será de un conjunto predefinido importado en el Payments DSL (p. ej., ISO) o de un conjunto personalizado de códigos definidos en el Payments DSL.

  • Si la response es un fallo, entonces debe definirse un reason code junto con una reason code description.

  • Si se utiliza el IPF Operational Dashboard, puede ser valioso describir lo que se esperaría ver en la GUI como parte de los criterios de aceptación.

  • Debe proporcionarse el global state que corresponde a la transición de estado, si necesita cambiar (en el ejemplo siguiente el global state permanecerá en estado pendiente si el creditor reachability check pasa).

Ejemplo:

THEN

an event is generated with a corresponding response and reason code and the following state transitions occur

Response

Event

Response code

Reason code

Reason code description

Transition to DSL state

Global state

pass

reachabilityCheckPassed

ACPT

GY.001.002

Creditor Agent Reachable

Transaction Completed

fail01

reachabilityCheckFailed

RJCT

GY.200.001

Creditor Agent Invalid

Transaction Rejected

Rejected

fail02

reachabilityCheckFailed

RJCT

GY.200.002

Creditor Agent Not Reachable

Transaction Rejected

Rejected
AND

the following is observable on the IPF Operational Dashboard:
+

the reachabilityCheckPassed event with Response Code
+

the reachabilityCheckFailed event with Response Code, Reason Code and Reason Description
+

the graphical representation of the flow showing the state transition to Transaction Rejected or Transaction Completed
+

the state transition of the global state from Pending to Rejected upon the reachability check failing
+

the global state remaining as Pending upon the reachability check passing

2.4 Historias para añadir una domain function

Las domain functions son desarrolladas por clientes de IPF y se llaman desde el flow mediante una request. La domain function proporcionará una response al flow.

Si la función es simple, la lógica de la función puede describirse en la user story; de lo contrario, es aconsejable describir la función donde mantienes la documentación del proyecto y referirte a ella desde la user story.

Usa el nombre de la función definido en la librería de funciones del Payments DSL al referirte a ella en la user story.

2.5 Historias de configuración y puesta a punto

Algunas historias estarán relacionadas con la preparación de datos, cambios de configuración, usabilidad de la GUI, etc., y no se prestarán de forma natural al uso de la sintaxis gherkin. En estos casos, describe el requisito de la manera más clara posible e ignora el formato Given, When, Then.

Asegúrate de usar siempre Given, When, Then al describir requisitos de flows

Algunos ejemplos:

  • Creación o modificación de estructuras de datos de Processing Entity

  • Creación o modificación de estructuras de datos de CSM Agent y CSM Agent Settings

  • Creación o modificación de configuración técnica o de negocio para un Service

2.6 Historias de simulador

Si se construyen simuladores para representar external domains en el Payments DSL (por ejemplo, una plataforma de contabilidad o un sistema de FX), entonces se necesitará una user story para crear el simulador.

Las historias de simulador deben:

  • Dar un contexto general y referenciar cualquier diagrama de arquitectura para dejar claro qué se está simulando (por ejemplo, un sistema de FX o un sistema de contabilidad)

  • Proporcionar enlaces a las especificaciones técnicas para el external domain que se está simulando

  • Dejar claro cuál es el mínimo de datos que necesita el simulador; en general, la request debe proporcionar los datos necesarios para ser válida y para pruebas significativas.

  • Especificar los magic values requeridos. Los magic values son valores (por ejemplo, un nombre o importe específico) que provocarán una response concreta.

Ejemplo:

Se requiere un simulador para representar un sistema que verifica que una cuenta puede ser debitada y devuelve una response de validación que, si es exitosa, incluye una dirección.

La user story tendría que definir los magic values necesarios para varios posibles resultados, y los datos en la request al simulador tendrían que contener esos magic values.

En este ejemplo se usa un importe específico para provocar las responses del simulador:

Scenario

Request Data

Expected Response

Transaction passes validation, no enrichment

Amount = 1.01

Pass

Address Line 1 is populated

Transaction passes validation, enriched data in response

Amount = 1.02

Pass

Address Line 1 is populated

Town is populated

Transaction fails validation

Amount = 1.03

Fail
No es necesario cubrir todos los escenarios de fallo, ya que pueden contarse por cientos. Solo necesitas cubrir cada escenario de fallo que impulse un comportamiento diferente en el flow. Si un grupo de fallos resulta en el mismo comportamiento, entonces necesitarás uno de ellos modelado en el simulador.

Consejos y trucos

  • Nunca uses las palabras "event" o "state" sin dejar claro cuál es el tipo; o bien es un domain event o un system event. Del mismo modo, o bien es un DSL state o un global state.

  • Una vez que hayas creado un simulador con una historia de simulador, añadir nuevos escenarios al simulador puede ser mejor manejarlo como parte de la user story del flow relevante, dependiendo del nivel de complejidad.

  • Usar un modelo de proceso de negocio, como BPMN, junto con un diagrama de secuencia UML ayuda a aclarar el alcance del épico, especialmente cuando se trata de parte de un proceso E2E complejo que se ha dividido en múltiples flows y servicios IPF.

  • Si usas Jira o una herramienta similar, el campo 'components' puede usarse para listar los servicios relevantes en lugar de los criterios de éxito.

  • Debido a que el message logging en IPF es flexible, no hay logging por defecto; por lo tanto, es buena idea indicar explícitamente que cualquier new external messages que una historia esté introduciendo en un flow necesita loguearse o puede pasarse por alto fácilmente.

  • Especifica siempre cómo quieres que se llamen los mensajes externos en la GUI.

  • Piensa si quieres ver en la GUI los mensajes que fallan una comprobación de esquema (p. ej., XSD) o no. Si esta validación se implementa en un connector antes de que comience un flow, no habrá unit of work para el mensaje y, por tanto, nada en ODS. Si quieres ver que se recibió un mensaje basura y se rechazó en la GUI, tendrás que hacer esta validación en el flow.

  • Como BA no tienes que decidir por adelantado si un requisito se implementará como una domain function o un servicio nuevo, etc. Necesitas entender las implicaciones de las distintas opciones, pero deja la decisión al proceso de refinamiento. La única excepción a esto es identificar subflows.