Asynchronous exports and imports using async helpers

Contents

• Asynchronous APIs
• Async helpers
  • Async helper for export example
  • Async helper for import example
• Create an async helper
  • General
  • Configure how to check status
  • Configure how to get results
  • Configure how to process initial submission

Asynchronous APIs

Some APIs are asynchronous, meaning that they will not immediately return results for your API requests, but instead require you to periodically check for status updates while your original API request is being processed. The asynchronous API will respond to each status check request confirming if the original API request is still in progress, completed, or failed. When the original API request is completed or failed, the final results can be retrieved.

1. integrator.io submits a request to the asynchronous API resource.
2. The asynchronous API resource responds with a message that says the requested task has been started.
3. integrator.io sends async helper requests at regular intervals to check the status of the task.
4. While the asynchronous API resource processes the requested task, it also responds to each integrator.io async helper request with a message confirming that the task is still in progress until the task is done.
5. Once the task is complete, the asynchronous API resource responds to the most recent integrator.io async helper request with a confirmation that the task is complete and delivers the results of the requested task.

Async helpers

An export or import flow step can use an integrator.io async helper to easily communicate with asynchronous APIs. If your target application requires you to check the status of in-progress requests, use an async helper to send status check requests and review the responses returned from the asynchronous API resource.

Note: You can’t create async helpers for sandbox accounts.

Async helper for export example

You send an API a request to export all orders placed within the past month, but retrieving the requested data to fulfill that request requires using the asynchronous API request/response pattern outlined above. You set up an async helper to send requests at regular intervals while the asynchronous API resource gathers the previous month’s orders. The final result of these requests confirms that the external API has finished processing last month’s orders, and can return the data required to fulfill the initial request.

Async helper for import example

You send an API a POST request to import a series of large image files to a resource for website publication, but the asynchronous API resource hosting the images might require significant time to ingest and process the image data during import. You set up an async helper to send requests at regular intervals and the asynchronous API resource responds with the processing status until the images are ingested and processed. The final response from the asynchronous API resource confirms that the API has finished processing the requested task and confirms the images are ready for publication.

Create an async helper

Use the following steps to enable and create an async helper for your flow step.

1. In the Advanced section on the Create import/export (or Edit import/export) panel, check the Configure async helper checkbox.

1. Click the + icon to create a new async helper. If you have already created an Async helper for this platform, you can select it from the drop-down list. Click the pencil icon to edit an existing async helper..
2. Complete the following fields on the Create async helper page:

General

Name (required): Enter a name for the async helper that you are creating.

Configure how to check status

Status export (required): The export resource responsible for checking if the requested task is done.

Initial wait time: Enter the wait time in minutes. This is the length of time integrator.io waits before sending the first check status message to the asynchronous API. For example, if you enter the number "2", integrator.io waits for two minutes before sending the first async helper request to check if the requested task is done.

Poll wait time: Enter the wait time in minutes. This is the length of time integrator.io waits before sending subsequent poll requests. For example, if you enter the number "2", integrator.io sends a check status request every two minutes until the target application returns a message indicating that the requested task is done.

Status path (required): Enter the XML/JSON path where the In progress values, Done values, and Error Values appear in the response received. This path is applied to resources extracted from the Status Export. For example, FeedProcessingStatus.

In progress values (case sensitive): Enter the values returned by the asynchronous API that communicate that the requested task is still in progress and is not done yet. Consult the external API documentation to determine the values returned. For example, if you have sent an API request to Amazon, your in-progress values are: SUBMIT, IN PROGRESS. Use comma-separated values to define multiple in progress values.

Done values: Enter the values returned by the asynchronous API that communicate that the requested task is done. For example, for Amazon the value is “DONE”. Use comma-separated values to define multiple error values.

Done without data values: Enter the value(s) that you receive as a response from the target application after the feed processing is complete without data.

Error values (case sensitive): Enter the values returned by the asynchronous API that communicate that the API request has failed. For example, if you have sent a request to Amazon, your error values are CANCELED, ERROR. Use comma-separated values to define the multiple error values.

Configure how to get results

Result export (required): The export resource responsible for getting the final results of the originally requested task.

Note: You can’t add transforms, output filters, or preSavePage hooks to an export configured with an async helper; however, if your export’s asynchronous API requires a preSavePage hook to manipulate/filter/transform your results, build a new export in flow builder (or programmatically through the Celigo API) that has the preSavePage hook attached, return to the Configure how to get the results section of the Create async helper panel, and select it from the Result export drop-down list.

See the following video for more detailed information:

Configure how to process initial submission

Same as check status: Check this box if the initial asynchronous API response is identical to the check status requests. If the initial asynchronous API response is different from the responses that communicate in-progress status, enter the Resource path and Transform rules necessary to handle the initial response.

Resource path: This field displays if Same as check status is not checked. Specify the path for obtaining data from the initial response. You can use handlebars expressions to access all data returned in status and result messages.

Transform rules: Use this optional field if the asynchronous API resource returns responses in non-JSON formats. For example, if your target application is Amazon, the response data returns in XML format. You can convert the XML response data to JSON using Transform rules. See Transform Rules Guide for more information.

See Transform Rules Guide for more information.

Click Save to save changes.

Click Save & close to save changes and exit the async helper.

Click Close to exit the async helper without saving changes.