Business Rules

Contents

• Overview
• Set Triggers
  • Workflow Rule Trigger Options
  • Validation Rule Trigger Options
  • Scheduled Workflow Rules Run Time Options
• Set Evaluation Criteria
• Set Error Message
• Set Actions
  • New Object Action
  • Change State
  • Outbound Call
  • Reschedule
  • Send Email
  • Send Update Request
  • Update Field
  • Save As Baseline
  • Conditional Action List
  • Send Report Action
  • Delete Action
  • Move Action
  • InterAct Only Actions
• Workflow Rule Examples
  • Send Update Request Example
  • Send Email Action Example
  • Reschedule Action
  • New Object Action
• 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
  • Remove irrelevant milestones
  • Move document to parent project
  • Move a feature from the RBL to a specific iteration
• Validation Rule Examples
• Send Report Examples
  • Reports Mailbox
  • Scheduled Workflow Rule Report

 

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.

 

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.

 

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

 

 

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.

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.

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:

 

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

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

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

 

 

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
  

 

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.

 

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

 

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”)}

 

Send Update Request

• Allows you to send an update request email to the work item's team

 

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.

 

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

 

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

 

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

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.

 

Best Practices for Actions

Leverage variables to avoid multiple function calls.

Do not use SysId as an object reference

Workflow Rule Examples

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

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

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

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

 

 

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

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

The Message subject will be

 

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