Scribe Forms - User Guide

Data files are used to store data in a way that can be accessed by Scribe reports. They use the *.nsdata file extension which is defined by, and only works within, Tag.

Files are accessed using the file tree on the left side of the window, which is discussed further in the Tag user guide. The "Forms" screen is shown below with the menu open to create a new data file. The report selected can be in the same folder, or anywhere else accessible using the local file system.

After creating the file, select the demo-setup form tab. This will display the auto-generated form that gathers data for the demo-setup.rng data setup file.

It may be necessary to turn off the data field filter using the "Only show required and fields used by report templates" menu item shown below. If that item is selected (on), it will only display fields you have used in the report (and required fields). Turning it off shows all fields.

It should be noted, that this form was generated entirely from information in the data setup file. The demo-data-file.nsdata file has a reference to a report (demo-templates.xsl), and will create one form for every imported (direct or indirect) data setup file. When all required fields in all forms have been filled in, the report is ready to generate.

If you change, add or remove any of the data setup files imported by a report, the data file may be auto upgraded on next use. Whenever a *.nsdata file is opened in Tag, any change in data definitions will be detected. The user will have the choice of upgrading the data, or not opening the file in the Forms screen.

If the file is not opened, it can still be accessed in other ways (e.g., to generate a summary report, convert to another format, etc.). It simply cannot be used to generate content in Tag, unless it is fully consistent with the current version of the report.

The process of auto upgrading data files will attempt to save as much data as possible. For example, if a data field is moved within the data setup file, it will trigger an auto upgrade with no data loss (the value is copied from old location to new location). If the field's name changes, or its properties change significantly, the value may not be copied.

Where possible, form controls will prevent invalid input. For example, if an Integer box is selected as a Form control in the Setup screen, then while entering data the form control will not accept any characters other than 0-9.

When entered data is invalid, an error message will appear (e.g., scaled scores must be within 0-20 range).

Other controls that assist with data entry include date pickers, pick lists (drop-downs) and checkboxes.

Buttons to save data are beneath the form. If there are multiple forms you can also use navigation buttons at the bottom to move between them.

If the data you want gathered in forms comes from other sources (e.g., database, other system, survey, cloud service, ...), the auto-fill feature can save you a lot of time. If you can get an extract of the data in CSV format, then it only requires a bit of mapping.

Each form has a more button (3 vertical dots) which has an Auto fill / Copy data from CSV... menu item. It opens a CSV import wizard. Menu items are also provided for importing from API connectors, task pipoelines, SQL databases and SPARQL endpoints.

If the filter to hide unused fields in on (by default it is), the first page of the wizard suggests turning it off. Leaving it on will filter the imported data to only use copy column values into fields that are visible in the form (i.e., required or used in report). Click Next to locate the CSV.

After selecting the CSV to import from, a table view of rows is displayed. When one row is selected to import, the Next button will become available.

The next page is where data mapping occurs. On the left side is a list of CSV column names. On the right is a list of data fields from the current form.

To map data values, click on a CSV column name on the left. Then click on the corresponding data field on the right. This creates a mapping line between the two which shows how data will be copied. Repeat until all columns of interest are mapped. Remove lines by clicking on them and pressing the Delete key.

When the mapping is all done, you have the option to save it to a mapping file (*.nsmap). You can use mapping files to save steps during auto fill in the future, or add one to the report so it is always available in the form. Mapping commands can also be made conditional, or used to transform copied values on the fly. More information is provided in the Templates user guide.

The CSV Import step-by-step guide provides another view of the auto fill feature.

The previous section showed how to copy data values from one CSV file to one data file. This section explains how to export (copy) data from one or more data files to one CSV.

The columns of a CSV file correspond to data fields. One row of a CSV corresponds to one set of fields (e.g., a data file).

The CSV export feature is accessed on the Generate page using the export menu, or using the more menu beneath the file tree and the Export / Comma separated values (CSV)... menu item.

Whichever way you request it, a wizard opens to walk you through a few steps. First, specify which file(s) to scan for values. If multiple data files are of interest, they must all reference the same report. This ensures they all map data fields to CSV columns in exactly the same way.

When you click Next, the data is prepared for export and the number of rows is displayed. After clicking Next again you can choose a file location, save the CSV file, and open it using the default program to open CSV files on your computer.

Here is a view of the exported CSV.

The CSV Export step-by-step guide provides an example of combining four data files for the same report into a single CSV file with four rows.

After data has been entered into all forms, click the magic wand form tab to return to the Generation page.

If there are no errors in any forms, then content generation is possible. The eye tool supports preview and is always available. You can see what the generated content will look like, but not save or copy.

The magic wand tool will also be available if your account has sufficient permission to generate to a file. If you purchase a subscription, you get unlimited generations as shown above.

New accounts also have unlimited generations during the free trial period. After that, they get 3 free generations to a file per month while using a $0 Community subscription.

Free tier accounts can manage their 3 generations to a file per month on this screen. The screenshot below shows that 2 of 3 free generations have been used so far this month. The counter resets each month on the day that the account was created (to a max of day 28).

The shopping cart tool opens the self-serve billing portal in a web browser. Here you can securely purchase a subscription using a credit card. After making a purchase, clicking the refresh tool will update the screen to allow unlimited generations as shown earlier.