Application sends a message to ION

Initialization phase: Prepare for sending messages

These methods are used by your application to get information and verify whether message processing is enabled:

  1. GET <Application>/service/ping

    Checks whether ION can reach your application and checks whether ION is authorized for your application.

    Note: Although the ION ping still returns a body, ignore that body. That body response is deprecated and will no longer be sent when API v1 is no longer supported.
  2. GET <ION>/service/versions

    Checks whether the ION version is v3 or later.

  3. GET <ION>/service/v3/<logicalid>/acceptedDocuments

    Gets, from ION, the list of documents that ION is prepared to receive from the application (lid).

    HTTP status code 200: returns a list of documents that ION accepts to receive. If the connection point is inactive or does not exist, that is, not entitled, an HTTP status code 412 is returned.

  4. If a document is missing:

    In ION Desk, open the connection point model and add the document to be 'sent by application'.

    Return to step 3.

  5. Now the sending of messages can start for document types that are accepted by ION.
Note: For ION to accept a message, at least these conditions must be met:
  • If IMS is called directly:
    • The OAuth credentials are correct, else HTTP status code 401 is returned.
    • OAuth principle is authorized for IMS, else HTTP status code 403 is returned.
  • If IMS is called through ION API: the client-Id of the ION API-authorized App is configured in the IMS through ION API connection point.
  • The fromLogicalId matches with the logical-id that is related to this OAuth principle. Else HTTP status code 403 is returned.
  • The connection point is active and the document type is defined on the documents tab of the connection point.

Send a message

This section describes the sequence when sending a message to ION.

Only start this cycle after the 'prepare for sending messages' procedure. In other words: only send messages that are accepted by ION CE.

  1. GET <ION>/service/ping

    If this is successful, then continue. Otherwise retry and raise errors.

    For the retry it is required to increase the delay between retries if the problem exists longer. Consider to aggregate the ERROR message to prevent log flooding.

    If the returned error is a 401 or 403, then stop sending messages. Instead, take corrective action, for example, by getting a correct OAuth keypair from ION.

  2. GET <ION>/service/versions

    Check whether the ION version is v3 or later.

  3. POST <ION>/service/v3/multipartMessage

    Http header X-TenantId

    If sending the message fails, based on the error code:

    1. HTTP status code 401, 403, 503, etc.: Return to the ping, step 1.
    2. HTTP status code 400: Raise an error to the admin that an invalid message was sent. Stop processing until the issue is resolved or skip this message and continue with the next.
    3. HTTP status code 412: Return to the initialization phase: Prepare for sending messages.

If the message was sent successfully, then continue with the next message, step 3.