Article published on the 30th of September, 2024.
Contents
1. Introduction
Step validation in WorkPoint Automate is used to check a selection or an input in a field on a form, and evaluate it against a condition, eventually allowing the user to proceed in the process when a valid selection or input has been made.
This is useful for ensuring correct values being passed between steps in WorkPoint Automate processes, and to help minimize human error.
In this article, we will demonstrate a couple of examples where step validation may be useful, and how to configure it.
Note that step validation is different from field validation, which is used for evaluating the input on a specific field against a condition.
2. Validating a selection in a Search form
In this section, we will cover how to set up step validation for selections in a Search form.
When using a search form, users can search for and select an item or entity for further processing in the subsequent steps.
Sometimes is can be useful to validate that the selection made conforms to some condition, and this is what we will demonstrate here.
For demonstration purposes, we have created a column on our Projects' Documents libraries for storing a document category:
We have also created a process, in which the user can select a report document in a Search form, and send it for approval. At the moment, however, any document from the library can be selected. We would like to use validation to ensure that the document selected is categorized as "Report" in the Document Category column.
To do this, we can use the "Validation" tab of the Search form in the Process Builder:
- In the "Conditions" section, we can set up conditions which the document selected must pass in order to be considered a valid selection, and thereby allow the user to continue in the process. If the condition(s) is not evaluated true, then the text in the "Message" section will be displayed above the "Continue" button on the form. You can either construct conditions using the Basic way, or use the Advanced way of adding an adaptive expression. In the further demonstration here, we will use an adaptive expression.
- In the "Message" section, we can type in a message which will be presented to the user if the element they selected in the form does not pass the condition(s) set up in the "Conditions" section. This message will appear just above the "Continue" button in the bottom right corner of the form.
In this demonstration, we use the adaptive expression SearchForm.ccDocumentCategory == "Report" where "SearchForm" is the name of the search form step, and "ccDocumentCategory" is the internal name of the Document Category column we want to check. We have also added a message, letting the user know that the document they selected is not categorized as a report:
Note that in this demonstration, the Search form is configured to not allow multiple selections. If your form does allow for multiple selections, you can validate e.g., the first element by using the 0th index of the SearchForm, like this: SearchForm[0].ccDocumentCategory == "Report".
We can then add the subsequent steps to the process:
Now we can save and publish the process, and run it from a project. When the process opens, we see our Search form, which contains documents of various categories:
If we select a document not categorized as "Report", the message we configured in the Validation tab of the step shows up above the Continue button:
If instead we select one that is categorized as Report, we are allowed to continue to the next step in the process:
This approach works for any element which can be selected in the Search form. It will also work on other types of search forms, such as the "Search for item in list"- and "Search entity" forms.
3. Validating a field entry in a form
In this section, we will give a coupe of examples of field validation. Field validation works by evaluating the input in a field in a form against a given condition. If the condition is fulfilled, the user will be able to proceed in the process. If not, a customizable message is displayed to the user, letting them know that there is a problem with their entry.
3.1. Date validation
In this example, we will use field validation to ensure that one date is not set earlier than another date.
Here, we have a process for creating tasks on our projects:
We would like to ensure that the date set in the "Due date" field is not set earlier than the "Start date" field.
We can do so by configuring validation on the "Due date" field in the process builder. In the image below, we have expanded the options for the "Due date" field on the Item form in the Create task process:
- In the "Validation" field, we can click the "Advanced" button to configure the conditions which must be fulfilled for the entry in the Due date field to be considered valid. If the configured condition(s) is not evaluated to true, then the entry is considered invalid, and the text in the "Validation message" is displayed to the user just below the field itself. You can either construct conditions using the Basic way, or use the Advanced way of adding an adaptive expression. In the further demonstration here, we will use an adaptive expression.
- In the "Validation message" field, we can type a text which will be displayed to the user if the entry they make in the field does not pass the validation condition(s) configured in the "Validation" field. This message appears just below the field itself. If no text is specified in this field, a default message of "Please check the value..." is displayed.
As previously mentioned, in this example, we want to check that the entry in the Due date field is not set earlier than the Start date. We can do so by using the following adaptive expression in the "Validation" field:
greaterOrEquals(formatDateTime(ItemForm.TaskDueDate, 'yyyy-MM-dd'), formatDateTime(ItemForm.StartDate, 'yyyy-MM-dd'))where "ItemForm" is the name of the item form step, and the texts immediately following the dots are the internal names of the date fields we want to compare. Note that the date formats must match in order to the comparison to function properly.
We can then also add a fitting validation message to the configuration:
We can now save and publish the process, and test it out on a project. Here, we are running the process and have given the task we want to create a title:
If we select a due date that is earlier than the Start date, we see the validation message:
Note that if the entry is invalid, we cannot use the "Continue" button to proceed in the process. Instead, a message is displayed above the Continue button, letting the user know that the form is not valid:
If we select a valid date, the messages appear, and we can use the Continue button to proceed:
3.2. Validating an e-mail address
In this example, we will use field validation to validate that the entry in text field contains a valid e-mail address.
For demonstration, we will use a process for creating Customer entities in our solution. Customers contain an "Email" field in which users of the system can type an e-mail address for the customer.
We have already set up a "Create customer" process for this purpose:
Note that the "Name 2"- and "Company ID" fields are set to hidden. This is just to hide them in the form when the process is running.
To configure the field validation on the "Email" field, we can expand the field in the list:
- In the "Validation" field, we can click the "Advanced" button to configure the conditions which must be fulfilled for the entry in the Email field to be considered valid. If the configured condition(s) is not evaluated to true, then the entry is considered invalid, and the text in the "Validation message" is displayed to the user just below the field itself. You can either construct conditions using the Basic way, or use the Advanced way of adding an adaptive expression. In the further demonstration here, we will use an adaptive expression.
- In the "Validation message" field, we can type a text which will be displayed to the user if the entry they make in the field does not pass the validation condition(s) configured in the "Validation" field. This message appears just below the field itself. If no text is specified in this field, a default message of "Please check the value..." is displayed.
For this example, where we want to check that the text in the Email field contains a valid e-mail address, we can use the "isMatch" function in an adaptive expression, and then use a regex expression to check that the text is a valid e-mail address. In this example, we use the following adaptive expression:
isMatch(EntityForm.wpEmail, '^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$')where "EntityForm" is the name of the entity form step, and the text immediately following the dot is the internal name of the Email field.
We also add a fitting validation message in the "Validation message" field:
Let's save and publish the process and try to run it in our solution. Here we are running it from the root site, and we have typed in some metadata for a new customer:
At the moment, our validation message appears because the field is empty, but if we type an invalid e-mail address in, the message stays there, and if we click the "Continue" button, a message appears, letting us know that there is a problem with the form:
If we enter a valid e-mail address, the validation messages disappear, and we are allowed to continue with the subsequent steps:
Comments
0 comments
Please sign in to leave a comment.