Validation Rules

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).

Triggers

There are 3 types of triggers:

• Created
  • Validation Rule is triggered when a user adds the new entity like Bug or Feature
• Updated
  • 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 $Previous in DSL.
• Deleted
  • 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.

Validation DSL

The filter is configured with Validation DSL, the same DSL as used in API v2 and Metrics, with some validation-specific extensions.

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.

Filtering by modification author

Special $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.Id field returns numeric ID of the user
• $Author.IsAdmin is a boolean flag indicating whether the user is selected as system administrator
• $Author.ScopedRole represents a role of the user in the scope of the modified entity, i.e. Project-level or Global role
  • $Author.ScopedRole.Id, $Author.ScopedRole.Name

For example, allow to modify User Story only if the current user is assigned to it:

Assignments.Count(GeneralUser.Id == $Author.Id) == 0

Accessing values before modification

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.Name is fine, but $Previous.Feature.Epic.PortfolioEpic.Name won't work
• No access to collections, no aggregations, e.g. $Previous.Bugs.Count() > 0 won't work

Detecting deleted references

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:

not $Previous.Release.IsBeingDeleted()

Other DSL features

• $ChangedFields allows to access a collection of modified field names
  • $ChangedFields.Contains("Budget")
• $Modification is 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
  • [Expected Budget] or Feature.[Total Time]