- Startup
- Business
- Enterprise
- On-Premise
- Add-on
About PUSH API
In Etlworks, 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 2. Create a Listener. Most likely, you will create an HTTP Listener.
Step 3. Create a Format for the payload. Most likely, you will use JSON, XML, HL7 2.x or HL7 FIHR, CSV, or Fixed Length Text as a payload.
Step 4. Start creating a Flow by selecting a Flow type where the source is a web service.
Step 5. Continue by creating a transformation where the source Connection (FROM
) is a Listener.
Only one Listener can be used in a single Flow.
Step 6. Add Mapping and parameters just like you normally would.
Step 7. The Flow 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.
Return response generated by destination connection
This section explains how to create a flow in Etlworks that uses an HTTP Listener, which acts as a user-defined API. When the listener receives a payload, it triggers an integration flow that transforms the payload and sends it to the destination. By default, the flow returns a generic response from the listener. However, if you want to return the response generated by the destination API endpoint, follow these steps:
Step 1. Configure the HTTP Listener
Set up the HTTP Listener with POST/PUT Processing set to Sync and specify a non-empty POST/PUT Response File Name. For example, use {app.data}/response.json as the file name to store the response.
Step 2. Configure the Destination HTTP Connection
In the destination HTTP connection, set the Response File Name property to the same file path used in Step 1 (e.g., {app.data}/response.json). This ensures the destination API’s response is written to the specified file.
Step 3. Create the Flow
Create a flow where the source is the HTTP Listener configured with the Response File Name, and the destination is the HTTP connection configured with the same Response File Name. This setup enables the flow to pass the destination API’s response back to the listener.
Step 4. Schedule the Flow
Schedule the flow to activate the listener endpoint. Once the listener receives a payload, the flow will process the request, and the response generated by the destination API will be returned to the client.
The response file created by the destination endpoint is automatically deleted when the API endpoint returns the response back to the caller.
Return User-defined response
By default, PUSH API endpoints return a pre-defined response. However, there are cases where you need to return a specific, user-defined response when calling a PUSH API endpoint. Follow these steps to configure a custom response:
Step 1. Configure the HTTP Listener
Set up the HTTP Listener with POST/PUT Processing set to Sync and specify a non-empty POST/PUT Response File Name. For example, use {app.data}/response.json as the file name.
Step 2. Create a flow to process the payload
Step 3. Create a Flow to Generate the Response File
Design a flow that generates the response file. The file name and location must match the POST/PUT Response File Name configured in Step 1.
Step 4. Combine Flows into a Nested Flow
Create a nested flow that combines the PUSH API flow from Step 2 and the response file generation flow from Step 3. This ensures that the response is created and sent in a coordinated manner.
5. Schedule the Nested Flow
Schedule the nested flow created in Step 4 to activate the PUSH API endpoint. This enables the endpoint to respond with the user-defined response.
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 POST
/ 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, Etlworks 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
To add the header to the HTTP response, use the following code anywhere where you can execute the JavaScript or Python code:
etlConfig.addResponseHeader('header-name', header-value);
End-to-end example
Requiremenets
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.
Solution
Step 1. Create HTTP Listener to receive the notification from the webhook. Configure it as a synchronous POST
endpoint.
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 Etlworks.
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 Etlworks API Connection with the following parameters to call the API endpoint::
-
Endpoint path
:/rest/v1/httplistener/patient
. -
Method
:POST
. -
User
: any existing Etlworks 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.
Comments
0 comments
Please sign in to leave a comment.