DocuPhase Forms latest - This documentation is for DocuPhase Forms v11.3. Not for you? Earlier documentation is available too.

Preconditions

Preconditions add logic to your workflow to conditionally perform or skip steps based on the data entered into prior workflow steps. They are also used to generate/not generate mapped PDFs. The precondition logic is the same used when writing business rules. A step with a precondition will be performed when the precondition evaluates to true and skipped if it evaluates to false.

Add a Precondition

You can add a precondition directly from your workflow diagram.

  1. Click theicon where you would like to add the precondition.
  2. Select Add precondition.

  3. Configure the precondition. 
    1. Provide a Precondition Description, which displays in the workflow diagram. This field is limited to 255 characters, and it is optional. If the description is empty, the Precondition logic is described i.e. "LoanAmount is equal to or more than 50000". 
    2. Add the precondition logic. You must enter a valid precondition in order to click Submit. 

Your precondition will appear in the workflow diagram as a yellow box with Yes and No arrows to illustrate how the workflow will route based on the precondition results. Click that yellow box to edit it.

Edit the Precondition

There are two entry modes for preconditions: Precondition Builder mode and code entry mode. Precondition builder mode is turned on by default. The designer can switch back and forth between the two modes. The Precondition Builder makes it very easy to eliminate incorrect or invalid JavaScript in your precondition statements during the design phase. Use the Precondition Builder to:

  • Write the JavaScript for a precondition on a workflow step.
  • Provide a short business-level description of the precondition to help make the workflow design easier to read.
Run the Precondition Builder
  1. The Precondition Builder is turned on by default. Launch the Builder by clicking in the Precondition logic box or clicking the Edit button.
    1. Click the CLEAR PRECONDITION button to remove any existing Precondition logic, if needed.
  2. This editor uses a modified version of the frevvo Visual Rule Builder where you can build your precondition statement by selecting controls and conditions from the dropdown lists. Note the field dropdowns (left and right sides) will not contain any repeating type fields (tables/repeats).
  3. Create the Precondition by selecting fields from your workflow, an operation, and a value. To enter a literal value, slide the toggle to the right. You can add more than one condition by clicking on the Add Condition button and modify the logic expression, if necessary.
  4. Click OK to save the precondition or click CANCEL to discard. You will be prompted to confirm the cancellation.
Edit Precondition with Javascript

To manually enter the Precondition JavaScript or edit a precondition created using the Precondition Rule Builder by editing the JavaScript code :

  1. Slide the Precondition Builder toggle to the left to turn off the Builder. Be aware that taking this action will remove your ability to edit using the Precondition Builder. A warning message will display:
    1. Click the CLEAR PRECONDITION button to remove any existing Precondition logic, if needed.
  2. Type the JavaScript into the field.
    1. Changes to the precondition trigger code validation. Appropriate messages are displayed if errors are encountered. Errors with information display if the JavaScript is invalid.
    2. It is important that designers test the preconditions in your workflow. The Precondition Builder displays an error if it encounters invalid JavaScript, however, runtime errors such as leaving off the .value are not flagged by the Precondition Builder because the JavaScript is valid. For example, the precondition in the image is missing the .value for the Loan Amount field. This precondition will pass the Precondition Rule Builder validation but it will not work. frevvo will catch this error when the workflow navigates to Step 2. To correct the runtime behavior, change the precondition to LoanAmount.value >=500000

Preconditions only support value-based conditions

Update Business Rules

If you have rules that operate on the step that may be skipped due to your precondition, such as show/hide a signed section, you must update the business rule to add the same condition you used in your precondition logic. 

For example, imagine you have created a 3-step approval workflow using the Workflow Design Wizard.

The wizard included a signed section and rules to show/hide them on their corresponding steps. 

Next, add a precondition on Step 2.

