GetHTTP

You can use the GetHTTP function to retrieve any HTTP URL or to post content to a web page.

You can use it to:

Retrieve web pages to get information
Complete a form on a web page
Run cgi, servlets, or other server scripts on the web server
Connect through a proxy server

To enable SSL connections between Netcool®/Impact servers and external servers, refer to the Netcool/Impact Administration Guide, within the security chapter go to the 'Enabling SSL connections with external servers' topic.

Syntax

GetHTTP(HTTPHost, HTTPPort, Protocol, Path, ChannelKey, Method,
AuthHandlerActionTreeName, FormParameters, FilesToSend, 
HeadersToSend, HttpProperties)

Parameters

This function has the following parameters:

Table 1. GetHTTP function parameters
Parameter	Description
`HTTPHost`	The IP address of the host to which the call is being made.
`HTTPPort`	The port number of the host to which the call is being made.
`Protocol`	The protocol used in the call. Set the `Protocol` parameter to `http` or `https`.
`Path`	The resource path. This can include a query string but query parameters must be URL (percent) encoded.
`ChannelKey`	Can be any text. Setting the `ChannelKey` to different values for different GetHTTP invocations will mean that the different invocations will use different HTTP connections even if an existing connection is free.
`Method`	The method used with the function and the method value is `GET` by default. You can also set it to `POST`, `PUT`, `DELETE`, or `PATCH`.
`AuthHandlerActionTreeName`	The name of an authorization handler action tree. This parameter is used for compatibility with earlier versions. The default is `DefaultAuthHandler`.
`FormParameters`	Name-value pairs that are URL encoded and added to the URL being accessed.
`FilesToSend`	This parameter is used in the POST method to send files.
`HeaderToSend`	Contains HTTP Header information in name-value pairs that needs to be added to the HTTP packet that is sent. The GetHTTP function will now generate Content-Length and Transfer-Encoding headers for a HTTP request as needed. These headers are automatically applied and can no longer be customized from a policy.
`HttpProperties`	Configure the HTTP request with the following properties: `ConnectionTimeout`: Sets the timeout in milliseconds until a connection is established. The default value is `0`. `ResponseTimeout`: Sets the default socket timeout (SO_TIMEOUT) in milliseconds which is the timeout for waiting for data. A timeout value of zero is interpreted as an infinite timeout. `UserId`: The user name. `Password`: The password. `Content`: Content is generated by using methods such as creating an xml string or JSON string. You can use this property with the `POST`, `PUT`, and `PATCH` HTTP methods. `ContentType`: The default `ContentType` is `text/xml`. You can use this property with the `POST`, `PUT`, and `PATCH` HTTP methods. For a full set of properties that you can use with the `HttpProperties` parameter see Table 2.
`OauthDataSourceName`	The name of the `OAUTH` Data Source to be used in authentication.

The following table shows the full set of properties that you can use with the HttpProperties parameter.

