Consolidate Setup Tool, Configuration Tool, and Preloaded Tree Creation

[CarolineDenis]

Fixes #7673
See issue description

(Cloned from #6671)

[grantfitzsimmons]

Starting with this, adding new reviews as I can:

4. Configuration Tool
Institution Tree Viewer

• Users can click and drag to view all nodes in the institution tree.
• Clicking a resource node opens the resource form.
• Users can:
  • Edit a resource
  • Create new resources
  • Delete collections

When I create a new collection, discipline, or division by clicking + Add {level} under the appropriate parent, it fails:

Backend error when creating a collection / discipline / division

``` specify7 | [29/Jan/2026 14:26:26] [ERROR] [django.request:246] Internal Server Error: /api/specify/division/ specify7 | Traceback (most recent call last): specify7 | File "/opt/specify7/ve/lib/python3.12/site-packages/django/core/handlers/exception.py", line 55, in inner specify7 | response = get_response(request) specify7 | ^^^^^^^^^^^^^^^^^^^^^ specify7 | File "/opt/specify7/ve/lib/python3.12/site-packages/django/core/handlers/base.py", line 197, in _get_response specify7 | response = wrapped_callback(request, *callback_args, **callback_kwargs) specify7 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ specify7 | File "/opt/specify7/specifyweb/specify/views.py", line 32, in wrapped specify7 | return view(request, *args, **kwargs) specify7 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ specify7 | File "/opt/specify7/ve/lib/python3.12/site-packages/django/views/decorators/cache.py", line 40, in _cache_controlled specify7 | response = viewfunc(request, *args, **kw) specify7 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ specify7 | File "/opt/specify7/specifyweb/specify/views.py", line 68, in view specify7 | return dispatch_func(request, *args, **kwargs) specify7 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ specify7 | File "/opt/specify7/specifyweb/specify/api/dispatch.py", line 97, in collection_dispatch specify7 | obj = post_resource(request.specify_collection, specify7 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ specify7 | File "/usr/lib/python3.12/contextlib.py", line 81, in inner specify7 | return func(*args, **kwds) specify7 | ^^^^^^^^^^^^^^^^^^^ specify7 | File "/opt/specify7/specifyweb/specify/api/crud.py", line 96, in post_resource specify7 | obj = create_obj(collection, agent, name, data) specify7 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ specify7 | File "/opt/specify7/specifyweb/specify/api/crud.py", line 62, in create_obj specify7 | result = CREATE_MODEL_REDIRECTS[model_name](normalize_keys(data)) specify7 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ specify7 | File "/opt/specify7/specifyweb/backend/setup_tool/api.py", line 170, in create_division specify7 | institution = resolve_uri_or_fallback(institution_url, None, Institution) specify7 | ^^^^^^^^^^^^^^^^^^^^^^^ specify7 | NameError: name 'resolve_uri_or_fallback' is not defined ```

Specify 7 Crash Report - 2026-01-29T20_24_28.542Z.txt

Note that I am unable to delete an empty collection using this since it was made in 6 (it contains a autonumsch_coll link, which Specify 7 doesn't recognize as a data model table):

IntegrityError at /api/specify/collection/786433/ (1451, 'Cannot delete or update a parent row: a foreign key constraint fails (`specify`.`autonumsch_coll`, CONSTRAINT `FK46F04F2A8C2288BA` FOREIGN KEY (`CollectionID`) REFERENCES `collection` (`UserGroupScopeId`))') 

• An empty configuration is created automatically for new disciplines.
• Users can collapse and expand sections in the left panel.
• Users can switch between vertical and horizontal views in the institution tree viewer.

[grantfitzsimmons]

1. Setup Flow
Setup Forms

• All setup forms must display correctly in both light mode and dark mode (based on system settings).
• Users can only progress to the next form once all required fields are completed.
• User selections must be reflected in the Overview sidebar in real time.
• The setup flow must be submittable at the end.

I can't proceed with the database creation:

Terminal Logs

specify7  | [29/Jan/2026 14:43:59] [DEBUG] [specifyweb.backend.setup_tool.api:112] Starting Database Setup.
specify7  | [29/Jan/2026 14:43:59] [ERROR] [specifyweb.backend.setup_tool.api:124] name 'normalize_keys' is not defined
specify7  | Traceback (most recent call last):
specify7  |   File "/opt/specify7/specifyweb/backend/setup_tool/api.py", line 114, in setup_database
specify7  |     data = normalize_keys(raw_data)
specify7  |            ^^^^^^^^^^^^^^
specify7  | NameError: name 'normalize_keys' is not defined
specify7  | [29/Jan/2026 14:43:59] [ERROR] [django.request:246] Internal Server Error: /setup_tool/setup_database/create/

There are also some strange issues:

1. You can have a rank that isn't included as "enforced". If it isn't included, it should prevent the user from choosing any other option:
   

2. The "Tree Ranks" heading shows twice, once in the table and once above the table.

• Users must be able to log into the database after setup completes.

[alesan99]

@grantfitzsimmons

When I create a new collection, discipline, or division by clicking + Add {level} under the appropriate parent, it fails:

Fixed now 👍

Note that I am unable to delete an empty collection using this since it was made in 6 (it contains a autonumsch_coll link, which

Specify 7 doesn't recognize as a data model table):
I believe this should be fixed after #7643 gets merged

I can't proceed with the database creation:

Also fixed

1. You can have a rank that isn't included as "enforced". If it isn't included, it should prevent the user from choosing any other option:

I made it so all fields are disabled if the rank isn't included. A user can still enable the rank, configure those fields, and then disable the rank, but I figured that since the fields are disabled now it should be clear that those configurations won't be used.

2. The "Tree Ranks" heading shows twice, once in the table and once above the table.

I changed the label to Rank as it should be

[grantfitzsimmons]

1. Setup Flow
Setup Forms

• All setup forms must display correctly in both light mode and dark mode (based on system settings).
• Users can only progress to the next form once all required fields are completed.
• User selections must be reflected in the Overview sidebar in real time.
• The setup flow must be submittable at the end.

One of the tested overview submissions

Category	Item
Institution
Name	Grant
Code	G
Address
Address	1345 Jayhawk Blvd
City	Lawrence
Province/State	Kansas
Country	United States
Zip/Postal Code	66045
Phone	7855555555
Define Accession Globally	No
Storage Tree
Tree Ranks
Site
Include	Yes
Enforced	Yes
In Full Name	No
Separator	,
Building
Include	Yes
Enforced	No
In Full Name	Yes
Separator	,
Collection
Include	Yes
Enforced	No
In Full Name	Yes
Separator	**
Room
Include	Yes
Enforced	No
In Full Name	Yes
Separator	;
Aisle
Include	Yes
Enforced	No
In Full Name	Yes
Separator	grant
Cabinet
Include	Yes
Enforced	No
In Full Name	Yes
Separator	$
Shelf
Include	Yes
Enforced	No
In Full Name	No
Separator	,
Box
Include	No
Enforced	No
In Full Name	No
Separator	,
Rack
Include	No
Enforced	Yes
In Full Name	Yes
Separator	,
Vial
Include	No
Enforced	No
In Full Name	No
Separator	,
Full Name Direction	Reverse
Division
Name	Division
Abbreviation	DIV
Discipline
Type	Geology
Name	Geology
Geography Tree
Tree Ranks
Earth
Include	Yes
Enforced	Yes
In Full Name	Yes
Separator	;
Continent
Include	Yes
Enforced	No
In Full Name	Yes
Separator	(continent)
Country
Include	Yes
Enforced	No
In Full Name	Yes
Separator	(country)
State
Include	Yes
Enforced	No
In Full Name	Yes
Separator	(state)
County
Include	Yes
Enforced	No
In Full Name	Yes
Separator	(county)
Full Name Direction	Forward
Populate tree with default records	Yes
Taxon Tree
Populate tree with default records	No
Tree to download:	-
Collection
Collection Name	Geology
Code	GEO
Catalog Number Format	CatalogNumberNumeric (#########)
Specify User
First Name	Grant
Last Name	Fitzsimmons
Username	spadmin
Password	***

• Users must be able to log into the database after setup completes.
  Default Data & Configuration

• Default schema configuration captions and descriptions must be populated (not blank).

• Default picklists must be created correctly.

  • Note: The Agent Type picklist does not exist in the schema config, this is expected.

• Default preparation types must be created correctly.

• All tree viewer pages must load without errors.

• The admin user’s agent must be created correctly and must always include a last name.

• An empty Global Preferences file must be created in App Resources.

Known Issue (Out of Scope):
The Accounts page and Stats page currently throw errors. These will be addressed separately in
Check default database constraint differences between Sp6 and Sp7 (#7551).

Auto-numbering is also still not working (as expected), see #7617

2. Tree Configuration During Setup
Storage Tree

• Users must be able to modify the storage tree configuration during setup.
• Changes must be correctly reflected in the application after setup.

Geography Tree

• Users must be able to modify the geography tree configuration during setup.
• Both options must work:
  Preloaded tree
  Empty tree

I made a small change to make pre-loading Geography data enabled by default. It would not make sense to have every user pre-load this themselves.

Taxon Tree

• Users must be able to select a preloaded default tree when one exists.

Still a blocker for 7.12, see: #7676

We need to also add at least a tree with a standard lookup of IMA minerals and Meteorites.

• The selected tree must be correctly preloaded and visible when the app opens.

Geology Discipline

• Relevant tectonic and chronostratigraphic (chrono) trees must be created automatically.

3. Tree Viewer: Preloaded & Empty Trees

• Users can create an empty tree from the tree viewer.
• Users can modify rank configuration in the tree viewer.
• Users can create a preloaded tree from the tree viewer.
• Empty trees now have an upload button. The Upload Tree icon under root creation must work as expected.

I find it to be rather unintuitive when "importing" data from a default tree source into an existing tree. Currently, if you have a tree that is missing a rank that is included in the default tree file, it is simply lost forever. The user is not notified of which ranks include the data beforehand, so they may simply be missing a huge segment of the tree (e.g. all classes or families) since they are given no warning.

I suggest we at least add some indicator in the tree import dialog that specifically communicates which ranks will be populated (if present), and make that more clear. Otherwise, they may fail to populate the tree properly.

• Users can delete a rank with no associated nodes.
• If ranks are deleted and a tree is then loaded, the tree configuration must be respected.
• Users receive notifications for:
  Tree creation start
  Successful completion
  Errors or cancellation

The user certainly receives a lot of notifications (and this is a brand new database), which feel completely unnecessary.

For example, when creating a new institution, division, discipline, and collection all at once (during the first setup), what is the benefit of notifying the user of all of these new records being created?

I created a botany discipline, yet I am notified about the completion of the botany geologictimeperiod tree? If this has to happen, so be it, but there is no benefit to the user when they receive notifications about these actions. Either the database is created or not, so I'd prefer a "Welcome to Specify!" notification once everything is completed over this approach.

The logs into Specify for the first time already with 6 notifications...

---

4. Configuration Tool
Institution Tree Viewer

• Users can click and drag to view all nodes in the institution tree.
• Clicking a resource node opens the resource form.
• Users can:
  • Edit a resource
  • Create new resources
  • Delete collections
• An empty configuration is created automatically for new disciplines.
• Users can collapse and expand sections in the left panel.
• Users can switch between vertical and horizontal views in the institution tree viewer.

Using the add button on the 'Collections' subview under any given discipline works, but it shows the incorrect discipline (e.g. the current logged in discipline) in the data entry form. See below:

Once it is created, it is placed under the appropriate discipline:

My suggestion: The add (+) button should be opening the same form as the "+ Add {Level}" dialog rather than the standard data entry form. For example, disciplines cannot be created since you can't select the type now.

The resources are created correctly already when you approach it from this view in my testing already (pick lists, schema records, etc)._ I think we should find a way to make this possible. I would also advocate for the removal of the search (:mag:) and delete (-) buttons from these subviews to minimize confusion.

---

Getting there! Some blockers (#7617, #6279, #7626, and #7643) before this can be considered finished.

I am going to work on some Geology defaults.

---

Final thought, in the 'Guided Setup' tool, when creating a new discipline, we ask the user to decide:

• Geography Tree
  • Configure ranks
  • Populate from default
• Taxon Tree
  • Populate from default

But in the 'System Config' tool, we don't offer the same functionality. They are forced to use the default, pre-configured geography tree and taxon tree. Can we make this consistent, with heavy preference to adding the discipline configuration options to the 'System Config' tool?