Business Rules/Logic

Data integrity is a primary concern of any database application. Data constraints must exist on the database and application server level, while client-side validation will make a web app more responsive and user-friendly.

For example, consider the following screenshot of the New Order Details form. End users can select any product and enter any price, quantity, and discount. The database engine will validate the constraints of the table Order Details and raise an exception when invalid data is submitted.

Let’s implement a code business rule that will perform more complex validation for Order Details controller.

Configuring Fields

Start the Project Designer. In the Project Explorer, switch to the Controllers tab and double-click on OrderDetails / Fields / ProductID* (Int32) –> Products node.

Change the following:

Press OK to save. Next, double-click on UnitPrice* (Decimal) field node.

Make the following changes:

Press OK to save.

Configuring Business Rule

Right-click on OrderDetails / Business Rules node, and press New Business Rule.

Assign the following values:

Press OK to save. On the toolbar, press Browse to generate the business rule file.

When complete, right-click on OrderDetails / Business Rules / Calculate|Insert|Update (Code / Execute) – r100 node, and press Edit Rule in Visual Studio.

Replace the code base with the following:

C#:

using System;
using System.Data;
using MyCompany.Data;

namespace MyCompany.Rules
{
    public partial class OrderDetailsBusinessRules : MyCompany.Data.BusinessRules
    {
        [Rule("r100")]
        public void r100Implementation(int? orderID,
            string orderCustomerID,
            string orderCustomerCompanyName,
            string orderEmployeeLastName,
            string orderShipViaCompanyName,
            FieldValue productID,
            string productProductName,
            string productCategoryCategoryName,
            string productSupplierCompanyName,
            FieldValue unitPrice,
            short? quantity,
            float? discount)
        {
            // 1. If the collected values are not valid then do not enforce the rule.
            //    The client library will instruct the user to correct the input.
            bool success = this.ValidateInput();
            string commandName = this.Arguments.CommandName;
            string triggerFieldName = this.Arguments.Trigger;

            // 2. Reset the base price for calculation of price limits 
            //    if the product selection has changed or if an existing
            //    data row has been selected for editing
            FieldValue oldProductID = (FieldValue)this.GetProperty("Session_ProductID"); 
            if (oldProductID == null || productID.Value.ToString() != oldProductID.Value.ToString())
            {
                decimal basePrice = Convert.ToDecimal(unitPrice.Value);
                if (!triggerFieldName.Equals("ProductID"))
                    basePrice = Convert.ToDecimal(unitPrice.OldValue);
                this.SetProperty("Session_UnitPrice", basePrice);
                this.SetProperty("Session_ProductID", productID);
                if (triggerFieldName.Equals("ProductID"))
                {
                    quantity = 1;
                    UpdateFieldValue("Quantity", quantity);
                    discount = 0;
                    UpdateFieldValue("Discount", discount);
                    Result.Focus("Quantity");
                }
            }
            // 3. Adjusting base price for an existing record
            decimal originalUnitPrice = (decimal)this.GetProperty("Session_UnitPrice");
            if (originalUnitPrice == null || originalUnitPrice == 0)
            {
                originalUnitPrice = Convert.ToDecimal(unitPrice.OldValue);
                this.SetProperty("Session_UnitPrice", originalUnitPrice);
            }
            // 4. validate Unit Price field
            if (success)
            {
                decimal minPrice = originalUnitPrice;
                decimal maxPrice = originalUnitPrice * (decimal)1.05;
                success = unitPrice != null;
                if (!success)
                    Result.Focus("UnitPrice", "Please enter the price.");
                else
                {
                    decimal price = Convert.ToDecimal(unitPrice.Value);
                    success = minPrice <= price && price <= maxPrice;
                    if (!success)
                        Result.Focus("UnitPrice", "This price must be between {0:c} and {1:c}", 
                            minPrice, maxPrice);
                }
            }
            // 5. validate Quantity field
            if (success)
            {
                success = quantity != null && quantity > 0;
                if (!success)
                    Result.Focus("Quantity", "The quantity must be greater than zero.");
            }
            // Validate Discount field
            if (success)
            {
                // 6. If value > 1, then convert value to percentage
                if (discount > 1)
                {
                    discount = discount / 100;
                    UpdateFieldValue("Discount", discount);
                }
                // 7. Confirm that Discount is between 0.00 and 0.99
                success = discount != null && discount >= 0.00 && discount <= 0.99;
                if (!success)
                    Result.Focus("Discount", 
                        "The discount must be between 0.00 and 0.99 (0% - 99%).");
            }
            // 8. Wrapping Up
            if (commandName == "Calculate" || !success)
                this.PreventDefault();
        }
    }
}

