Validation Tab

Users of AccuWork create and modify issue records through the Issue form. To increase the efficiency and accuracy of this process, you can create a set of validations to be applied as the user works with the Issue form. (Validations are sometimes called "edit checks".)

You create and maintain the set of validations using a point-and-click interface on the Validation subtab. AccuWork displays the current validations in tabular format; each one takes the form "if a certain condition is true, then perform a particular set of actions".

In this topic:

Initializing Field Values in a New Issue Record

The first entry in the table of validations is special. Its condition is always "initialization of new issue", so that its actions are performed exactly once: between the time the user invokes the New Issue command and the time the new Issue form appears.

To define an action, right-click in the Actions column, then select Add Action from the context menu. An Action window appears, in which you define the action. For initialization of a new issue record, the only appropriate action type is setValue. (Note: Some releases of AccuWork allow you to include setRequired and setChoices actions in a record initialization. Such actions will be ignored when a new record is initialized.)

After setting the action type to setValue, select a field to be initialized and specify the initial value. The Value edit-widget adjusts to the selected field. In the example below, the data type of the state field is choose, so the list-box offers the field's predefined choices as the initial value.

Back to top

Conditional Validations

The setting of initial field values is an unconditional validation: it happens every time a New Issue command is invoked. All other validations are conditional: a certain set of actions are performed if, and only if, a certain condition is met.

The unconditional setting of initial field values occurs just once; but the conditional validations are performed repeatedly: when an Issue form first appears and each time the user changes any field value. Each repetition involves:

• Clearing the "required" status of all fields.
• Performing all validations (except for that first one: "initialization of new issue"). If a validation's condition is true, the corresponding actions are performed.

Specifying the Condition

To create a new conditional validation — that is, a new row in the table — right-click anywhere in the Conditions column, then select Add Condition from the context menu. Then proceed to construct the "if" clause. The same context menu provides the Edit Condition command (for revising an existing "if" clause), and the Remove Condition command (for removing a conditional validation).

Specifying the "if clause" of a conditional validation is very much like specifying an AccuWork database query (see Working in the Query Editor). But there are some differences. In a validation condition, you can:

• Compare the current value of a field with its "old" value — that is, compare the value currently displayed for the field vs. the value stored in the AccuWork database by the most recent Save.

  

• Compare the (current or old) value of a field with the (current or old) value of another field in the same record.

  

• Test the AccuRev user identity or group membership of the person using the Issue form (CUR_USER).

  

Query conditions cannot make such field-to-field comparisons; they can only compare field values to literal values.

Specifying the Actions

Each conditional validation can include any number of actions. You create an action by right-clicking in the Actions column of the validation, and selecting Add Action from the context menu. This displays a window in which you define the action.

After you've created one or more actions for a conditional validation, you can use the same context menu to revise or delete individual actions.

The following sections describe the actions that you can define to be performed if the validation condition is true. Each validation can invoke any number of actions, of any type.

• Setting a field value (setValue)
• Revising the choices for a "choose" field (setChoices)
• Requiring a value to be entered in a field (setRequired)
• Setting permissions on all or part of the issue record (setIssuePermission, setTabPermission, setFieldPermission)
• Requiring change set entries (setChangesRequired)
• Requiring a relationship with another issue record (setParentRelationshipRequired, setChildRelationshipRequired)
• Constraining groups displayed (setGroupChoices)
• Associating a user-type issue field with a group-type field. The choices for the user-type field are restricted to the user members of the group selected in the group-type field (filterByRelatedGroup)
• Constraining the drop-down for a user-type field to include only the user members of a specified set of groups (filterByGroups)

Setting a Field Value

In addition to initializing field values (see Initializing Field Values in a New Issue Record), you can set the values of fields while the user is working with the record, based on certain conditions. For example, if the user enters ColorStar in the program_name field, a validation could automatically set the fix_priority field to high . (Management has mandated rapid improvement in the robustness of the ColorStar application.)

To define a setValue action for a validation condition:

1. In the Action window, select setValue as the action type, and select the field to be set.
2. The Value edit-widget adjusts to the selected field, just as it does when you're initializing a field in a new issue record.

For a "text", "log", or "timespan" field, you enter a text string as the value; for a "date" field, you specify a date in the standard way; for other field types, you use a list-box to specify any of the field's predefined values.

