Calling Ajax services from Coach Views

You can start Ajax services from within Coach Views. Coach framework calls Ajax services with the BPM REST API in taskless mode.

Before you begin

Before you begin, make sure that the Ajax service is built.

About this task

To call an Ajax service in a Coach View, you must specify configuration options of type Service in the Coach View variable declarations and select an Ajax service as a default service to be used. The default service is the application programming interface (API) for which custom services must match. (The names and types of both inputs and outputs must match.)

You can implement the Ajax service with either a simple JavaScript call syntax or a REST API.

Procedure

Open a Coach View and then specify a Service type configuration option in the variable declarations.
1. In the Variables tab, click the plus sign next to Configuration Options. The Data section opens.
2. Select the Service type option, select the default service, and then provide a name to represent this configuration option service.
  Note: Users of this Coach View can override the default service with a compatible service.

Implement the Ajax service. An Ajax service can be started by a simple JavaScript call syntax or by a REST API.

In the Behavior tab under Event Handlers, select a method (load, unload, view, change, or collaboration) and then provide code for calling the Ajax service. Use the following guidelines for your event handler code.

Starting the service with a JavaScript call syntax:

Use: this.context.options.service_option_name(args)

Table 1. Optional properties for `args` JavaScript object
Property	Description
params	(String or Object) A JSON string that represents the input to the service. If an object is provided, it is serialized into JSON format with `JSON.stringify()`. As such, the object must be JSON serializable.
load	(function) A callback function when the service call returns successfully. The callback function has a single parameter that contains the output or outputs of the service call.
error	(function) A callback function when the service call results in error. The callback function has a single parameter that contain the error information.

Note: The service is only started with JSON input and output.

Starting the service with a REST API:
- Use: this.context.options.service_option_name.url (This option contains the URL of the Ajax service.)
- Serialize your input data in JSON format and add it to the URL with params as the parameter name.
- Start the URL with an XHR call and specify the following properties appropriately: handleAs, headers, sync, load, error properties.

Restriction: If the Ajax service uses an error end event with error code and error data, the content of the modeled error in the Ajax service is not available in either the JavaScript error property or in the REST API error property. The error message returned contains the error code but no error data.

Example

The following example is JavaScript code for a load event handler:

var _this = this;
var input = {text: this.context.options.service_option_name.get("value")};
var serviceArgs = {
  params: JSON.stringify(input),
  load: function(data) {
console.log("service returned: ", data);  
    // now dynamically create the img tag
    require(["dojo/_base/url"], function(url) {
       var relPath = new url(data.path).path;
       domConstruct.create("img", {src:relPath, style:"margin:5px 0px"}, _this.context.element, "first");     
    });
  },
  error: function(e) {console.log("service call failed: ", e);}
} 
this.context.options.Ajax_service_name(serviceArgs);

Tip: If the Ajax service output is a complex-type business object, the data object that you get from the response contains a property that holds the metadata of your object, for example:

{"status":"200","data":{"serviceStatus":"end","key":"@54","step":"End","data":
{"bookPlacedPosition":{"Floor":1,"Room":"101","Row":2,"@metadata":
{"dirty":true,"shared":false,"rootVersionContextID":"2064.c30905ba-8d17-41f4-
b2a8-08cbb6516ff0T","className":"PlacedPosition"}}},"actions":null}}

If you directly set the response object to your binding like the following example, the @metadata object is added in your structure:

this.context.binding.get("value").set("BookPlacedPosition",data.bookPlacedPosition);

When you trigger the boundary event to the server, the server produces an error because it does not expect the boundary event to have the @metadata object. To avoid an exception, remove the @metadata object from the response before you set it to the binding, for example:

delete data.bookPlacedPosition['@metadata'];
_this.context.binding.get("value").set("BookPlacedPosition",data.bookPlacedPosition);