Business Rules

Contents

 

Overview

Clarizen’s Business Rules help you automate your business workflow and unify business methodologies by setting up triggers and rules that run automatically.

Business rules can be created for every entity type within the organization and include both workflow rules and validation rules.

Workflow rules allow you to define, for each entity type, a list of rules that can be triggered at every addition, modification or deletion of objects of that type.

Scheduled Workflow rules allow you to define, for each entity type, a specific date or time frame for the rule to run on, assuming that the relevant object meets the evaluation criteria set within the rule

Validation Rules allow you to specify if your data is valid by defining a custom set of predefined rules.

You will be able to block insertion, modification or deletion of objects when they meet specified criteria.

Note: In cases where a business rules include a run-time error any operation that triggered the appropriate business rule will be aborted.
Use the Catch() function to catch any run-time errors in real-time

 

Tips for creating good business rules
  • Use the Catch() function if there is a chance of getting a run-time error
  • Test the business rule on test data, by adding a condition into the business rule's evaluation criteria,

for example: <evaluation criteria>&& ($Project="P-302")

  • Use validation error messages for debugging by putting a formula within {} into the error message and

testing that the value you receive from the formula is what you expect

 

Set Triggers

 

When creating business rules you must choose the trigger type, i.e when the business rule will be activated.

Allow this workflow to trigger additional workflows 

A standard behavior is that updates caused by workflows do not trigger additional workflows. This is to protect the system from loops and unintended automatic updates by workflows, which could adversely impact other users.
Enabling this setting means you understand this precaution and specifically do want to chain workflows.
A workflow may trigger up to 5 additional levels of workflows. At each level, multiple workflows may be triggered.
When multiple workflows are triggered at a level, they run according to the run order set in the Configuration screen.

Workflow Rule Trigger Options (Set Run Time)

The following trigger options are available for workflow rules:

When a record is created, or when a record is edited and did not previously meet the rule criteria
  • This option will trigger the workflow rule upon creation of the selected object, or each time that object is edited and did not previously fulfill the evaluation criteria
  • Using this option will require you to add an evaluation criteria, (i.e. what criteria needs to be meet in order for the workflow rule to run), all other trigger options can be used without necessitating evaluation criteria and only choosing Actions.
Only when a record is created
  • This option will trigger the workflow upon the creation of the selected object on which the workflow was created
Every time a record is created or edited
  • This option will trigger the workflow rule whenever the object is created, or each time the object is edited (regardless of whether or not it has previously meet the evaluation criteria)
Every time a record is deleted
  • This option will trigger the workflow rule each time the selected object on which the workflow was created on is deleted.
  • Use this option when creating rules that track the deletion of objects,

for example, when adding automatic comments to a work item when dependencies are deleted.

Note: When using the "Every time a record is deleted" trigger and attempting to update or access the deleted objects relations, then you need to make sure to check that the relation is not null within the evaluation criteria

 

Validation Rule Trigger Options

The following trigger options are available for validation rules:

Only when a record is created
  • Use this option to trigger the validation rule upon creation of the specific entity
Every time a record is created or edited
  • Use this option to trigger the validation rule upon the creation and editing of the specified entity
Every time a record is deleted
  • This option will trigger the validation rule each time a recorded is deleted
  • Use this option when creating rules that track the deletion of object, for example, when requiring users to add a comment to a work item when dependencies are deleted
Note: When using the "Every time a record is deleted" trigger and attempting to update or access the deleted objects relations, then you need to make sure to check that the relation is not null within the evaluation criteria

 

 

Scheduled Workflow Rules Run Time Options

The following runtime options are available for scheduled workflow rules:

Run On
  • Use this option to select a specific date or set a formula for a specific date, for example, 2 days prior to the end of a project due date, or 3 days after an Issue is created
Run repetitively
  • use this option to select a time frame for a repeating workflow rule, either by selecting daily, weekly, monthly or yearly
  • For example, running a workflow rule that counts the total number of open issues for a specific customer every Monday morning.

