Guidelines for application teams that switch from v2 to v3

For a general understanding of the IMS interaction, see IMS interaction.

If your application currently supports v2, you must complete at least these steps to support v3:

  1. Adjust: When calling the ION versions method, check whether ION supports at least v3.
  2. If you still use the IMS message method, these are two options:
    1. multipartMessage method adoption:
      1. Adopt the v3/multipartMessage method.
      2. Adjust your protocol response to return "messageMethod" : "multipartMessage" and "version" : "v3".
    2. message/multipart method adoption:
      1. Adopt the v3/message/multipart method.
      2. Adjust your protocol response to return "messageMethod" : "message" and “version” : “v3”.
  3. Decide whether you are going to continue to populate documents through the discovery method. Alternatively, you can configure documents by pushing them to ION by calling the appropriate ION API methods.
    If you plan to switch to using the ION APIs, you must add this property in the protocol response: "hasDiscovery" : false
  4. In IMS v2, when ION sends a message , it actually deviates from the IMS swagger description.
    With IMS v3 that issue is fixed, but as a consequence you receive the message in a different format from ION.

    The differences are:

    • For the multipartMessage method:
      • The body for the payload now has a fixed Content-Disposition: form-data;name="MessagePayload". With v2 ION would send the Content-Disposition with the same name as used in the Content-Disposition of the parameter body.
      • The body for the parameters now has a fixed Content-Disposition: form-data;name="ParameterRequest". With v2 ION would send the Content-Disposition with the same name as used in the Content-Disposition of the payload body.
    • For the message/multipart method: The body for the payload now has a fixed Content-Disposition: form-data;name="MessagePayload". With v2 ION would send the Content-Disposition with the same name as used in the Content-Disposition of the parameter body.
  5. After successfully processing a multipartMessage or message/multipart v3 request, ION sends an HTTP status code 202 (Accepted) instead of 201 (Created). We recommend that you handle any 2xx HTTP status response as a positive response. If you check specifically for 201, you must change your implementation.
  6. Based on the multipartMessage or message/multipart, HTTP status response that is provided by ION, you now can better identify these situations:
    • The method was called incorrectly: HTTP status response 400
    • The request itself is correct but the ION side is not yet configured to receive the message: HTTP status response 412
  7. In IMS v3, the acceptedDocuments method is introduced as a replacement for the test method. With a single method you now can retrieve all documents that are accepted by a connection point in ION.
  8. When ION sends a v3 message using the multipartMessage method, it includes the documentName and logicalId as HTTP parameters. Therefore, you can use these parameters to route the incoming request instead of having to parse the parameter body. When ION sends a v3 message using the message/multipart method, it includes all the IMS message parameters as HTTP parameters.