ISO 20022 Migration - Enhanced Data (Structured Postal Address)

Reference Documents

The reference document table contains links to information relevant to the RFC, a link to the referenced document is also required. Here is an example:

Reference	Document Location
ISO Migration PRD	ISO Migration PRD
Technical Analysis	Technical Analysis

Problem Description

One of the primary objectives of this RFC is to collect feedback on the potential impact originating from the proposed modifications in the Core Address table, given their extensive scope.

By November 2025 SWIFT will be moving all their reporting and payment messages from MT to MX (ISO 20022) format. Taking advantage of SWIFT’s migration, local market infrastructures around the world such as CHAPS & FPS (UK), CHATS (HK), Target2 (EU), EBA-STEP2/Sepa Credit Transfer, etc. are adapting to the same format. It is estimated that by 2025, 80% of all transactions will be using the same format.

Ebury will need to address the storage and processing of those new data and structures in our systems and use them for our processes. They are currently considered optional, however, they will be progressively mandated in the near future. Ebury will be receiving enhanced Data from November 2023 as per the PMG recommendations & EPC rulebook.

Migrating to ISO 20022 format for our outbound payments will have a great impact on different areas that require integration. Areas such as beneficiaries and payments via channels such as API, EBO, Mobile App, EBICS, etc.

The ISO Enhanced Data initiative presents proposals for alterations across a broad range of sectors, as highlighted in the preceding picture. To simplify the complexity inherent in such widespread changes, we will approach it across five stages, each centered on structuring a particular sector. This RFC focuses on phase I of the Enhanced Data initiative, thus it is related to the Structure Postal Address fields only. Discussions about other phases will be undertaken within individual documents and agendas.

Background

A common table in BOS shared between different entities (clients, beneficiaries, bank accounts, etc.) holds address information. The table is named ‘core_address’ and it contains the following fields:

Field	Type
id	integer
address_line_1	character varying(1000) NULL
address_line_2	character varying(1000) NULL
postal code	character varying(40) NULL
city	character varying(500) NULL
state_province	character varying(400) NULL
country_id	character varying(3) NULL

The following illustration depicts the various tables present in the BOS database with a direct reference to the Address table. Please note that modifications made to the Address table could potentially impact the functionalities connected with these corresponding entities.

Despite many entities relating to the ‘Address’ class, the suggested alterations are expected to alter the behavior of certain functionalities associated particularly with the 'Client' and 'Beneficiary' models.

When a payment is created, the clients’ and beneficiaries’ addresses are retrieved from this table. The following sequences illustrate how they are retrieved in code.

• CurrencyAccount -> Entity(Client) -> Address

• BeneficiaryPayment -> BankAccount -> Entity(Beneficiary) -> Address

An important point about the source of truth of these addresses is that clients' information is retrieved from Salesforce through a synchronization routine, so clients have their addresses created or updated in BOS in sync with the information registered in Salesforce. With that, we can understand that the client's address information for making payments is retrieved from the BOS database, but the source of truth for this entity is Salesforce.

Regarding beneficiaries, they are created directly in BOS via its API. Thus, the channels or internal services can create these entities along with their address consuming these endpoints and the data is directly stored in BOS DB, which makes BOS the source of truth for these entities.

Solution

Core Address

Since all the addresses are stored in the ‘core_address’ table, new nullable fields could be created in this table, as well as constraints to assure that, when one of the new fields is filled, all the other required ones are filled too.

To preserve backward compatibility, it will also be important to fill the new structured postal address field and the legacy ones as well, so client services can consume it both ways. With this strategy, we can avoid impact on the current functionalities and have the flexibility to adapt services to read the enhanced data gradually.

These are the new fields that we should add in the ‘core_address’ table:

ISO20022 tag	Element Description	Ebury Name	Type
\	Street Name	Street Name	character varying(70) NULL
\	Building Number	Building no°	character varying(16) NULL
\	Floor	Floor	character varying(70) NULL
\	Room	Apartment/Office	character varying(70) NULL

All the required fields for Postal addresses can be seen in the PRD document, but the other ones are already present in the current ‘core_address’ table implementation.

After a BOS endpoint is updated or created to match the new fields, it will be possible to make the required changes on the affected channels, such as EBO, API, MOBILE APP, or EBICS.

Clients

For client-related changes, it will be necessary to update existing endpoints that consume or return address information, so that they adapt to the new fields added to core_address.

The client address updates take place in the synchronization process between BOS and SalesForce. To secure this process and prevent undesired incidents, it is necessary to first adapt BOS sync script to be able to process both the old address structure and the enhanced one, only then the changes on Salesforce can be enabled.

Beneficiaries

Similar to clients, it will be necessary to update existing beneficiary endpoints that consume or return address information, so that they adapt to the new fields added in core_address.

Consumers

