PUSH API: when API endpoint receives a payload it triggers execution of a data integration flow

PUSH API

In Integrator, you can configure an API endpoint so that when it receives a payload from a third-party application, it will trigger execution of a data integration flow.

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.

one listener can be used in only one flow; only one listener can be used in a single flow.

Step 6. Add mapping and parameters just like you would usually do.

Step 7. Since a flow with a listener cannot be manually executed, it must be scheduled.

the scheduled event-driven flows are executed when a payload arrives, as opposed to the regular flows, which are executed at specific time intervals.

Creating synchronously executed API endpoint which returns a user-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, {app.data}/response.json.

Step 2. Create PUSH API.

Step 3. Create a flow which will be creating a response file. Note that the filename and location must be the same as configured in step 1.

Step 4. Combine flows created in steps 2-3 into the nested flow.

Step 5. Schedule flow created in step 4.

Viewing inbound messages (a payload)

To view and query the inbound messages (a payload) sent to the PUSH API use the messaging app.

Testing an API endpoint

For a flow which is configured to be executed on-demand, you can create another flow, which will send an HTTP request, right from Integrator.

Let's assume that there is a scheduled on-demand flow which is triggered by sending a POST request to the https://app.etlworks.com/plugins/schedules/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:

• URL: https://app.etlworks.com/plugins/schedules/rest/v1/httplistener/patient.
• Authentication: token.
• Authentication URL: https://app.etlworks.com/rest/v1/token-auth/issue.
• HTTP Method for Token Authentication: POST.
• Authentication Request Payload: {"login":"{user}","password":"{password}"}
• Authentication Request Content Type: application/json.
• User: any existing Integrator user who has permission to run flows.
• Password: password for the user.
• Method: POST.

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 triggers the execution of an on-demand flow.