Rule Definitions

Each rule definition is an XML file that uses the structure of the following example: 

<derivation>
   <name>work_items_on_last_time_sheet</name>
   <description>text description</description>
   <reason>OnLastTimeSheet</reason>
   <resource-bundle>suggested_items</resource-bundle>
   <context>TIME_WORK_ITEM</context>   
   <sql>
      <![CDATA[
        SELECT ...
        FROM ...
        WHERE ...
      ]]>   
   </sql>
</derivation>

The values for the name, description, reason, resource-bundle, context, and sql tags are described in the following sections. The description and resource-bundle tags are optional.

Name

This tag is a case-sensitive code-style name (that is, one with no spaces or special characters) that uniquely identifies the rule. The <name> value in the rule definition and the <name> value to be used in the QuickListMaster.xml file must match.

Description

This tag is an optional text description of the rule definition. The description must not use any XML special characters. You can arrange to translate this field into other languages supported by PPM, as described in Translating Descriptions and Reasons in Custom Rule Definition Files

The description must be included in the .properties file that has the file name specified for the <resource-bundle> tag in the rule definition XML file, which is suggested_items in the example so the file name with extension is suggested_items.properties. This file must be located in the following directory: 

   <PPM_Home>/conf/custom_resources/suggested_items

Reason

This tag is the key for the text that explains to the user the reason the item is being included in the Suggested Items list. The reason must not use any XML special characters. For example, the key OnLastTimeSheet could display the text Item from previous time sheet. You can arrange to translate this field into other languages supported by PPM, as described in Translating Descriptions and Reasons in Custom Rule Definition Files.

The reason must be included in the .properties file that has the file name specified for the <resource-bundle> tag in the rule definition XML file, which is suggested_items in the example so the file name with extension is suggested_items.properties. This file must be located in the following directory: 

   <PPM_Home>/conf/custom_resources/suggested_items

Resource Bundle

If values for description and/or reason are to be translated into other languages, this tag is the name of the .properties file that contains those values. A new .properties file must be created for each language to which description and/or reason are to be translated. The file name must conform to Java resource bundle naming conventions, including any required suffix such as _de for German or _pt_BR for Brazilian Portuguese. For more information, see Translating Descriptions and Reasons in Custom Rule Definition Files.

Context

Keep the value of this tag as TIME_WORK_ITEM.

SQL

Define an SQL statement to identify work items for the Suggested Items list. Multiple lines are allowed.

Including <![CDATA[ and ]]> tags around your SQL statement allows inclusion of special or reserved characters.

The following tokens are supported:

  • [TMG.RESOURCE_ID]

  • [TMG.PERIOD_ID]

To be read correctly, the SELECT columns of the SQL statement must be aliased to the following column names (but the return order of the columns does not matter):

  • work_item_id (ID of the work item)

    • For projects or tasks (including summary tasks/root node): task_id

    • For requests: request_id

    • For packages: package_id

    • For miscellaneous: lookup_code

  • work_item_name (display name of the work item)

    • For projects or tasks: task_name

    • For requests: request_id

    • For packages: package_id

    • For miscellaneous: lookup_meaning

  • work_item_set_id (ID of the work item set, such as project or request type)

    • For projects or tasks: work_plan_id

    • For requests: request_type_id

    • For packages: workflow_id

    • For miscellaneous: validation_id

  • work_item_set_name (name of the work item set)

    • For projects or tasks: work_plan_name

    • For requests: request_type_name

    • For packages: workflow_name

    • For miscellaneous: lookup_type

  • description (any plain text description of the work item, with suggested descriptions as follows)

    • For projects: the project description

    • For tasks: project path list to the task

    • For requests: request description

    • For packages: package description

    • For miscellaneous: lookup description

  • work_item_type (type of the work item—internal code)

    • For projects or tasks: TASK

    • For requests: REQUEST

    • For packages: PACKAGE

    • For miscellaneous: MISC

  • wp_task_info_name (this is required only when you select TASK for work_item_type)

  • pfm_request_id (this is required only when you select TASK for work_item_type)

For example, the following SQL selects all the requests that are both assigned to the user and in Approved status: 

<sql>
  <![CDATA[
SELECT r.request_id work_item_id,
       r.request_id work_item_name,
       r.request_type_id work_item_set_id,
       rt.request_type_name work_item_set_name, 
       r.description description,
       'REQUEST' work_item_type
  FROM kcrt_requests r,
       kcrt_request_types rt,
       kcrt_statuses s
 WHERE r.assigned_to_user_id = [TMG.RESOURCE_ID]
   and r.request_type_id = rt.request_type_id
   and r.status_id = s.status_id
   and s.status_name = 'Approved'
  ]]>
</sql>