- 28 Oct 2024
- 13 minute read
- Print
- DarkLight
- PDF
Creating a Custom Dataset
- Updated 28 Oct 2024
- 13 minute read
- Print
- DarkLight
- PDF
Custom datasets are useful for storing data as you would on a person record, but for a different type of object or constituency not included among standard datasets in Slate.
🔔 Important!True to their name, custom datasets are entirely custom: many of the features taken for granted on the person record must be built from scratch in a custom dataset to achieve baseline functionality. These include: Display name, matching criteria, Lookup, and the "Create a New Record" form.
Before jumping into a custom dataset, familiarize yourself with the general principles of datasets. Your goal might be achievable with a Slate feature that requires a smaller commitment.
Start a conversation in the Community Forums to find the right case for a custom dataset.
Nine steps required to create a custom dataset
To make a custom dataset, you'll do the following:
Create the custom dataset
Create fields (including optional matching criteria fields) & prompts
Refresh the quartet
Add the query base (for legacy compatibility)
Create the Lookup (for legacy compatibility)
Create the Partial Match (for legacy compatibility)
Create the New Record form
Create the display name rule (if applicable)
(Optional) Create an index header rule
Step One: Creating the custom dataset
To create a custom dataset:
From the main navigation, select Database.
Under Records and Datasets, select Datasets.
Configure the following settings:
Status: Set to Active. Set datasets to Inactive when no longer in use without fear of losing data.
Folder: Keep custom datasets organized by placing it in a folder. Select Other to create a new folder.
Name: Enter the name of the dataset.
Type: A dataset’s type connects it to other Slate functionality. Enter a list of one or more of the following types separated by a comma:
school
: This dataset will autosuggest on the Schools table.
Only one dataset in your database should have this type.
In most databases, this type is already used for Organizations (Admission & Enrollment, Student Success) or Educational Institutions (Advancement).
location
: This dataset will autosuggest on the event field Location Name.
job
: This dataset will autosuggest on the Jobs table.
Only one dataset in your database should have this type.
In most Advancement databases, this type is already used for Companies and Foundations.
relation
: This dataset will autosuggest on the Relationships table.
Adds a Relationships tab to the dataset.
gift_fund
: Links the Funds dataset to the Fund field within the Giving table (Advancement).
giving
: Adds the Giving tab within the dataset (Advancement).Parent: If this custom dataset is a child dataset to a parent dataset, select the parent from the list.
Custom Icon (Optional): Choose a custom icon to represent the dataset records in Lookup.
Select Save.
With the custom dataset created, we'll move on to creating its fields and, optionally, prompts.
Step Two: Creating custom dataset fields & prompts
☑️ Prerequisite SkillsBecause of their similarity, an understanding of the creation of custom person-scoped fields and their associated prompts is recommended to create custom dataset fields. Read more about custom person-scoped fields and prompts before continuing with this section.
You can always start small and expand later. Create the fields you think you'll need now, then continue to the next steps.
You can always start small and expand later; create the fields you think you'll need now, then continue to the next steps.
Basic custom dataset fields
To create custom dataset fields:
From the main navigation, select Database.
Under Records and Datasets, select Fields.
Click New Field.
Configure the following settings:
Status: Active
Scope Category: Records
Scope: Select the name of your custom dataset from the list.
ID: Enter a unique, computer-friendly ID. Use an easily-identified prefix at the beginning of all custom dataset field IDs for easy recognition and sorting. For example, a Volunteer dataset might have field IDs such as "volunteer_email," "volunteer_firstname," and "volunteer_lastname".
Record Name Field
If your dataset records do not require a first and last name, use the Slate provided “Record Name” field as it does not need to be created custom.
Name: Enter a unique, human-friendly name. This should indicate to the viewer at a glance what the field is for. Will not be displayed externally.
Folder: Keep custom dataset fields organized by selecting a folder, or select Other to create a new one. We recommend placing custom dataset fields in a single folder so they can be viewed simultaneously.
Category: Select or create a Category for your fields, if desired.
Field Type: Select the appropriate Field Type for your field.
Click Save. Repeat for each field required in your dataset.
🔔 Important!Do not recreate standard field IDs.
📝 Note: Refresh the field cacheClick the link at the top of the Fields tool page to view newly created fields in forms and queries. Click Refresh Configurable Joins Library in Database to use the fields in Configurable Joins queries.
Some standard prompt keys require special configuration, including: bit, country, language, sex, state, and user.
When creating fields that use these prompt keys, select Custom Configuration (Advanced Use Only) from the Field Type select list. Under Prompt, choose the prompt key. Then, under Value, select Store Value.
Optional: Custom dataset matching criteria
☑️ Prerequisite Skills
Unlike person records, custom datasets do not come with matching criteria by default. Where person records match on first name, last name, birthdate and email, dataset matching criteria must be established using a dataset row key or a unique-for-merging field.
The key (or field) is used in Upload Dataset and upon form submission to match new records to existing records, allowing for the updating of existing records and preventing the creation of duplicate records.
Without a dataset row key or a unique field, all entries will create new records.
Custom dataset row key
The dataset row key:
is typically controlled by the institution (using something such as a unique ID number).
is universal for every record.
is unique for every record.
facilitates matching during import by referencing the related dataset.
📝 NoteWhen creating a dataset where a parent relationship will be established (such as Organization Contacts relating to a parent Organization), a key is required to enable matching during import.
To create a dataset row key:
Select Database on the top navigation bar and select Fields.
Click New Field. A popup appears.
Configure the following settings:
Status: Active
Scope Category: Records
Scope: Select the name of your custom dataset from the list.
ID: Enter a computer-friendly ID for the dataset row key. Use an easily-identified prefix at the beginning of all custom dataset field IDs for easy recognition and sorting. For example, a Volunteer dataset might have a dataset row key ID of "volunteer_dataset_row_key".
Folder: Keep custom dataset fields organized by selecting a folder, or select Other to create a new one. We recommend placing custom dataset fields in a single folder so they can be viewed simultaneously.
Dataset: Configure the field similarly to a typical person-scoped field, but select the name of the dataset within the Dataset setting.
Category: Select or create a Category for your fields, if desired.
Field Type: Dataset Row Key
Click Save.
Custom dataset unique for merging field
A unique-for-merging field:
is typically related to optional data points that are most likely controlled by a third party.
facilitates matching during import.
If you created a dataset key field, note that field is also unique for merging.
To create a unique-for-merging field:
Select Database on the top navigation bar and select Fields.
Click New Field. A popup appears.
Configure the following settings:
Status: Active
Scope Category: Records
Scope: Select the name of your custom dataset from the list.
ID: Enter a computer-friendly ID for the dataset row key. Use an easily-identified prefix at the beginning of all custom dataset field IDs for easy recognition and sorting. For example, a Volunteer dataset might have a dataset row key ID of "volunteer_dataset_unique".
Folder: Keep custom dataset fields organized by selecting a folder, or select Other to create a new one. We recommend placing custom dataset fields in a single folder so they can be viewed simultaneously.
Category: Select or create a Category for your fields, if desired.
Field Type: Select the appropriate Field Type for your field.
Unique for Merging: Set to Value contains a unique ID which identifies a single record for merging.
Click Save.
Optional: Custom dataset prompts
Unlike fields, prompts don't require a scope. They can be used with any field, regardless of those fields' scope (or scopes).
To create new prompts for use with your custom dataset fields, follow the directions provided in the Prompts article. If you have a lot of prompts to enter, consider uploading in batch.
Since prompts don't require a scope, you can safely use prompt keys already in your instance with your new custom dataset fields by selecting them from the prompt select list when creating your field. Reusing existing prompts keys like prefix (Mr., Ms., Mx., Dr.) rather than creating new ones keeps Slate lean and clean.
⭐ Best PracticeUse the same ID prefix in fields and in prompt keys. For example, if custom dataset field IDs begin with volunteer_, custom dataset prompt keys should also start with volunteer_.
📝 Note: Refresh the prompt cacheClick the link at the top of the Prompts tool page to view newly created prompts in forms and queries. Click Refresh Configurable Joins Library in Database to use the prompts in Configurable Joins queries.
Step Three: Refreshing the quartet
Refresh the quartet: that is, the prompts cache, the fields cache, the Slate Template Library (legacy tool), and the Configurable Joins library.
From the main navigation, select Database.
Under Queries, select Refresh Configurable Joins Library.
From the main navigation, select Database.
Under Records and Datasets, select Prompts.
Click the link to manually refresh the prompts cache.
On the right sidebar, select Fields.
Click the link to manually refresh the fields cache.
From the main navigation, select Database.
Under Configurations, select Slate Template Library (legacy tool).
Click the link to manually refresh the Slate Template Library.
With the custom dataset created, its custom dataset fields established, and the quartet refreshed, we can add the query base.
Step Four: Adding the custom dataset query base (for legacy compatibility)
💾 Dataset compatibility with legacy functionality
Steps 4, 5, and 6 of this article are included to ensure your dataset is compatible with any legacy tools that may depend upon legacy querying functionality (local/Slate Template Library queries). These steps are optional, but highly recommended. Completing these steps will require using database tools that are shown in gray text and marked as “(legacy tool)”. It is safe to do so.
Query bases open up the new dataset for use in the areas of Slate that do not yet support Configurable Joins, or where Local or Slate Template Library filters are still in use. If your institution is still using the legacy Lookup tool, this step is required to add your new dataset to that tool.
To add the query base for the custom dataset:
From the main navigation, select Database.
Under Configurations, select Slate Template Library (legacy tool).
In the Search Library bar, enter the name of the new dataset.
Under Query Bases, click Add. A popup appears.
Set Status to Active.
In the Order field, enter a number. This number determines the position of the new dataset in the Lookup tool relative to other record types.
Select a Read Permission for the dataset query base. Leave all other settings unchanged.
Click Save.
Step Five: Creating the Lookup (for legacy compatibility)
Creating a Lookup for a custom dataset displays it in the Record Lookup tool. Lookup also determines the columns that display for the Dataset Records in the Record Lookup tool.
To create the Lookup:
From the main navigation, select Database.
Under Configurations, select Slate Template Library (legacy tool).
Click the refresh the Slate Template Library link at the top of the page. A system dialog appears.
Click OK.
In the Search Library bar, enter the name of the new dataset.
Under Query Custom Exports, select one of the results from the list (it doesn't matter which) and click Add. A popup appears.
Configure the following settings:
Base: Select your new custom dataset.
Name: Enter Lookup
Default: Yes
Click Save.
With the Lookup record created, we'll create the partial match.
Step Six: Creating the partial match (for legacy compatibility)
Partial Match creates a “search box” that can be used in the Record Lookup tool to find specific Dataset Records.
To create a partial match:
From the main navigation, select Database.
Under Queries, select Query Exports/Filters.
Click Insert. A popup appears.
Configure the following settings:
Base: Select your new custom dataset
Name: Enter Partial Match
Where Clause: Enter (contains(d. [index], ))
#1 Operators: Enter CONTAINS
Click Save.
With the partial match created, we'll move on to the New Record form.
Step Seven: Creating the new record form
Similar to the default form that creates a new person record in Slate, you can make a form that creates records for other datasets.
Create the Form
Select Forms on the top navigation bar
Select New Form. A popup appears (pictured).
Configure each setting* as necessary.
Click Save
*Click here for a complete listing of all setting descriptions.
Adjust the Scope
Select Edit Form.
Select Edit Properties.
Change the Scope of the form to Dataset
Select the appropriate Dataset from the Dataset list.
Configure any other setting* as necessary.
Select Save.
*Click here for a complete listing of all setting descriptions.
Customize the Form
Default Fields
Prior to changing the scope, the scope of the form was person. Therefore the default person scoped form fields should be removed. Hover over each field and select the X that appears on the right side of the field. Confirm the deletion by clicking OK on the dialog box.
Dataset-Scoped Fields
Add in the desired form fields for the new dataset record, mapping to your new dataset-scoped custom fields.
Required Form Fields
Make sure to map a form field to the Name and Key or unique-for-merging field.
Record > Name
Mapping to Record > Name sets the display name for the dataset record. If the name is determined by a calculation of form fields (such as first name + last name), include a hidden form field using a calculation formula. The following example illustrates a typical dialog:
System Field to Record > Key
Mapping to the Key or unique-for-merging field ensures matching of form submissions based on the established matching criteria. To map to the Key, set the System Field to Record > Key. To map to the unique-for-merging field, set the System Field to Fields > the unique-for-merging field for the dataset.
📖 Further reading
Creating a new record form for a custom dataset
Integrating the New Record Form
Now that you have created a record creation form, you can use it to replace the default New Record button functionality.
📝 NoteThese steps depend on whether you have enabled the Configurable Joins Record Lookup early access feature.
If you did not complete Steps 4 - 6 above, follow the steps for Using Configurable Joins Lookup and ensure that configuration key is toggled in Database > Configuration Keys > Early Access Features.
Using Configurable Joins Lookup
Using Traditional Query Bases (for legacy compatibility)
Within the New Record form that was just created, right-click the New Registration link on the registration page, and then select Copy link address.
Select Database on the top navigation.
Select Query Bases (legacy tool).
Select the Query Base of the new dataset.
In the Create Record URL settings, paste the New Registration link that was previously copied.
Select Save.
When manually adding a record to the custom dataset, if an error appears that reads "Resource not available," this indicates that the query base has not been properly configured. Go to the Query Base with the Database tool and complete the Create Record URL setting.
Step Eight: Create a dataset display name rule
If your dataset represents people with a first and last name, or if you want to concatenate multiple field values to create the display name for a dataset record, you need to create a Dataset Display Name Rule. This ensures a display name is set for all records in your dataset, even if they are created in a manner that does not set a value for the Name (sys:name) field.
To create a custom dataset display name rule:
From the main navigation, select Database.
Under Automations, select Rules Editor.
Click New Rule. A popup appears.
Configure the following settings:
Name: Enter a descriptive, human-friendly name, such as Dataset Display Name Rule
Type: Configurable Joins
Category: Records
Base: Select your new custom dataset
Rule Type: Name
Folder (optional): Keep custom datasets organized by placing it in a folder, or create a new one by selecting Other.
Non-deterministic: Rule is deterministic and has an exclusive priority
Priority: 1
Status: Preview
Click Save. You are redirected to the rule configuration page.
In the Action section, set the Action to Replace Values from Formula.
Click the subquery icon to the right of ‘Export’. A pop-up window will open.
Within the Edit Part pop-up, configure the following settings:
Name: name
Type: Dependent subquery
Output: Concatenate
Row Separator: leave blank
Row Offset: 1
Row Limit: leave blank
Export Separator: insert a single space
Within the Edit Part pop-up, click ‘Export’. Select the exports you would like to use to generate the name for your dataset records (e.g., “First Name” and “Last Name”). Click Save.
Within the Formula box for your rule, type the @ symbol. The name of your subquery export (“name”) will automatically populate. Click the export name to auto-fill the name in the Formula box.
Click Save. You are redirected to the All Rules page.
Select the rule from the list.
Click Edit.
Set Status to Active.
✨ TipIf your database has many rules, you can search for your rule using the text box in the top right of the page containing the text “Search Rules…”
Step Nine (optional): Create index/header rules
To customize search criteria for your custom dataset, follow the the article Dataset Index/Header Rules - Customizing Dataset Record Search Criteria.