ISO 20022 codec gear

The codec_iso20022 gear converts ISO 20022 XML to a structured fluxMsg and back. It does for ISO 20022 what the ISO8583 codec gear does for ISO 8583. It converts the format, it checks the messages, and it gives the fields their aliases. It does not translate between protocols. The translate gear does that.

The gear loads an ISO 20022 spec. The wire source of the spec does the parsing and fixes the profile: the message definitions the gear accepts and the rules they follow.

Attribute	Details
Type	`codec_iso20022`
Status	Stable
Source Code	pkg/gears/native/iso20022/codec
Pairs With	Translate gear, TCP I/O gear, Conductor gear
Always Emitted Metadata (decode)	`codec.protocol`, `iso20022.message`, `iso20022.profile`, `codec.spec_id`, `codec.spec_version`, `codec.spec_hash`, `[alias]`
Conditionally Emitted Metadata	`codec.violations` (when validation is on and a check failed), `error.reason`, `error.gear` and `error.message` (on the `error` port, with `on_error: reject`)
Consumed Metadata (encode)	`iso20022.message` (when `message` is `auto`), `iso20022.participant_id` (when `participant_id` is empty)
Consumed Fields (encode)	`[alias]` or `iso20022.<element path>`

A worked example that uses this gear is the tutorial Bridge ISO 8583 and ISO 20022.

Reference

fluxrig gears doc codec_iso20022 generates the identity, ports, and configuration below from the gear's manifest, so they stay in lockstep with the code.


Type	`codec_iso20022`
Category	codec
Status	stable
Terminus	transparent

ISO 20022 encode and decode against a protocol spec. XML becomes structured fluxMsg fields, under their element paths and aliases, and back.

Ports

Port	Direction	Role	Summary
`in`	input	message	Message to encode or decode. Encode reads the message definition from iso20022.message when the config says auto.
`out`	output	message	Encoded or decoded message. A decode also sets iso20022.message, iso20022.profile and the codec.spec_* keys. An encode fills the elements the profile fixes, including the message identifier.
`error`	output	error	With on_error: reject, the message that the codec rejects, with error.reason (violation or codec_failed), error.gear and error.message. codec.violations lists the findings.

Configuration

Field	Type	Required	Default	Description
`spec_path`	string	yes	-	The ISO 20022 protocol spec: a path to a file, or a store reference as name:tag (e.g. iso20022-rtp:v1.0.0) or a content hash. Its wire source fixes the profile.
`direction`	enum: `auto`, `encode`, `decode`		`auto`	encode, decode, or auto (decode when the message has a raw payload, encode when it does not).
`message`	enum: `auto`, `pacs.008.001.08`, `pacs.002.001.10`		`auto`	the message definition. auto takes it from the document that the envelope carries on decode, and from the iso20022.message metadata on encode.
`on_error`	enum: `reject`, `drop`, `kill`		`drop`	on a decode/encode failure, or on a message a rule rejects: reject (emit the message on the error port, with error.reason), drop (discard it), or kill (return the error to the runtime).
`participant_id`	string		-	The 11-character participant identifier in the message identifier that the profile generates. Empty takes it from the iso20022.participant_id metadata, which translate writes. Set it only for an encode that no translate gear feeds.
`validation`	enum: `off`, `warn`, `enforce`		`off`	What the codec does with the findings of the wire validators and the spec checks. off: no checks. warn: the codec records the findings in codec.violations, and the message continues. enforce: a finding that rejects fails the message, which then follows on_error.

How the codec represents a message

On decode, the codec writes each field of the XML into fluxMsg.Data. On encode, it reads them back and writes the XML into fluxMsg.RawPayload. An encode does not remove the fields from Data: the message keeps both, and the next gear can read either.

Raw paths

The raw path of a field is the chain of XML element names below the message root, joined by dots, under the iso20022 key:

XML	Raw path	Value
`<GrpHdr><MsgId>M2026...</MsgId>`	`iso20022.GrpHdr.MsgId`	`M2026...`
`<CdtTrfTxInf><IntrBkSttlmAmt Ccy="USD">42.50</IntrBkSttlmAmt>`	`iso20022.CdtTrfTxInf.IntrBkSttlmAmt`	`42.50`
the same element, attribute `Ccy`	`iso20022.CdtTrfTxInf.IntrBkSttlmAmt@Ccy`	`USD`

The path uses the element names of the ISO 20022 schema, not the names of a programming language. Thus a field has the same path in every tool that reads the schema. An attribute is a sibling of its element: the element name, @, and the attribute name.

Aliases

The protocol spec can give a field an alias, for example settlement_amount for CdtTrfTxInf.IntrBkSttlmAmt. On decode, the codec writes the value two times: under the alias and under the raw path. On encode, the alias has priority over the raw path. The ISO8583 codec gear works the same way.

An alias can name two fields only if the two fields are never in the same message. For example, instr_id can name CdtTrfTxInf.PmtId.InstrId in a pacs.008 and TxInfAndSts.OrgnlInstrId in a pacs.002. A conductor can then match an answer to its request on one alias.

The spec also classifies fields. The codec masks a field that the spec marks as sensitive, for example an account identifier with sensitivity: pii, in its logs.

Profiles

The wire source of the protocol spec sets the profile. The profile is the ISO 20022 usage of one payment network. It sets the message definitions that the gear accepts, their envelope and their rules.

Wire source	Profile	Network	Message definitions
`moov-rtp20022`	`rtp`	The RTP network of The Clearing House	`pacs.008.001.08`, `pacs.002.001.10`

