TCH Business Application Header Mapper - (TCHMessageMapper)

Overview

The TCH Business Application Header Mappers 'TCHMessageMapperInbound' and 'TCHMessageMapperOutbound' are a pair of wrapper mappers which act as routers to message body mappers, for incoming and outgoing messages that incorporate TCH (The Clearing House) specification Business Application Header ccontent. These messages consist of a head.001 formatted outer envelope that contains the Business Application Header data, and a main body nested within the head.001 content. The body contains the main payload of the message and can have a range of formats, though typically pacs.002, or pacs.008.

A message that requires mapping arrives in the TCH Message Mapper, 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 mapper to map the body of the document before returning to the TCH Message Mapper. Differing from the ISOMessageRouters, the inbound and outbound TCHMessageMappers are also responsible for processing the TCH Business Application Header elements, as described in the following sections.

Several channels can be configured to use the same TCH Message Mapper, as it delegates body mapping to dedicated mappers dynamically, based on the message type and content received.

Note: The TCH Message Mappers are usually used in the following channels to map the ISO message containing TCH Business Application Header(head.001.001.01) to ISF message, or vice versa.

Request/Response from CSM
System Notification From CSM
Request/Response to CSM

TCHMessageMapperInbound

Incoming messages to be mapped to ISF using TCHMessageMapperInbound are processed in the following manner. Message type is determined by examining the second child underneath the root 'Message' element,

'CreditTransfer' indicating a pacs.008.* message
'FICreditTransfer' indicating a pacs.009.* message
'MessageStatusReport' indicating a pacs.002.* message
PaymentStatusRequest' indicating a pacs.028.* message
'ReturnOfFunds' indicating a camt.056.* message
'Acknowledgement' indicating a camt.035.* message
'ResponseRequestForInformation' indicating a camt.028.* message
'RequestForInformation' indicating a camt.026.* message
'PaymentRequest' indicating a pain.013.* message
'ResponsePaymentRequest' indicating a pain.014.* message
ResponseReturnOfFunds' indicating a camt.029.* message
'StandaloneRemittance' indicating a remt.001.* message
'SystemNotificationEvent' indicating an admi.004.* message
'MessageReject' indicating an admi.002.* message
'SignOnResponse' indicating an admn.002.* message
'SignOffResponse' indicating an admn.004.* message
'ParticipantReportResponse' indicating an admn.008.* message
'TokenIdentification' indicating an acmt.022.* message

The CONFIG=entry that is stored as a channel parameter, and the identified message type is used to retrieve the <msgTypeCfg> entry in Value table. The <msgTypeCfg> entry contains the body mapper to be used to map the received message.

The Request From CSM channel might be configured to use the TCHMessageMapperInbound mapper, with a CONFIG=IP_MAP_CFG_REQ_FROM_CSM parameter. When a pacs.008.001.06 message is received from the channel, TCHMessageMapperInbound determines that it is a pacs.008.* message from the CreditTransfer element, and the channel parameters provide the config value IP_MAP_CFG_REQ_FROM_CSM. Each <msgTypeCfg> entry with category IP_MAP_CFG_REQ_FROM_CSM in Value table is examined, and when a configuration value is found with a <type> matching "pacs.008.*", the mapper Pacs008ToISFMapper identified in the child element <mapName> will be used to map the received message.

If a <msgTypeCfg> entry with a matching <type> value is not found, an exception with error "Mapper not found" is thrown.

