Rule

A "Rules Engine" allows various types of business rules to be written in a text format and easily applied to the system "on the fly" – without even logging out or shutting it down.  USAS-R comes with its own set of required business rules, as well as a number of optional business rules that the district may enable or disable as they desire.  Customized rules can also be written for each district, either by district personnel with the appropriate access to do so, or with help from their ITC or the SSDT.  A few examples of using customized business rules are custom validations, sending email or Twitter notifications, or even updating fields based on certain criteria.  These can also be used in conjunction with Custom Fields 

Bundled means it comes with the USAS-R software; Mandatory means the rule can not be disabled.

Create

  1. From the System menu select 'Rules'
  2. Click on
  3. Enter in required rule information

    Check the enabled box if the user wants it to be in affect the next time the rulesets are activated


  4. Click on  to ensure rule is correct
  5. Click on  to create the rule, click on  to not create the rule.

Activate

Rules do not take affect as soon as they are saved.  In order to make a new or changed rule take affect, the user would click on .  This will reload all of the enabled rulesets and they will become effective immediately.

Search

The Rules grid allows the user to search for existing Rules on the system by clicking in the filter row in the grid columns and entering in the desired information. Click on any row of the search results to see a summary view of the record.  The Advanced Search can be utilized by clicking on the   in the upper right side of the grid.

Edit

The options listed will depend if the rule is bundled and/or mandatory. If the rule is bundled and mandatory a user will only be able to view it. If the rule is bundled and not mandatory the user will be able to view or disable it. If the rule is not bundled then the user will be able to edit, delete or disable it. 

Click on the   in the grid beside the Rule to edit the record.

Disable Rule

A rule may be disabled if it is not mandatory.

  1. From the System menu select 'Rules'
  2. Search for desired Rule
  3. Click on
  4. Uncheck the
  5. Click on and close the pop up window
  6. Click on in order for the change to go into affect

Enable Rule

A disabled rule may be enabled at any time.  

  1. From the System menu select 'Rules'
  2. Search for desired Rule
  3. Click on
  4. Check the 
  5. Click on and close the pop up window
  6. Click on in order for the change to go into affect

Delete

Click on the    in the grid beside the desired rule.  A confirmation box will appear and you will be asked to confirm that you really do want to delete this rule. A rule may be deleted if it is not bundled.

Mandatory Rules

The following rules come with the software (bundled) and are mandatory in order to use the software.  They will be enabled automatically when the data is imported.  Mandatory rules cannot be disabled.

