[Guided Setup] - Add a setup page for creating a new Institution, Divisions, Disciplines, and Collections

[grantfitzsimmons]

Problem Statement

Currently, Specify 7 is missing a user-facing interface for creating the foundational institutional hierarchy (divisions, disciplines, collections). This process is manual and requires intervention from the support team, creating a barrier for new user onboarding and keeps existing users from expanding their institutional structure as their needs change. The absence of this functionality is a major gap, making it difficult for institutions to adopt and configure the software independently.

The current workaround involves manual database manipulation or support requests, which is inefficient, not scalable, and prevents a seamless "out-of-the-box" experience for new installations.

Proposed Solution

We will implement a guided, multi-step workflow for creating the complete institutional hierarchy, available during initial application setup and later through an administrative configuration panel. This process will automate the creation of default configurations, schemas, and controlled vocabularies based on the selected scientific discipline, mirroring the setup (wizard) process from Specify 6.

Acceptance Criteria

First Run & Institution Creation

• The user will be directed to a new landing page upon opening Specify for the first time.
• There will be sign-up panels for each step, along with a next button.

This is the first interactive step for a new user setting up a Specify 7 instance. The goal is to capture all necessary information to create the top-level institution record.

The user will be presented with a single-panel form titled "Create Your Institution" (or similar) containing the following fields:

A tooltip will be displayed when hovering over the field label (e.g. Institution Name) to show the description shown in this table. All fields included in this table should be present on the form, both required and non-required as denoted.

Field Name	UI Control	Required	Description
Institution Name	Text Input	Yes	The full, official name of the institution (e.g., "University of Kansas Biodiversity Institute").
Institution Code	Text Input	Yes	A short, unique code or acronym for the institution (e.g., "KUBI").
Address	Text Input	No	The street address of the institution.
City	Text Input	No	The city where the institution is located.
State/Province	Text Input	No	The state or province.
Country	Text Input	No	The country.
Zip/Postal Code	Text Input	No	The postal code.
Phone	Text Input	No	A contact phone number.
Accession Scope	Toggle Switch	Yes	Controls accession numbering. Options: Global (default) or Divisional. A tooltip will explain: "Global scope allows you to share Accessions between all divisions. Divisional scope ensures Accessions are specific to each division."
Geography Tree Scope	Toggle Switch	Yes	Controls geography definitions. Options: Global (default) or by Discipline. A tooltip will explain: "A global geography tree is shared by all disciplines. Otherwise, geography trees are managed separately within each discipline."

The panel will feature a "Next" button that is disabled until all required fields are filled.

Storage Tree Configuration:

1. The UI will prompt the user to select ranks for the new Storage tree from our defaults. Default ranks are (defined here in config/common/storage_init.xml):
   • Site (0)
   • Building (100)
   • Collection (150)
   • Room (200)
   • Aisle (250)
   • Cabinet (300)
   • Shelf (350)
   • Box (400)
   • Rack (450)
   • Vial (500)
2. The UI will prompt the user to select ranks and configure the full name format for the new Storage tree.
3. By default, there will only be a single record, a ‘Root’ node at the ‘Site’ level. This node will have Root as both the full name and name.

(If global) Geography Tree Configuration:

4. The UI will prompt the user to select ranks for the new Geography tree (e.g., Continent, Country, State) from our defaults. Default ranks are (defined here in config/common/geography_init.xml):
   • Earth (0)
   • Continent (100)
   • Country (200)
   • State (300)
   • County (400)
5. The user can configure the format of the full name and whether it is reverse or in normal order. All ranks are required initially in Specify 6 and cannot be configured.
6. Implementation: Currently, we use the geonames.sql data provided in Specify 6, create a new geographytreedef and associated geographytreedefitem records, then populate the geography table with the default values.

A. Division Creation

The user will provide a name and code. The system will create a new division record in the database.

• Database: A new row will be inserted into the division table.

The panel will feature a "Next" button that is disabled until all required fields are filled.

B. Discipline Creation

This is a multi-stage process. Each step will have the panel will feature a "Next" button that is disabled until all required fields are filled.

