Quick Data Configuration

Transcription

1 Enviance Data Forms 17-2 Quick Data Main App Setup 17-2 Permissions 17-3 Form Configuration File 17-4 Copy Configuration 17-5 Configuration File Settings and Options 17-5 Header 17-5 Form Settings 17-5 Field Settings 17-6 Insert Values Data Tab Configuration Data Entry Setup Quick Data Custom Fields Requirements for Quick Data Fiscal Year and Quarter Configuration User Access & Security Locking Data Quick Data Documents Configuration Quick Data Reports Configuration Quick Links for Quick Data Enviance Quick Data allows users to enter data of different types quickly without having to navigate the main application. The following features are available in Quick Data: Data: The Data tab can be configured for entering parameter data for regular monthly, quarterly or yearly periods. The prior period's data is displayed for comparison. Users may set the end month for the year or quarter when the calendar year or quarter does not apply. Data Forms: The Data Forms tab can used to enter data in table form for multiple parameters at any specified date/time. Data may also be entered for associated Data Quality fields. Related non-numeric data may be entered at the same time and stored in a manual event log in the system. The tab may also be used to enter only event log data, in the same manner as a manual Event Log in the main application. Documents: The Documents tab allows users to access documents stored in the Enviance Platform. Reports: The Reports tab allows users to view cached reports and run pre-configured reports stored in the Enviance Platfomr. Quick Links: Create Quick Links for easy access to Quick Data pages with pre-configured filters. 17-1

2 Data Forms Data Forms in Quick Data are configured in the Enviance main application with a manual Event Log and its monitored requirements. Event fields may also be used to store non-numeric data related to the data entry. The Event Log fields will be displayed on the page along with the numeric data table. However, it is important to note that, as the Event Log is manual and not automatic, only one event record is created for the whole data set entered at one time on the page. The data points and the event record will have the same date time stamp. You may also use configure the Data Forms tab to enter only Event data through the event log fields. Only one event record can be created at a time (the same as data entry for a manual Event Log through the main application). Access to data forms is controlled through the permissions on the Event Log and the monitored requirements. To view data forms, users must have a minimum of Enter Data permission. To configure data forms, user must be a member of the Administrators group. Quick Data Main App Setup Permissions Form Configuration File Copy Configuration Configuration File Settings and Options Quick Data Main App Setup Data Forms in Quick Data are configured in the Enviance main application with a manual Event Log and its monitored requirements. The custom fields on the Event Template are the non-numeric fields that will be presented on the form. Parameters that are associated with the Event Log as monitored requirements define the data that is available for entry in the data grid. Calculated requirements associated with the Event Log are shown as view-only data. One Non-Numeric Requirement should be associated with the Event Log for the purpose of associating event instances. The event instance contains the custom fields completed at data entry. Note: If there is more than one Non-Numeric Requirement associated with the Event Log, instances will be associated with the last Non-Numeric Requirement alphabetically. If there is no Non-Numeric Requirement associated with the Event Log, instances will be associated with the last Numeric Requirement alphabetically. There is 17-2

3 Enviance 9.1 no method for choosing the requirement to associate with an instance through Quick Data. To set up the Data Form for Quick Data: 1. Create an Event Template with the custom fields that are to be available for entry on the form. Note: The following custom field types are not supported and will not be displayed on the form: Calculated Numeric, Hyperlink and Citation Hyperlink fields. 2. Create one Non-Numeric Requirement to associate with the Event Log. 3. Create a manual Event Log and associate the Event Template. The location and name of the Event Log will be used in Quick Data to select the appropriate form. The Facility drop-down shows the System Model tree path, and the Source drop-down shows the name of the Event Log. 4. The monitored requirements should include the Non-Numeric Requirement, the Parameters to be presented for data entry on the form, and any Calculated Requirements you want to display as view-only data on the form. Each data entry page will be saved as one event instance with the custom fields on the Event Template. If there is more than one Non-numeric Requirement, the event instance will be associated with the last one listed alphabetically. The Begin and End dates for the event instance are determined by the Navigation date on the form. The Non-Numeric Requirement itself does not display on the Quick Data form. System Variables and Material Activity Calculated Requirements are not supported and will not be displayed. 5. Grant permissions to the users who will need to access the forms and enter data. Permissions Users need View, Enter and Edit Data permission on the Event Log, its parent POI, and its monitored Requirements to access the form. Typically granting this permission to the POI will do, if all components are under the same POI; if the monitored requirements are in a different location, ensure that users also have this permission on the requirements. Users must be home users of the target system. Summary of functional permissions required in Quick Data Forms tab: Function To view, enter or edit data To mark data Complete To unlock data marked Complete To edit the configuration file Permission View, Enter and Edit Data View, Enter and Edit Data Full Control Must be a member of the Administrators group 17-3

