Software: hotdocs

The ERASE instruction is one of the handier instructions in HotDocs if you are populating data dynamically more than once, or are using ‘temporary dialogs’ during your interviews.  Use of this instruction will completely erase the contents of a variable or dialog, but be warned: it will erase all iterations of that variable or dialog!

Let’s say we’re doing an Estate Planning matter – you have the client, their spouse, a list of children, trustees, executors and some random beneficiaries.  There’s a lot of entities in there.  If you’re working with a system by Basha Systems, there would likely be a central party list that functions as a contact database.  If you’re not, you have several repeats containing contact information.  Either way, the approach is the same.  The example I will use is a generic letter.  You want to program a generic free-style letter that can be sent to any entity on the matter.  But because you quite often wish to send letters to the same party consecutively (a few days apart), you want the generic letter dialog to retain the information of who a letter was last sent to.  Here’s how you do it.

Create your dialog as you ordinarily would – name, address, salutation etc – lets call our dialog Generic Letter DLG.  I won’t get into the import mechanics – all we’re showing here is the ability to clear an entire dialog easily.  On that dialog, we’ll create a button that points to the computation Generic Letter Clear CO.  The script of that is:

ERASE Generic Letter DLG

That’s it.  If the variables on the dialog are saved in the answer file, then the next time you hit that dialog, the details of your last generic letter appear.  If the user wants to use those details – great!  If they don’t, they simply click the button and everything on that dialog is erased and the user can pick a new entity to direct a letter to.  Be warned that you don’t use this on repeating dialogs, as it will erase the entire dialog and all of its iterations/repetitions.

Today’s tip is about the DEFAULT and SET instruction models.  Both of these models will allow you to specify that a variable has a certain value, but in different circumstances and with different results.  This article provides the basics on when and how.

To quote the HotDocs help file, “This instruction (DEFAULT) suggests a value for a variable if the variable is unanswered”.  Unsurprisingly, the instruction is exactly what it appears to be – a DEFAULT value.  It will not, in any circumstance, overwrite any existing variable value, even if that variable value is a single space character, or 0 in a number variable.

Personally, I find DEFAULT useful for exactly that – providing default or “starting” answers to variables that may be overlooked by users.  Typically, its something I use with “fresh” answer sets, at the start of a matter.  The simple rule is to generally not bother with DEFAULT, unless you’re using it in a scenario where the dialog isn’t (or shouldn’t) have (m)any values in it.

SET however, is a completely different kettle of fish.  I use SET wherever I can.  The way SET works is very simple – ask no questions, take no prisoners and absolutely give this variable the supplied value.  It will override anything that previously existed in that variable.  There is one major drawback to SET – if you use it in a dialog script, it will prohibit the user from changing the SET variable.  Even if you wrap it in a conditional statement, there is no guarantee that HotDocs will re-process the condition properly and allow you to edit the variable. A minor bugbear.  The workaround (if absolutely necessary) is to use SET instructions in a button (dialog element, script link) on your dialog.  Because the SET instruction is not run by the script dynamically, but rather, is being run ONCE only on user click, HotDocs will not gray out the variable and prohibit changes. For the price of one click, you can set/clear/change/populate and manipulate your data as much as you want, without worrying about grayed out variables, or processing times (heavy script leads to slow response times.  heavy script on buttons only results in a one-off hit when a user actually clicks the button.  Its far more elegant).

And yes, I ignore all the HotDocs “errors” that tell me I am asking a variable in an interview and SETting it to have a value.  Why do I do this? Because I presume that good code gets you a correct answer, but relying on a user to get it right can get you inconsistent answers.  Lets say that everytime you specify you’re wearing a red shirt/blouse, you want black pants.  If you’re male, you also want a red and white tie.  If you’re female, you want ruby earings.  Without SET, you are relying on a user to know the ensemble and, just as importantly, to key it in correctly, every time.  Mistakes happen. Interruptions occur. And sometimes, people just plain get it wrong; its a part of the human condition.

I rely on human correctness (or, more accurately, avoid human error) as often as possible.  So lets show how SET can be used to automatically calculate answers based upon user data entry.  Here’s what my dialog script may look like:

//hide what we're going to force anyway.
HIDE Pants MC
HIDE Tie MC
HIDE Earings MC

//force the user to answer enough questions to calculate the answers
REQUIRE Gender MC
REQUIRE Blouse MC

