Scripting services

Calculations for this page are still in progress. Please wait a moment then click here to refresh the page.
[[nav]]

This section describes how to read service parameters, call services from scripts, and return XML messages. Combining all of these allows you to write new services using JavaScript.

Read service parameters

When scripts are called from services, the XML message used to call the service is available in an object of type [[scripting_reference_xpath_evaluator]]. User credentials will have been removed, so there is no danger of accessing user passwords. You can access this object using application.get('request'), and then use the XPathEvaluator methods to read this.

Example:

/**
 * Read the asset identifier parameter.
 */
var request = application.get('request');
var assetIdentifier = request.getInt('assetIdentifier');

Call a service

To call a script, use application.newServiceRequest() to create a service request of type [[scripting_reference_service_message_writer]]. Use the methods on ServiceMessageWriter to create the parameters for the call.

Invoke the service using application.service();

This returns an object of type [[scripting_reference_xpath_evaluator]]. Use the methods on this object to interpret the results.

Example:

/**
 * Find the name of the asset identified by assetIdentifier
 */
var assetRequest = application.newServiceRequest('GetAsset');
assetRequest.put('assetIdentifier',assetIdentifier);
var assetResponse = application.service(assetRequest);
var assetName = assetResponse.getString('assetName');

Returning results

Use application.newServiceResponse() to create a new object of type [[scripting_reference_service_message_writer]] for the response message. Use the methods on this object to set return parameters.

Example:

/**
 * Return the asset name
 */
var serviceResponse = application.newServiceResponse('Asset');
serviceResponse.put('assetName',assetName);

This will return something like:

<Asset>
  <errorNumber>0</errorNumber>
  <assetName>An Asset Name</assetName>
</Asset>

Error handling

If the service returns any errors, then these will be returned to the user instead of the response message. To detect errors as you go, you can use application.errorFound(), and if necessary application.resetError().

The application object will retain the first error it finds. If you test for errors, you must test after each service and reset the error if you do not want to respond to it.

The script below returns "Unknown Asset" if there is an error 102, but will return any other error.

var assetIdentifier = application.get("request").getInt("assetIdentifier");
var assetRequest = application.newServiceRequest("GetAsset");
assetRequest.put("assetIdentifier",assetIdentifier);

var assetResponse = application.run(assetRequest);

if ( application.getErrorNumber() == 102 ) {
    // Not found
    application.resetError();
    var assetName = "Unknown Asset";
    var serviceResponse = application.newServiceResponse("Asset");
    serviceResponse.put("assetName",assetName);
} else if ( !application.errorFound() ) {  // Same as getErrorNumber() == 0
    var assetName = assetResponse.getString("assetName");
    var serviceResponse = application.newServiceResponse("Asset");
    serviceResponse.put("assetName",assetName);
}

If a service return a user error (105, 108 or 109) then the error will be returned along with the service message.

[[nav]]