Entities, contexts, usage and languages

DiversityCollection may be used in diverse contexts like collection management, observations or field mapping. To ensure that a user working in a certain area will see the descriptions corresponding to his domain the DiversityWorkbench provides the possibility to define corresponding contexts.

To set the context and the language for the program choose Administration - Customize display … from the menu. A window will open as shown below where you may select the language and the context which should be used. By default the language will be set according to the settings of your operating system, however, you may change it here. The default language within DiversityCollection is English. If you select a certain context, the tables in the lower part of the form will show you the special setting within this context. These settings are edited as described below.  

For the documentation of the tables used for the storage of the entity related data please see the section Entity tables.

To edit the entities choose Administration - Application description … from the menu. A window will open as shown below where you may edit the entities defined for the program.

Group for the display of the entity

If in a user interface certain entities should be displayed in a group, enter the name of the group here. 

Usage

If nothing is defined for the usage of an entity, it will be handled according to the rights of the user. In certain context an entity may be set to e.g. read only, inapplicable or not used. In case of the later two possibilities the entity will not appear in the interface of the program. For example, transaction management (e.g. loan) will not be handled with a mobile device, thus the corresponding entities will be set to “not used”. Use the [Insert new usage] button to insert a new usage for an entity. To edit the possible usages choose Administration - Usage … from the menu.

• inapplicable: An entity which may not be applied in a certain context will not be shown in a user interface, e.g. the depositors accession number in the context observation. 
• preset: An entity will have a preset value, e.g. ‘determination’ for the identification category in the context observation.
• read only: An entity may not be changed.
• hidden: An entity should be hidden from the user interface.   

Context

The default context is General. Thus, in the beginning you will find all representations within this context. Within the representation, when a certain context is missing, the program will search for a representation in the parent context until a representation is found. To edit the context choose Administration - Context … from the menu. A window will open as shown below where you may edit the context.

Representation

An entity may have differing representations in different contexts. For example a CollectionEvent may correspond to an observation or gathering in other contexts. Use the Entity and Representation menu to fill in missing entries. If an only if entity should receive a different title or description in the user interface, enter the values in the table. If nothing is defined in a certain context, the program will walk up the tree defined with the parent code (see the image above) to find available values for the title or description of the entity. The highest entry in the hierarchy is the context General with the language English. If you define deviating values for the display text, the abbreviation or the description, you must at least enter values in the highest entry (General, English) as a default value for all other entities. 

Language

TThe default language used in DiversityCollection is English. Thus, in the beginning you will find all descriptions etc. in English. All representations may be defined for any language. Use the Representation menu to automatically fill in missing entries of a language. If there are changes in the original description of tables or columns in the database, choose

Representation - Update descriptions according to database/strong> from the menu to import the updated descriptions for the English version and context “General”.

Entity

To insert missing entities use the Entity menu. To insert all missing tables of a database choose Entity - Insert all missing tables … from the menu. A window will open listing the missing tables. Use the [Exclude: … ] field and [Requery] button to remove certain tables from the list, e.g. if you do not wish to define entities for log tables, enter *_log and then click [Requery]. You may repeat this until the list contains only tables you wish to use.

You find corresponding functions for single tables and for entries in a table. The later function is restricted to tables with a primary key with one column. A window will open where you map the columns, provided for the entity documentation to columns in the table, of which you wish to import the entries (see image below).

This may be necessary, if e.g. certain entries in a table should not be used in a certain context or if you wish to translate the contents into another language. 

Customize main window

Customize the main form

The main window can be customised in several parts. To change the visible parts in the main window select Administration - Customize display … from the menu. A window (see below) will open where you can select the groups which should be displayed. In the first tab you can change the visibility for the taxonomic groups and material categories.

In the second tab (see below) you can set

• visibility of the localisation systems displayed in a distribution map
• the localisation systems available for the selection in the drop down menus
• the collection site properties available for the selection in the drop down menus
• the source for the country list from a gazetteer
• the direction of the hierarchy derived from a gazetteer and written into the cached value representing the gazetteer entry
• the separator in the hierarchy derived from a gazetteer and written into the cached value representing the gazetteer entry

