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:
Field | Description |
---|---|
No | The document version number, where where "1" indicates the most recent version, "2" the second most recent version, "3" the third most recent version, and so on. Hence the largest value in this column would indicate the first version of the document. |
Who | The user account of the user who created the document version. |
When | The creation date and time of the document version. |
Initial | The name and previous value of each field that was changed by the document version. If a changed field had no previous value, then the field name suffixed with the text "No initial value" will display. |
New | The name and new value of each field that was changed by the document version. If a changed field had a previous value, then the new value suffixed with the text "(Updated)" will display. If a changed field had no previous value, the the new value suffixed with the text "(New)" will display. |
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:
- Default values for fields described in the tables below are shown in bold text.
2.1 Required System Fields
Field | Valid Values | Description |
---|---|---|
componentName | sc-audit-table | The component name. Example: "componentName": "sc-audit-table" |
2.2 Required Customizable Fields
Field | Valid Values | Description |
---|---|---|
name | Any value written in camel case. | Defines the name of the sc-audit-table field in the document and database. Example: "name": "testScAuditTable" |
2.3 Optional Customizable Fields
Field | Valid Values | Description |
---|---|---|
fullWidth | true | The sc-audit-table field displays full width on the form. Full width is recommended for the sc-audit-table field. Example: "fullWidth": true` |
false | Default value. The sc-audit-table field does not display full width on the form. | |
label | Any value | Defines the name of the sc-audit-table field on the form i.e. the field label. Example: "label": "Test sc-audit-table" |
Defaults to the sc-audit-table field displaying without a field label on the form. | ||
linkFunction | The linkFunction field is only required when the version history of a document is to be displayed in a customized "fit for purpose" sc-datatables rather than the default "fit for purpose" sc-datatables.The linkFunction field value is the name of the customized "fit for purpose" sc-datatables and is specified in a single element array.The linkFunction field is used in conjunction with the targetTable field and a customized "fit for purpose" sc-datatables.Note: The customized "fit for purpose" sc-datatables will require a linkFunction field set to the name of the sc-audit-table and a dataSource field set to "internal". |
|
sc-datatables name | The name of the customized "fit for purpose" sc-datatables and specified in a single element array. Example: "linkFunction": ["displayTestScAuditTable"] |
|
Defaults to using the sc-audit-table default "fit for purpose" sc-datatables to display the document version fields listed and described in Section1 Purpose | ||
targetTable | The targetTable field is only required when the version history of a document is to be displayed in a customized "fit for purpose" sc-datatables rather than the default "fit for purpose" sc-datatables.The targetTable field value is the name of the customized "fit for purpose" sc-datatables.The targetTable field is used in conjunction with the linkFunction field and a customized "fit for purpose" sc-datatables. |
|
A sc-datatables name | The name of the customized "fit for purpose" sc-datatables. Example: "targetTable": "displayTestScAuditTable" |
|
visible | false | The sc-audit-table field is not visible on the form. Example: "visible": false |
true | Default value. The sc-audit-table field is visible on the form. | |
useLabels | true | The sc-audit-table field will display the label of the field that has changed instead of the name of the field. If the field has been defined without a label, the name of the field is displayed Example: "useLabels": true |
false | Default value. The sc-audit-table display the name of the field that has changed. |
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.