Server Rules

You can use server-side rules to improve the performance and user experience of SmartForms. Server-side means that rules are executed by the K2 server before the form is sent to the browser on your device or computer, while Client-side means that the rules are executed by the browser on your device or computer. When a form or view uses client-side rules at runtime, conditions and actions are executed individually by the browser on your device or computer, potentially resulting in back-and-forth calls between the browser and the K2 server for each action that needs to use the server. By using server-side rules where possible, you can execute the rule set once on the server before the view or form is sent to the browser. Because the rules are executed by the server rather than by the browser, server rules can help to improve the runtime performance and user's experience of the SmartForm.

Server-side rules are available when a view, form, subview, or subform loads (using the When the server loads… event), and are typically used to enable or disable controls, enable or disable the visibility of controls or views, collapse or expand a view, populate a control, open a worklist item, or change the appearance of a form based on certain conditions.

Use server-side rules to:

  • Avoid the flickering effect when controls and views are rendered by the browser. You can use server-side rules if you have views or forms with a lot of views and controls that must be populated, shown or hidden, data changed, cascading drop downs and more. When these actions are executed in the Initialize (client-side) rule, this results in flickering as the controls and visual layout is downloaded and displayed as a whole, then rendered in the browser. Moving the actions to a server-side rule avoids this flickering effect, because the view or form is prepared by the server and then sent to the browser.
  • Speed up data retrieval. Client-side rules can potentially perform many calls to the server to execute SmartObjects and retrieve data. In addition, when using separate K2 and web servers, latency between SmartForms and the K2 application server can further slow down the overall rule execution and form loading. Server-side rules speed up the retrieval of data because rule execution happens on the K2 server and the results are sent to the client, reducing the number of back-and-forth calls to the server.
  • Reduce the impact of SharePoint threading limitations. When you use SharePoint-based solutions, a limited number of threads are available to the server. If you use client-side rules, AJAX calls limit the amount of client-side threads of execution even further. Use server-side rules to reduce the impact of these SharePoint threading limitations, reduce view and form load times and improve the experience of using the form.

To use server rules, select the appropriate event from the list of Server Events in the Rules designer. Not all conditions and actions are available in server rules, so when you select one of these server events, the rule's conditions and actions are filtered and display only those conditions and actions that are supported by the event. The tables below list some examples where you can use server events, conditions and actions:

You can find the server rule events in the Server Events group of the Rule Designer. One example is when the server loads a view as shown below.

Type Rule Definition Example
Server Events When the server loads the Form Change the appearance of a form when the server loads the form
Server Events When the server loads a View Collapse a view when the server loads a view
Server Events When the server loads a subview Enable a control when the server loads a subview
Server Events When the server loads a subform Change the visibility of a control when the server loads a subform
Server Events When the server loads a View on a subform Expand a view when the server loads a view on a subform
Server Events When the server loads the View Enable a control when the server loads the view

You can find the server rule conditions in the Conditions tab of the Rule Designer. (Remember that server conditions are filtered and show only those conditions that are supported by the selected server event.) One example is to use an advanced condition as shown below. Click the dotted line to configure the condition.

