Application Development

Business Rules

During the design of a WebApp, business rules can be incorporated into each page or for a specific field triggering an action or event. For example, business rules can be created on the Customers page to force a customer’s name to display in all upper case letters, or to default Date Shipped to be the same as Order Date. A page Designer can add a button with a business rule that, when clicked, runs the rule that adds one day to the Date Shipped date.

This topic contains these sections:

NOTE: Refer to Register Workflow Views for information about adding Business Rules to a workflow.

Business Rule Guidelines

  • Business Rules are stored procedures which are generally created from a select view.
  • Common naming for stored procedures is webTable_Event_Description#Action where:
    • Table Table registered to the page that calls the business rule
    • Event Event that calls the business rule
    • Description Procedure description or field being modified
    • # An optional number to prevent duplication
    • Action Action performed by stored procedure: 'Upd' if update; 'Ins' if insert; 'Del' if delete
  • Name stored procedures that include a select query view the same as the select view, without the 'Sel' suffix.

     

    Governance Example

    Migration Example

    Select View

    webRequestMasterRecipeStepsOperations_BeforeDelete_OpPhasesDelSel

    webTargetSourceReportUpdSel

    Stored Procedure

    webRequestMasterRecipeStepsOperations_BeforeDelete_OpPhasesDel

    webTargetSourceReportUpd

    Select View

    webRequestPurchasingContractItems_OnValidate_PSTYP_3UpdSel

    webTargetSourceRuleInsSel

    Stored Procedure

    webRequestPurchasingContractItems_OnValidate_PSTYP_3Upd

    webTargetSourceRuleIns

  • It is recommended to base behavior off of boaStatus rather than record existence. To validate data, it must exist; however, if the application data is invalid, exceptions during execution could result. Considering boaStatus during record manipulation can ensure business logic will not fail unexpectedly.
  • Determine under which validation conditions the business rule should execute. By default, business rules Run on Validate, which means they execute if the record is left in a valid state after the Validation Rule’s execution. However, there may be conditions where a business rule should ALWAYS execute. For example, a counter on how many times a button has been clicked is generally unconcerned with record validity and checking both Run on Validate and Run on Validate Fail check boxes on the Page Business Rulespage’s Vertical View would enable this. Alternatively, you may want to run an event even if the validation fails to record information or update a parent record.
  • If using the Force Foreground Execution option on the Page Business Rules page’s Vertical View, be aware that unexpected behavior can result. The intent of the feature is to ensure that the Business rule runs against the Web Server, even if the event is set to run in the background. For example, Force Foreground Execution may be required for plugin access to the Http Context. However, depending on chain event calling, (as used in Public Web App Events) unexpected behavior may result. Additionally, the Business rule still runs in the background, even if the Force Foreground Execution setting is used, so the Business rule executes twice.

  • Business rules should NEVER throw Internal Errors. Validation rules exist to ensure that the expected configuration for success exists prior to executing. Any runtime failures that may occur (in other words, database connection failures) should be Try/Catch formatted typed Messages back to the user.

NOTE: The view and stored procedure must have already been created in SQL.

Create a Stored Procedure Business Rule

To create a business rule for a field in Stewardship Tier Application Development:

  1. Select Admin > WebApps in the Navigation pane.
  2. Click the Pages icon for the WebApp.
  3. Click the Events icon for the page.

OR

  1. Access the WebApp page.
  2. Click the Change Settings icon on the Site toolbar.
  3. Click Design.
  4. Click the Events icon for the page.
  5. Click the Business Rules icon for the event.

    NOTE: If no record exists, the page displays in add mode. Otherwise, click Add.

  6. Enter a value in the PRIORITY field to determine execution order.

    NOTE: The Stewardship Tier attempts to wrap all procedures within a single SQL transaction. To avoid deadlocks, all pending transactions are committed before executing an external process. As a result, mixing external processes and SQL stored procedures can result in errors which cannot be completely rolled back. To minimize the effect, consider placing all external processes after SQL stored procedures by giving them a higher priority.

  7. Verify the ACTIVE check box is checked.
  8. Verify Stored Procedure is selected from the PROCEDURE TYPE list box.
  9. Click Save; the Vertical View displays.
  10. Select the name of the stored procedure from the Procedure list box.
  11. Enter text describing what the stored procedure does in the Comment field.

    NOTE: This comment is a description of the event; it does not display to the end user.

  12. Click the Advanced Properties label to expand the label set.
  13. Verify the Run On Validate check box is checked.
  14. Click Save.

    NOTE: Business Rules run only after all validation rules on the page are processed without error.

Create an External Page Business Rule

An External Page rule allows you to execute a plugin as the event action to determine whether the associated record is valid. The validation fails if a non-zero result is returned.

