sc-audit-table

This document is a user guide for the sc-audit-table component version 5.15, released April 17, 2019.

1 Purpose

The sc-audit-table component is used to display the version history of a document. It does this by linking to and placing a "fit for purpose" sc-datatables field on the form and displaying the version history of the document as rows in a table.

Formbird provides the option of defining the sc-audit-table field with or without defining a linked "fit for purpose" sc-datatables field.

If the sc-audit-table field is defined without a linked "fit for purpose" sc-datatables field, then Formbird will use a default "fit for purpose" sc-datatables to display the version history of a document on a form.

Otherwise, the sc-audit-table field can be defined with a customized "fit for purpose" sc-datatables in order to customize options such as column sorting, column heading display names, hide/add columns, style of selection, table reload button, etc.

The default "fit for purpose" sc-datatables displays, for each version of a document, values for the following fields:

Formbird is able to generate the version history of a document because each version of a document is kept and can be retrieved from the database. This removes the need to save the version history of a document as part of the current document.

The sc-audit-table definition provides fields for setting the properties of an audit table field and is fully described below.

2 Definition

sc-audit-table is defined by a set of name/value pair fields consisting of:

• Required system fields
• Required customizable fields
• Optional customizable fields

Note:

1. Default values for fields described in the tables below are shown in bold text.

2.1 Required System Fields

2.2 Required Customizable Fields

2.3 Optional Customizable Fields

3 Viewing the Version History of a Document

The options for viewing the version history of a document are:

Option 1:

Use one document template to define the fields of the document and the sc-audit-table field. Hence the resulting form would display the fields of the document and a table displaying the version history of the document.

A downside of this approach is the form will always displays the version history of the current document rather than viewing the version history on an as needed basis.

Option 2:

Use two document templates, the first to define the fields of the document and the second to define the sc-audit-table field.

On the first template, include a sc-static-html field to place a button on the form, which when clicked will pass the documentId of the current document to the second template i.e. the template with the sc-audit-table field for displaying the version history of the current document.

The advantage of this approach is the document history can be viewed on an as needed basis.

Example:

        {
            "componentName": "sc-static-html",
            "fullWidth": false,
            "html": "<div style='color:DimGray; font-weight:bold; font-size:1em'><a class='btn btn-default btn-bg' href='/form/{{doc.documentId}}/58be6bc0-4e9a-11e9-83de-dbe54b6cabc9' target='_self' ><span class='glyphicon glyphicon-search'></div>"
        }

This would place a search button on the form displaying the fields of the current document. Clicking the button will pass the the documentId of the current document to the template with documentId "58be6bc0-4e9a-11e9-83de-dbe54b6cabc9", being the template with the sc-audit-table field for displaying the version history of the current document.

4 Typical Definition

4.1 sc-audit-table defined WITHOUT a sc-datatables definition

Below is a typical sc-audit-table definition defined:

• Without a customised "fit for purpose" sc-datatables. Hence Formbird will use the sc-audit-table default "fit for purpose" sc-datatables to display the version history of a document on a form. The fields displayed for each document version are listed and described in Section1 Purpose.
• With its required fields plus any optional field whose value is typically other than its default value.

        {
            "componentName": "sc-audit-table",
            "label": "Test sc-audit-table",
            "name": "testScAuditTable",
            "fullWidth": true
        }

One or more of the optional fields shown below can be included in the above definition should a value other than their default value be required.

            "visible": false,
            "useLabels":true

4.2 sc-audit-table defined WITH a sc-datatables definition

Below is a typical sc-audit-table definition defined:

• With its required fields plus any optional field whose value is typically other than its default value.
• With a customised "fit for purpose" sc-datatables definition.

        {
            "componentName": "sc-audit-table",
            "label": "Test sc-audit-table",
            "name": "testScAuditTable",
            "fullWidth": true,
            "linkFunction": [
                "displayTestScAuditTable"
            ],
            "targetTable": "displayTestScAuditTable"
        },
        {
            "componentName": "sc-datatables",
            "fullWidth": true,
            "linkFunction": [
                "testScAuditTable"
            ],
            "selectOnLoad": false,
            "multiSelect": false,
            "name": "displayTestScAuditTable",
            "enableColumnMoving": true,
            "enableColumnResizing": true,
            "exportTypes": [
                "pdf",
                "copy",
                "csv"
            ],
            "templateTarget": "currentWindow",
            "columnSearch": true,
            "rowsPerPage": 10,
            "gridColumns": [
                {
                    "displayName": "Version",
                    "field": "no",
                    "type": "string",
                    "width": 1
                },
                {
                    "field": "who",
                    "displayName": "Updated By",
                    "width": 4
                },
                {
                    "field": "when",
                    "displayName": "When",
                    "width": 3,
                    "type": "date",
                    "cellFilter": "date:'dd-MM-yyyy hh:mm a'"
                },
                {
                    "field": "initial",
                    "displayName": "Initial Value",
                    "width": 4
                },
                {
                    "field": "new",
                    "displayName": "New Value",
                    "width": 4
                }
            ],
            "dataSource": "internal",
            "showReload": true
        }

One or more of the optional fields shown below can be included in the above sc-audit-table definition should a value other than their default value be required.

            "visible": false,
            "useLabels":true

5 Examples

Example 1

sc-audit-table defined WITHOUT a "fit for purpose" sc-datatables definition.

        {
            "componentName": "sc-audit-table",
            "label": "Test sc-audit-table",
            "name": "testScAuditTable",
            "fullWidth": true
        }

Resulting field on the form prior to the creation of a document:

The template for the form below showing the text box, checkbox, checklist, date/time and a dropdown fields was defined to also include the above sc-audit-table definition. As a result, the default "fit for purpose" sc-datatables field displays on the form and will be used display the version history of a document created using this form.

Resulting field on the form after creating and saving the 1st version of a document:

Resulting field on the form after updating and saving the 2nd version of a document:

Example 2

sc-audit-table defined WITH a linked sc-datatables definition and with the typically needed fields.

        {
            "componentName": "sc-audit-table",
            "fullWidth": true,
            "label": "Test sc-audit-table",
            "name": "testScAuditTable",
            "linkFunction": [
                "displayTestScAuditTable"
            ],
            "targetTable": "displayTestScAuditTable"
        },
        {
            "componentName": "sc-datatables",
            "fullWidth": true,
            "dataSource": "internal",
            "gridColumns": [
                {
                    "field": "no",
                    "displayName": "Version",
                    "type": "string",
                    "width": 1
                },
                {
                    "field": "who",
                    "displayName": "Who",
                    "width": 4
                },
                {
                    "field": "when",
                    "displayName": "When",
                    "width": 3,
                    "type": "date",
                    "cellFilter": "date:'dd-MM-yyyy hh:mm a'"
                },
                {
                    "field": "initial",
                    "displayName": "Initial Value",
                    "width": 4
                },
                {
                    "field": "new",
                    "displayName": "New Value",
                    "width": 4
                }
            ],
            "rowsPerPage": 10,
            "columnSearch": true,
            "exportTypes": [
                "pdf",
                "copy",
                "csv"
            ],
            "enableColumnResizing": true,
            "enableColumnMoving": true,
            "name": "displayTestScAuditTable",
            "linkFunction": [
                "testScAuditTable"
            ]
        }

Resulting field on the form prior to the creation of a document:

The template for the form below with the text box, checkbox, checklist, date/time and dropdown fields was defined to also include the above sc-audit-table definition and its linked customized "fit for purpose" sc-datatables definition. As a result, the customized "fit for purpose" sc-datatables field displays on the form and will be used to display the version history of a document created using this form.

Resulting field on the form after creating and saving the 1st version of a document:

The 1st version of a document:

• Sets the initial values for the text box, check list, date time and drop down fields.
• Has no value set for the check box field

Resulting field on the form after updating and saving the 2nd version of a document:

The 2nd version of the document:

• Has the initial value set for the check box field
• Updates the values of the text box and drop down fields

Resulting field on the form after updating and saving the 2nd version of a document:

The 3nd version of the document:

• Updates the values of the check box, check list and date time fields.