Visual Basic:

Imports MyCompany.Data
Imports System
Imports System.Data

Namespace MyCompany.Rules
    
    Partial Public Class OrderDetailsBusinessRules
        Inherits MyCompany.Data.BusinessRules
        <Rule("r100")> _
        Public Sub r100Implementation(ByVal orderID As Nullable(Of Integer),
                                      ByVal orderCustomerID As String,
                                      ByVal orderCustomerCompanyName As String,
                                      ByVal orderEmployeeLastName As String,
                                      ByVal orderShipViaCompanyName As String,
                                      ByVal productID As Nullable(Of Integer),
                                      ByVal productProductName As String,
                                      ByVal productCategoryCategoryName As String,
                                      ByVal productSupplierCompanyName As String,
                                      ByVal unitPrice As FieldValue,
                                      ByVal quantity As Nullable(Of Short),
                                      ByVal discount As Nullable(Of Single))
            ' 1. If the collected values are not valid then do not enforce the rule.
            '    The client library will instruct the user to correct the input.
            Dim success As Boolean = Me.ValidateInput()
            Dim commandName As String = Me.Arguments.CommandName
            Dim triggerFieldName As String = Me.Arguments.Trigger

            ' 2. Reset the base price for calculation of price limits 
            '    if the product selection has changed or if an existing
            '    data row has been selected for editing
            If Me.GetProperty("Session_ProductID") Is Nothing OrElse
                productID.Value.ToString() <> Me.GetProperty("Session_ProductID").ToString() Then
                Dim basePrice As Decimal = Convert.ToDecimal(unitPrice.Value)
                If Not triggerFieldName.Equals("ProductID") Then
                    basePrice = Convert.ToDecimal(unitPrice.OldValue)
                End If
                Me.SetProperty("Session_UnitPrice", basePrice)
                Me.SetProperty("Session_ProductID", productID)
                If triggerFieldName.Equals("ProductID") Then
                    quantity = 1
                    UpdateFieldValue("Quantity", quantity)
                    discount = 0
                    UpdateFieldValue("Discount", discount)
                    Result.Focus("Quantity")
                End If
            End If
            ' 3. Adjusting base price for an existing record
            Dim originalUnitPrice As Nullable(Of Decimal) =
                CDec(Me.GetProperty("Session_UnitPrice"))
            If originalUnitPrice Is Nothing OrElse originalUnitPrice = 0 Then
                originalUnitPrice = Convert.ToDecimal(unitPrice.OldValue)
                Me.SetProperty("Session_UnitPrice", originalUnitPrice)
            End If
            ' 4. validate Unit Price field
            If success Then
                Dim minPrice As Decimal = originalUnitPrice
                Dim maxPrice As Decimal = originalUnitPrice * CDec(1.05)
                success = unitPrice IsNot Nothing
                If Not success Then
                    Result.Focus("UnitPrice", "Please enter the price.")
                Else
                    Dim price As Decimal = Convert.ToDecimal(unitPrice.Value)
                    success = minPrice <= price AndAlso price <= maxPrice
                    If Not success Then
                        Result.Focus("UnitPrice",
                                     "This price must be between {0:c} and {1:c}",
                                     minPrice, maxPrice)
                    End If
                End If
            End If
            ' 5. validate Quantity field
            If success Then
                success = quantity IsNot Nothing AndAlso quantity > 0
                If Not success Then
                    Result.Focus("Quantity", "The quantity must be greater than zero.")
                End If
            End If
            ' Validate Discount field
            If success Then
                ' 6. If value > 1, then convert value to percentage
                If discount > 1 Then
                    discount = discount / 100
                    UpdateFieldValue("Discount", discount)
                End If
                ' 7. Confirm that Discount is between 0.00 and 0.99
                success = discount IsNot Nothing AndAlso discount >= 0.0 AndAlso discount < 1
                If Not success Then
                    Result.Focus("Discount",
                                 "The discount must be between 0.00 and 0.99 (0% - 99%).")
                End If
            End If
            ' 8. Wrapping Up
            If commandName = "Calculate" OrElse Not success Then
                Me.PreventDefault()
            End If
        End Sub
    End Class
