]po[ Rule Engine

This package defines rules and a rule engine that can perform actions whenever an object changes. Typical use cases are alert emails to project stake holders, the integration of specific process steps or the integration with external applications.

 

Rule Structure

A rule is defined by the following attributes:

  • Object Type (example: "im_project"):
    The type of object for which the rule should be applied.
    Please note that the rule-engine differentiates between im_project (main projects and sub-projects), im_timesheet_task (manually created tasks and imported MS-Project Gantt bars) and im_ticket (created by the package-intranet-helpdesk). Other object types will be supported in the future gradually, because the development team needs to connect various callbacks for these object types.

  • Initiation Type (example: "After Update"):
    Determines if the rule should be executed after an object has changed ("After Update") or after an object was created ("After Create").

  • Condition:
    A TCL expression that returns 1 or 0 (corresponding to true or false) and determines whether the rule should be executed ("fired").
    Examples: "1" (always true) or "$changed(project_status_id)" or "$new(percent_completed) > 95"

  • Action TCL:
    A TCL command that is executed if the condition evaluates to 1.
    Examples: "db_dml close_project "update im_projects set project_status_id = 81 where project_id=$new(project_id)"" (db_dml executes a SQL script)

  • Email To TCL:
    A TCL expression that returns a TCL list of email addresses to which an email should be sent. Additional fields defined below specify the subject and body of the email. 
    Examples: "db_list customer "select email from parties where party_id in ('$new(ticket_customer_contact_id)')"" or "db_list stakeholders "select email from parties where party_id in (select object_id_two from acs_rels where object_id_one = $new(project_id)) and party_id not in (select member_id from group_distinct_member_map where group_id in (select group_id from groups where group_name = 'Helpdesk'))""

 

Rule Execution

Execution Initiation

"After Creation" rules are executed exactly once after the rule engine detects a new object, while "After Update" rules are executed every time that the rule engine detects a change in the attributes of the underlying object.

The rule engine "detects" changes of an object:

  • whenever a user changes an object using a TCL page and
  • using a periodic "sweeper" process (a kind of cron script) that checks for objects modified outside TCL pages.

Fields Watched

The following values of a business object are considered for change:

A number of fields are expressively excluded from consideration because they are frequently modified internally:

  • im_project.tree_sortkey and im_project.max_child_sortkey: These values depend on the children of a project and are maintained internally by database triggers.
  • im_biz_object.rule_engine_old_value: This is value is used internally for keeping track of value changes.

 

Actions Executed

Both the "Action TCL" will be executed an an email will be sent to the "Email To TCL" if both fields contain values.

No action will be executed and no email will be sent if the respective fields are empty.

 

Available Variables

A number of predefined variables are accessible to rule TCL expressions:

  • $old(<attribute name>) - The values of the object previous to the last update,
  • $new(<attribute name>) - The values of the object after the last update and
  • $changed(<attribute name>) - Contains 1 if the attribute has changed during the last update, otherwise contains 0.

All columns of the rule's object type are available as <attribute name>. Please see the documentation of the project (in the case of a rule dealing with project) for a detailed documentation.

You can also call TCL procedures, for example in order to convert a "project_type_id" or "project_status_id" (which are integers) into a pretty name using by "[im_category_from_id $project_type_id]".

Important examples of attribute names for projects are:

  • project_id - The unique ID of the project,
  • project_name - The human readable name of the project,
  • project_nr - The project number ("2014_0001"),
  • parent_id - The ID of the parent project, or '' (empty string, the representation of NULL in TCL) in case of a main project,
  • company_id - The ID of the project's customer,
  • project_type_id - The status of the project (71=Potential, 76=Open, 77=Declined, 78=Delivered, 79=Invoiced, 81=Closed, 82=Deleted, 83=Canceled, ...) and
  • project_status_id - The type of the project (100=Task, 101=Ticket, 2501=Consulting Project, 2502=Service Level Agreement, 2504=Milestone, 2510=Program, ...)

For sending out emails, the following variables are available:

  • user_id - The unique object_id of the receiver (the person who will receive the email),
  • name - The full name of the receiver ,
  • first_names - The first names of the receiver (please observe the plural),
  • last_name - The last name of the receiver,
  • email - The email of the receiver,
  • system_url - The base URL of the server like "http://www.project-open.org" (without trailing "/" slash),
  • object_url - The URL to the object's view page and
  • auto_login - The hashed password of the user suitable as an authentication token for the "/intranet/auto-login?user_id=123&auto_login=...&url=..." page.

The following variables refer to the system user sending out the email, and not to the receiver:

  • sender_user_id - The unique object_id of the sender (the person who has last modified the object),
  • sender_name - The full name of the sender,
  • sender_first_names - The first names of the sender (please observe the plural),
  • sender_last_name - The last name of the sender and
  • sender_email - The email of the sender.

 

Rule Condition Details

A rule condition consists of a TCL expression that may evaluate to 0 (false) or 1 (true). Please see the TCL language documentation  for TCL syntax. Rule conditions may refer to rule variables as defined above.

Here are some examples for rule conditions:
  • 1:
    This condition is always true, so the action part of the rule will be executed every time the object changes or somebody looks at the object.

  • $changed(percent_completed) && $new(percent_completed) == 100.0:
    Fires the rule if "percent_completed" of a project or task reaches 100% for the first time.
    In other words, the rule fires if the project's work has been completed.

  • $changed(project_status_id) && $new(project_status_id) == 81:
    Fires if the project status has been set to 81 (=Closed, please see project status category page). Please see the project object model documentation for project states and their meaning.

 

Rule TCL Action

The TCL Action contains an arbitrary TCL statement that will be executed if the rule condition was true. Please see the TCL language documentation  for details.

Here are some examples for rule actions:

  • ns_log Notice "rule-engine: Executing rule":
    ns_log writes a log message to /web/projop/log/error.log.

  • db_dml update "update im_projects set project_status_id = 76 where project_id = $new(project_id)":
    Sets the status of the updated project to 76 ("Open").

 You can execute more than one TCL statement by separating statements by a semicolon (";").

 

Rule Email To

The engine will try to send out email messages to the email targets returned by this expression.

Here are some examples for the Email To field:

  • db_list my_emails "select email from parties where party_id in (
    select object_id_two from acs_rels where object_id_one = $new(project_id))"
    :
    Returns the list of all members of the specific project.

  • db_list my_emails "select email from parties where party_id in (
    select project_lead_id from im_projects where  project_id = $new(project_id)"
    :
    Returns the project manager of the affected project.

  • db_list my_emails "select email from parties where party_id in (
    select project_lead_id from im_projects where tree_sortkey in (select tree_root_key(tree_sortkey) from im_projects where project_id = $new(project_id)))"
    :
    Returns the project manager of the "main project". This is useful in order to report to the main project manager the events of sub-projects, tasks and tickets of any level.

  • db_list my_emails "select email from parties where party_id in (
    select r.object_id_two from acs_rels r, im_biz_object_members bom where r.rel_id = bom.rel_id and object_role_id = 1301 and object_id_one = $new(project_id))"
    :
    Returns the project "administrators" (member of the project in role "Project Manager").

 

Email Subject and Email Body

These field contain a string that may contain embedded variables in the syntax:

  •  $<variable_name>

where the value of variable_name is taken from the new(...) hash array.

Examples for Email Subject:

  • "Project $new(project_name) Complete" which is equivalent with:
  • "Project $project_name Complete"
  Contact Us
  Project Open Business Solutions S.L.

Calle Aprestadora 19, 12o-2a

E-08907 Hospitalet de Llobregat (Barcelona)

 Tel Europe: +34 932 202 088
 Tel US: +1 415 429 5995
 Mail: info@project-open.com