To create an External Page Business Rule for a field in Stewardship Tier Application Development:

  1. Select Admin > WebApps in the Navigation pane.
  2. Click the Pages icon for the WebApp.
  3. Click the Events icon for the page.

OR

  1. Access the WebApp page.
  2. Click the Change Settings icon on the Site toolbar.
  3. Click Design.
  4. Click the Events icon for the page.
  5. Click the Business Rules icon for the event.

    NOTE: If no record exists, the page displays in add mode. Otherwise, click Add.

  6. Enter a value in the PRIORITY field to determine execution order.

    NOTE: The Stewardship Tier attempts to wrap all procedures within a single SQL transaction. To avoid deadlocks, all pending transactions are committed before executing an external process. As a result, mixing external processes and SQL stored procedures can result in errors which cannot be completely rolled back. To minimize the effect, consider placing all external processes after SQL stored procedures by giving them a higher priority.

  7. Verify the ACTIVE check box is checked.
  8. Select External Page from the PROCEDURE TYPE list box.
  9. Click Save; the Vertical View displays.
  10. Select the name of the plugin that executes when the event fires from the Web App Plugin Type Code list box.
  11. Enter text describing what the stored procedure does in the Comment field.

    NOTE: This comment is a description of the event; it does not display to the end user.

  12. Click the Advanced Properties label to expand the label set.
  13. Verify the Run On Validate check box is checked.
  14. Click Save.

    NOTE: Business Rules run only after all validation rules on the page are processed without error.

Create a WebApp Event Business Rule

A WebApp Event allows you to execute an event that already exists on a different page. For instance, you can create a button in a custom app that runs the same event as the Refresh Table button in Collect. Since the functionality for refreshing a table already exists in Collect, this allows you to call it from anywhere without duplicating the code.

To create a WebApp Event Business Rule for a field in Stewardship Tier Application Development:

  1. Select Admin > WebApps in the Navigation pane.
  2. Click the Pages icon for the WebApp.
  3. Click the Events icon for the page.

OR

  1. Access the WebApp page.
  2. Click the Change Settings icon on the Site toolbar.
  3. Click Design.
  4. Click the Events icon for the page.
  5. Click the Business Rules icon for the event.

    NOTE: If no record exists, the page displays in add mode. Otherwise, click Add.

  6. Enter a value in the PRIORITY field to determine execution order.
  7. Verify the ACTIVE check box is checked.
  8. Select WebApp Event from the PROCEDURE TYPE list box.
  9. Click Save; the Vertical View displays.
  10. Select the name of the event on the page from the Event Name list box.
  11. Select the view name from the Parameter View list box, if needed.

    NOTE: This view contains extra columns to map to parameters to send to the other event. This view will be executed as part of the event, pulling in an associated record to the executing record, and assigning the other column data to mapped parameters. This parameter view allows another view to provide more data to an event without putting all the columns in the horizontal or vertical view on the page.

  12. Enter text describing what the stored procedure does in the Comment field.

    NOTE: This comment is a description of the event; it does not display to the end user.

  13. Click the Advanced Properties label to expand the label set.
  14. Verify the Run On Validate check box is checked.
  15. Click Save.

    NOTE: Business Rules run only after all validation rules on the page are processed without error.

Create a WebApp Event (Private) Business Rule

A WebApp Event (Private) allows you to execute an event that already exists on the page.

Private events are like public events, but only events on the same page can call that event. The use of private events helps reduce code duplication.

For example, a large event must run on a page after a few steps run. Add a button that when clicked, runs these steps before calling that large event. Set the large event to private, and have the last business rule be this ‘private’ event.

To create a WebApp Event (Private) Business Rule for a field in Stewardship Tier Application Development:

  1. Select Admin > WebApps in the Navigation pane.
  2. Click the Pages icon for the WebApp.
  3. Click the Events icon for the page.

OR

  1. Access the WebApp page.
  2. Click the Change Settings icon on the Site toolbar.
  3. Click Design.
  4. Click the Events icon for the page.
  5. Click the Business Rules icon for the event.

    NOTE: If no record exists, the page displays in add mode. Otherwise, click Add.

  6. Enter a value in the PRIORITY field to determine execution order.
  7. Verify the ACTIVE check box is checked.
  8. Select WebApp Event (Private) from the PROCEDURE TYPE list box.
  9. Click Save; the Vertical View displays.
  10. Select the name of the event on the page from the Event Name list box.
  11. Enter text describing what the stored procedure does in the Comment field.

    NOTE: This comment is a description of the event; it does not display to the end user.

  12. Click the Advanced Properties label to expand the label set.
  13. Verify the Run On Validate check box is checked.
  14. Click Save.

    NOTE: Business Rules run only after all validation rules on the page are processed without error.