The ISO 20022 spec reference names the library and the version of each wire source.

The `rtp` profile

The rtp profile carries one transaction for each message, in US dollars, between participants that a 9-digit routing number identifies.

Each message travels in the envelope of the network. The envelope holds a business application header (head.001) and one document, with a namespace prefix on each element:

<Message xmlns="urn:tch" xmlns:head="urn:iso:std:iso:20022:tech:xsd:head.001.001.01"
         xmlns:ct="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08">
  <AppHdr>
    <head:Fr>...</head:Fr>
    <head:To>...</head:To>
    <head:BizMsgIdr>...</head:BizMsgIdr>
    <head:MsgDefIdr>pacs.008.001.08</head:MsgDefIdr>
    <head:CreDt>...</head:CreDt>
  </AppHdr>
  <CreditTransfer>
    <ct:FIToFICstmrCdtTrf>...</ct:FIToFICstmrCdtTrf>
  </CreditTransfer>
</Message>

The fields of the header are under AppHdr., for example AppHdr.To.FIId.FinInstnId.ClrSysMmbId.MmbId. The fields of the document are under their element path below the document root, for example GrpHdr.MsgId.

The rules of the profile include these:

The currency is USD.
ClrSysMmbId.MmbId has exactly 9 characters.
MsgId and InstrId have the format of the profile: a date, an 11-character participant identifier and a serial number.
A pacs.008 has a debtor name and a creditor name.
TxSts is ACTC, ACWP, RCVD or RJCT.

On encode, the codec writes two kinds of elements.

The identity of the message. The codec always writes these elements, and replaces a value that the message already has. A message that answers another message is a new message: it carries the fields of the message it answers, but not its identifiers.

Message	Elements the codec always writes
Both	`GrpHdr.MsgId`, `GrpHdr.CreDtTm`, `AppHdr.Fr.FIId.FinInstnId.ClrSysMmbId.MmbId` (the participant identifier), `AppHdr.BizMsgIdr`, `AppHdr.MsgDefIdr` (the message definition), `AppHdr.CreDt`

The elements that have only one valid value in the profile. The codec writes these only when the message does not have them.

Message	Elements the codec writes when they are missing
`pacs.008.001.08`	`GrpHdr.IntrBkSttlmDt`, `GrpHdr.NbOfTxs` (`1`), `GrpHdr.TtlIntrBkSttlmAmt`, `GrpHdr.SttlmInf.SttlmMtd` (`CLRG`), `GrpHdr.SttlmInf.ClrSys.Cd` (`TCH`), `CdtTrfTxInf.PmtTpInf.SvcLvl.Cd` (`SDVA`), `CdtTrfTxInf.ChrgBr` (`SLEV`), `CdtTrfTxInf.InstgAgt` and `CdtTrfTxInf.InstdAgt` (copied from `CdtTrfTxInf.DbtrAgt` and `CdtTrfTxInf.CdtrAgt`)
`pacs.002.001.10`	`TxInfAndSts.AccptncDtTm`, `OrgnlGrpInfAndSts.OrgnlNbOfTxs`

The codec does not write the receiver, AppHdr.To. The translation sets it: the alias receiver_participant.

The codec does not write the instruction identifier (InstrId). That identifier links a request to its answer, so it must exist before a conductor parks the request, and that is before the encode. The translate gear generates it.

The participant identifier

GrpHdr.MsgId contains the participant identifier of the sender. The codec takes it from the iso20022.participant_id metadata, which the translate gear writes from the translation spec. Thus MsgId and the InstrId that the translate gear generates contain the same participant. Set the participant_id key only for an encode that no translate gear feeds.

Message and direction

With direction: auto, the codec decodes a message that has a RawPayload and encodes a message that does not.

A decode keeps the XML in RawPayload. Thus a codec with direction: auto decodes again a message that an earlier codec decoded. Set direction on every codec in a scenario that decodes a message and encodes an answer to it.

With message: auto, the codec finds the message definition:

On decode, from the document that the envelope carries: CreditTransfer is a pacs.008.001.08, and MessageStatusReport is a pacs.002.001.10.
On encode, from the iso20022.message metadata. The translate gear writes it from the target message of the translation.

Set message to a definition to override both.

Validation

With validation: warn or enforce, the codec checks each message on decode and on encode, in two layers:

The wire source. The ISO 20022 schema and the rules of the profile.
The protocol spec. The fields that each message of its catalog makes mandatory or forbids.

The checks of the protocol spec are not applied to traffic [Roadmap]. The spec loader checks that they are well formed.

The codec records the findings in codec.violations and logs them. With warn, the message continues. With enforce, a finding fails the message, which then follows on_error. With off, the codec does not check.

With on_error: reject, a message that fails leaves on the error port, without its XML. error.reason says why: violation for a finding with enforce, and codec_failed for XML that does not decode or a message that does not encode. Wire error to a gear that answers the sender, for example a decline. With drop, the message is discarded and the codec logs why.

Error handling

on_error sets what happens to a message that fails to decode, fails to encode, or fails a check under enforce:

Value	Behaviour
`drop`	The codec discards the message. This is the default, as on the ISO8583 codec gear.
`reject`	The codec emits the message on the error path.
`kill`	The gear fails.

Reference​

How the codec represents a message​

Raw paths​

Aliases​

Profiles​

The rtp profile​

The participant identifier​

Message and direction​

Validation​

Error handling​