Summary Mapping
Summaries are "projections" of a unit of work, and are based on data received by ODS. They represent the current state of a unit of work, and can be searched by a number of different fields.
This data is "mapped" into pre-defined summary fields, and by extension, some indexed search fields, via combination of core, default, and custom mappings.
-
Core mappings are usually essential for ODS functionality, and they cannot be overridden or customised.
-
Default mappings are those provided by ODS out-of-the-box, and they apply to ISO20022 MDS types and PDS types.
-
Custom mappings are solution specific, and they can override default mappings.
| Source Data | Core Mappings | Default Mappings | Customisable |
|---|---|---|---|
ISO20022 MDS |
Yes |
Yes |
Yes |
IPF PDS |
Yes |
Yes |
Yes |
Custom PDS |
No |
No |
Yes |
IPF Processing Data |
Yes |
No |
No |
Both MDS/PDS mappings have defaults and custom mappings.
Core Mappings
ISO20022 MDS
| Field Name | Source | Notes | Sequence |
|---|---|---|---|
instructionReceivedAt |
pain.001 (source event timestamp) pacs.008 (source event timestamp) pacs.004 (source event timestamp) camt.029 ( camt.056 ( |
Populated on receipt of each message |
Earliest |
executionStartedAt |
pacs.008 (source event timestamp) |
Populated on receipt of each message |
Earliest |
settlementCompletedAt |
pacs.002 (source event timestamp) |
Populated on receipt of each message |
Latest |
IPF PDS
| Field Name | Source | Sequence |
|---|---|---|
journeyType |
|
Always updates if there’s a change |
paymentType |
|
Latest |
csm |
|
Latest |
timeZone |
|
Latest |
priority |
|
Latest |
relatedUnitOfWorkId |
|
Always updates if there’s a change, but shouldn’t change over the lifetime of a unit of work |
Process Flow Event
| Field Name | Source | Sequence | Notes |
|---|---|---|---|
journeyType |
|
Always updates if there’s a change |
Deprecated |
paymentType |
|
Latest |
Deprecated |
csm |
|
Latest |
Deprecated |
timeZone |
|
Latest |
Deprecated |
priority |
|
Latest |
Deprecated |
relatedUnitOfWorkId |
|
Always updates if there’s a change, but shouldn’t change over the lifetime of a unit of work |
Deprecated |
reasonText |
|
Latest |
|
reasonCode |
|
Latest |
|
startedAt |
|
Earliest |
Typically the timestamp of the first event |
terminal |
|
Latest |
Looks up the process flow status from process flow definitions to determine if the state change is terminal |
failure |
|
Latest |
Looks up the process flow status from process flow definitions to determine if the state change is a failure |
Default Mappings
| Summary Field | Sources |
|---|---|
acceptanceDateTime |
CreditTransferTransaction{pain.001.001.09}@[/accptncDtTm] CreditTransferTransaction{pacs.008.001.08}@[/accptncDtTm] |
batchBooking |
PaymentInstruction{pain.001.001.09}@[/btchBookg] |
cancellationId |
PaymentTransaction{camt.056.001.08}@[/cxlId] |
chargeAmount |
PaymentTransaction{pacs.004.001.09}@[/chrgsInf/0/amt/value] |
chargeAmountCurrency |
PaymentTransaction{pacs.004.001.09}@[/chrgsInf/0/amt/ccy] |
controlSum |
CustomerCreditTransferInitiation{pain.001.001.09}@[/grpHdr/ctrlSum] PaymentInstruction{pain.001.001.09}@[/ctrlSum] |
convertedTransactionAmount |
Fx@[/convertedCurrencyAndAmount/value] |
convertedTransactionAmountCurrency |
Fx@[/convertedCurrencyAndAmount/ccy] |
creditAccount |
AccountNotification{camt.054.001.10}@[/acct/id/othr/id or /acct/prxy/id or /acct/id/iban] when @[/ntry/0/cdtDbtInd] == "CRDT" |
creditAmount |
AccountNotification{camt.054.001.10}@[/ntry/0/ntryDtls/0/txDtls/0/amtDtls/anncdPstngAmt/amt/value] when @[/ntry/0/cdtDbtInd] == "CRDT" |
creditAmountCurrency |
AccountNotification{camt.054.001.10}@[/ntry/0/ntryDtls/0/txDtls/0/amtDtls/anncdPstngAmt/amt/ccy] when @[/ntry/0/cdtDbtInd] == "CRDT" |
creditorAccount |
CreditTransferTransaction{pain.001.001.09}@[/cdtrAcct/id/iban or /cdtrAcct/id/othr/id] CreditTransferTransaction{pacs.008.001.08}@[/cdtrAcct/id/iban or /cdtrAcct/id/othr/id] PaymentTransaction{pacs.004.001.09}@[/orgnlTxRef/cdtrAcct/id/iban or /orgnlTxRef/cdtrAcct/id/othr/id] PaymentTransaction{camt.029.001.09}@[/orgnlTxRef/cdtrAcct/id/iban or /orgnlTxRef/cdtrAcct/id/othr/id] PaymentTransaction{camt.056.001.08}@[/orgnlTxRef/cdtrAcct/id/iban or /orgnlTxRef/cdtrAcct/id/othr/id] RequestToModifyPayment{camt.087.001.06}@[/mod/cdtrAcct/id/iban or /mod/cdtrAcct/id/othr/id] |
creditorAgentBIC |
CreditTransferTransaction{pain.001.001.09}@[/cdtrAgt/finInstnId/bicfi] CreditTransferTransaction{pacs.008.001.08}@[/cdtrAgt/finInstnId/bicfi] PaymentTransaction{pacs.004.001.09}@[/orgnlTxRef/cdtrAgt/finInstnId/bicfi] PaymentTransaction{camt.029.001.09}@[/orgnlTxRef/cdtrAgt/finInstnId/bicfi] PaymentTransaction{camt.056.001.08}@[/orgnlTxRef/cdtrAgt/finInstnId/bicfi] |
creditorBIC |
CreditTransferTransaction{pain.001.001.09}@[/cdtr/id/orgId/anyBIC] CreditTransferTransaction{pacs.008.001.08}@[/cdtr/id/orgId/anyBIC] RequestToModifyPayment{camt.087.001.06}@[/mod/cdtr/id/orgId/anyBIC] |
creditorName |
CreditTransferTransaction{pain.001.001.09}@[/cdtr/nm] CreditTransferTransaction{pacs.008.001.08}@[/cdtr/nm] PaymentTransaction{pacs.004.001.09}@[/orgnlTxRef/cdtr/pty/nm] PaymentTransaction{camt.029.001.09}@[/orgnlTxRef/cdtr/pty/nm] PaymentTransaction{camt.056.001.08}@[/orgnlTxRef/cdtr/pty/nm] RequestToModifyPayment{camt.087.001.06}@[/mod/cdtr/nm] |
csm |
Csm@[/value] |
debitAccount |
AccountNotification{camt.054.001.10}@[/acct/id/othr/id or /acct/prxy/id or /acct/id/iban] when @[/ntry/0/cdtDbtInd] == "DBIT" |
debitAmount |
AccountNotification{camt.054.001.10}@[/ntry/0/ntryDtls/0/txDtls/0/amtDtls/anncdPstngAmt/amt/value] when @[/ntry/0/cdtDbtInd] == "DBIT" |
debitAmountCurrency |
AccountNotification{camt.054.001.10}@[/ntry/0/ntryDtls/0/txDtls/0/amtDtls/anncdPstngAmt/amt/ccy] when @[/ntry/0/cdtDbtInd] == "DBIT" |
debtorAccount |
CreditTransferTransaction{pain.001.001.09}@[/dbtrAcct/id/iban or /dbtrAcct/id/othr/id] PaymentInstruction{pain.001.001.09}@[/dbtrAcct/id/iban or /dbtrAcct/id/othr/id] CreditTransferTransaction{pacs.008.001.08}@[/dbtrAcct/id/iban or /dbtrAcct/id/othr/id] PaymentTransaction{pacs.004.001.09}@[/orgnlTxRef/dbtrAcct/id/iban or /orgnlTxRef/dbtrAcct/id/othr/id] PaymentTransaction{camt.029.001.09}@[/orgnlTxRef/dbtrAcct/id/iban or /orgnlTxRef/dbtrAcct/id/othr/id] PaymentTransaction{camt.056.001.08}@[/orgnlTxRef/dbtrAcct/id/iban or /orgnlTxRef/dbtrAcct/id/othr/id] RequestToModifyPayment{camt.087.001.06}@[/mod/dbtrAcct/id/iban or /mod/dbtrAcct/id/othr/id] |
debtorAgentBIC |
CreditTransferTransaction{pain.001.001.09}@[/dbtrAgt/finInstnId/bicfi] PaymentInstruction{pain.001.001.09}@[/dbtrAgt/finInstnId/bicfi] CreditTransferTransaction{pacs.008.001.08}@[/dbtrAgt/finInstnId/bicfi] PaymentTransaction{pacs.004.001.09}@[/orgnlTxRef/dbtrAgt/finInstnId/bicfi] PaymentTransaction{camt.029.001.09}@[/orgnlTxRef/dbtrAgt/finInstnId/bicfi] PaymentTransaction{camt.056.001.08}@[/orgnlTxRef/dbtrAgt/finInstnId/bicfi] |
debtorBIC |
CreditTransferTransaction{pain.001.001.09}@[/dbtr/id/orgId/anyBIC] PaymentInstruction{pain.001.001.09}@[/dbtr/id/orgId/anyBIC] CreditTransferTransaction{pacs.008.001.08}@[/dbtr/id/orgId/anyBIC] RequestToModifyPayment{camt.087.001.06}@[/mod/dbtr/id/orgId/anyBIC] |
debtorName |
CreditTransferTransaction{pain.001.001.09}@[/dbtr/nm] PaymentInstruction{pain.001.001.09}@[/dbtr/nm or /dbtrAcct/nm] CreditTransferTransaction{pacs.008.001.08}@[/dbtr/nm] PaymentTransaction{pacs.004.001.09}@[/orgnlTxRef/dbtr/pty/nm] PaymentTransaction{camt.029.001.09}@[/orgnlTxRef/dbtr/pty/nm] PaymentTransaction{camt.056.001.08}@[/orgnlTxRef/dbtr/pty/nm] RequestToModifyPayment{camt.087.001.06}@[/mod/dbtr/nm] |
exchangeRate |
Fx@[/exchangeRate] |
initiatingPartyName |
CustomerCreditTransferInitiation{pain.001.001.09}@[/grpHdr/initgPty/nm] |
instructedAgent |
FIToFICustomerCreditTransfer{pacs.008.001.08}@[/grpHdr/instdAgt/finInstnId/bicfi] PaymentReturn{pacs.004.001.09}@[/grpHdr/instdAgt/finInstnId/bicfi] PaymentTransaction{pacs.004.001.09}@[/instdAgt/finInstnId/bicfi] |
instructedAmount |
CreditTransferTransaction{pain.001.001.09}@[/amt/instdAmt/value] CreditTransferTransaction{pacs.008.001.08}@[/amt/instdAmt/value] AccountNotification{camt.054.001.10}@[/ntry/0/ntryDtls/0/txDtls/0/amtDtls/instdAmt/amt/value] RequestToModifyPayment{camt.087.001.06}@[/mod/amt/instdAmt/value] |
instructedAmountCurrency |
CreditTransferTransaction{pain.001.001.09}@[/amt/instdAmt/ccy] CreditTransferTransaction{pacs.008.001.08}@[/amt/instdAmt/ccy] AccountNotification{camt.054.001.10}@[/ntry/0/ntryDtls/0/txDtls/0/amtDtls/instdAmt/amt/ccy] RequestToModifyPayment{camt.087.001.06}@[/mod/amt/instdAmt/ccy] |
instructedParty |
FIToFIPaymentCancellationRequest{camt.056.001.08}@[/assgnmt/assgne/agt/finInstnId/bicfi or /assgnmt/assgne/agt/finInstnId/lei or /assgnmt/assgne/agt/finInstnId/nm or /assgnmt/assgne/pty/id/orgId/anyBIC] |
instructingAgent |
FIToFICustomerCreditTransfer{pacs.008.001.08}@[/grpHdr/instgAgt/finInstnId/bicfi] PaymentReturn{pacs.004.001.09}@[/grpHdr/instgAgt/finInstnId/bicfi] PaymentTransaction{pacs.004.001.09}@[/instgAgt/finInstnId/bicfi] |
instructingParty |
FIToFIPaymentCancellationRequest{camt.056.001.08}@[/assgnmt/assgnr/agt/finInstnId/bicfi or /assgnmt/assgnr/agt/finInstnId/lei or /assgnmt/assgnr/agt/finInstnId/nm or /assgnmt/assgnr/pty/id/orgId/anyBIC] |
instructionId |
CreditTransferTransaction{pain.001.001.09}@[/pmtId/instrId] CreditTransferTransaction{pacs.008.001.08}@[/pmtId/instrId] RequestToModifyPayment{camt.087.001.06}@[/mod/instrId] |
interbankSettlementDate |
CreditTransferTransaction{pain.001.001.09}@[/intrBkSttlmDt] FIToFICustomerCreditTransfer{pacs.008.001.08}@[/grpHdr/intrBkSttlmDt] CreditTransferTransaction{pacs.008.001.08}@[/intrBkSttlmDt] PaymentReturn{pacs.004.001.09}@[/grpHdr/intrBkSttlmDt] RequestToModifyPayment{camt.087.001.06}@[/mod/intrBkSttlmDt] |
journeyType |
JourneyType@[/value] |
messageId |
CustomerCreditTransferInitiation{pain.001.001.09}@[/grpHdr/msgId] FIToFICustomerCreditTransfer{pacs.008.001.08}@[/grpHdr/msgId] PaymentReturn{pacs.004.001.09}@[/grpHdr/msgId] |
numberOfTransactions |
CustomerCreditTransferInitiation{pain.001.001.09}@[/grpHdr/nbOfTxs] PaymentInstruction{pain.001.001.09}@[/nbOfTxs] FIToFICustomerCreditTransfer{pacs.008.001.08}@[/grpHdr/nbOfTxs] |
originalEndToEndId |
PaymentTransaction{pacs.004.001.09}@[/orgnlEndToEndId] PaymentTransaction{camt.029.001.09}@[/orgnlEndToEndId] PaymentTransaction{camt.056.001.08}@[/orgnlEndToEndId] RequestToModifyPayment{camt.087.001.06}@[/undrlyg/initn/orgnlEndToEndId or /undrlyg/intrBk/orgnlEndToEndId] |
originalInstructionId |
PaymentTransaction{pacs.004.001.09}@[/orgnlInstrId] PaymentTransaction{camt.029.001.09}@[/orgnlInstrId] PaymentTransaction{camt.056.001.08}@[/orgnlInstrId] RequestToModifyPayment{camt.087.001.06}@[/undrlyg/initn/orgnlInstrId or /undrlyg/intrBk/orgnlInstrId] |
originalInterbankSettlementDate |
PaymentTransaction{pacs.004.001.09}@[/orgnlTxRef/intrBkSttlmDt or /orgnlIntrBkSttlmDt] PaymentTransaction{camt.029.001.09}@[/orgnlTxRef/intrBkSttlmDt or /orgnlIntrBkSttlmDt] PaymentTransaction{camt.056.001.08}@[/orgnlTxRef/intrBkSttlmDt or /orgnlIntrBkSttlmDt] RequestToModifyPayment{camt.087.001.06}@[/undrlyg/intrBk/orgnlIntrBkSttlmDt] |
originalMessageId |
PaymentReturn{pacs.004.001.09}@[/orgnlGrpInf/orgnlMsgId] PaymentTransaction{pacs.004.001.09}@[/orgnlMsgId or /orgnlGrpInf/orgnlMsgId] PaymentTransaction{camt.029.001.09}@[/orgnlMsgId or /orgnlGrpInf/orgnlMsgId] PaymentTransaction{camt.056.001.08}@[/orgnlMsgId or /orgnlGrpInf/orgnlMsgId] RequestToModifyPayment{camt.087.001.06}@[/undrlyg/initn/orgnlGrpInf/orgnlMsgId or /undrlyg/intrBk/orgnlGrpInf/orgnlMsgId] |
originalTransactionAmount |
PaymentTransaction{pacs.004.001.09}@[/orgnlTxRef/intrBkSttlmAmt/value or /orgnlIntrBkSttlmAmt/value] PaymentTransaction{camt.029.001.09}@[/orgnlTxRef/intrBkSttlmAmt/value or /orgnlIntrBkSttlmAmt/value] PaymentTransaction{camt.056.001.08}@[/orgnlTxRef/intrBkSttlmAmt/value or /orgnlIntrBkSttlmAmt/value] RequestToModifyPayment{camt.087.001.06}@[/undrlyg/intrBk/orgnlIntrBkSttlmAmt/value] |
originalTransactionAmountCurrency |
PaymentTransaction{pacs.004.001.09}@[/orgnlTxRef/intrBkSttlmAmt/ccy or /orgnlIntrBkSttlmAmt/ccy] PaymentTransaction{camt.029.001.09}@[/orgnlTxRef/intrBkSttlmAmt/ccy or /orgnlIntrBkSttlmAmt/ccy] PaymentTransaction{camt.056.001.08}@[/orgnlTxRef/intrBkSttlmAmt/ccy or /orgnlIntrBkSttlmAmt/ccy] RequestToModifyPayment{camt.087.001.06}@[/undrlyg/intrBk/orgnlIntrBkSttlmAmt/ccy] |
originalTransactionId |
PaymentTransaction{pacs.004.001.09}@[/orgnlTxId] PaymentTransaction{camt.029.001.09}@[/orgnlTxId] PaymentTransaction{camt.056.001.08}@[/orgnlTxId] RequestToModifyPayment{camt.087.001.06}@[/undrlyg/intrBk/orgnlTxId] |
paymentInformationId |
PaymentInstruction{pain.001.001.09}@[/pmtInfId] |
paymentType |
PaymentType@[/value] |
priority |
Priority@[/value] |
relatedUnitOfWork |
RelatedUnitOfWork@[/value] |
requestedExecutionDate |
PaymentInstruction{pain.001.001.09}@[/reqdExctnDt/dtTm or /reqdExctnDt/dt] RequestToModifyPayment{camt.087.001.06}@[/mod/reqdExctnDt/dtTm or /mod/reqdExctnDt/dt] |
returnId |
PaymentTransaction{pacs.004.001.09}@[/rtrId] |
returnedAmount |
PaymentTransaction{pacs.004.001.09}@[/rtrdIntrBkSttlmAmt/value] |
returnedAmountCurrency |
PaymentTransaction{pacs.004.001.09}@[/rtrdIntrBkSttlmAmt/ccy] |
timeZone |
TimeZone@[/value] |
totalAmount |
FIToFICustomerCreditTransfer{pacs.008.001.08}@[/grpHdr/ttlIntrBkSttlmAmt/value] |
totalAmountCurrency |
FIToFICustomerCreditTransfer{pacs.008.001.08}@[/grpHdr/ttlIntrBkSttlmAmt/ccy] |
transactionAmount |
CreditTransferTransaction{pain.001.001.09}@[/intrBkSttlmAmt/value] CreditTransferTransaction{pacs.008.001.08}@[/intrBkSttlmAmt/value] AccountNotification{camt.054.001.10}@[/ntry/0/ntryDtls/0/txDtls/0/amtDtls/txAmt/amt/value] RequestToModifyPayment{camt.087.001.06}@[/mod/intrBkSttlmAmt/value] Fx@[/originalCurrencyAndAmount/value] |
transactionAmountCurrency |
CreditTransferTransaction{pain.001.001.09}@[/intrBkSttlmAmt/ccy] CreditTransferTransaction{pacs.008.001.08}@[/intrBkSttlmAmt/ccy] AccountNotification{camt.054.001.10}@[/ntry/0/ntryDtls/0/txDtls/0/amtDtls/txAmt/amt/ccy] RequestToModifyPayment{camt.087.001.06}@[/mod/intrBkSttlmAmt/ccy] Fx@[/originalCurrencyAndAmount/ccy] |
transactionId |
CreditTransferTransaction{pain.001.001.09}@[/pmtId/txId] CreditTransferTransaction{pacs.008.001.08}@[/pmtId/txId] RequestToModifyPayment{camt.087.001.06}@[/mod/txId] |
uetr |
CreditTransferTransaction{pain.001.001.09}@[/pmtId/uetr] CreditTransferTransaction{pacs.008.001.08}@[/pmtId/uetr] |
Customisation
Customising summary fields and mappings requires building your own JAR containing the custom fields and mappings, and bundling that inside a deployable ODS Ingestion application so that it is part of the classpath.
It is possible to customise the default mappings for existing summary fields, and also, define completely new summary fields, for which you will need to define your own mappings.
Customising mappings for existing summary fields
All default mappings can be customised/overridden. When a custom mapping targets the same field as a default mapping, the default mapping is disabled. A custom mapping for a summary field could disable one or more default mappings.
Given the messageId field is mapped by default from a pain.001 CustomerCreditTransferInitiation, a pacs.008 FIToFICustomerCreditTransfer, or a pacs.004 PaymentReturn - If a custom mapping were to be defined targeting the same messageId field, the three default mappings would be disabled.
All mappings, including custom mappings, are defined in code, with a single source, and a single target summary field, and there are two types of mappers.
- ::INFO
-
When possible, prefer the JSON mappers. Direct object mappers incur an additional deserialisation cost, and require the target type to be available at runtime. Direct object mapping is appropriate when the value must be transformed before being applied to the summary.
JSON Mappings
JSON mapping is a flexible way to map into summary fields from MDS and PDS objects received by ODS. With this approach, the concrete types do not need to be available at runtime.
The mappings make use of JsonPointer, which is a path to a specific field within a JSON object, e.g. /grpHdr/msgId. The path traversal is resilient to null/missing fields, and the field within the JSON object at the designated path is converted/coerced to the target summary field type when required.
e.g., a PaymentTransaction mapper expects an MDS object with the type name "PaymentTransaction" and for the original message object to be a pacs.004
new JsonMdsMapper<>("PaymentTransaction", MessageNameSpecs.pacs004(), summaryFields.chargeAmount(), from("/chrgsInf/0/amt/value"));The mapping will be applied to any "PaymentTransaction" that originated from a pacs.004.
It’s possible to map from a PaymentTransaction that originated from any message object, e.g. a pacs.004, or a camt.056, or a camt.029
new JsonMdsMapper<>("PaymentTransaction", MessageNameSpecs.any(), summaryFields.originalTransactionId(), from("/orgnlTxId"));And the same can be expressed more explicitly
new JsonMdsMapper<>("PaymentTransaction", pacs004().or(camt056()).or(camt029()), summaryFields.originalTransactionId(), from("/orgnlTxId"));Mappings can also be version aware, making use of the version of the original message object, e.g., where the original message object is a pacs.004.xxx.09.
new JsonMdsMapper<>("PaymentTransaction", pacs004().atVersion("09"), summaryFields.interbankSettlementDate(), from("/grpHdr/intrBkSttlmDt"));Direct Object Mappings
Direct object mappings require the source object type to be available at runtime, and the received object is converted to the required type when the type name matches. This allows custom mappings to directly call methods on the source object.
e.g., a pacs.008 mapper expects the source FIToFICustomerCreditTransferV08, and targets the messageId summary field .
new MdsMapper<>(FIToFICustomerCreditTransferV08.class, summaryFields.messageId(), it -> it.getGrpHdr().getMsgId());The same approach is taken for custom PDS mappings, e.g., a mapper that expects a client specific PDS type and targets the messageId summary field.
new PdsMapper<>(ClientSpecificPdsType.class, "ClientSpecificPdsType", summaryFields.messageId(), it -> ClientSpecificPdsType::getValue);Configuring Custom Mappings
To apply custom mappings you must provide a JAR containing Spring autoconfiguration that provides a com.iconsolutions.ipf.ods.summary.SummaryMappingConfigurer bean.
Define a summary configurer bean
package com.client.ods;
import com.iconsolutions.ipf.ods.summary.MapperRegistry;
import com.iconsolutions.ipf.ods.summary.SummaryFields;
import com.iconsolutions.ipf.ods.summary.SummaryMappingConfigurer;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.context.annotation.Bean;
@AutoConfiguration
class CustomSummaryMappingConfig {
@Bean
SummaryMappingConfigurer customSummaryMappingConfigurer() {
return new SummaryMappingConfigurer() {
@Override
public void configure(final MapperRegistry registry, final SummaryFields summaryFields) {
registry
.register(new PdsMapper<>(CustomPdsType.class, "CustomPdsType", summaryFields.messageId(), CustomPdsType::getFieldA))
.register(new JsonPdsMapper<>("CustomPdsType", summaryFields.transactionId(), from("/fieldB")));
}
};
}
static final class CustomPdsType {
private String fieldA;
private String fieldB;
public String getFieldA() {
return fieldA;
}
public void setFieldA(final String fieldA) {
this.fieldA = fieldA;
}
public String getFieldB() {
return fieldB;
}
public void setFieldB(final String fieldB) {
this.fieldB = fieldB;
}
}
}Create Spring Autoconfiguration Imports file
com.client.ods.CustomSummaryMappingConfigCreating custom summary fields
It is possible to define your own summary fields, and map into those fields with your own custom mappings. Your custom fields, and the mappings that target those fields are visible in the summary layout.
To create custom summary fields, and custom mappings, you must provide a JAR containing Spring autoconfiguration that provides a com.iconsolutions.ipf.ods.summary.CustomSummaryMappingConfigurer bean.
Define a custom summary fields interface
package com.client.ods;
import com.iconsolutions.ipf.ods.summary.CustomSummaryFields;
import com.iconsolutions.ipf.ods.summary.Searchable;
import com.iconsolutions.ipf.ods.summary.SummaryField;
/**
* This interface MUST directly extend CustomSummaryFields. You do not need to implement this interface.
*/
public interface MyCustomSummaryFields extends CustomSummaryFields {
/**
* Only fields of type StringField may be searchable. Annotating a field that is not of type StringField will
* result in an exception at startup.
*/
@Searchable
SummaryField.StringField someSearchableId();
SummaryField.StringField someName();
SummaryField.BooleanField someFlag();
SummaryField.LongField someLong();
SummaryField.IntegerField someCount();
SummaryField.BigDecimalField someAmount();
SummaryField.DateField someDate();
SummaryField.DateTimeField someTimestamp();
SummaryField.DateOrDateTimeField someDateOrDateTime();
}Define a custom summary configurer bean
package com.client.ods;
import com.iconsolutions.ipf.ods.summary.MapperRegistry;
import com.iconsolutions.ipf.ods.summary.SummaryFields;
import com.iconsolutions.ipf.ods.summary.CustomSummaryMappingConfigurer;
import com.iconsolutions.ipf.ods.summary.TypeReference;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.context.annotation.Bean;
@AutoConfiguration
class CustomSummaryMappingConfig {
private static final TypeReference<CustomPdsType> customPdsType = new TypeReference<>() {
};
private static final String CUSTOM_PDS_TYPE = "CustomPdsType";
/**
* Your instance of CustomSummaryMappingConfigurer MUST be typed to your CustomSummaryFields subtype, in this
* case it is MyCustomSummaryFields.
*/
@Bean
CustomSummaryMappingConfigurer<MyCustomSummaryFields> customSummaryMappingConfigurer() {
return new SummaryMappingConfigurer() {
@Override
public void configure(final MapperRegistry registry, final MyCustomSummaryFields summaryFields) {
registry
//This mapping targets an existing summary field
.register(new PdsMapper<>(customPdsType, CUSTOM_PDS_TYPE, summaryFields.messageId(), CustomPdsType::getFieldA))
//This mapping targets a custom summary field
.register(new JsonPdsMapper<>(CUSTOM_PDS_TYPE, summaryFields.someSearchableId(), from("/fieldB")));
}
@Override
public Class<MyCustomSummaryFields> getSummaryFieldsType() {
return MyCustomSummaryFields.class;
}
};
}
static final class CustomPdsType {
private String fieldA;
private String fieldB;
public String getFieldA() {
return fieldA;
}
public void setFieldA(final String fieldA) {
this.fieldA = fieldA;
}
public String getFieldB() {
return fieldB;
}
public void setFieldB(final String fieldB) {
this.fieldB = fieldB;
}
}
}Create Spring Autoconfiguration Imports file
com.client.ods.CustomSummaryMappingConfigThe fields you define are limited in their type, the current supported set of possible types is:
| Type | Searchable? | Description |
|---|---|---|
|
Yes |
|
|
No |
|
|
No |
|
|
No |
|
|
No |
|
|
No |
The underlying type is |
|
No |
A type that represents a date and time. Factory methods are present to aid creating instances from |
|
No |
A type that can represent either a date, or a date time. Factory methods are present to aid creating instances from |
Custom searchable summary fields must be indexed. In ODS searchable fields on a summary will be populated under searchFields, e.g. searchFields.someId.
|
Deploying customisations
Custom ODS Ingestion Docker Image
One method of customising ODS is to build a custom ODS Ingestion docker image, using the default ODS Ingestion docker image as a base. Additional JARs can be included in this custom image, containing the customised summary mappings.
An example of such a customisation can be seen in the ODS repository. To apply custom mappings you must provide a JAR containing Spring autoconfiguration that provides SummaryMappingConfigurer and CustomSUmmaryMappingConfigurer beans
ODS is not usually aware of custom PDS types, but in this setup, your project is able to include the custom types in code, or via external dependencies, and they will be available on the classpath.
Custom PDS types are received by ODS as a map of properties. The type is actually Map<String, Object>. ODS will convert this map to the desired type, and will invoke the custom mapper with the converted value.
| Any third-party dependencies required by your custom mapping JAR will also need to be included in the custom docker image. Dependencies such as Spring/Spring Boot/Lombok etc. will not need to be provided, as they are already provided by ODS. |
| Avoid having more dependencies for your custom mappers than is absolutely necessary. This will help avoid classpath issues. |
The recommended set of dependencies your custom mapper JAR should depend on is
<dependencies>
<dependency>
<groupId>com.iconsolutions.ipf.ods</groupId>
<artifactId>ods-summary-mapping-api</artifactId>
<version>${ods.version}</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-autoconfigure</artifactId>
<version>${spring-boot.version}</version>
</dependency>
<!-- Optional: Only required if customising ISO20022 MDS Mappings -->
<dependency>
<groupId>com.iconsolutions.iso20022.model</groupId>
<artifactId>message-model-types</artifactId>
<version>${iso-model.version}</version>
</dependency>
</dependencies>These will not need to be added to your custom docker image, they will already be present.
In addition to these, you may need to depend on other libraries that provide your target custom PDS types. These will need to be included in the custom docker image along with your custom mappers.
| If your custom PDS type/s are small, you may choose to duplicate them alongside your custom mappers, rather than pulling in another dependency. ODS will be able to convert into the required types before invoking your mappers. |
Summary Layout
The summary layout, i.e. the set of default and custom summary fields, the custom MDS and PDS mappings, any disabled default mappings, and the overall final set of mappings, is available at runtime.
Logging
The summary layout is logged at startup.
Example summary layout log
2023-10-04 15:02:57.270 INFO 1 --- [ main] c.i.ipf.ods.summary.SummaryLayoutLogger :
-------------------------------------------------------------------------------------
Summary Layout
-------------------------------------------------------------------------------------
---------------------------------------------------------------------------------
Disabled MDS Mappings
---------------------------------------------------------------------------------
Target Field Source Type
---------------------------------------------------------------------------------
debtorName PaymentInstruction30
CreditTransferTransaction39
PaymentTransaction112
PaymentTransaction102
PaymentTransaction106
messageId CustomerCreditTransferInitiationV09
FIToFICustomerCreditTransferV08
PaymentReturnV09
transactionId CreditTransferTransaction39
PaymentTransaction112
PaymentTransaction102
PaymentTransaction106
---------------------------------------------------------------------------------
---------------------------------------------------------------------------------
Custom PDS Mappings
---------------------------------------------------------------------------------
Target Field Source Type
---------------------------------------------------------------------------------
debtorName CustomPdsType
messageId CustomPdsType
transactionId CustomPdsType
---------------------------------------------------------------------------------
---------------------------------------------------------------------------------
Final Mappings
---------------------------------------------------------------------------------
Target Field Source Type
---------------------------------------------------------------------------------
acceptanceDateTime CreditTransferTransaction39
batchBooking PaymentInstruction30
cancellationId PaymentTransaction106
chargeAmount PaymentTransaction112
chargeAmountCurrency PaymentTransaction112
controlSum CustomerCreditTransferInitiationV09
PaymentInstruction30
creditAccount AccountNotification20
creditAmount AccountNotification20
creditAmountCurrency AccountNotification20
creditorAccount CreditTransferTransaction34
CreditTransferTransaction39
PaymentTransaction112
PaymentTransaction102
PaymentTransaction106
creditorAgentBIC CreditTransferTransaction34
CreditTransferTransaction39
PaymentTransaction112
PaymentTransaction102
PaymentTransaction106
creditorBIC CreditTransferTransaction34
CreditTransferTransaction39
creditorName CreditTransferTransaction34
CreditTransferTransaction39
PaymentTransaction112
PaymentTransaction102
PaymentTransaction106
debitAccount AccountNotification20
debitAmount AccountNotification20
debitAmountCurrency AccountNotification20
debtorAccount PaymentInstruction30
CreditTransferTransaction39
PaymentTransaction112
PaymentTransaction102
PaymentTransaction106
debtorAgentBIC PaymentInstruction30
CreditTransferTransaction39
PaymentTransaction112
PaymentTransaction102
PaymentTransaction106
debtorBIC PaymentInstruction30
CreditTransferTransaction39
debtorName CustomPdsType
initiatingPartyName CustomerCreditTransferInitiationV09
instructedAgent FIToFICustomerCreditTransferV08
PaymentReturnV09
PaymentTransaction112
instructedAmount CreditTransferTransaction34
AccountNotification20
instructedAmountCurrency CreditTransferTransaction34
AccountNotification20
instructedParty FIToFIPaymentCancellationRequestV08
instructingAgent FIToFICustomerCreditTransferV08
PaymentReturnV09
PaymentTransaction112
instructingParty FIToFIPaymentCancellationRequestV08
instructionId CreditTransferTransaction34
CreditTransferTransaction39
PaymentTransaction112
PaymentTransaction102
PaymentTransaction106
interbankSettlementDate FIToFICustomerCreditTransferV08
CreditTransferTransaction39
PaymentReturnV09
messageId CustomPdsType
numberOfTransactions PaymentInstruction30
FIToFICustomerCreditTransferV08
originalEndToEndId PaymentTransaction112
PaymentTransaction102
PaymentTransaction106
originalInterbankSettlementDate PaymentTransaction112
PaymentTransaction102
PaymentTransaction106
originalMessageId PaymentReturnV09
PaymentTransaction112
PaymentTransaction102
PaymentTransaction106
paymentInformationId PaymentInstruction30
requestedExecutionDate PaymentInstruction30
returnId PaymentTransaction112
returnedAmount PaymentTransaction112
returnedAmountCurrency PaymentTransaction112
totalAmount FIToFICustomerCreditTransferV08
totalAmountCurrency FIToFICustomerCreditTransferV08
transactionAmount CreditTransferTransaction39
PaymentTransaction112
PaymentTransaction102
PaymentTransaction106
AccountNotification20
transactionAmountCurrency CreditTransferTransaction39
PaymentTransaction112
PaymentTransaction102
PaymentTransaction106
AccountNotification20
transactionId CustomPdsType
uetr CreditTransferTransaction34
CreditTransferTransaction39
---------------------------------------------------------------------------------Actuator Endpoint
The summary layout is available as a custom Spring Boot Actuator endpoint at /actuator/summary-layout. It’s not enabled by default.
Configure management.endpoints.web.exposure.include to include summary-layout, to enable the summary layout endpoint, or with * to enable all actuator endpoints.
e.g. management.endpoints.web.exposure.include = [health, info, prometheus, summary-layout].
Example summary layout response
{
"finalMappings": {
"debtorAccount": [
"PaymentInstruction30",
"CreditTransferTransaction39",
"PaymentTransaction112",
"PaymentTransaction102",
"PaymentTransaction106"
],
"debitAccount": [
"AccountNotification20"
],
"creditorName": [
"CreditTransferTransaction34",
"CreditTransferTransaction39",
"PaymentTransaction112",
"PaymentTransaction102",
"PaymentTransaction106"
],
"chargeAmountCurrency": [
"PaymentTransaction112"
],
"instructedAmountCurrency": [
"CreditTransferTransaction34",
"AccountNotification20"
],
"batchBooking": [
"PaymentInstruction30"
],
"instructingAgent": [
"FIToFICustomerCreditTransferV08",
"PaymentReturnV09",
"PaymentTransaction112"
],
"cancellationId": [
"PaymentTransaction106"
],
"totalAmountCurrency": [
"FIToFICustomerCreditTransferV08"
],
"creditorBIC": [
"CreditTransferTransaction34",
"CreditTransferTransaction39"
],
"numberOfTransactions": [
"PaymentInstruction30",
"FIToFICustomerCreditTransferV08"
],
"controlSum": [
"CustomerCreditTransferInitiationV09",
"PaymentInstruction30"
],
"instructedParty": [
"FIToFIPaymentCancellationRequestV08"
],
"debtorBIC": [
"PaymentInstruction30",
"CreditTransferTransaction39"
],
"debitAmountCurrency": [
"AccountNotification20"
],
"returnedAmountCurrency": [
"PaymentTransaction112"
],
"transactionAmount": [
"CreditTransferTransaction39",
"PaymentTransaction112",
"PaymentTransaction102",
"PaymentTransaction106",
"AccountNotification20"
],
"returnId": [
"PaymentTransaction112"
],
"instructingParty": [
"FIToFIPaymentCancellationRequestV08"
],
"chargeAmount": [
"PaymentTransaction112"
],
"acceptanceDateTime": [
"CreditTransferTransaction39"
],
"instructedAmount": [
"CreditTransferTransaction34",
"AccountNotification20"
],
"originalMessageId": [
"PaymentReturnV09",
"PaymentTransaction112",
"PaymentTransaction102",
"PaymentTransaction106"
],
"creditAmountCurrency": [
"AccountNotification20"
],
"originalEndToEndId": [
"PaymentTransaction112",
"PaymentTransaction102",
"PaymentTransaction106"
],
"creditAccount": [
"AccountNotification20"
],
"paymentInformationId": [
"PaymentInstruction30"
],
"instructedAgent": [
"FIToFICustomerCreditTransferV08",
"PaymentReturnV09",
"PaymentTransaction112"
],
"messageId": [
"CustomPdsType"
],
"transactionAmountCurrency": [
"CreditTransferTransaction39",
"PaymentTransaction112",
"PaymentTransaction102",
"PaymentTransaction106",
"AccountNotification20"
],
"debtorName": [
"PaymentInstruction30",
"CreditTransferTransaction39",
"PaymentTransaction112",
"PaymentTransaction102",
"PaymentTransaction106"
],
"debitAmount": [
"AccountNotification20"
],
"transactionId": [
"CustomPdsType"
],
"totalAmount": [
"FIToFICustomerCreditTransferV08"
],
"requestedExecutionDate": [
"PaymentInstruction30"
],
"creditorAccount": [
"CreditTransferTransaction34",
"CreditTransferTransaction39",
"PaymentTransaction112",
"PaymentTransaction102",
"PaymentTransaction106"
],
"uetr": [
"CreditTransferTransaction34",
"CreditTransferTransaction39"
],
"originalInterbankSettlementDate": [
"PaymentTransaction112",
"PaymentTransaction102",
"PaymentTransaction106"
],
"instructionId": [
"CreditTransferTransaction34",
"CreditTransferTransaction39",
"PaymentTransaction112",
"PaymentTransaction102",
"PaymentTransaction106"
],
"creditorAgentBIC": [
"CreditTransferTransaction34",
"CreditTransferTransaction39",
"PaymentTransaction112",
"PaymentTransaction102",
"PaymentTransaction106"
],
"creditAmount": [
"AccountNotification20"
],
"returnedAmount": [
"PaymentTransaction112"
],
"initiatingPartyName": [
"CustomerCreditTransferInitiationV09"
],
"interbankSettlementDate": [
"FIToFICustomerCreditTransferV08",
"CreditTransferTransaction39",
"PaymentReturnV09"
],
"debtorAgentBIC": [
"PaymentInstruction30",
"CreditTransferTransaction39",
"PaymentTransaction112",
"PaymentTransaction102",
"PaymentTransaction106"
]
},
"customMdsMappings": {},
"customPdsMappings": {
"messageId": [
"CustomPdsType"
],
"transactionId": [
"CustomPdsType"
]
},
"disabledMdsMappings": {
"messageId": [
"CustomerCreditTransferInitiationV09",
"FIToFICustomerCreditTransferV08",
"PaymentReturnV09"
],
"transactionId": [
"CreditTransferTransaction39",
"PaymentTransaction112",
"PaymentTransaction102",
"PaymentTransaction106"
]
}
}