Skip to content

sc-reference-no

1 Purpose

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 'counter' field on a 'counter' document is used to generate a reference number. The 'counter' field value is incremented by one for each new 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:

  1. 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 System generated The document id of a 'counter' document used to generate a reference number.
The process of creating a 'counter' document is described in the Section "3 Creating a Counter Document" below.
counterFieldName System generated The name of the 'counter' field on a 'counter' document used to generate a reference number.
The process of creating a 'counter' document is described in the Section "3 Creating a Counter Document" below.
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": "#"
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"
'name' field value Default value. Displays the 'name' field value with the first character in upper case and any following upper case characters in lower case prefixed with an underscore character.
Example: "Test_scl_reference_no" is the default value for the "name" field value "testScReferenceNo".
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 with a 'counter' field, insert the following sc-reference-no definition into the document template changing the 'name' and 'format' and 'label' fields to suit:

        {
            "componentName": "sc-reference-no",
            "type": "Reference No",
            "format": "#",
            "label": "Test sc-reference-no",
            "name": "testScReferenceNo",
            "counterDocumentId": "",
            "counterFieldName": ""
        }

Then on the creation of the first document from the template, the system will create a new 'counter' document with a 'counter' field and insert its document id and the 'counter' field name into the definition's 'counterDocumentid' and 'counterFieldName' fields respectively. The 'counter' field name is a concatenation of the sc-reference-no 'name' field value and the text 'Counter'. For above example, the template's sc-reference-no definition would now look like:


        {
            "componentName": "sc-reference-no",
            "type": "Reference No",
            "format": "#",
            "label": "Test sc-reference-no",
            "name": "testScReferenceNo",
            "counterDocumentId": "ae29e410-bb44-11e6-943f-8deecc4f8938",
            "counterFieldName": "testScReferenceNoCounter"
        }

Note To use the same counter in other templates, copy the resulting sc-reference-no definition into those templates.

4 Typical sc-reference-no 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",
    "format": "YYMMDD-#",
    "label": "Test sc-reference-no",
    "name": "testScReferenceNo",
    "enabled":false,
    "counterDocumentId": "ae29e410-bb44-11e6-943f-8deecc4f8938",
    "counterFieldName": "testScReferenceNoCounter"
}

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,
    "fullWidth":true,

5 Examples

Example 1

sc-reference-no with only its required system fields and required customizable fields defined.

        {
            "componentName": "sc-reference-no",
            "type": "Reference No",
            "format": "YYMMDD-#",
            "label": "Test sc-reference-no",
            "name": "testScReferenceNo",
            "counterDocumentId": "ae29e410-bb44-11e6-943f-8deecc4f8938",
            "counterFieldName": "testScReferenceNoCounter"
        }

Resulting field on the form:

alt text

Resulting field on the form after saving a new document:

alt text

Resulting field in document and database:

    "testScReferenceNo": "180221-56",