Websites

Executing Internal Web Checks via Groovy Scripts

Introduction to Scripting Internal Web Checks

In addition to the settings field configuration for Internal Web Checks, you can also execute your check using a Groovy script to collect and process HTTP data. Scripted Web Checks tend to be more flexible and are particularly useful for sites that use form-based authentication with dynamic tokens.

Web Checks that are executed via Groovy script will have at least one step, which will contain a Step Request script and a Step Response processor. What makes scripted checks unique is the ability to share contexts (i.e. a dynamic token for authentication) between steps. In this way, Step One can send a GET request to collect a site's authenticating token and share the token in Step Two, which will authenticate into the site.

Note: Scripted Internal Web Checks must be run on Collector version 22.180 or higher.

When creating or editing an Internal Web Check, you'll notice that an additional tab titled Script is available under both the Request and Response sections. You can choose to manually add your request and response Groovy scripts directly into the text boxes found under both of these Script tabs or, as shown next, you can choose to first complete the fields under the Settings tab (e.g. HTTP Version, Method, Follow redirect, Authentication Required, Headers, HTTP Response Format, etc.) and then click the Generate Script from Settings button to have LogicMonitor auto-generate request and response scripts based on those settigs. The latter option produces a basic template for your Groovy scripts. (For more information on completing the fields found under the Settings tab for both the HTTP request and response, see Adding a Web Check).

Scripted Internal Web Checks

Writing a Request Script

The request script will use the Groovy API to get an HTTP response.

API Commands for a Request Groovy Script

The following table lists the API commands you may use in your request Groovy script.

API

Return type

Description

Default Value (if applicable)

setAuthType(AuthType authType) LMRequest Set the Authentication Type
setUsername(String username) LMRequest Set the Authentication username
setPassword(String password) LMRequest Set the Authentication password
setDomain(String domain) LMRequest Set the Authentication Domain (only for NTLM Authentication)
followRedirect(boolean) LMRequest Specifies whether or not redirects should be followed True
addHeader(String name, String value) LMRequest Add the HTTP headers
userHttp1_0() LMRequest Specifies if HTTP/1.0 protocol version is used False
userHttp1_1() LMRequest Specifies if HTTP/1.1 protocol version is used True
needFullpageLoad() LMRequest Specifies if the full page needs to be loaded False
setContext(String name, Object value) LMHttpClient Set the context for the next scripts
getContext(String name) Object Get the context of the previous scripts
request(LMRequest) LMHttpClient Set the HTTP request parameters
get() StatusCode GET the Request and Return status.
get(URL) StatusCode GET the Request and Return status.
head() StatusCode Check if the URL exists
post(URL, PostDataType, String PostData) StatusCode Post the HTTP data
setProxy(String hostname, int port, String schema) LMRequest Set the HTTP proxy. Schema can only be HTTP or HTTPS
setProxy(String hostname, int port, String schema, String proxyUsername, String proxyPassword) LMRequest Set the HTTP proxy along with credentials.

 

Example Request Script Commands

  • The following Groovy syntax would be used in the first step of an Internal Web Check for a site using basic authentication.
    import com.logicmonitor.service.groovyapi.AuthType;
    import com.logicmonitor.service.groovyapi.LMRequest;
    LMRequest request = new LMRequest();
    request.setAuthType(AuthType.BASIC)
            .setUsername("username")
            .setPassword("password")
            .followRedirect(false)
            .useHttp1_0()
            .needFullpageLoad(true);
    String jsonData = "{\"name\": \"value\"}"
    return LMHttpClient.request(request)
                        .post(JSON, jsonData);
  • Example setContext() response:
    StatusCode status = LMResponse.statusMatch(200);
    LMResponse.setContext("body", Response.getBody());
    return status;
  • Example getContext() response:
    return LMResponse.plainTextmatch(Response.getContext("exampletext"))
  • Example post(PostDataType, String PostData) response:
    import status com.logicmonitor.service.groovyapi.StatusCode.*;
    import status com.logicmonitor.service.groovyapi.PostDataType.*;
    String jsonData = "{\"name\": \"value\"}";
    return LMHttpClient.post(JSON, jsonData);
  • Example request(LMRequest) response:
    import com.logicmonitor.service.groovyapi.AuthType;
    import com.logicmonitor.service.groovyapi.LMRequest;
    LMRequest request = new LMRequest();
    request.setAuthType(AuthType.BASIC)
            .setUsername("username")
            .setPassword("password")
            .followRedirect(false)
            .useHttp1_0()
            .needLoadFullPage(false);
    String jsonData = "{\"name\": \"value\"}"
    return LMHttpClient.request(request)
                        .post(JSON, jsonData);

Writing a Response Script

The response script will parse the HTTP response from your request script and apply any post processing methods (e.g. check status, check the HTTP response body, etc.).

The following table lists the API calls you may use in your request Groovy script.

API Command

Return type

Description

getStatus() Integer Return the HTTP status code
getReasonPhase() String Return the HTTP Reason Phase
getProtocolVersion() String Return the HTTP Protocol Version
getHeaders() Map (String, List [String]) Return all the headers
getHeader(String name) List Return the header value with name. If the header does not exist, a "null" response will be returned. Note that the name is case sensitive
getBody() String Return the HTTP Response Body
statusMatch(int expected) StatusCode Check if the status is as expected. If so, this will return STATUS_OK. Otherwise it will return STATUS_STATUS_MISMATCH
regexMatch(String pattern) StatusCode Check if the regex pattern matches the HTTP Response Body. If it fails, return STATUS_CONTENTS_MISMATCH
globMatch(String pattern) StatusCode Check if the regex pattern matches the HTTP Response Body. If it fails, return STATUS_CONTENTS_MISMATCH
plainTextMatch(String pattern) StatusCode Check if the HTTP Response Body contains the plain text. If it fails, return STATUS_CONTENTS_MISMATCH
jsonMatch(String path, String expectValue) StatusCode Check if the path's JSON result matches the expect value. If it fails, return STATUS_CONTENTS_MISMATCH
PathMatch(String path, String expectValue) StatusCode Check if the string's path matches the expect value. If it fails, return STATUS_CONTENTS_MISMATCH
keyValueMatch(String key, String expectValue) StatusCode Check if the returned key/Values match the expect value. If it fails, return STATUS_CONTENTS_MISMATCH
setContext(String name, Object value) void Sets the context for the next stages of your script
getContext(String) Object Return the context set in a previous script stage

 

Example Response Script

In the event that you wanted to verify a response status of "302" for a site, use the following request:

import com.logicmonitor.service.groovyapi.LMRequest;
LMRequest request = new LMRequest();
return LMHttpClient.request(request.followRedirect(false)
                        .get());

You would write your response script as follows:

return LMResponse.statusMatch(302);

Status Codes

Code

Value

Description

STATUS_OK 1 Data collection functioned as expected
STATUS_MISMATCH 11 The HTTP response status does not match
STATUS_CONTENTS_MISMATCH 12 The HTTP Request did not return expected HTTP Response body

 

Full Example Script

Below is a full two-step script used for verifying the availability of HipChat, a messaging service. This particular script uses a dynamic token shared between steps one and two of the Internal Web Check via the setContext and getContext commands in order to authenticate into the site. The post-processing method looks for the presence of "Welcome" in the HTTP response as a means of verifying the site's availability.

Full Example Script