Generating a Word Document

by Christina Moore Updated Aug 14, 2019

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 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 we'll explain how to configure the Generate Document Action. Finally, we'll wrap up by showing 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

In order for Onit to know the format and structure of the Word document that you want to generate, you’ll need to build a template and make sure to 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 down the road, 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 document once it's generated. 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. Additionally, for the Action’s Template Name, provide the full file name of your document template, with the extension included.

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.

Add a new Action Button and link it to the Action that you just 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

Very similar to how you can use 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

In your Word document template, add a new table, creating columns and rows to define where Onit should populate transaction data into.

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: As seen in the example template above, 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, lets say there are five child transactions that need to get 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 value of the status Field 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 it should expect to insert child transaction data so we'll create a Word Bookmark to reference in our Generate Document Action.

To do this place your cursor at the very beginning of the row which contains 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 copy/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 is adding 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%}
Previous Article Keeping Records Updated with a Generated Spreadsheet
Next Article Keeping Field Values in Sync Across Apps

© 2020 Onit, Inc.

docs.onit.com contains proprietary and confidential information owned by Onit, Inc. that is subject to copyright. Onit presents it exclusively to you for your sole use in conjunction with using Onit products. No portion of the materials contained herein may be used for any other purpose. No portion of the materials contained herein may be shared with third parties or reproduced in any form.