sc-reference-no
1 Purpose
This document is a user guide for the sc-reference-no component as of version 5.1.
sc-reference-no places a read only reference number field on a form, generally for the purpose of generating and displaying a reference number for a document created using the form.
A pre-requisite for sc-reference-no is the existance of a Counter document having at least one Counter field that stores its last generated reference number (an integer value).
A Counter field value is incremented by one each time it is used to generate a reference number.
Hence to generate a reference number, a sc-reference-no field definition specifies which Counter document and Counter field to use.
The process of creating the Counter document is described in Section 3 Creating a Counter Document.
The sc-reference-no definition provides fields for setting the properties of the reference number field and is fully described below.
2 Definition
sc-reference-no 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-reference-no | The component name. Example: "componentName": "sc-reference-no" |
2.2 Required Customizable Fields
| Field | Valid Values | Description |
|---|---|---|
| counterDocumentId | Counter document documentId | The documentId of the Counter document used to generate a reference number.The process of creating the Counter document is described in Section 3 Creating a Counter Document. |
| counterFieldName | Counter field name | The name of the counter field in the Counter document used to generate a reference number.The process of creating the Counter document is described in Section 3 Creating a Counter Document. |
| format | Defines the display format of the reference number. The format must use a # character to represent the generated reference number. It can optionally include a date format and/or other characters. If the format contains more than one # character, only the first # character will be replaced by the generated reference number. Example: To display just the generated reference number, use: "format": "#"Example: To display the generated reference number prefixed by the character 'A' plus the date, use: "format": "A-YYMMDD-#" |
|
| name | Any value written in camel case | Defines the name of the reference number field in the document and database. Example: "name": "testScReferenceNo" |
2.3 Optional Customizable Fields
| Field | Valid Values | Description |
|---|---|---|
| fullWidth | true | The Reference Number field displays full width on the form. Example: "fullWidth": true |
| false | Default value. The Reference Number field does not display full width on the form. | |
| label | Any value | Defines the name of the reference number field on the form i.e. the field label. Example: "label": "Test sc-reference-no" |
| Defaults to the sc-reference-no field on the form displays without a field label. | ||
| visible | false | The Reference Number field is not visible on the form. Example: "visible": false |
| true | Default value. The Reference Number field is visible on the form. |
3 Creating a Counter Document
To create a Counter document:
Open the Template Editor:
For each needed Counter field, add a name/value pair field to indicate its name and initial integer value.
Click save to create a Counter document, having in this case, 2 counter fields each initialized to zero.
To use the above Counter document and its first Counter field to generate reference numbers, a sc-reference-no definition would contain the two name/value pair fields shown below:
"counterDocumentId": "4b92ba10-301e-11e9-be5f-f5879a6b18f9",
"counterFieldName": "testCounter1",
4 Typical Definition
Below is a typical sc-reference-no definition, defined with its required fields plus any optional field whose value is typically other than its default value.
{
"componentName": "sc-reference-no",
"counterDocumentId": "4b92ba10-301e-11e9-be5f-f5879a6b18f9",
"counterFieldName": "testCounter1",
"format": "YYMMDD-#",
"name": "testScReferenceNo",
"label": "Test sc-reference-no",
"enabled": false
}
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.
"fullWidth": true,
"visible": false,
5 Examples
Example 1
sc-reference-no defined with the typically needed fields.
{
"componentName": "sc-reference-no",
"counterDocumentId": "4b92ba10-301e-11e9-be5f-f5879a6b18f9",
"counterFieldName": "testCounter1",
"format": "YYMMDD-#",
"name": "testScReferenceNo",
"label": "Test sc-reference-no",
"enabled": false
}
Resulting field on the form:
Resulting field on the form after saving a new document:
Resulting field in document and database:
"testScReferenceNo": "190215-1"
Also in the background the system will update the Counter document, incrementing its testCounter1 field by 1.
{
"documentId": "4b92ba10-301e-11e9-be5f-f5879a6b18f9",
"systemHeader": {
"templateId": "74746c80-8378-11e6-99b1-71ee944cf59f",
"systemType": "document",
"createdWith": "74746c80-8378-11e6-99b1-71ee944cf59f",
"keyIds": [],
"createdDate": "2019-02-14T06:11:50.959Z",
"createdBy": "b7c1e1b0-2b9f-11e6-ac9c-170c531a5a0c",
"serverUpdatedDate": "2019-02-14T13:00:25.055Z",
"serverCreatedDate": "2019-02-14T06:11:50.959Z",
"versionId": "6b0c2bf0-301f-11e9-a354-352b718f55c3",
"currentVersion": true
},
"testCounter1": 1,
"testCounter2": 0
}