RuleDescription
org.ssdt_ohio.modules.customfield.CustomFieldsCustom Fields are enabled so that user (with the correct permissions) can create them
org.ssdt_ohio.modules.rules.startup-eventsStarts up the Rules Engine.
org.ssdt_ohio.modules.rules.stream.startup-streamRules engine stream startup
org.ssdt_ohio.usas.model.account.CashAccountRules'Include as General' flag is automatically set for funds included as part of the Five Year Forecast.  
org.ssdt_ohio.usas.model.accountChange.AccountChangeAppropriationRuleWarns the user if crossing appropriation boundaries in an account change request
org.ssdt_ohio.usas.model.accountChange.AccountChangeRequestRulesGenerate an Error if the user is trying to cross funds in an Account Change Request
org.ssdt_ohio.usas.model.accountChange.AccountTransitionFiscalYearThe prior fiscal year must be closed in order to process requests for current fiscal year.
org.ssdt_ohio.usas.model.account.ExpenditureAccountRulesWarning: Expenditure And Budget Codes don't match
org.ssdt_ohio.usas.model.budget.BudgetExpenditureOneToOneRuleError: Budget Expenditure relationship is 1 to 1
org.ssdt_ohio.usas.model.cashrec.CashReconciliationRulesWarning if the fund total and item total for the Cash Reconciliation being saved do not balance
org.ssdt_ohio.usas.model.disbursement.DisbursementReconciledDateError if the Reconciled Date is not after the Disbursement date
org.ssdt_ohio.usas.model.disbursement.DisbursementRulesError if user is generating a Disbursement with a negative amount
org.ssdt_ohio.usas.model.disbursement.VoidDisbursementRulesError is generated if voiding a disbursement that is reconciled and/or in a previous FY and/or in a closed posting period and/or with a date prior to transaction date
org.ssdt_ohio.usas.model.distribution.DistributionRulesError is generated if Distribution amounts do not equal zero and/or accounts are not the same type (expenditure or revenue)
org.ssdt_ohio.usas.model.interfundcash.InterFundCashTransactionError is generated if trying to edit an advance that has already been paid.
org.ssdt_ohio.usas.model.invoice.InvoiceItemCancelFullRulesOnly one full invoice item per PO item
org.ssdt_ohio.usas.model.invoice.InvoiceitemsRulesRequires full invoice items to come after partial invoices for a po charge
org.ssdt_ohio.usas.model.modelTransaction.ModelTransactionPrevents requisition, purchase order or disbursement transaction from being posted when the date provided is in a closed posting period. 
org.ssdt_ohio.usas.model.po.AmendedPOItemsNotChangedPrevents an item from being changed on an amended PO
org.ssdt_ohio.usas.model.po.AmendedPOPreventModificationIfInvoicedPrevents the purchase order's vendor from being updated if the PO has been invoiced.
org.ssdt_ohio.usas.model.po.AmendedPOPreventUpdatePrevents a PO from being updated if the PO  is not Modifiable or Amendable
org.ssdt_ohio.usas.model.po.POConversionRequireAccountsPurchase Order charges must have a valid account
org.ssdt_ohio.usas.model.po.POIssuedCancelledDateRulesUnable to modify a PO due to the PO date or item's issued or charged dates are in a closed period
org.ssdt_ohio.usas.model.po.POItemChargeAmountValidationError: Purchase order item and charge amounts are not equal
org.ssdt_ohio.usas.model.po.POItemChargeDatesError: Issued and cancelled dates on PO items and charges cannot be prior to PO date
org.ssdt_ohio.usas.model.po.POMultivendorValidationVendor may not be null if purchase order is not a multivendor PO
org.ssdt_ohio.usas.model.po.POUpdateValidationCannot update purchase order if model indicates it is not modifiable.
org.ssdt_ohio.usas.model.postingPeriod.PostingPeriodPosting period may not be re-opened because it is more than one year prior to the current period
org.ssdt_ohio.usas.model.postingPeriod.PostingPeriodCloseAll other posting periods in this fiscal year must be closed prior to closing the current period
org.ssdt_ohio.usas.model.refund.RefundCheckAmountError: Check Amount must not be zero
org.ssdt_ohio.usas.model.requisition.ReqRestrictNumberError: User entered an invalid req number
org.ssdt_ohio.usas.model.requisition.RequisitionItemQuantityError: Item quantity must match sum of charge quantities
org.ssdt_ohio.usas.model.user.RoleChangeRulesUser Can Not Change, Create or Delete A Role With An Underscore (SSDT created Roles)
org.ssdt_ohio.usas.model.user.UserDeleteRuleA username cannot be deleted in SYSTEM/User
org.ssdt_ohio.usas.model.vendor.VendorUpdate Vendor last activity date when posting requisition, purchase order, invoice and disbursement
org.ssdt_ohio.usas.model.vendor.VendorDefaultAddressCheckVendor must have a default PO address defined
org.ssdt_ohio.usas.model.vendor.VendorDefaultAddressesError: Vendor has multiple default PO/check/1099 address defined
org.ssdt_ohio.usas.module.usascodes.CodeStopDateErrorError: Account with stop date prior to current posting period
org.ssdt_ohio.usas.module.usascodes.CodeStopDateWarningWarning: Account with defined stop date produces a warning
org.ssdt_ohio.usas.module.usascodes.validation.AccountValidationAccount code validation (must be a valid account)
org.ssdt_ohio.usas.module.userbasedbalancechecking.rules.UserBasedBalanceCheckingBootstrapBootstrap rules for user-based balance checking
org.ssdt_ohio.usas.rules.opu.OpuError: OPU code and/or IRN are invalid


Bundled Rules that are not Mandatory


The following rules come with the software but are not mandatory in order to use the software.   