IF Blouse MC = "Red"
SET Pants MC TO "Black"
IF Gender MC = "Male"
SET Tie MC TO "Black and White"
ELSE IF Gender MC = "Female"
SET Earings MC TO "Ruby"
END IF
ELSE IF Blouse MC = "Black"
SET Pants MC TO "Black"
IF Gender MC = "Male"
SET Tie MC TO "White"
ELSE IF Gender MC = "Female"
SET Earings MC TO "Diamond"
END IF
ELSE
//its not a red shirt/blouse and its not black either, let the user pick these ones....
//of course, you could specify as many ensembles as you wished.
SHOW Pants MC
IF Gender MC = "Male"
SHOW Tie MC
ELSE IF Gender MC = "Female"
SHOW Earings MC
END IF
END IF

In the above instance, you may be a little colour challenged, so you’d add this at the top of your code:

DEFAULT Blouse MC TO "Black"

This would thereby ensure that the first time you were presented with the dialog (for each different answer file), you could have your black ensemble, without touching a thing – just let the answers ride.  At the point you specified anything in the Blouse MC variable, the DEFAULT instruction would be ignored forever more.  But the first time round – it would do the job.

Looking at this, its a lot of code to avoid having the user answer a few extra questions.  However, lets put this in perspective – let’s say this WAS a program to get dressed in the morning, and it would get you ready for work in half the time you currently spend.  But a wrong answer would mean that you would have to go back to the start, re-specify your answers and let the program do its thing again. Suddenly, this isn’t “too much code”, but rather “time saving code”, because it calculates 2 answers based upon the answer to the first one.

The real benefit to such an approach (where possible) is that suddenly, your proof reading times are reduced.  Sure, saving your support staff time (and improving data integrity) is great. But saving an attorney an extra few minutes on proof reading (because the attorney only has to check one answer, not three…), now that’s profitable.

Calculate data from existing answers where you can. The LESS questions you ask, the better; so long as your answers allow you to calculate everything you need to know.  It is not uncommon for me to ask 10 questions and produce 13 answers.  SET and DEFAULT will allow you to do this.  DEFAULT will set up your most common answer set, so they don’t have to worry about doing anything at least SOME of the time.  SET will allow you to implement “sets” of instructions, so that one answer produces multiple correct answers.  That saves everyone time.

The DECREMENT and INCREMENT instructions are relatively new to HotDocs and they serve identical, but reversed purposes.  DECREMENT will reduce a given number variable by one, whereas INCREMENT will increase by one.

These two instructions are most useful in conjunction with WHILE and REPEAT instructions.  Lets say we are doing some real estate templates and one of the templates is ONLY required where there are one or more corporate borrowers. To do this, we could just use a TF variable that is set to TRUE if there is at least one corporate borrower, but that isn’t as useful as knowing exactly how many corporate borrowers we have.  Making MORE specific information available to your system is nearly always better than “the shortest approach”.

SET BORR Corporate CNT TO 0 //our var to store how many corporate borrowers
REPEAT BORROWERS RPT
IF BORRS Corporate TF = TRUE //a checkbox on the dialog if the borrower is a company
INCREMENT BORR Corporate CNT
END IF
END REPEAT

And that’s it.  At the end of this, BORR Corporate CNT will contain the number of corporate borrowers we have.  The same usage would apply in a WHILE statement, except that in a WHILE loop, it is nearly always imperative that you have an INCREMENT (or DECREMENT) statement.  The reason for this is that REPEAT will auto terminate when you have finished the repeated answers whereas WHILE does not – YOU must manually code that ‘cut out’.  And that’s where INCREMENT comes in.

At the end of the day, INCREMENT and DECREMENT could already be achieved in HotDocs scripting as follows:

INCREMENT: SET Variable NU TO Variable NU + 1
DECREMENT: SET Variable NU TO Variable NU - 1

Both of these would work. But these two new instructions are cleaner and easier to type.  And lets face it – convenience and clean code are pretty cool things to have.

The HotDocs DEBUG instruction model is very simple, very powerful and very clear about its use.  DEBUG is used to…well, debug!  If you have templates or computations that are producing unexpected or incorrect output, using the DEBUG instruction may get you back on track just a little quicker.

There are two uses of DEBUG – in templates and in scripts (both Dialog scripts and computations).  Both uses have a very similar effect.

