Welcome to the 4th stop on the Contract Management learning line. At this skill station, we will learn how to create a document that can be used as template to generate a printable version of the contract.
Learning Concepts at this Station:
Print templates and template variables
Generating a print template
Testing the template
Re-testing with a modified template
About documents
About template variables
Adding template variables to an existing document
Adding repeating rows
Viewing template variable tags in your browser
Adding conditional tags
Adding record meta data tags
Adding the total value tag
Uploading the document template
A print template is a Word document hat has been populated with template variables and uploaded to a stream.
Template variables, in turn, are stand-ins for data stored in the stream's data components. (You have seen template variables when creating email templates -- the format of the variables is different for a print template, but the concept is the same.)
When a document is generated from the template, stream data replaces the variables, producing a customized document.
It is also possible for a stream record to reference a Smart Object -- a reference table in a database that, like a stream, has additional capabilities. (It is the addition of those capabilities that elevates an otherwise-normal database table to the status of an object.)
When a Smart Object is referenced in that manner, and field in the object can be referenced. And since smart objects can reference other smart objects, any data that a print document needs can eventually be accessed, once the required references are in place.
Note:
Any kind of document can be uploaded and referenced in a stream, but Word documents are processed as templates. So, when template variables are included in a Word document, those variables are replaced by stream data whenever the document is accessed.
Most organizations have an existing document they want to use. If you have one, the question is where to find the variables you need to add to the document to make it a template.
One easy way to find out the names of those variables is to generate a print template from a form defined in the stream. That's also the place to start when you don't already have a document in mind, because a document is created for you that contains all of the relevant variables.
Later on, we'll see how to view all possible variables in your browser, but for now generating a template from a form is the way to go.
To generate a print template:
Now that we have at least a basic template to use, we can test it right away:
As with the template, the document we generated was a "bare bones" version. There was no formatting and none of the boilerplate text the lawyers want to see in the contract. But all of the fields are there, so now we have a place to start!
So at this point, we could either edit the generated document directly, or (more typically) copy the template variables to a pre-formatted document of your own. We will copy those variables in a few moments, in fact. But first, let's see how to re-test after we make modifications to the template.
After you saved the PDF, you are still at the Test Template dialog. That makes it easy to select another record and see how the template works in that case.
You can also modify the template, re-load it, and re-test. The trick is to remove the existing test-template first. To do that:
For Extra Credit...
In the generated document, you see the same narrow columns that were in the template we generated -- because, unlike an HTML page, table columns don't automatically resize themselves in a Word document. (A lot of the time, that's a good thing.) As a useful exercise in re-testing with a modified template, edit it to resize those columns, then re-select it and generate a new test document.
When you're done:
When we were testing our document template, it was uploaded only temporarily. But to make use of in the stream, we will first need to upload it as a component.
In the stream components list, you see a heading for Documents. Just below that, there is a heading for Email Templates. But where is the heading for document templates?
It turns out that any Word document that is uploaded to the stream is treated as a template, as long as it contains the appropriate variables (also called tags).
Most any kind of document can be uploaded to a stream, actually, but Word documents are treated as templates. (The only difference between a Word document that is a template and one that isn't is the presence of one or more template variables.)
Once uploaded to a stream then, any Word document that contains template variables is automatically treated as a print template whenever it is referenced.
Documents can be added to an email as an attachment, attached to a File field in the stream record, or sent for an electronic signature. When viewing a record, they can be used for printing. In any of those cases, an uploaded Word document is a template.
If you open the generated template file, you can observe the following:
For the remaining tags look like this:
Now we'll practice putting template variables into an existing document.
Now we can add the line item tags. Unlike the main section tags, these tags must be in table, or grid. Remember: Any formatting you specify in the template is preserved in the generated document. So make sure tag paragraphs are left-aligned, center-aligned, and right-aligned, as appropriate.
Here is the pattern to follow:
As long as there are no syntax errors, the generated document now shows the data for each of the line items.
Tip:
If you're not getting the results you expect, try comparing your document to this sample template: Contract Template.
So far, we have been copying template-variable tags from a generated printed template. But it is also possible to see a complete collection of tags for any record in the system, along with the data they contain.
Note:
In addition to the tags, you also the record data -- which can be invaluable for testing.
And, as you'll see in a moment, the available tags can depend on the data in the record. That's why you get the tags from a record, than from the definition of a data component.
The tags are displayed using JSON ("JavaScript Object Notation", should you happen to care). That's a very compact notation, so your browser needs to be able to format the data, to make easier to read.
Start by obtaining the record ID for the test record:
Then use the record ID to see the list of tags:
Scroll down 60 lines or so to get past the record meta data, and you come to a collection of tags you recognize:
"Contract": {
"Contact_Email": "nobody@nowhere.com",
"Customer_Continent_label": "North America",
"Contract_Number": "0001",
"Customer_Continent_value": ",North America",
"Total_Value": "$3,760.00",
"Customer_Continent": "North America",
"Contact_Name": "No one",
"Customer_Continent_North_America": 1,
...
},
There are fields like "Contact_Email" that you recognize right away. But when you examine the data structure, you'll see that the enumeration choice is coded several different ways. Here is the list for the test record, with everything pertinent collected together:
"Customer_Continent_label": "North America",
"Customer_Continent": "North America",
"Customer_Continent_value": ",North America",
"Customer_Continent_North_America": 1,
"Customer_Continent_Europe": 0
"Customer_Continent_Other": 0,
Notes:
Sometimes, there are things that need to be in contract in some cases, but not others. In this section, we'll explore ways to add conditional tags that create a customized version of the printed document, depending on the contract data.
All "conditional segments" with <<cs_{...some test here...}>> and end with <<es_>>. Anything between those tags is included in the document only when the conditional test is true.
Here are some samples. In this case, they all reference Contract fields, so they should appear within a <<rs_Contract>> segment.
For Extra Credit...
Add one or more of the conditionals above to your contract template, and experiment with the results.
In addition to extracting data from stream data components, you can also extract "meta data" values like those you saw in the first 60 lines of the tag-listing in your browser. Those values include things like date created, the ID of the user who submitted the record, the ID of the record itself, and similar data that is stored for every single record in the system.
All such tags must appear inside a segment that starts with <<rs_record>> and ends with <<es_record>>. For example:
<<rs_record>>
Date Prepared: <<dateCreated>>
Record ID <<id>>
<<es_record>>
However, it is important to note that field like <<createdBy>>, which points to the user who submitted the contract. But that pointer, in turn, references a user record -- a record in the system that stores information about that user.
To put useful information about that user into the print template, we need to create a new segment to reference those fields:
<<rs_createdBy>>
Prepared By: <<fullName>>
Email: <<email>>
<<es_createdBy>>
Of course, that segment must itself be within an <<rs_record>> segment, so the createdBy field can be found. So the resulting template needs to look something like this:
<<rs_record>>
...
<<rs_createdBy>>
...
<<es_createdBy>>
...
<es_record>
For Extra Credit...
Add tags to the bottom of the document to include the Date Prepared and Prepared By data.
Now that we've seen how to find all available tags, let's add the final total to the contract template:
With the template finalized it's time to upload it to the stream as a document.
See the help system to learn more about uploading templates and generating Documents.
Learn more about Smart Objects, as well as and File Attachments (File fields), and Image Attachments.
At this skill station, we've learned a lot about documents, print templates, and template variables. In the end, we produced a contract that is ready to send to a customer. In the next skill station, we will prepare it for an electronic signature (eSigning).