Generic Adaptor (1.0) Adaptor-Routine: Generic HTTP Get Request
The routine makes a HTTP GET request to any web service to call a specified URL. This can allow the routine to trigger events and actions on remote web servers. The routine may be used for polling, to make sure a remote web service is running, or may be used to start a process or begin processing data within the called web service. The routine calls a URL just like if it was being placed within the address bar of a web browser.
Topics |
Prerequisites
Please make sure you understand how the HTTP protocol works, and have read the following linked documents before proceeding on.
How It Works
The routine makes a HTTP request to call a configured URL using the HTTP GET method, similar to placing a URL into a web browser. The routine can optionally check to see if a response has been returned from the calling web service, and then additionally check that the correct response is returned, and further check to see if any data returned from the response is correct.
Routine steps:
- Generate URL to call by joining the HTTP protocol and Request setting values together
- Create a HTTP request and send it through the computer's network. The network may forward the request through its local network or through to the internet, depending on the address set in the URL.
- The routine waits for for a HTTP response from the web service being called.
- A web service listening at the URL's address receives the HTTP request and processes it, returning a HTTP response to the routine in the Connector.
- Optionally, the routine checks that HTTP response code matches the expected response code. If the incorrect response code is returned then the routine reports that the routine failed.
- Optionally, the routine checks that the data returned in the HTTP response body matches the expected response data, by performing a regular expression text match. If no match is found then the routine reports that the routine failed.
- The routine logs if the routine suceeded or failed.
Routine Setup: Creating a new Generic HTTP Get Request routine
- Open up the Connector application.
- In the Adaptors and Messages tab, Under the Adaptors section, click on the Settings button against a listed Generic adaptor.
- Click on the Data Routines tab.
- In the Routine Type drop down, select the Generic HTTP Get Request option, then click the Create Routine button.
- In the Routine Code text box enter a name for the routine, then press the Save Routine button.
A new routine will be created for the adaptor and appear in the Routines drop down.
Routine Setup: Configure Settings
- Click on the Settings tab of the routines.
- For each row in the settings table, click on the Setting Value field.
- Enter a setting value, then click to the next row. The setting will automatically save once the cursor exits the field.
Notes:
- In the Routine Settings section below describes what each of the settings does. Use this to configure the routine or read the settings documentation below.
- If a red icon appears in the Setting Value cell, then the cell does not accept the given input. You will need to change the value in the cell to be valid.
Routine Settings
Below are the settings that can be configured for the routine.
| Setting label | Allowed Values | Description |
|---|---|---|
| HTTP Request Protocol | Allowed Filename Characters | Protocol to use for making the HTTP request. For secure requests set to https://, or else http:// for insecure requests |
| Request URL | Allowed Filename Characters | Set the URL to make a HTTP request to. The URL may contain a domain publicly accessible over the internet, within an internal network, or with an IP address. |
| Timeout | Values: true or false | Set the amount of seconds before giving up on a response from the server being called. If the timeout is exceeded then the routine will report that it failed, regardless on whether the calling web server suceessfully processed the request or not. |
| Expected HTTP Response Code | All Valid Email Characters | Set the response code that is expected to be returned in the HTTP response. Set to 0 to ingore expecting a valid response. A typically response code is 200 - successful. If the calling web service does not returned the matching response code then the routine will report that it failed. View the list of HTTP response codes at wikipedia.org/wiki/List_of_HTTP_status_codes |
| HTTP Response Validation Regex | Allowed Filename Characters | Set a regular expression pattern that is used to match on the returned HTTP response. Leave empty to ignore matching. The regular expression will match on the data returned in the body of the HTTP response. Note that the regular expression set must be in the .NET programming language flavour. Setting a regular expression allows to specifically search for certain text in the response to ensure that expected data was sucessfully returned, such a message or unique response. |
Routine Message Meanings
Listed below are a majority of the messages that are generated by the routine, either through the connector logs, or in a scheduled routine email notification.
|
Type |
Message | Meaning |
|---|---|---|
| Error | The adaptor routine was not found or could not be run | A error has occurred that has caused the routine not to run as it should. This error occurs when no other errors have been handled. Advised us if this occurs. |
| Error | Unable to run "routine code" due to settings that cannot be found. Please notify us about this issue. | The error occurs when the settings for the routine could not be found. This is most likely to do with a update issue when the connector was last changed. Advise us if you see this message. |
| Error |
The response returned from the server does not match the expected response. Response data: http-response-body-data Matching Regular Expression: http-response-validation-regex |
The routine successfully sent a HTTP(S) request to the web service and it returned a HTTP response. In the body of the HTTP response its data did not match with the value set in the HTTP Response Validation Regex setting. Either the server returned incorrect data, or the regular expression is not correctly set to match on the response data returned. |
| Error | HTTP Response Code: returning-http-response-code doesn't match expected code: expected-HTTP response-code | The routine successfully sent a HTTP(S) request to the web service and it returned a HTTP response. However the response code did not match the response code set in the Expected HTTP Response Code setting. Either the server is returning an incorrect response code, or an response code set in the Expected HTTP Response Code setting is incorrectly set. |
| Debug | URL: http-request-url | Outputs the final URL containing the protocol joined with the request URL that is going to be called when the routine makes a HTTP request. |
| Debug | Attempting to check if the response from the server contains successful response body data. Regular Expression: http-response-validation-regex Response Body: http-response-body-data | The routine successfully sent a HTTP(S) request to the web service and it returned a HTTP response. The message shows the data returned in the HTTP response's body, and the regular expression that is will be attempting match the data on. |