4 Form Configuration File After the Event Log has been set up in the main application, log into Quick Data to view and configure the Quick Data data form. Note: To configure Quick Data data forms a user must be a member of the Administrators group. You must also access Quick Data as a home user of the target system. Steps to configure the Quick Data form: 1. Log into Quick Data and select the Data Forms tab. You can also go directly to the Data Forms tab with the following url: 2. Select the Facility and Source from the dropdown lists. The form will be displayed with the default configuration. The data grid appears first, followed by the custom fields associated with the Event Template. 3. Select the Configuration link. (This link only displays for Administrators). The configuration file is displayed in an editable text form. If no prior configuration has been done, the default configuration file is presented. Each requirement and custom field presented on the form has a separate definition section. 4. Edit the file to change the settings for each field as desired.you may edit the file directly or copy the file to a text file for editing, then paste it back when you are done. The file format is in YAML, a human-readable data serialization language. No prior knowledge of the language is requiredare For standard file settings and field options, see Configuration File Settings and Options. The structure, including syntax and indentations, must be strictly maintained. However, you can easily edit values. You can also cut and paste sections to change the order of fields in the form. The order the fields are shown in the configuration file is the order in which they will be displayed. Use spaces, not tabs, for indentation. If you edit the file in another application, be sure that you do not introduce tabs or other characters. You may also copy the configuration from an existing source, if the requirements and custom fields are identical. See Copy Configuration. 5. After editing the configuration file as desired, click Save. Quick Data validates the file in two steps: 1. Confirms the structure of the YAML file. If the structure is not correct, an error message is returned. 2. Confirms the options are valid and the settings are correct. If the settings or options are not correct, an error message is returned. If the file format and settings are correct, the configuration file will be saved. 17-4

5 Enviance 9.1 Copy Configuration You can copy the configuration file from an existing source (event log) to another source which has identical monitored requirements. The monitored requirements are matched by requirement name (since the GUIDs will not match). If more than one match for a requirement name is found, a warning is displayed, but the copy will continue and match the requirements in the order found. To copy a configuration: 1. Select the Facility and Source to which you want to copy a configuration. 2. Select the Configuration link. 3. Select Copy. 4. Select the Facility and Source from which you want to copy the configuration. 5. Click Copy. Any errors or warnings will be shown. If a requirement or field is not found, the configuration will not be copied for that field. If more than one match is found, only the first will be used. If there are fields in the "copy to" source for which no match is found, you will need to add these fields manually to the configuration file. 6. Click Save to save the configuration file. Configuration File Settings and Options A sample configuration file is provided that contains examples of settings and the required syntax for various field types. Download the text file to view and copy the syntax. Sample Configuration File (.txt file) Header The header shows: name of the Event Template, path and name of the Source, name of the Event Template, as in the following example: --- # # The configuration file configures to YAML 2.1 standards # Last Edited by User LName on # QD-Water [Event Template] # Enviance Home (Demo)\DMR Demo\Outfall 002 [Source] # Water Analyses [Event Log] Form Settings The first three lines in the configuration file after the header set the options for the page. This includes the date format, which determines how data may be entered, and the display mode, which specifies how data is displayed for entry. NavigationDate : month year date datetime DisplayEventAs : form DisplayNumericsAs : grid form 17-5

