Document Templates - Creating and Editing
Document templates allow users to generate documents that automatically insert information from a case — such as the client's name, legal problem code, primary advocate, and so on. Templates have criteria so that only templates relevant to a case are displayed by default; for example, matching the case's problem code and client's language.
Document templates are also available in the user module to insert information from the user record. This page focuses on templates on cases, but new style templates for the user module are created and mapped in the same way. A site must be using a dynamic user profile page that includes the Recommended Documents block to see any available templates.
Administrators create a template and upload it to LegalServer (or upload a fillable PDF), set display criteria, then map fields to markers within the template. Users see templates in the Recommended Documents list and Email Templates lists on a case. Document templates generate a document that pulls information from the case and inserts it in the appropriate places in the document, while email templates do the same for a case note that can be emailed.
Create a Template
Templates are RTF (Rich Text Format) files. New style templates also support fillable PDFs. Files saved as Word documents (.doc, .docx) will not work.
RTF files created in Microsoft Word generally work, but Word has a habit of inserting extraneous formatting characters in field markers. Our experience, and that of many site administrators, is that LibreOffice or another word processor avoids this issue.
Field markers in RTF templates are text between square brackets to indicate where information from a case will be inserted into the generated document.
The text between brackets must not contain spaces or special characters like a slash (/).
The marker text does not need to match field names in LegalServer, but it helps at the field mapping stage to be explicit — ClientFirstName or Client_First_Name instead of just "Name".
Here is a simple letter template:
Templates can contain images such as an organization's logo. However a common problem is large (in size, not necessarily dimensions) bitmap (BMP) images. It is not uncommon for a simple and small BMP image to actually be 10MB or more, and cause problems when attempting to upload as a template. We recommend changing BMP images to PNG or JPG format before putting them in a template.
When using Microsoft Word to create RTF templates, we recommend turning off smart quotes to avoid strangely formatted output in generated documents.
Links (like http://www.legalserver.org ) should be entered in plain text in templates to avoid formatting issues in generated documents.
Upload a Template and Set Display Criteria
Upload templates or fillable PDFs to LegalServer on the Documents page (Admin / Documents). Click the Create a New Document link in the Actions or Options menu tab to open the upload form.
Title is optional but should generally be filled in. The title text is displayed in the template lists.
Viewable Offline? is only relevant for documents that may be downloaded as part of an online intake. "Offline" refers to the person not being logged in to LegalServer. This field is editable only if your role has the related permission.
Type is optional.
Folder is required. If a site has more than a few templates, a Templates subfolder and subfolders under that folder may be helpful. Subfolders can be created on the main Admin / Documents page.
File Name is required. Use the "Browse" button to open a file dialog, then find and select the template on your computer.
Revision Date is optional.
Author is an optional text field. It defaults to the person uploading the template.
Template Type is optional, but must be set to one of the available types to create a template. The template type determines the manner of mapping fields and setting whether a process is associated with the template.
Old Style Document Template - provides a simple interface for mapping fields, but does not provide access to all fields on a case.
New Style Document Template - provides a more complex interface for mapping fields, but provides access to nearly all fields on a case. During initial upload, or editing a template, displays an additional "Download instead of Begin Process" prompt. This affects the user experience when using the template. At the default of "No", the user will be taken through a series of steps to produce a document based on the template. If set to "Yes", a document will be immediately generated with certain default values.
Email Template - provides an additional "Data Source" prompt. Select "Client" (the other options do not apply to templates in the context of cases).
XSLT Template - this is an advanced format that is beyond the scope of this topic. XSL stands for EXtensible Stylesheet Language, and is a style sheet language for XML documents. XSLT stands for XSL Transformations.
Old Style versus New Style Templates
Old Style templates support certain features that new style templates do not: mapping list views, the contents of certain notes, and answers to case questions. However, these features are no longer being actively developed and may be removed in the future.
Documents intended to be used as templates with the Publications and Document Selection blocks are always new style templates.
The upload page contains several multi-select lists that are used to determine if a template should appear in lists on a case. The Recommended Documents and Email Templates lists on cases have default filters, so that they only display relevant templates. The criteria fields are legal problem code, special legal problem code, county, language, program, and office.
You must select at least one legal problem code and one county for a document template to appear in the lists.
For a template that should appear on all cases (for example a Retainer Agreement), select all legal problem codes, all counties, and all programs.
Map Template Markers
The method for mapping template markers to fields and optionally setting a process for a template depends on the type of template.
Map Old Style Document Templates
Click the Edit Fields link on the Actions or Options menu of the document profile page to open the edit fields page. On the left side of the page are all the field markers LegalServer recognized in your template. On the right are dropdown options that map a marker to a field or other data.
For each marker on the left, decide if it will be mapped to a field, a list, notes, or an answer to a case question.
Field - maps to a field, for example, client's full name or legal problem code. The second dropdown is a search and select list of available fields.
List - maps to a list of information, for example, the Timeslip Log. The second dropdown displays the available lists.
Notes - maps to available note types, for example, Case Close Notes. The second dropdown displays the available note types.
Answer to a Case Question - the Case Specific Questions feature this option is related to has been deprecated. This option should not be used.
Map Email Templates
The mapping interface for email templates is similar to Old Style templates, except that you can only map fields. There is no option to select a list, note, or answer to question.
Map New Style Document Templates
The mapping process for new style templates is more complex than old style templates, but provides access to a greater range of fields. Click the Edit Fields link on the Actions or Options menu of the document profile page to start the mapping process.
The process has 4 steps: Fields, Actors, Map, and Summary. Links to each step appear in the sidebar, and can be used to return to a different step once it has been completed.
The first step of the mapping process displays a list of markers recognized in the document. Select the markers to be mapped to fields on the left and move them to the right.
The second step of the mapping process is to add Actors, and optionally Sub Actors.
If this is brand new template, you first need to select if the template will be used in the "matter" module (for cases) or the "user" module (for user profiles). The rest of this section focuses on "matter" templates.
The available actors are controlled by the Actors lookup list (Admin, Lookups, Actors). Common actors are "Case Information", "Client", "Primary Advocate", "Pro Bono Assignment", and so on. Most templates will use at least a "Case Information" actor.
Each actor has an Actor Type, which determines the fields available for that actor when mapping markers to LegalServer fields. Actor types are 'system' lookup values, and may vary depending on the features a site has enabled. Check Admin > Lookups > Actor Types to see what is available on your site. Site administrators can add as many actors as desired to a site's Actors lookup list, but the actor types available are set by the system. The four most commonly used types in templates are:
Case Data - Contains multiple table links. In addition to basic fields like case ID number, date opened, and legal problem code, it also includes special fields such as "Today's Date" and "Today's Date (Formal)". Most templates will need an actor of this type, and often only need a single actor based on this type.
Person - Contains multiple table links for a person associated with a case; contact information, name variants, demographics, immigration information, etc. Much of the information about the client can be obtained from a Case Data actor without needing to add a "Client" actor. For example, the client's full name is available via Case Data, but some special fields like "All Aliases" are only available from Person.
Assignment - Information about an assignment such as Assignment Type, Caseworker, Start Date, etc. Some commonly used assignment fields, like Primary Advocate, are available from a Case Data actor, so an Assignment actor may not be needed for a template.
Organization - Information about an organization linked to a case, for example a court. Most of the fields available on an organization profile are available for an actor of this type.
To add an actor to the template, pick it from the list and click Add. This is an example of a Case Information actor (based on the Case Data actor type) with the sub actor drop down displayed:
List Order, Header, and Instruction, if used, are displayed during the document generation process, if a process is enabled.
This is an example of a Client actor (based on the Person actor type). Actors based on Person, Assignment, and Organization have additional options for Default Type and Default Index. The sub actor dropdown is also displayed:
The Default Type dropdown lists the types of people associated with a case. In addition to Client, as shown above, additional types are family, adverse party, litigation contacts, etc. There is also a special type, Currently Logged In User, which is useful to fill in the name and other information about the user generating a document.
Default Type is particularly important when no process is used, meaning the user will not have the opportunity to pick the person on a case to associate with an actor when the document is generated.
Default Index, along with the Default Type, tells the system which number to pick if there is more than one type of actor. For example, entering a "1" in relation to a family child actor would pick the first child on the case. Default Index is particularly important if the template will be directly downloaded instead of using a process. For 'unique' actors like Client (only one per case), the template knows which person to pull information from. However, for an actor like adverse party, you need a "1" for Default Index to pull the first, or only, adverse party; leaving Default Index blank will result in no information being merged for an adverse party actor.
Actors based on Case Data or Person can have sub actors; information that is associated with that actor. For actors based on Case Data, the types are Case Note, Litigation, and Unit of Service. For actors based on Person, the types are Address, Employment, Marital Status, and Organization Affiliation.
Sub Actors may not be needed for common templates. For example, the client's address fields are available via a Case Information actor, along with special fields like Full Address and Full Mailing Address (but see below to get the client's address in "block format" (on multiple lines)).
The Actors page has a Deactivate button for each actor to remove unneeded actors. Removing an unused actor is not required, but eliminates unnecessary clutter when a user is completing a document generation process.
Multiple Actors - Each actor can only be added to a template once. If a template needs, for example, multiple family members, then multiple actors must be added to the lookup, such as Family Member 1, Family Member 2, and so on.
Each actor can have as many sub actors as needed. For example, if a template needs a client's current job and previous 4 jobs, then 5 employment sub actors can be added to the single Client actor.
After adding the actors needed, click Continue to move to the Map step.
The third step of the process involves linking template markers to LegalServer fields. Fields on the right are dragged and dropped onto markers on the left.
This is partial screenshot of a Map page showing markers on the left and the LegalServer fields available for the Case Information actor added earlier:
In the example, "program" has been entered in the search box below the Case Information actor. This expands the tables that have a field name containing "program". The "Assigned Program" field has already been dragged and dropped onto the "assigned_program" marker on the left, as indicated by the full chain link icon (compare the half link icon in the 3 program fields above it on the right). On the left, the linked actor and field name are displayed; in this example, "Case Information: Assigned Program".
The third marker on the left illustrates how the actor dropdown on the right was changed to Client to link the special "All Aliases" field that is not available under the Case Information actor.
A LegalServer field can be mapped to multiple markers to repeat information in different parts of a document.
To unmap a field, place your mouse cursor over the marker on the left side, then click the red X that appears.
Clicking the + sign next to a marker on the left will display the Transform dropdown list. A transform modifies the associated data as it inserts it into the generated document. It does not modify the underlying data in the database. The transforms currently available are "UPPERCASE", "Remove 'Group:'" (used to remove the literal text "Group:" that is prepended to organization client names), and "QR Code" (used in generating bar code cover sheets).
The final step of the mapping process displays a summary of all of the mapped markers, their types, and the actors and sub-actors they have been mapped to.
As noted above, the process steps appear in the sidebar, so you can return to any step of the process via those links without needing to continue on the summary page and clicking Edit Fields again on the template.
To edit an existing template, use the Actions or Options menu links on the document's profile page.
Use the Edit this document link to change the problem codes, counties, and other criteria used to determine if the template will appear as a Recommended Document on cases.
Use the Edit fields link to change any of the mappings from template markers to LegalServer fields.
Use the Download this document link to download the template to your computer to make changes to the template. Upload the revised file to the same document profile (replacing the existing file), to preserve field marker mappings — except those that have been edited or added.
Use the Download document and mapped fields link (new style templates only) if you want to transfer a template from one site to another; for example from a demo site to a live site. Downloads an XML file which must be imported to the other site. Attempts to preserve as many field mappings as possible.
Use the Delete this document link to delete the template.
Enabling a Document Completion Process
For Old and New Style templates, the template creator determines if the user immediately generates a document by clicking a "Download" link, or starts a process by clicking a "Begin Process" or "Start Process" link.
Email Templates do not have an option to download or start a process. The "Download" link displays a page where the subject, body, and date posted (for the case note that is created) can be changed.
Old Style Templates
By default, Old Style Templates display a "Download" link that immediately generates a document. Alternatively, the template can display a "Begin Process" link that displays a form. The form allows a user to see and change information on the case before generating the document.
Template writers enable a process by clicking the "Create Process" link in the Actions or Options menu on the document profile page, then the "Enable Process" link. The "Edit Process" and "Edit Dynamic Form" links then allow controlling the process and changing the form. If a process is enabled, use the "Disable Process" link to change the link users see back to "Download".
New Style Templates
By default, New Style Templates display a "Start Process" link and take users through a multi-step process to review and optionally select and add information that will be inserted into the template. To immediately generate a document from a new style template, change the "Download instead of Begin Process" field on the template to "Yes".
Mapping problems can cause "exception errors", which usually result in a mostly empty white page that displays something like "A NNIException error occurred while downloading this document. Please file a support request." when you try to generate a document from a template.
If you get such a page, copy the URL in the address bar to your clipboard, then click your browser's back button, and file a ticket from that page (Help menu > Support Request). Paste the URL into the ticket description box, and add the name of the template.
If you need LegalServer support to look at a template, let us know in the ticket a case it is okay for us to use to generate a document from a template; a case that will demonstrate the issue.
Client: The client's address is available via a Case Information actor. You don't need to add an Address subactor. Also see "Client's Full Address in Block Format" below.
Primary Advocate: See the "Primary Advocate's Work Address" and "Primary Office Information" sections below.
Other actors: For other actors, add an Address subactor, then map fields from the Address Elements section. The Computed section has some combinations of address fields that may be useful.
A Case Information actor has Adverse Parties and Adverse Party Summary fields.
Alternatively, you can add multiple Actors, such as Adverse Party 1, Adverse Party 2, etc. If you use the "Full Name" field for an adverse party actor, the "Remove Group:" transform is useful if cases can have organization/business APs. Otherwise the name inserted would look like "Group: Bob's Bargain Barn".
For a case: Case Information > Primary Assignment Office > Primary Assignment Office Name.
For a case: Case Information> Client > Assigned Program.
Case Information > All Assignment Names returns the names of all users ever assigned to a case.
For more detailed information add one or more Assignment actors.
People added as case contacts are available as "litigation contacts". Add a person actor defaulted to one of the litigation contact options. As with family members, you'll need multiple actors if you need to map to multiple case contacts.
Several fields in a Case information actor allow reporting on the notes that can be added to matters. The "general" versions are:
Case Information > Case > Case Notes. A list of case notes in reverse chronological order. Includes case notes created from timeslips.
Case Information > Case > Case Notes Summary. A list of case notes in chronological order. Does not include case notes from timeslips.
The other two fields, "Case Information > Case > Notes" and "Case Information > Ungrouped > Notes", both produce a list of case notes, including case notes from timeslips. Both include posted on and posted by information. Not currently suitable without manual formatting after a document is generated because there are no hard returns after one note and the start of the next note.
Client's Full Name
instead of the individual fields, use the "Name" field in both old and new style templates. In new style templates this field is available on the Case Information actor if the template doesn't otherwise need a separate Client actor.
Client's Email Address
Use the Case Information > Client > Email Address field.
Client's Full Address in Block Format
In new style templates, add a Client actor (any Person type actor with the Default Type set to Client), and an Address subactor. Default the address subactor to Home, Mailing, etc. as needed, and set the Default Index to "1". On the mapping step, use "Full Address" in the "computed" category for that subactor. The "Full Address" field in old style templates is always in block format.
Docket Number and Other Litigation Information
The Docket Number field that can be collected on litigation records (and via the Court Case/Docket Number block) is available from a Litigation subactor. Add the subactor under the Case Information actor.
Domestic Violence Fields
These fields usually aren't found by the search box. Case Information > Ungrouped > Is the caller a victim of domestic violence. On a person actor like the client, Client > Misc > Victim of Domestic Violence.
You need an Actor for each family member, like Family Member 1, Family Member 2, etc., in Admin > Lookups > Actor.
How Did Applicant Hear About Us
Also labeled How Referred and other variants, is under Case Information > Client. You currently need to find it manually; it does not come up in a search for 'how did' or 'how ref', etc.
Medical Record Request Information
Information entered via the Medical Record Request block is available via a Unit of Service subactor of Case Information.
Number of People 18 and Over and Number of People under 18
Are both in the Client section of the Case Information actor. They do not show up using the search box. Leave it blank and manually click on the Client section to see them.
Are not available to map. There are 3 fields in the Ungrouped section of a Case actor, but each will cause an error.
Outcome V2 information
Can be mapped in new style document templates. Add one or more Matter Outcome V2 subactors to a Case Information actor on your template. NB: Your template will need to have "Download instead of Begin Process" set to No so users can pick the outcome(s) they want to pull in.
On a case: Case Information > Case > Primary Advocate.
Primary Advocate's Work Address (or Any User)
Add a Person actor with the Default Type set to "Assignment Primary", then an Address subactor with the Default Type set to "Work" and Index to "1". The "computed" section of that table contains "Full Address" and "Full Address (inline)". "Full Address" is block style.
The Address Elements section of a user's work address contains the individual Street, City, State, etc. fields.
Primary Office Information
A Case Information actor contains a "Primary Assignment Office" section. That section has the office name, phone, fax, and address fields.
Useful if you need the assigned office information on a case, even if the primary advocate's office is not the same as the assigned office.
For her - his, she - he, is enabled on the Admin > Lookups > Genders lookup list for each gender. The person being used in a template must have a gender stored for this to work.
Today's Date Spelled Out
Displayed as April 1, 2000 instead of 4/1/2000. Case Information > Today's Date (Formal).
* You can't delete an old style template after enabling a process on it. Trying to delete it will result in an error page. The current workaround is to deselect all problem codes, etc. on the template so that it doesn't show up on any cases. (Ref: 60889).
* The Case Information > Date Proceeding Initiated field causes an error when generating a document. (Ref: 72204)
* You can't delete an Email Template that has been used in the communication manager. (Ref: 76920)
* Case Note subactors cause an error when generating a document from a template. (Ref: 78625)
* Special Legal Problem Code cannot be mapped. (Ref: LS-42997)