Services from other domains and channels, such as FXSuite, ACBalancer, Beneficiaries Query Service (BQS) and Payments, consume this information via API calls or Kafka events.

The Kafka events are generated with a CDC connector to the BOS database. After the database changes, the new fields information should be automatically included in the core_address table events, so services will be able to consume it right away.

Regarding the API, adding the new fields to the table and migrating the changes will also enable the work on the BOS endpoints that are related to these address updates. The idea is to define the best approach for each endpoint, which could be to update the existing endpoint, add the new address fields as optional, or create a new endpoint that will replace the existing one in the future if impacts can’t be avoided.

Channels

After the clients' and beneficiaries' updates are done, it will be necessary to update each channel that consumes their content from the BOS API and domain events. It is not in the scope of the RFC to list all dependencies, but backward compatibility will be one of the requirements.

• Ebury Online

  EBO has many functionalities that require direct consumption of beneficiaries and clients endpoints in BOS and BQS, such as beneficiary creation. - API WebApp

  API WebApp directly consumes beneficiaries and clients endpoints in BOS, such as requesting a list of clients.

• Mobile App

  Mobile app consumes BOS through the API WebApp endpoints, requesting a list of beneficiaries, for example.

Data Migration Strategy

The data migration strategy for populating newly added fields for already existing clients and beneficiaries is yet to be determined by the product team, and it is not in the scope of this RFC.

Service Ownership

This solution will affect many existing services that consume BOS API in operations related to beneficiaries and clients:

New Service	Service Name	Service Owner
No	BOS	TEG Team
No	EBO	ONL Team
No	API WebApp	API Team
No	MOBILE	Mobile Team
No	Bosporus	JAM Team
No	Outgoing Payment Service	PAY Team
No	Beneficiary Services	PAY Team

Alternatives

In a similar way for the database updates where the aim is to create all fields as optional so the new requirements can be added without breaking the existing services, for the endpoint updates, backward compatibility should also be assured.

Two alternatives are to be considered:

1. Proceed with the changes on the existing endpoints, making sure the contracts are properly updated with the Channels upon changes.
2. Create a new version of the endpoints that will only have affect when the other Channels start to consume it.

Caveats

• ‘core_address’ table new fields must be done before BOS API updates, which must be done before related channel updates.

• All updates must be backward compatible, to ensure that the unstructured postal address keeps working.

Operation

The updates required in this RFC will be run in many different services, such as BOS, EBO, and API. The LMI Team will be in charge of operating it. Changes made in this project should not change the exposure of any of the already-defined services and communications.

Security Impact

The proposed changes include new fields to clients' and beneficiaries’ addresses in a database scope and the necessary adjustments to the related exposed resources, such as API endpoints, changes in the way the API is accessed are not planned though.

In order to preserve the current functionalities that use unstructured data, the new structured data provided by clients should be properly concatenated and stored in the unstructured fields.

Performance Impact

The proposed changes in this RFC should make a minor impact on the system’s performance. The big difference, from a technical perspective, between the final and current implementation, will be the use of structured postal address data instead of unstructured data. The way to fetch the data and the implementation logic should not vary much. The minor impact will be because of new branches created during the course of the code in the various services that will be changed, but nothing critical.

Developer Impact

It is important to note that any alterations influencing endpoints or resources should be safeguarded by feature flags. This strategy allows the ability to toggle between an existing and new approach seamlessly. It is an effective risk mitigation measure, providing the freedom to experiment while ensuring business continuity and an easy rollback mechanism, should the need arise.

Apart from beneficiaries and clients, which are the purpose for the proposed changes, the address is also a part of other entities as shown in the background section. So, during the development of the changes, we should consider a solution that is backward compatible and doesn’t impact the other related entities and their functionalities.

Data Contracts

New optional fields will be added to the ‘core_address’ table in BOS database:

Field	Type
street_name	character varying(70) NULL
building_number	character varying(16) NULL
floor	character varying(70) NULL
room	character varying(70) NULL

This change will be backward compatible and will impact BOS and all other services that consume BOS API operations related to beneficiaries and clients, such as EBO and API WebApp.

Data Sources

The main data source for this project will be BOS DB.

Deployment

The project requires changes in many different systems. Then, there must be a reasonable order to apply the implementation and deployment. The core of the whole functionality is BOS, so the changes including database migrations and endpoint changes should be prioritized.

As the endpoints related to clients and beneficiaries are updated, the changes in other channels and services are unblocked and in general, they can be parallelized and self-paced since the intention is to preserve backward compatibility.

Regarding the rollout of the API changes, it will require a separate strategy to be aligned with Product, and probably considered to be made in stages as there would be breaking changes to the API customers. Changes on the API should also be done in coordination with Customers in order to allow them to first test the inclusion of the new postal address fields and then make the final adjustments on their side.

Dependencies

There is no other work that needs to be completed before we can implement the solution proposed for this project.

Based on RFC Template Version 1.1