Copy of: What is Smart Content?

Smart content is another way to describe content automation. In Tag this means combining content, logic and data to create the first draft of a word processing document. This is all done within the Scribe app in Tag.

 

While you can generate other kinds of documents (e.g., HTML), our focus is on word processing files that help run organizations all over the world. Tag generates *.docx files that can be opened by most major word processors.

This page describes smart content from several angles:

In places where this page discusses files, this always refers to files on your local file system - nothing is ever stored in the cloud. This provides a secure way to work with sensitive information and ensures you always have access to files you create. 

Steps to generate a draft document

Define data fields

To help the discussion, we'll use a simple example. The organization is a gymnasium which has members. During the registration process some personal information is gathered.

 

Each member has the right to ask for a copy of all personal information the gym has on file. This example will show how that information can be gathered, and how to generate a personal information summary document using it.

Data setup instructions are stored in files that use the *.rng file name extension. They describe all data fields that are used in smart content. Data setup files are imported when creating templates (see below).

 

This screenshot shows the Data Setup screen displaying member data. On the left side you can add, delete or rearrange data fields. On the right side you can add a label for the form or change other field properties.

The Form control dropdown allows you to specify the type of data collected (e.g., checkbox for true/false, decimal box for numbers with decimal points, date picker or dropdown list for a list of values).

Create templates that mix content and logic

Now that we know what data will be collected, it is easy to imagine what the personal information document will look like. We should probably use a table so that data values line up nicely.

Templates are used to organize chunks of content and logic. They have names and can be called from one another. Templates can contain sections of content (e.g., introduction, summary), calculated values, handy utilities (e.g., he-she, his-her, client name), or anything else that you can type into the editor.

Templates are stored in files that use the *.xsl file name extension. These files import data setup instructions to resolve what data fields can be accessed. In most cases, a template file is used to generate a word processing document - in Tag these files are called reports. When a report is generated it begins with a start template specified by the author. The start template can then call as many other templates as needed.

This screenshot shows the Templates editing screen. Our document starts with a paragraph that combines first and last names. It ends with a table that displays all other personal info on file.

The data placeholders are called logic bubbles and flow within text like small images. A variety of logic bubbles are available including value-of, if, choose/when, call-template and more.

Gather data in auto-generated forms

That is all you need to do to create smart content. However, it's not much fun yet because we still need data.

Data is stored in files that use the *.nsdata file name extension. Each file contains one set of data for all defined fields. Multiple files can be combined into CSV files or copied into a database. Data files are linked to a report, and forms only show data fields used by the report.

Tag uses data setup instructions to automatically create forms for data entry. These forms always stay in sync when you make changes to data setup. If the structure changes meaningfully, an option is provided to upgrade older data documents when you open them in a form.

The Forms screen works like a wizard and displays one form for each data setup file imported by the report. In this case, all the fields we created earlier show up under a tab called "member".

The form control chosen during data setup displays here and helps ensure that valid data is gathered. Required fields must be filled out. When all required fields have values the form tab's border turns solid green, which means it is ready to generate.

The generate page (circle tab on the left) becomes available when all data tabs are ready.

Generate a draft document ready for editing

We can now use the data file created for Harry to generate a word processing file. Tag's default file format is *.docx which is used to store Microsoft Office Open XML documents. This format is widely recognized and can be opened in several popular word processors including Microsoft Word, Apple Pages, Google Docs, Apache OpenOffice and more.

After specifying a file location to save to, you can generate a draft *.docx file and open it using your desktop (i.e., it opens the same way as if you double-clicked the file). You must have a word processor installed that can open this kind of file.

The final result is a *.docx file that you can edit like any other. If data changes and you need a new copy, one click of a button is all it takes.

This is what we mean by knowledge automation. We've captured knowledge about gym members and how to communicate with them, and automated the creation of a useful office document.

Low-level instructions

Going a little deeper allows us to discuss low-level instructions. These are called expressions and are used within templates to provide the precision and power needed to create richly formatted, data-driven content.

Expressions use a popular and well-supported open standard called XPath to tell the computer exactly what to do. While in some applications expressions are reserved for use by programmers, in Tag we aim to make them simple enough that anyone can use them. We do that by creating user-friendly expression editing panels.

A look at the instructions used

High-level instructions