7. User Input:

   • The user provides a name and code.
   • The user selects a disciplineType from a predefined list (e.g., 'botany', 'entomology', 'ichthyology'), which is sourced currently from disciplines.xml. This will need to be integrated into the Specify 7 app, possibly in a JSON file. See

     specify7/specifyweb/context/app_resource.py

     Lines 27 to 39 in 8664c08

     	"fish": "fish",
     	"herpetology": "herpetology",
     	"paleobotany": "invertpaleo",
     	"invertpaleo": "invertpaleo",
     	"vertpaleo": "vertpaleo",
     	"bird": "bird",
     	"mammal": "mammal",
     	"insect": "insect",
     	"botany": "botany",
     	"invertebrate": "invertebrate",
     	"minerals": "minerals",
     	"geology": "geology",
     	"anthropology": "anthropology",

Note

The type field should be a predefined list. After internal discussions, we recommend generating this as a picklist at runtime. This approach allows us to define it in a single static location instead of creating a picklist with items through a migration. (2025-09-23 dev meeting)

8. (If not global) Geography Tree Configuration:

   • The UI will prompt the user to select ranks for the new Geography tree (e.g., Continent, Country, State) from our defaults. Default ranks are (defined here in config/common/geography_init.xml):
     • Earth (0)
     • Continent (100)
     • Country (200)
     • State (300)
     • County (400)
   • The user can configure the format of the full name. All ranks are required initially in Specify 6 and cannot be configured.
   • Implementation: Currently, we use the geonames.sql data provided in Specify 6, create a new geographytreedef and associated geographytreedefitem records, then populate the geography table with the default values.

9. Schema Configuration:

   • Implementation: We will need to create a backend system for handling schema generation.
     • It will first parse a base schema_configuration.json file containing default field definitions, field captions, descriptions, pick lists, field formats, and localizations. This will be based on what exists now, currently defined in XML, which is the baseline schema for all disciplines (see disciplines.xml), but this must be converted to JSON.
       • The pick lists, including all items contained within, are defined in the config/common/picklist.xml file currently, but this must too be converted to JSON or similar.
     • It will then check for a discipline-specific override file (e.g., config/bird/schema_configuration.json, see current equivalent from Specify 6 in XML like this config/bird/schema_localization.xml). If present, it will deeply merge this JSON object, with the discipline-specific values overwriting the base values.
     • The resulting JSON object will be used to populate the splocalecontainer, splocalecontaineritem, splocaleitemstr, and related schema configuration tables for the new discipline. To clarify, this assigns default field visibility, assigned field formats, assigned web links, and pick lists.

10. Taxonomy Tree Configuration:

    • Similar to the Geography tree, the UI will prompt the user to select ranks and configure the full name format for the new Taxon tree. The default ranks that can be configured for each discipline's default taxon tree are defined currently in XML files within the respective discipline (see config/reptile/taxon_init.xml), but this should be converted to a modern approach, possibly using JSON for each discipline.
    • The user will be prompted with an option to pre-load a default taxonomy.
    • Implementation: If the user opts in, a job will pull the appropriate CSV file either from https://files.specifysoftware.org/taxonfiles/ or sourced directly from tree files provided in the app, unzip it, and upload it to the taxon tree for that discipline.

The next trees will only be visible if the discipline is geology or any paleo discipline, which currently includes: geology, vertpaleo, invertpaleo, paleobotany

