HTTP

Execute an HTTP(s) connection and fetch the result

Available since 6.0.2 version.

Result expressed as a String (e.g. a JSON or XML result content)

Syntax

var json = utils.getWebContent(uri, settings);

Argument detail

uri: URI, expressed as http:// or https:// with or without variables, expressed as :XXX

Settings detail

Argument
Description

httpMethod

if specified, it defines the HTTP method: GET, POST, PATCH, PUT, DELETE

replaceVariables (optional) (default is true)

flag used to replace variables within the uri (variables are expressed as :XXX)

contentType (optional)

can be null); if specified, it defines the content type request (e.g. application/json)

requestBody (optional)

can be null); if specified, it defines the request body, expressed as a String (e.g. a JSON or XML content)

user (optional)

can be null); if specified, it defines the username for a BASIC authentication

pwd (optional)

can be null); if specified, it defines the password for a BASIC authentication

charSet (optional)

can be null); if specified, it defines the char set to use for the request body (req property "Accept-Charset"); if not specified, it is autodefined as "UTF-8"

headers(optional)

can be null); if specified, it defines a collection of attribute-values to pass as request headers; it is expressed as a javascript object: { attr1: value2, attr2: value2, ... }

timeout (optional) (recommended)

optional argument: can be set to null; timeout for the request, expressed in seconds; helpful when the service to invoke could be very slow

additionalSettings (optional)

optional argument: can be set to null; it is a javascript object containing additional settings

requestBody (optional)

if specified, it defines the request body, expressed as a String (e.g. a JSON or XML content)

dirId (optional)

directory id of file to send

sendFileName (optional)

file name to send

cookie (optional) (default is false)

true if you want use the cookie

log (optional) (default is true)

false if you don't want write the logs

responseWithHeaders (optional) (default is false)

add the headers in response. Example: { headers: { header1: headerValue1, header2: headerValue2...}, response: { ... },

statusCode: 200 }

Example

var url = "http://host/context?par1=abc de&par2=ab\ncd";
url = encodeURI(url);
var settings = {
	"replaceVariables": true,
	"httpMethod": 'POST',
	"contentType": null,
	"requestBody": null,
	"user": "ADMIN",
	"pwd": "ADMIN",
	"cookie": true,
	"headers": {
	    "number": 1,
	    "text": "ciao"
	},
	"additionalSettings": {	    
	},
	"log": false,
	"timeout": 10
};
utils.getWebContent(url, settings);

Execute an HTTP(s) connection and fetch the result

result expressed as a String (e.g. a JSON or XML result content)

Syntax

var json = utils.getWebContent(uri, replaceVariables, httpMethod, contentType, requestBody, user, pwd);

Details

Argument

Description

uri

URI, expressed as http:// or https:// with or without variables, expressed as :XXX

replaceVariables

flag used to replace variables within the uri (variables are expressed as :XXX)

httpMethod (optional

can be null); if specified, it defines the HTTP method: GET, POST

contentType (optional

can be null); if specified, it defines the content type request (e.g. application/json)

requestBody (optional

can be null); if specified, it defines the request body, expressed as a String (e.g. a JSON or XML content)

user (optional

can be null); if specified, it defines the username for a BASIC authentication

pwd (optional

can be null); if specified, it defines the password for a BASIC authentication

 Returns the HTTP response, expressed as a String (e.g. a JSON or XML result).

HTTP response codes included between 200 and 399 are managed as correct answers and the response is sent back through the "json" return variable.

In case of HTTP response codes above or equal to 400, an exception is fired _and the exception content would contain the message sent back by the invoked web service; consequently, it would be better to surround this instruction between try-catch.

Important note: Please pay attention to the URL definition: it must respect the HTTP syntax, which means it cannot contains special characters, such as a space or \n. In case of special characters, you will get an HTTP error when trying to use the URL. In such a scenario, use the encodeURI method:

var url = "http://host/context?par1=abc de&par2=ab\ncd";
url = encodeURI(url);
utils.getWeb...

Examples with errors:

try {
 var res = utils.getWebContent("http://www.google.it","PUT"...); // HTTP errors >= 400
}
catch(e) {
  /*
JavaException: java.lang.Exception: 411
<!DOCTYPE html>
<html lang=en>
  <meta charset=utf-8>
  <meta name=viewport content="initial-scale=1, minimum-scale=1, width=device-width">
  <title>Error 411 (Length Required)!!1</title>
  <style>
    *{margin:0;padding:0}html,code{font:15px/22px arial,sans-serif}html{background:#fff;color:#222;padding:15px}body{margin:7% auto 0;max-width:390px;min-height:180px;padding:30px 0 15px}* > body{background:url(//www.google.com/images/errors/robot.png) 100% 5px no-repeat;padding-right:205px}p{margin:11px 0 22px;overflow:hidden}ins{color:#777;text-decoration:none}a img{border:0}@media screen and (max-width:772px){body{background:none;margin-top:0;max-width:none;padding-right:0}}#logo{background:url(//www.google.com/images/branding/googlelogo/1x/googlelogo_color_150x54dp.png) no-repeat;margin-left:-5px}@media only screen and (min-resolution:192dpi){#logo{background:url(//www.google.com/images/branding/googlelogo/2x/googlelogo_color_150x54dp.png) no-repeat 0% 0%/100% 100%;-moz-border-image:url(//www.google.com/images/branding/googlelogo/2x/googlelogo_color_150x54dp.png) 0}}@media only screen and (-webkit-min-device-pixel-ratio:2){#logo{background:url(//www.google.com/images/branding/googlelogo/2x/googlelogo_color_150x54dp.png) no-repeat;-webkit-background-size:100% 100%}}#logo{display:inline-block;height:54px;width:150px}
  </style>
  <a href=//www.google.com/><span id=logo aria-label=Google></span></a>
  <p><b>411.</b> <ins>That’s an error.</ins>
  <p>POST requests require a <code>Content-length</code> header.  <ins>That’s all we know.</ins>
  */
}
try {
 var res = utils.getWebContent("http://notexistinghost"...); // this URL refers a not existing host 
}
catch(e) {
  // "e = JavaException: java.net.UnknownHostException: www.gooooooooggle.it"
}
try {
  var json = utils.getWebContent("ht://host"...); // this is an invalid URL 
  ...
}
catch(e) {
  // e = "JavaException:java.net.MalformedURLException: no protocol: xyz"
}

Execute an HTTP(s) connection and fetch the result (with headers)

result expressed as a String (e.g. a JSON or XML result content)

Syntax

var json = utils.getWebContentWithHeaders(uri, replaceVariables, httpMethod, contentType, requestBody, user, pwd, charSet,  headers);

Details

Argument

Description

uri

URI, expressed as http:// or https:// with or without variables, expressed as :XXX

replaceVariables

flag used to replace variables within the uri (variables are expressed as :XXX)

httpMethod (optional

can be null); if specified, it defines the HTTP method: GET, POST

contentType (optional

can be null); if specified, it defines the content type request (e.g. application/json)

requestBody (optional

can be null); if specified, it defines the request body, expressed as a String (e.g. a JSON or XML content)

user (optional

can be null); if specified, it defines the username for a BASIC authentication

pwd (optional

can be null); if specified, it defines the password for a BASIC authentication

charSet (optional

can be null); if specified, it defines the char set to use for the request body (req property "Accept-Charset"); if not specified, it is autodefined as "UTF-8"

headers(optional

can be null); if specified, it defines a collection of attribute-values to pass as request headers; it is expressed as a javascript object: { attr1: value2, attr2: value2, ... }

 Returns the HTTP response, expressed as a String (e.g. a JSON or XML result).

HTTP response codes included between 200 and 399 are managed as correct answers and the response is sent back throughthe "json" return variable.

In case of HTTP response codes above or equal to 400, an exception is fired and the exception content would contain the message sent back by the invoked web service; consequently, it would be better to surround this instruction between try-catch.

Important note: Please pay attention to the URL definition: it must respect the HTTP syntax, which means it cannot contains special characters, such as a space or \n. In case of special characters, you will get an HTTP error when trying to use the URL. In such a scenario, use the encodeURI method:

var url = "http://host/context?par1=abc de&par2=ab\ncd";
url = encodeURI(url);
utils.getWeb...

Example

try {

 var json = utils.getWebContentWithHeaders(...);

 ...

}

catch(e) {

 // e.message would containthe error message

}

Execute an HTTP(s) connection and fetch the result (most flexible version)

result expressed as a String (e.g. a JSON or XML result content)

Syntax