Best Practices and Notes:

  • Workflow criteria is evaluated only once for all objects, and thereafter for newly created or modified objects. As items are evaluated according to the workflow rule, but the execution may occur at a different time, time functions may not work as expected. 
  • The evaluation criteria only checks attributes of the current object. Look at the following workflow criteria created on the Bug entity:
    $State="Opened" AND IsMemberOf("Dev", $AssignedTo)
    The workflow runs based on updates to the Bug entity, and not on the related group (linked using 'IsMemberOf'). Therefore the workflow criteria will not recognize any updates if a new user is added to the group. Only updates to the Bug attributes (for example, State) will trigger the re-evaluation of the workflow.
  • Every time you enable or update a scheduled rule, the system reruns the initial calculation on all items.
    • If you are making several changes to a rule, make sure to disable it, perform all changes and only enable it after you have finished.
    • Enabling or updating a scheduled workflow rule several times can overload the system and cause you to exceed your daily API quota as well as the Workflow Execution quota.
    • Any Conditional Action Lists are calculated in run time for every object that fits the master evaluation criteria rule, which may impact performance.
    • When enabling, if the number of items the Scheduled Workflow rule runs exceeds 10,000, then the rule is automatically turned off.
    • If a rule is enabled and there are more than 10000 items, the rule will run 10,000 each time (the next 10,000 will be processed in the next run (next hour)). 

Set Evaluation Criteria

The evaluation criteria defined will determine under what conditions the business rule runs.

Note: Validation rules always require evaluation criteria, while workflow rules only require evaluation criteria when selecting the "When a record is created, or when a record is edited and did not previously meet the rule criteria trigger.

The evaluation criteria of a business rule is based on a formula, which can be created using the Formula Editor .

To view examples of formula's see the Formula Editor Functions article, or see the workflow, custom action and validation rule examples below.

Note: When creating evaluation criteria please note that certain field types display default values different than "Null". To see a full list of all field type defaults, click here.

 

Best Practices for setting Evaluation Criteria

When a workflow rule is enabled, the evaluation criteria for that rule is queried each time the corresponding entity is updated or created.

Make sure the evaluation criteria is set up based on the following rules and in the following order to ensure optimal performance:

  • Order by simplicity: The most simple expression should first
    mceclip0.png
  • When using AND the least likely expression should be first
    mceclip1.png
  • When using OR the most likely expression should be first
    mceclip2.png
  • Use IsChanged() in Every time a record is created or edited
    mceclip3.png
    Reduce executions on user-related workflows by ignoring logins
    mceclip4.png

  • Use catch() instead of IsNull() on nested references
    mceclip5.png

Set Error Message

Validation rules require you to enter an error message, which will be displayed to users when the validation rule is triggered.

Error messages should be informative so that the user understands what needs to be done.

For example, if the 'Description' of a 'Document' needs to be filled in when attaching a document to a task, the error should read:

Please be sure to fill in the document description prior to saving


 

Set Actions 

See also Best Practices for Actions.

The Set Action drop-down list allows you to select the action that will take place when the workflow rule is triggered.

Each workflow rule can have multiple actions and each action can include a formula. You can view sample formula's here.

Some Actions are only available when creating workflow rules on Work Item entities, and are labeled as such below.

#New Object Action

#Change State

#Outbound Call

#Reschedule

#Send Email

#Send Update Request

#Update Field

#Save As Baseline

#Conditional Action List

#Save Attachment

#Save Triggering Email

#Multiple Resource Assignment

#Send Report Action

#Move Action

#Delete Action

# Move Action

# InterAct Only Actions

 

New Object Action

  • Enables you to add a new object into the system
  • When selecting this action you must first select the object type, by selecting either an Entity or Linked Entity from the dropdown list
  • After selecting the object type you will be required to fill in certain fields
  • To update additional fields of the new object, click the "Another Field" link and select the relevant field
  • Users also have the ability to use the variable "NewObjectx", where x is the object number, within additional actions in the list

 

 

New Object Options

