Related Topics
Conditions are true or false statements that are evaluated in order to determine an appropriate response. Process Director includes a Condition Builder that enables you to create conditions to test nearly any value you desire. You'll see the Condition Builder in many different places, such as when to make a form field enabled or hidden, or what value to return from a Business Rule. The Condition Builder is usually invoked by an action link that is labeled Click to create condition.... Anywhere you see this link, you can open the Condition Builder by clicking on it.
Adding a condition to a specific option makes it easy to set a value or perform an action based on your preference.
Adding a Condition #
When the Condition Builder has been invoked, you may add a condition by selecting the Add Condition button .
Once you click the Add Condition button, the first conditions row will appear, and the first control in the row (we refer to this as the “left-hand side” of the condition) is a Picker control that will display the text, “Form Field” in most contexts. You'll use this Picker control to set the variable that you'll evaluate for the condition. The middle control is a Dropdown control that enables you to pick the method for comparing the system variable to a desired value, which is called the operator. Finally, there is, for most variable types, a third field, which is the desired value to which you wish to compare the system variable. We refer to this as the "right-hand side" of the condition.
Not all system variables will have a desired, or right hand side value. For instance, boolean variables only return true or false. As such, they aren't compared to a desired value, merely evaluated to determine if they are true or false.
System Variable #
Click the Picker Control’s Build button to reveal the Choose System Variable dialog box. This dialog box contains all of the system variables that are available for evaluation.
All of the system variables are organized in a dropdown menu that divides the system variables into a number of categories, as shown above. Use the dropdown menu to select the appropriate system variable. Once you've selected the system variable, click the OK button to close the dialog box and set the system variable in the condition row. Please see the System Variables Reference Guide for a description of all the possible system variables that may appear in the dropdown. This dropdown menu is context-sensitive, so, depending on where you are using the Condition Builder, different options will appear that are relevant to the selection or filtering operation you are conducting.
For process Director v5.32 and higher, the Condition Builder won't include fields that have no value, like Embedded Sections, or labels, when evaluating form fields
Operator #
Once the variable has been selected, you must choose an operator for the variable, i.e., the method we will use to compare the variable to the desired value. A number of operators are available, and the type of available operators will depend on the type of system variable you select. A Boolean system variable, for instance, will only allow you to select whether the variable is true or false, while a string variable will provide a much wider array of choices.
In general, the following operators are available:
= (Equals)
This operator requires that the system variable and the desired value match exactly. You should only use the = operator when you're using fixed, predictable values. For example, you shouldn't use this operator when comparing dates, unless you're sure that both the date and time values will always match, to the second. Otherwise the data comparison will always return false for the date evaluation.
<> (Does Not Equal)
This operator requires that the system variable and the desired value don't match.
A search for fields that are NOT empty can be performed using this operator with the syntax :
Value <> ""
< (Less Than)
This operator requires that the value of the system variable be less than that of the desired value.
<= (Less Than or Equal To)
This operator requires that the value of the system variable be less than or equal to that of the desired value.
> (Greater Than)
This operator requires that the value of the system variable be greater than that of the desired value.
>= (Greater Than or Equal To)
This operator requires that the value of the system variable be greater than or equal to that of the desired value.
In
This option is primarily designed to match a value to a list of values. For instance, of the left side of the condition contains a user, and the right side of the condition contains user group, this operator will determine if the user is contained in the group. Similarly, if the value on the left is a string and the value on the right is a comma-separated list of values, the In operator means “in that list”. If the value is determined to be in the list of values, this operator will return "true"
Not In
This option is also primarily designed to match a value to a list of values, though, in this case, it returns "true" if the value isn't in the list.
A User filter on a Knowledge View will now support "user IN/NOT (group or user list)". If it is a "user IN group list", the filter will return True if the user is in ANY of the groups. If you have a "user NOT IN group list" filter, then the filter will return true if the user is NOT IN ANY of the groups.
Contains
The string value of the System Variable is contained in the string value of the desired value. For instance, a desired value of "Rejected" would contain a system variable with the string value of "Reject".
Does Not Contain
The string value of the System Variable isn't contained in the string value of the desired value.
Matches
This operator works similarly to the Contains operator, but supports the ability to use AND and OR operators in the filter string. The filter string can also contain double quotes to force the search on that entire character string. If there is no operator between strings, or a ",", these will be treated as "AND". Additionally, the Matches operator supports a Regular Expression (REGEX) value for the desired value.
No Earlier Than
This operator is applicable only to date/time values. In enables you to specify the lower bound of a date range.
No Later Than
This operator is applicable only to date/time values. In enables you to specify the upper bound of a date range.
Full-Text Search Operators #
For Process Director v5.21 and higher, full text search operators enable you to use nonspecific or "fuzzy" search terms to return a larger set of potential matches for a search term. Please remember that full-text searching can be resource-intensive, may take a long time, and may return an unexpectedly large set of search results, depending on the precision of your search terms. There is a custom variable, fCONTAINSUseValueSearchOnly, that can speed up full-text searching, though at the cost of some search accuracy.
To implement full-text searching, you must enable it on your system by performing the following process:
- While in debug mode, click the command in the troubleshooting page to create the index and catalog. There is another link to see status, and another to turn off full-text searching. Turning on this feature may take a while to complete on existing databases.
There are some restrictions that you must keep in mind when using full-text search operations.
- Partial word searches must start with the beginning of the word.
- Some words may not be found if they contain special characters that the database considers to be a "stop word". For instance a word that contains a number may be ignored, even though it otherwise matches the search term. What constitutes a "stop word" depends on the system settings of your database, so Oracle and SQL Server may operate differently.
You can turn the stoplist off on SQL Server by using the following SQL Command in the SQL Server Management Console:ALTER FULLTEXT INDEX ON tblFormData SET STOPLIST = OFF
To turn the stoplist ON with the default of "system" use this SQL command:ALTER FULLTEXT INDEX ON tblFormData SET STOPLIST = SYSTEM
Once full-text searching is enabled, the following operators will be come available when appropriate.
Starts With
This full text search operator enables you to find text strings that begin with the specified search term. For instance, a Starts With search for "ham" will return "hammer", "ham-fisted", "Hamlet", "Hamilton", hamburger, etc.
Contains (Lexical)
This full text search operator enables you to perform a search of text that returns terms that are lexically similar terms to the search term. For instance, a search for "check" will return items that contain the lexical matches such as "Uncheck", "Checked", "Checking", "Checker", etc.
Desired or Comparison Value #
Once the operator has been selected, you must provide the desired value on the right hand side of the Condition Row, to which the System Variable will be compared. The desired value can be derived from Process Director, or manually entered by the user. A dropdown menu is available to select the type of desired value. Different data types will present different items in the dropdown menu, each of which is appropriate to the data type you are comparing.
Depending on which item you select from the dropdown menu, the appropriate selection or input method, if necessary, will be displayed in the Condition Builder to enable you to enter the appropriate comparison value. For instance, if you select a "String" as the desired comparison value, a text box will be provided into which you can type the string value you desire.
In the example above, the condition requires that the value of the Sample-Fill 2 Dropdowns form field equal the desired string value, "Another String".
Managing Conditions
Once a condition has been created, you may remove a condition by selecting the red “x” icon next to the condition to be removed.
You may also select the green arrow icon to insert a new condition to be included in that condition.
You may also select the Add Condition button to insert another condition but to use it as an OR condition.
Once you've set your conditions for your option you can save it by clicking the OK or the Update buttons.
Using Arrays in Form Validation Conditions #
Validation filter conditions that use Array fields on a Form can be complex, and may not work in the way you expect, because various filter conditions operate differently, depending on whether you are trying to filter based on a single (scalar) value or an array (column) value, and whether the value is used on the left or right side of the operator in the Condition Builder. The various condition scenarios are described in the table below.
| LEFT SIDE | RIGHT SIDE |
COMPARISON BEHAVIOR |
EXAMPLE |
||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Scalar | Scalar | Simple comparison of the two values. For instance, if you wanted to search a Form Field named favoriteColor for the color Blue, the comparison would be:
If the favoriteColor field contains the value "Blue" the condition will return "true". |
Field1="Value" | ||||||||||||||||||
| Column | Scalar |
The column value on the left side of the operator is returned as a comma-separated list, and the condition will evaluate to see if the scalar value on the right side is contained in the list. This condition will return "true" if the scalar value matches the condition for any row in the array column. For instance, let's assume we have an array column named primaryColors, containing the following values: Row [1]: red Row [2]: blue Row [3]: yellow Any of the following comparisons will return "true":
|
Column1=Field1 Column1<=Field1 |
||||||||||||||||||
| Scalar | Column |
The column value on the right side of the operator is returned as a comma-separated list, and the condition will evaluate to see if the scalar value on the left side is contained in the list. This condition will return 'true" if a matching value is found. For instance, let's assume we have an array column named primaryColors, containing the following values: Row [1]: red Row [2]: blue Row [3]: yellow Any of the following comparisons will return "true":
|
Field1 IN Column1 | ||||||||||||||||||
| Column | Column |
Each row in the column is compared with the corresponding column in the same row. This condition will return "true" if any row comparison matches the operator. For instance, let's assume we have two array columns, primaryColors and berryColors, containing the following values: Array column “primaryColors” Row [1]: red Row [2]: blue Row [3]: yellow Array column “berryColors” Row [1]: red Row [2]: black Row [3]: blue The comparison condition would be:
Since Row[1] matches the condition, the condition will return true. |
Column1=Column2 |
Client Validation #
In Process Director v5.1 and higher, a client side validation function allows conditional processing on form fields to occur in the client browser without having to make the form fields into event fields, and reposting the form when the fields change.
These conditions are used to control the display/hidden “when”, enabled/disabled “when”, and required/not required “when” settings in the properties displayed from the Form Controls tab of the form definition.
When this client side condition flag is enabled, system variables will only be evaluated once on the server when the page is displayed or an event occurs. Form fields, however, will always use to most current form data on the visible form when evaluating the condition, because the evaluation will take place in the client browser, and will not require the form to be reposted to the server to evaluate the form fields.
By default, the traditional server-side evaluation method will be the default evaluation method for conditions, unless you specifically choose to use client validation.
As of Process Director v5.1, only the following control types can be used for client-side conditional processing, both for Showing/Hiding and for the querying of live data:
- Input/Text
- Checkbox
- Date
- Dropdown
- Buttons
- Sections
Date Comparison Issues #
First of all, using the "=" operator is usually a bad idea for date comparisons. Date fields—even those where you don't explicitly set a time—always have a time value. The database default time for DateTime fields is always precisely 12AM, e.g., 1 Jan 2023 00:00:00. Obviously, if you use a DateTime Picker control, the time element will be whatever is explicitly set. In either case, the date will always have a time value as part of the data. Since the "=" operator always requires that two values match exactly, if the two time elements are even one second off when the evaluation occurs, a date comparison that uses the "=" operator will always return false. The "=" operator can only return true at a single second in time. Date comparisons should use either the "<" or ">" operators.
Next, while comparing two known dates is relatively simple, date comparisons in conditions can use a variety of date calculations such as "Days Ago", "Weeks Ago", etc., which also enable you to specify the number of days or weeks. Making these types of date comparisons in conditions are slightly more complicated than one might think.
Let's say you wish to create a condition to see of the start date of a Process Timeline activity was more than 2 days ago. To properly set this condition, your condition would look like:
(Activity Start Date [ActivityName] < 2 Days Ago)
Note that this condition uses the Less Than (<) operator and not the Greater Than (>)operator. Why is this, if I'm looking to see if the Activity start date is "greater" than 2 days ago? Well, it's because the 2 Days Ago element doesn't take the Activity Start Date and calculate to see if it's now more than two days later. Instead, the 2 Days Ago element independently returns whatever the datetime value was exactly two days before the evaluation.
You're not really asking if the Activity Start Date was more than 2 days ago. What you're actually asking is whether the Activity Start date is earlier than whatever date is returned by the 2 Days Ago element.
For example, let's say the Activity Start Date was 1 Jan 2023 09:00:00. If you were to evaluate the 2 Days Ago element at exactly the same time the Activity started, it would return 29 Dec 2022 09:00:00 as the date.
1 Jan 2023 09:00:00 is later (>) than 29 Dec 2022 09:00:00. Since that is so, the condition will evaluate as false, which is what we want.
On the other hand, if the 2 Days Ago evaluation is performed at 9:01AM on 3 Jan 2023, the 2 Days Ago element will return 1 Jan 2023 09:01:00, The Activity Start Date of 1 Jan 2023 09:00:00 is now one minute earlier (<) than1 Jan 2023 09:01:00. Our condition will evaluate as true, therefore, on at any time after 9AM on 3 Jan 2023, as the Activity Start Date will now always be earlier (<) than the date returned by the 2 Days Ago element of the condition.
Documentation Feedback and Questions
If you notice some way that this document can be improved, we're happy to hear your suggestions. Similarly, if you can't find an answer you're looking for, ask it via feedback. Simply click on the button below to provide us with your feedback or ask a question. Please remember, though, that not every issue can be addressed through documentation. So, if you have a specific technical issue with Process Director, please open a support ticket.
