HVP business application header mapper - HVPMessageRouter
These HVPMessageRouter mappers are a pair of wrapper mappers that act as routers to message body mappers for incoming and outgoing messages that use the ISO 20022 or SWIFT specifications.
Overview
- The ISO 20022 specification business application header content.
- The Swift specification application header content.
<AppHdr>
- This element contains the business application header or application header data.
<Document>
- This element contains the main body of the message.
A message that needs to be mapped arrives in the HVP message router and is processed in a manner similar to that of the ISOMessageRouter. Root elements are created and populated in the mapped document. Then, the message is routed to an appropriate body mapper to map the body of the document before it returns to the HVP message router. Differing from the ISOMessageRouters, the inbound and outbound HVPMessageRouters are also responsible for processing the business application header and application header elements that are used for the relevant specification.
- CBPR+
- For this scheme, the mappers are CBPR+MessageRouterInbound and CBPR+MessageRouterOutbound.
- EURO1
- For this scheme, the mappers are Euro1MessageRouterInbound and Euro1MessageRouterOutbound.
- Kronos2
- For this scheme, the mappers are Target2MessageRouterInbound and Target2MessageRouterOutbound.
- NBO
- For this scheme, the mappers are NBOMessageRouterInbound and NBOMessageRouterOutbound.
- RIX
- For this scheme, the mappers are RIXMessageRouterInbound and RIXMessageRouterOutbound.
- T2
- For this scheme, the mappers are Target2MessageRouterInbound and Target2MessageRouterOutbound.
The Message To channels for these payment schemes are configured to use the outbound mapper for the scheme. Similarly, the Message From channels for the payment schemes are configured to use the inbound mapper for the scheme. The following table shows the mappers that are configured for the channels for the different payment schemes.
Channel name | Mapper |
---|---|
Message From CBPR+ Gateway | CBPR+MessageRouterInbound |
Message To CBPR+ Gateway | CBPR+MessageRouterOutbound |
Message From Euro1 | Euro1MessageRouterInbound |
Message To Euro1 | Euro1MessageRouterOutbound |
Message From Kronos2 | Target2MessageRouterInbound |
Message To Kronos2 | Target2MessageRouterOutbound |
Message From NBO | NBOMessageRouterInbound |
Message To NBO | NBOMessageRouterOutbound |
Message From RIX | RIXMessageRouterInbound |
Message To RIX | RIXMessageRouterOutbound |
Message From Target2 | Target2MessageRouterInbound |
Message To Target2 | Target2MessageRouterOutbound |
HVPMessageRouterInbound
Incoming messages to be mapped to ISF by using the HVPMessageRouterInbound mapper are processed in the
following manner. The message type is determined by examining the child element of the
<Document>
element. If the message contains <AppHdr>
content,
the <Document>
element is usually a child element of a wrapper root element. Or, in
some cases it is the root element itself.
<FIToFICstmrCdtTrf>
indicates a pacs.008.* message.<FICdtTrf>
indicates a pacs.009.* message.<FIToFIPmtStsRpt>
indicates a pacs.002.* message.<PmtRtr>
indicates a pacs.004.* message<FIToFIPmtCxlReq>
indicates a camt.056.* message.<xsys.011.001.01>
indicates an xsys.011.* message.<xsys.011.001.02>
indicates an xsys.011.* message.<xsys.012.001.01>
indicates an xsys.012.* message.<xsys.012.001.02>
indicates an xsys.012.* message.<RsltnOfInvstgtn>
indicates a camt.029.* message.<RctAck>
indicates an admi.007.* message.<Rct>
indicates a camt.025.* message.<BkToCstmrStmt>
indicates a camt.053.* message.<BkToCstmrDbtCdtNtfctn>
indicates a camt.054.* message.
The CONFIG=entry
, which is stored as a channel parameter, and the
identified message type are used to retrieve the <msgTypeCfg>
entry from the value
table. The <msgTypeCfg>
entry contains the name of the body mapper to use to map the
received message.
For example, the Message From Target2 channel can be configured to use the Target2MessageRouterInbound
mapper by using a CONFIG=HVP_MAP_CFG_MSG_FROM_TARGET2
parameter. When a pacs.008.001.08
message is received from the channel, the HVPMessageRouterInbound mapper determines that it is a pacs.008.*
message based on the FIToFICstmrCdtTrf element. Then, each <msgTypeCfg>
entry with
category HVP_MAP_CFG_MSG_FROM_TARGET2 in the value table is examined. When a
<msgTypeCfg>
entry with a <type>
child element that matches
pacs.008.*
is found, its <mapName>
element is used to get the name of
the body mapper to use for the received message. For example, Pacs008ToISFMapper.
If a <msgTypeCfg>
entry with a matching <type>
value is not
found, an exception with a mapper not found error occurs.
Category | Key | Configuration value |
---|---|---|
HVP_MAP_CFG_MSG_FROM_TARGET2 |
msgTypeCfg_pacs.008 |
Note: The
<type> element matches and the <mapName> element
identifies the correct mapper. |
HVP_MAP_CFG_MSG_FROM_TARGET2 |
msgTypeCfg_pacs.002 |
|
HVP_MAP_CFG_MSG_FROM_TARGET2 |
msgTypeCfg_admi.007 |
|
HVP_MAP_CFG_MSG_FROM_TARGET2 |
msgTypeCfg_xsys.011 |
|
After the mapper to be used for the body of the incoming message is identified, HVPMessageRouterInbound sets environment variables before the message is redirected to the body mapper. These variables are used by the body mapper to determine where in the incoming message to begin mapping from.
The incoming message is then redirected from the Route to Label node in the HVPMessageRouterInbound mapper to the appropriate dedicated body mapper. When the body mapper is finished, the message is redirected back to the HVPMessageRouterInbound mapper.
- EURO1
- Kronos2
- NBO
- RIX
- T2
<AppHdr>
element was present in the original message, it is
appended to the now-mapped ISF as the last child element under the <Addenda>
element.Sample mapped ISF, including addenda, from inbound pacs.008 message from T2
<isf:ISFMessage xmlns:isf="http://www.ibm.com/xmlns/prod/ftm/isf/v3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Header>
<BusinessConcept>HVP_FROM_CSM_INSTR</BusinessConcept>
<TransactionRef>Inp008b020-InsId</TransactionRef>
<MessageName>pacs.008.001.08</MessageName>
<Sender>TRGTXETGXXX</Sender>
<Receiver>FEUBAB20XXX</Receiver>
</Header>
<isf:CreditTransfer>
<ChargeBearer>DEBT</ChargeBearer>
<EndToEndIdentification>Inp008b020-E2EId</EndToEndIdentification>
<PartyRole xsi:type="isf:DebtorRole">
<Player xsi:type="isf:Party">
<Identification xsi:type="isf:OrganisationIdentification">
<PartyName>
<Name>Debtor name</Name>
</PartyName>
<AnyBIC>DEBTORXXBIC</AnyBIC>
</Identification>
</Player>
</PartyRole>
<PartyRole xsi:type="isf:DebtorAgentRole">
<Player xsi:type="isf:FinancialInstitution"/>
</PartyRole>
<PartyRole xsi:type="isf:CreditorAgentRole">
<Player xsi:type="isf:FinancialInstitution"/>
</PartyRole>
<PartyRole xsi:type="isf:CreditorRole">
<Player xsi:type="isf:Party">
<Identification xsi:type="isf:OrganisationIdentification">
<PartyName>
<Name>Creditor name</Name>
</PartyName>
<AnyBIC>CREDITORBIC</AnyBIC>
</Identification>
</Player>
</PartyRole>
<PaymentExecution xsi:type="isf:ISFPaymentInstruction">
<CreationDate>2019-10-07T09:30:00.000+00:00</CreationDate>
<Identification>Inp008b020-InsId</Identification>
<AgentRole xsi:type="isf:InstructingAgentRole">
<Player xsi:type="isf:FinancialInstitution">
<Identification xsi:type="isf:OrganisationIdentification">
<BICFI>PBBBDEFFXXX</BICFI>
</Identification>
</Player>
</AgentRole>
<AgentRole xsi:type="isf:InstructedAgentRole">
<Player xsi:type="isf:FinancialInstitution">
<Identification xsi:type="isf:OrganisationIdentification">
<BICFI>PBAADEFFAC2</BICFI>
</Identification>
</Player>
</AgentRole>
<SettlementInstruction>
<InterbankSettlementAmount Currency="EUR">200</InterbankSettlementAmount>
<InterbankSettlementDate>2019-10-27T13:00:00.000+00:00</InterbankSettlementDate>
<PartyRole xsi:type="isf:SettlementInstructionSystemRole">
<System>
<Identification CodeIssuer="ExternalCashClearingSystem">TGT</Identification>
</System>
</PartyRole>
<SettlementMethod>CLRG</SettlementMethod>
</SettlementInstruction>
</PaymentExecution>
<PaymentObligation xsi:type="isf:ISFPaymentObligation">
<PartyRole xsi:type="isf:UltimateDebtorRole">
<Player xsi:type="isf:Party">
<Identification xsi:type="isf:OrganisationIdentification">
<PartyName>
<Name>Ultimate debtor name</Name>
</PartyName>
<AnyBIC>ULTMDBTRBIC</AnyBIC>
</Identification>
</Player>
</PartyRole>
<PartyRole xsi:type="isf:UltimateCreditorRole">
<Player xsi:type="isf:Party">
<Identification xsi:type="isf:OrganisationIdentification">
<PartyName>
<Name>Ultimate creditor name</Name>
</PartyName>
<AnyBIC>ULTMCDTRBIC</AnyBIC>
</Identification>
</Player>
</PartyRole>
</PaymentObligation>
<AlternativeTransactionIdentification>
<IdentificationIssuer>MsgId</IdentificationIssuer>
<IdentificationValue>NONREF</IdentificationValue>
</AlternativeTransactionIdentification>
<UETR>e008b020-59c5-41e9-be4c-d45102fc201e</UETR>
</isf:CreditTransfer>
<Addenda xmlns:isfa="http://www.ibm.com/xmlns/prod/ftm/isf/v3/Addenda">
<isfa:HVPAppHdr xmlns:head="urn:iso:std:iso:20022:tech:xsd:head.001.001.02">
<head:Fr xmlns:head="urn:iso:std:iso:20022:tech:xsd:head.001.001.02">
<head:FIId>
<head:FinInstnId>
<head:BICFI>TRGTXETGXXX</head:BICFI>
</head:FinInstnId>
</head:FIId>
</head:Fr>
<head:To xmlns:head="urn:iso:std:iso:20022:tech:xsd:head.001.001.02">
<head:FIId>
<head:FinInstnId>
<head:BICFI>FEUBAB20XXX</head:BICFI>
</head:FinInstnId>
</head:FIId>
</head:To>
<head:BizMsgIdr xmlns:head="urn:iso:std:iso:20022:tech:xsd:head.001.001.02">B2021012710112908008in_ct_good</head:BizMsgIdr>
<head:MsgDefIdr xmlns:head="urn:iso:std:iso:20022:tech:xsd:head.001.001.02">pacs.008.001.08</head:MsgDefIdr>
<head:CreDt xmlns:head="urn:iso:std:iso:20022:tech:xsd:head.001.001.02">2021-01-28T10:12:12</head:CreDt>
</isfa:HVPAppHdr>
</Addenda>
</isf:ISFMessage>
HVPMessageRouterOutbound
Outgoing messages to be mapped from ISF by using the HVPMessageMapperOutbound mapper are processed similar
to the ISOMessageRouterOutbound mapper. For outgoing messages, the channel parameter config value and ISF
business concept of the outgoing message are used to retrieve the <msgTypeCfg>
entry
from the value table. The channel parameter is used as the category and the ISF business concept is used to
match the <subType>
child element of <msgTypeCfg>
. The
<msgTypeCfg>
entry contains the name of the body mapper to use to map the outgoing
message. For more information, see ISOMessageRouterOutbound.
Category | Key | Configuration value |
---|---|---|
HVP_MAP_CFG_MSG_TO_TARGET2 |
defaultMsgTypeCfg |
Note: The
<name>BAH_FR_CLRSYS_MMBID</name> entry is provided by default only in the
HVP_MAP_CFG_MSG_TO_TARGET2 configuration category as a T2 requirement. |
After the mapper to be used for the body of the outgoing message is identified, HVPMessageMapperOutbound sets environment variables before the message is redirected to the body mapper. These variables are used by the body mapper to determine where in the outgoing message to begin mapping from. HVPMessageMapperOutbound also creates and populates the elements for the business application header.
HVP_MAP_CFG_MSG_TO_SCHEME
or the
<defaultMsgTypeCfg>
configuration provides some of these values.- The root element is created and a namespace is assigned by using values that are found in
<defaultMsgTypeCfg>
. The default values for the root element and namespace are<Message>
andhttp://www.ibm.com/xmlns/prod/ftm/hvp/v1
. - The
<AppHdr>
element is created. For more information about the structure and values, see Table 4. - The initial elements for the main body of the message are created. For example,
Message/Document/FIToFICstmrCdtTrf
. The body mapper places its mapped elements after these initial elements.
Path | Description | Value that is used |
---|---|---|
AppHdr/Fr/FIId/FinInstnId/BICFI |
Identifies the message sender. | The element uses the value that comes from the first available location in this list.
|
AppHdr/Fr/FIId/FinInstnId/ClrSysMmbId/MmbId |
Clearing system member identification. It is required in messages that are sent to T2. | If this value was not provided by the originating message from the channel, the element uses the
BAH_FR_CLRSYS_MMBID value that is found in the
HVP_MAP_CFG_MSG_TO_SCHEME or <defaultMsgTypeCfg>
configuration, if it exists. By default, this configuration value is only provided in the T2 configuration because population of this element is a T2
requirement only. |
AppHdr/To/FIId/FinInstnId/BICFI |
Identifies the message recipient. | The element uses the value that comes from the first available location in this list.
|
AppHdr/BizMsgIdr |
Unambiguously identifies the business message to the messaging endpoint that created the business message. | The element uses the value that comes from the first available location in this list.
|
AppHdr/MsgDefIdr |
Contains the message identifier that defines the business message. It must contain a message identifier that is published on the ISO 20022 website. | An appropriate value that is retrieved from an appropriate mapping configuration entry. Some examples
are shown in the following list.
|
AppHdr/CreDt |
Date and time that this business message (header) was created. | The element uses head.001.001.01, which requires ISONormalisedDateTime and the format
yyyy-MM-dd'T'HH:mm:ss , for the following messages.
The element uses head.001.001.02, which requires ISODateTime and the format yyyy-MM-dd'T'HH:mm:ss'Z' , for the following messages.
|
<AppHdr>
content of an outgoing message to be built by using version 1 (v1) or version 2 (v2) of the head.001 message
definition. The different schemes use different versions of the head.001 message definition. The following
scheme messages require head.001 v1.- EURO1
- Kronos2
- T2
- CBPR+
- NBO
- RIX
The outgoing message is then redirected from the Route to Label node in the HVPMessageRouterOutbound mapper to the appropriate dedicated body mapper. When the body mapper is finished, the message is redirected back to the HVPMessageRouterOutbound mapper.
Sample mapped outbound pacs.008 message to T2, including business application header content
<?xml version="1.0" encoding="UTF-8"?>
<Message xmlns="http://www.ibm.com/xmlns/prod/ftm/hvp/v1">
<AppHdr xmlns="urn:iso:std:iso:20022:tech:xsd:head.001.001.01">
<Fr>
<FIId>
<FinInstnId>
<BICFI>FEUBAB20987</BICFI>
</FinInstnId>
</FIId>
</Fr>
<To>
<FIId>
<FinInstnId>
<BICFI>HVPBEF20XXX</BICFI>
</FinInstnId>
</FIId>
</To>
<BizMsgIdr>20220715FEUBAB20XXX00000164002</BizMsgIdr>
<MsgDefIdr>pacs.008.001.08</MsgDefIdr>
<CreDt>2022-07-15T15:45:38Z</CreDt>
</AppHdr>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08">
<FIToFICstmrCdtTrf>
<GrpHdr>
<MsgId>NONREF</MsgId>
<CreDtTm>2022-07-15T15:45:38.913+00:00</CreDtTm>
<NbOfTxs>1</NbOfTxs>
<SttlmInf>
<SttlmMtd>CLRG</SttlmMtd>
<ClrSys>
<Cd>TGT</Cd>
</ClrSys>
</SttlmInf>
</GrpHdr>
<CdtTrfTxInf>
<PmtId>
<InstrId>20220715FEUBAB20XXX00000164002</InstrId>
<EndToEndId>Inp008b022-E2EId</EndToEndId>
<UETR>684692c5-59aa-411e-9d79-869c77b77d5b</UETR>
</PmtId>
<PmtTpInf>
<SvcLvl>
<Cd>SDVA</Cd>
</SvcLvl>
<LclInstrm>
<Prtry>STANDARD</Prtry>
</LclInstrm>
<CtgyPurp>
<Prtry>CONSUMER</Prtry>
</CtgyPurp>
</PmtTpInf>
<IntrBkSttlmAmt Ccy="EUR">525.25</IntrBkSttlmAmt>
<IntrBkSttlmDt>2022-07-15</IntrBkSttlmDt>
<ChrgBr>CRED</ChrgBr>
<InstgAgt>
<FinInstnId>
<BICFI>FEUBAB20XXX</BICFI>
</FinInstnId>
</InstgAgt>
<InstdAgt>
<FinInstnId>
<BICFI>TRGTXETGXXX</BICFI>
</FinInstnId>
</InstdAgt>
<Dbtr>
<Nm>ABC Corporation</Nm>
<PstlAdr>
<StrtNm>The Empire State Building, 5th Ave</StrtNm>
<BldgNb>45, Apt. 303</BldgNb>
<PstCd>NY 10118</PstCd>
<TwnNm>New York</TwnNm>
<CtrySubDvsn>NYC</CtrySubDvsn>
<Ctry>US</Ctry>
</PstlAdr>
</Dbtr>
<DbtrAcct>
<Id>
<IBAN>FE01AB2003030387654321</IBAN>
</Id>
</DbtrAcct>
<DbtrAgt>
<FinInstnId>
<BICFI>FEUBAB20987</BICFI>
</FinInstnId>
</DbtrAgt>
<CdtrAgt>
<FinInstnId>
<BICFI>HVPBEF20XXX</BICFI>
</FinInstnId>
</CdtrAgt>
<Cdtr>
<Nm>BCD Corporation</Nm>
<PstlAdr>
<StrtNm>Canal Street</StrtNm>
<PstCd>20000</PstCd>
<TwnNm>New York</TwnNm>
<CtrySubDvsn>New York</CtrySubDvsn>
<Ctry>US</Ctry>
</PstlAdr>
</Cdtr>
<CdtrAcct>
<Id>
<IBAN>DE02DEDB02020211223344</IBAN>
</Id>
</CdtrAcct>
</CdtTrfTxInf>
</FIToFICstmrCdtTrf>
</Document>
</Message>