Bug
Allows you to create a new Issue of type Bug
Mandatory fields - Title
Calendar Exception
Allows you to create a Calendar Exception in a specified calendar
Mandatory fields - Name, Start Date, End Date, Event Calendar
Event Calendar - indicates the calendar on to which the new exception will be created on, can be a reference to the organization, group, user, or project
Customer
Create a new customer in the system
Mandatory fields - Name
Expense
Creates a new expense to link to an existing expense sheet
Mandatory fields - Expense Description, Expense Sheet
Expense Sheet
Creates a new expense sheet
The new object ID (i.e. NewObject1) for an expense sheet can be used within the Expense Sheet field when creating a new object of type expense
Issue
Creates a new Issue
Mandatory fields - Title
Job Title
Creates a new job title within the system
Mandatory fields - Name
Milestone
Creates a new milestone, either from a template or from scratch
Mandatory fields - Name, Parent (a parent of a milestone must always be a project)
Note
Creates a new note that can be linked to a work item or issue
Mandatory fields - Body, Attached To (determines what work item or issue the note will be attached to)
Post
Creates a new note that can be linked to a work item or issue
Mandatory fields - Body, Attached To (determines what work item or issue the note will be attached to)
Project
Creates a new project, can be created using an existing template
Mandatory fields - Name
Risk
Creates a new Issue of type Risk
Mandatory fields - Title
Skill
Creates a new skill set that can then be linked to users within the system
Mandatory fields - Name
Task
Creates a new task
Mandatory fields - Name, Parent (the parent can either be a project, milestone, or task)
Timesheet
Creates a new timesheet entry by the current user (i.e. user who triggered the rule)
Mandatory fields - Reported Date, Duration, Work Item (work item that the time sheet is linked to)
User
Creates a new user within the sytem
Mandatory fields - First Name, Last Name, Email
User Group
Creates a new user group, that users can be linked as members to
Mandatory fields -Name
Dependency
Creates a new dependency between two work items, where the default dependency type is Finish to Start
Mandatory fields - Work Item, Depends On
Note: To select the dependency type (i.e, Start to Finish, Finish to Start, etc) select the Dependency Type field from the "Another field" link
Group Hierarchy
Creates a new group hierarchy, in which multiple groups can be members of a parent group
Mandatory fields - Container (parent group), Member (can either be individual users or groups)
Issue Customer Link
Creates a link between an issue and a customer
Mandatory fields - Entity (specific Issue or Issue based on a formula), Customer
Issues Team
Allows you to add resources to an Issues team
Mandatory fields - Issue, Team Member
Job Title Link
Allows you to add members to an existing Job Title
Mandatory fields - Container (specify the Job Title or use a formula), Member
Parent
Allows you to create a hierarchical link between two work items
Mandatory fields - Parent, Child

Note: Tasks can be children of either Projects, Milestones or Tasks, while Projects and Milestones must have a parent that is of type "Project"

Progress Impact
Allows you to create a progress impact link between two work items, where the progress of the "child" will impact the progress of the "parent"
Mandatory fields - Parent, Child
Project Customer Link
Links a Customer to a Project
Mandatory fields - Entity (specific project or project based on a formula), Customer
Rate Holder
Allows you to modify the resource rate (cost) for specific work items
Mandatory fields - Work Item, Resource
Related Work
Creates a link between a work item and an issue
Mandatory fields - Case (specific or formula derived Issue), Work Item (specific or formula derived work item)
Resource
Assigns a resource to a work item
Mandatory fields - Work Item, Resource
Reviewer
Assigns a reviewer to a work item
Mandatory fields - Work Item, Resource
Shortcut
Creates a shortcut of a work item into a specified project
Mandatory fields - Parent, Child
Skill Link
Adds members to a specified skill set
Mandatory fields - Container (Skill), Member

 

Workflow Rule on Related

This action allows you to select a related (or linked) object using the Workflow on Related objects functionality.

If you select a related object, you will have the ability to filter through the object based on an evaluation criteria

For example, if you would like to create a new task, each time a project's related issue's state is changed to "In Work" then:

  • Select the "$Issues" entity via the "Run On" link
  • Select the "Filter related objects" checkbox
  • In the evaluation criteria enter the following: TargetObject.State='In Work'
  • Select the "Task" entity from the New Object dropdown and enter the necessary details


Get more info here

 

