With Onit, you can leverage Record data to generate Microsoft Word documents. The Generate Document Action relies on Liquid markup in a pre-built template to query Record data and insert it in the appropriate location.
For instance, if your App manages Non-Disclosure Agreements (NDA), you could generate a document that contains Record-specific data (such as the other party’s name to the agreement, its effective date, etc.) for each NDA Record in your App. This allows you to essentially use Onit as a publishing tool.
In this tutorial, we’ll first explain how to build the Word template and then how to configure the Generate Document Action. Finally, we'll show you how to generate a table of child data in your Word document.
Before We Start ...
This tutorial will assume you understand the following concepts:
To both build the template and view the generated document you’ll also need access to Microsoft Word.
Note that Onit can only generate .docx files
Building the Template
To ensure Onit understands the format and structure of the Word document you want to generate, you’ll need to build a template and save it as a .docx file. This template can include any Liquid markup to extract data from an Onit transaction.
For example, can you spot the Liquid markup in the following example? (Hint: Anything wrapped in {{ and }} contains Liquid.)
In the example above, {{effective_date}}, {{name}}, and {{incorporation_state}} are all Onit variables. When the document gets generated, the Liquid will be replaced with the Record in question’s actual values. Like so:
Templates can include any Liquid, including loops, if/then statements, filters, etc.
Make sure your template document is saved as a .docx file before moving on.
Uploading the Template
When your template is ready, upload it as an Asset to your Onit environment.
1. Browse to Administration
Browse to your environment’s Administration page.
2. Browse to Assets
From the left-hand pane of the Administration page, select Assets.
3. Upload Your Template
Select your template and click Upload.
Updating Your Template
If you need to update your document template, always delete the existing version first and then re-upload the new version.
Configuring a Generate Document Action
Let’s get to configuring our app with an Action to put this template to work.
1. Configure an Attachment Field for the Generated Document
First, we need to create a new Field to store the generated document. Open the Wizard, browse to the Fields screen, and Add a new Field.
Give this Field a Name and a Type of Attachment. Change its Display In property so it only shows on the View page.
Update your app.
2. Configure a Generated Document Action
Browse to your App’s Advanced Designer page. From the left-hand pane, select the Actions node.
Select Generate Document from the Add dropdown.
Provide this Action with a Name. For the Action’s Template Name, provide the full file name of your document template, including the extension.
Fun fact: You can use Liquid for the Template Name property to conditionally use different document templates.
For the Attachment property, select the Name of the Attachment Field you created in Step 1 above.
Under Saved File Name enter 'Generated_NDA'.
Save your Action by selecting OK.
3. Link Your Action to a Button
Add a new Action Button and link it to the Action you created.
Need help creating an Action Button? See our tutorial Creating a Button to Execute an Action.
Test It Out
Congrats! You just created an awesome Button for your document generation needs.
Take it on a test run by visiting one of your app’s transactions and selecting the new Button.
Look for your generated document in the generated_document Field in your transaction's Details Panel.
Below is a screenshot of part of an example document template for an NDA:
Generating a Table in Word with Child Record Data
Similar to using a Generate Spreadsheet Action to fill an Excel spreadsheet with child transaction data, you can also set up a Word document template with a table and fill the table with child transaction data upon generation.
1. Add a Table to Your Word Template
Add a new table in your Word document template, creating columns and rows to define where Onit should populate transaction data.
Below is an example of a table in a template that will hold four columns of Onit Field values.
The first row of the table is for the column headers. Onit doesn't care what values appear here, and you could technically exclude this row.
The second row contains the Liquid expressions that tell Onit which transaction data to insert. There are two critical concepts to understand here:
- Looping: The example template above shows that each Liquid expression contains loop_atom. This Liquid says to Onit, when generating the table, run this Liquid expression for each child transaction. For example, let's say there are five child transactions that need to be inserted into the table. That means that loop_atom will run five times. The Liquid that follows loop_atom tells Onit what value to insert. For example, loop_atom.status tells Onit to always insert the status Field value into this column.
- Context: Context is king when it comes to Liquid. In this case, any Liquid that you insert into the table lives at the level of the child transaction. In other words, {{loop_atom.field_name}} will only work if the Field in question lives within the child app.
Additionally, note that outside the table you can still reference parent Field names. In the example above, we're collecting the parent transaction's name Field and issued (i.e., generation) date values.
2. Create a Word Bookmark for the Table
We need to tell Onit where to expect to insert child transaction data so we can create a Word Bookmark to reference in our Generate Document Action.
To do this, place your cursor at the very beginning of the row containing your Liquid loop expressions, as highlighted in the screenshot below.
Next, select Bookmark from Word's Insert menu.
Give your Bookmark a name and select Add.
Save your document template and upload it to your environment.
3. Point Your Action at Your Document's Bookmark
Back in your app's Generate Document Action, select the + button below the Populate Table with Related Transactions property.
For the Word Bookmark Name property, provide the name you gave your Bookmark in your Word template. For the Relation Field property, provide the Name of the HasMany Field that correlates with the child App you want data exported from.
Save your Action by selecting OK.
Test Out Your Table
Now, give your Generate Document Action a try.
Below is a screenshot of what the document template we've been working with above produced for a parent transaction:
Gotchas
- We recommend not referencing Fields with a Type of HTML in your generated documents, as these Fields will be printed in their raw HTML form.
- If your generated document contains unexpected values (like AtomDrop instead of a valid Field value), try copying/pasting all of the associated Liquid into a basic text editor that doesn’t support formatting (e.g., Notepad, Sublime Text). After pasting the text into the text editor, copy/paste it back into your Word document. Following these actions will usually remove any formatting that Microsoft Word adds in/around the Liquid that may be causing issues.
- To preserve line breaks when displaying TextArea Fields' values, you'll need to use the following script in your document template, replacing textarea_field_name with the name of your TextArea Field:
{% assign magic = '{ "key": "\r\n"}' | parse_json %}{% assign lines = textarea_field_name | split: magic.key %}{% for line in lines%}{{line}}{%endfor%}