Implementation and Error Handling

There are 2 methods of implementing a web service client:

• Directly in the client's browser, where calls are made from a loaded web page from a given web server, and call the Engage web services in JavaScript from that web page.
• From a server-side script or application that communicates with the Engage SOAP or REST web services endpoints.

Server-side clients

We recommend that you create your web service clients directly on your server, so that:

• There is no direct end-user visible information exchange between the browser and the Engage web service: All username and password details will be handled between your server and ours without being exposed publicly.
• Data can be queued so you can mark data as being sent successfully and removed from the queue, or rejected, to be retried.
• Errors can be logged and reviewed rather than lost
• There are no cross-site scripting security restrictions

Running scripts from your server will entail that your page may need to communicate back to your server for example via AJAX that itself will call your web service client or add data into the web service client processing queue, but this is a design implementation question that depends on your specific needs and architecture.

Direct client-side clients from a browser

We do not recommend coding a web service client in JavaScript on a web page for the following reasons:

• You cannot hide your username and password that must be sent in clear text to your clients - and this data can then be indexed on Google and made available to the world.
• You cannot rely on a 3rd party web browser being able to contact the Engage web service and control the exchange of data from Engage back to the browser and to your server with a 100% success rate
• You have limited retry options if you attempt to access the Engage web services when they are not available.
• Calls could end up blocking the web page while waiting for data that your application is relying on if there is not sufficient error handling built into the JavaScript web service management code.
• You may encounter Cross Site Scripting errors where the browser itself is forbidding your page to make calls to the Engage Webservice

Due to these 5 points above, we do not recommend implementing SOAP or REST web service calls directly within your public web pages that your service to your clients: Some of your calls will be made in "fire-and-forget" mode, meaning that you believe that the web service call has been made, but you have no absolute control on if the call was made, was successful and you have no means of retrying if there was an error that your code could not intercept, or because the page was closed.

If you are planning a mass import of data via the REST or SOAP web service, you should consider using parallelized processing, submitting multiple requests in parallel. This allows calls to be balanced across our API cluster rather than sequentially sent to a single server.

This avoids contention issues where if a call is handled slowly, it does not slow down your overall import process as it would if you were processing the data sequentially. As noted above, you should also have a queuing and logging mechanism to allow retry in case of timeouts or unavailability due to maintenance operations.

Alternative mass import method - Control XML

If you are attempting to mass-import a very large amount of data sequentially, the API methods may not be the most adequate answer, and our Control XML file import method may be better adapted to your needs. After generating a Control XML "capsule" containing processing information and client details, this can be uploaded to an SFTP server, and you can then call a pre-existing Control XML processing task to pick up and import the file via either our SOAP or REST API on an ad-hoc basis or set the processing task to run automatically at a given time.

Certain API calls as per the documentation may respond with an HTTP 204 response, meaning "successful, but no further response details are required", others will provide you with an HTTP response code indicating success or failure, and can also provide further details in the response body. You should process these responses, especially failure conditions, as the information provided will be very useful in determining the root cause of any problem, and if there is a problem with the submitted API request or a problem with how Mapp is handling the request.

For this reason, we do not recommend creating a "fire-and-forget" API on the assumption that 100% of calls work 100% of the time, as you will have no way of identifying or handling any error conditions.

Due to this, a web service client must check the response of our web service and manage a retry of the call if an error condition is encountered that can be retried.

We also strongly recommend implementing some method to trace the execution of any batch mode API clients, to ensure you can react to any general execution issues in a timely manner, for example, to note if a process is not functioning at all, and to react to any specific processing issues, for example, calls that unexpectedly fail, as per the recommended API Retry Process documented below.

API Retry Process

We recommend the following retry procedures depending on the API used

For API 2.0

• Ensure that you have set an adequate timeout for your calls (some calls can return a lot of data and can take more than 30 seconds to respond).
• Run initial call
• On error: Log that a retry is to be attempted after at least 30 seconds
• On subsequent error: Log that a retry is to be attempted after at least 15 minutes
• On subsequent error: Log failure and contact Technical Support.

If after the call and 2 retries fail, a definitive failure can be considered, and you should contact Technical Support for further details.

For API 1

Note that API 1 REST and SOAP are deprecated, and we recommend using or migrating to API 2.0 where possible.

• Ensure that you have set an adequate timeout for your calls (some calls can return a lot of data and can take more than 30 seconds to respond).
• Run initial call
• On error:
  • Execute a logout API call
  • Execute a login API call and get a new token
  • Retry call with new connection-token

• Log that a retry is to be attempted after at least 30 seconds
• On subsequent error: Log that a retry is to be attempted after at least 15 minutes
• On subsequent error: Log failure and contact Technical Support.

CORS is a mechanism for integrating applications with our API. It's an extension of a same-origin policy and is necessary for authorizing resource sharing with external third parties.

If you're having trouble with third-party applications, please contact your Customer Success Manager. We may be able to fix this issue by updating your settings. You will need to specify the (sub)domains in use.