Feature map - Scribe
The best way to view a feature map is on the Start Screen in Tag. There is an interactive graph view and links to all the described apps. Download Tag now to see how it works.
Some of the feature map content related to the Scribe app is included below. A list of all feature maps can be found here.
Scribe app features
The Scribe app generates word processing (*.docx) documents. Although the Automate app also has this capability, Scribe handles more complex documents and includes more advanced features.
It treats dynamic reports (documents) as multi-file projects.
- Data setup (*.rng) files describe data structure
- Templates files (*.xsl) contain logic that uses data
- Data files (*.nsdata) store data for 1 report
The files are all automatically connected: data files reference template files, which reference data setup files. This collection of files is called a Scribe project.
When data files are created, they use data setup files to create a structure and automatically generate forms to gather data. After data has been entered in forms, the template files are used to generate content.
Advanced features include smart data, smart expressions, utility templates and form input.
How are standards used?
The Scribe app has support for several open standards, including data, expressions, logic and rich text.
standards
The Scribe app supports four kinds of open standards.
Data standards are used to define how data fields are structured, how data instructions can be reused and available data sources.
Expression standards address features such as paths, math and functions.
Rich text standards define word processing content, format, layout and conversion.
Finally, Logic standards address powerful features like creating content and data, templates, variables and processing rules.
Scribe app samples
Click on the arrow icon (hover your mouse over the "standards" topic in the feature graph) to review a list of all samples that work in the Scribe app.
If you find a sample of interest, you can jump directly to the Samples app to download it.
auto forms
Use automatically generated forms to enter data.
How does it work?
As explained in file groups, a runnable template file is called a report. It defines a group of files that can be processed together.
The auto forms feature displays a wizard full of forms for all data files in a group.
The wizard guides users to fill in all forms until all required data fields are entered. When that is done, a special form to generate the document is made available.
Forms are arranged alphabetically. The fields in a form match the order of fields in a data setup file. The label for a field will be used in the form if the user provides one.
Data set files may contain form hints that affect how a form displays. For example, if a text field has a form control of "Text area", the form will display with a larger typing area.
More info
auto upgrade
Keep data files in sync with changing report files.
How does it work?
As explained in file groups, a runnable template file is called a report. It defines a group of files that can be processed together.
The auto upgrade feature ensures that data files in a group stay valid over time as report definitions change.
Data files are created by selecting a report (a runnable template file). XML elements are created for every field in every data setup file imported into the report.
Each time the data file is opened it is validated against the current report settings. If a change has occurred since the last time it was opened, the user is alerted that an upgrade is needed to view data or generate a document.
If the user chooses to upgrade, Tag will alter the XML elements as needed and try to save as much data as possible. If a field moves but keeps the same name, its value will be retained.
More info
calculate
Automatically calculate values in forms.
How does it work?
The Scribe template editor has a form settings dialog that supports calculated fields. It can be opened using the "File options" menu at the top of the editor.
The Calculated fields tab lists all data setup files currently attached to (imported by) the template file. Selecting a data setup file (schema) makes the "Add calculated field" button appear.
Each calculated field has 2 parts: a target mapping (which field is being calculated), and an expression which specifies the desired calculation.
Expressions may be as complex as needed, including using functions or looping logic. They can even reach into other data setup files (i.e., access data entered on other forms).
An "Allow overwrite" checkbox is also provided. If this is selected. the current value will be replaced (recalculated) every time the form is opened or saved. Leave this false for durable values like an ID, that should only be calculated once.
More info
file groups
Treat multiple related files as a group.
How does it work?
As the complexity of a generated document increases, typically the number of files involved does as well. Each data source requires a data setup (*.rng) file, and large sections of content are often saved in their own template (*.xsl) file.
Tag addresses this issue by treating all files involved in generating a document as a single group, called a report.
Template files may be runnable (able to generate a document) or just a collection of useful templates. When a template file is runnable, it becomes the root of all connected files in a report file group.
Data files (*.nsdata) contain XML content and a single reference to a report template file. This serves as a declaration that the data in that file is valid according to all the data setup files referenced by the report (alphabetically sorted).
This approach makes it easy to separate data files from all the other files. There are often many data files (e.g., one for each customer) that share a single set of report files.
Over time, data setup rules can change. Fields may be added, removed or renamed. The auto upgrade feature takes care of all that, and helps you keep all files in the group in sync.
More info
form input
Tag provides several ways to enter data in forms.
How does it work?
Scribe forms are automatically generated to match data setup files. Data entry is streamlined using form controls that match the datatype, defining pick lists of acceptable values, and importing multiple data values at a time.
Multiple values can be imported from several sources including pipelines, web API connectors, SQL databases, CSV files and more.
An import wizard is used to guide the process which is similar for all external sources. Once the source is identified, data is retrieved and prepared for value mapping.
Data containing rows and columns (e.g., CSV, SQL database) is handled by displaying the data in a grid. The user must then select a single row to import from.
Hierarchical data like XML can be copied from as-is, or reduced to rows and columns by selecting repeating elements. When repeating elements are identified using an expression, they are treated just like CSV files.
More info
piped
Import data into forms using pipelines.
How does it work?
Data can be imported into forms by running a pipeline document that generates recognizable data. In general, any CSV or XML content will readily map to form fields.
If CSV is used, the import wizard displays all rows and columns and lets the user select a single row to import from. Each column in the row can be mapped to one or more form fields.
If XML is used, there are two ways to map data. An expression can be used on each field that needs input to select a precise chunk of content or data from the XML tree. Alternately, an expression can be used to select a list of repeating XML elements, which can be treated like CSV above. In this case, repeating elements are treated as rows and their child elements are treated like columns.
The last page in the import wizard lets you visually map input data/content to form fields. Each map command can be made conditional (only run if a condition is true) and/or a transformation where an expression is used to modify the input.
Mapping instructions can be saved when defined in the Scribe template editor, and attached to forms in the report. When it's time to import data into a form, a single menu item will call the pipeline, optionally select rows, and reliably run all mapping instructions.
More info
mapping
Providing control over how data values are imported.
How does it work?
Scribe forms make it possible to import data from external sources like pipelines, web API connectors, SQL databases and CSV files.
Mapping is the process of selecting values to copy and optionally modifying each value along the way.
Source values are selected in a mapping panel that lets you draw visual lines between source values and form fields. You can also make a mapping rule conditional, where data will only be copied if an attached expression evaluates to true.
Values can be modified during the copy operation if a transformation expression is attached to the mapping rule. These transformations can be quite powerful by adding or removing characters, performing substitution, or applying one of many available functions.
Mapping rules can be saved and attached to forms in the Scribe template editor. In this case, the entire import process for all fields in a form is triggered using a single menu item click.
More info
opt functions
Tag extension functions for optional data fields.
How does it work?
The Scribe app includes some extension XPath functions that make working with optional data fields easier. These are listed in the insert function dialog.
- opt:inRangeExcl - returns true if a score exists and is greater than a min score and less than a max score
- opt:isDate - returns true if a score exists and is a date
- opt:isDecimal - returns true if a score exists and can be a decimal number (may contain a decimal)
- opt:isFalse - returns true if a score exists and is not equal to "true"
- opt:isGt - returns true if a score exists and is greater than a number
- opt:isGte - returns true if a score exists and is greater than or equal to a number
- opt:isInteger - returns true if a score exists and is an integer number (may not contain a decimal)
- opt:isLt - returns true if a score exists and is less than a number
- opt:isLte - returns true if a score exists and is less than or equal to a number
- opt:isTrue - returns true if a score exists and is equal to "true"
More info
schema-aware
Making the XSLT processor smarter.
How does it work?
Generating content involves combining logic and data. The logic is defined using the XSLT open standard.
XSLT defines the concept of a schema-aware XSLT processor. In simple terms, this refers to an XSLT processor that understands data setup files.
A schema-aware processor validates data before generating content. It also analyzes the datatype for each field, which can make a big impact on your expressions.
For example, a schema-aware processor knows that 10 > 9 if the data field storing 10 is identified as a number. A non-schema-aware processor treats numbers like strings and compares them alphabetically, so it will think 10 < 9.
The Scribe app includes a schema-aware XSLT processor, whereas the Automate app has a non-schema-aware XSLT processor. This represents a significant difference between these two apps.
More info
smart data
The Scribe app works with data in many ways.
How does it work?
Data is used to inform content generation. Values from a data file may be copied into the final document, or expressions can check data values to determine if a specific chunk of text should be included. Data is defined by data setup files.
Sometimes content generation requires a group of files and multiple data setup files are involved. Tag has several features that take advantage of this approach.
When creating data files, all data setup files in a group are included. The same is true when forms are automatically generated for data entry.
If any change is detected over time in a group of data setup files, the auto upgrade feature ensures that data files stay in sync with the most up to date report instructions.
Tag also contains form input features that facilitate entering data into data files from several sources.
More info
smart expr
The Scribe app has a few expression-related features.
How do they work?
Functions are chunks of logic that can be called from within an expression. There are many built-in functions that are defined by open standards. The Scribe app adds two additional groups of functions.
The optional data functions use the opt: name prefix. These functions generally test if a value exists (and is the correct type) before checking a specific condition (e.g., value >= 0).
The statistics functions use the stats: name prefix. These functions convert values between several score types (e.g., T-score, Z-score, scaled score).
The Scribe app also includes a schema-aware XSLT processor. This allows expressions to be a bit smarter, especially related to datatypes.
More info
stats functions
Tag extension functions for statistical functions.
How does it work?
The Scribe app includes some extension XPath functions that make working with statistical data values easier. These are listed in the insert function dialog.
These functions convert values to standard scores, scaled scores, percentiles, ordinal percentiles (e.g., "90th"), T-scores, Z-scores and interpretations (e.g., "very high").
- stats:scaledScoreToInterp
- stats:scaledScoreToPctl
- stats:scaledScoreToPctlOrd
- stats:scaledScoreToStd
- stats:scaledScoreToT
- stats:scaledScoreToZ
- ---
- stats:stdScoreToInterp
- stats:stdScoreToPctl
- stats:stdScoreToPctlOrd
- stats:stdScoreToScaled
- stats:stdScoreToT
- stats:stdScoreToZ
- ---
- stats:tScoreToInterp
- stats:tScoreToPctl
- stats:tScoreToPctlOrd
- stats:tScoreToScaled
- stats:tScoreToStd
- stats:tScoreToZ
- ---
- stats:zScoreToInterp
- stats:zScoreToPctl
- stats:zScoreToPctlOrd
- stats:zScoreToScaled
- stats:zScoreToStd
- stats:zScoreToT
More info
util templates
Non-standard template types that can save you time.
How does it work?
The XSLT open standard defines the concept of templates. Tag extends this to define several utility (widget) templates that serve a specific purpose.
Tag currently has two kinds of widget template: "Combine strings inline" and "Bulleted or numbered list". They both work much the same.
When you edit a widget template, a special panel displays that lets you enter a list of strings that are each protected by an expression. When the document is generated, only strings protected by expressions that evaluate to true will be included.
When you combine strings inline, selected strings are combined using commas or another separator into one sentence (e.g., "string one, string five and string seven"). When you create a list, each selected string becomes a (un)ordered list item.
The strings stored by widget templates can be complex. They can use inline formatting (e.g., bold, italic) and can even call other templates or use embedded logic.
More info
connectors
Web APIs can be called from pipelines and forms.
How does it work?
The Connect app lets you save the instructions to call a web API as a connector. The tag:connector extension step allows pipelines to call remote web APIs from within Tag.
The result returned by a web API is usually JSON. In pipelines this is handled like any JSON content and displays to the user as a tree. It can be saved to a file or converted to XML for further processing.
When importing web APIs into Scribe forms, the data can be mapped to specific form fields using expressions. This works the same way as mapping from XML, and displays the input JSON to the user as a tree.
More info
data setup
Data setup uses instructions to describe your data.
How does it work?
There are 2 main open standards that let you define data. XML Schema is widely used and very powerful, although it is often criticized for being overly complex. RELAX NG (RNG) is an alternative that has it all in the name - "relax".
The rules defined by RNG are generally simpler, and more intuitive for most human users. It can't handle some complex (e.g., scientific) XML structures, but it can handle the vast majority of what's needed by business documents.
Tag uses RNG to describe data and includes a no-code editor to create it. The editor lets you build a tree structure for data, where branches contain information about datatype (string, number, date, etc.) and settings like required/optional. It also lets you list valid string values for a field, which can be used to fill pick lists in a form.
It is possible to use XML Schemas in Tag in some cases. This support is expected to improve over time.
More info
docx export
Generate content for popular word processors.
How does it work?
Word processing files named *.docx use an open standard (Office Open XML) that is widely recognized. In particular, this is the preferred format for Microsoft Word.
While this standard uses XML, it is notoriously difficult to generate content with due to a non-hierarchical internal structure. Tag's approach is to generate content using XSL-FO, which has an excellent internal structure, and then convert the result to *.docx for final editing in your favorite word processor.
This is not an exhaustive solution, and only uses a subset of rich text instructions from either open standard. However, this subset covers the 20% of functionality used by 80% of most document types.
One added benefit to this approach, is that you can use inherited properties in ways that work processors won't let you. For example, you can change the font once at the table level and have that setting apply to all text within the table.
The Scribe app uses *.docx as its preferred output format. The Automate app provides it as an option when generating logic+text.
More info
expr editor
Provides 4 ways to edit expressions.
How does it work?
Expressions are used in many places in Tag. They are critical for defining logic and pipelines, by deciding true/false conditions, performing math, calculating values and more.
Due to this importance, Tag includes a no-code expression editor that has 3 point-and-click panels and 1 text panel that shows raw XPath syntax.
The quick values panel lists common expressions in a tree (e.g., insert a source data value). For some datatypes additional options appear in the tree (e.g., format a date).
The basic panel builds true/false expressions such as those used in if and choose/when instructions. It includes menus to select left and right values and a compare option between them.
The advanced panel includes a more extensive menu to create and combine expression parts. It supports for-loops, sequences, arrays, maps, functions and more.
More info
logic+text
Generate word processing documents using logic and data
How does it work?
Tag provides a no-code way to use logic to generate content. You can insert data, transform it, make chunks of text conditional, perform looping, sorting and more.
Rich text is defined using blocks of text (paragraphs), lists, images and tables. Sections of text within blocks can be styled (bold, inline) or used to insert computed phrases.
The main editing area is like a word processor, with additional buttons to insert and edit logic. Logic bubbles are used to define logic and wrap freely within text like small images.
Logic is defined primarily using an expression editor, which lets you access attached data using a tree.
Content and logic are organized within named templates. The editor displays one template at a time, and you can call templates as much as you want from one another.
More info
logic bubbles
Logic bubbles embed instructions within rich text.
How do they work?
When mixing logic with rich text, authors need the freedom to insert detailed instructions at any point in the content (e.g., only insert a phrase/paragraph/section if the test expression returns true, insert a data value).
Logic bubbles represent any instruction, and float within rich text just like small images. You can freely type around them and even copy/paste like normal text.
When you click on a bubble more options appear. Some bubbles let you open the expression editor, while others open the call-template dialog.
Logic bubbles are only applicable for logic embedded within rich text. The Scribe app uses them extensively, while the Automate app also uses them when you combine logic and rich text.
More info
sql query
SQL databases can be called from pipelines and forms.
How does it work?
The pipeline editor lets you insert standard or extension steps into a pipeline. The tag:sql extension step allows pipelines to call remote SQL databases from within Tag.
The pipeline editor includes a no-code SQL query builder that explores database tables and columns. Options are provided to create common queries, or you can paste and/or edit manually using JDBC SQL syntax.
The SQL database type must be known. Tag currently supports three common types (Microsoft SQL Server, MySQL and Microsoft Access), and more will be added over time.
The result returned by a SQL query is converted into XML that describes rows and columns (CSV data is handled the same way). The XML+JSON editor lets you view query results, and convert to other formats if possible.
When importing into pipelines the result is treated like XML data. When importing into Scribe forms, the data can be mapped to specific form fields.
More info
xml+json
A data editor that supports multiple formats.
How does it work?
There are several pipeline steps that access external data including web APIs and SQL databases. The Scribe and Connect apps also provide ways to import data in a similar way.
The XML+JSON editor was created to handle this data in a consistent way. It contains 3 views of the same data using 3 formats (XML, JSON and text), where the text view always shows raw markup. The XML and JSON views use a tree to display data and work much the same.
When moving between XML and JSON formats, data is automatically converted. There are 2 ways to convert either way (XPath and Jackson) which can handle many situations. Note that there are some XML documents (e.g., XHTML) which do not convert properly to JSON using the Jackson approach.
A common scenario is converting JSON returned by a web API to XML, which can be processed further by pipeline or logic instructions. XML offers a much wider range of processing options, which makes this functionality quite important.