Runtime Prompts: Merge User Input With Documents At Runtime

Video Tutorial

Introduction to Runtime Prompts

The S-Docs Runtime Prompts feature allows you to set up forms with questions for users to respond to during the document generation process. This form input can then be merged into the document and/or conditionally render certain sections of the document.

Setting up a template with Runtime Prompts is fairly simple: open your template in the Template Editor and head over to the Runtime Prompts tab.

Overview of the Runtime Prompts menu

Although different options will appear for each type of prompt, this is the basic layout of the Runtime Prompts menu. Each piece of input you'd like to collect from your users is called a "Prompt." You can create as many as you like. To create a basic prompt:

[1] Select the type of prompt you would like users to answer: Text, Date, Checkbox, or Related List.

[2] Name the merge field for this prompt and place it within the template body. The user's response to the prompt will appear where the merge field is placed.

Note: Merge field name must start with a letter; numbers or symbols will cause an error.

[3] Write the prompt itself. This is the question the user sees and responds to during the document generation process.

We will now go over the options for each individual prompt type.

The Four Types of Prompts

As we stated before, you can choose from Text, Date, Checkbox, and Related List Prompts.

Text Prompts

Text prompts are simple free-form text fields that the user can type whatever they want into. This is the text prompt menu:

[1] Set the prompt type to Text to create a text prompt.
[2] Make this prompt required or optional. The user will not be able to finish generating this document without responding to this prompt if it is required.
[3] Name the merge field for this prompt and place it within the template body. This name cannot start with a number or special character. The user's response to this prompt will appear where the merge field is placed. This merge field can also be used within conditional statements.

Note: Merge field name must start with a letter; numbers or symbols will cause an error.

[4] Preformatting tool to assign a specific number of characters that can be entered. Use an X to indicate any single-character input, or use a # to indicate a digit. For example, for U.S. phone numbers, do '(###) ###-####'.
[5] Write the text prompt itself. This is the question the user sees above the text box during document generation.
[6] Choose a Salesforce text field to write this data back to.

Note: Omit curly braces for Writeback merge fields used within Runtime Prompts. For example, instead of {{!Opportunity.Description}}, write Opportunity.Description.

[7] Allow the end-user to respond with rich text (e.g. bold, italics, tables, images, links) and create new lines of text with the Enter key.

Note: If this checkbox is checked, be sure to reference this merge field with 3 sets of curly braces instead of 2 (e.g. {{{!RichTextField}}})

[8] Choose which page this text prompt should appear on. You can create up to 10 different pages for your Runtime Prompts.
[9] Specify conditions for this prompt to be shown. This field accepts conditional statements, and can be used with regular merge fields and Runtime Prompt merge fields (see the Runtime Prompt Decision Trees section of this article for more information).
[10] Choose to prepopulate this prompt with the user's previous response. This means that if they typed "Example Response" into the text box the last time they generated this document, the default value for this field will be "Example Response" the next time they generate it.
[11] Specify a default value for this prompt. This will be used if the user leaves the prompt blank.

Note: You can only specify a default value if the prompt is not required.

Text prompts look like this at runtime:

Date Prompts

Date prompts provide a date picker that the user can choose a date from. This is the date prompt menu:

[1] Set the prompt type to Date to create a date prompt.
[2] Make this prompt required or optional. The user will not be able to finish generating this document without responding to this prompt if it is required.
[3] Name the merge field for this prompt and place it within the template body. This name cannot start with a number or special character. The user's response to this prompt will appear where the merge field is placed. This merge field can also be used within conditional statements.

Note: Merge field name must start with a letter; numbers or symbols will cause an error.

Note: This date field can be formatted with format-date (e.g. {{!ExamplePrompt MM/dd/yyyy}}), or it can be used to filter a WHERE clause in your related list (e.g. WHERE CreatedDate > {{!ExamplePrompt}}), or it can do pretty much anything else an ordinary date merge field can do.

[4] Write the date prompt itself. This is the question the user sees above the date picker during document generation.
[5] Choose a Salesforce date field to write this data back to.

Note: Omit curly braces for Writeback merge fields used within Runtime Prompts. For example, instead of {{!Opportunity.Description}}, write Opportunity.Description.

[6] Choose which page this date prompt should appear on. You can create up to 10 different pages for your Runtime Prompts.
[7] Specify conditions for this prompt to be shown. This field accepts conditional statements, and can be used with regular merge fields and Runtime Prompt merge fields (see the Runtime Prompt Decision Trees section of this article for more information).
[8] Choose to prepopulate this prompt with the user's previous response. This means that if they chose "8/11/2021" the last time they generated this document, the default value for this field will be "8/11/2021" the next time they generate it.
[9] Specify a default value for this prompt. This will be used if the user leaves the prompt blank. You can use merge fields and static text.

Date Prompts look like this at runtime:

Checkbox Prompts