Type Rule Definition Example
Parameter Conditions a Form parameter has been specified Execute a rule if a form parameter is not blank, such as if Manager is true, then enable the Manager Comments control.
Parameter Conditions a Form parameter has not been specified Execute a rule if a form parameter is blank, such as if Manager is not specified, then disable the Manager Comments control.
Parameter Conditions a Form parameter has a specific value Execute a rule if a form parameter has a specific value, such as if Number is 1000, then change the visibility of a control.
Parameter Conditions a Form parameter does not have a specific value Execute a rule if a form parameter is not a specific value, such as if Number is not 1000, then change the visibility of a control.
Parameter Conditions a subform parameter has been specified Execute a rule if a subform parameter is not blank, such as if Manager is true, then enable the Manager Comments control.
Parameter Conditions a subform parameter has not been specified Execute a rule if a subform parameter is blank, such as if Manager is not specified, then disable the Manager Comments control.
Parameter Conditions a subform parameter has a specific value Execute a rule if a subform parameter has a specific value, such as if Number is 1000, then change the visibility of a control.
Parameter Conditions a subform parameter does not have a specific value Execute a rule if a subform parameter is not a specific value, such as if Number is not 1000, then change the visibility of a control.
Parameter Conditions a subview parameter has been specified Execute a rule if a subview parameter is not blank, such as if Manager is true, then enable the Manager Comments control.
Parameter Conditions a subview parameter has not been specified Execute a rule if a subview parameter is blank, such as if Manager is not specified, then disable the Manager Comments control.
Parameter Conditions a subview parameter has a specific value Execute a rule if a subview parameter has a specific value, such as if Number is 1000, then change the visibility of a control.
Parameter Conditions a subview parameter does not have a specific value Execute a rule if a subview parameter is not a specific value, such as if Number is not 1000, then change the visibility of a control.
Parameter Conditions a View parameter has been specified Execute a rule if a view parameter is not blank, such as if Manager is true, then enable the Manager Comments control.
Parameter Conditions a View parameter has not been specified Execute a rule if a view parameter is blank, such as if Manager is not specified, then disable the Manager Comments control.
Parameter Conditions a View parameter has a specific value Execute a rule if a view parameter has a specific value, such as if Number is 1000, then change the visibility of a control.
Parameter Conditions a View parameter does not have a specific value Execute a rule if a view parameter is not a specific value, such as if Number is not 1000, then change the visibility of a control.
Parameter Conditions a View parameter on a subform has been specified Execute a rule if a view parameter on a subform is not blank, such as if Manager is true, then enable the Manager Comments control.
Parameter Conditions a View parameter on a subform has not been specified Execute a rule if a view parameter on a subform is blank, such as if Manager is not specified, then disable the Manager Comments control.
Parameter Conditions a View parameter on a subform has a specific value Execute a rule if a view parameter on a subform has a specific value, such as if Number is 1000, then change the visibility of a control.
Parameter Conditions a View parameter on a subform does not have a specific value Execute a rule if a view parameter on a subform is not a specific value, such as if Number is not 1000, then change the visibility of a control.
Custom Conditions an advanced condition is true Advanced conditions use data and comparison operators such as:
  • Equals or Not Equals
  • Greater Than or Less Than
  • Greater Than Equals or Less Than Equals
  • Contains, Starts With or Ends With
  • Is Empty or Is Not Empty
See How To Use Advanced Filter Conditions for an example.
Logical Conditions Else The Else condition defines the action to execute if another condition is false.
Error Handling Error occurred If a view parameter that expects a value to execute a load method is blank, then navigate to another view.
Workflow Conditions a Workflow Activity is specified If workflow activity is Manager Approval, then open the Manager Approval worklist item.
Workflow Conditions a Workflow Activity on a View is specified If workflow activity on a view is Manager Approval, then open the Manager Approval worklist item.
Workflow Conditions a Workflow Activity on a subform is specified If workflow activity on a subform is Manager Approval, then open the Manager Approval worklist item.
Workflow Conditions a Workflow Activity on a subview is specified If workflow activity on a subview is Manager Approval, then open the Manager Approval worklist item.
Workflow Conditions a Workflow Activity on a View on a subform is specified If workflow activity on a view on a subform is Manager Approval, then open the Manager Approval worklist item.

You can find the available server rule actions in the Actions tab of the Rule Designer. (Remember that server actions are filtered and show only those actions that are supported by the server event.) One example is to transfer data as shown below. Click the dotted line to configure the action.

Type Rule Definition Example
Form Interaction Set a View's properties When the server loads a form, expand a view on the form at runtime, see How To Set a View's Properties for an example.
Form Interaction Set the Form's properties When the server loads a form, change the Form Color at runtime, see How To: Use the Set a Form's Properties Action for an example.
SmartObject Interaction Execute a method on the View Execute a SmartObject method, such as Create or Load.
SmartObject Interaction Execute a subview method Execute the Load method on a subview.
SmartObject Interaction Execute a View method that was opened on a subform Execute the Load method on a view on the subform.
SmartObject Interaction Execute a SmartObject method Execute a SmartObject method, such as Create or Load.
SmartObject Interaction Execute a View method Execute a SmartObject method, such as Create or Load.
Data Transfer Transfer data Update the Status control with a view or form parameter.
Data Transfer Transfer data to a subview Update the Status control on a subview with a view parameter.
Data Transfer Transfer data to a subform Update the Status control on a subform with a view parameter.
Navigation Go to a tab

When the server loads a form, set the focus to a tab on the form.
Navigation Go to a subform tab

When the server loads a subform, set the focus to a tab.
Navigation Go to a View

When the server loads a form, set the focus to a view on the form.
Navigation Go to a View on a subform

