View source for Dictionary Creator

[[Main_Page|Main Page]]
__FORCETOC__
 Note: This page is under development and as such is not yet complete.
<strong>Dictionary Creator</strong>
<br>Collection dictionaries are made by account administrators from the ''Admin Portal'' in the ''Dictionary Creator'' main menu item. Here you can create, view and edit what data is collected and how it is collected.

[[File:Dictionary.png|none|800px]]


When you first navigate to the Dictionary Creator window you will see a drop-down menu which contains all of your collection dictionaries as well as an empty collection dictionary form. You can either start a new dictionary from scratch by typing in a name and adding new fields or modify an existing one by selecting it from the list '''(selecting the option of "-----" from the drop-down list will reset the Dictionary Creator for you)'''. 

<br>
=Dictionary Settings=
[[File:DC_DictOptions.png|thumb|none]]
[[File:DC_UpdateOrNew.png|thumb|none]]
===Saving Changes===
When you load an existing dictionary you will have both a <code>Duplicate/Create New</code> button and a <code>Save Changes</code> button. The ''Duplicate/Create New'' works like ''save as'' and will create a new dictionary with whatever name you have entered in the ''Dictionary Name'' box. ''Save Changes'' will save your changes to the existing dictionary.

If you have started from the blank template click the <code>Create New Dictionary</code> button after assigning a name (and sub-folder if desired) to create the dictionary.


===Dictionary Name===

[[File:Name.png|none| 600px ]]

Each dictionary needs a name. It is suggested to name each dictionary with the customer name and year. Where multiple dictionaries are used for the same customer those line or circuit names can be used as well.


===Sub Folder===
[[File:SubFolder.png|none| 600px ]]
Sub Folders are a great way to organize your collection dictionaries in the mobile app. This is optional and if not set here the dictionary will be shown in the main dictionary directory.

===Dictionary Order===
[[File:Order.png|none| 600px ]]
By default all dictionaries will be shown in the mobile app in alphabetical order. Normally this works but if you wish to specify the order manually the number you enter here will dictate the order shown when selecting a dictionary in the app.

===Default Search Field===
[[File:DC Default.png|none]]
The mobile app user has an option to search the existing collected records right from the device. While any field can be used for the search, the administrator has the option to set the default field for the search. To make things more efficient the most common search field can be set here (i.e. Pole Number).

 
A second use of this setting is for the map labels on the mobile app. Common fields used for this are the pole number or circuit number. 

If this setting is left blank (in the Dictionary Creator) simple map pins will be used.
[[File:Location.png|thumb|none]]

 It is possible for the mobile app user to temporarily change the label by using the search function for the field they wish to see on the map labels. The labels will reflect the most recent field used for the search during the current session. The next time the user opens the dictionary the labels will revert back to the default set in the Dictionary Creator.