End Namespace

The business rule is written in C# or Visual Basic. The fields are present in the arguments of the method. Changing the data type of the argument to FieldValue allows accessing additional properties of the field.

Click Browse button on the toolbar, sign in as admin/admin123% and navigate to Customers / Order Details page.

The business rule will be engaged as soon as a new record is being entered or an existing one is modified. The business rule will react to changes to the fields specified in the Context Fields property of UnitPrice when Calculate action is raised. The field UnitPrice depends on itself. It does not matter which application field is used to trigger the Calculate action. The only field that cannot trigger the calculation is ProductID. The Context Fields of a lookup will provide filtering information for the lookup window. Any field names in the Context Fields of ProductID will make the client library treat them as context filters, which will prevent users from seeing any products in the lookup window.

Business Rules provide a true abstraction level and separation from the user interface. The business rule is not actively selecting user interface elements to collect input values, which allows flexible modification of the presentation and the rule itself. The same business rule can service any number of data controller views regardless of the view types.

There are eight distinct steps in the business rule.

1. Initial Input Validation

The client library automatically performs basic validation of the entered values. The rule declares success variable, which is used to determine if any special validation needs to be applied to the fields.

The command causing the rule to execute is stored in commandName variable. The possible values are Calculate, Insert, or Update.

The rule also makes a note of the field that has triggered the business rule. The trigger field name will be known only when Calculate action is raised. The possible triggers are ProductID, UnitPrice, Quantity, and Discount.

This is an example of a basic validation that does not require custom coding.

2. Determination of The “Base” Price

The rule will memorize the last ProductID and UnitPrice in the properties of the data view instantiated on the browser page. The base price is used to ensure that users do not enter lesser values and to prevent the price inflation by more than 5%. If the product has just been changed, then the rule will reset values of fields Quantity and Discount and set the focus on the Quantity field.

This screen shot shows the form after the product selection.

3.  Adjusting Base Price for Existing Records

If the user is editing an existing record then the old (original) value of the UnitPrice is memorized in the data view properties.

4. Price Validation

The business rule figures the minimum and maximum price that can be entered by the user. If the price is blank, then the user is instructed to enter a value. If the price is out of range, then the user is forced to correct the problem.

This is the price validation in the form view.

This is how the price validation is performed in the data sheet view.

5. Quantity Validation

The rule ensures that a positive Quantity is entered.

6.  Automatic Conversion of Discount

The Discount column in Order Details table has the Single type. There is also a database constraint that requires the value to be between zero and one. The business rule will help the user by automatically converting the discount to a fraction of 100.

A user has entered a value greater than one in this screenshot.

The value is automatically converted when the user leaves the field.

7. Discount Range Validation

If the end user is trying to enter a particularly high discount that remains out of range even after automatic conversion, then the validation error is displayed.

8. Wrapping Up

The default behavior of the client library is to send the collected values to the server for processing by application. The business rule will prevent this from occurring. The business rule prevents server-side execution of Calculate action. It is also preventing server-side processing of Insert and Update if the validation has not been successful.

Code On Time web applications support out-of-the-box reporting capabilities that require zero programming.

Standard Report Actions

All data views offer four standard actions that yield a different output.

• Action “ReportAsPdf” will render the data presented to end users as a Adobe PDF document. The shorthand action “Report” will produce the same result. This type of report requires a compatible software installed on the client computer to view and print the report output. You can download free Adobe Acrobat Reader at at http://get.adobe.com/reader.
   
