Custom rules for time sheets

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:

Overview Description
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.
XML file

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.
Message display

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.

Performance

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.

Back to top

Rule attributes

A custom time sheet rule includes the following attributes:

Attribute Description
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.
sql

Defines the rule.

The SQL in the rule can use the following tokens, which get resolved at run time:

  • [TMG.TIME_SHEET_ID]. The time when the time sheet is submitted.

  • [TMG.CURRENT_USER_ID]. The user who is currently logged in, not necessarily be the time sheet resource.

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.
type

Available in 10.0.3 and later versions.

(Optional) Specifies the violation type for the rule: error or warning.

  • If it is set to error, users cannot submit the time sheet until the violation is resolved.
  • If it is set to warning, users can ignore the violation and continue to submit time sheets.

If no value is specified, the default value error is used.

Back to top

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:

  1. 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.

  2. Copy the config.xml.sample file to the <PPM_Home>/conf/tm_policy directory, and rename the file config.xml.

  3. 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.

  4. Make necessary changes to the config.xml and TMCustomRulesResources.properties files.

    For references on how to update these files, see Sample files and Examples of rules and messages.

  5. Restart the PPM server. Upon successful server startup, a message appears stating that the rules in the XML file are parsed correctly.

Back to top

Sample files

PPM provides the following sample files for you to use as references:

Sample file Description
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.
TMCustomRulesResources.properties.sample

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:

  • TMCustomRulesResources_en.properties for English
  • TMCustomRulesResources_de.properties for German

Back to top

Examples of rules and messages

See the following examples to understand how custom time sheet rules work. These example rules are listed in the increasing order of complexity.

Back to top