Migration Guide

This guide outlines the changes you should expect when migrating from to ODS Inquiry API V3 from V2.

See the full detailed list of changes compared to V2 for more detailed information.

Specification Changes

The V3 Inquiry API was introduced to consolidate all four views/summaries endpoints to one, with journeyType becoming a search parameter rather than a url parameter. The following changes have been made:

  • All endpoints have been updated to have a path beginning with /api/v3. For example:

    • /api/v2/views/details/{unitOfWorkId} → /api/v3/views/details/{unitOfWorkId}

    • /api/v2/catalogue/process-objects/message-logs → /api/v3/catalogue/process-objects/message-logs

    • etc.

  • The four /views/summaries/ search endpoints have been unified. Previously, these four API endpoints had journeyType as a url parameter, now it is a query parameter. For example:

    • /api/v2/views/summaries/payments → /api/v3/views/summaries?journeyType=PAYMENT

    • /api/v2/views/summaries/recalls → /api/v3/views/summaries?journeyType=RECALL

  • Which means these endpoints have been removed:

    • /views/summaries/payments

    • /views/summaries/recalls

    • /views/summaries/batches

    • /views/summaries/bulks

  • The response class for all /api/v3/all/mds-objects and /api/v3/catalogue/mds-objects/ endpoints has changed to MdsObjectSearchItem, removing the use of the distinct classes:

    • MdsObjectSearchItem

    • Pacs008FIToFICustomerCreditTransferMdsSearchItem

    • Pacs008CreditTransferTransactionMdsSearchItem

    • Pacs002FIToFIPaymentStatusReportMdsSearchItem

    • Pacs002OriginalGroupHeaderMdsSearchItem

    • Pacs002PaymentTransactionMdsSearchItem

    • Pacs004PaymentReturnMdsSearchItem

    • Pacs004PaymentTransactionMdsSearchItem

    • Pacs009FinancialInstitutionCreditTransferMdsSearchItem

    • Pacs009CreditTransferTransactionMdsSearchItem

    • Pacs028FIToFIPaymentStatusRequestMdsSearchItem

    • Pacs028OriginalGroupInformationMdsSearchItem

    • Pacs028PaymentTransactionMdsSearchItem

    • Pain001CustomerCreditTransferInitiationMdsSearchItem

    • Pain001PaymentInstructionMdsSearchItem

    • Pain001CreditTransferTransactionMdsSearchItem

    • Pain002CustomerPaymentStatusReportMdsSearchItem

    • Pain002OriginalPaymentInstructionMdsSearchItem

    • Pain002PaymentTransactionMdsSearchItem

    • Camt027ClaimNonReceiptMdsSearchItem

    • Camt029ResolutionOfInvestigationMdsSearchItem

    • Camt029PaymentTransactionWithResolutionMdsSearchItem

    • Camt029UnderlyingTransactionMdsSearchItem

    • Camt054BankToCustomerDebitCreditNotificationMdsSearchItem

    • Camt054AccountNotificationMdsSearchItem

    • Camt056FIToFIPaymentCancellationRequestMdsSearchItem

    • Camt056PaymentTransactionMdsSearchItem

    • Camt056UnderlyingTransactionMdsSearchItem

    • Camt087RequestToModifyPaymentMdsSearchItem

  • The structure and response of the API remain consistent with the V2 implementation. This affects the following endpoints:

    • /api/v3/all/mds-objects

    • /api/v3/all/mds-objects/{odsObjectId}

    • /api/v3/all/mds-objects/{mdsObjectId}/history

    • /api/v3/catalogue/mds-objects/PACS_008

    • /api/v3/catalogue/mds-objects/PACS_008_CREDIT_TRANSFER_TRANSACTION

    • /api/v3/catalogue/mds-objects/PACS_002

    • /api/v3/catalogue/mds-objects/PACS_002_ORIGINAL_GROUP_HEADER

    • /api/v3/catalogue/mds-objects/PACS_002_PAYMENT_TRANSACTION

    • /api/v3/catalogue/mds-objects/PACS_004

    • /api/v3/catalogue/mds-objects/PACS_004_PAYMENT_TRANSACTION

    • /api/v3/catalogue/mds-objects/PACS_009

    • /api/v3/catalogue/mds-objects/PACS_009_CREDIT_TRANSFER_TRANSACTION

    • /api/v3/catalogue/mds-objects/PACS_028

    • /api/v3/catalogue/mds-objects/PACS_028_ORIGINAL_GROUP_INFORMATION

    • /api/v3/catalogue/mds-objects/PACS_028_PAYMENT_TRANSACTION

    • /api/v3/catalogue/mds-objects/PAIN_001

    • /api/v3/catalogue/mds-objects/PAIN_001_PAYMENT_INSTRUCTION

    • /api/v3/catalogue/mds-objects/PAIN_001_CREDIT_TRANSFER_TRANSACTION

    • /api/v3/catalogue/mds-objects/PAIN_002

    • /api/v3/catalogue/mds-objects/PAIN_002_ORIGINAL_PAYMENT_INSTRUCTION

    • /api/v3/catalogue/mds-objects/PAIN_002_PAYMENT_TRANSACTION

    • /api/v3/catalogue/mds-objects/CAMT_027

    • /api/v3/catalogue/mds-objects/CAMT_029

    • /api/v3/catalogue/mds-objects/CAMT_029_PAYMENT_TRANSACTION_WITH_RESOLUTION

    • /api/v3/catalogue/mds-objects/CAMT_029_UNDERLYING_TRANSACTION

    • /api/v3/catalogue/mds-objects/CAMT_054

    • /api/v3/catalogue/mds-objects/CAMT_054_ACCOUNT_NOTIFICATION

    • /api/v3/catalogue/mds-objects/CAMT_056

    • /api/v3/catalogue/mds-objects/CAMT_056_PAYMENT_TRANSACTION

    • /api/v3/catalogue/mds-objects/CAMT_056_UNDERLYING_TRANSACTION

    • /api/v3/catalogue/mds-objects/CAMT_087

