An "SDC Rule" (also known as "Custom Business Rule", "Programmable
Business Rule", or "Business Rule") is an SDC-specific custom class
that you create by extending sapphire.action.BaseSDCRules
(see Creating SDC Rules). Essentially, you generate
code that applies conditional logic to a System Action, then execute your code
using methods in sapphire.action.BaseSDCRules.
The BaseSDCRules class provides a number of utility methods to support execution
of the rule. Methods that control code excution are prefixed by "pre" or "post"
to indicate when the method executes your code:
| Prefix |
Method Type |
Executes your code... |
| pre |
pre-insert |
...before database inserts. |
| post |
post-insert |
...after database inserts, but prior to commit. |
The Javadoc for class sapphire.action.BaseSDCRules
specifies the System Actions to use when overriding each method with to add
the required logic before or after database inserts.
As an example, here is a comparison of how the AddSDI
Action runs with and without using SDC Rules:
| Without SDC Rule
|
With Pre-Insert Method
|
With Post-Insert Method
|
| 1. |
Get Properties |
| 2. |
Parse Properties |
| 3. |
Build Inserts |
| 4. |
Do Inserts |
| 5. |
Commit |
|
| 1. |
Get Properties |
| 2. |
Parse Properties |
| 3. |
Execute Method
|
| 4. |
Build Inserts |
| 5. |
Do Inserts |
| 6. |
Commit |
|
| 1. |
Get Properties |
| 2. |
Parse Properties |
| 3. |
Build SQL |
| 4. |
Do Transaction |
| 5. |
Execute Method
|
| 6. |
Commit |
|
SDC Rule methods can throw SapphireExceptions (class sapphire.SapphireException)
to force Action failure, thereby making them suitable for add/edit/delete validation
rules.
Suppose you want to ensure that a column is always populated with a certain
value whenever an SDI is created. In this case, you could write a preAdd() method
to poplulate the column every time the AddSDI Action executes.
Assume you have a Project SDC with a column specifying the number of Samples
in the Project. You want to execute an AddSDI Action that updates the number
of Samples in the Project each time the Action adds a Sample. Without SDC Rules,
you would have to write a custom Action to execute an AddSDI (for Sample) and
EditSDI (for Project). With SDC Rules, you could execute the AddSDI (for Sample),
then write a postAdd() method to update the number of Samples in the Project
prior to commit.
| NOTE:
|
Advanced users can also use these methods to process another Action prior
to commit (such as SendMail). However, be advised the email would be sent
whether or not a commit has occurred. Therefore, in such a case, it would
be wiser to use the AddToDoListEntry Action to put the SendMail Action into
the ToDo List. The email would then be sent only following commit. |
In general:
|
|
Create your new class by extending sapphire.action.BaseSDCRules.
Note that:
| • |
Your new class must have the same name as the relevant SDC (such
as Sample.class). |
| • |
You must put your class in a custom package (such as sapphire.custom.myapp.rules). |
|
|
|
Register the custom package as a LabVantage "Profile Property"
by adding the package information to the ProfileProperty table. This allows
your custom SDC Rule (such as Sample.class) to be executed after the LabVantage
core SDC Rules.
If you are registering a single package, you can do this simply by specifying
the package name under "Custom Business Rules" in the "API
Options" section of the System Configuration. If you are registering
multiple packages, see "Defining Multiple Packages" below.
|
Defining Multiple Packages
|
|
You can define (create and register) multiple SDC Rule packages. When defining
multiple packages:
| • |
Each set of SDC Rule classes must exist in a unique package name. |
| • |
Each package name must be registered in the ProfileProperty table with
the following column values:
| ColumnId | Value | | ProfileId | System | | PropertyId | Must begin with this string: customrulesjavapackage | | SysUserId | (system) | | PropertyValue | Must specify the custom package name. |
|
Default Behavior
By default, SDC Rules from multiple packages are executed in alphabetical order.
Example:
| Package Names |
Execution Order
|
|
customrulesjavapackage_abc
customrulesjavapackage
customrulesjavapackage_xyz
|
| 1. |
customrulesjavapackage |
| 2. |
customrulesjavapackage_abc |
| 3. |
customrulesjavapackage_xyz |
|
Custom Sequences
To define a custom sequence, add an additional Profile
Property to the ProfileProperty table called "customrulessequence".
The value of this property defines the sequence of execution. Example:
| Package Names |
Value of customrulesequence
|
Execution Order
|
|
customrulesjavapackage_abc
customrulesjavapackage
customrulesjavapackage_xyz
|
customrulesjavapackage_xyz;customrulesjavapackage_abc;customrulesjavapackage |
| 1. |
customrulesjavapackage_xyz |
| 2. |
customrulesjavapackage_abc |
| 3. |
customrulesjavapackage |
|
SDC-Specific Sequences
You can further refine a custom sequence to be specific for a particular SDC.
Do this by adding additional Profile Properties in the format customrulessequence_[SDC].
For example, if there is a specific sequence in which your Sample rules must
execute, you can add a Profile Property called "customrulessequence_Sample"
and specify the correct semicolon-delimited package sequence.
| NOTE: |
If you specify a package under "Custom Business Rules" in the
"API Options" section of the
System Configuration, that class is stored in the ProfileProperty table
with the PropertyId = customrulesjavapackage. Any additional packages you
define must be manually added to the ProfileProperty table. At execution
time, all Profile Properties starting with customrulesjavapackage are loaded
- first customrulesjavapackage, then any you added manually. They are executed
in the order you define as shown above. |
Here are links to the source code for two LabVantage core classes in sapphire.jar/com/labvantage/sapphire/admin/ddt,
which demonstrate implementations of SDC Rules:
| • |
RefType.java creates
the RefType class by overriding BaseSDCRules. The preAdd and preDelete methods
are demonstrated. |
| • |
SampleType.java
creates the SampleType class by overriding BaseSDCRules. The preAdd, postAdd,
preEdit, postEdit, preDelete, and postDelete methods are demonstrated. |
