You can create custom time sheet rules that are evaluated when users submit their time sheets. These rules supplement the standard configurable time sheet policies described in Time Sheet Policies.
Overview of custom time sheet rules
The following table provides the overview of custom time sheet rules:
|Rule violation||A time sheet rule violation occurs when a user submits a time sheet that does not meet the requirements of the rule. The messages for rule violations are not displayed if the user saves the time sheets without submitting them.|
You define all the rules in one XML file. Each rule includes SQL statements to specify the conditions that trigger a violation. Any data on the time sheet can be validated through SQL. You can restrict the custom rules to apply to users who are associated with particular time sheet policies.
|Properties file||In a properties file, you can design the titles and bodies of messages that are shown to users when a rule violation or runtime error occurs.|
If a time sheet violates both time sheet policies and custom rules, the violation messages are displayed in the same dialog box. The messages of custom rule violation are displayed after the messages of time sheet policy violation.
When using custom rules, the performance of Time Management when time sheets are submitted depends on such factors as the number of rules, rule complexity, and whether the rules require evaluation of all time sheet lines.
A custom time sheet rule includes the following attributes:
|identifier||A number or a string that can help you distinguish multiple rules in the XML file. We recommend you specify a unique identifier for each rule.|
|title||Specifies the key for a key-value pair in the properties file, where the value is the title of both the violation message and the error message for the rule.|
|enabled||A flag to enable or disable the rule.|
|restrictTo||(Optional) Restricts the rule to apply to only the specific time sheet policies listed by ID number.|
Defines the rule.
The SQL in the rule can use the following tokens, which get resolved at run time:
|violation||Specifies the key for a key-value pair in the properties file, where the value is the body of the rule violation message.|
|error||Specifies the key for a key-value pair in the properties file, where the value is the body of the runtime error message for the rule. The body can be either specific or generic and applicable to all rules.|
Available in 10.0.3 and later versions.
(Optional) Specifies the violation type for the rule: error or warning.
If no value is specified, the default value error is used.
Create custom rules for time sheets
You can create your custom rules for time sheets by either copying the sample files or creating new ones.
To create custom rules for time sheets:
Prerequisite: Add the com.kintana.core.server.TM_ENABLE_POLICY_EXTENSION server.conf parameter in the server.conf file and set it to true. For details on adding server.conf parameters, see Installation and Administration.
Note: You cannot configure this parameter from the Administration Console.
- Copy the config.xml.sample file to the <PPM_Home>/conf/tm_policy directory, and rename the file config.xml.
Copy the TMCustomRulesResources.properties.sample file to the server/<PPM_Server_Name>/deploy/itg.war/WEB-INF/conf directory, and rename the file TMCustomRulesResources.properties.
If you have translated properties files, place them in the same directory.
Make necessary changes to the config.xml and TMCustomRulesResources.properties files.
- Restart the PPM server. Upon successful server startup, a message appears stating that the rules in the XML file are parsed correctly.
PPM provides the following sample files for you to use as references:
|config.xml.sample||Located in the <PPM_Home>/conf/tm_policy directory. This file contains rules that you can use to design your custom rules.|
|config.xsd||Located in the <PPM_Home>/conf/tm_policy directory. Do not change this schema file.|
Located in the server/<PPM_Server_Name>/deploy/itg.war/WEB-INF/conf directory. This file contains titles and bodies for violation messages and error messages.
Note: If your environment supports localization, you can translate the properties file to a local language and name it with the language. For example, the properties files can be translated and named:
See the following examples to understand how custom time sheet rules work. These example rules are listed in the increasing order of complexity.