Table 1. Sample configuration value table entries
Category	Key	Configuration value
IP_MAP_CFG_REQ_FROM_CSM	msgTypeCfg_pacs.008	`<msgTypeCfg> <class>PACS008</class> <subType>IP_FROM_CSM_INSTR</subType> <extendedCfg> <name>MASTER_FLAG</name> <value>Y</value> </extendedCfg> <pt> <class>PACS008</class> <subType>IP_FROM_CSM_INSTR</subType> </pt> <mapName>Pacs008ToISFMapper</mapName> <type>pacs.008.*</type> </msgTypeCfg>` Note: <type> element matches, with <mapName> element identifying correct mapper.
IP_MAP_CFG_REQ_FROM_CSM	msgTypeCfg_pacs.002	`<msgTypeCfg> <class>PACS002</class> <subType>IP_FROM_CSM_PSTAT</subType> <extendedCfg> <name>MASTER_FLAG</name> <value>N</value> </extendedCfg> <pt> <class>PACS002</class> <subType>IP_FROM_CSM_PSTAT</subType> </pt> <mapName>Pacs002ToISFMapper</mapName> <type>pacs.002.*</type> </msgTypeCfg>`
IP_MAP_CFG_REQ_FROM_CSM	msgTypeCfg_camt.056	`<msgTypeCfg> <class>CAMT056</class> <subType>IP_FROM_CSM_RCL</subType> <extendedCfg> <name>MASTER_FLAG</name> <value>Y</value> </extendedCfg> <pt> <class>CAMT056</class> <subType>IP_FROM_CSM_RCL</subType> </pt> <mapName>Camt056ToISFMapper</mapName> <type>camt.056.*</type> </msgTypeCfg>`
IP_MAP_CFG_REQ_FROM_CSM	msgTypeCfg_camt.035	`<msgTypeCfg> <class>CAMT035</class> <subType>IP_FROM_CDTR_PACK</subType> <extendedCfg> <name>MASTER_FLAG</name> <value>Y</value> </extendedCfg> <pt> <class>CAMT035</class> <subType>IP_FROM_CDTR_PACK</subType> </pt> <mapName>Camt035ToISFMapper</mapName> <type>camt.035.*</type> </msgTypeCfg>`

When the mapper to use for the body of the incoming message is identified, TCHMessageMapperInbound sets environment variables that are used by the upcoming body mapper to determine where to begin mapping from in the incoming message.

The incoming message is then redirected to the appropriate dedicated body mapper via the Route to Label node in TCHMessageMapperInbound. Then, it is redirected back to TCHMessageMapperInbound when the body mapper is finished.

Upon returning from the body mapper, TCHMessageMapperInbound adds an addendum to the now mapped ISF message. The entire app header structure from the original message is appended to the now mapped ISF as a last child under 'addenda'.

Inbound TCH Message wrapper:

Example inbound ISO mapper:

Sample Mapped Inbound Message including Addenda