6 NavigationDate determines the date format on the page and also affects when the data will be stored. Options for the Date display are: Year: User selects the year only. Data entry grid corresponds to the months in the year, with 12 data rows. Data is stored on the first day of each month at 12:00 AM. Month (default): User selects month and year. Data entry grid corresponds to the days in the month (28-31 days). Data is saved at 12:00 AM on each day. Date: User selects day, month and year. Data entry grid corresponds to the hours in the day, with 24 data rows from 12:00 AM to 11:00 PM. Datetime: User may select day, month, year and time (to the minute). Optionally, user may also select an event instance end date. Data entry grid shows one row for data entry with Complete Date same as the selected Navigation Date. The display mode determines the entry format presented to the user, with options for displaying event custom fields and numeric data. Form: Each field with value entry box is presented on a separate line. Grid: In this mode (available for numerics only), numeric fields are presented in a table grid. Event custom fields will appear in form mode below the grid. Note: If you are using Quick Data for data entry for a manual event log, with no numeric requirements, use DisplayNumericsAs: form to hide the grid. An example of the page form settings is shown below. Values in red must not be edited. Values in green may be edited. Example of Page Form Settings: NavigationDate : month DisplayEventAs : form DisplayNumericsAs : grid Field Settings The basic format to define a numeric requirement, with possible attributes and values, is shown in the example following. Fields : # Requirement Name - Id : 16c08ffa-5d ed-de8127c2f44d Type : Requirement MandatoryValidations: Type: DataType : Number Message : "* Must be number" Range: Minimum : "10" Maximum : "100" Message : "Valid range 10 to 100 (inclusive) 17-6

7 Enviance 9.1 OptionalValidations: Required: ToSave : Yes ToComplete : Yes Message : "* Required" MaxDecimalPlaces: Value : 2 # integer Message : "Maximum decimal places 2" Range: Minimum : "10" Maximum : "100" Inclusive : Yes Message : "Valid range 10 to 100 (inclusive);" AdminNotes : "Today is [Insert Date]" Values in red should not be edited. Values in green may be edited. Attibutes and values in blue are optional elements that may be added. # indicates a comment. The format to define a custom field, with possible attributes and values, is: # [Custom Field Name] - Id : 16c08ffa-5d ed-de8127c2f44d Caption : CustomField Caption Type : CustomField MandatoryValidations: Type: DataType : Text # UDF field type Message : "Must be [type]" MaxCharacterLength: Value : Message : "Limited to [x] characters" OptionalValidations: Required: ToSave : Yes ToComplete : Yes Message : "* Required" DefaultValue : "text value" Hidden : Yes Level : 0 # optional; may use 1, 2 or 3 for display emphasis. Default is 0. Data Quality (DQT) fields are defined along with the requirement to which they apply. The same attributes and values as custom fields may be applied. AdminNotes may include instructions for DQT fields, but they must be part of the requirement definition; they are displayed in the right panel below the DQT section and above validation messages. A sample format for a numeric requirement with DQT fields is: Fields : # BOD5 - Id : 16c08ffa-5d ed-de8127c2f44d Type : Requirement MandatoryValidations: 17-7

8 Type: DataType : Number Message : "Must be number" AdminNotes : "If below detectable value, substitute.5 detectable value" DQTFieldOptions: # Detection Limit - ID : d d-4efb-aca1-05blad DefaultValue : 1.5 Hidden : False Keywords and options are described in the following table. Note: 1- Configuration keys are case-sensitive. Values are not. 2- Use spaces, not tabs for indentation. 3- Indentations are required as indicated for sub-keys. True/False values for keys: True values are: 1, Y, yes, true False values are: 0, N, No, false Key : Values # Requirement or Custom Field name - ID : [ComplianceObject].[GUID] or [UDF].[GUID] Caption : Custom field Caption property Hidden : Yes No Description Beginning of field definition GUID of object in database. Caption for custom field. Default is as defined in database, but may be edited for QuickData display. Caption is displayed to user on the UI in place of Name for all custom fields. Determines if the field will be displayed on the UI. If a required field is hidden it must have a default value. DefaultValue : "value" The default value to insert in the field when the form loads. Default value may be set for either a numeric or text field. When the field is hidden, the default value is inserted and saved along with the rest of the data. The default value can use Insert Values to insert the current user's name, the current Date or DateTime). Mandatory Validations: Type: Mandatory validations are the restrictions set on the field in Enviance. Only the message may be edited. 17-8