Defaults and miscellaneous

In the third tab (see below) you can add the name of the responsible person or choose the current user for several entries and show/hide the controls for the exsiccata.

Timeout

The timeout for web resources and databases either added manually or via linked server can be set to adapt to the velocity of the available net. If you set the Timeout for web response to 0, the application will ignore any resources retrieved from the web. By default these values are set to 30 seconds This is demonstrated in a short tutorial .  

Responsible

You can choose to either use the current user or a specified user as a responsible for new datasets for various tables (see image above).

Storage location

The source for the list for the storage location can be set as shown below:

• Taxonomic names from identifications within the selected specimen
• Storage locations already entered for the parts within the collection where the part is stored
• Storage locations already entered for the parts within the whole database

Template copy mode

There are 3 possibilities:

• Copy values from the template only if there are no entries in the data
• Ask the user if there are differing contents in data and template whether the template values should be copied into the data
• Copy the values from the template irrespective of any content in the data

Subcollection content

The display text for the content of the subcollection can be composed of the fields listed below:

• Accession number of the specimen
• Accession number of the part
• First identification of the first organism
• Storage location of the first part
• Locality of the collection event
• Collection date

The maximal content of a subcollection can be restricted hire for new parts can set here as well.

The default collection for new parts can set here as well.

Miscellaneous

Use translations: If the data fields for the exsiccatal series should be displayed.

Show exsiccata: If the data fields for the exsiccatal series should be displayed.

Show accepted names: With this option the names linked to DiversityTaxonNames will be checked for the synonymy status. Accepted names will be shown with a green color and for synonyms the accepted name will be displayed above the current name (see below).    

Show valid names: With this option the valid names linked to DiversityAgents will be shown. Valid names will be shown with a green color and will be displayed above the current name.

Scan DiversityDescriptions: If accessible DiversityDescriptions databases should be scanned for links to the current dataset.

Load datasources: If the datasources on linked servers should be loaded together with the start of the programm.

Autocompletion

Use autocompletion for all textboxes: Available in upcoming version - If this option is choosen, textboxes will autocomplete starting with the specified text length.

You can choose the mode of the autocompletion. There are 4 options:

• Node: No autocompletion
• Append: Append the first fitting entry
• Suggest: Provide a list corresponding to the typed text
• Suggest & Append: Provide a list corresponding to the typed text and append the first fitting

Query

The set the option for optimized queries and the option to remember the query settings as default, select the Optimized resp. Remeber option. The corresponding buttons in the query will be hidden providing more space. 

Resources directory

The directory for the resource can be set with as shown in the area below. Here parameters for example the spreadsheets are stored. See chapter Resources for details.

Time for tooltip

You can set the time for which the tooltip should be shown. In the customize window the setting will be changed instantly while in the main windows the setting will only be effectiv after restart of the application. 

You have 3 options:

• Set the time the tooltip should be visible to 1 up to 5 seconds
• Set the time the tooltip should be visible to no limit
• Hide the tooltip

Transaction

Transaction display sequence

To customize the sequence and format of the transactions shown in the tree, choose Administration -> Customize display … from the menu and then select the part Transaction (see below). If you want to change the default sequence and/or display type, click on the button. Use the and buttons to change the position of a certain type of transaction and choose one of the display types. To reset these settings to the database default, use the button. If your transactions are organized within a hierarchy, you can include the titles of the superior hierarchies with the Include superior transaction in title option. 

Transaction standard comments

As an administrator you can add entries to the Standard comments for transactions (see above) that are used to enter standard phrases into the comment field of a transaction.

Default currency

The default currency for all transaction payments in the database is Euro. To change the default currency click on the Currency button. 

Settings

The tab Settings shows an overview of all settings set by the user e.g. when linking the sources for identification to a certain database or webservice via the button (see below). Relations to Diversityworkbench modules include the database and the project as shown below. With the Reset button, you can clear the whole settings. These settings can not be defined here, but are set in the main form in the corresponding parts e.g. the identification. These settings are stored in the database for every user (UserProxy -> Settings). 

Query