Dependency Changes

All code related to ODS Inquiry API V3 now lives under different maven coordinates to the V1 and V2 APIs; The groupId has changed to com.iconsolutions.ipf.ods.inquiry.v3, and all artifactIds are now prefixed with ipf, e.g. ods-inquiry-api becomes ipf-ods-inquiry-api.

Below is the full list of dependencies you can expect to be using:

<dependency>
    <groupId>com.iconsolutions.ipf.ods.inquiry.v3</groupId>
    <artifactId>ipf-ods-inquiry-api</artifactId>
</dependency>
<dependency>
    <groupId>com.iconsolutions.ipf.ods.inquiry.v3</groupId>
    <artifactId>ipf-ods-inquiry-client-api</artifactId>
</dependency>
<dependency>
    <groupId>com.iconsolutions.ipf.ods.inquiry.v3</groupId>
    <artifactId>ipf-ods-inquiry-client-connector</artifactId>
</dependency>

Package Changes

All code related to ODS Inquiry API V3, both generated and non-generated, lives in its own v3 package. Anything previously under com.iconsolutions.ipf.ods.inquiry.* now lives under com.iconsolutions.ipf.ods.inquiry.v3.*.

Type names are mostly unchanged, with an exception in the client connector outlined below in Client Connector Changes, which means a search-replace of the package should get you most of the way there with a migration.

Model Changes

All generated code is generated into the package com.iconsolutions.ipf.ods.inquiry.v3.model.*. When migrating from V2 in one go, you can search and replace all usages of com.iconsolutions.ipf.ods.inquiry.\* packages and replace them with the v3 equivalent.

These types became stricter, where fields were made non-null:

Type Fields Made Non-Null

com.iconsolutions.ipf.ods.inquiry.v3.model.OdsObjectHeaders

createdAt, clientRequestId, objectType, processingEntity, unitOfWorkId

com.iconsolutions.ipf.ods.inquiry.v3.model.IPFMessageLogPayload

content

com.iconsolutions.ipf.ods.inquiry.v3.model.IPFMessageLogPayload

content

com.iconsolutions.ipf.ods.inquiry.v3.model.IPFProcessFlowEvent

rawContent

com.iconsolutions.ipf.ods.inquiry.v3.model.IPFProcessFlowDefinition

rawContent

com.iconsolutions.ipf.ods.inquiry.v3.model.PdsObjectSearchItem

links

com.iconsolutions.ipf.ods.inquiry.v3.model.PdsObjectODSObject

payload

com.iconsolutions.ipf.ods.inquiry.v3.model.MdsObjectSearchItem

links

com.iconsolutions.ipf.ods.inquiry.v3.model.MdsObjectODSObject

payload

com.iconsolutions.ipf.ods.inquiry.v3.model.MdsObjectPayload

content, type

com.iconsolutions.ipf.ods.inquiry.v3.model.DetailView

createdAt, unitOfWorkId, terminal, failure

com.iconsolutions.ipf.ods.inquiry.v3.model.PdsData

content

com.iconsolutions.ipf.ods.inquiry.v3.model.EventSummaryView

processFlowDefinitionId

These types gained new fields compared to the V2 equivalent:

Type Fields Added

com.iconsolutions.ipf.ods.inquiry.v3.model.IPFProcessFlowEvent

hash, terminalIndicator, labels

com.iconsolutions.ipf.ods.inquiry.v3.model.IPFProcessFlowDefinition

terminalGlobalStates, states, events, rawContent

com.iconsolutions.ipf.ods.inquiry.v3.model.MdsObjectPayload

metadata, type, version, messageDefinition, content

com.iconsolutions.ipf.ods.inquiry.v3.model.OdsObjectHeaders

associationId

These types lost fields compared to the V2 equivalent:

Type Fields Removed

com.iconsolutions.ipf.ods.inquiry.v3.model.OdsObjectHeaders

version, class, primaryAssociation

com.iconsolutions.ipf.ods.inquiry.v3.model.SummaryView

class

com.iconsolutions.ipf.ods.inquiry.v3.model.MdsObjectPayload

mdsContentType

These types contain fields that changed type compared to the V2 equivalent:

Type Fields Changed

com.iconsolutions.ipf.ods.inquiry.v3.model.PdaData

version changed from a string type to an integer

Client Connector Changes

Previously, usages of the inquiry connector client would need to be migrated all at once, but it is now possible to run both the v2 client connectors, and the v3 client connectors together, which means migration can be more gradual. Simply depend on the v3 client connectors in addition to the v2 client connectors.

Type Notes

com.iconsolutions.ipf.ods.inquiry.v3.model.PdsObjects

The client request types GetPdsByUnitOfWorkIdRequest, GetPdsByOdsObjectIdRequest and GetPdsHistoryByPdsObjectIdRequest replace the V2 types GetPdsObjectsRequest, GetPdsObjectRequest, GetPdsRequest, GetHistoryRequest, GetPdsHistoryRequest, this was to align the API’s with the rest of the ODS object type API’s.