Back to top

Revising the Choices for a "choose" Field

The definition of each field of type "choose" includes an ordered list of strings. The user fills in this field by choosing one of the strings from a list-box.

In a validation, a setChoices action can change the "choice list" that the user will see when he opens the list-box: The changes to the choice list can include:

• Removing one or more of the existing choices
• Changing the order of the choices

You cannot add new strings to the choice list with a setChoices action. The changes made by a setChoices action are temporary: they last only until the next setChoices action on the same field, or until the user closes the Issue form. When an Issue form is opened on another issue record (or subsequently on this issue record), the user will see the field's original choice list, as defined on the Schema tab.

To define a setChoices action for a validation condition:

1. In the Action window, select setChoices as the action type, and use the Field list-box to select one of the database's fields of type "choose".
2. Use the controls at the bottom of the Action window to define the temporary change to the choice list:

Requiring a Value to be Entered in a Field

Like many other programs that process fill-in-the-blanks forms, AccuWork can treat certain fields as required fields — the user must specify a value in each such field before AccuWork will create or update an issue record. (For a "choose", "list", or "user" field, the value must not be blank.)

AccuWork affords you great flexibility in controlling required fields. A field's "required" status is not part of the basic database schema. Instead, it is controlled by the conditional-validation facility. Thus, AccuWork repeatedly redecides whether a field is required: when the Issue form first appears and each time the user changes any field value on the Issue form. Whenever the user clicks the Save button, AccuWork uses the current set of required fields to allow or disallow the "save" operation.

To define a setRequired action for a validation condition:

1. In the Action window, select setRequired as the action type.
2. Select the field to be required.

If you want a field to be required in all circumstances, use the setRequired action along with a condition that's always true. For example, you can exploit the fact that every issue record has a positive integer as its issue number:

Setting Permissions on All or Part of the Issue Record

The setIssuePermission, setTabPermission, and setFieldPermission actions are essentially similar: they restrict the editability of some component of the issue record:

• setIssuePermission makes the entire issue record read-only.
• setTabPermission makes a particular page (tab) of the Issue form read-only.
• setFieldPermission makes a particular field of the issue record read-only.
• There are two attributes that you can assign to these actions:
• ro — Make read-only for all situations.
• auto — (AccuRev Workflow only.) Make read-only for end-users, but allow AccuRev to make changes.

The "read-only" ( ro ) permission affects the user's current access to the issue record; the "read-only" status is not stored in the repository as part of any issue record. For example, user allison might find that she cannot change any fields on the Assignment page of any issue record, because of this validation:

This restriction affect allison 's access to issue records; other users' access remains unaffected. And if this conditional validation is subsequently removed, allison will regain access to the Assignment page of all the issue records.

Note that setting read-only permission on an issue record will affect the behavior of AccuRev commands such as cpkremove and promote, in addition to restricting the user's ability to edit the issue.

The “automatic” ( auto ) permission is similar to ro, but in AccuRev Workflow, AccuRev can perform actions that end-users are prevented from making as described above. For more information about AccuRev Workflow-specific details, see the AccuRev Web Interface User’s Guide.

We recommend that each change to the schema be tested thoroughly to prevent unexpected side-effects to your organization's processes.

Requiring Change Package Entries

The setChangesRequired action specifies that the user cannot Save an issue record unless there is at least one entry in the issue record's change package.

Requiring a Relationship with Another Issue Record

The setParentRelationshipRequired action specifies that the user cannot Save an issue record unless there is at least one entry in the lower table of a particular relationship field.

The setChildRelationshipRequired action specifies that the user cannot Save an issue record unless there is at least one entry in the upper table of a particular relationship field.

You cannot set both these requirements for the same relationship field, because each field can have parent relationships or child relationships, but not both.

Revising and Removing Validations and Actions

Each conditional validation consists of a condition (left column) and a set of actions (right column). To revise or remove an entire validation, right-click anywhere within the condition, and select the appropriate command, Edit Condition or Remove Condition, from the context menu.

To revise or remove an individual action from a validation, right-click on that action and select the appropriate command — Edit Action, Remove Action, or Add Action — from the context menu.

AccuWork also has two unconditional validations — "initialization of new issue" and "initialization of cloned issue". These two validations are performed in the specified order, and you cannot remove them from the Validation tab.

Back to top