This project is a simple ISO20022 message generator that generates pacs.008 xml messages for serial message flow. The project is called rapide, a French word. It translates to swift or fast or quick or swift, a swallow like bird.
The Java package names start with rapide at the root. You will notice references to rapide in different places such as
name of the wrapper bash shell script for the CLI tool.
This repository contains source code for iso20022 message generator tool (rapide) and machine learning prototype models. This
page has instructions for building and using rapide. The code for machine learning prototype models in form of Python notebooks
is in ml-models directory. The readme in that directory includes instructions for using
Python notebooks to build, train, deploy and use trained model for realtime and batch inferences.
These models help in predicting if an ISO20022 pacs.008 XML message will be successfully processed (Success) or fail
processing (Failure) leading to exception processing.
The ISO 20022 message generator supports generation of pacs.008 xml messages for serial message flow. It can generate a configurable number of messages with randomization of message elements as below:
- Charge Bearer: Randomly rotate value of between "SHAR", "DEBT" or "CRED". If "CRED" is used then block is added with set to a random value ranging from "1.00" to "15.00" with 2 decimal places.
- Category Codes and Payment Purpose Code: Randomly rotate value of using the "Code" list in a configuration file.
- Post Address: Randomly rotate the details of the Debtor, Ultimate Debtor and Creditor and Ultimate Creditor parties, using the LEI database and randomly populates the . LEI database has to be provided by the user.
- BIC Addresses, Instructing and Instructed Agents: Randomly rotate the details of the and , using the "BIC CODE" in the BIC database. BIC database has to be provided by the user. See Databases section for details.
- BIC Addresses, Previous Instructing Agent1, Intermediary Agent1: Randomly rotate the details of the and using the "BIC CODE" in the BIC database. BIC database has to be provided by the user. See Databases section for details.
- Currency Code: Randomly rotate the Currency Code in with 3 character currency codes using the ISO 4217.
- Instructed and Instructing Agents: Users can control the use of BIC codes for instructing and instructed agents by providing a list of BIC code in a configuration file. Only BIC Codes from configuration file are used, BIC database is ignored.
The rapide software is built using Java. You will need JDK 11 or higher to be installed on your developer machine. You can use Amazon Corretto, an openJDK distribution from Amazon.
-
Clone this repository:
git clone https://github.com/aws-samples/iso20022-message-generator.git
-
Change directory to the clone repository:
cd iso20022-message-generator -
Build the message generator:
./gradlew clean build
This will build the Spring Boot jar.
-
Run the iso20022 message generator cli:
cd pacs008 ./rapide-iso20022 # this print the command line options
rapide, an ISO 20022 message generator, is command line tool and provides options to control:
- number of sample messages to generate
- customize name of the generated xml message file
- directory where to place all generated xml message files
- zip all generated xml message files
Usage: rapide-iso20022 [-z] [-d=<outputDirectory>] -n=<numberOfMessages> [-o=<outputFilePrefix>]
-d, --directory=<outputDirectory>
Directory where files will be written to
-n, --number-of-messages=<numberOfMessages>
Number of messages to generate
-o, --output-file-prefix=<outputFilePrefix>
File name prefix that will store generated messages
-z, --archive Flag to create zip file of generated filesOnly -n or --number-of-messages is required option and if -d or --directory is not used then files are generated in
current working directory.
Rapide software is built using Java and it uses following open source Java libraries, frameworks and platforms:
The diagram below shows high level architecture diagram of the Rapide CLI tool.
There are two databases used by the message generator:
- LEI Database: The data for LEI can be obtained from Global Legal Entity Foundation or GLEIF website. The JPA Entity model mentioned below was created data file available on GLEIF web site. A sample file with dummy data is here.
- BIC Database: The BIC database can be obtained from SWIFT. The JPA Entity model mentioned below was created a sample data file. A sample file with dummy data is here.
We recommended that you obtain the LEI and BIC data from these data providers. The data files in CSV format should be consistent with the sample files mentioned above. If they diverge, you can fork this repository and modify the JPA entities below to meet your needs.
The rapide.iso20022.data package has Spring Data Repository and JPA Entities for each database.
- LegalEntity - see this class for LegalEntity attributes
- BICRecord - see this class for BIC attributes
- Database Schema has DDL for above entities as well code for loading H2 in-memory database with records from a CSV files.
The ISO 20022 message generator CLI tool provides various options to customize message generation. As mentioned the message generator
tool built using Spring Boot and hence the customizations are done using Spring Boot's application.yaml file.
These options can be provided using Spring Boot's mechanisms for providing application yaml, see section 2.3:
- Modifying the application.yaml file and rebuilding the jar.
- Providing an updated
application.yamlin current directory (i.e. pacs008) or config directory in pacs008d directory. Spring Boot will automatically readapplication.yamlplaced above directory.
The application.yaml file contains configurable properties for both Spring Boot related resources and rapide CLI tool.
The Spring related configuration properties are under Spring's namespace and hierarchy.
The rapide's message generator's configurable properties are under rapide hierarchy:
rapide:
PurposeCode:
Currency:
SourceBicList:
DestinationBicList:
...Logging is performed using Spring Boot's Logging
support. The application.yaml file controls log levels. By default it the
log level is at ERROR level. You can change the log level to info or debug to get detailed logs for troubleshooting.
You can replace in-memory H2 relational database with any relational database such as Amazon RDS (any support relational database e.g. mysql, postgresql et.c). This is possible due to Spring Boot's Spring Data JPA support.
The data source related properties in application.yaml can be configured to meet the needs of your database platform.
See Spring Boot's documentation on Data Access. For example to use Amazon RDS
for MySQL, the application.yaml file will look like one shown below:
spring:
datasource:
platform: mysql
driver-class-name: com.mysql.cj.jdbc.Driver
url: jdbc:mysql://{instance-id}.{random-identifier}.{region}.rds.amazonaws.com:3306/{database-name}
username: <username>
password: <password>
jpa:
database-platform: org.hibernate.dialect.MySQLDialectYou can also initialize database with reference data or full records on startup using Hibernate's database initialization mechanism in conjunction with Spring Boot as documented here.
The category codes and payment purpose codes used in the generated messages can be customized by providing them in application.yaml
under property rapide.PurposeCode:
rapide:
PurposeCode:
- Your code 1
- Your code 2
- ... You can provide currency for countries by adding them in the application.yaml under rapide.Currency property:
rapide:
Currency:
- Country: US
Code: USD
- Country: UK
Code: GBPYou can add a list of source and destination BICs to be used in generated messages by adding them in the application.yaml
under rapide.SourceBicList property for source BIC list (from BIC) and rapide.DestinationBicList property for
destination BIC list:
rapide:
SourceBicList:
- Your Source BIC1
- Your Source BIC2
DestinationBicList:
- Your Destination BIC1
- Your Destination BIC2In this case the BIC codes in BIC database are ignored (i.e. are not selected randomly from BIC database). You can choose to just override source BIC or destination BIC only or both.
This source code is licensed under the MIT-0 License. See the LICENSE file for details.