KB180978225: WebCenter - How to call an External Web Service from the Attributes

Description

For some advanced Attribute forms, it may be required to collect information from an external server of send information to it.

Normally, web calls can be done using AJAX in the CustomFormExtension.js file. However, because of security reasons, most browsers will not let you call an External server with AJAX. 

WebCenter 16 introduces the possibility to go to an external system indirectly using the External Web Connections extensions. This article will show an example of how an external call can be made.

Procedure

Follow these steps:

1. Make use of the CustomFormExtensions.js file. This can be found on the Web Server in: <Installation folder>/tomcat/webapps/<Instance name>/custom/JavaScript.

2. Add a function that makes the Web Call. The example given below will allow the Attribute Category to make a SOAP call. Things to keep in mind for this function:

   1. Make a call to GetExternalWebInfo.jsp and add the needed parameters in FormData object.

   2. Add the target of the call by refering to an existing External Web Connection, using the parameter ExternalWebConfigName.

   3. Add correct request method (GET vs POST) using the parameter requestmethod. GET is the default option. 

   4. If extra request headers are needed (e.g.: SOAPAction for SOAP calls), add them using the parameter requestheader. There can be multiple request headers and they should be added in the format <headername>:<headervalue>.
   5. If needed, add a request body using parameter requestbody.
   6. if needed, parameters can be added to the URL dynamically, using requestparams.

   7. Define the response type using the parameter responsetype, which should be a valid MIME type, e.g.: application/json, text/html.
      SOAP example

      Soap call example

      soap : function(att) { 
      	var attr1 = att['attr1'];
      	var attr2 = att['attr2'];
      	var attr3 = att['attr3'];
      	
      	var body = '<?xml version="1.0" encoding="utf-8" standalone="no"?>'
      	+ '<soap:Envelope schema_params>'
      		+ '  <soap:Body>' 
      		+ '    <Operation xmlns=\"http://something.org/\">" 
      		+ '      <Request>"
      		+ '		   <data>" 
      		+ '			  <attr1>'+ attr1+'</ attr1>' 
      		+ '			  <attr2>'+ attr2+'</ attr2>' 
      		+ '			  <attr3>'+ attr3+'</ attr3>' 
      		+ '		   </data>' 
      		+ '      </Request>' 
      		+ '    </ Operation >'
      		+ '  </soap:Body>' 
      		+ '</soap:Envelope>';
      	
      var formData = new FormData();
      	formData.append("externalwebconfigname", "theService");
          formData.append("requestparams", "service="+att["service"]+"&type="+att["type"]); // will be appended to URL of externam web connection configuration
      	formData.append("requestbody", body);
      	formData.append("requestmethod", "POST");
      	formData.append("requestheader", "Content-type:text/xml; charset=utf-8");
      	formData.append("requestheader", "SOAPAction:http://something.org/Request");
      	formData.append("responsetype", "application/xml");
      
      	$.ajax({
      		url: "GetExternalWebInfo.jsp",
      		dataType : "xml",
      		type: 'POST',
      		enctype: 'multipart/form-data',
      		cache: false,
      		processData: false,
      		contentType: false,
      		data: formData,
      		async: false
      	})
      	.done(_.bind(function(data){
      		// Read and handle data
      	}, this))
      	.fail(_.bind(function(err, status, errStr){
      	   alert("Request failed: " + errStr);
      	}, this));
      }
      
      

3. Using this function in a JavaScript button will obtain information from the server. However, if you want to add the information to the attributes, you will need an extra step. Because AJAX calls are done asynchronously (answer only comes back later) and the update of the attributes are done as soon as the button's code is executed, attributes are updated before the external service information has returned. To prevent this, you can use either of these solutions:

   1. Make the AJAX call synchronous by adding a parameter async: false. This will wait until an answer returns until it continues. Side effect however, is that the browser will be blocked while waiting. This is not recommended for slow calls.

   2. Add some logic that stores the returned information when it returned and trigger a new button click to a button that can process the obtained information. For example:

      window._storedData = data;
      $('input[value="Calculate Values"][type=button]').click();

      Where a button with the label Calculate Values exists and executes a function that will read the stored data and save them in attributes.