<isf:ISFMessage xmlns:isf="http://www.ibm.com/xmlns/prod/ftm/isf/v3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<Header>
		<BusinessConcept>IP_FROM_CSM_INSTR</BusinessConcept>
		<TransactionRef>TxPrefix....20160513223041395000014</TransactionRef>
		<MessageName>pacs.008.001.06</MessageName>
		<Sender>021200201</Sender>
		<Receiver>020010001</Receiver>
	</Header>
	<isf:CreditTransfer>
		<ChargeBearer>SLEV</ChargeBearer>
		<EndToEndIdentification>E2E-TxPrefix20160513223041395000014</EndToEndIdentification>
		<PartyRole xsi:type="isf:DebtorRole">
			<Player xsi:type="isf:Person">
				<ContactPoint xsi:type="isf:ISFPostalAddress">
					<Country>
						<Code>UK</Code>
					</Country>
					<PostCodeIdentification>10000</PostCodeIdentification>
					<StreetName>22 Heron Drive</StreetName>
					<TownName>London</TownName>
				</ContactPoint>
				<Identification xsi:type="isf:PersonIdentification">
					<PartyName>
						<Name>Mr Debtor 1</Name>
					</PartyName>
				</Identification>
				<BirthDate>1969-06-28T00:00:00+01:00</BirthDate>
				<PlaceOfBirth>
					<Address>
						<Country>
							<Code>US</Code>
						</Country>
						<TownName>City</TownName>
					</Address>
				</PlaceOfBirth>
			</Player>
			<CashAccount>
				<Identification>
					<ProprietaryIdentification xsi:type="isf:GenericIdentification">
						<Identification>GR3001720810005081023929510</Identification>
					</ProprietaryIdentification>
				</Identification>
			</CashAccount>
		</PartyRole>
		<PartyRole xsi:type="isf:DebtorAgentRole">
			<Player xsi:type="isf:FinancialInstitution">
				<Identification xsi:type="isf:OrganisationIdentification">
					<OtherIdentification xsi:type="isf:GenericIdentification">
						<Identification>021200201</Identification>
					</OtherIdentification>
				</Identification>
			</Player>
		</PartyRole>
		<PartyRole xsi:type="isf:CreditorAgentRole">
			<Player xsi:type="isf:FinancialInstitution">
				<Identification xsi:type="isf:OrganisationIdentification">
					<OtherIdentification xsi:type="isf:GenericIdentification">
						<Identification>020010001</Identification>
					</OtherIdentification>
				</Identification>
			</Player>
		</PartyRole>
		<PartyRole xsi:type="isf:CreditorRole">
			<Player xsi:type="isf:Person">
				<ContactPoint xsi:type="isf:ISFPostalAddress">
					<Country>
						<Code>US</Code>
					</Country>
					<PostCodeIdentification>20000</PostCodeIdentification>
					<StreetName>Canal Street</StreetName>
					<TownName>New York</TownName>
				</ContactPoint>
				<Identification xsi:type="isf:PersonIdentification">
					<PartyName>
						<Name>Mr Creditor 1</Name>
					</PartyName>
				</Identification>
				<BirthDate>1969-06-28T00:00:00+01:00</BirthDate>
				<PlaceOfBirth>
					<Address>
						<Country>
							<Code>US</Code>
						</Country>
						<TownName>City</TownName>
					</Address>
				</PlaceOfBirth>
			</Player>
			<CashAccount>
				<Identification>
					<ProprietaryIdentification xsi:type="isf:GenericIdentification">
						<Identification>GR3001720810005081023929510</Identification>
					</ProprietaryIdentification>
				</Identification>
			</CashAccount>
		</PartyRole>
		<PaymentExecution xsi:type="isf:ISFPaymentInstruction">
			<CreationDate>2016-05-14T03:30:41.000+00:00</CreationDate>
			<Identification>20160516021200201BFFF0000000014</Identification>
			<ProcessingInstructions>
				<LocalInstrument>CONSUMER</LocalInstrument>
				<ServiceLevel>
					<ServiceLevel CodeIssuer="ExternalServiceLevel">SDVA</ServiceLevel>
				</ServiceLevel>
			</ProcessingInstructions>
			<AgentRole xsi:type="isf:InstructingAgentRole">
				<Player xsi:type="isf:FinancialInstitution">
					<Identification xsi:type="isf:OrganisationIdentification">
						<OtherIdentification xsi:type="isf:GenericIdentification">
							<Identification>021200201</Identification>
						</OtherIdentification>
					</Identification>
				</Player>
			</AgentRole>
			<AgentRole xsi:type="isf:InstructedAgentRole">
				<Player xsi:type="isf:FinancialInstitution">
					<Identification xsi:type="isf:OrganisationIdentification">
						<OtherIdentification xsi:type="isf:GenericIdentification">
							<Identification>020010001</Identification>
						</OtherIdentification>
					</Identification>
				</Player>
			</AgentRole>
			<ClearingSystemReference>001</ClearingSystemReference>
			<SettlementInstruction>
				<InterbankSettlementAmount Currency="USD">432.1</InterbankSettlementAmount>
				<InterbankSettlementDate>2016-05-13T00:00:00</InterbankSettlementDate>
				<PartyRole xsi:type="isf:SettlementInstructionSystemRole">
					<System>
						<Identification CodeIssuer="ExternalCashClearingSystem">TCH</Identification>
					</System>
				</PartyRole>
				<SettlementMethod>CLRG</SettlementMethod>
			</SettlementInstruction>
		</PaymentExecution>
		<PaymentObligation xsi:type="isf:ISFPaymentObligation">
			<AssociatedDocument xsi:type="isf:Document">
				<ContentDescription>Company Details No.2</ContentDescription>
			</AssociatedDocument>
		</PaymentObligation>
		<AlternativeTransactionIdentification>
			<IdentificationIssuer>MsgId</IdentificationIssuer>
			<IdentificationValue>MsgPrefix...20160513223041000000014</IdentificationValue>
		</AlternativeTransactionIdentification>
		<TransactionIdentification>TxPrefix....20160513223041395000014</TransactionIdentification>
	</isf:CreditTransfer>
	<Addenda xmlns:isfa="http://www.ibm.com/xmlns/prod/ftm/isf/v3/Addenda">
		<isfa:TCHAppHdr>
			<head:Fr xmlns:head="urn:iso:std:iso:20022:tech:xsd:head.001.001.01">
				<head:FIId>
					<head:FinInstnId>
						<head:ClrSysMmbId>
							<head:MmbId>021200201A1</head:MmbId>
						</head:ClrSysMmbId>
					</head:FinInstnId>
				</head:FIId>
			</head:Fr>
			<head:To xmlns:head="urn:iso:std:iso:20022:tech:xsd:head.001.001.01">
				<head:FIId>
					<head:FinInstnId>
						<head:ClrSysMmbId>
							<head:MmbId>990000001S1</head:MmbId>
						</head:ClrSysMmbId>
					</head:FinInstnId>
				</head:FIId>
			</head:To>
			<head:BizMsgIdr xmlns:head="urn:iso:std:iso:20022:tech:xsd:head.001.001.01">B20151112020010001A1BRR0000000001</head:BizMsgIdr>
			<head:MsgDefIdr xmlns:head="urn:iso:std:iso:20022:tech:xsd:head.001.001.01">pacs.008.001.06</head:MsgDefIdr>
			<head:CreDt xmlns:head="urn:iso:std:iso:20022:tech:xsd:head.001.001.01">2015-11-12T16:45:00</head:CreDt>
			<head:Sgntr xmlns:head="urn:iso:std:iso:20022:tech:xsd:head.001.001.01">
				<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
					<SignedInfo>
						<CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
						<SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
						<Reference URI="">
							<Transforms>
								<Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
							</Transforms>
							<DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
							<DigestValue>xJYUUSPUn1jjbUtiXivnfYY1bwoVCwG5KXzMFLTbVa8=</DigestValue>
						</Reference>
					</SignedInfo>
					<SignatureValue>ZpV+Cq6QibGeDsstQnDx7/+mB181N+QCkqcODCl1E8Q5WRzcmloyWBwfYpbLdQVaR2SCK/4Aqh5LaSHgB2VIwg3w4tpHyfGWaLSEG6tKkg/mGJC0QTr8sdrm2HyRIUO1AgjlnwS7g0uPSP56SN0QVN8ZxWI/674iHucB+9mNjug=</SignatureValue>
					<KeyInfo>
						<X509Data>
							<X509IssuerSerial>
								<X509IssuerName>CN=rsa0, OU=ips, O=vocalink, L=rickmansworth, ST=Unknown, C=uk
								</X509IssuerName>
								<X509SerialNumber>1329834379</X509SerialNumber>
							</X509IssuerSerial>
							<X509SubjectName>CN=rsa2,OU=ips,O=vocalink,L=rickmansworth,ST=Unknown,C=uk
							</X509SubjectName>
						</X509Data>
					</KeyInfo>
				</Signature>
			</head:Sgntr>
		</isfa:TCHAppHdr>
	</Addenda>