Visibility

The query containing results and fields is positioned a the left of the window. To visibility of the query can be set in the menu: Query - Show query:

The query fields are displayed in the main form beneath the list of the result items. You can change this arrangement using the  /  button to place the query fields on the left side of the item list.

To hide the area containing the search fields click on the  button. If the search area is hidden and you want to start a new search, just click on the  button.

Searching

To search for data, enter the restrictions in the fields for the search conditions and click on the  button. The agents found in the database will be shown in the list. To add agents with differing search conditions click on the  button. If you want to remove entries from the selected list, choose them and click on the  button. This will not delete the data from the database, but remove them from your query result.

The option to provide a result list with many columns is described in chapter Many result columns.

To change the displayed fields for searching data click on the  button to change the query options. 

A window will open containing the command used to retrieve the data (see below).

To keep the values you entered for the query, you can click on the button. It will change to and when restarting the program your query values will be remembered

To speed up the query you may use the optimized version (Standard query: Optimized query: ). The optimized query in combination with the remembering option includes the functionality to preselect data depending on the query restrictions, e.g. if you search for an identification and enter a taxonomic name the first identification matching the restrictions will be preselected in the main window as shown below.

The set the option for optimized queries and the option to remember the query settings as default, choose Administration - Customize display... from the menu. In the tab Defaults and miscellaneous select the Optimized and Remember option. The buttons in the query will be hidden providing more space. 

Certain query fields provide the option to add up to 3 duplicates of themselves. Use the button to add and the button to remove duplicates. The restrictions can be combined with AND + and OR |. Just click on the + resp. | sign to change between the modes.

Within the query options you have several possibilities to specify your search restriction. Use the drop-down menu to switch between operators. The available operators are shown in the tables below.
Availability: t = text, n = numeric, d = date, h = hierarchy, x = XML, e = EXIF, g = geography, a = annotation, m = module
For an introduction see two short tutorials

Query operators

Operators for text

Operators for numeric data

Operators for date values

Oparators for hierachy

Operators for XML

Operators for geography

Use (via local files or manual creation) resp. (via DiversityGazetteer) button to set geography

For yes/no fields exists a checkbox with 3 options: = yes, = no, = undefined

For a search within a lists (using the |, ∈ or ∉ operator) you may double click in the text field to open a window where you can enter your values. To separate the values either use the "|" sign or a new line as shown in the image below.

Query modules

In the query for values linked to another module click on the button to open a window where you can search for values within the linked module. A click on the button will show a list of the selected items. For some modules you can choose the cache database as source (if you have the proper permissions). This option provides a faster query esp. if e.g. the data of a related module are accessed via a linked server.

Tutorial:

Operator	Meaning	Example
∈	Search for entries with a list	Rosa | Rosa caninia \
∉	Search for entries not within a list	Rosa | Rosa caninia | ...
+H	search for entry including lower ierarchy	Picea | Picea abies | ...
+S	search for entry including synonyms	Picea abies | Pinus abies | ...
+HS	search for entry including lower hierarchy and synonyms	Picea | Picea abies | Pinus abies | ...
	Change filter mode between link and text	http://tnt.diversityworkbench.de/TaxonNames_Plants/4269 <> Picea abies L.

Query annotation

The query for annotations deviates from the standard query (see below). Additionally, you may specify a type of the annotation (Annotation , Problem , Reference ) and the linked table (see Annotation).

Query any fields

The query for any fields will search in several fields, e.g. withholding reasons in specimen, images etc. There are two versions: The first version (e.g. Notes) will search in all tables but not in collection event tables while the second version (e.g. Any notes) will search in any table (see image below).

Wildcards in SQL

There are 4 different possibilities for wildcards in SQL:

Many columns

The option to include several columns in the result list is only available for optimized queries . To display several columns in the result list, click on the button next to the order by column (see below). A window will open where you can select the next column for the sorting. Underneath the order by column the second column for the sorting will be added. To remove this sorting column you can click on the    button. By default the width for the columns is set to 10. You can change this according to content. To set the width to the maximal length of the current content, click on the button. To change the sorting of the added order column click on the button. The colums are separated via " | " as shown in the image below.