When the server loads a view on a subform, set the focus to a view on the subform.
Control Interaction Populate a list control with data Populates a list control, such as a drop-down list, with data. Use it if you want to populate the control with data.
Control Interaction Populate a list control on a subview Populates a drop-down list on a subview.
Control Interaction Populate a list control on a View that was opened on a subform When you open a view on a subform, then populate a list control, such as a drop-down list or picker on the view, with data. Use it if you have data in a subform which should populate a list control on a view.
Control Interaction Set a control's properties When the server loads a view, enable a Button control at runtime. See How To: Use the Set a Control's Properties Action for an example.
Control Interaction Set a subview control's properties When the server loads a subview, enable a Button control on a subview at runtime. See How To: Use the Set a Control's Properties Action for an example.
Control Interaction Set a View on a subform control's properties When the server loads a subform, enable a Button control on a view on the subform at runtime. See How To: Use the Set a Control's Properties Action for an example.
Control Interaction Set a subform control's properties When the server loads a subform, enable a Button control on a subform at runtime. See How To: Use the Set a Control's Properties Action for an example.
Control Interaction Set a View control’s properties When the server loads a view, enable a Button control on a view at runtime. See How To: Use the Set a Control's Properties Action for an example.
Control Interaction Set a Form control's properties When the server loads a form, enable a Button control on the form at runtime. See How To: Use the Set a Control's Properties Action for an example.
Workflow Interaction Open a worklist item

Open a Manager Approval worklist item. Allows you to configure input and output mappings for the worklist item.
Workflow Interaction Open a worklist item on a subview

Open a Manager Approval worklist item on a subview. Allows you to configure input and output mappings for the worklist item.
Workflow Interaction Open a worklist item on a subform

Open a Manager Approval worklist item on a subform. Allows you to configure input and output mappings for the worklist item.
Workflow Interaction Open a worklist item on a View on a subform

Open a Manager Approval worklist item on a view on a subform. Allows you to configure input and output mappings for the worklist item.
Subform Interaction Set a subform's properties When the server loads a subform, change the Page Color of the subform at runtime. See How To: Use the Set a Form's Properties Action for an example.
Subform Interaction Set a View on a subform's properties When the server loads a subform, enable a view on a subform at runtime. See How To: Use the Set a View's Properties Action for an example.
Rule Interaction Stop rule execution
Rule Interaction Continue to next execution
Rule Interaction Execute a server rule When the server loads a Client form, then execute the When the server loads Region Item View server rule.

The example below shows how to replace an auto-generated Initialize rule of a Leave Item view with an equivalent server-side rule to perform the necessary load actions on the server, rather than on the client. In this example, you will replicate the rules in the When the View executed Initialize event with equivalent rules in the When the server loads the View event, and then switch the view to use the server-side rules when loading the view.

Follow the steps below to create a server-side rule based on the logic of the existing Initialize rule:

  1. Edit the Leave Item view, go to the Rules tab and click Add Rule.
  2. Click When the server loads the View event in the Server Events group.
  3. In the Actions tab, click Populate a list control with data in the Control Interaction group and select the Leave Type Drop-Down List control.
  4. Click Set a control's properties action and then select the Employee Name Text Box control. Click configure next to the action.
  5. In the Context Browser, expand System Values>Current User, then drag the Display Name into the Text property as shown below. Click OK.
  6. Your rule looks like the following image. When the server loads the view, these actions are executed on the server before the view is sent to the browser. This reduces the view load time and improves the experience of using the view. Click OK to save the rule.
  7. You can now disable or delete the existing Initialize rule, and K2 will instead use the server-side rule to load the view.
  • If you create a server rule on a view and you put that view on a form, you have to create a form server load rule to execute the view server load rule on the form. You can do this conditionally and/or specify the order. The example below shows the When the server loads Client Item View and When the server loads Client List View rules executing one after another when the server loads the form.

    If your Initialize rule is configured with an input mapping, you can use the transfer data action to replicate this mapping in the When the server loads the Form rule. The example below shows the When the Form is Initializing rule with a then on Client Item View, execute the Initialize method.

    The Initialize method is configured with an input parameter.

    When you create the When the server loads the Form rule, you can add the then transfer data action,

    and configure the action with the input parameter.
  • When you use server load rules, you must set up the event, condition and actions on the same level, for example when you use the When the server loads the View event, you must select the condition and action for a view. You cannot select a condition or action for a form, subview or subform.

    The same applies when you use a subview server rule event as shown below. You must select the subview conditions and actions.
  • When you use server load rules, you can choose from the execution types as shown here. However, when the rule executes (on the server), actions are always processed sequentially (then complete the following one after another).
  • See Rule Configuration for information on how to use items from the Context Browser to configure a rule.
  • You can only use server-side rules when a view, form, subview or subform loads.
  • If you have a view or form that performs satisfactorily with existing Initializing or Initialized rules, then there is no reason to change them to server-side rules.
  • You cannot change an existing client-side rule to a server-side rule by merely selecting the When the server loads… event, because server-side rules do not support all the conditions, actions and context browser items as client-side rules. If you want to configure an existing view or form to use server-side rules, it is recommended that you create a new rule, select the server-side rule event, and then rebuild the conditions and actions based on the logic in the existing Initialize or Initialized rule. You can then disable or delete the original rule once the server-side rule is complete. See Creating a Server-Side Rule for more information.