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