IMS v3 introduction

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 documentsIMS is prepared to receive.

    This is a new method in ION. Therefore, a new protocol version is required. So an application can check whether ION is prepared for this method. This is relevant for on-premises deployments.

    With that the integration flow with ION changes.

  • ION exposes APIs to configure the IMS connection point. These APIs are a good replacement for the discovery method.

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

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

    You can now 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 itself deviated from the swagger definition. This issue has been fixed. It was the main reason to introduce version v3 because this might be a compatibility issue for some adopters.

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

    You could use the v2 test method to check for a specific document if ION was prepared to receive it. The acceptedDocuments method lists the documents that IMS accepts for a specific connection point (logical-id).

  3. More granular HTTP status codes.

    multipartMessage method v2 throws a 412 error, both in case of configuration errors and malformatted messages. In v3 this is improved as follows:

    • A 412 error is thrown for configuration issues, such as an inactive connection point.
    • A 400 error is thrown for bad messages, for example because of a missing property.

    This way, adopters can handle the response more specifically.

  4. The protocol method has an extra option to define whether the discovery method is available.

    Traditionally, the two-way (bidirectional) IMS integration required that applications used the discovery method to list the documents they can exchange. Nowadays, ION offers APIs to configure ION models. Applications can call these APIs to add and adjust the documents that are configured on a connection point. Therefore, the discovery method is optional. Applications can use the hasDiscovery property to indicate whether the discovery method is implemented by them. The default value is true.

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

    When ION sends a multipartMessage, the message includes the documentName and logicalId HTTP parameters. This way, an application can route the message internally without having to parse the actual message.

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