IMS v3

These are the reasons to introduce an IMS v3 protocol.
  • When ION IMS sends a message with v3, the message is sent in a format that is compliant with swagger v2. This can be a breaking change for some applications. Therefore, a new IMS protocol version is required.
  • Introduce a new method: acceptedDocuments. Applications can call this method to check which documents IMS is prepared to receive.

    This is a new method in ION. Therefore, a new protocol version is required so that an application can verify whether ION supports this method. This is relevant for on-premises deployments.

    With this method, the integration flow with ION changes.

    Note:  When duplicating an IMS connection point, documents are duplicated only if Discovery is disabled. If Discovery is enabled, the Documents tab remains empty in the duplicated connection point.
  • ION exposes APIs to configure the IMS connection point. These APIs replace the discovery method.

    Extend the IMS endpoint definition with this property: discovery=false. The same value can also be set as part of the protocol method.

    ION supports documents that are defined through the UI or API rather than through the discovery method.

    You can add documents in the same way as for a regular connection point.

Compared to IMS v2, IMS v3 offers these features:

  1. Consistent implementation for multipartMessage method.

    In IMS v2, a message that was sent by ION deviated from the swagger definition. This issue is corrected in v3.

  2. The test method is replaced with the acceptedDocuments method.

    The v2 test method checked whether a specific document could be received. The acceptedDocuments method lists the documents that IMS accepts for a specific connection point (logical-id).

  3. More granular HTTP status codes.

    In v2, the multipartMessage method returned a 412 error for both configuration errors and malformed messages.

    • 412 error for configuration issues, such as an inactive connection point.
    • 400 error for invalid messages, for example when a required property is missing.

    These responses allow applications to handle errors more precisely.

  4. The protocol method includes an option to specify whether the discovery method is available.

    Traditionally, bidirectional IMS integration required applications to use the discovery method to list supported documents.

    Applications can now configure documents through APIs provided by ION. The hasDiscovery property indicates whether the discovery method is implemented. The default value is true.

  5. The IMS v3 multipartMessage method includes documentName and logicalId as HTTP parameters.

    When ION sends a multipartMessage, these parameters allow applications to route messages internally without parsing the payload.

  6. The IMS v3 message/multipart method includes all IMS message parameters as HTTP parameters.