We've already discussed several high-level instructions. Data setup files describe fields and store preferences for how to interact with them in forms. Template files store named templates and references to data setup files. Data files store references to (report) template files and can auto-upgrade when changes are detected over time.

It should be noted that all instructions used in smart content are visible to authors. So many new technologies are clever, but hide exactly why they do what they do. Smart content instructions are 100% visible to authors, and use open standards where possible.

 

When you click on a logic bubble, more buttons appear as shown above. Clicking the Edit expression button opens up a dialog with 4 choices of panel to edit the expression with.

The simplest panel is Quick values as shown to the left. It shows all imported data fields and lets you select them in a tree. If the field can be formatted (e.g., date) options appear to select common formats.

To access more power you can choose the Basic expression editing panel.

The basic panel is designed for expressions that evaluate to true or false. This is the kind of expression used in if and choose/when instructions. For example, the following expression would display a chunk of content if the "competitive" field has a value of true.

Each of the words shown above are touch-sensitive and will display a popup menu when clicked. This effect is shown in the screenshot to the right.

The left and right words represent data fields or literal (manually entered) values. The center word offers a list of comparisons that are appropriate for the type of data being compared (e.g., "equals" or "does not equal" for true/false, or math comparisons like >, <. >=, etc. for numerical fields).

Even more functionality is available when you choose the Advanced expression editing panel.

The advanced panel is a full-featured touch-sensitive expression editor. It uses popup menus just like the basic panel, however it includes far more options to select from.

As shown to the left, each part of the expression becomes clickable and presents a popup menu with all the available options. Expression parts can be nested and grouped within brackets when needed.

The Function... menu item opens a dialog with dozens of functions to choose from. A view of the format-date function used by the "Date of birth" row in our example is shown below.

The final option is the Raw expression editing panel. This is a text area that lets you type using raw XPath syntax.

We're not going to provide a screenshot for the raw panel, because the whole point of Tag is to shield users from having to deal with dense (and hard to remember) technical syntax. That being said, the advanced panel does not handle 100% of XPath syntax and the raw panel does. It is rare that you might need it, but if you do it can be an invaluable tool.

How templates act as decision trees

Each template contains a combination of content and logic. It gets copied into the final generated document by starting at the beginning, replacing all logic bubbles with whatever they represent, and continuing to the end.

When if or choose/when instructions are used the flow of a template can change dramatically. If content is protected by an if instruction, it will only be included if the result of the test expression is true. Similarly, with a choose/when instruction, there are one or more when fragments and an optional otherwise fragment. Only the first when fragment that evaluates to true is copied to the result document - if none do the otherwise fragment is copied, if one exists.

This kind of logical flow can be represented by a decision tree. This is shown below using a slightly more complicated example that uses two if instructions and a choose/when.

 

To keep the display from becoming too confusing, only one fragment of text is viewed at a time. Note there are eight different fragments in the displayed template above (abas3.interpretation). You select which fragment to view using the decision tree graph at the top.

In this case, the first when instruction is selected which is protected by an expression that checks a pattern. The string of characters it is testing for is one option from a dropdown list created during data setup (just like "Level of experience" above).

If there were other templates in this document, you could view them using the Show template dropdown list. Each template would have its own unique decision tree. Tools are provided to add, remove or edit templates in the current document.

The last thing to note about the above screenshot is the navigation panel on the left. Use tabs at the top to switch between the three main file types (data setup, templates and data). The tree displays a folder in your local file system which can be remembered as a favorite. You can quickly swap between favorite folders using the dropdown list.

Summing up

Smart content provides a way to capture how you want a document to read, even while reflecting changes in connected data values. Once you've got a document all setup, the process is pretty simple: 

  1. Gather data

  2. Generate

  3. Manually edit

What you may find is that quality can improve in two ways. First, and most obviously, there will never be a missed he/she or client name mis-paste. Every draft document generation will do exactly what you tell it to.

Second, since so much busy work has disappeared, you have more time to spend on step 3 where you can customize the content to reflect current circumstance. Not everything should be automated, and you should be able to draw the line where too much automation makes no sense. With Tag you can do that. It's free. Try it.

nSymbol Technology Inc. is a startup company operating out of Alberta, Canada. 

© 2021 by nSymbol Technology Inc.