Change State

  • Enables you to change the state of a work item
  • When selecting this action you must select the work item that you would like to change the state of, as a default the "Current Object" is selected (i.e. the work item which triggered the workflow rule)
  • Allows you to select a related (or linked) work item using the Workflow on Related objects functionality.

If you select a related object, you will have the ability to filter through the object based on an evaluation criteria

 

Note: This action's execution is queued in the job server, meaning that it may occur in the background and values will be refreshed after completion

 

Outbound Call

  • Enables you to call an external web service using json or xml that can either interact back with Clarizen or with other systems
  • Run On - You can run the Outbound Call action on behalf of a specific user. The default is the CurrentUser.
  • URL – the URL of the web service to invoke
  • Have Token for this Web Service - Allows you to enter a token for the entered web service for user identification purposes
  • Web Service User - You can run the web service call action on behalf of a specific user

If no user value is entered, the system will use the default workflow user as defined in the organization settings.

  • Send also Session ID - Selecting this checkbox will send the current user's session ID along with the outbound call, allowing instant access to the user's session without requiring a login.

Notes:

  • This action's execution is queued in the job server, meaning that it may occur in the background and values will be refreshed after completion
  • If you get a timeout, make sure your web service is available from outside of your organization domain, and that you are getting results via a simple HTTP call
  • If multiple outbound calls happen close to each other, they will be grouped into one request and sent together to the external service. For example, a workflow that ran for 3 projects will be sent once with the details for the 3 projects. They will be sent in an “entities” array that may contain 1 or more items.
    Example
    mceclip2.png

 

Reschedule

  • Enables rescheduling the entity (start or due date) while providing the rescheduling options
  • When selecting the this action you must select the Start Date or Due Date field to be rescheduled.
Note: Rescheduling is only available for workflow rules created on Work Item entities
Note: This action's execution is queued on Clarizen job servers, meaning that it may run in the background and updated data will be refreshed and visible after it's completion

 

Send Email

  • Enables the defining an email template and a distribution list for the email
  • Emails can include hyperlinks to specific objects using the GetHyperlink() Function
  • Selecting recipients is done dynamically, meaning you can select the distribution list based on the user role within the object
  • To add static email addresses to an email, check off the "Additional Named Recipients" check box and enter the email address or user names.

Clicking the "..." will open up a flat list of all users within the application.

  • Emails can be created dynamically, meaning that you can enter field names to reference, or formulas
Note: This action's execution is queued in the job server, meaning that it may occur in the background and values will be refreshed after completion

 

Formula-Based Recipients

  • You can create dynamic recipients lists based on formula which must be contained in curly brackets {}.
  • You can use multiple formulas separated by semi-colon.

Example: {CurrentUser()}; {$Project.Manager}; {GetObjectById(“User”,”Joe.User”)}

Note: In Scheduled Workflow Rules CurrentUser() is the Default Workflow User,
so when creating Scheduled Workflow Rules on User object to send email to the User, you should use the CurrentObject() function, and not the CurrentUser() function.

 

Send Update Request

  • Allows you to send an update request email to the work item's team
Note: this action is only available for workflow rules created on Work Item entities
Note: This action's execution is queued in the job server, meaning that it may occur in the background and values will be refreshed after completion

 

Update Field

  • Enables you to edit other fields of the entity, including Clarizen's standard fields
  • When selecting this action, you must select the field that you would like to update by clicking on the "Select Field..." link
  • Fields can be updated using formulas

 

Save As Baseline

  • Allows you to save a project baseline, that can then be used for reporting purposes and to see deltas between actual and expected project scheduling and financial data.
  • When selecting this action you must select the object on which you want to "Run On"
    • By default this will be the CurrentObject, however, clicking on the "Change" link will allow you to select a related object as well
    • You also have the ability to select a variable from the variable tabs which can either reference a NewObject created within the rule or a variable set in the Custom Action or InterAct "User Input" section.
Note: This action's execution is queued in the job server, meaning that it may occur in the background and values will be refreshed after completion

 

Conditional Action List

  • Allows you to create a sub-flow within workflow rules, scheduled workflow rules, Custom Actions and InterAct
  • Selecting this action will open up a second "Evaluation Criteria" section with the ability to add sub actions within.

