HTTP Listener

• Startup
• Business
• Enterprise
• On-Premise
• Add-on

When to use this Listener

The HTTP Listener is used to build user-defined APIs in the Etlworks Integrator.

Create Listener

To create a new HTTP Listener, go to Connections, select the Listeners tab, click Add Listener, and type in http in the search field. 

Parameters

Below are the available parameters.

Common parameters

• URL Pattern: the HTTP Listener endpoint. The actual endpoint URL starts with {integrator-host}/rest/v1/httplistener and ends with the provided URL. For example, if the Integrator Host is https://app.etlworks.com and the URL Pattern is /hl7/patient, the resulting endpoint URL will be https://app.etlworks.com/rest/v1/httplistener/hl7/patient, the HTTP method will be POST, and the payload will be whatever the third-party application sends to this endpoint.

The URL Pattern must be unique across all Listeners and all customers. There is a rule: one Listener - one Flow. The Etlworks Integrator validates against this rule and provides an appropriate error message if someone is trying to create an endpoint that already exists.

Learn more about how to define URL patterns.

• Method: HTTP method for the Listener. The following methods are available: GET, POST, PUT, DELETE.
• Auth Type: authorization type. The following types are available: JWT - which requires using the Etlworks Integrator authentication API to obtain an access token, and Basic - which requires a valid username and password.
• Auth Location: authorization data location. If Header is selected, the authorization data, such as access token, username, and password, must be passed as HTTP header parameters. If Query parameter is selected, the authorization data is expected to be passed as query parameters.

• Example of the basic authentication when Auth Location is a query parameter: https://app.etlworks.com/rest/v1/httplistener/hl7/patient/?Authorization=Basic%20Base64_encoded_username:password 

• Request Preprocessor script(optional): select which JavaScript script will be executed when an HTTP request with the raw message data arrives to build the HTTP response body and/or pre-process the raw message. Example:

• request.setInput(request.getInput().replace(/ /g, '-')); 
  request.setSuccess(false); value = 'Expected response';
  

As shown above, JavaScript does the following:

1. Replaces all white spaces in the request with the dash - character.

2. Sets the response to error (the 500 HTTP code will be returned to the caller).

3. Sets the response body to Expected response.

GET/Delete parameters

• Empty GET response code: select which HTTP code should be returned in case of an empty response body (nothing, empty object, or empty array). The default is 200 but the REST API standard typically assumes that 404 (not found) should be returned. Keep the default (200) unless the selected method is GET.
• Successful DELETE response code: select which HTTP code should be returned in case of a successful DELETE request. The REST API standard typically assumes that 204 should be returned.

POST/PUT parameters

• POST/PUT processing: select whether requests should be processed synchronously, or asynchronously. Only applicable when the HTTP method is POST or PUT. GET and DELETE requests are always synchronous.
• POST/PUT Response File Name: the name of the file which contains a response to the request. Only applicable when the HTTP method is POST or PUT. If nothing is entered or the file does not exist, the system will return the default response. It is possible to use {tokens}, for example {app.data} as a part of the file name. Read how to configure synchronously executed API endpoint which returns a user-defined response.
• Default Payload: the default payload that should be used in case of POST/PUT request with an empty body.
• Non strict UTF-8 payload encoding: if this option is enabled (it is disabled by default) HTTP request payload containing non-UTF-8 characters will not trigger the exception. In this case, the payload will be automatically converted to UTF-8 which theoretically can cause downstream issues so enable it with caution.  
• Queue priority: if queuing is enabled in global settings, asynchronous POST/PUT requests to this listener will have this priority when they are queued.