• Action “ReportAsImage” creates a TIFF image file, which requires a compatible software installed on the client. TIFF format supports multiple pages and is a perfect alternative to PDF. The quality of output in PDF and TIFF formats is equivalent.
   
• Action “ReportAsWord” renders a report as a Microsoft Word document with a high-quality output. In some instances, the output is less precise than the output produced by the action “ReportAsImage” and “ReportAsPdf”.
   
• Action “ReportAsExcel” produces a Microsoft Excel spreadsheet that offer a lesser quality output due to rendering restrictions of Excel files.

If a user  requests a “Report...” action then a report is rendered on the server with the help of Microsoft Report Viewer. The output is streamed to the client browser. Typically a prompt is displayed before a compatible installed software viewer will be activated. Users also have an option to save the output locally. If a viewer is not installed on the client computer, then the prompt to save the file is the only option.

Code On Time web applications execute various server calls off-band to provide a smooth Web 2.0 user experience. Modern web browsers make sure to prevent all sorts of popups initiated by the scripts embedded in the web pages. The client library makes use of correct techniques to process reports on the server without triggering popup blockers.

Custom Report Action Handlers

Code On Time web applications created with version 6.0.0.19 or higher allow developers to perform custom processing of reporting actions in business rules. There are several reasons that may require an execution of  custom code that must precede or override the standard report rendering logic:

• The data must be “prepared” before a report is rendered.
• The report request must be logged.
• An external report rendering engine is available. The custom code will redirect the report request to such an engine.
• A special report preview page needs to be displayed.
• A custom report building code must execute. The custom code replaces the standard report rendering logic.

To modify the behavior of the Report action, create a business rule and implement methods to handle the corresponding “Report...” actions.

Passing Action To An External URL

Start the Project Designer. In the Project Explorer, switch to the Controllers tab. Right-click on Customers / Actions node, and press New Action Group.

Assign the following value:

Save the new action group. Right-click on Customers / Actions / ag100 (ActionColumn) and press New Action.

Assign these values:

Press OK to save. Right-click on Customers / Business Rules node, and press New Business Rule.

Assign the following values:

Save the business rule. Press Browse on the toolbar to generate the business rule file.

When complete, right-click on Customers / Business Rules / Report, _blank (Code / Execute) – r100 node and press Edit Rule in Visual Studio.

The file will be opened in Visual Studio. Replace the existing code base with the following:

C#:

using System;
using MyCompany.Data;

namespace MyCompany.Rules
{
    public partial class CustomersBusinessRules : MyCompany.Data.BusinessRules
    {
        [Rule("r100")]
        public void r100Implementation(string customerID, 
            string companyName, 
            string contactName, 
            string contactTitle, 
            string address, 
            string city, 
            string region, 
            string postalCode, 
            string country, 
            string phone, 
            string fax)
        {
            // Redirect user to another URL
            Result.NavigateUrl = String.Format(
                "~/Pages/Customers.aspx?CustomerID={0}&_controller=Customers" +
                "&_commandName=Select&_commandArgument=editForm1",
                customerID);
        }
    }
}

Visual Basic:

Imports MyCompany.Data
Imports System

Namespace MyCompany.Rules
    
    Partial Public Class CustomersBusinessRules
        Inherits MyCompany.Data.BusinessRules
        <Rule("r100")> _
        Public Sub r100Implementation(ByVal customerID As String,
                                      ByVal companyName As String,
                                      ByVal contactName As String,
                                      ByVal contactTitle As String,
                                      ByVal address As String,
                                      ByVal city As String,
                                      ByVal region As String,
                                      ByVal postalCode As String,
                                      ByVal country As String,
                                      ByVal phone As String,
                                      ByVal fax As String)
            ' Redirect user to another URL
            Result.NavigateUrl = String.Format( _
                "~/Pages/Customers.aspx?CustomerID={0}&_controller=Customers" + _
                "&_commandName=Select&_commandArgument=editForm1",
                customerID)
        End Sub
    End Class
End Namespace

Save the file. The business rule will use the ID of the selected customer to compose a URL relative to the application. The URL will open in a new browser window and will force the application to select a customer with the specified ID.

