Enable Polling for Endpoint Requests

If you run into timeout issues when working with business objects, you might want to enable polling for long-running endpoint requests.

Polling is useful in many contexts involving long-running processes, where you run the risk of breaking the client/server connection because of gateway or browser timeouts. A process can be long running, say, when your application integrates with external services, perhaps through a trigger that makes API calls to an external service. It can also involve endpoint requests that import a large volume of data from a file or from one database (development, staging, or live) to another during your application's lifecycle. Most data-related endpoint requests, including those to create, query, update, and delete business object data, are long-running processes that can benefit from polling.

You can enable polling by adding the vb-poll=true query parameter to an endpoint request URL. Now when the client makes an endpoint request, the server—instead of waiting for the request to complete and then return an HTTP response (status 200 or otherwise)—returns an HTTP response (status 202) with details of a new URL for the client to poll. This allows the server to continue processing the request in the background and the client to poll the new URL as and when it wants to find out if the request is complete and get the response (or error).

To enable polling for long-running endpoint requests:

1. Add the vb-poll=true query parameter to your endpoint request URL, for example:

   POST https://server.example.com/ic/builder/rt/hrapp/1.0/resources/data/Employee?vb-poll=true

2. When you receive the HTTP response with status 202, look for the Polling-Location header whose value will be the polling URL.

   The client can poll this URL and check the response, which will either contain the Polling-Location header to indicate that the process is still running, or will be the final response.

   When the long-running process completes, the response remains available for a limited time period, after which it is removed. The process itself is not affected by this, but the result is not available beyond this period—two minutes by default. The client should take this setting into account when determining the frequency of polling requests.