About PUSH API
In the Etlworks Integrator, you can configure an API endpoint so that when it receives a payload from a third-party application, it will trigger the execution of a data integration Flow.
PUSH API definition
PUSH API is a variation of the user-defined API.
Steps to building a REST API
Step 1. Create an API user, which will be used to run the Flow.
Step 4. Start creating a Flow by selecting a Flow type where the source is a web service.
Only one Listener can be used in a single Flow.
Step 6. Add Mapping and parameters just like you normally would.
Step 7. Since a Flow with a Listener cannot be manually executed, it must be scheduled.
Scheduled event-driven Flows are executed when a payload arrives, as opposed to regular Flows, which are executed at specific time intervals.
By default, PUSH API endpoints return a pre-defined response. It is quite often required to return a specific response when calling a user-defined PUSH API endpoint.
Step 1. Configure HTTP Listener with
POST/PUT processing set to
Sync and not empty
POST/PUT Response File Name, for example,
Step 2. Create PUSH API.
Step 3. Create a Flow that will create a response file. Note that the file name and location must be the same as configured in Step 1.
Step 4. Combine Flows created in Steps 2 and 3 into the nested Flow.
Step 5. Schedule Flow created in Step 4.
The response file created in step 4 is automatically deleted when the API endpoint returns the response back to the caller.
Handle empty payload
It is common for the payload sent to the
PUT HTTP Listener to be empty. For example, you might be using
POST Listener as a receiver for the webhook created in a third-party application, and the third-party application might be sending a
POST request without the body. The payload is used as a source in the source-to-destination transformation, so when it is empty, the Etlworks Integrator will likely generate an exception because it will not be able to parse the payload.
To handle cases when the payload is empty, enter the default payload in the accepted Format (for example, JSON) in the
Default Payload field when configuring the HTTP Listener.
Work with HTTP headers in Request and Response
In many cases, the important information is passed in the HTTP headers. In this section of the documentation, we will show you how to get the HTTP headers passed in the request and how to return them in the response.
Get the HTTP headers passed in the request
To convert HTTP headers to the Flow variables, simply enable the
Pass request headers to the flow as parameters option when configuring the HTTP Listener.
Be aware that when HTTP headers are converted to Flow variables, the variable name will change to ALL CAPS. Example: Validation-Token > VALIDATION-TOKEN.
All Flow variables passed from the Listener are available in the Flow that has the Listener and/or, if the Flow is a part of the nested Flow, in the condition for this Flow. For example, assuming that the original header parameter is
VALIDATION-TOKEN, you can use the following code to access the value of the
VALIDATION-TOKEN in the Flow condition:
var token = scenario.getVariable('VALIDATION-TOKEN').getValue();
Return the HTTP headers in the response
The RingCentral allows configuring a webhook that will send a notification to the HTTP endpoint when someone subscribes to the service. The endpoint must be configured as a
POST with no payload but with a
VALIDATION-TOKEN passed in the HTTP request. To complete the subscription, the endpoint must return the same
VALIDATION-TOKEN in the HTTP response. The actual name of the HTTP header is Validation-Token.
Step 1. Create HTTP Listener to receive the notification from the webhook. Configure it as synchronous
Step 2. Create a Flow where the Listener created in step 1 is a source.
Step 3. Create a nested Flow and add the Flow created in step 2.
Step 4. Click
Edit and configure the Flow
Condition as following:
var token = scenario.getVariable('VALIDATION-TOKEN');
etlConfig.addResponseHeader('Validation-Token', token != null ?
token.getValue() : '');
value = true;
View inbound messages (a payload)
To view and query the inbound messages (a payload) sent to the PUSH API use the messaging app.
Test an API endpoint
For a Flow that is configured to be executed on-demand, you can create another Flow, which will send an HTTP request from the Etlworks Integrator.
Let's assume that there is a scheduled on-demand Flow that is triggered by sending a
POST request to the
https://app.etlworks.com/rest/v1/httplistener/patient endpoint, with a payload that contains a JSON document representing the patient.
For testing purposes, let's put
patient.json in the folder on the server or cloud storage.
Step 1. Create an HTTP Connection with the following parameters:
HTTP Method for Token Authentication:
Authentication Request Payload:
Authentication Request Content Type:
User: any existing Etlworks Integrator user who has permission to run Flows.
Password: password for the user.
Step 2. Create a Flow where the source Connection points to
patient.json, the source Format is JSON, the destination Connection is the Connection created in Step 1, and the destination Format is the same as the source Format.
Step 3. Manually execute the Flow created in Step 2 and watch it trigger the execution of an on-demand Flow.