This will allow you to limit certain actions from occurring in rules, unless of course a specific criteria is met.

  • Once you set the evaluation criteria for the conditional action you can select the sub-actions, which will be nested below the conditional action list.
  • A conditional action list can also be nested within a conditional action, so that you may have several levels of nesting within a rule
  • Deleting a conditional action will delete all actions nested within
Note: Each conditional action used within a rule will count as a new rule,
so that if you create a custom action with a conditional action within it will count as two separate custom actions

 

Send Report Action

  • Allows you to automatically send any of Clarizen's predefined and custom reports
  • When selecting this action you must first select the report to generate
  • Selecting a report will present a list of report parameters that you will need to fill. The list of parameters include:
    • On behalf – allows to define the user permission that will be used to run the report.  Please note that based on this user permission financial data and other secured information can potentially be sent out.
    • The list of parameters defined for the report selected
    • parameter definition options change according to the operator defined for the parameter:

 

 

  • Additionally you must fill the email information, in the same way as the send email action
  • If choosing to track the report's email in Clarizen. The report will be added as an attachment to the entity that the email is attached to
  • Send report limitations per edition type can be found here

 

Note: This action's execution is queued in the job server, meaning that it may occur in the background and values will be refreshed after completion
Note: SECURITY NOTE: as this action may include sensitive information.

It is up to the administrator defining the action to make sure that the on behalf permissions,

email recipients and permission to the entity that the report is attached to are appropriate.

See Examples

 

Delete Action

  • Allows you to delete an object in the system
    • Object may be an entity (e.g.: delete a work item) or a link (e.g.: remove a resource from a work item)
  • The deletion will be done in the same way they would be deleted manually
    • For example, deleting a work item will delete all of its sub work items and moves them all to the recycle bin
  • When selecting this action, you must select the entity type to delete and the entity instance it self
  • You may use formulas to define the entity to delete
  • In order to delete a link entity, you may use the GetLink function to get the link entity to delete

See Examples

 

Move Action

  • Allows you to move work items and documents in the system to a new parent
  • When selecting this action you must select the entity type to move (work item/ document), the entity instance in self and the new parent instance.

In case of a document you must also select the new parent type (work item/ issue/ expanse)

  • You may use formulas to define the entity instance to move and the new parent
Note: This action's execution is queued in the job server, meaning that it may occur in the background and values will be refreshed after completion

See Examples

Calculate Project Financials

This action triggers a refresh of financial data for multiple projects. The action is available in Custom Actions and Scheduled Workflows. Click here to learn more.

InterAct Only Actions

The following actions are only available when creating mailbox rules in InterAct .

For examples on InterAct rules be sure to check out the Examples .

 

Save Attachment

  • Allows you to save email attachments onto objects within the system
  • Once this action is selected a "Filter File Types" input box is opened.

This allows you to decide what file types you would like to upload into Clarizen, for example,

if you only want to upload files of type .pdf and .doc then enter ".doc, .ppt" into the input box. This is an optional field

  • The AttachTo field will also be available once this action is selected, and requires you to insert the object onto which you would like to link the attachments.
  • Objects that attachments can be linked to must be either Issues, Work Items or Expenses
  • Users can input specific objects, or may refer to objects using the "Variables" tab in the "Formula Options"

 

Save Triggering Email

  • Allows you to attach the original email that was sent to activate a mailbox rule onto a newly created or existing object
  • Once this action is selected the "AttachTo" formula field will be available.

This is a mandatory field that requires you to insert the object onto which you would like to link the email

  • Objects that emails can be linked to must be either Issues or Work Items
  • Users can input specific objects, or may refer to objects using the "Variables" tab in the "Formula Options"

 

Multiple Resource Assignment

  • This action allows you to assign multiple resources to a work item at once,

and is meant to be used with either an emails CC list or with a variable of type text that contains a list of users all seperated by a comma

  • Once this action is selected two fields are available
  • WorkItem - this formula field must return an object of type Work Item and can either contain a specific object,