Scan mode

Scanner

With the scan mode you may use a barcode scanner or the camera of your computer or tablet using e.g. bcWebCam to search for a specimen. To work with the scan mode select the Scan mode in the Query menu. The query part will be hidden and the field for the scanned identifier will be accessible for the entry via the scanner. As possible identifiers you can choose among the accession number of the specimen , the ID of the specimen ID, the accession number of the part or the identifier of the organism . If the field for the entry of the identifier is not activated, move the mouse to the field to activate it. Once you scan the barcode the program will start the search for the specimen in the database. To return to another query mode deselect the Scan mode.

If the results captured by the scanner do not correspond to the scanned codes, the timer intervall may need an adaption to your scanner. To set the timer interval of the scanner, click on the button. The default is set to 200 ms. Change it until the results captured by the scanner correspond to the codes.

The second scan mode for collection codes (stable identifier for collections) or the name of the collection will list all specimen within a collection. For the query of collection names these must be unique within the database. The query for collections may include depending collections. By default only specimen of the selected collection will be shown. Click on the button above the button to change to the mode including specimen in depending collections.

Specimen list

The result list displays the specimens found in a query.

The specimens may be displayed with their e.g. with their accession number. To change the information of the specimen shown in the list, choose among the option provided in the [order by:]{.style1} combobox. Some possibilities are shown above: identifications, storage location or collectors number. After you changed the selection of the displayed information, you have to start the query to see it in the result list. To view further information on the chosen field simply place the mouse in the field. A text box will appear with the description of the field (see below).

You may restrict the maximum number of specimens and queryoptions (click on the button), if you have for example a slow connection to the database. As a default the maximum number is set to 100. If the number of data sets according to your query is higher than the maximum value set in the query options, it will be indicated in the header of the list.

To ensure that restrictions set in the query conditions will be applied to the specimen list make sure that you choose matching restrictions and order columns as shown below. In the upper example corresponding fields were used for restricting the query and the display (Tax. name). Here the query results will be restricted to said field.

In the second example a different field for the restriction was chosen (Last ident. <> Tax. name). The query result in consequence will list all data sets with entries found in the field Tax. name and entries which match the restriction (see below).

To search for specimens enter the restrictions in the fields for the search conditions and click on the button. The specimens found in the database will be shown in the result list. To add specimens with differing search conditions click on the button. If the list of items is longer than your maximum number of returned items you may browse the next items with the button. If you wish to remove entries from the selected list, choose them in the list and click on the button. This will not delete the data from the database but remove them from your query result.

