Inquiry API V3 Migration Guide

Specification Changes from V2

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 MdsObjectSearchItem2, 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

Migrating Client Connectors

The ods-inquiry-client module has been updated to support both V1, V2 and V3 Inquiry APIs. The default configuration (ods.inquiry.client.version=2) enables the instantiation of the V2 Inquiry Client APIs and needs to be explicitly overridden for V3 Inquiry Client APIs.

If you want to migrate to the V3 client APIs, your configuration must be updated to override the client version configuration as follows: ods.inquiry.client.version=3
This will ensure the V3 client APIs can be enabled and a code change will be required. See V3 Inquiry API client documentation for more information on the V3 client APIs that can be enabled.

The available V3 Client APIs are listed below. Client API configuration lives under ods.inquiry.client, and all properties listed below must be prefixed with this.

Configure V3 Client APIs
Property Default Notes

summaries.enabled

false

Enable the Summaries bean when set to true

details.enabled

false

Enable the Details bean when set to true

process-flow-graphs.enabled

false

Enable the ProcessFlowGraphs bean when set to true

process-objects.enabled

false

Enable the ProcessObjects bean when set to true

custom-objects.enabled

false

Enable the CustomObjects bean when set to true

mds-objects.enabled

false

Enable the MdsObjects bean when set to true

pds-objects.enabled

false

Enable the PdsObjects bean when set to true

Client Connector Changes from V2

There are differences from the set of V2 beans:

V2 Bean Replacement V3 Bean Notes New required fields Changed fields

Summaries

SummariesV3

SummaryView should be replaced with the SummaryView2 class. Search requests now require JourneyType as a parameter.

createdAt, unitOfWorkId, terminal, failure

The class field has been removed.

ProcessObjects

ProcessObjectsV3

- ProcessObjectSearchItem should be replaced with the ProcessObjectSearchItem2 class
- IPFMessageLogSearchItem should be replaced with the IPFMessageLogSearchItem2 class
- IPFSystemEventSearchItem should be replaced with the IPFSystemEventSearchItem2 class
- IPFProcessFlowEventSearchItem should be replaced with the IPFProcessFlowEventSearchItem2 class
- IPFProcessFlowDefinitionSearchItem should be replaced with the IPFProcessFlowDefinitionSearchItem2 class

- OdsObjectHeaders2 requires createdAt, clientRequestId, objectType, processingEntity, unitOfWorkId, source
- IPFMessageLogPayload requires content
- IPFProcessFlowEvent2 requires rawContent
- IPFProcessFlowDefinition2 requires rawContent

- OdsObjectHeaders2 in comparison to ODSObjectHeaders has the version and class fields removed
- IPFProcessFlowEvent2 in comparison to IPFProcessFlowEvent has hash, terminalIndicator and labels fields added
- IPFProcessFlowDefinition2 in comparison to IPFProcessFlowDefinition has terminalGlobalStates, states, events and rawContent fields added

PdsObjects

PdsObjectsV3

PdsObjectSearchItem should be replaced with PdsObjectSearchItem2. V3 now has GetPdsByUnitOfWorkIdRequest, GetPdsByOdsObjectIdRequest and GetPdsHistoryByPdsObjectIdRequest objects rather than the previous GetPdsObjectsRequest, GetPdsObjectRequest, GetPdsRequest, GetHistoryRequest, GetPdsHistoryRequest, this was to align the API’s with the rest of the ODS object type API’s.

links, payload and within the payload field content is now required.

- OdsObjectHeaders2 in comparison to ODSObjectHeaders has the version and class fields removed
- PdsObjectPayload2 in comparison to PdsObjectPayload has the version and metadata fields added

MdsObjects

MdsObjectsV3

MdsObjectSearchItem should be replaced with the MdsObjectSearchItem2 class.

links and payload and within the payload the content and type fields are now required.

- OdsObjectHeaders2 in comparison to ODSObjectHeaders has the version and class fields removed
- MdsObjectPayload2 in comparison to MdsObjectPayload has metadata, type, version, messageDefinition and content fields added

Details

DetailsV3

DetailView should be replaced with the DetailView2 class.

- DetailView2 requires createdAt, unitOfWorkId, terminal and failure
- PdsData2 requires content
- EventSummaryView2 requires processFlowDefinitionId

- SummaryView2 in comparison to SummaryView has the class field removed
- PdaData2 in comparison to PdsData the version field has changed from a string type to an integer

Migrating Test Client

The ods-inquiry-test-client module has been updated to support V1, V2 and V3 Inquiry APIs. Similar to the Client APIs, a new set of V3 Test Client APIs are available via the InquiryClientV3 interface.

Usage