Table 2. HttpProperties
Property	Description
`ConnectionTimeout`	Sets the timeout in milliseconds until a connection is established. The default value is `0`.
`ResponseTimeout`	Sets the default socket timeout (SO_TIMEOUT) in milliseconds which is the timeout for waiting for data. A timeout value of zero is interpreted as an infinite timeout.
`AuthenticationHost`	The host the credentials apply to. The host can be set to null if the credentials are applicable to any host.
`AuthenticationPort`	The port the credentials apply to. The port can be set to a negative value if the credentials are applicable to any port.
`AuthenticationScheme`	The authentication scheme the credentials apply to. The authentication scheme can be set to null if the credentials are applicable to any authentication scheme. Basic: Basic authentication is the original and most compatible authentication scheme for HTTP. It is also the least secure as it sends the user name and password unencrypted to the server. Digest: Digest authentication was added in the HTTP 1.1 protocol. Digest authentication is more secure than basic authentication as it never transfers the actual password across the network. Instead digest authentication uses it to encrypt a "nonce" value sent from the server.
`AuthenticationRealm`	The realm the credentials apply to. The realm can be set to null if the credentials are applicable to any realm.
`UserId`	The user name.
`Password`	The password.
`Content`	Content is generated by using methods such as creating an xml string or JSON string. You can use this property with the `POST`, `PUT`, and `PATCH` HTTP methods.
`ContentType`	The default `ContentType` is `text/xml`. You can use this property with the `POST`, `PUT`, and `PATCH` HTTP methods.
`RetryCount`	Sets the number of connection attempts. The default is `1`.
`ValidateAfterInactivity`	Defines period of inactivity in milliseconds after which a persistent connection must be re-validated prior to being re-used. The default is `200`.
`TrustCertificate`	Before a SSL connection can be established, the remote server's SSL certificate is verified against the Impact server's trust store . If no matching signer or certificate chain is found in the trust store, then the connection attempt is stopped. If TrustCertificate is set to `true`, the trust store verification check is skipped.
`AlwaysSendAuth`	If set to true, always send the Authorization header. Normally, authorization credentials are only sent in response to a challenge from the server. ¹
`UseProxy`	Use this property to specify whether you want connect to a web server using a proxy server. Valid values are: `true` and `false`. If you set this property to `true`, you must specify values for the `ProxyHost` and `ProxyPort` properties.
`ProxyHost`	If you set `UseProxy` to `true`, use this property to specify the name of the proxy host.
`ProxyPort`	If you set `UseProxy` to `true`, use this property to specify the port on the proxy host through which to make the connection.
`ProxyProtocol`	Use this property to specify which protocol to use when connecting to the proxy. Set this property to `http` (the default) or `https`. This is separate from the Protocol parameter.
`UseProxyAuth`	Use this property to specify whether you want to perform authentication with the proxy server. If you set `UseProxyAuth` to `true`, use the `ProxyUserId` and `ProxyPassword` properties to specify the user name and password to authenticate with the proxy server.
`ProxyUserId`	If you set `UseProxy` to `true`, use this property to specify the user name to log on to the proxy server.
`ProxyPassword`	If you set `UseProxy` to `true`, use this property to specify the password.
`DecryptPassword`	If the password has been encrypted using the `Encrypt()` function or the `nci_crypt` script, set this property to `true`.
`ProxyRealm`	Specify the realm if the proxy server requires one.
`ProxyAuthScheme`	Specify the authentication scheme if the proxy server requires one.
`FollowRedirect`	The function will follow redirects by default. Set this to `NEVER` to ignore the redirect and return immediately. If using a `POST` request, set this to `KEEP_POST` to preserve the `POST` method and body when traversing redirects.
`FileUploadMode`	The file upload functionality was updated in 7.1.0 Fix Pack 34 to improve compatibility with HTTP endpoints. To revert the upload functionality to its previous behavior, set this property to `legacy`.

¹ Starting in Fix Pack 7.1.0.29, the default value for AlwaysSendAuth was changed to true.

Default property values set for the GetHTTP function

Global default values for the following properties are specified for the GetHTTP function in the $IMPACT_HOME/etc/<ServerName>_server.props file:

Table 3. GetHTTP function properties
Property	Description
`impact.function.gethttp.connection.timeout`	Sets the default time (in milliseconds) to allow the connection to be made before timing out. The default is `60000` (60 seconds). Note: You can override the global default value by setting the ConnectionTimeout variable in the policy.
`impact.function.gethttp.response.timeout`	Sets the default time (in milliseconds) to allow for a response from the socket before timing out. The default is `60000` (60 seconds). Note: You can override the global default value by setting the ResponseTimeout variable in the policy.
`impact.function.gethttp.maxconnectionsperhost`	Sets the maximum number of HTTP connections allowed per host. The default is 50.

Using the GetHTTP function to retrieve a web page

The following IPL policy will retrieve a web page and log the response:

HTTPHost="maps.googleapis.com";
HTTPPort=80;
Protocol="http";
Path="/maps/api/geocode/xml?address=07002&sensor=false";   
ChannelKey="";
Method="";
AuthHandlerActionTreeName="";
FormParameters=null;
FilesToSend=null;
HeadersToSend=NewObject();
HeadersToSend["Accept-Charset"]="utf-8";
HttpProperties=NewObject();
HttpProperties.ConnectionTimeout=Int(60000);
HttpProperties.ResponseTimeout=Int(60000);
x=GetHTTP(HTTPHost, HTTPPort, Protocol, Path, ChannelKey, Method, AuthHandlerActionTreeName, FormParameters, FilesToSend, HeadersToSend, HttpProperties);
Log(x);

Log(ResultCode); // The http response code
Log(ThePage); // The response body
Log(HeadersSent);  // The http request headers
Log(HeadersReceived); // The http response headers
Log(ErrorReason);  // The error message associated with the response

Note: Make sure variables in the JavaScript policy have been defined before use. Otherwise, you will get the following exception:

'ReferenceError: "FormParameters" is not defined.'

Equivalent variables as shown in the sample should be defined in the JavaScript policy as follows:

var FormParameters=NewObject();
var FilesToSend=NewObject();
var HeadersToSend=NewObject();

The following JavaScript policy will retrieve a web page and log the response:

