IBM Business Automation Workflow Service Flow Execution Models From UI

Explores the different ways that a developer can invoke service flows from the UI Toolkit.

belchonock © 123RF.com

Authors: Leonard Blunt, Greg Ekaprana, Okka Sudaryanto, Diorella Mari Tom

Code Repository

Tips for BAW Toolkit Git Repository

Introduction

This article will discuss and demonstrate the different ways that a service can be invoked from within the IBM Business Automation Workflow UI. Three models of how to execute service flows will be explored, these include:

1. Task based execution of Service Flows in the context of a human service task flow (Client-Side Human Service)
2. Service Call control in Coach View, which is part of the IBM UI Toolkit
3. A variable defined in Coach View as type service

Using the Service Flow Task

Figure 1: Service Call in CSHS

The service flow task can be added by selecting the service from the list of services and dragging it on the flow (Figure 2), or by clicking the service icon on the right of the flow view and then selecting the service by using the select button from within the Implementation tab for the new service (Figure 3).

Figure 2: Drag existing service onto CSHS Flow

Figure 3: Use the service Icon and Manually configure the service to invoke in the Implementation tab

After service to invoke is set complete the Data Mapping tab by assigning the Input and Output parameters (Figure 4)

Figure 4: Data Mapping Tab

Should it be required each service also supports a pre and post script execution in the Pre & Post tab (Figure5).

Figure 5: Pre & Post Tab

Using ‘Service Call’ control in Coach View

Another way to execute a service in the Coach View is to use the ‘Service Call’ control. This control is used to invoke an Ajax service which can be called On Load, or programmatically.

Figure 6: Service Call Data Binding

Note: The Service Call control does not need to be bound for it to work.

When this control executes, it runs the service flow with Ajax access that uses two variables; one as the input data for the Ajax Service, and outputs the result bound to this control.

Remember: The input of the Ajax service must be named ‘data’, which can be of any type of data object. The output of the Ajax service must be named ‘results’, which you can leave the data object of ANY, unless you want to specify what the output will be (e.g. List, String, Decimal). To return an error, an AjaxError object should be used as an output variable named ‘error’.

The events are fired when the you get a result or error from the Ajax call. Here’s a simple example that shows how to retrieve a list of data in the database by using a Service Call control.

• Create a Service Flow that will run the Ajax service when the control is executed

Figure 7: GetCustomerInformationList Service Flow and Variables

1. Set SQL Statement

SELECT
   ID, FIRSTNAME, LASTNAME, DEPARTMENT, JOBTITLE
FROM <#= tw.env.DSN_NEWSCHEMA_NAME #>.EG_CUSTOMER_INFO

2. Execute SQL by implementing SQLConnector service

Figure 8: SQLConnector implementation to execute the SQL

• Add the Service Call control in the Coach View and set up the configuration option

Figure 9: Service Call Configuration Options

• Create a JavaScript function that will invoke the execute function of the control which runs the attached Ajax service and then call the function in ‘load’ event of the coach view.

Figure 10: Inline Javascript Function — getCustomerInfoList()

Figure 11: Load event of the coach view

Note: In this example, input data is not used in the service call as this value is optional. In case, you use input data to the service call, you need to pass the parameter to the execute function 
(e.g. _this.ui.get("svcGetCustInfoList").execute(input);)

• Create a JavaScript function that will set the output result of the service call and then call the function in ‘On result’ event of the service call control.

Figure 12: Inline Javascript Function — setCustomerInfoList()

Figure 13: On result event of Service Call control

• When an error occurs and you want to catch any errors returned from the service, create a JavaScript function that will display the error and then call the function in ‘On error’ event of the service call control.

Figure 14: Inline Javascript Function — displayAlert()

Figure 15: On error event of Service Call control

Figure 16: Service Call Example: Display Error Message

• To test, run the Service Flow Task Example CSHS and this should display the Customer Information List table in Figure 17.

Figure 17: Service Call Example — Customer Information List

Using ‘Service’ Variable in Coach View

To call a service in the coach view, you must specify the configuration options of type ‘Service’ in the coach view variable declarations and then select the 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.

Figure 18: Coach View Variable Declaration — Service Type

The service can be invoked by a simple JavaScript call syntax. Use this syntax format:

this.context.options.<service_option_name>(args)

Here is the example JavaScript call and the details of the arguments:

Figure 19: Example of JavaScript Call — addData() function

1. params — This represents the input to the service. The name of the input variable of the service flow must be the same name define in the syntax for it to execute the service.

Figure 20: Sample Syntax for params property

2. load — A callback function when the service call returns successfully. The callback function has a single parameter containing the output(s) of the service call.

Figure 21: Sample syntax for load property

AddCustomerData service flow has two outputs: results (ANY) and error (AjaxError). If the service returns successfully, the parameter (data) of ‘load’ function which contains these two outputs will be returned. Any error occurred during SQL execution will be caught and handled by the error handler service as shown in Figure 22. The catch error is set in the output variable: error (AjaxError). From the sample code, we need to make sure that the customer data is successfully added by checking if the service returns an error otherwise, continue with the processing.

Figure 22: Details of ‘load’ function

If the service returns successfully, it will refresh the list of customer data and display a success message shown in Figure 23.

Figure 23: Customer Data is successfully added

In case the service returns successfully but the customer data is not added, service will return an error and displays the error message shown in Figure 24.

Figure 24: Sample error message displayed if service call returns an error

In case the error does not occur on the SQL execution but on the Server Scripts, then this error will be handled in the ‘error’ function which will be explain on the next item.

3. error — A callback function when the service call results in error. The callback function has a single parameter containing the error information.

Figure 25: Sample syntax for error property

If an error is thrown by an error event as shown in Figure 26 or if an error occurs on any activity in the service flow which is not caught by an error event, then this triggers the ‘error’ function. From the sample code, if the service call results to an error, then it will display the error message as shown in Figure 27.

Figure 26: Shows how ‘error’ function is invoked

Figure 27: Sample error message displayed if service call results an error

Note: To use ‘this’ keyword inside the argument, you must first declare it as a global variable then use the assign variable in the argument as shown in Figure 28, otherwise it will cause an error on runtime.

Figure 28: Using ‘this’ keyword inside the argument

Summary

In choosing which way to use in executing a service flow, it would still depend on a given scenario. Here are things to remember on implementing Service Flow:

• With Client-Side Human Services, everything that is needed to show data to the user and interact with it is already loaded within the browser. At runtime, when user has done performing tasks using the user interface but there’s a post processing needed which the activity calls another service, then you can implement Service Flow task in Client-Side Human Service. With this, the user won’t need to wait for the service to complete, instead the user sees that the transaction is complete, while the service runs in the background.
• A Coach View runs within the browser and doesn’t have direct access to any server-side data. If you are building Coach Views and you want to make it reusable, you can use Service Call control and/or Service type variable to invoke an Ajax service.
• You can use Service Call control in a Coach View, if you want to implement an Ajax service call with a simple input (data) and output (result) parameter only, but if you are dealing with a complex parameters having 2 or more input/output, you can use the Service type variable to simplify the creation and passing of parameters using the JavaScript call syntax.