sc-time-recorder
This document is a user guide for the sc-time-recorder component version 5.25, released October 31, 2019.
1 Purpose
sc-time-recorder places a time recorder field on a form, allowing a logged in user to record periods of time against the document displayed on the form. The time recorder field displays as a switch with an indication of whether it is on or off i.e. whether a time recorder is currently running or not running. To record a time period, the logged in user simply clicks the time recorder field to start a running time recorder, then clicks it again to stop the running time recorder. This will result in the creation of a timesheet document which records at a minimum, the following information:
- Start time of a time period.
- End time of a time period.
- A link to the parent document (i.e. the document currently displayed on the form containing the time recorder field).
- A link to the either the logged in user's Account document or if configured, to one of their Group Account documents (see Note 2 below).
For example, to record the periods of time spent working on a task, a time recorder field would be placed on the Task form. Then for each time period a logged in user spends on a Task displayed on the form, clicking the time recorder field will start/stop a running time recorder and create a timesheet document, one for each time period. Each timesheet document will record at a minimum the 4 pieces of information listed above.
Note:
-
The parent document must first be created in order to link timesheet documents to it. Until then, the time recorder field on a form is disabled.
-
A time recorder field can be defined to link its timesheet documents to either the logged in user's Account document or if configured, to one of their Group Account documents. A Group Account document is used to group user Accounts in order to broaden the number of users who can view, start or stop a particular time recorder field.
A description of Group Accounts, their usage and how to implement them can be found in Section 3.3.
-
A particular user's abilty to view, start or stop a particular time recorder field is dependent on how their user Account has been configured and on how that time recorder field has been defined.
Section 3 Time Recorder Matching provides a detailed description of how Formbird determines whether a time recorder field on a form matches a particular user's defined usage of it.
The sc-time-recorder definition provides fields for setting the properties of a time recorder 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:
-
Default values for fields described in the tables below are shown in bold text.
-
Below are the meanings of some of the terms found within this document:
- A "parent document" is a document displayed on the form containing a time recorder field.
- A "timesheet document" is a document created and linked to the parent document as a result of using the time recorder field to record a time period.
- A "running time recorder" refers to a timesheet document that has been started but not yet ended.
- A Formbird user's Account is defined by 3 documents, an "Account" document and its two child documents, the "Account Control" and "Account Security" documents.
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 | The name of a related document field on the timesheet document. | The name of the related document field on a timesheet document for recording the documentId of the logged in user's Account document or if configured, the documentId of one of their Group Account documents. Example: "accountDocField": "account" |
endDateField | The name of a date time field on the timesheet document. | The name of the date time field on a timesheet document 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 | The name of a related document field on the timesheet document. | The name of the related document field on a timesheet document 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. Example: "timesheetTemplateId": "da802a90-e67a-11e6-a653-a97426fd3754" |
startDateField | The name of a date time field on the timesheet document. | The name of the date time field on a timesheet document for recording the start time of a time period. Example: "startDateField": "startDate" |
2.3 Optional Customizable Fields
Field | Valid Values | Description |
---|---|---|
anyAccount | Refer to Section 3 Time Recorder Matching for a detailed description of how this and four other optional fields are used to determine whether a time recorder matches a particular user's usage of it i.e. whether a particular user is allowed to view, start or stop a time recorder for the parent document displayed on a form. Note: If "anyAccount": true , then the groupAccountField , "groupAccountControl" , "groupFilterField" and "autoClosePrior" fields are ignored regardless of their value. It is recommended that "anyAcount" should not be used together with any of these 3 fields. |
|
true | Removes the Account Matching rule from the time recorder matching process. Hence, provided all other matching rules are met, this will allow any user Account to view, start or stop a time recorder for the parent document displayed on the form. This will also allow a different user Account to stop a running time recorder than started it. Refer to Section 3.5 for a full description of time recorder matching with "anyAccount" .Example: "anyAccount": true |
|
false | Default value. Does not remove the Account Matching rule from the time recorder matching process. |
|
autoClosePrior | Refer to Section 3 Time Recorder Matching for a detailed description of how this and four other optional fields are used to determine whether a time recorder matches a particular user's usage of it i.e. whether a particular user is allowed to view, start or stop a time recorder for the parent document displayed on a form. Note: If "anyAccount": true , then the groupAccountField , "groupAccountControl" , "groupFilterField" and "autoClosePrior" fields are ignored regardless of their value. It is recommended that "anyAcount" should not be used together with any of these 3 fields. |
|
true | When the user starts a time recorder for the parent document displayed on the form, then any existing time recorders running in the background for other parent documents and which meet certain rules will be automatically stopped with notifications of their state change posted. Refer to Section 3.2 for a full description of time recorder matching with "autoClosePrior" .Example: "autoClosePrior": true |
|
false | Default value. When the user starts a time recorder for the parent document displayed on the form, then any existing time recorders running in the background for other parent documents will not be automatically stopped. | |
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. | |
groupAccountField | Refer to Section 3 Time Recorder Matching for a detailed description of how this and four other optional fields are used to determine whether a time recorder matches a particular user's usage of it i.e. whether a particular user is allowed to view, start or stop a time recorder for the parent document displayed on a form. The function "groupAccountField" field is to link a time recorder's timesheet documents to a Group Account rather than an individual's user Account. This will allow any user whose user Account is configured as linked to that Group Account, to view, start or stop a time recorder for the parent document displayed on the form.A user's Account can be linked to one or more Group Accounts via a related document field on either their Account document or their Account Control document. If the related document field is defined on the user's Account document then define the time recorder with the groupAccountField field set to the name of the related document field in their Account document.If the related document field is defined on the user's Account Control document then define the time recorder with the below groupAccountControlField field set to the name of the related document field in their Account Control document.Note: If "anyAccount": true , then the groupAccountField , "groupAccountControl" , "groupFilterField" and "autoClosePrior" fields are ignored regardless of their value. It is recommended that "anyAcount" should not be used together with any of these 3 fields. |
|
The name of a related document field on the user's Account document. | The name of a related document field on a user's Account document and whose value is an array of zero, one of more linked Group Account documents. Each Group Account document identifies a group account that the user account is linked to and can be selected and used to start a time recorder. The resulting timesheet document will be linked to the selected Group Account document. If a logged in user's Account is linked multiple Group Accounts then the time recorder field will display multiple instances of the time recorder switch (one for each Group Account) allowing the user to select which switch to start or stop. Refer to Section 3.3 for a full description of time recorder matching with "groupAccountField" .Example: "groupAccountField": "workCrew" |
|
IF a time recorder field on a form is defined without the groupAccountField or groupAccountControlField fields OR the logged in user Account document is not linked to a Group Account, then by default, its resulting timesheet documents will be linked to the logged in user Account document. This means a running time recorder's timesheet document can only be ended by the user Account that started it. |
||
groupAccountControlField | Refer to Section 3 Time Recorder Matching for a detailed description of how this and four other optional fields are used to determine whether a time recorder matches a particular user's usage of it i.e. whether a particular user is allowed to view, start or stop a time recorder for the parent document displayed on a form. The function "groupAccountControlField" field is to link a time recorder's timesheet documents to a Group Account rather than an individual's user Account. This will allow any user whose user Account is configured as linked to that Group Account, to view, start or stop a time recorder for the parent document displayed on the form.A user's Account can be linked to one or more Group Accounts via a related document field on either their Account document or their Account Control document. If the related document field is defined on the user's Account document then define the time recorder with the above groupAccountField field set to the name of the related document field in their Account document.If the related document field is defined on the user's Account Control document then define the time recorder with the groupAccountControlField field set to the name of the related document field in their Account Control document.Note: If "anyAccount": true , then the groupAccountField , "groupAccountControl" , "groupFilterField" and "autoClosePrior" fields are ignored regardless of their value. It is recommended that "anyAcount" should not be used together with any of these 3 fields. |
|
The name of a related document field on the user's Account Control document. | The name of a related document field on a user's Account Control document and whose value is an array of zero, one of more Group Account documents. Each Group Account document identifies a group account that the user account is linked to and can be selected and used to start a time recorder. The resulting timesheet document will be linked to the selected Group Account document. If a logged in user's Account is linked multiple Group Accounts then the time recorder field will display multiple instances of the time recorder switch (one for each Group Account) allowing the user to select which switch to start or stop. Refer to Section 3.3 for a full description of time recorder matching with "groupAccountControlField" .Example: "groupAccountControlField": "workCrew" |
|
IF a time recorder field on a form is defined without the groupAccountField or groupAccountControlField fields OR the logged in user Account document is not linked to a Group Account, then by default, its resulting timesheet documents will be linked to the logged in user Account document. This means a running time recorder's timesheet document can only be ended by the user Account that started it. |
||
groupFilterField | Refer to Section 3 Time Recorder Matching for a detailed description of how this and four other optional fields are used to determine whether a time recorder matches a particular user's usage of it i.e. whether a particular user is allowed to view, start or stop a time recorder for the parent document displayed on a form.br /> The "groupFilterField" works in conjunction with the "groupAccountField" field or the "groupAccountControlField" field. Note: If "anyAccount": true , then the groupAccountField , "groupAccountControl" , "groupFilterField" and "autoClosePrior" fields are ignored regardless of their value. It is recommended that "anyAcount" should not be used together with any of these 3 fields. |
|
The name of a related document field on the same form as the time recorder field. | Filter a user's array of linked Group Accounts to just those in the filtering field. The filtering field being a related document field located on the same form as the time recorder field. Hence only those Group Accounts that are in both the user's array of linked Group Accounts and in the filtering field can be used to view, start or stop a time recorder for the parent document displayed on the form. Refer to Section 3.4 for a full description of time recorder matching with "groupFilterField" .Example "groupFilterField": "ownerIntray" |
|
Defaults to no filtering is applied to the user's array of linked Group Accounts. | ||
label | Any value | Defines the name of the sc-time-recorder field on the form i.e. the field label. Example: "label": "Test sc-time-recorder" |
Defaults to no field label is displayed. | ||
linkDocument | icon | When the time recorder is started, the link document button displays to the right of the time recorder field. The link document button remains visible while the time recorder is on. Clicking the link document button opens the underlying timesheet document in a pop-up dialog. Clicking the pop-up close button closes the pop-up dialog. Example: "linkDocument": "icon" |
start | When the time recorder is started, the link document button displays to the right of the time recorder field and the underlying timesheet document opens in a pop-up dialog. The link document button remains visible while the time recorder is on. Clicking the pop-up close button closes the pop-up dialog. Clicking the link document button re-opens the underlying timesheet document in a pop-up dialog. Example: "linkDocument": "start" |
|
stop | When the time recorder is started, the link document button displays to the right of the time recorder field. The link document button remains visible while the time recorder is on. Clicking the link document button opens the underlying timesheet document in a pop-up dialog. Clicking the pop-up close button will close the pop-up dialog. When the time recorder is stopped, the underlying timesheet document opens in a pop-up dialog. Example: "linkDocument": "stop" |
|
both | Combines the behaviour of start and stop. Example: "linkDocument": "both" |
|
never | Default value. The link document button does not display to the right of the time recorder field i.e. the button to manually open the underlying timesheet document is not provided. | |
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). | |
noMatchViewing | Refer to Section 3 Time Recorder Matching for a detailed description of how this and four other optional fields are used to determine whether a time recorder matches a particular user's usage of it i.e. whether a particular user is allowed to view, start or stop a time recorder for the parent document displayed on a form. Works in conjunction with the "linkDocument" field. |
|
true | Overrides the default behaviour of a time recorder that does not meet any of the time recorder matching scenarios discussed in Section 3 Time Recorder Matching. Refer to Section 3.6 for a detailed description of "noMatchViewing": true |
|
false | Default value. Refer to Section 3.6 for a detailed description of "noMatchViewing": false |
|
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": { "scTimeRecorderTestTemplateTestDescription": "timesheetTestDescription", "scTimeRecorderTestTemplateSelectedColour" : "timesheetSelectedColour" } 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 timesheetTestDescription will be set to the value of parent document field scTimeRecorderTestTemplateTestDescription .3. The timesheet document field timesheetSelectedColour will be set to the value of parent document field scTimeRecorderTestTemplateSelectedColour . |
visible | false | The field is not visible on the form. Example: "visible": false |
true | Default value. The field is visible on the form. |
3 Time Recorder Matching
Time tecorder matching is the process of determining if a time recorder field on a form matches a user's allowed usage of it, in particular:
-
Should that user be able to view the time recorder field and its current state (i.e. on or off).
-
Should that user be able to start or stop the time recorder field.
- When that user starts the time recorder for the parent document displayed on a form, which if any existing time recorders running in the background for other parent documents should be automatically stopped.
A user's allowed usage of a time recorder field on a form can be influenced by:
- Configuring their user account to be linked to zero, one or more group accounts.
- Defining the time recorder field with zero, one or more of the following optional fields:
autoClosePrior
(discussed in Section 3.2)groupAccountField
orgroupAccountControlField
but not both. (discussed in Section 3.3)groupFilterField
(discussed in Section 3.4)anyAcount
(discussed in Section 3.5)noMatchViewing
(discussed in Section 3.6)
3.1 Fundamental Time Recorder Matching
Fundamental time recorder matching involves checking if a running time recorder's timesheet document meets the following 3 rules:
-
templateId Match: The running time recorder's timesheet document must have been created using the template defined in the time recorder's
timesheetTemplateId
field.I.e. The time recorder's
timesheetTemplateId
field and the running time recorder's timesheet document'stemplateId
field must have the same value. ` -
documentId Match: The running time recorder's timesheet document must be linked to the parent document displayed on the form.
I.e. The parent document's
documentId
field and the running time recorder's timesheet document'sparentDocField
field must have the same value. -
account Match: The running time recorder's timesheet document must be linked to the logged in user's account document or to one of their group account documents.
I.e. The logged in user's account document's
documentId
field or one of their group account document'sdocumentId
field and the running time recorder's timesheet document'saccountDocField
field must have the same value.
When a running time recorder's timesheet document meets all 3 of the above rules, then it is considered to match the logged in user's usage of it. As a result, the time recorder field on the form will be displayed to the user with a state of 'On' (i.e. running) and they will be able click the time recorder field to stop the running time recorder.
When a running time recorder's timesheet document does not meet all 3 of the above rules, then it is considered to not match the logged in user's usage of it. As a result, the time recorder field on the form will be displayed to the user with a state of 'Off' (i.e. not running). Clicking the time recorder field will start a new running time recorder i.e. create a new timesheet document and link it to parent document displayed on the form and to the logged in user's account document.
3.2 Time Recorder Matching with "autoClosePrior"
When a time recorder field is defined with an "autoClosePrior"
field, the 3 fundamental time recorder matching rules (i.e. templateId Match, documentId Match, account Match) as described in Section 3.1 will still determine if that time recorder matches a particular user's allowed usage of it. Hence the autoClosePrior
field does not alter a particular user's usage of a time recorder field on a form i.e. their ability to or not to view, start or stop a time recorder for the parent document displayed on the form remains unchanged.
However, when a time recorder is started for the parent document displayed on a form, the function of autoClosePrior
is to determine if any existing time recorders running in the background for other parent documents should be automatically stopped.
When "autoClosePrior": true
and a time recorder is started for the parent document displayed on a form, then any existing time recorders running in the background that were found to only meet fundamental time recorder matching rules 1 and 3 (i.e. templateId Match and account Match) will be automatically stopped and notifications of their state change posted. These will be those time recorders running in the background that:
-
Were created using the template defined by the time recorder's
timesheetTemplateId
field.I.e. Rule 1(templateId Match) is met
-
And whose timesheet document is linked to the logged in user's account document. I.e. Rule 3 (account Match) is met
-
But whose timesheet document is linked to a parent document other than the parent document displayed in the form. I.e. Rule 2 (documentId Match) is not met
The default value for "autoClosePrior"
is false
.
When "autoClosePrior": false
and a time recorder is started for the parent document displayed on a form, then any existing time recorders running in the background that only meet fundamental time recorder matching rules 1 and 3 (i.e. templateId Match and account Match) will not be automatically stopped.
Note:
- If
"anyAccount": true
, then thegroupAccountField
,"groupAccountControl"
,"groupFilterField"
and"autoClosePrior"
fields are ignored regardless of their value. It is recommended that"anyAcount"
should not be used together with any of these 3 fields.
3.3 Time Recorder Matching with "groupAccountField"
or "groupAccountControlField"
When a time recorder field is defined with a "groupAccountField"
or a "groupAccountControlField"
field, the fundamental time recorder matching rules 1 and 2 (i.e. templateId Match, documentId Match) as described in Section 3.1 still apply but rule 3 (account Match) is modified so as to broaden the number of users who can view, start or stop a time recorder for the parent document displayed on the form.
The function of a "groupAccountField"
or a "groupAccountControlField"
field is to link a time recorder's timesheet documents to a Group Account document rather than a user Account document. This will allow any user Account that is linked to that Group Account, to view, start or stop a time recorder for the parent document displayed on the form.
A user's Account can be linked to one or more Group Accounts via a related document field on either their Account document or their Account Control document.
To link a user Account to one or more Group Accounts:
-
Define a Group Account template and use it to create the required Group Account documents.
-
Add a related document field to either the user Account template or Account Control template.
-
Use the related document field from step 2 to link each user's Account to zero, one or more group Account documents. For example, users belonging to the same work crew would have their user Account linked to the Group Account document created for that work crew.
Whereas a supervisor responsible for multiple work crews would have their user Account linked to multiple Group Account documents, thus providing the supervisor with the ability to view, start or stop a time recorder on behalf of the work crews they are responsible for.
If the requirement of particular time recorder field is to have its timesheet documents linked to a Group Account then define it with a "groupAccountField"
field (if in step 2, the related document field was added to the user Account template) or with a "groupAccountControlField"
field ( if in step 2, the related document field was added to the user Account Control template). Set the value of the field to the name of the related document field in step 2.
Example:
Requirement
A company has 2 work crews (Crew A and Crew B) each consisting of 3 workers (A1, A2, A3 and B1, B2, B3 respectively) plus a supervisor (S1) who is responsible for both work crews. Time periods spent spent working on a Task need to be recorded at the work crew level rather than at the individual worker level.
Solution
-
Create 2 Group Account documents, one for Crew A and one for Crew B.
-
Add a suitable named related document field (e.g.
"workCrew"
) to say the user Account document template. -
For workers A1, A2 and A3, configure their Account document's
"workCrew"
field with 1 related document: Crew A's group account document. For workers B1, B2 and B3, configure their Account document's"workCrew"
field with 1 related document: Crew B's group account document.For the supervisor S1, configure their Account document's
"workCrew"
field with 2 related documents: Crew A's Group Account document and Crew B's Group Account document. -
Define the time recorder field on the Task form with:
"groupAccountField": workCrew
"accountDocField": "account"
Resulting Behaviour
If say user A1 starts the time recorder field on the Task form, the resulting timesheet document will be linked to the Crew A's Group Account document rather than A1's individual Account document.
If say user B2 starts the time recorder field on the Task form, the resulting timesheet document will be linked to the Crew B's Group Account document" rather than B2's individual Account document.
As a result:
- For users A1, A2, and A3 the Task form will display a time recorder field for Crew A with a status of "on". Only users A1, A2, A3 and S1 will be able to stop this running time recorder.
- For users B1, B2, and B3 the Task form will display a time recorder field for Crew B with a status of "on". Only users B1, B2, B3 and S1 will be able to stop this running time recorder.
- For user S1 the Task form will display a time recorder field for Crew A with a status of "on" and a time recorder field for Crew B with a status of "on". Supervisor S1 will be able to stop either of these 2 running time recorders.
IF a time recorder field on a form is defined without the groupAccountField
or groupAccountControlField
fields OR the logged in user Account document is not linked to a Group Account THEN by default, its resulting timesheet documents will be linked to the logged in user Account document. This means a running time recorder's timesheet document can only be ended by the user Account that started it.
Note:
- If
"anyAccount": true
, then thegroupAccountField
,"groupAccountControl"
,"groupFilterField"
and"autoClosePrior"
fields are ignored regardless of their value. It is recommended that"anyAcount"
should not be used together with any of these 3 fields.
3.4 Time Recorder Matching with "groupFilterField"
The "groupFilterField"
works in conjunction with the "groupAccountField"
field or the "groupAccountControlField"
field.
When a time recorder is defined with a "groupFilterField"
, the user's array of linked Group Accounts will be filtered to just those in a filtering field. The filtering field being a related document field located on the same form as the time recorder field.
This means if the contents of the filtering field changes, then time recorder matching may evaluate to a different result due to the change in filter criteria. Hence a time recorder that displayed as "Off" prior to the change may display as "On" after the change and vice versa.
3.5 Time Recorder Matching with "anyAccount"
When a time recorder field is defined with "anyAccount": true
, the fundamental time recorder matching rules 1 and 2 (i.e. templateId Match, documentId Match) as described in Section 3.1 still apply but rule 3 (account Match) is removed thus removing user checking from the time recorder matching process. Hence provided fundamental time recorder matching rules 1 and 2 are met, this will allow:
- Any user Account to view, start or stop a time recorder for the parent document displayed on the form.
- A different user Account to stop a running time recorder than started it.
In this mode additional fields are added to the timesheet to track the user Accounts that started & ended a timesheet document.
The default value for the "anyAccount"
is false
. When a time recorder field is defined with "anyAccount": false
, all 3 fundamental time recorder matching rules (i.e. templateId Match, documentId Match, account Match) as described in Section 3.1 will still determine if that time recorder matches a particular user's allowed usage of it.
Note:
- If
"anyAccount": true
, then thegroupAccountField
,"groupAccountControl"
,"groupFilterField"
and"autoClosePrior"
fields are ignored regardless of their value. It is recommended that"anyAcount"
should not be used together with any of these 3 fields.
3.6 Time Recorder Matching with "noMatchViewing"
When a time recorder does not meet any of the time recorder matching scenarios discussed above, the default behaviour is to display the time recorder with a status of "off" and allow the user to start a new running time recorder for the parent document displayed on the form. This then becomes it's own running time recorder and has it's own matching rules.
When a time recorder does not meet any of the time recorder matching scenarios discussed above, then "noMatchViewing": true
:
- Allows the user to view the time recorder field and its current state (i.e. "on" or "off").
- Does not allow the user to start or stop a running time recorder for the parent document displayed on the form.
- If the
"linkDocument"
field has been configured to display the link document button, then clicking it allows the user to view but not change the details of a running time recorder's timesheet document.
When a time recorder does not meet any of the time recorder matching scenarios discussed above, then "noMatchViewing": false
, being the default value, will result in the above default behavour.
4 Typical Definition
Below is a typical sc-time-recorder 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": "workedOnTask",
"accountDocField": "account",
"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.
"anyAccount":true,
"fullWidth":true,
"groupAccountField": "workCrew",
"groupAccountControlField": "workCrew",
"groupFilterField": "ownerIntray",
"linkDocument":"icon"
"mandatory": true,
"noMatchViewing": true,
"readOnly":true,
"relatedFields": {
"scTimeRecorderTestTemplateTestDescription": "timesheetTestDescription",
"scTimeRecorderTestTemplateSelectedColour": "timesheetSelectedColour"
},
"visible":false
5 Examples
Note: The timesheet template shown in Section 5.2 is used by each of the examples below i.e. each sc-time-recorder field is defined with "timesheetTemplateId": "da802a90-e67a-11e6-a653-a97426fd3754"
5.1 Example 1
sc-time-recorder defined with the typically needed fields.
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": "Test sc-time-recorder",
"name": "testScTimeRecorder",
"parentDocField": "workedOnTask",
"accountDocField": "account",
"startDateField": "startDate",
"endDateField": "endDate",
"autoClosePrior":true,
"timesheetTemplateId": "da802a90-e67a-11e6-a653-a97426fd3754"
}
Resulting field on the form:
Resulting field on the form after clicking the field to start a time period & create a timesheet document
Resulting timesheet document:
"userAccount": [
{
"name": "User Account - barry.eadie@formbird.com",
"documentId": "b1c1e1be-2b7f-11e6-ac9c-1234c531a5a0c"
}
],
"workedOnTask": [
{
"name": "sc-time-recorder Acceptance Test Result: Wed Nov 06 2019 00:35:04 GMT+1100 (AEDT)",
"documentId": "8d071090-e688-11e6-b0ca-b969961fba08"
}
],
"startDate": "2019-11-05T13:36:00.756Z",
"documentId": "996c2140-e688-11e6-b0ca-b969961fba08",
Resulting field on the form after clicking the field to stop the time period & update the timesheet document:
Resulting Timesheet Document:
"userAccount": [
{
"name": "User Account - barry.eadie@formbird.com",
"documentId": "b1c1e1be-2b7f-11e6-ac9c-1234c531a5a0c"
}
],
"workedOnTask": [
{
"name": "sc-time-recorder Acceptance Test Result: Wed Nov 06 2019 00:35:04 GMT+1100 (AEDT)",
"documentId": "8d071090-e688-11e6-b0ca-b969961fba08"
}
],
"startDate": "2019-11-05T13:36:00.756Z",
"documentId": "996c2140-e688-11e6-b0ca-b969961fba08",
"endDate": "2019-11-05T13:51:33.418Z"
5.2 Timesheet Template Definition
Below is the definition of the timesheet template (i.e. template with documentId "da802a90-e67a-11e6-a653-a97426fd3754") used by each of the examples to create/update timesheet documents.
{
"formColor": "#ededed",
"systemHeader": {
"systemType": "template",
"templateId": "54d96f610bc006eb84369a8b",
"keyIds": [],
"excludeGeneralSearch": false,
"summaryName": "sc-time-recorder Test Data: Timesheet Template",
"createdWith": "74746c80-8378-11e6-99b1-71ee944cf59f",
"versionId": "b98512a0-e4cf-11e9-9f36-db7d1b314bd7",
"serverDate": "2017-05-15T05:27:04.571Z",
"currentVersion": true,
"createdDate": "2019-10-02T04:47:23.338Z",
"createdBy": "b1c1e1be-2b7f-11e6-ac9c-1234c531a5a0c",
"summaryDescription": "Timesheet Template da802a90-e67a-11e6-a653-a97426fd3754 used by sc-time-recorder Test Template to create Timesheet documents",
"serverUpdatedDate": "2019-10-02T04:47:25.427Z",
"serverCreatedDate": "2019-10-02T04:47:25.427Z",
"previousVersionId": "7349f260-e4cf-11e9-9f36-db7d1b314bd7"
},
"documentId": "da802a90-e67a-11e6-a653-a97426fd3754",
"summaryNameRule": "sc-time-recorder Test Data Timesheet document",
"appTags": [
"formbird",
"testData",
"barryTestDataTemplate",
"sc-time-recorder Test Data Timesheet template"
],
"components": [
{
"componentName": "sc-static-html",
"fullWidth": true,
"html": "<div class='well well-sm' style='font-weight:bold; border-radius: 4px 4px 4px 4px;background:blue;;color:white;margin-bottom: 0;'><span style='margin-left:0px'>sc-time-recorder Test Template: TIMESHEET TEMPLATE</span></div>"
},
{
"name": "appTags",
"value": [
"formbird",
"Test document",
"testResultDocument",
"barryTestResultDocument",
"sc-time-recorder Test Result Timesheet document"
],
"componentName": "sc-static-value"
},
{
"componentName": "sc-reference-no",
"counterFieldName": "testCounter",
"counterDocumentId": "e70cca50-ab3d-11e8-9ba5-71cd0b2b7b3d",
"format": "20YY-MM-DD (#)",
"name": "timesheetId",
"label": "Timesheet ID"
},
{
"componentName": "sc-static-html",
"html": "<br/>",
"fullWidth": true
},
{
"label": "Task",
"componentName": "sc-related-document",
"name": "workedOnTask",
"enabled": false
},
{
"label": "Account",
"componentName": "sc-related-document",
"name": "account",
"enabled": false
},
{
"label": "Started",
"componentName": "sc-date-time",
"name": "startDate",
"enabled": false
},
{
"componentName": "sc-date-time",
"enabled": false,
"name": "endDate",
"label": "Ended"
},
{
"componentName": "sc-static-html",
"fullWidth": true,
"html": "<br/><br/><div style='font-weight:normal; font-size:1.25em;color:black;'>The following two fields are populated if the 'sc-time-recorder Test Template' includes them in a relatedFields property of the sc-time-recorder definition.</div><br/>"
},
{
"componentName": "sc-text-box",
"label": "Test Description",
"name": "timesheetTestDescription",
"fullWidth": true,
"readOnly": true
},
{
"componentName": "sc-text-box",
"label": "Selected Colour",
"name": "timesheetSelectedColour",
"fullWidth": true,
"readOnly": true
}
],
"hideCommandBar": true,
"summaryDescriptionRule": "sc-time-recorder Test Template {{{documentId}}} Timesheet document"
}