var json = utils.getWebContentWithSettings(
  uri, 
  replaceVariables, 
  httpMethod, 
  contentType, 
  requestBody, 
  user, 
  pwd, 
  charSet,  
  headers,
  timeout,
  additionalSettings
);

Details

Argument

Description

uri

URI, expressed as http:// or https:// with or without variables, expressed as :XXX

replaceVariables

flag used to replace variables within the uri (variables are expressed as :XXX)

httpMethod (optional

can be null); if specified, it defines the HTTP method: GET, POST

contentType (optional

can be null); if specified, it defines the content type request (e.g. application/json)

requestBody (optional

can be null); if specified, it defines the request body, expressed as a String (e.g. a JSON or XML content)

user (optional

can be null); if specified, it defines the username for a BASIC authentication

pwd (optional

can be null); if specified, it defines the password for a BASIC authentication

charSet (optional

can be null); if specified, it defines the char set to use for the request body (req property "Accept-Charset"); if not specified, it is autodefined as "UTF-8"

headers(optional

can be null); if specified, it defines a collection of attribute-values to pass as request headers; it is expressed as a javascript object: { attr1: value2, attr2: value2, ... }

timeout

optional argument: can be set to null; timeout for the request, expressed in seconds; helpful when the service to invoke could be very slow

additionalSettings

optional argument: can be set to null; it is a javascript object containing additional settings

 Returns the HTTP response, expressed as a String (e.g. a JSON or XML result).

Supported attributes by "additionalSettings" argument:

  • log: true|false - used to turn down the automatic logging of an HTTP request; helpful when you don't want to log credentials passed forward or when you have a large number of requests

  • enableSNIExtension: true|false - used to customize the SNI settings per single request

HTTP response codes included between 200 and 399 are managed as correct answers and the response is sent back throughthe "json" return variable.

In case of HTTP response codes above or equal to 400, an exception is fired and the exception content would contain the message sent back by the invoked web service; consequently, it would be better to surround this instruction between try-catch.

Important note: Please pay attention to the URL definition: it must respect the HTTP syntax, which means it cannot contains special characters, such as a space or \n. In case of special characters, you will get an HTTP error when trying to use the URL. In such a scenario, use the encodeURI method:

var url = "http://host/context?par1=abc de&par2=ab\ncd";
url = encodeURI(url);
utils.getWeb...

Execute an HTTP(s) connection and fetch the result (binary content)

result expressed as a binary content and store it into the specified file

Syntax

utils.getBinaryContent(toFile, uri, replaceVariables, httpMethod, contentType, requestBody, user, pwd);

Argument

Description

Details

toFile

absolute path including the file name, related to the local binary file to create and fill in with the result of this HTTP request

uri

URI, expressed as http:// or https:// with or without variables, expressed as :XXX

replaceVariables

flag used to replace variables within the uri (variables are expressed as :XXX)

httpMethod (optional

can be null); if specified, it defines the HTTP method: GET, POST

contentType (optional

can be null); if specified, it defines the content type request (e.g. application/json)

requestBody (optional

can be null); if specified, it defines the request body, expressed as a String (e.g. a JSON or XML content)

user (optional

can be null); if specified, it defines the username for a BASIC authentication

pwd (optional

can be null); if specified, it defines the password for a BASIC authentication

Fetches the HTTP response, expressed as a binary content and stores in to the specified file.

Important note: Please pay attention to the URL definition: it must respect the HTTP syntax, which means it cannot contains special characters, such as a space or \n. In case of special characters, you will get an HTTP error when trying to use the URL. In such a scenario, use the encodeURI method:

var url = "http://host/context?par1=abc de&par2=ab\ncd";
url = encodeURI(url);
utils.getBinaryContent(...);

Execute an HTTP(s) connection and fetch the result (binary content) optionally with a body requiest (binary content)

result expressed as a binary content and store it into the specified file

Syntax

utils.getBinaryContentWithSettings(
  toFile, 
  uri, 
  replaceVariables, 
  httpMethod, 
  contentType, 
  requestBody, 
  user, 
  pwd, 
  settings
);

Argument

Description

Details

toFile

absolute path including the file name, related to the local binary file to create and fill in with the result of this HTTP request

uri

URI, expressed as http:// or https:// with or without variables, expressed as :XXX

replaceVariables

flag used to replace variables within the uri (variables are expressed as :XXX)

httpMethod (optional

can be null); if specified, it defines the HTTP method: GET, POST

