Skip to content

sc-time-recorder

1 Purpose

sc-time-recorder places a time recorder field on a form, allowing the user to record periods of time. For example, to record one of more periods of time spent working on a task, a sc-time-recorder field would be placed on a Task form. Then for each time period recorded against a task, sc-time-recorder will create and link a Timesheet document to the parent Task document and include the following information:

  • Start time of the time period
  • End time of the time period
  • A link to the parent Task document
  • A link to the logged in user's account document

Note: The parent Task document must first be created in order to link timesheet documents to it. Until then, the sc-time-recorder field on the Task form is disabled.

Clicking the sc-time-recorder field will start or stop a time period and in the process create and link a timesheet document to the parent document and to the logged in user's account document. Doing so again will create and link another timesheet document.

The sc-time-recorder definition provides fields for setting the properties of a text box field and is fully described below.

 

2 Definition

sc-time-recorder 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-time-recorder The component name.
Example: "componentName": "sc-time-recorder"

2.2 Required Customizable Fields

Field Valid Values Description
accountDocField A related document field on the timesheet document. The timesheet document field for recording the documentId of the logged in user account.
Example: "accountDocField": "userAccount"
endDateField A date time field on the timesheet document. The timesheet document field for recording the end time of a time period.
Example:: "endDateField": "endDate"
name Any value written in camel case. Defines the name of the sc-time-recorder field in the document and database.
Example: "name": "testScTimeRecorder"
parentDocField A related document field on the timesheet document. The timesheet document field for recording the documentId of the parent document.
Example: "parentDocField": "workedOnTask"
timesheetTemplateId A template documentId. The documentId of the template used to create/update timesheet documents when the sc-time-recorder field is clicked.
Example: "timesheetTemplateId": "da802a90-e67a-11e6-a653-a97426fd3754"
startDateField A date time field on the timesheet document. The timesheet document field for recording the start time of a time period.
Example: "startDateField": "startDate"

2.3 Optional Customizable Fields

Field Valid Values Description
anyAccount true Removes the single account restriction on a timesheet record, allowing a different user to end a timesheet record than started it.
In this mode additional fields are added to the timesheet to track the user accounts that started & ended a timesheet record.
Example: "anyAccount": true
false Default value. Enforces the single account restriction on a timesheet record. The same user must open and close a timesheet record.
autoClosePrior true Allows automatic chaining of timesheet documents where an existing timesheet is ended when a subsequent timesheet is started.
This occurs for all parent documents created from the same base template by the same user.
Note: If "anyAccount": true, the autoClosePrior is ignored regardless of its value.
Example: "autoClosePrior": true
false Default value. No automatic chaining of timesheet documents.
fullWidth true The field displays full width on the form.
Example: "fullWidth": true
false Default value. The field does not display full width on the form.
linkDocument label The field label is displayed as a link to the underlying timesheet document.
start The underlying timesheet document pops up when the time recorder is started.
stop The underlying timesheet document pops up when a time recorder is ended.
both Combines the behaviour of start and stop.
Example: "linkDocument": both
never Default value. The field label is not displayed as a link to the underlying timesheet document.
label Any value Defines the field label for the sc-time-recorder field on the form.
Example: "label": "Test sc-time-recorder"
"name" field value Defaults to the value defined for the 'name' field, with the first letter displayed in upper case and any upper case letters displayed in lower case prefixed with an underscore.
Example: "Test_sc_time_recorder" is the default value if the "name" field value was "testScTimeRecorder".
mandatory true The field displays as mandatory (i.e. label in red text with an asterisk).
Saving without a value, a message prompts the user to enter a value for the mandatory field.
Example: "mandatory": true
false Default value. The field displays as optional (i.e. label in black text).
readOnly true The field is greyed out.
A Stop icon appears on mouseover.
The field cannot be activated.
Example: "enabled": false
false Default value. The field is not greyed out.
A Stop icon does not appear on mouseover.
The field can be activated.
relatedFields A set of field mappings A set of field mappings, each mapping a timesheet template field to a parent document field.
The values are set upon creation of a timesheet document.
Example:
"relatedFields": {
    "scTimeRecorderTestDescription": "testDescription",
    "parentDocumentId" : "documentId"
}
In this example, on clicking the time recorder field on the parent document:
1. A timesheet document will be created
2. The timesheet document field "timeRecorderTestName" will be set to the value of parent document field "timeRecorderTestDocument".
3. The timesheet document field "parentId" will be set to the value of parent document field "documentId".
visible false The field is not visible on the form.
Example: "visible": false
true Default value. The field is visible on the form.

 

3 Typical sc-text-box Definition

Below is a typical sc-text-box definition, defined with its required fields plus any optional field whose value is typically other than its default value.

{
    "componentName": "sc-time-recorder",
    "label": "sc-time-recorder Test",
    "name": "scTimeRecorderTest",
    "parentDocField": "workedOn",
    "accountDocField": "userAccount",
    "startDateField": "startDate",
    "endDateField": "endDate",
    "autoClosePrior":true,
    "timesheetTemplateId": "da802a90-e67a-11e6-a653-a97426fd3754"
}

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.

   "relatedFields": {
        "scTimeRecorderTestDescription": "testDescription",
        "parentDocumentId" : "documentId"
    },
    "readOnly":true,
    "mandatory": true,
    "visible":false,
    "anyAccount":true,
    "linkDocument":"label"

 