Checkbox Prompts provide users with a variety of options to choose from. This is the checkbox prompt menu:

[1] Set the prompt type to Checkbox to create a checkbox prompt.
[2] Name the merge field for this prompt and place it within the template body. This name cannot start with a number or special character. The user's response to this prompt will appear where the merge field is placed. This merge field can also be used within conditional statements.
[3] Write the checkbox prompt itself. This is the question the user sees above the list of checkbox options during document generation.

Note: Merge field name must start with a letter; numbers or symbols will cause an error.

[4] Choose a Salesforce text field to write this data back to.

Note: Omit curly braces for Writeback merge fields used within Runtime Prompts. For example, instead of {{!Opportunity.Description}}, write Opportunity.Industry.

[5] Specify the minimum and maximum number of options that can be selected by the user. If you leave these fields blank, users will be able to select all options.
[6] Choose which page this checkbox prompt should appear on. You can create up to 10 different pages for your Runtime Prompts.
[7] Specify conditions for this prompt to be shown. This field accepts conditional statements, and can be used with regular merge fields and Runtime Prompt merge fields (see the Runtime Prompt Decision Trees section of this article for more information).
[8] Choose to prepopulate this prompt with the user's previous response. This means that if they chose "Option A" the last time they generated this document, the default value for this field will be "Option A" the next time they generate it.
[9] Specify a delimiter to separate multiple values by in the document. For example, say your Options are OkayGoodBetter, & Best, your merge field is {{!ExamplePrompt}}, and your delimiter is "AND." If the user selects GoodBetter, and Best at runtime, then {{!ExamplePrompt}} will be replaced with "Okay AND Good AND Best" in the final document.
[10] Allow the user to collapse the checkbox options and only show the prompt on screen.
[11] Create the checkbox Options for users to choose from. An Option can be just one word, or it can consist of heavily formatted rich text paragraphs; you can even use merge fields in an Option. You can define as many Options as you'd like.
[12] Choose to have options appear checked or unchecked by default.
[13] Add or remove as many options as you'd like.
[14] Specify a default value for this prompt. This will be used if the user leaves the prompt blank. You can use merge fields and static text.

Now, what about picklists? Where are the Picklist Prompts!? Trick question - they're here! Runtime Prompts plays off of simplicity and flexibility to allow you to get a lot of power out of these three little Prompt types.

So, how can we get a picklist? Well, let's start with what a picklist functionally is: a collection of options that allows for the selection of exactly one of those options. In other words, a list of options from which you can select a minimum of 1 option and maximum of 1 option, meaning you can simply create a Checkbox Prompt with "1" as the value for both "Minimum number of options that can be selected" and "Maximum number of options that can be selected."

Checkbox prompts look like this at runtime:

Related List Prompts

Related List Prompts display records from a related list and allow the user to select which records to include in the document. They can be used with LineItemsSOQL queries. This is the related list prompt menu:

[1] Set the prompt type to Related List to create a related list prompt.
[2] Enter a name to be included within <runtimeprompts> tags within your LineItemsSOQL statement. This name cannot start with a number or special character. Let's say we wanted users to be able to select which opportunitylineitems to include in a table on a quote. The LineItemsSOQL statement would look similar to the following:

<strong>Products</strong>
<table cellpadding="4" cellspacing="0">
    <thead>
        <tr>
            <th>name</th>
            <th>quantity</th>
            <th>listprice</th>
            <th>totalprice</th>
            <th>productcode</th>
        </tr>
    </thead>
    <tbody><!--{{!
<LineItemsSOQL>
<runtimeprompts>ExamplePrompt</runtimeprompts>
<uniqueid>123</uniqueid>
<class>table151</class>
<soql>
SELECT name, quantity, listprice, totalprice, productcode
FROM opportunitylineitem
WHERE opportunityid='{{!Opportunity.id}}'
</soql>
<column>name</column>
<column>quantity</column>
<column>listprice</column>
<column>totalprice</column>
<column>productcode</column>
</LineItemsSOQL>
}}-->
    </tbody>
</table>

Note that the "Merge Field Name" goes inside <runtimeprompts> tags. You must also enter a unique ID (any unique string of numbers) and enter it within <uniqueid> tags, as shown above.
Upon generating the document, users would be presented with a list of related opportunitylineitems that displays the name, quantity, list price, total price, and product code of each product. They could then select which products to include in the document's related list table.

Note: Merge field name must start with a letter; numbers or symbols will cause an error.

[3] Use this merge field in your document to reference the record IDs that the user selects from the Runtime Prompt related list. For example, you could write a new SOQL query in your document that only displays the records chosen, similar to the following:

SELECT ... FROM .... WHERE id IN {{!ExamplePrompt}}