Run the workflow with the precondition not met so that Step 2 is skipped. You will notice that on Step 3, the signed section for Step 2 is required but not enabled, so you cannot submit the workflow. This happens because the rule "On or After Approval Step (Step 2)" is setting the Step 2 approval section visible. When a signed section is visible, it is automatically required. However, the rule "On Approval Step (Step 2)" is setting the same section to disabled on the third step, so you cannot sign it. 

To correct this, we should edit the rule "On or After Approval Step (Step 2)" to have two conditions: the original "current step is on or after" condition, and the same condition that your precondition uses.

Run the workflow again just as before. This time, when the precondition fails the Step 2 approval section will not be visible on Step 3, and you will be able to submit the workflow.

Though this often occurs with rules to show/hide signed sections, you may find that other types of rules that run on or on and after a step with a precondition also require this additional condition that matches the precondition logic.

More Info

If you have an existing precondition that was manually entered into the Precondition Code field when the Builder was turned off (code mode), slide the  to the right to turn the Builder back on. The existing code will be removed but the Precondition Builder will be available again. You will see this message:

To remove an existing precondition step, click the Action Menu and select Delete.

You must enter valid precondition logic to enable the Submit button (when adding the precondition) or navigate away from the Precondition Step when it is selected. If you see this error message, please double check that you have entered valid precondition logic.

  • You cannot use form template syntax in preconditions.
  • Preconditions are re-validated on saving forms/workflows and if there is an error, the user is notified and given an option to re-edit
  • The precondition logic is the same used when writing Business Rules. However, the User Info, Numeric, Boolean and Date/Time functions, added to the Visual Rule Builder, are not available in the Precondition Builder. If you hand type one of these functions, it will validate and but you will receive an error message at runtime.
  • The following operators are supported in precondition expressions:
    • + (add and concat)
    • -
    • * (multiply)
    • /

Make sure the controls used in preconditions are required controls. Controls without values used in preconditions will cause an error in the workflow. Test for this when you are creating workflows with preconditions to ensure that when the workflow designer shares the workflow with others that it will not display an error.

Precondition Examples

 Click here for some Precondition examples

Example 1:

Imagine a mortgage project in which a Supervisor had to perform a step for all mortgages over $500,000.00. The applicant performs Step 1, and enters the loan amount into a field named LoanAmount. Step 2 is performed by a bank Employee and Step 3 is performed by the Supervisor only for mortgages over 500k.

To do this,  use the Precondition Builder or drop in the code to add the precondition before Step 3.

Optional javascript
LoanAmount.value >= 500000

Example 2:

You can also set preconditions based on values in dropdowns and radios. For example, imagine Step 2 contained a dropdown control named SendToSupervisor with the values Yes/No. The Employee could override the logic in the workflow to send for Supervisor approval even for loan amounts under 500,000.00. Add the following precondition before Step 3 (Supervisor Approval).

Optional javascript
(LoanAmount.value >= 500000) || (SendToSupervisor.value === 'Yes')

The Supervisor step would be skipped for loans less then 500,000.00 or if the Employee set Send To Supervisor to 'no'.

Example 3:

In this example if the Supervisor was the one to fill the first step of the workflow then they were required to enter their Supervisor Title, and that field is thus guaranteed to have a value. In this case, to skip the next step and go directly to the Supervision step, add this code - SupervisorTitle.value != '' " to the second step's precondition or use the builder to create a precondition where the second step only executes if the Supervisor Title filed is empty. Then add another OR statement to the precondition on the Supervisor step to execute that step if the Supervisor Title is filled.

Preconditions and Rejecting Tasks to Discard

Preconditions can be used to implement a Reject to Discard scenario as an option for rejecting workflow tasks. Let's say you want to note that a workflow task is rejected (not approved) but still have the form stored as a completed submission in the frevvo repository. Adding preconditions that evaluate to true to later workflow steps will cause those subsequent steps to be skipped and the workflow will complete. The workflow will be saved in the frevvo submission repository with some customized indication that the workflow step was rejected. See the Reject to Discard topic for the details and an example.