Skip to content

Commit

Permalink
preps 1.3.0
Browse files Browse the repository at this point in the history 
- extends README
  • Loading branch information
Maxim committed Jan 14, 2019
1 parent 2b46a0a commit 15ccbfd
Show file tree
Hide file tree
Showing 3 changed files with 74 additions and 45 deletions.
46 changes: 28 additions & 18 deletions CHANGELOG.mdown
View file
Original file line number Diff line number Diff line change
@@ -1,35 +1,45 @@
# 1.3.0

- [FEATURE] adds MT942 compability

# 1.2.0
* [FEATURE] strips mt940 header if configured ([#9](https://github.com/railslove/cmxl/issues/9))
```ruby
Cmxl.config[:strip_headers] = true
```

- [FEATURE] strips mt940 header if configured ([#9](https://github.com/railslove/cmxl/issues/9))
```ruby
Cmxl.config[:strip_headers] = true
```

# 1.1.1
* [BUGFIX] prevents short bank references from swallowing supplementary details delimiter

- [BUGFIX] prevents short bank references from swallowing supplementary details delimiter

# 1.1.0
* [FEATURE] adds support for supplementary details in transactions (Field 61, Subfield 9) ([#18](https://github.com/railslove/cmxl/issues/18))

- [FEATURE] adds support for supplementary details in transactions (Field 61, Subfield 9) ([#18](https://github.com/railslove/cmxl/issues/18))

# 1.0.0
* [FEATURE] adds support for storno transactions ([#14](https://github.com/railslove/cmxl/issues/14))
* [NOTE] full backwards compatibility
* [NOTE] same as release 0.2.2, fixing versioning

- [FEATURE] adds support for storno transactions ([#14](https://github.com/railslove/cmxl/issues/14))
- [NOTE] full backwards compatibility
- [NOTE] same as release 0.2.2, fixing versioning

# 0.2.1
* addressing an bug that occoured for transactions submitted end of
but were fetched in the new year -> those ended up with the wrong year
on the entry date
* MT942 support for field 13

- addressing an bug that occoured for transactions submitted end of
but were fetched in the new year -> those ended up with the wrong year
on the entry date
- MT942 support for field 13

# 0.2.0
* added several balance related accessors ([#7](https://github.com/railslove/cmxl/issues/7))
* configuration option for `statement separator` ([#5](https://github.com/railslove/cmxl/issues/5))
* improvement for general compatibility

- added several balance related accessors ([#7](https://github.com/railslove/cmxl/issues/7))
- configuration option for `statement separator` ([#5](https://github.com/railslove/cmxl/issues/5))
- improvement for general compatibility

# 0.1.3

* [BUGFIX] fixed the statement details parser. It failed in case of empty values in the SEPA details
- [BUGFIX] fixed the statement details parser. It failed in case of empty values in the SEPA details

# 0.1.2

* [BUGFIX] fixed the statement details parser. It failed in case of empty values in the sub fields
- [BUGFIX] fixed the statement details parser. It failed in case of empty values in the sub fields
71 changes: 45 additions & 26 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,24 +2,24 @@

# Cmxl - your friendly ruby MT940 parser

At [Railslove](http://railslove.com) we build a lot of financial applications and work on integrating applications with banks and banking functionality.
At [Railslove](http://railslove.com) we build a lot of financial applications and work on integrating applications with banks and banking functionality.
Our goal is to make simple solutions for what often looks complicated.

Cmxl is a friendly and extendible MT940 bank statement file parser that helps your extracting data from the bank statement files.
Cmxl is a friendly and extendible MT940 bank statement file parser that helps your extracting data from the bank statement files.

## What is MT940?
## What is MT940 & MT942?

MT940 (MT = Message Type) is the SWIFT-Standard for the electronic transfer of bank statement files.
When integrating with banks you often get MT940 files as interface.
MT940 (MT = Message Type) is the SWIFT-Standard for the electronic transfer of bank statement files.
When integrating with banks you often get MT940 or MT942 files as interface.
For more information have a look at the different [SWIFT message types](http://en.wikipedia.org/wiki/SWIFT_message_types)

At some point in the future MT940 file should be exchanged with newer XML documents - but banking institutions are slow so MT940 will stick around for a while.

## Reqirements

Cmxl is a pure ruby parser and has no dependency on native extensions.
Cmxl is a pure ruby parser and has no dependency on native extensions.

* Ruby 1.9.3 or newer (jruby, etc.)
- Ruby 1.9.3 or newer (jruby, etc.)

## Installation

Expand All @@ -37,7 +37,7 @@ Or install it yourself as:

## Usage

Simple usage:
Simple usage:

```ruby

Expand All @@ -55,14 +55,14 @@ Cmxl.config[:strip_headers] = true

# Statment parsing:

statements = Cmxl.parse(File.read('mt940.txt'), :encoding => 'ISO-8859-1') # parses the file and returns an array of statement objects. Please note: if no encoding is given Cmxl tries to guess the encoding from the content and converts it to UTF-8.
statements = Cmxl.parse(File.read('mt940.txt'), :encoding => 'ISO-8859-1') # parses the file and returns an array of statement objects. Please note: if no encoding is given Cmxl tries to guess the encoding from the content and converts it to UTF-8.
statements.each do |s|
puts s.reference
puts s.generation_date
puts s.opening_balance.amount
puts s.closing_balance.amount
puts s.sha # SHA of the statement source - could be used as an unique identifier

s.transactions.each do |t|
puts t.information
puts t.description
Expand All @@ -87,24 +87,46 @@ Every object responds to `to_h` and let's you easily convert the data to a hash.

#### A note about encoding and file wirednesses

You probably will encounter encoding issues (hey, you are building banking applications!).
We try to handle encoding and format wirednesses as much as possible. If no encoding is passed we try to guess the encoding of the data and convert it to UTF8.
In the likely case that you encouter encoding issues you can pass encoding options to the `Cmxl.parse(<string>, <options hash>)` it accepts the same options as [String#encode](http://ruby-doc.org/core-2.1.3/String.html#method-i-encode)
You probably will encounter encoding issues (hey, you are building banking applications!).
We try to handle encoding and format wirednesses as much as possible. If no encoding is passed we try to guess the encoding of the data and convert it to UTF8.
In the likely case that you encouter encoding issues you can pass encoding options to the `Cmxl.parse(<string>, <options hash>)` it accepts the same options as [String#encode](http://ruby-doc.org/core-2.1.3/String.html#method-i-encode)
If that fails try to motify the file before you pass it to the parser - and please create an issue.

### MT940 SWIFT header data

Cmxl currently does not support parsing of the SWIFT headers (like {1:F01AXISINBBA ....)
Cmxl currently does not support parsing of the SWIFT headers (like {1:F01AXISINBBA ....)
If your file comes with these headers try the `strip_headers` configuration option to strip data execpt the actual MT940 fields.

```ruby
Cmxl.config[:strip_headers] = true
Cmxl.parse(...)
```

### MT942 data

CMXL is now also capable of parsing MT942 data. Just pass the data and the parser will identify the type automatically.

```ruby
first_statement = Cmxl.parse(File.read('mt940.txt'), :encoding => 'ISO-8859-1').first
puts first_statement.mt942?
#=> false

first_statement = Cmxl.parse(File.read('mt942.txt'), :encoding => 'ISO-8859-1').first
puts first_statement.mt942?
#=> true

p first_statement.vmk_credit_summary.to_h
#=> { type: 'credit', entries: 1, amount: 9792.0, currency: 'EUR' }

p first_statement.vmk_dedit_summary.to_h
#=> { type: 'debit', entries: 0, amount: 0.0, currency: 'EUR' }

first_statement.transactions # same as for MT940
```

### Custom field parsers

Because a lot of banks implement the MT940 format slightly different one of the design goals of this library is to be able to customize the individual field parsers.
Because a lot of banks implement the MT940 format slightly different one of the design goals of this library is to be able to customize the individual field parsers.
Every line get parsed with a special parser. Here is how to write your own parser:

```ruby
Expand All @@ -128,23 +150,20 @@ my_field_parser.data #=> {'world' => 'hello from mt940'} - data is the accessor

## Parsing issues? - please create an issue with your file

The Mt940 format often looks different for the different banks and the different countries. Especially the not strict defined fields are often used for custom bank data.
The Mt940 format often looks different for the different banks and the different countries. Especially the not strict defined fields are often used for custom bank data.
If you have a file that can not be parsed please open an issue. We hope to build a parser that handles most of the files.


## ToDo

* collect MT940 files from different banks and use them as example for specs
* support for Mt942
* better header data handling

- collect MT940 files from different banks and use them as example for specs
- better header data handling

## Looking for other Banking and EBICS tools?

Maybe these are also interesting for you.

* [EPICS: Open Source SEPA EBICS client](https://railslove.github.io/epics/) full implementation to manage all the banking activities like direct debits, credits, etc. (SEPA Lastschrift, Überweisungen, etc.)
* [EBICS::Box: out of the box solution to automate banking activities](http://www.railslove.com/ebics-box) - The missing API for your bank
- [EPICS: Open Source SEPA EBICS client](https://railslove.github.io/epics/) full implementation to manage all the banking activities like direct debits, credits, etc. (SEPA Lastschrift, Überweisungen, etc.)
- [EBICS::Box: out of the box solution to automate banking activities](http://www.railslove.com/ebics-box) - The missing API for your bank

## Contributing

Expand All @@ -161,9 +180,9 @@ Automated tests: We use rspec to test Cmxl. Simply run `rake` to execute the who
Cmxl is inspired and borrows ideas from the `mt940_parser` by the great people at [betterplace](https://www.betterplace.org/).

other parsers:
* [betterplace/mt940_parser](https://github.com/betterplace/mt940_parser)
* [gmitrev/mt940parser](https://github.com/gmitrev/mt940parser)

- [betterplace/mt940_parser](https://github.com/betterplace/mt940_parser)
- [gmitrev/mt940parser](https://github.com/gmitrev/mt940parser)

## Stats

Expand All @@ -172,6 +191,6 @@ other parsers:
[![Test Coverage](https://codeclimate.com/github/railslove/cmxl/badges/coverage.svg)](https://codeclimate.com/github/railslove/cmxl)
[![Gem Version](https://badge.fury.io/rb/cmxl.svg)](http://badge.fury.io/rb/cmxl)

------------
---

2014 - built with love by [Railslove](http://railslove.com) and released under the MIT-Licence. We have built quite a number of FinTech products. If you need support we are happy to help. Please contact us at [email protected].
2 changes: 1 addition & 1 deletion lib/cmxl/version.rb
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
module Cmxl
VERSION = '1.2.0'.freeze
VERSION = '1.3.0'.freeze
end

0 comments on commit 15ccbfd

Please sign in to comment.