</isf:ISFMessage>

TCHMessageMapperOutbound

Outgoing messages to be mapped from ISF using TCHMessageMapperOutbound are processed in a manner similar to that of ISOMessageRouterOutbound. Namely, identifying the correct body mapper for the outgoing message by using the channel configuration parameter as category to identify a selection of <msgTypeCfg> entries in Value table, and then using the ISF Business Concept to identify a specific entry by matching it to the <subtype> element, which also gives the body mapper name. This is demonstrated in more detail in the ISOMessageRouterOutbound section.

When the body mapper is identified, environment variables are set which are used by the upcoming body mapper to determine where to begin mapping from in the outgoing message.

TCHMessageMapperOutbound is also responsible for creating and populating elements for the TCH required Business Application Header.

Before being routed to the dedicated body mapper, parts of the mapped document are created. Included are app header elements under Message/AppHdr, and the initial elements under which the dedicated body mapper place mapped elements. For example, Message/MessageStatusReport/FIToFIPmtStsRpt.

Table 2. TCH Business Application Header elements
Path	Description	Note
AppHdr/Fr/FIId/FinInstnId/ClrSysMmbId/MmbId	For identifying the sender of the message.	Value that is populated from Addenda/TCHAppHdr/Fr/FIId/FinInstnId/ClrSysMmbId/MmbId if present. Otherwise, the value is populated from value table entry that is found by using 'IP_CONFIG'/'IP_BANK_PART_ID' as category/key.
AppHdr/To/FIId/FinInstnId/ClrSysMmbId/MmbId	Identification of a member of a clearing system.	Value that is populated from Addenda/TCHAppHdr/To/FIId/FinInstnId/ClrSysMmbId/MmbId if present. Otherwise, the value is populated from value table entry found by using 'IP_CONFIG'/'IP_TCH_PART_ID' as category/key.
AppHdr/BizMsgIdr	Unambiguously identifies the Business Message to the Messaging Endpoint that created the Business Message.	When mapping to pacs.008.* or pacs.009., populate from ISFMessage/CreditTransfer/AlternativeTransactionIdentification/IdentificationValue When mapping to pacs.002., pain.014., admi.002., or acmt.022., populate from ISFMessage/Acknowledgement/GeneralInformation/StatusMessageIdentification When mapping to camt.026., camt.028., camt.035., or pacs.028., populate from ISFMessage/CreditInvestigation/GeneralInformation/StatusMessageIdentification When mapping to camt.056. or camt.029., populate from ISFMessage/CreditInvestigation/Case/AssignmentIdentification When mapping to pain.013. or remt.001., populate from ISFMessage/Transaction/AlternativeTransactionIdentification/IdentificationValue When mapping to admn.001., populate from ISFMessage/Addenda/SourceData/MessageData/AdmnSignOnReq/GrpHdr/MsgId When mapping to admn.003.*, populate from ISFMessage/Addenda/SourceData/MessageData/AdmnSignOffReq/GrpHdr/MsgId With leading 'M' character changed to 'B' per TCH requirement.
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.	One of the following value: pacs.008.001.06 pacs.008.001.08 pacs.009.001.08 pacs.002.001.07 pacs.002.001.10 pacs.028.001.08 camt.026.001.05 camt.026.001.07 camt.028.001.06 camt.028.001.09 camt.029.001.06 camt.029.001.09 camt.035.001.03 camt.035.001.05 camt.056.001.05 camt.056.001.08 pain.013.001.05 pain.013.001.07 pain.014.001.05 pain.014.001.07 remt.001.001.02 acmt.022.001.02 admi.002.001.01 admn.001.001.01 admn.003.001.01
AppHdr/CreDt	Date and time when this Business Message (header) was created.	ET time zone that uses the format `yyyy-MM-dd''T''HH:mm:ss`.
AppHdr/CpyDplct	Indicates whether the message is a Copy, a Duplicate, or a copy of a duplicate of a previously sent ISO 20022 Message.	Value 'DUPL' if ISFMessage/Header/BusinessConcept ends in '_RPT'.

