Validation Rules allow system administrators to configure policies to prevent undesired data modifications, such as:
- Do not allow to change custom values of Epic when it is in final state
- Do not allow to change Time records once they are marked as billed
- Allow to change "Approved" custom value only by users with "Approver" role
Every Validation Rule is defined as a trigger (which data modifications it reacts to) and a filter (whether to allow to save the modification).
There are 3 types of triggers:
- Validation Rule is triggered when a user adds the new entity like Bug or Feature
- Validation Rule is triggered when a user changes some field of existing entity, like Feature of User Story, or Budget custom value of Epic
- Administrators may optionally specify a list of field names which must be modified to trigger the validation. Omitting such changed field names causes the validation to be triggered for any modification of the selected entity.
- Adding, updating, or removing data from collections is not treated as Update of parent entity in Validation Rules, and must be done from the child's point-of-view. For example, to react to adding a User Story to existing Feature, administrator must configure a rule for User Story entity with changed fields set to Feature.
- It is also possible to check the original values of the fields before the modification using
- Depends on the Targetprocess version, may not be available for your Targetprocess installation yet
- Validation is performed before deleting the existing entity, so that Validation DSL can access the state of entity and its relations.
When Validation DSL expression resolves to
true, the validation is assumed to be failed, and transaction is reverted.
For example, the following DSL will reject any modifications (matched by trigger) when entity is in final state:
EntityState.IsFinal == true
Query capabilities (depth level for field access and aggregations) are the same as in
select clause of API v2.
$Author object allows to configure validations based on the user attempting to change the data. This may be useful to limit some changes to particular users only:
$Author.Idfield returns numeric ID of the user
$Author.IsAdminis a boolean flag indicating whether the user is selected as system administrator
$Author.ScopedRolerepresents a role of the user in the scope of the modified entity, i.e. Project-level or Global role
For example, allow to modify User Story only if the current user is assigned to it:
Assignments.Count(GeneralUser.Id == $Author.Id) == 0
When using Updated trigger, Validation DSL can access the values before the modification using special
$Previous object. For example, a rule may prohibit to increase the budget:
Budget > $Previous.Budget
Please note that
$Previous query capabilities are more limited than modified values:
- Max 2 levels depth, e.g.
$Previous.Feature.Project.Nameis fine, but
- No access to collections, no aggregations, e.g.
$Previous.Bugs.Count() > 0won't work
Deleting data in Targetprocess may also trigger Update operations. For example, deleting a Release also updates Features linked to that Release: their Release reference is set to
null. Validation rule may need to distinguish such transitive updates from user-initiated direct updates.
Validation DSL has a special
IsBeingDeleted() extension which returns
true when referenced entity is being deleted in the same operation. For example, to prevent changing Release of Feature, unless Release itself is deleted, the following DSL can be used:
$ChangedFieldsallows to access a collection of modified field names
$Modificationis a string representing currently validating data modification type - Created, Updated, Deleted
- Custom fields with non-alphanumeric symbols in name should be accessed using [square brackets] syntax
Updated 6 months ago