4.2.4.15. Http Client Gateway In – Babelway

The Http Client allows to periodically retrieve the content of the Http response to a specific URL.

Configuration file	If you fill it, only this file is used for the configuration.
Variables	Allow you to create variables with the response of the call.
Authentication Type	You can select from (Basic, Digest, Ntlm, Any, Cert, Form, OAuth 1a, OAuth 2.0 with Bearer, OAuth 2.0 with Credentials) depend on the server response.
Login url	If authentication method is (Form, OAuth 2.0 with Credentials).
Username	Username used for (Basic, Digest, Ntlm, Any) authentications. For Ntlm authentication, the username can be prepended by the domain (domain/username).
Password	Password used for (Basic, Digest, Ntlm, Any) authentications.
Preemptive Authentication	Allows to send authentication information with the first http request (to avoid making a second request). Only for (Basic, Digest, Ntlm, Any) authentications.
Trust Level	The trust level defines the level of security used in the SSL handshake. Relax = No certificate verification. Standard = trusting certificates in environment certificates as well as known CA's. Paranoiac = only trusts certificates defined in the environment certificates. Mutual = requires 2-way authentication. The default is Standard.
Valid HTTP return code	Comma separated list of expected return Http code. If the return code is not in the list, the polling generates an alert. The default is '200,201,202,204,205'.
Certificate Alias	Alias of an existing key certificate.
Login URL	If authentication method is (Form, OAuth 2.0 with Credentials).
Http Headers	You can add specific http header(s).
Form Fields	When using (Form, OAuth 2.0 with Credentials) authentication, you can add specific authentication form fields to the authentication call. This accepts metadata.
Grant Type	You can select (Client Credentials, Password, Other). Client Credentials (Scope, Username, Password). Password (Scope, Username, Password).
ContentType	You can select (application/json, FORM_URLENCODED).
OAuth1 Signature Method	If OAuth 1a authentication is used, this allows select the signature algorithm to use. You can select (HmacSHA1, HmacSHA256, SHA1withRSA, PlainText). Note that if SHA1withRSA is used, a Key alias must be selected.
OAuth1 Consumer Key	If OAuth 1a authentication is used, this allows defining the consumer key. This is mandatory.
OAuth1 Consumer Secret	If OAuth 1a authentication is used, this allows defining the consumer secret. This is optional.
OAuth1 Token	If OAuth 1a authentication is used, this allows defining the token. This is mandatory.
OAuth1 Token Secret	If OAuth 1a authentication is used, this allows defining the token secret. This is optional.
OAuth1 Key Alias	If SHA1withRSA is used, a Key alias must be selected.
OAuth1 Realm	The realm value is a string, generally assigned by the origin server, which may have additional semantics specific to the authentication scheme.
Bearer	If OAuth 2.0 with Bearer authentication is used, this allows selecting the OAUTH bearer token to use.
Calls	In this section you define one or multiple API calls.
Name	Name of a call, used in the next step to go to another call.
HTTP method	You can specify the http method to call. You can select the needed HTTP method (Post, Form Posting, Form Posting (url-encoded), Put, Get, Delete, Head, Trace, Patch). The default is Get.
URL	URL to call to create a message. Support HTTP and HTTPS protocols.
Use the global authentication	When enabled the call will be done using the global authentication defined. When disabled you can click on the "Add authentication" button then provide the authentication for this call only.
Content	Content to send, for Gateway out, if no content, we send the message. You can select (Constant, Script, Metadata).
Timeout	Timeout for connection in milliseconds. Must be between 10000 and 240000.
Post Action	In a call you can create a Post Action, to do something with the response of your request. You can choose the next step which takes the name of another call.
Condition	Condition of the creation of the message.
Response FileName	Allow you to define a FileName for the new message.
Set Metadatas	Allow you to create metadata in the Babelway context.
Connected Gateways	Connected Gateways to send the message.
Next Step	Name of the next call to run after this one.
Validate	Allow you to validate the content of the call response.
Error Message	The error message that will be generated in Babelway when the Validate fails.
Scheduling	By default, the gateway will regularly poll the messages from your Dropbox account, so that they come into Babelway a short time (less than 10 minutes) after they have been placed in your Dropbox account. You can write here a cron expression to customize the polling schedule and the preferred time zone. For easy creation of your cron expression, you can use the online cron maker tool available at : http://www.cronmaker.com/

Main Information

What is the benefit of using the new HTTP Client "Gateway In" VS old deprecated HTTP Client "Gateway In" ?

