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:
    1. Adopt the v3/multipartMessage method.
    2. Adjust your protocol response to return "messageMethod" : "multipartMessage".
  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 Desk API methods.
    If you plan to switch to using the ION Desk APIs, you must add this property in the protocol response: "hasDiscovery" : false
  4. In IMS v2, when ION sends a multipartMessage, it actually deviates from the multipartMessage as defined in IMS swagger.
    With IMS v3 that issue is fixed, but as a consequence you receive the multipartMessage in a different format from ION.
    The differences are:
    1. 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.
    2. 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.
  5. After successfully processing a multipartMessage 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 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 multipartMessage, 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.