By placing a DEBUG instruction in your template or script, you tell HotDocs to display the Debugger screen.  With the debugger, you can manually step through a script or template while viewing extremely detailed information regarding each variable’s value.  You can add variables to watch lists, “step” the script (ie: manually tell HotDocs to progress the script line by line) and watch the variable values change with each step.  Using DEBUG, you can quickly identify what data is coming in/going out and what data is changing.  This will allow you to track down any errors quickly, as you can not only assess each computation or variable, but also the variable values that went into creating the problematic data.

Additionally, the Debugger contains a processing stack tab.  This is a sequential list of templates and components to be processed, in order.  It will also give you the reason as to WHY HotDocs has a particular item in the queue.

In the most general sense, the Debugger gives you a real look under the hood as to exacty how HotDocs is handling/treating your code.  This is invaluable if you simply cannot make your code produce the correct content.

A very brief HotDocs tip today – the CONCEAL and OMIT instruction models.  These two commands make working with HotDocs dialogs as answer sources a little cleaner and easier for users to work with.

In short, CONCEAL keeps a variable from showing in the “Select from Answer Source” dialog – it is simply hidden from the user, allowing for the more meaningful fields to be shown only.  OMIT does a similar thing, but hides a variable from the user in the “Edit Answer Source” dialog box – again, allowing only the meaningful fields to show to the user.

These two commands go hand in hand to pare down information that displays in dialog answer source manipulation.  Rather than trying to show an example, these two commands are best “tinkered” with on a case by case basis.  If you want to try something cool, try using dialog answer sources in a scenario where only ONE variable is not CONCEALed.  The variable still showing should be an identifier, such as a name or similar.  That way, a user will simply see a nice drop down to pick from and all the other data will ‘appear out of nowhere’ – just like magic!

This stuff is super simple and takes about 10 minutes to master.  Play around with dialog answer sources, CONCEAL and OMIT – it may actually be FUN.

Unfortunately, the CLEAR instruction model doesn’t really have any use on its own.  Its job is simple: to remove all the options and option prompts from the specified multiple choice (“MC”) variable.  That’s it.  When used in conjunction with the ADD instruction (which adds options & option prompts to a specified MC variable), you end up with a pair of commands that can dynamically build MC variables on the fly, based on whatever data you desire.

For the sake of this example, lets say we are drafting real estate documents.  We have BORROWERS RPT, which collects information on…well, borrowers!  We have BORRS Full Name CO which constructs the full name of each individual borrower (ie: can only be used inside the repeat).  Lastly, we have BORRS Guaranteed MS, which is a multi select MC variable which asks which borrowers have guarantors.  Here’s how we’d build our BORRS Guaranteed MS variable:

CLEAR BORRS Guaranteed MS
ASK NONE
REPEAT BORROWERS RPT
ADD "«BORRS Name Full CO»" TO BORRS Guaranteed MS
END REPEAT
ASK DEFAULT

That’s it.  We firstly clear the MC variable, then inside an ASK NONE/ASK DEFAULT pair, we add the full name of each borrower to the MC variable.  The user may now select borrower names from the MC variable for insertion into the template.  In conjunction with the list format applied to the variable, you can quickly and easily generate user-specified lists of any data from any repeat you have in your system.

There are far more uses for CLEAR/ADD, but this covers what we consider to be the most useful one.

One of the cooler instructions is the ASSEMBLE command, which allows you to queue up a template for assembly in HotDocs.  When it comes to assembling individual documents in packages/batches (as opposed to a template package in a single document output), assemble is the only way to fly.

The syntax is easy enough:

ASSEMBLE "FileName.ext"

The true power comes from being able to conditionalize the ASSEMBLY command, as well as apply command switches to the ASSEMBLE command.  Imagine that you are drafting a Will or similar document for a client.  You could have a multi-select multiple choice variable (WILL Docs Additional MS) that asks what additional documents you wish to draft after the will.  You could then have something like:

IF WILL Docs Additional MS = "Cover Letter"
ASSEMBLE "WillCoverLetter.rtf"
END IF

IF WILL Docs Additional MS = “Trust Deed”

IF ANSWERED ( WILL DEED Exec to Trustee TF ) AND WILL DEED Exec to Trustee TF

WILL POA Exec to Trustee Duplicator CO //duplicates data from executors in will to deed trustees – run before assembling
ASSEMBLE “POA.rtf /ni” //no interview – Trustees uses same Will executors!

ELSE

ASSEMBLE “DeedOfTrust.rtf” //use interview as the trustees are different

END IF
END IF