The new HTTP Client "Gateway In" allows to chain multiple HTTP calls.
For each call the user can manipulate and store part(s) or all of the received response information of the current call to be used in the second call if needed based on the HTTP call specification to be implemented.
The new HTTP Client "Gateway In" supports scripting language.

Expression

The below print screen shows the expression which the user can select one of the (Constant, Script, Metadata) values, as shown below.

Constant : When selected the user will provide a static text that will be used as a value in this field.

Script : When selected the user will provide a script code which its result will be used in this field to achieve the user logic in this section.

Note:

For security reasons we use a black box to run the Javascript code and it does not contain many libraries.
The Script engine is fully compatible with ECMAScript 5.1.

Script Functions

The "HttpClientFunctions" class have the below functions defined that can be used in the Javascript code

HttpClientFunctions.HmacMD5(String data, String key, Boolean base64Encode)
HttpClientFunctions.HmacSHA1(String data, String key, Boolean base64Encode)
HttpClientFunctions.HmacSHA256(String data, String key, Boolean base64Encode)
HttpClientFunctions.HmacSHA512(String data, String key, Boolean base64Encode)
HttpClientFunctions.base64Encode(String toEncode)
HttpClientFunctions.base64Decode(String toDecode)
HttpClientFunctions.rsaEncrypt(String toEncrypt, String publicKeyAlias)
HttpClientFunctions.xmlToJson(String data)

The below example shows the use of the HmacSHA256() function from the "HttpClientFunctions" class which will generate the base64 value of the HmacSHA256 of "message" with the key "secret", as shown below.

HttpClientFunctions.HmacSHA256('message','secret',true);

Metadata : When selected the user will provide a metadata name between curly bracket like for example {MetadataName}, This can be a user defined metadata which is generated from the current gateway.

Pattern in metadata : (only available for POST Multipart)
Name = Filename of the attachment in the multipart.
Value = Pattern to match the metadata containing the file to attach.
If one pattern matches multiple files, it is possible to put them all, if you guarantee to generate a different filename name for each one. This can be achieved by using the capturing groups of the regex in the filename. Ex: if your metadata pattern is attachment-(.*) and your filename is $1, processing with two metadata attachment-file1.csv and attachment-file2.csv will result in files, file1.csv and file2.csv.

File section

You can download and upload the configuration in XML format.

Download the current saved configuration, After configuring HTTP Client "Gateway In" and testing it successfully you can download the current configuration which is saved in XML format.
Upload the configuration in XML format, This will override the current configuration of the gateway by the provided configuration in the uploaded XML file.

Note: The download button will only download the saved configuration for the gateway, So if you have done some changes to the gateway which is not saved then all of the unsaved information will not be provided in the downloaded XML file.

Global information section

Scripting language is the scrip language used when the "Script" type is selected and the suported scripting language is JavaScript.

Variables

Allow the user to create variables which can be used in a different calls in this gateway when the expression type of "Script" is selected the result of the script will be used, as shown below.

Already defined variables (system variables)

By default Babelway will create the below system variables for each call and there values can be used when selecting the expression of type "Script".

loginResponseContent : The body of the login response, save as text.
loginResponseContentBytes : The body of the login response save as byte.
loginResponseHeaders : The headers of the login response saved as key-value pairs, To get the value of the login response header write loginResponseHeaders.get("header_name")
loginResponseCode : The status code of the login response.
responseContent : The body of the response save as text.
responseContentBytes : The body of the response save as byte.
messageContent : The content of the message out save as text.
messageContentBytes : The content of the message out save as byte.
responseHeaders : The headers of the response saved as key-value pairs, To get the value of the response header write responseHeaders.get("header_name")
responseCode : The status code of the response.
responseCookies: The cookies of the response saved as key-value pairs. To get the value of a cookies, write responseCookies.get('sessionId');

Note:

The response of the call is saved in the script system variable "responseContent" which can be used in the "Post Action" section.
The expression of type "Script" is case sensitive and you will need to make sure when using the above variables to work properly to provide them using the correct case sensitive as mentioned above.
For each call the old system variables will be overridden with the new response of the new call, So if you want to use the old system variable in other call(s) then you can save th old system variable in a user variable in the "Post Action - Validate" section.

Global Authentication and call Authentication sections

When a global authentication is defined then it can be used in the calls where the "Use the global authentication" option is enabled, as shown below.

In case for a specific call(s) you will need to use different authentication then you can create the needed authentication type from the "Authentication" section of each call, as shown below.

In case the call will not have any authentications then just make sure to disable the authentication for this call, as shown below.

Note: When using the call authentication of type "OAuth2.0 With Credentials" then you can extract the token from the authentication response and save the token in a metadata which will be used in the "Authorization" header of the call, This can be done by using the "loginResponseContent" variable and set the expression type to "Script", as shown below.

