Calling services from coach views

You can invoke Ajax services or service flows from within coach views. The Coach framework calls the services by using the BPM REST API in taskless mode.

Before you begin

Before you begin, the Ajax service or service flow should already be built.

About this task

To call a service in a coach view, you must specify configuration options of type Service in the coach view variable declarations and select an Ajax service or service flow 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 service using either a simple JavaScript call syntax or a REST API.

Procedure

  1. 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: The default service can optionally be overridden with a compatible service by users of this coach view.
  2. Implement the Ajax service or service flow. The service can be invoked 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 or service flow. Use the following guidelines for your event handler code.
      • Invoking the service using 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 will be serialized into JSON format using 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 containing the output(s) of the service call.
          error (function) A callback function when the service call results in error. The callback function has a single parameter containing the error information.
          Note: The service is invoked only using JSON input and output.
      • Invoking the service using a REST API:
        • Use: this.context.options.<service_option_name>.url (This contains the URL of the Ajax service or service flow.)
        • Serialize your input data in JSON format and add it to the URL using params as the parameter name.
        • Invoke the URL using an XHR call and specify the following properties appropriately: handleAs, headers, sync, load, error properties.
      Restriction: If the Ajax service or service flow uses an error end event with error code and error data, the content of the modeled error in the 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.
  3. Click Save or IBM BPM version 8570 cumulative fix 2017.03Finish Editing.

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.service_name(serviceArgs);
Tip: If the service output is a complex-type business object, the data object that you get from the response contains a property holding 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 throws an exception 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);