HttpRequest

HTTP request executed directly from the server. Unlike WebService, which runs requests through web service definitions on agents, HttpRequest gives scripts full control over method, URL, headers, body, and authentication. A request can be executed standalone with execute() or within an HttpSession, which adds connection reuse and cookie handling.

HTTP requests from scripts are controlled by server configuration variable NXSL.HttpRequests.Enabled (enabled by default). A script executed on behalf of a user also requires the "Execute HTTP requests from scripts" system access right. If requests are disabled or the access right is missing, the constructor returns null. Only http and https URLs are allowed, including on redirects. Response size is limited to 16 MB and at most 10 redirects are followed. Request timeout cannot exceed NXSL.HttpRequests.MaxTimeout (default 300 seconds); NXSL.HttpRequests.DefaultTimeout (default 30 seconds) is used when no timeout is set.

Instance attributes

All attributes are writable. Settings attributes (followRedirects, maxResponseSize, proxy, timeout, userAgent, verifyHost, verifyPeer) read as null until set; headers reads as an empty hash map. Setting a settings attribute to null resets it to "not set", in which case the value from the session (when executed within a session) or the server default is used.

body: String: Request body. String values are sent as is; JsonObject, JsonArray, array, and hash map values are serialized to JSON, and Content-Type: application/json header is added unless already set. null clears the body. Body is ignored for GET and HEAD requests.

followRedirects: bool: Follow HTTP redirects. Default is true.

headers: HashMap: Request headers as hash map of header name to value. Assigning a hash map replaces all headers (assigning null removes all headers); use setHeader() to change a single header. Header names and values are validated, invalid entries and entries with null value are ignored.

maxResponseSize: int64: Maximum accepted response body size in bytes. Default and upper limit is 16 MB. If the response is larger, the request fails with an error.

method: String: HTTP method: GET, POST, PUT, DELETE, PATCH, HEAD, or OPTIONS. Can be set with a string in any letter case; assigning an unsupported method fails.

proxy: String: Proxy server URL, or null to connect directly.

timeout: int: Request timeout in seconds.

url: String: Request URL.

userAgent: String: Value of the User-Agent header. Default is NetXMS Server/<version>.

verifyHost: bool: Verify that server certificate matches the host name in the URL. Default is true.

verifyPeer: bool: Verify server certificate against trusted certificate authorities. Default is true.

Instance methods

clearAuth(): void: Reset authentication to "not set". Session authentication (if executed within a session) or no authentication will be used.

execute() ⇒ HttpResponse: Execute the request standalone, without a session.

Return

HttpResponse object. Communication errors do not raise a script error; check success and errorMessage attributes of the response.

removeHeader(name): void

Remove request header.

Table 1. Parameters
name	String	Header name.

setAuth(type, login, password): bool

Set authentication method and credentials.

Table 2. Parameters
type	String	Authentication type: `"none"`, `"basic"`, `"digest"`, `"ntlm"`, or `"bearer"` (case-insensitive).
login	String	User name. Optional, ignored for `bearer`.
password	String	Password, or bearer token for `bearer` type. Optional.

Return

true on success, false if authentication type is not recognized.

setBasicAuth(login, password): void

Set HTTP basic authentication credentials.

Table 3. Parameters
login	String	User name.
password	String	Password.

setBearerAuth(token): void

Set bearer token authentication. The token is not sent to a different host if the request is redirected.

Table 4. Parameters
token	String	Bearer token.

setHeader(name, value): bool

Set request header. Header names are matched case-insensitively.

Table 5. Parameters
name	String	Header name.
value	String	Header value, or `null` to remove the header.

Return

true on success, false if header name or value contains characters not allowed in HTTP headers.

Constructors

HttpRequest(url)

Creates new GET request for the given URL.

Table 6. Parameters
url	String	Request URL.

Return

HttpRequest object, or null if HTTP requests from scripts are disabled or the caller has no access right.

HttpRequest(method, url)

Creates new request with the given method and URL.

Table 7. Parameters
method	String	HTTP method: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, or `OPTIONS` (case-insensitive).
url	String	Request URL.

Return

HttpRequest object, or null if HTTP requests from scripts are disabled, the caller has no access right, or the method is not supported.

// Post alarm to an external ticketing system
request = new HttpRequest("POST", "https://tickets.example.com/api/v1/incidents");
request.setBearerAuth($node.getCustomAttribute("ticketing.token"));
request.timeout = 10;
request.body = {
   "title": "Node " .. $node.name .. " is down",
   "severity": "high"
};

response = request.execute();
if (response.success)
   println("Ticket created: " .. response.json.get("id"));
else if (response.errorMessage != null)
   println("Request failed: " .. response.errorMessage);
else
   println("Request rejected with status " .. response.statusCode);