RuleDescription
org.ssdt_ohio.authnz.authnz-default-passwordMust meet the required default password rules
org.ssdt_ohio.authnz.authnz-stream-rulesAuthentication: Default Breaking Detection and Evasion
org.ssdt_ohio.usas.model.account.AppropriationCreationRulesErrorWarning issued stating Appropriation account already exists
org.ssdt_ohio.usas.model.account.AppropriationCreationRulesWarningWarning issued stating Appropriation did not previously exists so appropriation account automatically created
org.ssdt_ohio.usas.model.account.CashAccountCreationRulesErrorCash Account - Prevent Automatic Creation
org.ssdt_ohio.usas.model.account.CashAccountCreationRulesWarningWarning issued stating cash account did not previously exists so it will be created
org.ssdt_ohio.usas.model.accountChange.AccountChangeRequestFiscalYearPrior fiscal year must be closed to process an account change request in current fiscal year
org.ssdt_ohio.usas.model.budget.AppropMappingSampleBudget to appropriation mapping sample
org.ssdt_ohio.usas.model.disbursement.DisbursementNegativeCashBalanceErrorError generated if Disbursement cash account contains a negative balance
org.ssdt_ohio.usas.model.disbursement.DisbursementNegativeCashBalanceWarningWarning is generated if Disbursement cash account contains a negative balance
org.ssdt_ohio.usas.model.distribution.DistributionNegativeCashBalanceErrorError generated if Distribution cash account contains a negative balance
org.ssdt_ohio.usas.model.distribution.DistributionNegativeCashBalanceWarningWarning generated if Distribution cash account contains a negative balance
org.ssdt_ohio.usas.model.interfundcash.InterFundNegativeCashBalanceErrorError generated if fund-to-fund transfer or advance cash account contains a negative balance
org.ssdt_ohio.usas.model.interfundcash.InterFundNegativeCashBalanceWarningWarning genearted if fund-to-fund transfer or advance cash account contains a negative balance
org.ssdt_ohio.usas.model.invoice.InvoiceDatePriorToPODateWarningWarning: Invoice Date is prior to Purchase Order Date
org.ssdt_ohio.usas.model.invoice.InvoiceItemAmountExceedsEncumbranceRuleWarning: Invoice amount exceeds remaining encumbrance
org.ssdt_ohio.usas.model.invoice.InvoiceVendorActiveError generated if the invoice's vendor in Inactive 
org.ssdt_ohio.usas.model.invoice.InvoiceVendorDefaultCheckAddressWarning: Vendor does not have a default Check address defined - invoice
org.ssdt_ohio.usas.model.invoice.InvoiceItemAmountExceedsEncumbranceRuleWarning: Invoice amount exceeds remaining encumbrance
org.ssdt_ohio.usas.model.po.POPreventDeleteError: Purchase orders cannot be deleted
org.ssdt_ohio.usas.model.po.PORequireActiveAccountsRequires active accounts on purchase orders
org.ssdt_ohio.usas.model.po.PORestrictedFunctionCodesPrevents Posting purchase order expenditures with function codes 7100-7499
org.ssdt_ohio.usas.model.po.POVendorActiveRequires active vendors on purchase orders
org.ssdt_ohio.usas.model.po.PoVendorDefaultPOAddressWarning: Vendor does not have a default PO address defined on the purchase order
org.ssdt_ohio.usas.model.postingPeriod.PostingPeriodReOpenError: Prevent opening a previously closed posting period
org.ssdt_ohio.usas.model.receipt.ReceiptAccountRulesRequires active accounts on receipts
org.ssdt_ohio.usas.model.receipt.ReceiptNegativeCashBalanceErrorPrevents posting Receipt to a cash account with negative balance
org.ssdt_ohio.usas.model.receipt.ReceiptNegativeCashBalanceWarningWarning when posting a Receipt to a cash account with negative balance
org.ssdt_ohio.usas.model.receipt.ReceiptNumberChangedPrevent the Receipt number from being modified
org.ssdt_ohio.usas.model.receipt.ReceiptRestrictedCodesPrevent an invalid revenue account from being posted to a receipt item
org.ssdt_ohio.usas.model.refund.RefundAccountRulesPrevent an Inactive account from being posted to a refund
org.ssdt_ohio.usas.model.refund.RefundNegativeCashBalanceErrorPrevent a Refund from being posted to a negative cash account balance
org.ssdt_ohio.usas.model.refund.RefundNegativeCashBalanceWarningWarning will be issued is the refund posts to a negative cash balance
org.ssdt_ohio.usas.model.refund.RefundVendorActivePrevent inactive vendors from being posted to a refund
org.ssdt_ohio.usas.model.requisition.ReqRequireActiveAccountsPrevent an inactive account to be posted to a requisition
org.ssdt_ohio.usas.model.requisition.ReqRestrictedFunctionCodesPrevent posting requisitions with expenditure account containing function codes 7100-7499
org.ssdt_ohio.usas.model.requisition.RequisitionVendorActivePrevent an inactive vendor from being posted to a requisition
org.ssdt_ohio.usas.model.requisition.ReqVendorDefaultPOAddressWarning will be issued if a vendor does not have a default PO address defined when posting a requisition
org.ssdt_ohio.usas.model.vendor.VendorNumberChangedPrevent a Vendor number from being modified
org.ssdt_ohio.usas.model.vendor.VendorTaxIdRulesEnforces that the tax Id Type must be set if the Id # and Type 1099 are set.
org.ssdt_ohio.usas.module.usascodes.AccountDescriptionRuleSet the account description to the default account descriptions when left blank
org.ssdt_ohio.usas.module.userbasedbalancechecking.rules.DistributionAppropriationBalanceCheckWarningWarning will be issued if Appropriation account balance is negative when posting a distribution
org.ssdt_ohio.usas.module.userbasedbalancechecking.rules.DistributionBudgetBalanceCheckWarningWarning will be issued if Budget account balance is negative when posting a distribution
org.ssdt_ohio.usas.module.userbasedbalancechecking.rules.PendingTransactionAppropriationBalanceCheckWarning will be issued if Appropriation account balance is negative when posting a pending transaction
org.ssdt_ohio.usas.module.userbasedbalancechecking.rules.PendingTransactionBudgetBalanceCheckWarning will be issued if Budget account balance is negative when posting a pending transaction
org.ssdt_ohio.usas.module.userbasedbalancechecking.rules.POAppropriationBalanceCheckWarningExcludePreEncumbranceWarning will be issued if appropriation account unencumbered balance is negative when posting a purchase order
org.ssdt_ohio.usas.module.userbasedbalancechecking.rules.POBudgetBalanceCheckWarningExcludePreEncumbranceWarning/Error: Negative budget unencumbered balance check - purchase order
org.ssdt_ohio.usas.module.userbasedbalancechecking.rules.PurchaseOrderAppropriationBalanceCheckWarningWarning will be issued if Negative appropriation balance when posting a purchase order
org.ssdt_ohio.usas.module.userbasedbalancechecking.rules.PurchaseOrderBudgetBalanceCheckWarningWarning will be issued if Negative budget balance when posting a purchase order
org.ssdt_ohio.usas.module.userbasedbalancechecking.rules.ReqAppropriationBalanceCheckWarningExcludePreEncumbranceWarning will be issued if Negative appropriation unencumbered balance when posting a requisition
org.ssdt_ohio.usas.module.userbasedbalancechecking.rules.ReqBudgetBalanceCheckWarningExcludePreEncumbranceWarning will be issued if Negative budget unencumbered balance when posting a requisition
org.ssdt_ohio.usas.module.userbasedbalancechecking.rules.RequisitionAppropriationBalanceCheckWarningWarning will be issued if Negative appropriation balance when posting a requisition
org.ssdt_ohio.usas.module.userbasedbalancechecking.rules.RequisitionBudgetBalanceCheckWarningWarning will be issued if Negative budget balance when posting a requisition

