Business Rules/Logic

Application business requirements may specify actions demanding user-defined values. Field values of a selected data record are not sufficient to complete such actions.

Consider the example of implementing a custom business logic with “SQL” action. The example explains how to create a Standard Discount action that can be executed on any order in the Northwind sample application. The action will increment the discount of line items of a selected order by 1%.

The screen shot shows the application in action.

The properties of the action are defined as follows.

update "Order Details"
set Discount = 0
where 
    OrderID = @OrderID and Discount = 0.1
    
update "Order Details"
set Discount = cast(Discount as decimal(3,2)) + 0.01
where 
    OrderID = @OrderID and Discount < 0.1

If the action is selected then a simple confirmation is displayed.

A more flexible implementation of this action would allow a user to enter the exact discount that will apply to order line items. Let’s implement a confirmation that will allow capturing the discount and have it passed to the action implementation.

Start the application generator and click on the project name, click Design to activate the Project Designer. Select the Controllers tab in Designer and choose New | New  Controller option on the action bar.

Enter the following property values and click OK button.

Right-click the DiscountDialog / Fields node on the Controllers tab in Project Explorer and select the New Field option.

Enter the following property values and click OK button to save the new field.

Our “confirmation” data controller is ready.

Select Orders / Actions / ag1 (Grid) / a100 – SQL | Standard Discount action node on the Controllers tab in Project Explorer.

Change the action properties and click OK button.

update "Order Details"
set Discount = @Parameters_Discount
where 
    OrderID = @OrderID

Click Browse on the Project Designer toolbar to have the application generated. The home page of the app will open in the default web browser. Navigate to the Orders page and select Apply Discount option in the context menu of an order.

The modal form view will display. Enter a discount and click OK button to execute the action.

Any field values entered in the modal action parameter form are accessible in the “SQL” action script if your prefix the field name with “Parameters_”. Our script is referencing the entered Discount as @Parameters_Discout parameter.

If you are writing a custom business rules class or implementing shared business rules then you can reference the action parameter field by name “Parameters_Discount” as you would use any other field of a data controller.

The application client library displays a modal view if you define the confirmation property of the action as a collection of name/value arguments.

The library supports the following arguments. Only the “_controller” attribute is mandatory.

The DiscountDialog controller defines a single field. There are no commands, views, or actions.

The application framework treats data controllers that do not have a command as virtual controllers. Virtual Data Controllers are not based on a database table or view. The assumption is made that the controller has one data row only.

If the controller does not define its own views or actions then the application framework will complete the controller definition at runtime. This configuration is equivalent to the custom-defined controller shown in the picture.

The virtual data controller used for action confirmation is not different from any other data controller based on a real database table or view. You can implement business rules and custom actions that may in turn require other virtual controllers for confirmation.

Developers can apply data controller virtualization techniques to customize the data controller actions at runtime according to the custom workflow requirements. For example, the action properties Data and Confirmation may be stored in a dedicated database table and applied to data controllers based on user identity.

Complex business logic can be implemented either with custom business rules or with the help of SQL action.

Consider the following example.

End user selects an order in a sample Northwind web application.
Multiple line items (order details) must be discounted with a single
user interface command.

Let’s add the user interface command.

Select the project on the start page of application generator and click Design.

Right-click Orders / Actions / ag1 (Grid) action group node on the Controllers tab in the Project Explorer and select New Action.

Enter the following values in the action properties and click OK button.

update "Order Details"
set Discount = 0
where 
    OrderID = @OrderID and Discount = 0.1
    
update "Order Details"
set Discount = cast(Discount as decimal(3,2)) + 0.01
where 
    OrderID = @OrderID and Discount < 0.1

Click Browse on the Project Designer toolbar, navigate to the Orders page, select an existing order and choose Standard Discount option in the context menu of the order data row.

Confirm the action and the standard discount of 1% will be added to each line item that have a discount less than 10%. If you keep discounting the order details, then the discount will revert to 1% after reaching 10%.

Data view Order Details is shown after execution of SQL action Standard Discount four times.  The standard discount of 4% has been assigned to all line items that have the discount less than 10%.

You can affect multiple rows with the same definition of SQL action if you enable multiple selection in the Orders data view.

First, add a new action to the action group Orders / Actions / ag4 (ActionBar) – Edit/Delete.

Set its properties as follows and click OK button.

update "Order Details"
set Discount = 0
where 
    OrderID = @OrderID and Discount = 0.1
    
update "Order Details"
set Discount = cast(Discount as decimal(3,2)) + 0.01
where 
    OrderID = @OrderID and Discount < 0.1

this.get_selectedValues().length > 0

The JavaScript expression in the When Client Script property is evaluated at runtime in the web browser to enable the Discount option on the action bar. The Discount option becomes visible when at least one item is selected.

Note that the SQL script is identical to the script of action placed in the group with Grid scope. You may want to consider creating a stored procedure and specifying an expression in the Data property of both actions similar to the the one shown below:

execute sp_IncreaseOrderDiscount @OrderID

Next, enable multiple data row selection mode for Customers / Orders / container1 / view1 (Orders, grid1) data view node in Project Designer.

Browse to the order page of the Northwind sample application and select multiple orders.

Click Discount option on the action bar to apply a discount to the details of selected orders.

The application framework is aware of multiple selection and will perform one SQL action for each selected primary key value. 

Remember that application end users always have an option to go over each line item to rapidly change the Discount in the Data Sheet view by hand.