11. Geologic Time Period (Chronostratigraphy) Tree Configuration:
    • No user input is needed.
    • The system will automatically create a GeologicTimePeriod tree and tree ranks. The defaults, followed by RankID, are as follows (see BuildSampleDatabase.java):
      • Root (0)
      • Erathem/Era (100)
      • System/Period (200)
      • Series/Epoch (300)
      • Stage/Age (400)
    • By default, the tree will be populated with the ICS’s International Chronostratigraphic Chart (ICC) (see #5181)
      • Currently, this is based on the demo_files/chronostrat_tree.xls, but it is known to be problematic. Logic describing how this is built is here: BuildSampleDatabase.java
      • For example, a row of the spreadsheet shows this:

Erathem / Era	Period	Epoch	Age	Start Time	End Time
Cenozoic	Paleogene	Paleocene	Danian	66	72.1 ± 0.2

The current logic builds tree records where it places the “Start Time” value in the startPeriod field and the “End Time” in the endPeriod field. If there is uncertainty denoted in a column (e.g. 72.1 ± 0.2), it is split and placed in the appropriate *uncertainty column.

As of 7.11.1, we have a migration that reverses Geologic Time Period records so that the endPeriod and startPeriod values go in order (where startPeriod is larger than endPeriod) for default records (see #6434). This will need to be taken into account when populating the default trees.

See a snippet of this record after it has been added to Specify and after the 7.11.1 changes were applied:

{
"id": 33,
"endperiod": "66.0000000000",
"enduncertainty": "0.2000000000",
"fullname": "Paleogene, Paleocene, Danian",
"guid": "1711bec5-2f29-478e-a85e-a44c136f7f8d",
"highestchildnodenumber": 44,
"isaccepted": true,
"isbiostrat": false,
"name": "Danian",
"nodenumber": 44,
"rankid": 400,
"startperiod": "72.1000000000",
"startuncertainty": null,
}

• This can be customized later by the user.

12. Tectonic Unit Tree Configuration:
    • No user input is needed.
    • The system will automatically create a GeologicTimePeriod tree and tree ranks. The defaults, followed by RankID, are as follows:
      • Root (0)
      • Superstructure (10)
      • Tectonic Domain (20)
      • Tectonic Subdomain (30)
      • Tectonic Unit (40)
      • Tectonic Subunit (50)
    • By default, there will only be a single record, a ‘Root’ node at the ‘Site’ level. This node will have Root as both the full name and name.
    • This can be customized later by the user.

C. Collection Creation

Collections are created within a parent discipline. The panel will feature a "Next" button that is disabled until all required fields are filled.

1. User Input:

   • The user provides a name and code.
   • The user selects a default CatalogNumFormatName from a list of available formats.

2. Automated Default Record Creation:

   • Preparation Types: A service will read a discipline-specific preptypes.json file (e.g., config/bird/preptypes.json), see currently config/bird/preptypes.xml in Specify 6. It will then iterate through the definitions and create new records in the preptype table for the new collection.
   • Pick Lists: A similar service will parse a discipline-specific picklists.json file (e.g., config/bird/picklists.json), see currently config/bird/picklist.xml in Specify 6. It will create the picklist and picklistitem records, preserving attributes such as isSystem, isReadOnly, and size limits.
   • Collection Object Type: The system will set the selected CatalogNumFormatName on both the collection record and the default collectionobjecttype record associated with the new collection.

First Run Only: Admin User Creation

This is the concluding step of the "First Run" setup process and will never happen again. Its purpose is to create the initial administrative user who will have full permissions to manage the newly configured institution. This step ensures that upon completion, the instance is secure and has a valid user.

After the first collection is configured, the user will be presented with a final panel titled "Create Administrator Account" (or similar) with the following fields:

Field Name	UI Control	Required	Description
Username	Text Input	Yes	The username for the primary administrator account (e.g., "spadmin").
Password	Password Input	Yes	The password for the account.
Confirm Password	Password Input	Yes	Must match the password entered above.

The panel will feature a "Finish Setup" button, which is disabled until all fields are filled and the passwords match. Upon clicking this button, the system will finalize the setup, and the user will be redirected to the main login page.

• A new specifyuser record will be created with the provided username and a securely hashed version of the password.
• A corresponding agent record will be created, using the default agent view definition for the chosen discipline.
• This new agent record will be associated with the division created earlier in the wizard (using divisionId from the payload).
• The new specifyuser will be automatically added as an 'Institution Admin' (given all permissions via the spuserpolicy table)

Access

Institution Singularity

The institution record is the top-level container for all data within a Specify 7 database instance. As such:

• A single institution record is created once per database. This creation event is exclusively handled by the "First Run" guided setup process.
• Once the initial guided setup is completed and the institution is created, the guided setup will be permanently disabled for that database instance. There will be no user interface to create a second institution and doing so should be prevented.
• While fields of the institution (e.g., address, phone number) may be editable by an administrator later, the core record itself cannot be deleted or re-created through the UI.

Source and Stakeholders

• Source: These requirements are based on a detailed analysis of the well-established and functional hierarchy creation process in Specify 6. It aims to bring proven functionality into Specify 7.
• Stakeholders: All new and existing Specify 7 users who need to set up or modify their institutional structure. This is a foundational feature for the entire user base.

Required Documentation

• User: We need to write comprehensive documentation so that new administrators can navigate the guided setup process to fully leverage Specify 7’s capabilities without reliance on support.
• Developer: The code should include comments to explain each part of the process. Additionally, internal standalone documentation should highlight areas for improvement or notes necessary for enhancing this feature in the future.

---

TODO Recap

Institution

UI

• “Create Institution” form
• All fields from requirements: Name*, Code*, Address, City, State/Province, Country, Zip/Postal Code, Phone
• Toggles*: Accession Scope (Global / Divisional), Geography Tree Scope (Global / by Discipline)
• Tooltips on every field label
• Continue button disabled until all required fields are valid
• Storage‐tree configuration step
• Select default ranks (Site, Building, Collection, …, Vial)
• Configure full-name format for each rank and direction
• Preview initial “Root” node (Name=“Root”, Full Name=“Root”)

Backend

• Create Institution record (enforce singleton; block second institution)
• Create Storage Tree (storagetreedef + storagetreedefitem) from UI selections
• If Geography Scope = Global:
• Create GeographyTreeDef + items using geonames.sql
• Populate geography table with default data

---

Division

UI

• “Create Division” form
• Fields: Name*, Code*
• Continue button blocked until valid

Backend

• Create Division record linked to the institution

---

Discipline

UI

• “Create Discipline” form
• Fields: Name*, Code*, Discipline Type* (dropdown)
• Continue button blocked until valid
• Geography-tree configuration (if per-discipline)
• Select ranks + full-name format
• Taxonomy-tree configuration
• Select ranks + full-name format
• Toggle: Preload default taxonomy

Backend

• Load and merge schema JSON:
• Parse base schema_configuration.json
• Deep-merge discipline override JSON
• Populate locale & schema tables (splocalecontainer*, etc.)
• Create Geography Tree (per-discipline)
• Create Taxonomy Tree + optional preload job (download/unzip CSV)
• Geology/Paleo disciplines only:
• Create Geologic Time Period tree & populate with ICC chart
• Create Tectonic Unit tree (single “Root” node)

---

Collection

UI

• “Create Collection” form
• Fields: Name*, Code*, Catalog Number Format*
• Continue button blocked until valid

Backend

• Create Collection record linked to discipline
• Import default preparation types from preptypes.json → preptype table
• Import default picklists from picklists.json → picklist & picklistitem
• Create default CollectionObjectType with selected format

---

User

UI

• “Create Administrator” form (final step)
• Fields: Username*, Password*, Confirm Password* (must match)
• Finish button blocked until valid

Backend

• Create SpecifyUser with hashed password
• Create corresponding Agent linked to division
• Grant full permissions (Institution Admin via spuserpolicy)

---

Other

Security

• Prevent second institution creation
• Restrict setup-wizard UI after first run
• Verify fix for unused DBs missing Remote/Global prefs (issue [Guided Setup] - Databases that are not used with Specify 6 are missing Remote and Global prefs #3653)
• Add tooltips with field descriptions throughout wizard

Documentation

• User documentation: wizard walkthrough + screenshots
• Developer documentation: architecture, JSON schemas, extension points

[maxpatiiuk]

For the simplest implementation, this is possibly just requiring some business rules to be added

For more complicated implementation, creating a new division, should also prompt to configure the trees, which gets into #2932

Probably a lot of other cases to handle too

[specifysoftware]

This issue has been mentioned on Specify Community Forum. There might be relevant details there:

https://discourse.specifysoftware.org/t/add-a-collection-in-specify-7/2017/2

[grantfitzsimmons]

Closed in favor of #5491 and #5490