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 (variante 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.





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 must be 'GET'.

URL (HTTPRestManager)

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

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

Example URL

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


Parameter

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 he 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)
additionalHeaders
adding additonal Headers to the Rest call"&method=GET&additionalHeaders=[NAME_OF_VARIABLE=" + variable + ";" + "NAME_OF_VARIABLE2=" + variable2 + "]"


Example

JavaScript
var URL = "https://demo.com/interface/getExampleData"; 
var USER = "$enc$-605bc19777d129d182d0c467a54b129"; 
var PASSWORD = "$enc$-eda084ca7ea688d6454add9f9e4bd84"; 

jqxhr = jQ.ajax({ 
			url: '/loom-portal/rest/HttpRestManager?hostName=' + URL + '&method=GET&authMethod=basic&user=' + USER + '&pass=' + PASSWORD + &postParameter=json, 
			type: 'GET', 
			}).done(function(data){ 
				//todo!
			}).success(function(data) { 
			var response = 	data; 
			if (checkIfVariableIsNotNullAndNotUndefinedAndNotEmpty(response)) { 
				var parsedResponse = data; 
				if (typeof parsedResponse === "string") { 
					parsedResponse = JSON.parse(data); 
				} 
				thisPointer.entity.setValue('variable', JSON.stringify(data.response)); 
				thisPointer.entity.mergeLocal(true); 
			} 
		}).fail(function(data) { //Error Handling });

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]
/** checkIfVariableIsNotNullAndNotUndefinedAndNotEmpty - returns true, if given variable is not empty and not null and not undefined - else it returns false**/ 

function checkIfVariableIsNotNullAndNotUndefinedAndNotEmpty(variable) { 
	if(variable !== null && variable !== undefined && variable !== "") { 
		return true; } 
	return false; 
}
Output Console
JSON.parse(thisPointer.entity.getValue('variable')); { name: "Name", id: "id_val" }





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 ressource 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 user names in the JavaScript file.



tim.properties

third-party-endpoint-getRESTCall={ 
	"hostName":"https://demo.com/interface/getExampleData", 
	"method":"GET"
	"authMethod":"basic", 
	"responseVariable":"demoVariable", 
	"user":"user", 
	"pass":"password",
	"postParameter": "json" 
}


JavaScript

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

DATA_SOURCE_CATALOGUE['getExampleData'] = { 
	src: Gadget.HOST + 'loom-portal/rest/HttpRestManager/getExampleData', 
	type: "json", 
	key: "key", 
	label: "label", 
	requestDataType: "application/json", 	
	requestType: "GET", 
	i18n: false, 
}; 

var callbackAfterFramework = function (thisPointer) { 

	var loadDone = $.Deferred(); 
	gadget.functions.loadAjaxDataForDropdownPromiseBased(thisPointer, $('#<<field_name>>')[0], $('#<<field_name>>').attr("data-timdatasource"), loadDone); 

	loadDone.done(function() { 
		var variable = myTKDropdownDataSet["getExampleData"]; 
		//todo! 
	}); 
}
jQ.ajax({
		url: "/loom-portal/rest/HttpRestManager/getRESTCall,
		type: "GET",
	}).done(function (data) {
		console.log('Date from interface is done loading:' + data);
	}).success(function (data) {
		// YOUR CUSTOM CODE HERE
	}).fail(function (data) {
		console.log('There has been an error loading the data from the interface:' + data);
	}).always(function () {
		console.log('The interface call is completed.);
	});

When calling the HttpRestManager via JavaScript the type must be 'GET'.

URL (HTTPRestManager)

URL: '/loom-portal/rest/HttpRestManager/<<name_of_tim.propertie_endpoint>>


Parameter

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 he 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
jQ.ajax({
		url: "/loom-portal/rest/HttpRestManager/getRESTCall,
		type: "GET",
	}).done(function (data) {
		console.log('Date from interface is done loading:' + data);
	}).success(function (data) {
		// YOUR CUSTOM CODE HERE
	}).fail(function (data) {
		console.log('There has been an error loading the data from the interface:' + data);
	}).always(function () {
		console.log('The interface call is completed.);
	});

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)

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

JavaScript
var URL = "https://demo.com/interface/getExampleData"; 
var USER = "$enc$-605bc19777d129d182d0c467a54b129"; 
var PASSWORD = "$enc$-eda084ca7ea688d6454add9f9e4bd84";
var demoVariable = "Demo";

jQ.ajax({ 
	url: '/loom-portal/rest/HttpRestManager' +
		 '?hostName=' + URL + 
		 '&method=POST' +
		 '&authMethod=basic' + 
		 '&user=' + USER + 
         '&pass=' + PASSWORD + 
		 '&responseVariable=variableNameToSaveResponseTo' +
		 '&templatePath=httpBodyGetHeadDataByDemoVariables.json' +
		 '&customVariables=[custom_variable_name=' + demoVariable + ',custom_variable_name_two=' + demoVariableTwo + ']',
	type: 'GET', 
}).done(function(data){ 
	//todo!
}).success(function(data) { 
	//todo!
}).fail(function(data) { //Error Handling });

JSON File - httpBodyGetHeadDataByDemoVariables.json (Parameter: templatePath)

JSON
{
    "search": [{
        "field": "demoField",
        "value": "${custom_variable_name}",
        "operator": "startsWith"
    }]
}

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

On this page