You can also use this merge field in additional related list runtime prompts, so that only the records chosen in one prompt will display in another prompt. If you opt to do this, each prompt must be on its own Runtime Prompt page.
[4] Write the related list prompt itself. This is the question the user sees above the list of related list records during document generation.
[5] Specify the minimum and maximum number of records that can be selected by the user. If you leave these fields blank, users will be able to select all records.
[6] Choose which page this related list prompt should appear on. You can create up to 10 different pages for your Runtime Prompts.
[7] Specify conditions for this prompt to be shown. This field accepts conditional statements, and can be used with regular merge fields and Runtime Prompt merge fields (see the Runtime Prompt Decision Trees section of this article for more information).
[8] Choose to automatically select each record in the related list by default (the user could then uncheck items that shouldn't be included).

Related list prompts look like this at runtime:

Runtime Prompt Decision Trees

You can conditionally show certain prompts based on responses given for previous prompts, meaning that you can create complex decision trees for your documents. We'll demonstrate this with the following example.

Example Use Case

Alex owns a professional paint removal service. His representatives conduct preliminary evaluations at their clients' homes, then send follow-up letters afterward. Alex wants his representatives to be able to generate these letters from a pre-made template - the only problem is, there are different types of paint removal and methods of getting it done. Alex doesn't want his employees to have to choose from a list of 20 different templates each time they want to send a follow-up letter!

Luckily, Runtime Prompts can help him out. Let's take a look at the possible choices that Alex's representatives have for their letters:

Setting Up The Prompts

The two initial options are lead paint removal and basic paint removal. For these, Alex [1] creates a simple checkbox prompt. [2] He names the merge field "RemovalOption," and [3] chooses to have it appear on page 1 of the Prompts, since it is the first question that needs to be asked. He [4] leaves the Show this prompt if field blank, since his representatives should always see this question when they generate follow-up letters.

Since only 1 option is allowed to be checked, Alex [1] inputs "1" for both the minimum and maximum number of options that can be selected, and [2] leaves the delimiter field blank. He then [3] adds the two choices in as Options.

He now needs to provide his representatives with a list of basic and lead paint removal services to choose from. He only wants his representatives seeing basic removal options if they chose basic paint removal, and lead removal options if they chose lead paint removal.

He starts with the prompt for basic paint removal. He [1] chooses a Checkbox prompt, [2] names the merge field "BasicCharges," and [3] opts to have it appear on page 2, since it's a conditional prompt. In the Show this prompt if field, he [4] denotes that the Prompt should only appear if the representative chose "basic paint removal," using the syntax {{!removaloption}} == 'basic paint removal.'

He then adds the basic removal options. Alex [1] requires at least one option to be chosen, but accepts a maximum of three choices, since a few different service charges might apply for this option. He [2] doesn't specify a delimiter because he has edited the source of his Options so they appear as bullets. He then [3] adds the three basic paint removal service charges.

He repeats this process for the lead removal options and the other conditional prompts he requires. This is the gist of Runtime Prompt Trees: they can be as basic or complex as you want!

Adding The Prompt Merge Fields Into The Document

Once Alex finishes creating his Runtime Prompts, he needs to add his custom merge fields to the followup letter template. He begins by adding in the merge fields that will always appear in the document: the client's name, the date of the representative's return, and the paint removal type.


After this introduction, he wants certain sections of the document to conditionally appear/disappear based on responses to his Runtime Prompts, so he opts to use the Conditional Logic feature. He first inserts a conditional statement for basic paint removal. The portion outlined in green is what will appear in the document if "basic paint removal" is chosen by his representatives.

He uses a nested conditional statement for lead removal options, since one of the options (enclosure) has further options to choose from, and he only wants these further options shown if both "lead paint removal" is chosen and "enclosure" is picked as the type. The portions outlined in green are what will appear if "lead paint removal" is chosen by his representatives, and the portion outlined in orange is what will appear if "enclosure" is chosen as the removal type.

What The End User Sees

Now that Alex has added in all of his merge fields, let's see what his representatives will see each time they generate the follow-up letter. On the first page, they will simply be prompted to enter the date of their return and the type of paint removal that the client needs.

If they choose "basic paint removal," they will be prompted with the appropriate options.

Since there are no more options that go with basic paint removal, the representative can click Generate Doc to generate the follow-up letter with their choices incorporated.

Let's go back to before the document was generated. If Alex's representatives choose lead paint removal instead, they will be prompted with the lead options.

Finally, if they choose enclosure as the method of lead paint removal, they will be prompted with the further options that are available, on a separate page.

The final document will render only the lead paint removal sections.

That's it! We designed Runtime Prompts to be as simple as possible while providing enough flexibility so that you can integrate them with other features in order to achieve pretty much any result imaginable when form input is required prior to document generation. If you want to download and play around with a template already set up with Runtime Prompts, you can get this Boiler Inspection Follow-Up Letter from our Template Library. This is one of many examples of how we can use form data to build a living, breathing document.

Tags: , , ,

Was this helpful?