NAME

Business::CAMT - ISO20022 Cash Management (CAMT) messages

SYNOPSIS

my $camt = Business::CAMT->new;
my $data = $camt->read($file|$xml);

DESCRIPTION

Use this module to manage CAMT messages, which are ISO20022 standard "Cash Management" messages as produced in banking. For instance, CAMT.053 is produced by banks and consumed by accountancies, showing transactions in bank-accounts. See https://www.iso20022.org.

At the moment, this module can be used to read the XML files. It is intended to also support constructing them. However, I need a sponsor to make that happen. Contact the author for support.

METHODS

Constructors

Business::CAMT->new(%options)

Create a new CAMT processing object.

Reuse this object to avoid recompilation of the message reader.

-Option       --Default
 big_numbers    false
 long_tagnames  false
 match_schema   'NEWER'

big_numbers => BOOLEAN

Set to a true value when your accounts run into the billions. This will enable Math::BigFloat to be used, which is slower and memory hungry.

long_tagnames => BOOLEAN

The schemas are derived from an UML specifications which uses clear and readible long names for relations and attributes. But, someone with a poor sense of optimization removed most of the vowels from these tags while translating the UML into an XSD. When set to true, this option will give you the nice long names in Perl.

match_schema => $rule

Sets the default $rule how to handle messages which have namespaces which do not match the schemas contained in the module release.

See matchSchema() for the available $rule values. See the DETAILS section about the namespace versioning horrors.

Accessors

DETAILS

Implementation issues

XML namespaces

The idea behind XML namespaces to include schema versioning is fundamentally flawed. The CAMT files form no exception in broken XML concept. Of course, schema versions are backwards compatible, so why not design your versioning with that in mind?

This module bends the namespace use to hide these design mistakes into flexible code. Without full knowledge about existing and future versions of the schemas, there is a powerfull configuration setting with matchSchema(). Please consider to contribute discovered issues to this module.

Tag abbreviations

XML is very verbose anyway, so it really does not help to abbreviate tags leaving some vowels out. This makes it harder to read messages and code. It increases the chance on stupid typos in the code.

No common types

Each schema is separate, although their type definitions are overlapping. It is not guaranteed that equal types will stay that way over time. This may cause instable code. Probably, issues will not emerge because the schema files are generated from a central UML model.

Missed chances on XML

The messages are designed with an UML tool, which means: limited to the features of that tool and hindering the view on the quality of the schema. This leads to structures like:

<Bal>
  <Tp>
    <CdOrPrtry>
       <Cd>OPBD</Cd>
    </CdOrPrtry>
  </Tp>
  <Amt Ccy="SEK">500000</Amt>
  <CdtDbtInd>CRDT</CdtDbtInd>
  <Dt>
    <Dt>2010-10-15</Dt>
  </Dt>
</Bal>

In Perl, this leads to (long_tagnames on)

Balance => {
  Type => {
    CodeOrProperty => {
      Code => 'OPBD',
    }
  },
  Amount => {
    _ => '500000',
    Currency => 'SEK',
  },
  CreditDebitInd => 'CRDT',
  Date => {
    Date => '2010-10-15',
  },
}

The XML schema, when designed as XML schema, could have looked like

<Credit Code="OPDB">
  <Amount Currency="SEK">500000</Amount>
  <Date>2010-10-15</Date>
</Credit>

Also: use of substitutionGroups would have made messages so much clearer and easier.

Read

$obj->fullname2tagTable()

Translates long and understandable names into (silly) abbreviated tags.

$obj->knownVersions( [$set] )

Returns a sorted LIST with all schema versions which are included in this distribution. When the $set is specified (like 053.001), then only those are reported.

$obj->matchSchema($set, $version, %options)

Find the available schema version for the $set (like '053.001') to interpret a message with $version (like '02').

-Option--Default
 rule    new(match_schema)

rule => 'EXACT'|'NEWER'|'NEWEST'|'ANY'|CODE

When EXACT, only the precise version is acceptable. NEWER will fall back to the closest newer version. When no exact match, NEWEST returns the highest available version, but must be newer. Most generous is ANY, which falls back to the newest available version even when it is older than the message version.

You may also pass a CODE reference, which is called with the $set, the requested schema, and a sorted ARRAY of available versions. It must return one of the available versions or undef (no compatible version).

$obj->read($file|$xml, %options)

Pass a $file name, an $xml document or an $xml node. Returned is a HASH blessed in class 'Business::CAMT::CAMnr', for instance Business::CAMT::CAMT053.

-Option      --Default
 match_schema  new(match_schema)

match_schema => $rule

$obj->schemaReader($set, $version, $ns)

$obj->tag2fullnameTable()

Returns a table which translates the (silly) abbreviations used in the XML tags into readable names. Good names make it easier to understand the handling code and is less error-prone.

SEE ALSO

This module is part of Business-CAMT distribution version 0.10, built on November 25, 2024. Website: http://perl.overmeer.net/CPAN/

LICENSE

Copyrights 2024 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://dev.perl.org/licenses/

cpanm Business::CAMT

perl -MCPAN -e shell
install Business::CAMT