var HTTPHost="maps.googleapis.com";
var HTTPPort=80;
var Protocol="http";
var Path="/maps/api/geocode/xml?address=07002&sensor=false";   
var ChannelKey="";
var Method="";
var AuthHandlerActionTreeName="";
var FormParameters={};
var FilesToSend={};
var HeadersToSend=NewObject();
HeadersToSend["Accept-Charset"]="utf-8";
var HttpProperties=NewObject();
HttpProperties.ConnectionTimeout=Int(60000);
HttpProperties.ResponseTimeout=Int(60000);
var x=GetHTTP(HTTPHost, HTTPPort, Protocol, Path, ChannelKey, Method, AuthHandlerActionTreeName, FormParameters, FilesToSend, HeadersToSend, HttpProperties);
Log(x);

Log(ResultCode); // The http response code
Log(ThePage); // The response body
Log(HeadersSent);  // The http request headers
Log(HeadersReceived); // The http response headers
Log(ErrorReason);  // The error message associated with the response

Using the GetHTTP function with URL encoding

If the resource path contains a query string with non-ASCII text, you must encode the strings using the URLEncode function (see URLEncode) otherwise the request may fail with a java.net.URISyntaxException error.

HTTPHost="example.com";
HTTPPort=443;
Protocol="https";
Path="/api/now/table/incident?" +
  "sysparm_fields=" +
  URLEncode("num,assign_group,state") +
  "&sysparm_limit=500" +
  "&sysparm_offset=0" +
  "&sysparm_query=" +
  URLEncode("sys_updated_on>=1979-01-01T00:01:00.000Z^sys_created_by=test");
ChannelKey="";
Method="";
AuthHandlerActionTreeName="";
FormParameters=null;
FilesToSend=null;
HeadersToSend=NewObject();
HeadersToSend["Accept-Charset"]="utf-8";
HttpProperties=NewObject();
HttpProperties.TrustCertificate=true

x=GetHTTP(HTTPHost, HTTPPort, Protocol, Path, ChannelKey, Method, AuthHandlerActionTreeName, FormParameters, FilesToSend, HeadersToSend, HttpProperties);
Log(x);

Using the GetHTTP function to connect through a proxy server

The following example connects to a server using a proxy host.

function sendRequestToServerWithProxy(Host,Port,Protocol,Username,Password, Path, 
 body) {
   body = ""+ body;
    HTTPHost=Host;
    HTTPPort=Port;
    Log("Connecting to Server: " + Host + " on port: " + Port + " with user: " 
        + Username);
    ChannelKey="";
    Method="GET";
    AuthHandlerActionTreeName="";
    Log("Content info: " + body);
    HttpProperties=NewObject();
    HttpProperties.ConnectionTimeout=Int(60000);
    HttpProperties.ResponseTimeout=Int(60000);
    HttpProperties.Content=body;
    Headers = NewObject(); 
    Headers['Connection']='close';
    HttpProperties.UserId = Username;
    HttpProperties.Password = Password;

//optional Password can be encrypted using Encrypt() function or nci_crypt script, 
//if so the following property must be added:
HttpProperties.DecryptPassword = true;

// following section enables proxy redirect.
    HttpProperties.UseProxy = true;
    HttpProperties.ProxyHost = "localhost";  
    HttpProperties.ProxyPort = 8080; 

    GetHTTP(HTTPHost, HTTPPort, Protocol, Path, ChannelKey, Method, 
            AuthHandlerActionTreeName, null, null, Headers, HttpProperties);
  
   return  ThePage;
}  

Path="/full/path/to/server/actios?parameter1=val1&parameter2=val2";  
result=sendRequestToServerWithProxy
         ("localhost",16310,"http","username","password",Path,null); 
Log("result: " + result);   

//make sure to replace all required fields with actual values.

Authenticating with a proxy server

The following example is the same as the previous one, but it includes authenticating with the proxy server.

function sendRequestToServerWithProxy(Host,Port,Protocol,Username,Password, Path, 
 body) {
   body = ""+ body;
    HTTPHost=Host;
    HTTPPort=Port;
    Log("Connecting to Server: " + Host + " on port: " + Port + " with user: " 
        + Username);
    ChannelKey="";
    Method="GET";
    AuthHandlerActionTreeName="";
    Log("Content info: " + body);
    HttpProperties=NewObject();
    HttpProperties.ConnectionTimeout=Int(60000);
    HttpProperties.ResponseTimeout=Int(60000);
    HttpProperties.Content=body;
    Headers = NewObject(); 
    Headers['Connection']='close';
    HttpProperties.UserId = Username;
    HttpProperties.Password = Password;
    HttpProperties.AlwaysSendAuth = true;

//optional Password can be encrypted using Encrypt() function or nci_crypt script, 
//if so the following property must be added:
HttpProperties.DecryptPassword = true;

// following section enables proxy redirect 
// and includes authenticating with the proxy server.
    HttpProperties.UseProxy = true;
    HttpProperties.ProxyHost = "localhost";  
    HttpProperties.ProxyPort = 8080; 
    HttpProperties.UseProxyAuth = true;
    HttpProperties.ProxyUserId = ProxyUsername;
    HttpProperties.ProxyPassword = ProxyPassword;

    GetHTTP(HTTPHost, HTTPPort, Protocol, Path, ChannelKey, Method, 
            AuthHandlerActionTreeName, null, null, Headers, HttpProperties);  
   return  ThePage;
}  