Custom Rules

Customized rules can also be written for each district, either by district personnel with the appropriate access to do so, or with help from their ITC or the SSDT.  A few examples of using customized business rules are custom validations, sending email or Twitter notifications, or even updating fields based on certain criteria.  These can also be used in conjunction with Custom Fields. 

A few things worth mentioning with regards to rules. 


The following are custom rules that can be created:

Require a deliver to address when creating a requisition 

Name: org.districtname.RequisitionDeliveryAddressRequired

Description: Prevent posting Requisition without a Delivery Address


package org.districtName.Requistion.DeliveryAddressRequired;
dialect  "mvel"

import function org.ssdt_ohio.modules.rules.RulesHelper.*
import org.ssdt_ohio.model.ModelInformation;
import org.ssdt_ohio.model.ModelState;
import org.ssdt_ohio.model.events.*;
import org.ssdt_ohio.usas.model.requisition.Requisition;
import org.ssdt_ohio.usas.model.vendor.Vendor;

rule "requisition delivery address is required" 

	when
	    CreateObjectEvent() or UpdateObjectEvent()
    	ModelInformation(state != ModelState.IMPORTING, primary)
	    $requisition : Requisition(deliveryAddress.isEmpty())

    then
    	error(kcontext, "Requisition cannot be saved without a delivery address")

end



Require a vendor when creating a requisition

Name: org.districtname.RequisitionVendorRequired

Description: Prevent posting Requisition without a Vendor


package org.districtName.Requisition.VendorRequired;
dialect  "mvel"

import function org.ssdt_ohio.modules.rules.RulesHelper.*
import org.ssdt_ohio.model.ModelInformation;
import org.ssdt_ohio.model.ModelState;
import org.ssdt_ohio.model.events.*;
import org.ssdt_ohio.usas.model.requisition.Requisition;
import org.ssdt_ohio.usas.model.vendor.Vendor;

