Using the Service Call

Purpose

The purpose of this article is to describe 2 aspects of using the SPARK Service Call control:

1. How to pass in complex Data
2. How to use the error capability

This will be illustrated with a small sample Human service.  

Please note that this is just a simple illustration of the two above capabilities of the Service Call Control

Sample service shown at Runtime

The following image shows this service when there is NO Error

 

The following shows the result when the service call returns an error

Sample Service in Process Designer

 

The Service Call Panel contains two text fields Candidate Name and Years of Experience and a Button that will invoke the Service Call, the On Click event of this button points to the callSvc function (shown later). 

The Service Call control invokes the AJAX Service called "Process Complex SC Input" via the Attached AJAX Service configuration option, the content of which is:

var name = tw.local.data.name;
tw.local.results = "";
if (name.toUpperCase()== "ERROR")
{
   tw.local.error = new tw.object.AjaxError();
   tw.local.error.errorText = "SIMULATED ERROR";
   tw.local.error.serviceInError = "Process Complex SC Input";
   tw.local.error.errorCode = "SIMERR";
}
else
{
    var value = Number( tw.local.data.value)
    tw.local.results = name + " has " + value + " years of experience";

}

This AJAX service expects as input a NameValuePair complex type.  When the name is anything other than error, it returns a string result with the name concatenated with the years of experience as shown.  IF the name is "ERROR", an error is simulated and the service returns an AjaxError object formatted as shown.

The Service call's On Result Event invokes the following in-line function:

    ${Result}.setData(me.getResult())

which populates the Service Call Result Output control (Result).

The Service call's On Error invokes the svcError function (shown later) which populates and displays the Service Error panel shown in the runtime error illustration above.

Custom Functions

The following custom functions are contained in the Custom HTML control on the page: 

function callSvc(btn)
{
  var svcCall = page.ui.get("SvcCall");
  var name = page.ui.get("CandidateName").getData();
  var experience = page.ui.get("Experience").getData();
  page.ui.get("Result").setData("");
  page.ui.get("ServiceCallError").hide(true);
  svcCall.execute( { name: name, value: experience });
}

function svcError(svcCall)
{
  var res = svcCall.getLastError()
  page.ui.get("ServiceInError").setData(res.serviceInError)
  page.ui.get("ServiceErrorText").setData(res.errorText)
  page.ui.get("ServiceErrorCode").setData(res.errorCode)
  page.ui.get("ServiceCallError").show();
}

Function callSVC

This function is invoked when the Run Service Call button is clicked.  The operative part of this is the last line of the function where the actual AJAX service pointed to by the SPARK Service Call control is invoked using the execute function.

Recall that we said earlier that the service is expecting a NameValuePair complex type.  So the data being passed in the execute function is defined as an object with a name property and a value property containing the values entered in the CandidateName and Experience text controls respectively.

Function svcError

This function is invoked by the Service Call's On Error event.  The logic simply accesses the error object using the getLastError method, then builds the proper Error display and "shows" it to the user.

Note: Remember to leave the input of your Ajax service named 'data' but change the type of data to the object you map to the Input Value configuration object! Also, make sure to leave the output of your Ajax service named 'results', you can leave the data object of ANY, unless you'd like to specify what the output will be (e.g. Decimal).