Path="/full/path/to/server/actios?parameter1=val1&parameter2=val2";  
result=sendRequestToServerWithProxy
        ("localhost",16310,"http","username","password",Path,null); 
Log("result: " + result);   

//make sure to replace all required fields with actual values.

Authentication

Setting the HttpProperties.AuthenticationScheme is no longer required to authenticate with the GetHTTP function. When you do not specify the following variables, AuthenticationScheme, AuthenticationHost, AuthenticationPort, AuthenticationRealm, the GetHTTP function uses any scheme, any host, any port, and any realm.

Basic authentication

To do basic authentication, all you need is to assign HttpProperties the name-value pairs for a user name and password.

For example:

HttpProperties = NewObject();
HttpProperties.UserId= "<username>";
HttpProperties.Password= "<password>";

version 7.1.0.24+ Authentication using OAUTH

To use OAUTH as the authentication mechanism, use the following code snippet: Configure THE OAUTH Data Source, and use it in a GetHttp function policy:

For example:

HttpProperties = NewObject();
HttpProperties.OauthDataSourceName= "MyOAuthDataSource";

Make a POST, PUT, or PATCH request with the GetHTTP function

The GetHTTP function can send data using the HTTP POST, PUT or PATCH methods. For example, you may use these methods to send JSON content to a product with a REST (Representational State Transfer) interface.

The content can be sent either in the request body, as a file upload or as URL encoded form parameters.

The following IPL example, demonstrates how to send an HTTP PUT request using the Content property.

FormParameters = null;
FilesToSend = null;

HeadersToSend = NewObject();

HttpProperties = NewObject();
HttpProperties.Content = '{"Hello":"World"}';
HttpProperties.ContentType = 'application/json';

GetHTTP('example.com', 80, 'http', '/test', '', 'PUT', '', FormParameters, FilesToSend, HeadersToSend, HttpProperties);

If no ContentType is specified, it will default to the text/xml content type.

The following Javascript example, demonstrates how to send an HTTP PUT request using the Content property.

var FormParameters = {};
var FilesToSend = {}; 
var HeadersToSend = NewObject();

var HttpProperties = NewObject();
HttpProperties.Content = '{"Hello":"World"}';
HttpProperties.ContentType = 'application/json';

GetHTTP('example.com', 80, 'http', '/test', '', 'PUT', '', FormParameters, FilesToSend, HeadersToSend, HttpProperties);

Note: When setting the request body, the FormParameters and FormParameters parameters should be set to null in IPL or to an empty object in Javascript policies. The content body types (Content, FormParameters and FilesToSend) are exclusive of each other. When setting the request body, only one type should be set.

Submit a FORM with the GetHTTP function

The following IPL example will send an HTTP POST request using the FormParameters option:

// Override the default content type for FormParameters
HeadersToSend = NewObject();
HeadersToSend['Content-Type']='application/x-www-form-urlencoded; charset=UTF-8';

HttpProperties = NewObject();

FormParameters=NewObject();
FormParameters.firstname="name1";
FormParameters.lastname="name2";
FormParameters.emailaddress="name1@example.com";

GetHTTP('example.com', 80, 'http', '/api/post/form?action=submit', '', 'POST', '', FormParameters, null, HeadersToSend, HttpProperties);

Upload a file with the GetHTTP function

The following JavaScript example will upload files using the FilesToSend parameter:

var HeadersToSend = NewObject();
var HttpProperties = NewObject();

// Initialize to an empty object
var FormParameters = {};

// Initialize to a new object
var FilesToSend=NewObject();

// The property name for each file can be set to anything
FilesToSend.winfilenam1="/tmp/patch1.xml";
FilesToSend.imagefilename="/tmp/test.png";

// For Windows, the directory paths must be escaped
//FilesToSend.imagefilename="C:\\temp\\test.png";

GetHTTP("example.com", 80, "http", "/test/api/upload", "", "POST", "", FormParameters, FilesToSend, HeadersToSend, HttpProperties);

The different content types (Content, FormParameters and FilesToSend) are exclusive of each other. Only one type should be selected for the HTTP request.