4 Examples

Example 1

sc-time-recorder with only its required system fields and required customizable fields defined.

Note: The timesheet template used by the sc-time-recorder field below to create/update timesheet documents is located at the end of this example.

        {
            "componentName": "sc-time-recorder",
            "label": "sc-time-recorder Test",
            "name": "scTimeRecorderTest",
            "parentDocField": "workedOn",
            "accountDocField": "userAccount",
            "startDateField": "startDate",
            "endDateField": "endDate",
            "timesheetTemplateId": "da802a90-e67a-11e6-a653-a97426fd3754"
        }

Resulting field on the form:

alt text

Resulting field on the form after clicking the time recorder field to start a time period & create a timesheet document

alt text

Resulting timesheet document:


    "userAccount": [
        {
            "name": "User Account - barry.eadie@fieldtec.com",
            "documentId": "b7c1e1b0-2b9f-11e6-ac9c-170c531a5a0c"
        }
    ],
    "workedOn": [
        {
            "name": "sc-time-recorder Test Document",
            "documentId": "8d071090-e688-11e6-b0ca-b969961fba08"
        }
    ],
    "startDate": "2017-01-30T01:08:24.406Z",
    "documentId": "996c2140-e688-11e6-b0ca-b969961fba08",

 

Resulting field on the form after clicking the time recorder field to stop the time period & update the timesheet document:

alt text

Resulting Timesheet Document:


    "userAccount": [
        {
            "name": "User Account - barry.eadie@fieldtec.com",
            "documentId": "b7c1e1b0-2b9f-11e6-ac9c-170c531a5a0c"
        }
    ],
    "workedOn": [
        {
            "name": "sc-time-recorder Test Document",
            "documentId": "8d071090-e688-11e6-b0ca-b969961fba08"
        }
    ],
    "startDate": "2017-01-30T01:08:24.406Z",
    "documentId": "996c2140-e688-11e6-b0ca-b969961fba08",
    "endDate": "2017-01-30T01:22:38.308Z"

Timesheet Template Definition used by Example 1

Below is the definition of the timesheet template (i.e. template with documentId "da802a90-e67a-11e6-a653-a97426fd3754") used by the above sc-time-recorder field to create/update timesheet documents.

{
    "formColor": "AliceBlue",
    "systemHeader": {
        "systemType": "template",
        "templateId": "54d96f610bc006eb84369a8b",
        "keyIds": [],
        "excludeGeneralSearch": false,
        "summaryName": "sc-time-recorder Test Template: TIMESHEET TEMPLATE",
        "createdWith": "54d96f610bc006eb84369a8b",
        "versionId": "53ed96d0-37b4-11e7-ab24-4d7404352287",
        "serverDate": "2017-05-13T08:15:29.981Z",
        "currentVersion": true,
        "createdDate": "2017-04-19T05:04:08.625Z",
        "createdBy": "b7c1e1b0-2b9f-11e6-ac9c-170c531a5a0c",
        "previousVersionId": "da83f380-37ad-11e7-ab24-4d7404352287"
    },
    "documentId": "da802a90-e67a-11e6-a653-a97426fd3754",
    "summaryNameRule": "sc-time-recorder Test Template Timesheet document",
    "appTags": [
        "formbird",
        "testTemplate",
        "testData"
    ],
    "components": [
        {
            "name": "appTags",
            "type": "Static Value",
            "value": [
                "formbird",
                "Test document",
                "sc-time-recorder Test Template Timesheet document"
            ]
        },
        {
            "label": "ID",
            "componentName": "sc-reference-no",
            "type": "Reference No",
            "name": "timesheetId",
            "format": "20YY-MM-DD (#)",
            "counterDocumentId": "8be7dec0-e6a5-11e6-8e4e-09fc4290540c",
            "counterFieldName": "timesheetIdCounter"
        },
        {
            "componentName": "sc-static-html",
            "type": "Custom",
            "fullWidth": true,
            "html": "<br/>"
        },
        {
            "label": "User Account",
            "componentName": "sc-related-document",
            "type": "Custom",
            "name": "userAccount",
            "enabled": false
        },
        {
            "label": "Worked on Task",
            "componentName": "sc-related-document",
            "type": "Custom",
            "name": "workedOnTask",
            "enabled": false
        },
        {
            "label": "Start",
            "componentName": "sc-date-time",
            "type": "Custom",
            "name": "startDate",
            "enabled": false
        },
        {
            "label": "End",
            "componentName": "gscbl-date-time",
            "type": "Custom",
            "name": "endDate",
            "enabled": false
        },
        {
            "componentName": "sc-text-box",
            "type": "Custom",
            "label": "sc-time-Recorder Test Description",
            "name": "scTimeRecorderTestDescription",
            "readOnly": true,
            "fullWidth": true
        },
        {
            "componentName": "sc-text-box",
            "type": "Custom",
            "label": "Parent Document ID",
            "name": "parentId",
            "fullWidth": true,
            "readOnly": true
        },
        {
            "componentName": "sc-note-box",
            "type": "Note Box",
            "label": "Timesheet Comments",
            "name": "timesheetComments",
            "fullWidth": true
        }
    ]
}