Skip to content

Commit 0b9705f

Browse files
zzeppozzzzeppozz
committed
docs
1 parent 2a78603 commit 0b9705f

File tree

5 files changed

+224
-27
lines changed

5 files changed

+224
-27
lines changed

‎sphinx/index.rst

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,21 @@ Welcome to Specify Developer documentation!
6464

6565
testing/pull_requests
6666

67+
.. toctree::
68+
:maxdepth: 1
69+
:caption: Specify Software:
70+
71+
software_desc/glossary
72+
software_desc/overview
73+
software_desc/membership
74+
software_desc/disciplines
75+
software_desc/hosting
76+
software_desc/hosting_db
77+
software_desc/migration
78+
software_desc/training
79+
software_desc/workbench
80+
software_desc/workflows
81+
6782
.. toctree::
6883
:maxdepth: 1
6984
:caption: Misc:

‎sphinx/software_desc/history.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Specify History
2+
###################
3+

‎sphinx/software_desc/overview.rst

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
Overview
2+
###################
3+
4+
The Consortium
5+
**********************
6+
The Specify Collections Consortium (SCC) is an international, non-profit, membership
7+
organization of biological museums, universities and government agencies working
8+
together to advance computerization within biodiversity research collections. The SCC
9+
does this by providing open-source software platforms and technical services for
10+
specimen data digitization and collection management.
11+
12+
As of November 2024, the Specify Collections Consortium comprises 142-member
13+
institutions from 24 countries that collectively use Specify software in 451 research
14+
collections. (The SCC member list is available on our web site,
15+
http://www.specifysoftware.org/members.) The Consortium is financially and legally
16+
administered as a U.S. 501(c)3 non-profit organization under the Office of Research of
17+
the University of Kansas, a U.S. public research university. Prior to 2018, the Specify
18+
initiative was funded by grants for 20+ years by the U.S. National Science Foundation.
19+
Reaching back to its roots in 1987, the Consortium represents 36 years of biodiversity
20+
collection community engagement with collections software and technical support.
21+
22+
The Consortium’s financial health has been strong since we transformed the Specify
23+
initiative to an institution membership organization in 2018. Membership has grown an
24+
average of 14% per year; in 2024 the SCC’s membership revenue will reach $486,000 USD.
25+
The University of Kansas provides additional salary support to the Consortium in the
26+
amount of $186,000 per year. Supplemental revenue comes from grants. In 2024, with
27+
$192,000 in grant funding from the Swiss Academy of Sciences SwissCollNet Program,
28+
and in collaboration with several Swiss museums of natural history, we are extending
29+
Specify to the geosciences for managing research collections of rocks, minerals, gems,
30+
and meteorites. The extension will be available as of the first quarter of 2025.
31+
32+
Expertise and Services
33+
**********************
34+
The SCC office, acting as home base for its software engineers and support staff, is
35+
located in the Biodiversity Institute at the University of Kansas in Lawrence Kansas.
36+
Staff includes the Director (Dr. J.H. Beach), three professional software engineers,
37+
two professional technical support staff, four junior undergraduate software engineers,
38+
and three undergraduate software quality testers.
39+
40+
With member fulfillment and technical services, the SCC provides timely responses to
41+
help desk requests. We also operate a Specify Community Forum site that serves as a hub
42+
for Specify member feedback and discussion (http://discourse.specifysoftware.org). In
43+
addition to producing new capabilities in regular Specify software releases and fixing
44+
bugs in minor updates, we also work with SCC member collections to migrate historical
45+
data sets and to resolve technical or data issues that arise. We have a deep technical
46+
understanding of the research and curatorial goals of collections scientists and of the
47+
data management tasks that are part of museum operations. Our professional software
48+
engineering and support staff have decades of experience working with collections of
49+
all biological disciplines, sample preparation types and collection work protocols.
50+
51+
Why use Specify Software?
52+
-------------------------
53+
We understand biological collections and their data, A-to-Z and top-to-bottom. No team
54+
on the planet has worked with more collections’ data or converted more legacy database
55+
systems to a modern relational database design than we have. The SCC was born in the
56+
biological collections community, and we have been embedded and fully-engaged with
57+
research collections for decades.
58+
59+
Since the mid-1990s our approach to the semantics, structure, and logical processing of
60+
biological collections data has met the needs of hundreds of collections curators and
61+
researchers, worldwide. One ingredient for our long-term success, and ongoing utility of
62+
Specify for biological collections, lies in the design of Specify’s layered software
63+
architecture. Specify has a highly-adaptable, collection-centric design that allows
64+
interface forms, components, languages, and even embedded help tips to be customized
65+
for each collection. By using configuration preferences and settings, Specify’s data
66+
forms can be optimized around a collection’s standard protocols without modifying
67+
Specify’s codebase or database design.
68+
69+
Our flagship software platform, Specify 7, combines the interface design components and
70+
data management foundation we supported for over 15 years in Specify 6, our Java
71+
thick-client platform, with the efficiency and ease-of-use of web-based data access and
72+
cloud computing. The Specify 7 web application uses the same data forms layout language
73+
as Specify 6, so user interface customizations made in one platform are mirrored in the
74+
other. Also because Specify 6 and Specify 7 use the same database schema in a MySQL or
75+
MariaDB database, they can be run simultaneously within a biological collection. By
76+
providing a clear migration path to the web, Specify 7 has helped transition Specify 6
77+
collections to cloud computing. Specify 7 is also a great starting platform for
78+
institutions that prefer to avoid managing server hardware or workstation software
79+
installation, with the added benefit of ubiquitous web browser access. Specify 7 server
80+
software is supported on generic Linux servers, which provides an option to consider a
81+
cloud hosted deployment to handle server administration, security management, and data
82+
backup. Institutions can use their own hosting provider or the SCC’s Specify Cloud
83+
service (https://www.specifysoftware.org/products/cloud/) to host their collection
84+
databases.
85+
86+
Moving forward
87+
**********************
88+
The Specify team is constantly working on enhancing the user experience by revising
89+
code and adding new features. The 2025 Work Program for development and outreach can be
90+
found on our Forum (https://discourse.specifysoftware.org/t/2025-scc-work-program/2273).
91+
Development priorities are established through feedback and discussion with our Board
92+
of Members, User Advisory Committee, and Technology Advisory Committee, as well as our
93+
interactions with our members via email, meetings, and our member Forum.
94+
95+
Working with New Members
96+
**************************
97+
Specify staff includes an Implementation Officer and Technical Support Officer who will
98+
take the lead in analyzing data and workflow requirements, as well as work with customer
99+
staff to discuss implementation options to decide on a path forward as well as a
100+
timeline for the decided path. The discussions may involve weekly or monthly meetings
101+
between us and the customers, site visits potentially on both sides, and training on
102+
Specify software.
103+
104+
We have a long history of working with organizations to onboard them into Specify
105+
software. We have worked with collections of all sizes from a few hundred specimens
106+
to around a billion (Canadian Department of Fisheries and Oceans), just about every
107+
natural history discipline, different collection types (preserved specimen, lots,
108+
DNA/tissue, etc.), different complexities from a single collection to consortia with
109+
dozens of institutions each with multiple disciplines.
110+
111+
We have also worked with several consortia of institutions with natural history and
112+
geology collections to bring their data into Specify, including the Denmark Consortia
113+
of Natural History Collections, the South African National Biodiversity Institute
114+
(SANBI), Commonwealth Scientific and Industrial Research Organisation (CSIRO), and the
115+
Canadian Department of Fisheries and Oceans (DFO). We are also currently working with a
116+
Greek Consortia of Natural History Collections to obtain a grant to bring their
117+
institutions’ data into Specify. We can not only leverage that experience in our
118+
discussions and plans, we have a close relationship with representatives from those
119+
consortia who we can reference or meet with to come to the most effective plan for
120+
Norway’s data migration.
121+
122+
We have completed or are currently working with the above Consortia to plan how they
123+
structured their data, each defining optimal work protocols and methods according to
124+
their workflow, institutional independence, and support level. Decisions on how they
125+
structured collection data in their institutional network had downstream effects on
126+
how their information was imported and standardized, all of which we mapped out for
127+
them and assisted, including followup visits and constant interactions. All of the
128+
consortia we’ve worked with are also on our Board of Members, so they are active
129+
participants in deciding the future of our development and of the SCC as a whole.

‎sphinx/software_desc/workbench.rst

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
Specify Workbench
2+
####################
3+
4+
.. _WB field collection:
5+
6+
Field collection
7+
**********************
8+
9+
SCC recommends sending researchers out into the field with a spreadsheet that has a
10+
"Mapping Template" that matches spreadsheet columns to Specify database fields. Users
11+
can create Mapping Templates for any combination of data fields to be imported.
12+
The spreadsheet for data entry is referred to as a "Mapped Spreadsheet".
13+
Mapped Spreadsheets can be created for
14+
research expeditions, focusing on data collection specific to that field trip.
15+
Researchers can easily use the spreadsheet in the field to record information about
16+
specimens, collecting event(s), locality, and more.
17+
18+
Data entered into a Mapped Spreadsheet can be imported via the Specify Workbench, a
19+
spreadsheet-based application. In this workflow, the user chooses the correct Mapping
20+
Template, the uploads the Mapped Spreadsheet to the Workbench. At this stage, the
21+
Workbench is completely external to the data catalog. The Workbench contains
22+
extensive matching and editing features that can be edited to fit user needs.
23+
The Workbench then performs Data Validation on spreadsheet contents before submitting
24+
the data for upload to the Data Catalog.
25+
26+
It allows the user to bring in bulk
27+
data, match columns to fields in Specify, and perform basic data integrity checks to
28+
ensure the data matches database requirements (data validity, controlled vocabulary
29+
matching, and linked record matching, such as Agent or Taxon records).
30+
31+
Users first validate the spreadsheet data within the Workbench, then upload the verified
32+
data to the database. Users may be assigned different levels of access to the
33+
Workbench functionality, such as permission to validate a dataset with the Workbench,
34+
or to perform the upload, so different people may verify that the data is sound.
35+
36+
Because Specify 7 is an online software, with internet access, a dataset may be
37+
created directly in the Specify Workbench from the field. This workflow allows
38+
researchers to verify data against database requirements upon entry.

‎sphinx/software_desc/workflows.rst

Lines changed: 39 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -11,34 +11,10 @@ acquired for collecting and cataloging specimens. Either the Permit or the
1111
Permit Associated Record can be created first, and either can be linked to an
1212
existing record.
1313

14-
SCC recommends sending researchers out into the field with a spreadsheet that has a
15-
"Mapping Template" that matches spreadsheet columns to Specify database fields. The
16-
spreadsheet for data entry is referred to as a "Mapped Spreadsheet".
17-
Mapped Spreadsheets can be created for
18-
research expeditions, focusing on data collection specific to that field trip.
19-
Researchers can easily use the spreadsheet in the field to record information about
20-
specimens, collecting event(s), locality, and more.
14+
:ref:`WB field collection`<Using the Specify Workbench for Field Collection>
2115

22-
Data entered into a Mapped Spreadsheet can be imported via the Specify Workbench, a
23-
spreadsheet-based application. In this workflow, the user chooses the correct Mapping
24-
Template, the uploads the Mapped Spreadsheet to the Workbench. At this stage, the
25-
Workbench is completely external to the data catalog. The Workbench contains
26-
extensive matching and editing features that can be edited to fit user needs.
27-
The Workbench then performs Data Validation on spreadsheet contents before submitting
28-
the data for upload to the Data Catalog.
29-
30-
It allows the user to bring in bulk
31-
data, match columns to fields in Specify, and perform basic data integrity checks to
32-
ensure the data matches database requirements (data validity, controlled vocabulary
33-
matching, and linked record matching, such as Agent or Taxon records).
34-
35-
Alternatively, a researcher could create a custom spreadsheet and simply create a mapping template before importing data to Specify.
36-
37-
Users first validate the spreadsheet data within the Workbench, then upload the verified data to the database. Users may be assigned different levels of access to the Workbench functionality, such as permission to validate a dataset with the Workbench, or perform the upload, so different people may verify that the data is sound.
38-
39-
Because Specify 7 is an online software, if there is internet access there is the option to create a dataset directly in the Specify Workbench from the field. This workflow allows researchers to verify data against database requirements on entry.
40-
41-
More information on our Workbench application is available here: https://discourse.specifysoftware.org/t/the-specify-7-workbench/540
16+
More information on our Workbench application is available here:
17+
https://discourse.specifysoftware.org/t/the-specify-7-workbench/540
4218

4319
Object entry
4420
******************************************
@@ -51,9 +27,45 @@ Each of these approaches to pre-cataloged data has been successfully used by exi
5127

5228
Acquisition and accessioning
5329
******************************************
30+
Specify contains an Accession table for documenting the accession of
31+
objects and groups of objects. The Accession table links to the Collection Object
32+
table and Permit table allowing the user to document metadata about the accession such
33+
as date, agents involved, and permits included, as well as the objects brought in under
34+
that Accession.
35+
36+
The Specify Workbench can ingest a large dataset at one time, and can accepted
37+
pre-assigned Catalog Numbers or automatically assign them.
38+
39+
A status field can be added (Under Registration, Awaiting proof-reading, etc.).
40+
Users can create an unlimited number of unique label templates for individual or bulk
41+
printing, then print one or more labels for one or more objects.
42+
43+
With the introduction of our Batch Edit tool, due in the second quarter of 2025, users
44+
may change the status of many records at a time.
45+
46+
One or more Preparation objects can be assigned to a Collection Objects and Storage
47+
Location information may be documented for each Preparation. For example, the Ethanol
48+
preparation of a specimen may be kept in a different facility than the tissue(s) or
49+
the skeleton.
50+
51+
5452

5553
Location and movement control
5654
******************************************
55+
Storage location information is a tree, which is a hierarchical relationship between
56+
storage values. Default levels are Building, Collection, Room, Aisle, Cabinet, Shelf,
57+
Box, Rack, Vial, but users can define what levels they want in their Storage tree. An
58+
entire section of the storage location tree may be moved to a different parent location
59+
(for example, a box may be moved to another shelf) to reduce the possibility of errors.
60+
Storage locations have names and unique identifiers.
61+
62+
Storage Locations are associated with Preparations. Each preparation may have a
63+
different storage location. A preparation may have a temporary storage location in
64+
addition to its standard storage location.
65+
66+
The SCC is currently gathering requirements for documenting the cold-chain, including
67+
the history of where an object has been stored, at what temperature, start and end times, moved-by, and approved-by.
68+
5769

5870
Cataloguing
5971
******************************************

0 commit comments

Comments
 (0)