9 Enviance 9.1 Key : Values DataType : Number Date DateTime Message : "[Number Date DateTime] required" Range: Minimum : [value] Description Inclusive indicates whether the valid range includes or excludes the minimum and maximum values. Character limits on text boxes are small=20, medium=50, large=7990. Maximum : [value] Inclusive : Yes No Message : "Valid range x to y (inclusive)" MaxCharacterLength: Value : Message : "Limited to x characters" Optional Validations: Type: DataType : Number Date DateTime Message : "Number Date DateTime required" Range: Minimum : [value] Maximum : [value] Inclusive : Yes No Message : "Valid range x to y (inclusive)" MaxDecimalPlaces : One or more optional validations to be performed, with an optional message (up to 50 characters) to be displayed on the form. DataType validations allow you restrict data entry types on text fields. Maximum and Minimum values restrict user data entry. Inclusive indicates whether the valid range includes or excludes the minimum and maximum values. MaxDecimalPlaces requires user to truncate entry to given decimal places. Value :[value] Message : "Restrict to x decimals" MaxCharacterLength: Value : [value] Required: ToSave prevents user from saving without a value in the field. Required: ToComplete prevents user from marking data Complete without a value. 17-9

10 Key : Values Description Message : "Limited to x characters" Required: ToSave : Yes No ToComplete : Yes No Message : "* Required" Level : 0, 1, 2, 3 0 = Default text (normal black text on light background) 1 = bold white text on bold background color 2 = bold black text on medium background color 3 = bold white text on dark background color Does not apply to numeric fields displayed in grid form. AdminNotes : "field notes" May be used to add notes (such as user instructions). AdminNotes can include Insert Values to insert the current user's name, the current Date or DateTime). Insert Values The following Insert Values may be applied to the values for keys Messages, DefaultValue, and AdminNotes: [Insert DateTime] YYYY-MM-DD HH:MM:SS Example: :22:12 [Insert Date] YYYY-MM-DD Example: [Insert User] UserFirstName UserLastName Example: # Comments - Id : 16c08ffa-5d ed-de8127c2f44d Caption : Comments Type : CustomField MandatoryValidations: 17-10

11 Enviance 9.1 MaxCharacterLength: Value : 7990 DefaultValue : "[Insert User] said on [Insert Date]:" When the page loads, the user's first and last name and the date are inserted, for example: "John Smith said on :" Data Tab Configuration The Data tab in Enviance Quick Data allows users to enter periodic data in an easy-to-use form. Once the data has been validated, it can be locked so that further editing is disabled, preventing inadvertent changes. (If necessary, data can still be edited by logging into the Enviance Platform.) The following section explains how to set up the Enviance Platform for data entry using the Data tab. The setup involves the use of specific custom fields on the system objects you want to expose in the Data tab. Data Entry Setup Quick Data Custom Fields Requirements for Quick Data Fiscal Year and Quarter Configuration User Access & Security Locking Data Data Entry Setup To view and enter data on the Data tab in Enviance Quick Data, the following elements are required: Custom Field Template with Quick Data fields Properties defined on numeric requirements, to include Quick Data fields, Active Dates and Periodicity. Summary of objects and custom fields to apply: POI Object type Custom Fields, Notes Optional: QuickData Previous Default: Text, dropdown list with two values: Previous Period, Previous Year QuickData Data Collection Period: Text, dropdown list, with three values: Monthly, Quarterly, Annually Parameter QuickData Source (text, dropdown list, any values) Calculated Requirements (for display 17-11