Both the V1, V2 and V3 Test Clients can be used at the same time. If you are migrating from V2 to V3, you will need to update your test suite to use the InquiryClientV3 interface. The InquiryClient method createInquiryClientV3 will return a default instance of the InquiryClientV3 interface.

@Configuration
class TestClientConfig {
    @Bean
    InquiryClient inquiryClient(@Value("${inquiry.base.url}") final String baseUrl,
                                @Value("${inquiry.openapi-validation.enabled}") final boolean openApiValidation,
                                final CurrentAuthToken currentAuthToken) {
        return InquiryClient.createInquiryClient(InquiryClientOptions.builder()
                .baseUrl(baseUrl)
                .currentAuthToken(currentAuthToken)
                .requestTimeout(Duration.ofSeconds(60))
                .openApiValidation(openApiValidation)
                .build());
    }

    @Bean
    InquiryClientV2 inquiryClientV2(@Value("${inquiry.base.url}") final String baseUrl,
                                    @Value("${inquiry.openapi-validation.enabled}") final boolean openApiValidation,
                                    final CurrentAuthToken currentAuthToken) {
        return InquiryClient.createInquiryClientV2(InquiryClientOptions.builder()
                .baseUrl(baseUrl)
                .currentAuthToken(currentAuthToken)
                .requestTimeout(Duration.ofSeconds(60))
                .openApiValidation(openApiValidation)
                .build());
    }

    @Bean
    InquiryClientV3 inquiryClientV3(@Value("${inquiry.base.url}") final String baseUrl,
                                    @Value("${inquiry.openapi-validation.enabled}") final boolean openApiValidation,
                                    final CurrentAuthToken currentAuthToken) {
        return InquiryClient.createInquiryClientV3(InquiryClientOptions.builder()
                .baseUrl(baseUrl)
                .currentAuthToken(currentAuthToken)
                .requestTimeout(Duration.ofSeconds(60))
                .openApiValidation(openApiValidation)
                .build());
    }
}

Test Client Changes from V2

The difference between the V2 and V3 Test Client APIs is as follows:

  • All APIs have been updated to utilise the V3 Inquiry API specification

  • The Details, MdsObjects, MessageLogs, PdsObjects, ProcessFlowDefinitions, ProcessFlowEvents, ProcessObjects, Summaries1 and SystemEvents interfaces has been deprecated, to be replaced with the DetailsV3, MdsObjectsV3, MessageLogsV3, PdsObjectsV3, ProcessFlowDefinitionsV3, ProcessFlowEventsV3, ProcessObjectsV3, SummariesV3 and SystemEventsV3 interfaces.

    • The DetailsV3 interface returns the DetailView2 class, whereas Details uses the DetailView class.

    • The MdsObjectsV3 interface returns the MdsObjectSearchItem2 class, whereas MdsObjects uses the MdsObjectSearchItem or the Pacs008FIToFICustomerCreditTransferMdsSearchItem class for the pacs008CreditTransferTransactions method.

    • The MessageLogsV3 interface returns the IPFMessageLogSearchItem2 class, whereas MessageLogs uses the IPFMessageLogSearchItem class.

    • The PdsObjectsV3 interface returns the PdsObjectSearchItem2 class, whereas PdsObjects uses the PdsObjectSearchItem class. The PdsObjectsV3 interface also now only has methods that search by unitOfWorkId, odsObjectId and pdsObjectId, whereas PdsObjects had methods that also searched by unitOfWorkId and name as two search parameters.

    • The ProcessFlowDefinitionsV3 interface returns the IPFProcessFlowDefinitionSearchItem2 class, whereas ProcessFlowDefinitions uses the IPFProcessFlowDefinitionSearchItem class.

    • The ProcessFlowEventsV3 interface returns the IPFProcessFlowEventSearchItem2 class, whereas ProcessFlowEvents uses the IPFProcessFlowEventSearchItem class.

    • The ProcessObjectsV3 interface returns the ProcessObjectSearchItem2, SystemEventsV3, MessageLogsV3, ProcessFlowEventsV3 and ProcessFlowDefinitionsV3 classes, whereas ProcessObjects uses the ProcessObjectSearchItem, SystemEvents, MessageLogs, ProcessFlowEvents and ProcessFlowDefinitions classes.

    • The SummariesV3 interface returns the SummaryView2 class and no longer uses the JourneyType class as a search parameter, whereas Summaries1 uses the SummaryView class and uses the JourneyType class as a search parameter.

    • The SystemEventsV3 interface returns the IPFSystemEventSearchItem2 class, whereas SystemEvents uses the IPFSystemEventSearchItem class.

  • The Summaries1, Details, MdsObjects, ProcessObjects and PdsObjects interfaces have therefore been replaced with the SummariesV3, DetailsV3, MdsObjectsV3, ProcessObjectsV3 and PdsObjectsV3 classes for the InquiryClient3 interface