Between optional use of command line switches, and optional additions of templates to be assembled, the ASSEMBLE command offers a very flexible way to build packages of documents on the fly, based on interview choices.  Many times, this is far more flexible and easier to build than master templates that actually contains 10 or so templates inside it.  Certainly, where a firm wishes to individually profile each document in their DMS, ASSEMBLE is nearly always the right answer.

Final note: you can use the ASSEMBLE instruction directly in templates, inside or outside IF statements – it works the same way you would use INSERT, but with the difference of assembling a separate document, not an ‘in-line’ document.  For basic ASSEMBLE usage, this is fine.  But if you’re writing conditions around them, it is nearly always more elegant and easier to work with in a computation (and quicker for HotDocs to process!).

The ASK instruction does exactly what it appears it will do – forces HotDocs to ASK (present to user) a specific variable or dialog.  ASK is quite often under utilized, as many developers permit HotDocs to generate a template interview.  For those developers in the know, there is a lot more functionality, flexibility and control possible when you write your own interview.  For those developers who design their own interviews, use of the ASK statement is absolutely critical.

In its simplest form, you simply ASK a variable or dialog.  Lets say we are designing a conveyancing/real estate master interview.  We have borrowers, lenders, their counsel and perhaps a guarantor or two.  The borrowers may not necessarily always have representation, nor will the borrowers always have a guarantor.  So here’s how our interview might look:
In its simplest form, you simply ASK a variable or dialog.  Lets say we are designing a conveyancing/real estate master interview.  We have borrowers, lenders, their counsel and perhaps a guarantor or two.  The borrowers may not necessarily always have representation, nor will the borrowers always have a guarantor.  So here’s how our interview might look:

ASK INTRO DLG //ask whatever intro/matter information we need
ASK PROPERTY DLG //get property information
ASK LOAN DLG //get loan related information

ASK BORROWER DLG //basic information - how many borrowers, any shared address for service - details common to all borrowers

IF ANSWERED ( BORR Num LMT ) //force user to specify how many borrowers there are going to be
ASK BORROWERS RPT //info for each borrower
END IF
IF BORR Counsel TF //did the user specify that the borrowers had counsel?
ASK BORROWER COUNSEL DLG
END IF
IF LOAN Guaranteed TF //did the user specify that the loan was guaranteed?
ASK GUARANTOR DLG //if so, grab guarantor details as well
END IF

With developer designed interviews and the ASK instruction used in conjunction with IF statements, we can minutely control the interview and user experience.  ONLY those dialogs necessary are presented to the user, which reduces the chance of erroneous data entry, while forcing the user to be presented with the dialogs and questions that are necessary to complete the specifics of each transaction.  Dynamically. Efficiently. Correctly.

The ascend instruction is used with the REPEAT instruction to sort the resulting output.  Here’s what the official HotDocs help file states:

The ASCEND instruction sorts lists of answers (gathered using a REPEAT instruction) in alphanumeric order, from 1 to 9, and from A to Z. The DESCEND instruction sorts lists of answers from 9 to 1, and from Z to A.

There are two major uses for the ASCEND instruction: in a computation and in a template.

Consider a lease where you may wish to generate a list of lessors, sorted ASCENDING by last name, then first name (say, a husband and wife on the lease – the last name isn’t quite enough).  Your template may look like this:

«REPEAT LESSORS RPT::>LESSORS Name Last TE:>LESSORS Name First TE»
– «LESSORS Name Full CO»
«END REPEAT»

The above template code is generated for you by HotDocs’ REPEAT builder, using the advanced options (1 or 2 level sorts, filters and list format example.

Alternatively, you may wish to create a list of all Plaintiffs in a single variable.  This is a very handy and common use in litigation type systems – you use computations to generate a list of parties in the matter in different formats, and output the result to a text variable.  Thereafter, you dont have to REPEAT every time you want a pre-set & formatted list of parties – you simply use the text variable you SET..  Your computation to output a list of all Plaintiffs may look something like this:

SET PLF Names All TE TO “” // clear our variable where the result will land
“” //start off the computation with an empty (but necessary) result
REPEAT PLAINTIFFS RPT
FORMAT (“a, b and c”)
ASCEND PLFS Name Last TE
RESULT + PLFS Name Full CO
END REPEAT

SET PLF Names All TE TO RESULT

After this computation is run via your interview process, PLF Names All TE will now hold the value of all plaintiff full names in the matter, sorted alpha by last name, and may appear something like this:

Billy Blogs, John Doe and Marcus Fitzgerald