reference to an object, or to an object available in the "Variables" tab in the "Formula Options"

  • ResourceList - this formula field can contain a string, or series of strings, each separated by a comma.

For example to assign all users in the CC list of an email enter {EmailObject.CC}.

You can also enter the following: {EmailObject.Cc}, {username}, email@domain.com, firstname lastname which would assign all existing CC users, a specific user set with the username, a user that is found with the email address, and a user whose first name and last name match the one entered.

Note: If a user is not found in the Resource List he/she will simply be skipped and the action will continue running

 

Best Practices for Actions

Leverage variables to avoid multiple function calls.

mceclip6.png

Do not use SysId as an object reference

mceclip7.png

Workflow Rule Examples

To reschedule a work item in case its predecessors were completed ahead of time, set the evaluation criteria to be

$Executable && Not(IsManuallySet($StartDate)) && ($StartDate > Now()) && Now()


To send an email every time a work item was manually updated by the appropriate manager to be "off track", set the evaluation criteria to be

IsManuallySet($TrackStatus) && $TrackStatus = "Off Track"


To get an email update whenever substantial progress is made (>25%), set the evaluation criteria to be

$PercentCompleted - GetPreviousValue($PercentCompleted) >= 25


To build a workflow rule that updates the expense sheet approver to be a specific person, in case the expense sheet total amount has exceeded $1600, set the evaluation criteria to be

$Total > Currency (1600,'usd')

 

 

Send Update Request Example

Create a workflow rule on 'Milestone' entity whenever it is changed to 'At Risk'. Build the workflow rule as follows:

 

 

Send Email Action Example

Create a workflow rule that alerts a Work Item manager whenever a new document has been attached to their managed work item.

The Email message body should include

{GetHyperLink($Document)} was added to {GetHyperLink($Entity)}


Create a workflow rule that sends an email to the work item's manager whenever there is significant progress.

The email message body should include

$PercentCompleted - GetPreviousValue($PercentCompleted) >= 25

The Message subject will be

Work Item progress was updated on {{$Name}}

 

Reschedule Action

Create a workflow rule that will reschedule a work item when its predecessors have been completed early.

 

New Object Action

You can use a Custom Action and the New Object action to create a mini timesheet for work items.

 


Another use of the new object action is to create a Resource link between a work item or Issue and a User in the system.


Another great use is to quickly create a new task. For example,

create a workflow rule on Issues that will automatically create a task if the Issue duration is greater than 8 hours.

The example below shows how to create a custom action on the organization level, in order to quickly create new tasks on specified projects.

 

Custom Action Examples

 

Calculate Resource Load

 

Create Tasks from Issues

 

Create a New Critical Bug

 

Find and Replace Managers in a Project

 

 

Find and Replace Resources

The delete action allows you to create a custom action on the project level that replace a resource with a different

resource for all work items in the project, in one click

 

 

Remove irrelevant milestones

A Custom Action that allows you to delete a irrelevant milestone from a newly created project,

in case that the project is a set as a specific type of project (in the example below, we delete the "Planning" milestone from secondary projects)

 

 

Move document to parent project

A custom action on a document that moves it from the current task it is attached to, to that task's parent project.

This is very useful in cases where users attach documents to tasks that are relevant for the entire resource pool of the project

 

 

Move a feature from the RBL to a specific iteration

In agile project management methodologies, a common process is to create a release backlog (RBL) of all the planned features, and later on assign the features to short term iteration according to priority, needed effort and available resources.

The custom action below allows PM's to quickly and easily move selected tasks from the RBL to the specified iteration.

 

Validation Rule Examples

Create a validation rule on the Document link entity that will force a user to fill in the document description each time a new document is added to a work item.

 


Create a validation rule on a Task entity that won't allow a a task to be marked as complete when it's pending customer approval

 

 

Send Report Examples

 

Reports Mailbox

A rule within a general interact mailbox for sending reports to users.

This rule sends the user his tasks for the week as a response to an email sent to that mailbox with the title "my tasks"

 

Scheduled Workflow Rule Report

Scheduled workflow rule that sends group managers a report of the bugs opened for their group members

 

 
Have more questions? Submit a request

Comments