Introduction to Runtime Prompts

Ever wanted to have a user fill out a form before they generate a document? Maybe one that merges the user's answers into your template like any other merge field? Perhaps one that will even conditionally render sections of your document based on your user's inputs? Wouldn't it be great if something like that existed?

Well, great news: the Runtime Prompts feature does all of that! This feature will pause the document generation process and ask the user questions that you define, then merge their answers into your template and/or conditionally render certain sections of the document based on their answers before finishing the generation process.

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

This is 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. [1] Begin by selecting the type of prompt you would like your users to answer: Text, Date, or Checkbox. [2] Then, you can write the name of the merge field for that prompt. You can name the merge field anything you want. Once you've defined it, you can use it like any other merge field; just place it wherever you want the user's response to the prompt to appear. After that, [3] write the prompt itself. This is the question the user sees and responds to during the document generation process.

Now let's get into some of the optional fields.

You can optionally [4] choose to have different Prompts appear on up to 10 different pages, as well as [5] conditionally show certain prompts based on answers received for other prompts. We'll get into this later when we discuss Runtime Prompt Trees. Next, you can [6] specify a field in Salesforce that you want to be updated with the user's response to this prompt. For example, if you wanted to write this response back to an opportunity description, you would write Opportunity.description (note that {curly braces} are not used here).

You can also [7] specify if a Prompt is "Required" - this means that the user will not be allowed to generate the document unless they answer your Prompt. In addition, you can choose to prepopulate this prompt with the user's previous response - this means that if they chose "Option A" last time they generated the document, "Option A" will be set as the default answer the next time they generate it. You can also forgo making a field "Required" and [8] specify a "Default Value" as the "data" for your Prompt's merge field if the user doesn't answer that particular prompt. Or you can leave "Required" unchecked and "Default value" blank, allowing the user to leave that prompt blank.

The Three Types of Prompts

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

Text and Date Prompts

Text and Date Prompts are pretty simple. A Text Prompt just a simple free-form text field that the user can type whatever they want into. It looks like this at runtime:

Date Prompts provide a date picker that the user can enter a date into. It looks like this at runtime:

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

Checkbox Prompts

Checkbox Prompts are a bit more complex. When you select this type of Prompt, additional options will appear in the Runtime Prompts menu. Scroll down to take a look at them.

[1]You can provide several different pre-defined values for the user to select from; we refer to each of these values as an "Option." 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. For each Checkbox Prompt, you can define as many Options as you'd like; [2]add Options via the Add Another Option button found at the bottom of that Checkbox Prompt's list of Options.

Checkbox Prompts have a few different parameters compared to Text and Date Prompts. When the user checks off a few options, they are combined together and can be referenced by the single merge field you defined for the Checkbox Prompt. You can optionally [3]specify a delimiter, which is what separates each Option  if the user selects multiple options. For example, say you have Options "Okay," "Good," "Better," & "Best," your merge field is {{!MyCheckboxPrompt}}, and your delimiter is "AND:" if the user selects "Good," "Better," and "Best" at runtime, then {{!MyCheckboxPrompt}} will be replaced with "Okay AND Good AND Best" in the final document.

For a given Checkbox Prompt, you can also [4]specify the minimum and maximum number of Options that can be selected by the user. Note that these fields are required.

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."

At runtime, Checkbox Prompts look like this:

Runtime Prompt Decision Trees

Like we mentioned before, 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 creates a simple checkbox prompt. He names the merge field "removaloption," and chooses to have it appear on page 1 of the Prompts, since it is the first question that needs to be asked. He leaves the Show this prompt only if the following conditions are true field blank, since his representatives should always see this question when they generate follow-up letters.

Alex doesn't set a delimiter, since only one option is allowed to be checked. He then 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 chooses a Checkbox prompt, names the merge field "removalcharges," and opts to have it appear on page 2, since it's a conditional prompt. In the Show this prompt only if the following conditions are true field, he 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. He doesn't specify a delimiter because he has edited the source of his Options so they appear as bullets.

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 Render feature. He first inserts a render 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 Render 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 document will be generated once the representative clicks Next.

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.