Skip to content

Commit cde2d58

Browse files
kapuickapuic
committed
Add README for Storage Finder with data and usage instructions
1 parent 9e22585 commit cde2d58

1 file changed

Lines changed: 233 additions & 0 deletions

File tree

‎src/pages/storage-finder/README.md‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
# Storage Finder README
2+
3+
## Overview
4+
5+
The Storage Finder is an interactive web application that helps users choose the most appropriate NYU storage service for their research data based on their specific requirements. Users answer a series of questions about their data characteristics, usage patterns, and compliance needs, and the application filters and highlights suitable storage options.
6+
7+
## Data Sources
8+
9+
### Current Implementation
10+
11+
The storage finder uses static JSON files located in `src/data/storage-finder/`:
12+
13+
- `facet-tree.json` - Contains the questions (facets) and their answer choices
14+
- `service-list.json` - Contains the storage services and their characteristics
15+
16+
### Original Data Source
17+
18+
The data structure is designed to be compatible with Drupal-based content management systems. Ideally, this data would be downloaded from a Drupal endpoint that provides:
19+
20+
- **Facets taxonomy** - A two-level hierarchy representing questions and answer choices
21+
- **Services content type** - Storage services with their matching criteria and detailed information
22+
- **Service paragraphs** - Structured data fields for service comparison
23+
24+
For organizations wanting to use a Drupal instance to manage this data:
25+
26+
1. Set up the Finder module in Drupal following the original Cornell documentation
27+
2. Configure your questions, answer choices, and services through the Drupal admin interface
28+
3. Download the data from the Drupal REST API endpoints:
29+
- **Facet Tree**: `http://your-drupal-site.com/rest/facettree`
30+
- **Service List**: `http://your-drupal-site.com/rest/servicelist`
31+
4. Save the downloaded JSON files to `src/data/storage-finder/`:
32+
- Save facet tree data as `facet-tree.json`
33+
- Save service list data as `service-list.json`
34+
35+
## Adding or Modifying Data
36+
37+
> [!IMPORTANT]
38+
> Adding services and questions through the Drupal interface may be easier and provides a better user experience. If you have access to a Drupal instance with the Finder module, it is recommended to manage your data there. However, if you must modify the JSON files directly, follow the steps below carefully.
39+
40+
### Adding a New Question (Facet)
41+
42+
To add a new question to the storage finder:
43+
44+
1. **Edit `facet-tree.json`**:
45+
46+
```json
47+
{
48+
"id": "unique-id", // Must be globally unique across all facets and choices
49+
"name": "Your new question text?", // The question displayed to users
50+
"control_type": "radio", // "radio" (exclusive selection) or "checkbox" (multiple selections)
51+
"parent": "0", // Always "0" for top-level questions
52+
"weight": "order-number", // Controls display order; lower numbers appear first (e.g., "-1" appears before "0")
53+
"selected": false, // Always false for new questions
54+
"description": "Optional HTML description with help text", // If provided, an info button appears next to the question; clicking it opens a dialog with this content
55+
"choices": [
56+
{
57+
"id": "choice-id-1", // Must be globally unique across all facets and choices
58+
"name": "First answer choice", // The answer text displayed to users
59+
"control_type": "radio", // Should match parent's control_type
60+
"parent": "unique-id", // Must match the parent question's id
61+
"weight": "0", // Controls display order within the question; lower numbers appear first
62+
"selected": false, // Always false for new choices
63+
"description": null // Optional: HTML description for this specific choice
64+
},
65+
{
66+
"id": "choice-id-2",
67+
"name": "Second answer choice",
68+
"control_type": "radio",
69+
"parent": "unique-id",
70+
"weight": "1",
71+
"selected": false,
72+
"description": null
73+
}
74+
]
75+
}
76+
```
77+
78+
> [!IMPORTANT]
79+
> All `id` values (for both facets and choices) must be globally unique across the entire `facet-tree.json` file. Using duplicate IDs will cause filtering errors.
80+
81+
2. **Update existing services** in `service-list.json` by adding the appropriate choice IDs to their `facet_matches` arrays.
82+
83+
> [!WARNING]
84+
> When you add a new question, **all existing services** must be updated to include at least one choice ID from the new question in their `facet_matches` arrays. Otherwise, those services will be filtered out and hidden when users answer the new question.
85+
86+
#### Control Types
87+
88+
- **`radio`** - Only one choice can be selected (exclusive). Users can select a different option by clicking it.
89+
- **`checkbox`** - Multiple choices can be selected (inclusive). Users can select multiple options from the same question.
90+
91+
### Adding a New Storage Service
92+
93+
To add a new storage service:
94+
95+
1. **Edit `service-list.json`**:
96+
97+
```json
98+
{
99+
"id": "unique-service-id", // Must be unique across all services
100+
"title": "Service Name", // The service name displayed to users
101+
"facet_matches": ["choice-id-1", "choice-id-2"], // Array of choice IDs this service matches
102+
"summary": null, // Currently unused, set to null
103+
"field_data": { // Service details displayed in comparison table
104+
"field_eligibility": {
105+
"value": "Who can use this service", // HTML content displayed in the table
106+
"label": "Eligibility", // Column header text
107+
"weight": 1 // Controls row display order; lower numbers appear first
108+
},
109+
"field_limitations": {
110+
"value": "Any limitations or restrictions",
111+
"label": "Limitations",
112+
"weight": 2
113+
},
114+
"field_use_case": {
115+
"value": "Typical use cases",
116+
"label": "Use Case",
117+
"weight": 3
118+
},
119+
"field_storable_files": {
120+
"value": "Types of files that can be stored",
121+
"label": "Storable Files",
122+
"weight": 4
123+
},
124+
"field_permission_settings": {
125+
"value": "Permission and access control info",
126+
"label": "Permission Settings",
127+
"weight": 5
128+
},
129+
"field_links": {
130+
"value": "Relevant links and resources",
131+
"label": "Links",
132+
"weight": 6
133+
},
134+
"field_synchronous_access": {
135+
"value": "Real-time access capabilities",
136+
"label": "Synchronous Access",
137+
"weight": 7
138+
},
139+
"field_alumni_access": {
140+
"value": "Access after graduation/leaving",
141+
"label": "Alumni Access",
142+
"weight": 8
143+
},
144+
"field_backup": {
145+
"value": "Backup and recovery information",
146+
"label": "Backup",
147+
"weight": 9
148+
}
149+
}
150+
}
151+
```
152+
153+
2. **Ensure facet_matches accuracy**: The `facet_matches` array must contain at least one choice ID from each question the user answers.
154+
155+
> [!WARNING]
156+
> For each question in `facet-tree.json`, you must include at least one matching choice ID in `facet_matches`, otherwise the service will be filtered out and hidden when users answer that question.
157+
158+
**Example**: If a service is for "Public/Low Risk" data (ID "5"), "Faculty" users (ID "28"), and can be used for any purpose from "For what purpose will you be using this storage?" (IDs "33", "32", "35", "34", "36"), then include: `["5", "28", "33", "32", "35", "34", "36"]`. This example is not comprehensive—you must also add choice IDs from all other questions in `facet-tree.json` to ensure the service remains available regardless of what users select.
159+
160+
### Modifying Service Fields
161+
162+
To add, remove, or modify the fields shown in the service comparison table:
163+
164+
1. **Update the field structure** in `service-list.json` for all services
165+
2. **Modify the TypeScript interface** in `storage-finder.tsx`:
166+
167+
```typescript
168+
interface ServiceFieldData {
169+
[key: string]: FieldData;
170+
field_your_new_field: FieldData;
171+
// ... other fields
172+
}
173+
```
174+
175+
> [!TIP]
176+
> All services must have the same `field_data` structure for the comparison table to display correctly. If you add a new field, make sure to add it to every service in `service-list.json`.
177+
178+
### Data Structure Details
179+
180+
#### Facet Structure
181+
182+
- **id**: Unique identifier for the question
183+
- **name**: The question text displayed to users
184+
- **control_type**: "radio" or "checkbox"
185+
- **parent**: "0" for top-level questions
186+
- **weight**: Controls display order
187+
- **description**: Optional HTML help text
188+
- **choices**: Array of possible answers
189+
190+
#### Choice Structure
191+
192+
- **id**: Unique identifier for the choice
193+
- **name**: Answer text displayed to users
194+
- **parent**: ID of the parent question
195+
- **weight**: Controls display order within the question
196+
197+
#### Service Structure
198+
199+
- **id**: Unique identifier for the service
200+
- **title**: Service name
201+
- **facet_matches**: Array of choice IDs this service is compatible with
202+
- **field_data**: Object containing service details for comparison table
203+
204+
## Troubleshooting
205+
206+
### Common Issues
207+
208+
**Services not filtering correctly:**
209+
210+
- Verify `facet_matches` arrays contain correct choice IDs
211+
- Check that choice IDs in questions match those referenced in services
212+
213+
**New questions not appearing:**
214+
215+
- Ensure the question has a unique ID
216+
- Verify `parent` is set to "0" for top-level questions
217+
- Check `weight` for proper ordering
218+
219+
**Comparison table missing data:**
220+
221+
- Confirm all services have the same `field_data` structure
222+
- Verify field names match the TypeScript interfaces
223+
- Check for JSON syntax errors
224+
225+
## Inspiration
226+
227+
This storage finder was inspired by the **Finder Module** originally created by:
228+
229+
> Cornell Data Management Service Group and Cornell Information Technologies Custom Development Group (2018). Finder Module. Drupal 8. [https://github.com/CU-CommunityApps/CD-finder](https://github.com/CU-CommunityApps/CD-finder)
230+
231+
---
232+
233+
Last updated: October 2025

0 commit comments

Comments
 (0)