contentType (optional

can be null); if specified, it defines the content type request (e.g. application/json)

requestBody (optional

can be null); if specified, it defines the request body, expressed as a String (e.g. a JSON or XML content)

user (optional

can be null); if specified, it defines the username for a BASIC authentication

pwd (optional

can be null); if specified, it defines the password for a BASIC authentication

Fetches the HTTP response, expressed as a binary content and stores in to the specified file.

You can pass forward a String based request body as usually (using "requestBody" argument) or pass forward a binary content, using the "settings" argument, where specifying a "fromFile" attribute, filled with an absolute path (including file name) to the file to pass forward, which must be located in the server file system.

Settings can also accept an optional attribute named "headers" containing a javascript object related to the set of request headers to pass forward.

Example

var url = "http://host/context?par1=abc...";
url = encodeURI(url);
utils.getBinaryContentWithSettings(
  "/mylocalpath/outputfile", // toFile
  url, 
  false, // replaceVariables
  "POST", // httpMethod
  "application/octet-stream", // content type 
  null, // requestBody is null, since the input binary content is passed through "settings"
  null, // user
  null, // pwd
  { // settings
    fromFile: "/mylocalpath/inputfile",
    headers: { ... }
  }
);

Execute an Alfresco web script

starts with "service/xyz?..." and fetch the result, expresses as a String (e.g. a JSON or XML result content)

Syntax

var responseBody = utils.getAlfrescoWebScript(uri, replaceVariables, httpMethod, bodyRequest, charSet);

Details

Argument

Description

uri

last part of the URI to pass to the Alfresco base URL, in order to invoke a webscript, i.e. from the webscript name to required parameters

replaceVariables

flag used to define if :XXX value in the uri must be replaced by Platform defined variables

httpMethod

optional: HTTP method to use: GET, POST, etc.

bodyRequest

optional: body request to pass, expressed as a String

charSet

optional: the request/response charset to use; if not specified, Unicode charset will be used (UTF-8); possible values: UTF-8, Windows-1252

Execute an HTTP(s) connection using NLTM authentication

result expressed as a String (e.g. a JSON or XML result content)

Syntax

var json = utils.getWebContentWithNTLM(
  uri, 
  contentType, 
  httpMethod, 
  requestBody, 
  user, 
  pwd,
  workstation,
  domain,
  settings
);

Details

Argument

Description

uri

URI, expressed as http:// or https:// with or without variables, expressed as :XXX

contentType (optional)

can be null); if specified, it defines the content type request (e.g. application/json)

httpMethod (optional

can be null); if specified, it defines the HTTP method: GET, POST

requestBody (optional)

can be null); if specified, it defines the request body, expressed as a String (e.g. a JSON or XML content)

user (optional)

Windows username

pwd (optional)

Windows password

workstation

Windows workstation

domain

Windows domain

settings

optional js object; it can contain a few other settings, reported below

 Returns the HTTP response, expressed as a String (e.g. a JSON or XML result).

HTTP response codes included between 200 and 399 are managed as correct answers and the response is sent back through the "json" return variable.

In case of HTTP response codes above or equal to 400, an exception is fired an the exception content would contain the message sent back by the invoked web service; consequently, it would be better to surround this instruction between try-catch.

The "settings" js object can include the following attributes:

  • "connectionTimeout: an optional number defining the timeout for the connection

  • "headers": a js object containing request headers, e.g. required credentials

Example:

var requestBody = "...";
var json = utils.getWebContentWithNTLM(
    'https://...', 
    "application/json; charset=utf-8",
    "POST",
    requestBody,
    "username",
    "pwd",
    "workstation",
    "domain",
    null
);

Sending back through a server-side js action a response header

When executing a server-side js action, it is possibile to send back not only a JSON response but also response headers, through this method.

Syntax

utils.addResponseHeader(
  String headerName,
  String headerValue
);

Details

headerName

name of the response header (e.g. "cookie")

headerValue

the header value

Setting an attribute into the HttpSession through a server-side js action

Within the server-side js action it is also possibile to set attributes into the HttpSession object of the current user session, for example the "username" or "password" values.

Syntax

var json = utils.addSessionAttribute(
  String attrinuteName,
  String value
)

attributeName

the attribute name to set into the user session (i.e. a specific browser session)

value

the attribute value to set

PreviousEmailNextJWT

Last updated