Flow Versioning Guide
Over time, IPF flows may need to be updated due to new requirements, regulatory changes, or a deeper understanding of the domain. While this is straightforward during development, it becomes critical to manage such changes carefully once flows are live and actively processing payments.
Typically, key requirements from clients are:
-
The service must carry on processing payments with minimum/no disruption
-
There is no duplicate processing / double submission of payments
-
In-flight transactions must carry on processing with minimum/no disruption
This page summarises the main ways in which IPF flows may evolve over time and provides high-level guidelines for how to implement the described changes.
Types of Changes
Changes to flows can have different forms, depending on the change in business requirements.
Domain Event Changes
These are typically changes to the definition of domain events within an existing flow. As a result, you may have to write specific migration code that allows seamless transition to the new/updated definitions. Note that it all depends on the type of change and whether the change is breaking or not. Below are some examples of these changes:
-
Adding a data field to an event
-
Changing the fully-qualified class name (FQCN) of an event
-
Changing the name of a data element in an event
-
Changing the data type of an element in an event
-
Splitting an event into multiple, smaller events
-
Removing an event
In order to understand how to handle these changes, refer to IPF devdocs on schema evolution.
Breaking Flow Changes
These are typically the changes to an existing flow definition that changes the structure.
Some examples are :
-
Changing the sequence of steps and events in a flow definition
-
Adding a new step to an existing flow definition
-
Removing a step from an existing flow definition
-
Adding a new decision to an existing flow definition
-
Removing a decision from a flow definition
-
Adding/removing a subflow call in an existing flow definition
-
Applying the same changes above applied to a subflow
These type of changes can’t be handled by simply updating the flow. A new flow will have to be defined with a new versioning.
Depending on the requirements, older flow versions will need to remain available in the application for a period of time, specifically until all in-flight transactions using the older versions have completed. Meanwhile, new payment transactions can be routed to a new flow version. To support this concurrency, it’s essential to implement flow versioning from the outset. For a practical example and discussion of flow versioning, please see Flow Versioning.
Non-Breaking Flow Changes
These are minor changes to the flow definition that don’t change the overall structure of the flow.
An example of this is, changing the description of the flow elements (description of events, business data)
In this case, there will be no need to create a new version of the flow. Applying the changes in the existing flow definition would suffice.