Creating a Custom Dataset

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 Slate's standard datasets.

  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. 

Seven steps required to create a custom dataset

To make a custom dataset, you must do the following: 

  1. Create the custom dataset
  2. Create fields (including optional matching criteria fields) & prompts
  3. Add the query base
  4. Create the Lookup
  5. Create the Partial Match
  6. Create the New Record form
  7. Create the display name rule (if applicable)

 

Step One: Creating the custom dataset

To create a custom dataset:

  1. From the main navigation, select Database.
  2. Under Records and Datasets, select Datasets.
  3. Select Insert. A popup appears.
  4. Configure the following settings*:

    • Status:  Inactivate datasets that are no longer used without fear of losing data associated with them.

    • Folder: Keep custom datasets organized by placing it in a folder, or create a new one by selecting Other. 
    • Name: Enter the name of the dataset.

    • Type: Connects the dataset to other Slate functionality. More than one type can be entered by separating each type with a comma. Enter one or more of the following types to link:

      • school: Autosuggests on the Schools table.

      • location: Autosuggests on the Location Name for events.

      • job: Autosuggests on the Jobs table.

      • relation: Autosuggests on the Relationships table. Adds a Relationships tab to the dataset.

    • 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.

  5. Click Save.

New_Dataset_Record_Popup.png

*Click here for a complete listing of all setting descriptions.

With the custom dataset created, we'll move on to creating its fields and, optionally, prompts.

 

Step Two: Creating custom dataset fields & prompts

  Prerequisite Skills

Because 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. 

Basic custom dataset fields

To create custom dataset fields:

  1. From the main navigation, select Database.
  2. Under Records and Datasets, select Fields.
  3. Click New Field. 
  1. 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".
    • 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.
  2. Click Save. Repeat for each field required in your dataset.

New_Custom_Dataset_Field.png

  Important!

Avoid using any of the standard field IDs for your custom dataset fields. Standard field IDs are listed in the Knowledge Base and at the top of the Fields Tool page in Database.

 

  Where are my fields?

Force_Refresh_Fields_Cache.png

Cached values are refreshed approximately every 5 minutes in production environments. Force-refresh the cache by clicking the force-refresh link at the top of the Fields tool. A new tab appears reading "OK," and you'll find the fields ready for use in forms and queries. Click Refresh Configurable Joins Library in Database to use the field 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.

Custom_Configuration_for_Certain_Prompt_Keys.png

 

Optional: Custom dataset matching criteria

  Prerequisite Skills

Unique for Merging

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 the update of existing records and preventing duplicate record creation. 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.

  Note

When 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:

  1. Select Database on the top navigation bar and select Fields.
  2. Click New Field. A popup appears.
  3. 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
  4. Click Save.

New_Custom_Dataset_Row_Key.png

 

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.

To create a unique-for-merging field:

  1. Select Database on the top navigation bar and select Fields.
  2. Click New Field. A popup appears.
  3. 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.
  4. Click Save.

New_Custom_Dataset_Unique_for_Merging_Field.png

 

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.

Select_Standard_Prompt_for_Custom_Dataset_Field.png

  Best Practice

If you want to create prompts specifically for use with your custom dataset, we recommend using the same ID prefix you used in your fields in your prompt key. For example, if you have field IDs beginning with volunteer_, your custom dataset prompt keys should also start with volunteer_.

  Where are my prompts?

Force_Refresh_Prompts_Cache.png

Cached values are refreshed approximately every 5 minutes in production environments. Force-refresh the cache by clicking the force-refresh link at the top of the Prompts tool. A new tab appears reading "OK," and you'll find the prompts ready for use in forms and queries. Click Refresh Configurable Joins Library in Database to use the prompts in Configurable Joins queries.

 

With the custom dataset created and its custom dataset fields established, the next step is to add the query base.

 

Step Three: Adding the custom dataset query base

After creating your fields and prompts, we'll add a new query base to the database. 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.

To add the query base for the custom dataset:

  1. From the main navigation, select Database.
  2. Under Configurations, select Slate Template Library.
  1. Click the refresh the Slate Template Library link at the top of the page. A system dialog appears.
  2. Click OK.

Refresh_Slate_Template_Library.png

  
  1. In the Search Library bar, enter the name of the new dataset.
  2. Under Query Bases, click Add. A popup appears.

Add_Query_Base_to_Slate_Template_Library.png

  1. Set Status to Active.

Insert_Record_in_Query_Bases_-_Set_Status_and_Read_Permission.png

  1. In the Order field, enter a number. This number determines the position of the new dataset in the 
  2. Select a Read Permission for the dataset query base. Leave all other settings unchanged.
  3. Click Save.

New_Query_Base_-_Lookup_Order.png

 

Step Four: Creating the Lookup

Creating a Lookup for a custom dataset displays it in the Record Lookup tool (the order in which it will appear was set in the previous section). Lookup also determines the columns that display for the Dataset Records in the Record Lookup tool.

To create the Lookup:

  1. From the main navigation, select Database. 
  2. Under Configurations, select Slate Template Library.
  3. In the Search Library bar, enter the name of the new dataset.
  4. Under Query Custom Exports, select one of the results from the list (it doesn't matter which) and click Add. A popup appears.
  5. Configure the following settings:
    • Base: Select your new custom dataset.
    • Name: Enter Lookup
    • Default: Yes
  6. Click Save. 

Create_Custom_Dataset_Lookup_Record.png

 

With the Lookup record created, we'll create the partial match.

 

Step Five: Creating the partial match

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:

  1. From the main navigation, select Database.
  2. Under Queries, select Query Exports/Filters.
  3. Click Insert. A popup appears.
  4. Configure the following settings:
    • Base: Select your new custom dataset
    • Name: Enter Partial Match
    • Where Clause: Enter (contains(d. [index], <operand>))
    • #1 Operators: Enter CONTAINS
  5. Click Save.

Create_Custom_Dataset_Partial_Match_Record.png

 

With the partial match created, we'll move on to the New Record form.

 

Step Six: Creating the new record form

Follow the steps laid out in the Custom Dataset New Record Form article.

 

Step Seven: 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:

  1. From the main navigation, select Database.
  2. Under Automations, select Rules Editor.
  3. Click New Rule. A popup appears.
  4. Configure the following settings:
    • Name: Enter a descriptive, human-friendly name, such as Dataset Display Name Rule
    • Population: Select your new custom dataset
    • Type: Name
    • Folder: 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
  5. Click Save. You are redirected to the rule configuration page.

Create_Custom_Dataset_Display_Name_Rule.png

  1. Set Action to Replace Values from Formula.
  2. Click Export.
  3. Select the fields that you will use to generate your display name.
  4. Double click an export. Rename it to be computer-friendly: for example, First Name becomes first. Repeat for each export.
  5. Enter a calculation formula using your exports as the variables. For records with a first and last name, a basic calculation is:
    isnull(@first + ‘ ‘, ‘’) + isnull(@last, ‘’)
  6. Click Save. You are redirected to the All Rules page.
  7. Select the rule from the list.
  8. Click Edit.
  9. Set Status to Active.

Configure_Rule.png

  What’s the deal with “isnull”?

In JavaScript, isnull lets us provide an alternative value if our export has no value. (For example, if a record was created with only a last name and no first name).

 

  Tip

If 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…”

Was this article helpful?
4 out of 22 found this helpful