===Field for Device Map===
In the [[https://wiki.goldenretrieverapp.com/index.php?title=Data_Management#Databases_Summary_Page Databases Summary Page]] it is possible to view on a map, the most recent record's GPS location for each device. By setting an inspector name instead of the id of the device, any change in phone/tablet will not effect this maps functionality.
===Duplicate Records Allowed===
By default saving changes as duplicate records is allowed. This is to avoid data loss due to editing mistakes. However, this does create more administration work later on to edit and consolidate these duplicates. By selecting this option no duplicates will be allowed by the mobile app for map markers once they turn from red to green. This is when working from a map of data supplied by the utility as this is location specific (Pole Number, etc makes no difference.
===Photo Required===
If a photo is required for every inspection record select this check-box to force a photo before the app will save a new record.


<br>

=Dictionary Fields=
==Default Dictionary Fields==
Golden Retriever uses several fields for every dictionary which are automatically completed by the system. These fields are shown in the Database view. They are:
*RecordNo - the record number assigned by the database when the record is uploaded
*Latitude - the latitude of the GPS location
*Longitude - the longitude of the GPS location
*Date - An automatic timestamp when the record is saved in the mobile app
*Device - The unique device id as supplied by the mobile device.
[[File:FieldType.png|none]]
<br>

==Optional Dictionary Fields==
In addition to the basic fields, you can define as many other fields as you wish. These custom fields will all be placed after the automatic fields.
===Add Field===
To add a new dictionary field click on the green <code>Add field here</code> button at the location you wish to add the field.
[[File:FieldAdd.png|none]]

[[File:DC_MoveField.png|thumb|none]]
===Position Field===
The fields will appear on the mobile app collection form according to the order they are in the Dictionary Creator. They can be Position by entering the desired position number in the box to the right of the green field box and clicking the <code>Position</code> button. The Dictionary Creator will automatically adjust all subsequent fields so there is no worry of overwriting a field.

===Delete Field===
[[File:DeletePosition.png|thumb|none]]
To delete a field click on the red '''X''' by the field. You will be asked to confirm before deletion. Once this is done it is final; there is no 'undo' option.

===Define Fields===
Several data collection field types are available. Once you add a new field, you first need to select the field type from the drop-down list. 
[[File:DropDown.png|none]]
====Define Field Type====
The first step is to select the field type from the dropdown list.
====Field Name====
This is the name which will be visible in the collection form on the mobile app. It will also be the column name in the online spreadsheet.
====Field Description====
This field description can be used to give more information for the end user (Mobile App user) as well as for anyone with a shared map link. This is an optional field attribute and may not be useful for all fields.
[[File:FieldDesc.png|none]]
The field types are grouped into categories and are as follows:
<br>
=====Classic Fields=====
======Comment======
This is a text field which always defaults to a blank value. Instructions may be added which show up when entering a new record (on the mobile app). This text does not show up in the final data.
[[File:Comments.png|none]]

======Picklist======
A drop-down list of values for the user to select. Click the <code>Add Picklist Option</code> as many times as necessary and type in the options you would like available to your users. Any unneeded picklist options may be deleted by clicking the red X to the right of the picklist option. 
[[File:Picklist.png|none]]
By default, the mobile app users may only select from the list. If desired you may allow custom entries by specifying a ''Length of Custom Entries'' value. The length value represents the maximum amount of characters they can use when creating a new picklist options. User-added picklist itmes will be recurring on the user's device (until they next refresh their dictionaries) but ''will not'' transfer to the dictionary or other devices. 

 Be careful what you wish for when opening up picklists to users. Whatever is inputted by the user will end up in the data. These entries will very easily include typo's and are bound to differ from user to user.

======Text======
This is one of the most common field types to use and while this is a 'simple text' field, there are several options available and some must be defined before your dictionary can be saved.
*<strong>Default Value</strong> - You may set a default value here. As users are entering records, the previous value will be transferred to the new record unless the ''Force Default'' checkbox is selected.
*<strong>Max Length</strong> - A maximum length must be set. A standard length length for text is 15 but can be shorter or longer. For a numeric field this number is how many characters are left of the decimal - the ''Number of Decimals Allowed'' setting will add to the maximum length.
*<strong>Min Length</strong> - An optional minimum length may also be set here.
*<strong>Max Value</strong> - A maximum value may be specified for numeric fields. For example, you may wish to disallow any pole year greater than the current year to minimize data entry errors.
*<strong>Min Value</strong> - A minimum value may be specified for numeric fields. For example, you may wish to disallow any pole year older than 1940.
*<strong>Number of Decimals Allowed</strong> - For numeric fields you may set the maximum number of decimals allowed. This is optional and may be left blank.
*<strong>Alphanumeric</strong> - You can set this to ''All Characters'' (including special characters), ''Letters and Numbers'', ''Numbers Only'' or ''Letters Only''. 
*<strong>GPS Data</strong> - In addition to the default GPS fields which Golden Retriever automatically collects you may specify GPS coordinate fields for navigation. When defining these fields set this option to either ''longitude'' or ''latitude''. Without defining this option Golden Retriever will not recognize this field as containing GPS coordinates and will not plot the pole locations on the navigation map.
*<strong>Capitalize</strong> - When an ''Alphanumeric'' option containing letters has been selected you may choose to have Golden Retriever automatically capitalize either the first letter of each word or all letters. This avoids inconsistent data in the final data. This option is not shown when ''Numbers Only'' is the selected ''Alphanumeric'' option.
*<strong>Increment</strong> - When you have selected ''Numbers Only'' as the ''Alphanumeric'' option you may set this number to increment up or increment down. This option is not shown when ''Numbers Only'' is not the selected ''Alphanumeric'' option.
*<strong>Barcode Scanning</strong> - Select this option to enable barcode scanning as the input method for this field.
*<strong>Make This A TimeStamp</strong> - 
*<strong>Always Locked</strong> - This prevents this field from being edited by the user.
[[File:Text.png|none]]
<br>

=====Modern Fields=====
======Attachment======
With Golden Retriever you are able to add pdf documents to the collection dictionary. This can give the mobile app user quick access to Safety Data Sheets, Product Labels, Instructions, etc. through a clickable link from within the collection record.
======Date Picker======
The Date Picker field will open up a calendar screen where the user can select a date. This is different from the automatic timestamp field for each record.
======Formula======
With the formula field you can enter an equation string that is evaluated in the app. To reference another field in the dictionary use the format <code>"~~Field Name~~"</code> (The quotes are important as ~~Field Name~~ will be replaced by the current value of the field).

{| class="wikitable" style="margin:auto"
|+ Operator Precedence
|-
! Operator !! Associativity !! Description
|-
| (...) || None || Grouping
|-
| f(), x.y, a[i] || Left || Function call, property access, array indexing
|-
| ! || Left || Factorial
|-
| ^ || Right || Exponentiation
|-
| +, -, not, sqrt, etc. || Right || Unary prefix operators (see below for the full list)
|-
| *, /, % || Left || Multiplication, division, remainder
|-
| +, - || Left || Addition, subtraction
|-
| ==, !=, >=, <=, >, <, in || Left || Equals, not equals, etc. "in" means "is the left operand included in the right array operand?"
|-
| and || Left || Logical AND
|-
| or || Left || Logical OR
|-
| x ? y : z || Right || Ternary conditional (if x then y else z)
|-
| = || Right || Variable assignment
|-
| ; || Left || Expression separator
|}

{| class="wikitable" style="margin:auto"
|+ Unary operators
|-
! Operator !! Description
|-
| -x || Negation
|-
| +x || Unary plus. This converts it's operand to a number, but has no other effect.
|-
| x! || Factorial (x * (x-1) * (x-2) * … * 2 * 1). gamma(x + 1) for non-integers.
|-
|abs x || Absolute value (magnitude) of x
|-
| acos x || Arc cosine of x (in radians)
|-
| acosh x || Hyperbolic arc cosine of x (in radians)
|-
| asin x || Arc sine of x (in radians)
|-
| asinh x || Hyperbolic arc sine of x (in radians)
|-
| atan x || Arc tangent of x (in radians)
|-
|atanh x || Hyperbolic arc tangent of x (in radians)
|-
| cbrt x || Cube root of x
|-
| ceil x || Ceiling of x — the smallest integer that’s >= x
|-
| cos x || Cosine of x (x is in radians)
|-
| cosh x || Hyperbolic cosine of x (x is in radians)
|-
| exp x || e^x (exponential/antilogarithm function with base e)
|-
| expm1 x || e^x - 1
|-
| floor x || Floor of x — the largest integer that’s <= x
|-
| length x || String or array length of x
|-
| ln x || Natural logarithm of x
|-
| log x || Natural logarithm of x (synonym for ln, not base-10)
|-
| log10 x || Base-10 logarithm of x
|-
| log2 x || Base-2 logarithm of x
|-
| log1p x || Natural logarithm of (1 + x)
|-
| not x || Logical NOT operator
|-
| round x || X, rounded to the nearest integer, using "grade-school rounding"
|-
| sign x || Sign of x (-1, 0, or 1 for negative, zero, or positive respectively)
|-
| sin x || Sine of x (x is in radians)
|-
| sinh x || Hyperbolic sine of x (x is in radians)
|-
| sqrt x || Square root of x. Result is NaN (Not a Number) if x is negative.
|-
| tan x || Tangent of x (x is in radians)
|-
| tanh x || Hyperbolic tangent of x (x is in radians)
|-
| trunc x || Integral part of a X, looks like floor(x) unless for negative number
|}

{| class="wikitable" style="margin:auto"
|+ Pre-defined functions
|-
! Function !! Description
|-
| random(n) || Get a random number in the range [0, n). If n is zero, or not provided, it defaults to 1.
|-
| fac(n) || n! (factorial of n: "n * (n-1) * (n-2) * … * 2 * 1") Deprecated. Use the ! operator instead.
|-
| min(a,b,…) || Get the smallest (minimum) number in the list.
|-
| max(a,b,…) || Get the largest (maximum) number in the list.
|-
| hypot(a,b) || Hypotenuse, i.e. the square root of the sum of squares of its arguments.
|-
| pyt(a, b) || Alias for hypot.
|-
| pow(x, y) || Equivalent to x^y
|-
| atan2(y, x) || Arc tangent of x/y. i.e. the angle between (0, 0) and (x, y) in radians.
|-
| roundTo(x, n) || Rounds x to n places after the decimal point.
|-
| map(f, a) || Array map: Pass each element of <code>a</code> the function <code>f</code>, and return an array of the results.
|-
| fold(f, y, a) || Array fold: Fold/reduce array <code>a</code> into a single value, <code>y</code> by setting <code>y = f(y, x, index)</code> for each element <code>x</code> of the array.
|-
| filter(f, a) || Array filter: Return an array containing only the values from <code>a</code> where <code>f(x, index)</code> is <code>true</code>.
|-
| indexOf(x, a) || Return the first index of string or array <code>a</code> matching the value <code>x</code>, or <code>-1</code> if not found.
|-
| join(sep, a) || Concatenate the elements of <code>a</code>, separated by <code>sep</code>.
|-
| if(c, a, b) || Function form of c ? a : b. Note: This always evaluates both <code>a</code> and <code>b</code>, regardless of whether <code>c</code> is true or not. Use <code>c ? a : b</code> instead if there are side effects, or if evaluating the branches could be expensive.
|}

{| class="wikitable" style="margin:auto"
|+ Constants
|-
! Constant !! Description
|-
| E || The value of E 
|-
| PI || The value of PI
|-
| true || Logical true value
|-
| false || Logical false value
|}
<br><br>

======Picklist - Multiple Selection======
A multiple-selection picklist allows for multiple choices. This is used for dictionary fields where you need to record multiple things, if they exist. This data is stored in a text field similar to a notes field and ''can not'' be used for any show/hide rules.
======Signature======
The signature field allows for signature collection using the device's touchscreen. This is most useful when customizing a collection dictionary as for ''Tailgate safety meetings'' and for other administrative tasks. Due to crews being spread out it can be difficult to distribute forms to the crews and to receive the completed forms back. Golden Retriever can be used as a tool to aid in this by creating specific dictionaries.
======Spacer======
The spacer is not a data field but a horizontal line which is displayed in the mobile app to visually separate different categories of fields in the collection form. Use of this is completely voluntary.
======Weather======
When a user taps this field in the mobile app, while conducting the inspection, the current weather conditions will be recorded in the inspection record. Golden Retriever is also often used by vegetation control companies to record their herbicide mixing and application - in which weather plays a large role.
<br>
=====Calculator Fields=====
Golden Retriever has two pole strength calculator fields available. One based on the RUS Tables and one on the ANSI remaining strength tables. These can be used by field personnel to help determine pole integrity. Both calculator fields allow the author of the dictionary to set fields to pull data from as well as fields to record the results.
======RUS Deduction - RUS Tables======
======Strength Calc - ANSI Tables======
<br>
Golden Retriever has remaining strength calculations for symmetrical decay (internal and external) based on the ANSI tables. This field can be set up to pull information from other fields as well as record all data used for the calculations in a comment or text field. The image below shows assigned fields for most of the required information.
[[File:StrengthTest.png|none]]
Any information not automatically imported into the calculation will need to be added when the calculation popup is shown. Once the user taps the <code>CALCULATE</code> button the remaining strength values are recorded into the ''Remaining Strength'' field as well as the data used for the calculation into an assigned field.


<br>This information can be accessed later by engineering staff either through the Admin Portal or from downloaded data.
<br>
<br>'''Online View'''
[[File:StregthCalc_OnlineData.png|none|border]]
<br>
'''Spreadsheet View'''
[[File:StrengthCalc_Data.png|none|border]]

=====Monitoring Fields=====
======Altered Data======
This is a hidden field from the mobile app user and will record any changes made to the original utility supplied data (as seen by the app users in the map or online search function).
======Custom GPS======
Normally, if the mobile device is unable to obtain a GPS lock the user will be presented with a pop-up stating ''Could not get a GPS lock. Do you wish to wait?''. With this field, which is hidden from the collection screen, the user will be given the option to manually enter the GPS coordinates in addition to waiting.
======Elevation======
Elevation is a hidden field (hidden from the mobile app user) and is automatically populated during the inspection. It can be set to Metric (metres) or Imperial (feet).
<br>
=====Utility Pole Fields=====
For convenience Golden Retriever has some predefined pick lists for common utility pole inspection fields.
======Class======
A picklist of pole classes (1-10 and H1-H6). Once selected the list may be modified for your specific use by adding, deleting or editing any of the picklist items.
======Height======
A picklist of pole heights (lengths) from 15 to 120 in increments of five. Once selected the list may be modified for your specific use by adding, deleting or editing any of the picklist items.
======Manufacturer======
A very extensive picklist of current and historical pole manufacturers. Once selected the list may be modified for your specific use by adding, deleting or editing any of the picklist items.
======Species======
A picklist of common utility pole species. These are the common abbreviations for the species names (ie. WC - Western Cedar, SP - Southern Yellow Pine). Once selected the list may be modified for your specific use by adding, deleting or editing any of the picklist items.
<br>

==Field Options==
Once you have selected the field type, all of it's options will be displayed. Assign a name to it and complete any field options.
Most fields have four basic options.
[[File:DC_FieldOptions.png|thumb|none]]
===Required Field===
If the required checkbox is selected, this field must be completed for the record to save.
===Hidden Field===
Is the field visible on the mobile app. Sometimes it makes sense to pass data through to the final reports without cluttering up the field user's screen.
===Lock From Search===
If this is a field that will contain utility supplied data that the mobile app should never need to change, select this option. If the mobile app user doesn't need to see the data, use a Hidden Field instead.

===Force Default===
''Text'' and ''Single select Picklists'' can have default values assigned. If the ''Force Default'' is selected, whatever is in the default value box (can be left blank) is pre-populated in the collection form . Otherwise whatever has been entered in the previous record will copy to the new record - this is good for fields such as ''line'' or ''circuit'' number which do not change often.
<br>
===Show/Hide Field===
[[File:Hide.png|none]]
To keep collection forms easier to navigate hiding certain fields if unneeded can be beneficial. For example, different collection data is required for poles than for meters if both are being inspected. For this to work all possible combinations must be defined - if the picklist you are referencing has five different options then all five must be accounted for. When you are setting this up there is an option ''everything else'' which can be used to save time. Once the dictionary is saved this will be filled out ''long hand'' and show all combinations.
[[File:DC_ShowHideExample.png|none]]
 Note: Failure to account for all options will lead to inconsistent results.
<br>

===Require Photo===
Sometimes a photo is required only when a certain condition is met. This can be set here.

==Upload Supplied Data==
When asset location and other details are supplied by the utility this information can be uploaded into the collection dictionary to give a map of the assets to be inspected (if GPS locations are included in the data) and/or simply provide a local database of data that can be searched using the magnifying glass button in the app.
When uploading data into a dictionary it is important that the required field names match. Keep these things in mind:
*Latitude field ''should'' be named <strong>Y</strong> and must be set to the GPS Data type of 'Latitude'
*Longitude field ''should'' be named <strong>X</strong> and must be set to the GPS Data type of 'Longitude'
[[File:other.png|none]]
*Field names are ''not'' case sensitive. As well, spaces and special characters are also ignored.
 i.e. ''Pole Number'', ''POLE NUMBER'', ''pole number'', ''Pole_Number'', ''PoleNumber'' are all exactly the same and therefore considered duplicates
*Do not include these field names as they are reserved by the system
**RecordNo
**Latitude
**Longitude
**Date
**Device

*By default, Golden Retriever sets all supplied coordinates to a Red map marker and completed ones as Green. You may alternately set other colors by defining them (by number) in a '''MapColor''' field in your csv file. Green is 'reserved' for completed records. Red, Blue, Purple, Yellow and Orange are currently the other colors available for the 'TO DO' map markers. These are set in the csv which contains the utility supplied data. To accomplish this, add a field (csv only and ''not'' in the Dictionary Creator) called '''MapColor''' and identify the requested color by its number:
** '''0''' - Red
** '''1''' - Green (It is not recommended to use green markers)
** '''2''' - Blue
** '''3''' - Purple
** '''4''' - Yellow
** '''5''' - Orange
[[File:GR MapMarkerColors2.jpg|none|thumb]]

 Note: The colors do not show the same on iOS and Android - the colors shown here are how they display on Android.



 Note: the file must be a ''CSV'' (comma delimited and enclosed with double quotes), any coordinates must be in ''WGS84 format (EPSG:4326)'', and the column names must match the columns in the dictionary for them to be used by the program.
[[File:DC_UploadCSV1.png|thumb|none]]
Once the file has successfully been uploaded the Local Database will show is ''Database Uploaded''. The csv can be removed at any time by clicking the red ''click to unassign'' link.
You can verify all fields with data by looking for the ''Note: field exists in uploaded database'' (in red) statement, located immediately under the Field Name.
[[File:DC_CSVUploaded.png|thumb|none]]
<br>
[[File:DC_UploadCSV2.png|none]]
 Note: For instructions on how to extract pole data from a Utility supplied ''shapefile'' and other QGIS specific functions [[QGIS#Exporting_a_csv_for_Golden_Retriever_from_utility_supplied_shapefile|follow these instructions]].

Once you have uploaded the csv file and saved the dictionary, the data will be available on the mobile app once dictionaries are refreshed. 
 ''If the poles do not show up in the expected location on the mobile app's map it is most likely due to incompatible GPS coordinates. Confirm that they have been supplied to Golden Retriever in <strong>EPSG:4326, WGS 84</strong>.''

=Assign Dictionary=
For Administrators working with multiple Golden Retriever accounts you may assign/unassign collection dictionaries as needed. Select the checkbox beside the account(s) you wish to have access to the dictionary - both on mobile app and in the [[https://wiki.goldenretrieverapp.com/index.php?title=Data_Management#Databases_Summary_Page Dictionary Summary]] page of the Admin Portal.
[[File:DC_Assign.png|thumb|none]]