12 Object type only) Custom Fields, Notes QuickData Sort Order (number, text box) Active Date (filters display of requirements for data entry; if null, displays for all available dates) Periodicity (values: Monthly, Yearly or Quarterly) Controls when data entry is allowed. Non-numeric requirement One NNR is required in the same location as the data entry parameters in order to display Data Lock and Comments box. Properties are not important. Quick Data Custom Fields 1. Create the following custom fields. The naming convention is important. The Name (id value) must be exactly as specified: QuickData Source: Text/Dropdown list. List values may be anything that reflects your monitoring categories. QuickData Sort Order: Number/Text box QuickData Previous Default: Text/Dropdown list. Two list values: Previous Period and Previous Year. QuickData Data Collection Period: Text/Dropdown list. Three list values: Monthly, Quarterly, Annually 2. Create two Custom Field Templates and add these fields. Template 1 for Numeric Requirements: Add the following fields to be applied to the requirements: QuickData Source and QuickData Sort Order. Template 2 for POI (optional fields): Add the following field to be applied to the POI: QuickData Previous Default and QuickData Data Collection Period. You may use the same template for both the requirements and POI, but the fields will only be relevant according to the object type to which they are applied. If the objects already have a Custom Field Template, you can add the QuickData fields to that template. The template names are not important. Requirements for Quick Data The following requirements can be set up for access through the Data tab in Enviance Quick Data: Parameters for which you want to allow users to enter data. Calculated requirements: Calculated data that you want to be visible (not editable) One non-numeric requirement (optional) to enable the data lock feature and allow comments to be added

13 Enviance 9.1 To set up the requirements to be accessed through the Data tab in Enviance Quick Data: 1. Apply a Custom Field Template with the fields QuickData Source and QuickData Sort Order to the requirements. 2. Set the following properties on each requirement: Active Date: Earliest date for which you want to allow data entry. The requirement will not be shown for data entry before this date. If no date is entered, data entry will be allowed for any date available in the date dropdown (currently monthly from Jan 2002). (Inactive date can also be used to disable data entry after a set date.) In addition, the Active and Inactive Dates on the parent object can be set to control data entry access to all child requirements. The active date on the parent is checked first, then the active dates on the child requirements. The active date on the parent object will override any active dates set on the children when deciding whether to display the requirements or not. Periodicity: This setting is optional. You may use either the QuickData Data Collection Period on the POI to set the periodicity for all requirements or the periodicity field on the requirements. If no value is set for that POI custom field, or the field is not present, set periodicity for each requirement individually. For monthly data, enter 1 Month. For yearly data, enter 1 Year. For quarterly data, enter 1 Quarter. If the periodicity is 1 yr, the monthly selection will be disabled and by default the last month of the year will be selected (by default, December, but fiscal year end may be configured differently from the Data tab in Quick Data). For period of 1 yr, the data point is stored at 1200AM on the last day of the last month of the year. For monthly or quarterly periods (or if periodicity is not defined), one data entry field is available for each month; the data point will be stored at 1200 AM on the last day of the appropriate month. Note: Periodicity setting for all requirements will be ignored if the field QuickData Data Collection Period is present on the POI in the system and has a value. Unit of Measure: A value (any value) must be selected for the requirement to appear on the Enter Data tab. QuickData Source: A value in this field (any value) will expose the requirement to the Quick Data page. If there is no value, the requirement will not be displayed in Quick Data. Quick Data Sort Order: Numeric value, which determines the order of appearance in the list shown on the Data tab. If none is entered, or there are conflicts, sorting will be alphabetical

14 3. To add Comments box and Data Lock checkbox, create a Non-Numeric Requirement under the same POI as the requirements. You can name it QuickData for identification; however the name is unimportant and no properties are required. (A Custom Field Template is also not necessary.) The mere existence of the NNR causes a Comments box and a Data Lock checkbox to appear in the page, below the data entry fields for the requirements. The Comment and Data Lock features are optional. However, the data lock feature adds extra security, as it ensures that once data has been validated and locked, it cannot be edited further from the Data tab in Enviance Quick Data by anyone. (Data can still be edited from the Enviance 17-14

15 Enviance 9.1 Platform if necessary. This is not to be confused with the data lock feature in the main application.) Important: For this feature to work properly, there should be only one NNR under the parent object, which is used exclusively for Enviance Quick Data. If there is more than one NNR, multiple Comment boxes and data lock checkboxes will be displayed, with the risk of overwriting or corrupting data already stored by existing NNRs. 4. Apply the Custom Field Template that contains the fields QuickData Previous Default and QuickData Data Collection Period to the parent POI of the requirements. QuickData Previous Default: Default value to show in the Previous data column. Choice may be toggled from the user data entry screen. Previous Period shows the last data entry for the parameter (previous month, quarter or year, depending on the frequency of data entry). Previous Year's Month shows the data for the same month last year. (In the case of yearly data entry, this is the same as the Previous Period.) QuickData Data Collection Period: Sets the data collection period (annually, monthly or quarterly) for all requirements under the POI. If a value is present, any Periodicity values on the individual requirements will be ignored