The outgoing message is then redirected to the appropriate dedicated body mapper via the Route to Label node in TCHMessageMapperOutbound, returning by the same mechanism when the body mapper is finished.

Outbound TCH Message wrapper:

TCHMessageMapperOutbound.subflow diagram

Example outbound ISO mapper:

Sample Mapped Outbound Message including BAH

<?xml version="1.0" encoding="UTF-8"?>
<NS1:Message xmlns:NS1="urn:tch">
	<NS1:AppHdr>
		<NS2:Fr xmlns:NS2="urn:iso:std:iso:20022:tech:xsd:head.001.001.01">
			<NS2:FIId>
				<NS2:FinInstnId>
					<NS2:ClrSysMmbId>
						<NS2:MmbId>990000001S1</NS2:MmbId>
					</NS2:ClrSysMmbId>
				</NS2:FinInstnId>
			</NS2:FIId>
		</NS2:Fr>
		<NS3:To xmlns:NS3="urn:iso:std:iso:20022:tech:xsd:head.001.001.01">
			<NS3:FIId>
				<NS3:FinInstnId>
					<NS3:ClrSysMmbId>
						<NS3:MmbId>021200201A1</NS3:MmbId>
					</NS3:ClrSysMmbId>
				</NS3:FinInstnId>
			</NS3:FIId>
		</NS3:To>
		<NS4:BizMsgIdr xmlns:NS4="urn:iso:std:iso:20022:tech:xsd:head.001.001.01">B20161207020010001ABBRRR00000959001</NS4:BizMsgIdr>
		<NS5:MsgDefIdr xmlns:NS5="urn:iso:std:iso:20022:tech:xsd:head.001.001.01">pacs.002.001.07</NS5:MsgDefIdr>
		<NS6:CreDt xmlns:NS6="urn:iso:std:iso:20022:tech:xsd:head.001.001.01">2016-12-07T05:51:17</NS6:CreDt>
	</NS1:AppHdr>
	<NS1:ResponseCreditTransfer xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<NS7:FIToFIPmtStsRpt xmlns:NS7="urn:iso:std:iso:20022:tech:xsd:pacs.002.001.07">
			<NS7:GrpHdr>
				<NS7:MsgId>M20161207020010001ABBRRR00000959001</NS7:MsgId>
				<NS7:CreDtTm>2016-12-07T05:51:17</NS7:CreDtTm>
			</NS7:GrpHdr>
			<NS7:OrgnlGrpInfAndSts>
				<NS7:OrgnlMsgId>MsgPrefix...20160513223041000000014</NS7:OrgnlMsgId>
				<NS7:OrgnlMsgNmId>pacs.008.001.06</NS7:OrgnlMsgNmId>
				<NS7:OrgnlCreDtTm>2016-05-13T22:30:41</NS7:OrgnlCreDtTm>
				<NS7:OrgnlNbOfTxs>1</NS7:OrgnlNbOfTxs>
			</NS7:OrgnlGrpInfAndSts>
			<NS7:TxInfAndSts>
				<NS7:OrgnlInstrId>20160516021200201BFFF0000000014</NS7:OrgnlInstrId>
				<NS7:OrgnlTxId>TxPrefix....20160513223041395000014</NS7:OrgnlTxId>
				<NS7:TxSts>ACTC</NS7:TxSts>
				<NS7:AccptncDtTm>2016-12-07T05:51:17</NS7:AccptncDtTm>
				<NS7:ClrSysRef>001</NS7:ClrSysRef>
				<NS7:InstgAgt>
					<NS7:FinInstnId>
						<NS7:ClrSysMmbId>
							<NS7:MmbId>020010001</NS7:MmbId>
						</NS7:ClrSysMmbId>
					</NS7:FinInstnId>
				</NS7:InstgAgt>
				<NS7:InstdAgt>
					<NS7:FinInstnId>
						<NS7:ClrSysMmbId>
							<NS7:MmbId>021200201</NS7:MmbId>
						</NS7:ClrSysMmbId>
					</NS7:FinInstnId>
				</NS7:InstdAgt>
				<NS7:OrgnlTxRef>
					<NS7:IntrBkSttlmAmt Ccy="USD">432.1</NS7:IntrBkSttlmAmt>
					<NS7:IntrBkSttlmDt>2016-05-13</NS7:IntrBkSttlmDt>
				</NS7:OrgnlTxRef>
			</NS7:TxInfAndSts>
		</NS7:FIToFIPmtStsRpt>
	</NS1:ResponseCreditTransfer>
</NS1:Message>