HTTPRestManager

Description

The HTTP Rest Manager enables the user to send requests to a server and save the returned answer in a variable and can work with the values in JS.

The following documentation shows how to call the service via different ways (variant 1 and 2). By using the functionality, the request gets forwarded via the server to prevent Cross Site Scripting and e.g. Google Chrome browser from blocking the request data due to the CORS policy.

Requirement: The execution user/server of the application (operating system user, not the currently logged-in user) must be able to reach the desired endpoint.

All these characters :/?#[]@ are part of the generic syntax for a URI (defined in RFC 3986) and must be replaced with there corresponding URL / percent encoded value. In our example [ and ] got replaced by %5B and %5D. Check out W3Schools.com if you want to check your URI

Variant 1: REST CALL in JS

Description

The REST CALL will be managed completely in the JS File. For changes, you have to update the custom-project.js file in your resource folder.

JavaScript

jqxhr = jQ.ajax({ 
			url: '/loom-portal/rest/HttpRestManager?<<?>>', 
			type: 'GET', 
		}).success(function(data){ 
			//Function to be called if the request succeeds 
		}).fail(function(data){ 
			//Error Handling 
		});

When calling the HttpRestManager via JavaScript, the type of the REST CALL must be 'GET'.

(The parameter 'method' can also be e.g. 'POST')

URL (HTTPRestManager)

URL: '/loom-portal/rest/HttpRestManager?<<PARAMETER>>

The first parameter starts with a <<?>> all others will be added by an <<&>>.

Example URL

$.ajax({
    url: '/loom-portal/rest/HttpRestManager?hostName='+URL+"&method=GET&additionalHeaders=%5B" + "NAME_OF_VARIABLE=" + variable + ";" + "NAME_OF_VARIABLE2=" + variable2 + "%5D",
    type: 'GET',
    success: function(data) {
        if (data.status && data.status == "200") {
        console.log(data);
        }
    }
});

Parameter

Parameter name	Default value	Description	Valid examples

Parameter name	Default value	Description	Valid examples
hostName		This parameter contains the URl of the requested server.	https://demo.com/interface/getExampleData
method	“POST”	This parameter determines which method will be remotely invoked. “Post” means that the server expects an input in XML format, which it will process and return. “Get” on the other hand means that the Server will send data without requiring an input.	Other possibilities are “delete”, “get”, “head”, “options”, “patch”, “post”, “put”.
postParameter		This parameter contains the input for the server in JSON-Format.	"json", "XML", "HTML", "text", "auto"
responseVariable	"SYS.HttpRestManager_response"	This parameter contains the process variable into which the server response should be saved.	demoResponseVariable
user		This parameter is only required if the server requires identification and contains the username of the user.	demoUser
pass		This parameter is only needed if the server requires an identification and contains the user's password.	demoPassword
authMethod	"basic"	This parameter is only needed if the server requires identification and contains the encryption which should be applied. One possible encryption is base64, which will be applied by setting this parameter to “basic”.	"oauth" "basic"
oAuthTokenUrl		Required only if authMethod = "oauth" URL from where to retrieve the oauth token from.
access	""	Defines which groups or users are able to call the interface and retrieve data from it. All other calls from not authorized users/groups will be denied. Multiple users/groups can be seperated via ','. Per default, the interface is callable for all users. Leave the parameter empty/undefined for unrestricted access.	group(exampleGroup), user(exampleUser)
additionalHeaders		adding additonal Headers to the Rest call	"&method=GET&additionalHeaders=%5B" + "NAME_OF_VARIABLE=" + variable + ";" + "NAME_OF_VARIABLE2=" + variable2 + "%5D"

Example

JavaScript

Do not save the user & password in the JS files without masking!

Use the encoder module to mask the data.

Url: <<serverAdress>>/encoder/ (If not available, please reach out to the defined contact person)

Function checkIfVariableIsNotNullAndNotUndefinedAndNotEmpty \[polyfill\]

Output Console

Variant 2: REST CALL with tim.properties

Description

The difference to variant 1 is that you have to configure the REST CALL in the tim.properties file located in the super resource folder (accessible with a super admin) or server file system (accessible via file access to the server). In this case, you don't have to touch the JS file if you want to change e.g. the password or other configurable parameters. As long as the REST CALL is already implemented at the JS file. The advantage of this variant is that you do not have to store passwords or usernames in the JavaScript file.

tim.properties

JavaScript

This method is only available in the extended framework (custom, no standard):

URL (HTTPRestManager)

Parameter

Parameter name	Default value	Description	Valid examples

Parameter name	Default value	Description	Valid examples
hostName		This parameter contains the URl of the requested server.	https://demo.com/interface/getExampleData
method	"POST"	This parameter determines which method will be remotely invoked. “Post” means that the server expects an input in XML format, which it will process and return. “Get” on the other hand means that the Server will send data without requiring an input.	Other possibilities are “delete”, “get”, “head”, “options”, “patch”, “post”, “put”.
postParameter		This parameter contains the input for the server in JSON-Format.	"json", "xml", "html", "text", "auto"
responseVariable	"SYS.HttpRestManager_response"	This parameter contains the process variable into which the server response should be saved.	demoResponseVariable
user		This parameter is only required if the server requires identification and contains the user name of the user.	demoUser
pass		This parameter is only needed if the server requires an identification and contains the user's password.	demoPassword
authMethod	"basic"	This parameter is only needed if the server requires identification and contains the encryption which should be applied. One possible encryption is base64, which will be applied by setting this parameter to “basic”.	"oauth" "basic"
oAuthTokenUrl		Required only if authMethod = "oauth" URL from where to retrieve the oauth token from.
access	""	Defines which groups or users are able to call the interface and retrieve data from it. All other calls from not authorized users/groups will be denied. Multiple users/groups can be seperated via ','. Per default, the interface is callable for all users. Leave the parameter empty/undefined for unrestricted access.	group(exampleGroup), user(exampleUser)

Example

JavaScript

Customizing: REST CALL with custom variables (via template file) (JS and tim.properties)

Description

The following example shows how to use custom variables in relation with a REST CALL via JSON template file. In this case, you have to add the parameter "templatePath" and "customVariables" in the REST CALL URL. In this way, you can customize your call.

JavaScript

JSON File - httpBodyGetHeadDataByDemoVariables.json (Parameter: templatePath)

JSON

The parameter templatePath refers to the root folder of the client resources (accessible via the Administration Client).