Chapter 9 - Recipes

Each recipe is a complete, small build that combines rules from the earlier chapters. Follow the steps as written the first time; afterwards they serve as patterns to adapt. All of them were built and run in the sample template used for this manual.

Every recipe has the same shape: Goal, Rules used, Steps, Check, Pitfalls.

9.1 Auto-fill the requester from the user profile

Goal: when the form opens, the requester's name and e-mail are already filled in and cannot be edited.

Rules used: on-load action rule with a qRules command (Ch. 3, 6), formatting rule Disable (Ch. 5).

Steps

1. Form > Form Load Rules > +, name it Load user profile.
2. Add Run a qRules Command, insert GetUserProfileByName from the Command Builder (source: Site Users List).
3. Add Set a field value: Field = RequesterName, Value = Value[Name = "PreferredName"] from the GetUserProfileByName data source with the filter ../../../tns:Name = "PreferredName".
4. Add another Set a field value: Field = RequesterEmail, same path with "Email".
5. Select the RequesterName text box on the canvas, Formatting Rules > +, name Lock requester, condition RequesterName is not blank, tick Disable this control. Repeat for the e-mail box.

Check (Open Ctrl+O):

Pitfalls: forgetting tns: in the filter; putting the Set actions before the command action; using a Hide rule instead of Disable, which hides the value the user should see.

9.2 Validate before submit

Goal: the Submit button runs the validation rules, refuses to submit while any of them fires, and tells the user what to fix. (Validation rules do nothing until a button runs GetErrors; see Chapter 4, section 4.1.)

Rules used: validation rules (Ch. 4), button action rules with qRules commands and the stop flag (Ch. 3), formatting rule Hide (Ch. 5).

Steps

1. Add validation rules to the fields that need them (required, format, cross-field).
2. Add two text fields to the main data source, ErrorCount and ErrorMessage, and place them read-only at the top of the form.
3. Select the Submit button, Action Rules > +, name Run Validation, actions in this order:
4. Run a qRules Command "GetErrorCount /novalidate=false"
5. Set a field value: ErrorCount = concat(GetDOM("QdabraRules")/QdabraRules/Result, " error(s) found. Please fix the errors below.")
6. Run a qRules Command "GetErrors /format=fieldAndMessage /novalidate=false"
7. Set a field value: ErrorMessage = GetDOM("QdabraRules")/QdabraRules/Result
8. + again, name Stop if Validation Error Exists, condition ErrorMessage is not blank, tick Stop after this rule runs. A rule needs at least one action to run, so add a harmless one (the sample template sets a scratch attribute to an empty string); the rule exists for its stop flag.
9. + again, name Submit, action Submit data with your submit connection, then Close the form if wanted.
10. Select the ErrorCount control, Formatting Rules > +, condition ErrorMessage is blank, tick Hide this control. Same for ErrorMessage.

Check (Open Ctrl+O):

Pitfalls: the stop rule placed below the submit rule (it must be above); passing /novalidate=true to GetErrorCount or GetErrors, which skips the fresh validation pass (the default false is what you want here); forgetting to clear ErrorMessage, so the summary from a previous attempt stays (clear both fields as the first actions of Run Validation).

9.3 Show a section only when it applies

Goal: an "Additional details" section is hidden unless the user ticks "Needs review", and its fields are only required when it is shown.

Rules used: formatting rule Hide (Ch. 5), conditional validation (Ch. 4), action rule to clear values (Ch. 3).

Steps

1. Select the section control, Formatting Rules > +, name Hide unless review, condition NeedsReview ≠ true, tick Hide this control.
2. For each required field inside the section, Validation Rules > +, condition Field is blank AND NeedsReview = true, screentip "Required when review is needed."
3. Select the NeedsReview check box, Action Rules > +, name Clear review details, condition NeedsReview ≠ true, actions: Set a field value for each field in the section to "".

Check (Open Ctrl+O):

Pitfalls: making the fields plainly required (rule fires while the section is hidden and blocks submit); forgetting step 3, which leaves stale values in the data when the section is hidden again.

9.4 Derive one field from another

Goal: the e-mail address is proposed from the name, but a value the user typed is not overwritten.

Rules used: field action rule with a formula and a condition (Ch. 2, 3).

Steps

1. Select the Name text box, Action Rules > +, name Propose e-mail.
2. Condition: EmailAddress is blank AND Name is not blank.
3. Action: Set a field value, Field = EmailAddress, Value = concat(., "@example.com") (insert . with the picker; it stands for the rule's own field).

Check (Open Ctrl+O):

Pitfalls: typing Name instead of inserting the field (the editor reports "Could not resolve"); omitting the is blank guard, which overwrites the user's edit on every keystroke.

9.5 Status-driven form

Goal: a Status field (New, Submitted, Approved) controls what the user can see and change.

Rules used: formatting rules Hide and Disable (Ch. 5), button action rules with Switch views and Set a field value (Ch. 3), validation guarded by status (Ch. 4).

Steps

1. Add a Status field with default New; show it read-only.
2. Each input control in the requester section: Formatting Rules, condition Status ≠ New, Disable this control. (Sections themselves cannot be disabled; build the rule once and use Copy Selected Rule / Paste Rules for the other controls.)
3. Approval section: Formatting Rules, condition Status = New, Hide this control.
4. Submit button: after the validate-before-submit rules (9.2), add an action rule Mark submitted with Set a field value Status = "Submitted" and, if you use a separate approver view, Switch views.
5. Approve button: Formatting Rules, condition Status ≠ Submitted, Hide this control; Action Rules: Set Status = "Approved", then Submit data.
6. Validation on approval fields: condition Field is blank AND Status = Submitted.

Check: walk a form through New, Submitted, Approved and confirm at each step which sections are visible, which are editable, and which button is offered.

Pitfalls: setting Status before validation has passed (put Mark submitted below the stop rule); forgetting that hidden sections still validate (guard every validation with Status).

9.6 Manager-only approval

Goal: only managers see the approval section.

Rules used: on-load profile query (Ch. 6), formatting rule Hide (Ch. 5).

Steps

1. In the on-load rule from 9.1, add Set a field value: UserTitle = the profile Value[Name = "Title"] (or UserDepartment from "Department", or a flag computed from a managers list you query).
2. Select the approval section, Formatting Rules > +, name Managers only, condition UserTitle does not contain Manager, tick Hide this control.

Check: Open (Ctrl+O) as a manager and as a non-manager (two test accounts).

Pitfalls: relying on hiding alone for security. A hidden section is still in the form data; if approval must be enforced, also check the role on submit (a validation or stop rule on the Approve button) and restrict the library with SharePoint permissions.

9.7 Environment-safe template (Dev and Prod)

Goal: the same template file works on the Dev site and the Prod site without edits.

Rules used: Dynamic Data Connections (Ch. 7) and one of the two designs in Chapter 8.

Steps: follow Chapter 7 to add and configure the XTP, switch off Query during form load on re-pointed connections, and order the finishedLoading rules; then pick Approach 1 (separate sites, identical names) or Approach 2 (one site, template name switch) from Chapter 8.

Check: the Debug Slider log shows ChangeConnectionUrl / ChangeSubmitUrl lines for the current site on both environments; a test submit lands in the right library on each.

Pitfalls: leaving one connection with Query during form load on; a rule that queries data sitting above Run Dynamic DCs.

Next: Chapter 10 - Rule Inspector.