The new window will open if your have entered the command argument as “_blank” when defining the action in Project Designer. If action command argument has been left blank then the new URL will replace the page in the web browser. Users will have an option to return to the previous page using the browser’s Back button.

Switch back to the web app open in the browser window and navigate to Customers page. A new action button will be present in the leftmost column.

Click on the Report button - a new browser window will open. You can see that the address bar is reflecting values from the selected customer.

Our web application is using its own capabilities to present the data with the help of data controller URL parameters. You can redirect the report action to a generic web request handler or to a web-enabled report server such as Crystal Reports or Microsoft SQL Server Reporting Services.

Overriding the Report Action

Switch back to the Project Designer. Right-click on Customers / Business Rules and press New Business Rule.

Use the following configuration:

Save the business rule. Right-click on Customers / Business Rules / ReportAsImage (Code / Execute) – r101 node, and press Edit Rule in Visual Studio.

Replace the code base with the following:

C#:

using System;
using MyCompany.Data;
using System.IO;

namespace MyCompany.Rules
{
    public partial class CustomersBusinessRules : MyCompany.Data.BusinessRules
    {
        [Rule("r101")]
        public void r101Implementation(string customerID, 
            string companyName, 
            string contactName, 
            string contactTitle, 
            string address, 
            string city, 
            string region, 
            string postalCode, 
            string country, 
            string phone, 
            string fax)
        {
            PreventDefault();
            // return the same image in response to all "Report..." commands
            Context.Response.Clear();
            Context.Response.ContentType = "image/jpeg";
            Context.Response.AddHeader("Content-Disposition",
                String.Format("attachment;filename={0}.jpg", customerID));
            byte[] reportData =
                File.ReadAllBytes(@"C:\Users\Public\Public Pictures\Sample Pictures\Koala.jpg");
            Context.Response.AddHeader("Content-Length", reportData.Length.ToString());
            Context.Response.OutputStream.Write(reportData, 0, reportData.Length);
        }
    }
}

Visual Basic:

Imports MyCompany.Data
Imports System
Imports System.IO

Namespace MyCompany.Rules

    Partial Public Class CustomersBusinessRules
        Inherits MyCompany.Data.BusinessRules
        <Rule("r101")> _
        Public Sub r101Implementation(ByVal customerID As String,
                                      ByVal companyName As String,
                                      ByVal contactName As String,
                                      ByVal contactTitle As String,
                                      ByVal address As String,
                                      ByVal city As String,
                                      ByVal region As String,
                                      ByVal postalCode As String,
                                      ByVal country As String,
                                      ByVal phone As String,
                                      ByVal fax As String)
            PreventDefault()
            'return the same image in response to all "Report..." commands
            Context.Response.Clear()
            Context.Response.ContentType = "image/jpeg"
            Context.Response.AddHeader("Content-Disposition", _
                String.Format("attachment;filename={0}.jpg", customerID))
            Dim reportData As Byte() = _
                File.ReadAllBytes("C:\Users\Public\Public Pictures\Sample Pictures\Koala.jpg")
            Context.Response.AddHeader("Content-Length", reportData.Length.ToString())
            Context.Response.OutputStream.Write(reportData, 0, reportData.Length)
        End Sub
    End Class
End Namespace

Save the file.

This business rule takes control over the report rendering completely.

First, the method cancels out the default reporting logic at the very beginning by calling PreventDefault. The method uses the customer ID to assign the file name to the output. Next, it reads the file C:\Users\Public\Public Pictures\Sample Pictures\Koala.jpg and streams it out. If you are reproducing this sample on a Windows 7 computer then there is not need to change the code . Otherwise change the path to the image file accordingly.

In a real-world application you can produce any sort of output using custom code.

Switch back to the browser, navigate to Customers page and select a customer. Choose Report | Multipage Image on the action bar.

The custom method will execute and you will  be prompted to download the file AROUT.jpg.

Click Open and the default image viewer will start.

If you select any other customer and choose the same action bar option then exactly the same image will be downloaded but the file name will reflect the primary key of the selected customer.

In a real-world applications you will likely stream other formats of output such as PDF or custom Microsoft Office documents using 3rd party reporting software.