rule "requisition vendor is required" 

	when
	    CreateObjectEvent() or UpdateObjectEvent()
    	ModelInformation(state != ModelState.IMPORTING, primary)
	    $requisition : Requisition(getVendor() == null)

    then
    	error(kcontext, "Requisition cannot be saved without a vendor")

end

Require that an account code be entered for each requisition line item when creating requisition

Name: org.districtname.RequisitionWithoutAccount 

Description: Prevent requisition from being created without account code 

package org.ssdt_ohio.usas.model.requisition;
dialect "mvel"

import function org.ssdt_ohio.modules.rules.RulesHelper.*
import org.ssdt_ohio.model.events.*
import org.ssdt_ohio.model.ModelInformation
import org.ssdt_ohio.model.ModelState
import org.ssdt_ohio.usas.model.requisition.*
import org.ssdt_ohio.usas.model.accountChange.AccountChangeUpdateRules

rule "require accounts on requisitions"

	when
		CreateObjectEvent() or UpdateObjectEvent()
		ModelInformation(state != ModelState.IMPORTING, primary)
		not AccountChangeUpdateRules()
		$req : Requisition()
		RequisitionItem(charges.size() == 0) from $req.items

	then
		error(kcontext, "Expenditure Account is required")

end



Prevent Requisition from being created when the attention to field is blank

Name: org.districtname.RequisitionWithoutAttentionTo 
Description: Prevent requisition from being created when attention to is blank

package org.districtName.RequisitionAttentionTo;
dialect  "mvel"

import function org.ssdt_ohio.modules.rules.RulesHelper.*
import org.ssdt_ohio.model.ModelInformation;
import org.ssdt_ohio.model.ModelState;
import org.ssdt_ohio.model.events.*;
import org.ssdt_ohio.usas.model.requisition.Requisition;
import org.ssdt_ohio.usas.model.vendor.Vendor;

rule "requisition vendor is required" 

	when
    	CreateObjectEvent() or UpdateObjectEvent()
    	ModelInformation(state != ModelState.IMPORTING, primary)
   		$requisition : Requisition(attention == null)

    then
    	error(kcontext, "Requisition must have valid attention field")

end


Prevent Requisition from being saved or updated when any of the item descriptions are null or are an empty string

Name: org.districtname.RequisitionItemsWithNoDescription

Description: Prevent requisition from being saved or updated when any of the item descriptions are null or are an empty string


package org.districtName.Requisition
dialect "mvel"

import function org.ssdt_ohio.modules.rules.RulesHelper.*
import org.ssdt_ohio.model.events.*
import org.ssdt_ohio.model.ModelInformation
import org.ssdt_ohio.model.ModelState
import org.ssdt_ohio.usas.model.requisition.*


rule "Requisition Items Must Have A Description"

	when
		$event : RepositoryModificationEvent(isCreate() || isUpdate())
		ModelInformation(state != ModelState.IMPORTING, primary)
		$requisition : Requisition() from $event.target
		$item : RequisitionItem(description == null || description.trim().length() == 0) from $requisition.getItems()

	then
		error(kcontext, "Requitistion item number: " + $item.lineNumber + ", units: " + $item.units +
		", quantity: " + $item.quantity + ", unit price: " + $item.unitPrice +
		" has no description from requisition: " + $requisition.description)

end


Require an amount on a Receipt item

Name: org.districtname.ReceiptItemsWithoutAmount

Description: Prevent receipt from being saved or updated when a receipt item amount is empty

package org.ssdt_ohio.usas.model.receipt;
dialect  "mvel"
//ssdt: mandatory=false, enabled=true, description=Error: receipt item amount must be specified

import function org.ssdt_ohio.modules.rules.RulesHelper.*
import org.ssdt_ohio.model.ModelInformation
import org.ssdt_ohio.model.ModelState
import org.ssdt_ohio.model.events.*
import org.ssdt_ohio.usas.model.account.RevenueAccount
import org.ssdt_ohio.usas.model.account.RevenueCode

rule "ReceiptItemAmounts"
    when
        ModelInformation(state != ModelState.IMPORTING, primary)
        CreateObjectEvent() or UpdateObjectEvent()
        $receipt : Receipt()
        $item : ReceiptItem(amount == null || amount == 0) from $receipt.items

    then
        error(kcontext, "Item amount required for item: " + $item.lineNumber)
end



More Information