16 Fiscal Year and Quarter Configuration If the yearly or quarterly data collection period does not conform to the standard calendar periods, you will need to change the designated end month from the Quick Data page. To change the end month for annual or quarterly data: 1. In Quick Data on the Data tab, click Configuration. (You must have admin rights to access this link.) 2. Set the Annual or Quarterly period, depending on your data entry configuration. For annual data entry, select the Annual End month. This setting only applies if the collection period is annually. For quarterly data entry, select the First Quarter End month. This setting only applies if the collection period is quarterly. 3. Click Save. Confirm by clicking OK. Click the Back link to return to data entry. Note: The Annual End and First Quarter End months set via the Configuration link are system settings and will apply to all QuickData pages for the system. It only needs to be set once on a QuickData page to apply to all other pages. (This has no value in the main application, however, which allows for data entry at any date/time.) User Access & Security To view or enter data on the Data tab in Enviance Quick Data, users must have the following minimum permissions: View Data: Allows users to see but not edit data values. View, Enter and Edit Data on the requirements, including the non-numeric requirement used for data lock and comments. (Permissions may be inherited from the parent object.) Note: Users must be Home users of the system they need to enter data for. There is no method for changing system models from Enviance Quick Data. The Active/Inactive Dates on the facility and requirements also control what users see. Locking Data The lock checkbox on the data entry page may be used to lock data once it has been validated. The lock checkbox is an optional feature which can be set up using a non-numeric requirement, as explained in the setup instructions. To lock data: 1. Select the month and year to display the data for the selected period. 2. Check the "lock" box at the bottom. Then click Save

17 Enviance 9.1 Once the data set has been locked, the data may not be edited from the Quick Data interface. If necessary, the data may be edited from the main application. You may also reset the lock from the main application so that users may edit the data from Quick Data. To reset the lock: 1. In the Enviance main application, find the non-numeric requirement used to configure the Quick Data page. 2. Right click the requirement and choose Data > Enter/Edit. Select the data point whose date corresponds with the data you want to unlock. 3. Click Delete. The lock box on the Quick Data page will now be unlocked and users may edit the data from Quick Data. Note: The Quick Data lock box is unrelated to the data lock feature in the main application and applies only to the Quick Data interface. Quick Data Documents Configuration The Enviance Quick Data Documents tab allows users to access documents stored in the Enviance Platform quickly and easily from Quick Data without the need to log into the main application and navigate the Documents library. It is designed to be used for documents that may be directly related to data entry and forms completion in Quick Data. To make documents available from Quick Data: 1. Create a Documents folder with the name: QuickData Support Documents 2. Upload the desired documents to this folder, or copy/move documents from elsewhere in the Documents library. 3. Grant document Read permissions to the users who need to access each document. Permissions must be granted to each document. Only those documents for which the user has been granted permissions will be shown in the Documents tab in Enviance Quick Data. Quick Data Reports Configuration The Enviance Quick Data Reports tab allows users to access reports stored in the Enviance Platform quickly and easily from Quick Data without the need to log into the main application and navigate the Reports library. To make reports available from Quick Data: 1. Create a Reports folder with the following name: QuickData Reports 17-17

18 2. Create your Quick Data reports in this folder, or copy/move reports from elsewhere in the Reports library. 3. Grant the appropriate report permissions to the users who will be running the reports. Only those reports for which the user has been granted permissions will be shown in the Reports tab in Enviance Quick Data. Quick Links for Quick Data You can create Quick Links to Quick Data pages which include pre-configured filter criteria. These links can then be used on dashboards to allow easy access from the Enviance main application. To create Quick Links to Quick Data, users must have the Manage Quick Links right. Quick Links created from Quick Data are saved as Shared Quick Links. To be available to users, they must then be published to users or used on a Shared Quick Links panel on a distributed dashboard. To create a Quick Link to Quick Data: 1. Make your filter selections for the page. For example, on the Data Forms tab, choose the facility for which you want to enter data. 2. Click Add Quick Link. 3. Enter a name for the Quick Link (the link name as it will appear on your dashboard). Then click OK