The result list will contain data with [Read only]{style=“color: #707070; font-weight: bold”} access. For these data all controls and menus for editing the data will be disabled except the button for adding annotations .

Here are some examples you may select for display in the result list:

AccessionNumber: One entry is shown for each specimen with its corresponding accession number.

Last identification: The last identification for every unit in a specimen is shown in the list. As there can be several units in one specimen, several entries for one specimen may appear in the list.

Storage location: The storage location of every part of a specimen stored in the collections is shown in the list. As parts of a specimen can be stored in several collections under different names, several entries for one specimen may appear in the list.

Collecting number: The collecting number given by the collector of every sample of a specimen is shown in the list. A specimen may have several collectors each with a different number. Therefore, several entries for one collection specimen may appear in the list.

Synchronizing

With the maintenance functions you can update values cached from other modules or external webservices. DiversityCollection can be linked with several other modules of the DiversityWorkbench. If you link a data source to another module, the URI of the data set in the other module together with one or several cached values will be stored in DiversityCollection. Due to changes in the source modules these cached values may differ from the original values. To get the actual values you can use the synchronize functions for taxonomic names, family and orders, people, exsiccatal series, geographical names and references.

Orphaned data

The removal of certain data may leave orphaned data as shown in the image below. The removal of a specimen may leave event data without any relation to a specimen. As the access to the data is organized via projects this relation is removed as well. So orphaned data are accessible by anyone. Orphaned data may on the other hand exist due to the preparation of events for upcoming expeditions and the like. Therefore care should be taken when removing orphaned data to not remove preparations of other users. For an overview see a short tutorial .

Maintenance Event & series

CollectionEvents - orphaned events

Provided you have the proper rights you can remove orphaned data sets in the tables CollectionEvent and CollectionEventSeries. To delete events which are not linked to any data in the database use the tab page Orphaned data - Event. These unrelated data sets may e.g. be derived from specimens that were transferred to another CollectionEvent. Click on the Find orphaned data button to list all events which are not related to a specimen. The found CollectionEvents and their dependend data will be listed as shown below. Click on the Start removal button to delete the data.

Country, Place and Altitude via GeoNames

If your data sets contain WGS84 Coordinates, you can use the webservice www.geonames.org to insert or update the country, the place or the altitude of your collection sites. Choose the tab Set place and country, the project you wish to update and an optional upper limit of the data sets (recommended for slow connections). Click the Query GeoNames button to start the query. According to the selected option (only if missing / when different / for all entries) the retrieved data will be marked with colors as shown in the images below.

In the first column you can deselect a data set for the update. To inspect a single data set from the list select it and click on the Close window and check data set button. To update the data set click on the Set countries button.

As for countries, the places will be listed as shown below.

To insert or update the selected data sets click the Insert places button.

The image above shows the data for the altitude. After the update all updated data sets will be marked green (see below).

Sampling plots

If your data contains references to sampling plot coordinates, you can update the locality description according to the name of the sampling plot (see image below). Click on the Start search button to find links to SamplingPlots where the locality description does not correspond to the name of the sampling plot. You can restrict the search to missing locality descriptions and attach the name of the sampling plot to the existing entry in the locality description. Use the Start update button to set the locality description according to your settings and the differences found.

Method parameters

If your events contain methods where parameters for these methods had been added afterwards, you can add these missing parameters. You may restrict the search for missing parameters to certain methods and projects (see image below). Click on the Find differences button to search for missing parameters and on the Start update button to add them to the methods used in the events.

If your data contain or needs coordinates, please see the corresponding chapter on adding and calculatingcoordinates.

Collection date

If your events contain missing or invalid collection dates you may search for these in the Collection date section (see below). Use the button to search for these datasets. In the upper part of the window datasets with complete parts for a valid date but missing dates are listed. These can be updated with a click on the button. In the lower part of the window you find data with date parts that would result in an invalid date. Click in one of the lines and then on the button to close the window and inspect and fix the listed data.

Maintenance

Accession number duplicates

The database will warn but not prevent you from entering an accession number several times e.g. via an import. In the main form a duplicateaccession number is indicated with a red background. To check for duplicate accession numbers choose Administration - Maintenance from the menu. In the window that will open, choose the tab page  Specimen as shown below. You can restrict the query to a project or leave the project empty in order to compare with all the available projects. For a restriction to certain numbers you may enter a filter (using wildcards, see below). To start the query click on the Check for duplicates button.

The form will list all duplicates found as shown above. To switch to a data set in the database select it in the table and click on the Close form and check dataset in database button. To see only the selected rows, click on the Close form and check selected rows . To list all duplicates in the main form click on the Close form and check whole list in database . To compare the contents of duplicates, select the duplicate in the list and click on the button. A window as shown below will open. All tables containing the data of the duplicates will be shown.

Use the button to optimize the width of the columns. The columns in the tables are marked with different colors as shown in the image above. For the comparison of the data key columns will be ignored unless you choose the option Compare text key columns. To restrict the displayed tables and columns to those with differences, choose the Restrict to differences option (see below). In the window for comparing the data, editing is not possible, but you can open another client and edit the duplicated data. To show changes in the data performed e.g. in a second client, click on the button.

Maintenance

Retrieval Type

To find observations (= organisms without a part in a collection) with missing retrieval type choose Organisms - Retrieval type in the maintenance form as shown below. After selection of the project, click on the Find missing retrieval types button. The organisms missing a retrieval type will be listed as shown below. To inspect a single dataset, select it in the list and click on the Show selected dataset button. To edit the data in the main form, choose those you want to edit as shown in the image below and click on the Edit data in main form button. If nothing is selected all data will be listed. If you want to insert the missing retrieval type, selected the proper type from the list and click on the Insert retrieval type button

Maintenance

Storage

Maintenance - Insert missing organisms in specimen parts

To print a label for your samples you need to specify which of the organisms in the specimen should be shown on the label. If for any reason the organisms where not included into the parts as shown in the image below, you may do this belated for all data sets for a selected project.

Select the print tab as well as the project and click on the [Check for missing units in parts] button. The missing entries will be listed as shown below. To insert them click on the corresponding button.

Set storage location to last identification

The image below displays the option to synchronize the storage location with the last identification. Select the project and Search for differing storage . All parts with differing storage location will be listed. To check a single dataset, select it in the list and click on the Check dataset button. A click on the Update storage locations button writes the new versions of the storage locations in the database.

Maintenance

Analysis

To add a new analysis depending on present entries choose Administration - Maintenance from the menu. A window will open as shown below. On the tab page Analysis select the project, the taxonomic group, the analysis etc. for which the analysis should be added. To check the numbers present in the database, click on the button. The numbers will be listed in the area on the right. To test the data that would be added with you settings, click on the test button. To check a single dataset in the database, select it in the result list and click on the button. This will close the window and open the selected dataset in the main window. If finally you want to insert the data as shown in the area on the right, click on the button.

Maintenance

Images

The sorting of images may be changed for a whole project. Choose Administration - Maintenance from the menu. A window will open as shown below. On the tab page Images select the project for which the images should be sorted. There are 4 options to sort the images (see image below). Click on the button to list all images that may be sorted. To write the selected sorting into the database click the button Change sequence of images .

Maintenance

Administration of Regulations

To insert regulations like the Nagoya protocol choose Administration -> Maintenance from the menu. A window will open as shown below. On the tab page Regulations select the project and the country for which the regulations should be entered. Select the collection and/or accession date where the search for the data should be started. A click on the Search for events button will start the search and list all detected data as shown below.

If the data should be withheld from publication e.g. via the cache database, enter the corresponding withholding reason . These withholding reasons will only be inserted if the specimens are not already withheld for other reasons.

Click on the button to find the regulation that should be inserted.

With the Start entry of the regulations button the withholding reasons and regulations will be inserted.

The regulations will be inserted as shown below.

Maintenance

Remove C0-codes

To remove C0 codes from text columns in the database choose Administration - Maintenance from the menu. A window will open as shown below. On the tab page Tools either start a query for all tables and columns in the database or select the table and column you want to test for the existance of C0 codes in the data. The data will be checked for C0 codes from 1 - 31 excluding 9, 10 and 13. If C0 codes are detected, these will be listed as shown below with C0 codes indicated by the ■ sign. You can either ignore this sign or remove it from the data using the corresponding buttons. 

Maintenance

Insert missing organisms in specimen parts

To print a label for your samples you need to specify which of the organisms in the specimen should be shown on the label. If for any reason the organisms where not included into the parts as shown in the image below, you may do this belated for all data sets for a selected project.

Select the print tab as well as the project and click on the Check for missing units in parts button. The missing entries will be listed as shown below. To insert them click on the corresponding button.

Maintenance

Reference Transfer

To transfer references from deprecated columns in the tables CollectionSpecimen and Identification into the new table CollectionSpecimenReference choose Administration -> Maintenance from the menu. A window will open as shown below. On the tab page References you find the tabs for the transfer of the data. You may restrict the search to a project and have 2 types to match with existing data, either the Existence that will search for any data in the table CollectionSpecimenReference or the Title searching for content with the same title. Start the search with a click on the Search for references button. To show the details of a detected dataset, use the Show details button. To finally transfer the data into the new table, click on the Transfer data button. 

Collectors

Sequence

There may be datasets where the sequence of the collectors in one specimen are the same. To fix this error, use the Collector tab as shown below.

Click on the search button to search for the corresponding data. Then click on the update button to add the number of milliseconds to the last collector corresponding to the number of collectors detected. This will finally change the sequence according to the alphabetical order.