JSON.parse(loginResponseContent).access_token

Calls section

In this section you can create one call or more than one call to connect to a server to receiver or send data based on the logic you want to achieve, as shown below.

Name : This is the name of the call which is mandatory and also this name will be used in the "Post Action - Next Step" section when there are more than one call defined and each call is linked to the other call.

Timeout : Timeout for connection in milliseconds which is by default 90 seconds.

Valid HTTP return code : Comma separated list of expected return HTTP code which evaluates the response HTTP code in the header, If the return code is not in the list, the message is set in error, The default is '200,201,202,204,205'.

Post Action - Validate section

The validate section will allow us to validate the call and generate some user defined variables and user defined metadata to be used in other call(s) or channel(s).

Validate Condition : Allows you to validate the call and the call will be valid when the implemented condition result is true and when the result of condition is false the message will fail in error.

Error Message : When the result of the condition above is false the message will fail in error and the error message will be used from this field in the message details.

Variables : Allow you to create variables to be able to use in the calls in this gateway where supported.

Set metadatas : Allow you to create user defined metadata to be able to use in the calls in this gateway where supported and also will be sent the channel.

Post Action - Create message section

In order to create a message from the received response body from the current HTTP Client "Gateway In" of this channel, It is a must to use "Script" expression with the value of "responseContent" in the "Content" which will be created by default, as shown below.

Note: You can change the "responseContent" with any other system variables and also you can do some manipulation to only extract a part of the received response or even do other manipulation to achieve your request logic.

Condition : Allows you to create a condition to create a message only when the result of the condition is true so only for specific calls the message will be created.

Response FileName : Allow you to define the FileName for the new message created, If this is empty then the default is "httpresponse.txt".

Set metadatas : Allow you to create user defined metadata to be used in the channel when the message is created.

The most important is that all of the user defined metadata created in the "Post Action - Validation" section from all of the previous calls including this call will be sent to this channel and only the user defined metadata created in this "Post Action - Creat Message" section will be sent to this channel.

User Metadata Transfer Strategy : The strategy that will be used to transfer the user metadata to the new message created in the connected gateways.

Post Action - Next Step section

In order to be able to do multiple calls you will need to provide the second call name exactly in the "Next step" as you have already defined the call name in the "Name" field to be able to execute the second call after this call complete.

If the "Next step" has a typo the message will fail in error and when "Next step" is empty the execution will end and not other calls will be executed.

Beware that if you use a script, it must provide a string value for all possibly cases and an empty string for no further action:

if(responseCode == 404) "myNextStep" else ""

Babelway Message Metadata section

Allow you to update the "User comment" and "Gateway out message key" when the gateway execution is completed.

User comment metadata : Allow you to define the "User comment" of the current message, The value will be trimmed after 4096 characters.

Gateway (In/Out) Message Key : Allow you to define the "Gateway in message key" of the current message, The value will be trimmed after 100 characters.

Scheduling

Cron expression : By default, the gateway will regularly poll the messages (typically every 10-15 minutes).

You should usually not change this parameter, as the system will adapt automatically to different situations, but if you need to, you can write here the desired schedule (see http://www.cronmaker.com/ ) and choose the preferred time zone.

If you do this, please keep in mind :
The polling should not happen too often, to avoid putting too much load on your servers (especially if you have 1000s of gateways).
The polling should happen often enough so that
-The messages come quickly to the platform.
-You can recover quickly from errors (ex: if you set only one poll a day, and your server is unavailable during the polling, messages will be delayed of 24 hours, instead of a few minutes with default parameters).
-Poll runs are not too long. If they are, Babelway is allowed to cut the runs after some time, to guarantee fairness between all gateways, and prevent that one is monopolising resources for hours, and preventing others to run.

Message details Call log

To see the complete call log for each call which will help in investigation from the monitoring message details download the "httpClientGatewayFlowIn" ZIP file from the "Files" section.

For security reasons we will not log the "Authorization" header.

Note:

In the "General" page for this Gateway In you can see the "Poll now" button. When clicking on this button this will poll all of the messages immediately (and will not wait for the next defined moment).
If there is a file name provided in the "Message In" or "Message Out" which contain ~ tilde character, All browser based on Chromium will replace the ~ tilde character by the _ underscore character when you try to download the file from the Babelway interface, For more details you can check this link https://bugs.chromium.org/p/chromium/issues/detail?id=479419
You can check bunch of info like last success date, last message date …etc. by pressing on Run Info button.

The maximum file size accepted by this gateway is 100 MB.