How to Create Smart Lists and Best Practices

In this article, we'll explore the essential steps to create and leverage Smart Lists effectively. Smart Lists provide the data behind Lookup Smart Fields, Smart Layouts and Smart Layout Smart Fields. Smart Lists can be set up as part of a Professional Services engagement (especially if you’d like to integrate data from an external tool), or you can set up your own Smart List. In this article, we'll guide you through the process of creating your own Smart List as a CSV file, importing its structure, and uploading the data. This comprehensive guide will cover the fundamentals and best practices you need to know for seamless Smart List management.

1. Preparing your CSV files
   • Your Smart List structure & aAccepted Data Types
   • Your Smart List data
   • Saving your CSVs
2. Creating your Smart List
3. Smart List best practices
4. FAQs

1. Preparing your CSV files

Before you start you will need to set up 2 CSV files:

• Your Smart List structure 
• Your Smart List data

Samples of these CSV files can be found here.

Your Smart List structure

We suggest getting started by downloading the attached "Sample Experience Structure.csv" file. This file is based on an “Experience List", but can be modified to represent any other type of data that you’d like to make available for Smart Layouts or Smart Fields. However, row 1 contains all of the required parameters for the structure you will be defining. 

Column A, “Name” is the name of your data field. These will be the headings for your data columns that you will eventually upload. A couple of tips:

• The maximum length of the name field is 127 characters, but we recommend keeping it <100 characters for clarity and readability.
• The name cannot start with the word “system”.

Column B, “Type” is the data type. This describes the type of data the Smart Field should expect. As you enter these values, make sure they match the names of the Types listed below exactly, and there are no leading or trailing spaces. Here are the various data types that are supported:

• Short Text: Suitable for text up to 300 characters.
• Long Text: For more extensive text entries.
• Number: Accepts whole numbers only.
• Decimal: Handles numbers with up to two decimal points (e.g., 20.00).
• Date: Dates should be in the format yyyy-MM-dd.
• DateTime: Follows the ISO 8601 format (yyyy-MM-ddTHH:mm:ssZ), in UTC. When creating DataTime data in Excel, use the Ceustom format setting to get it into this format.
• Yes/No: Simple binary choice fields.
• Image: Requires a publicly accessible URL (including https:// prefix). 

Columns C-F, “Search; Filter; Visible; Required” only accept “Yes” or “No” values - again, make sure not to include leading or trailing spaces.

• Search: Indicates whether the field can be used to return search results (only supported for Short Text or Long Text field Types); you must have at least one field that is marked as Yes.
• Filter: Determines whether the field is used in Library Filters (only supported for Short Text, Long Text, or Yes/No field Types; Date and DateTime Types will be supported soon!)
• Visible: Determines whether the user will see this field in their search results
• Required: If marked as “Yes”, any data imported must contain a value for this field.

A value must be supplied for all columns mentioned above, except for the Required column.

When setting up your data structure, make sure you have at least one field that can serve the following functions:

• Search – Your list will need at least one field used to find the data record.
• Unique identifier – This field will be used to identify each distinct record in your list; must be a Short Text or Long Text field type.
• Title – This field shows as the Title for the record when searching (and any field you use for the Title must be set as Search = Yes)
• Description – the field that shows as the Description of the record when searching (needed for Smart Layouts only)

A Smart List can contain up to 100 fields.

Your Smart List data

While your Smart List data will be entirely unique to you and your business operations, the "Sample Experience Database.csv" file should just give you an idea of how your Smart List data CSV should look in relation to the structure import.

The most IMPORTANT thing to note is that the data column headers match those defined in the "Name" column of your structure import - otherwise, your data will not upload successfully.

Tip: When using Excel, to efficiently copy the "Name" fields from your "Structure" CSV file, simply select these fields, then utilize the "Paste Special" function, followed by "Transpose." This straightforward process allows you to seamlessly transfer the precise "Name" fields from your "Structure" file to your "Database" CSV":

Saving your CSVs

Once you have tailored your CSV files you can go ahead and save them. When saving these files make sure you are saving it as a CSV file. First navigate to File > Save As (1) > CSV UTF-8 (Comma delimited) (*.csv) (2) > Save (3):

And there you have it, your csv files are ready to be imported and uploaded.

Back to the top

Creating your Smart List

Now that you have your CSV data set prepped and ready for upload we can navigate our way back to the  QorusDocs Hub. From your Hub you will navigate to Manage > Smart Lists and click the Add button:

This is the area where you can import your Structure CSV file, which you intend to use for your Smart List. The easiest way to get this information in is to click and drag as demonstrated below:

1. Assign a name to your Smart List.
2. Drag/import your CSV with field definitions.
3. Pick a unique identifier (choose a distinctive, always unique field).
4. Click ‘Create’

Once you've imported your structure, you will be prompted to upload your Smart List data:

1. Select "Upload CSV"
2. Locate and select your Database CSV
3. Select "Open" to upload it

4. And there you have it: Your Smart List Structure and data are uploaded and ready for use. If you’re not ready to upload your Smart List data now, you can always come back later to do that. Simply go to Manage > Smart Lists, click on the gear icon next to the Smart List where you want to upload data, and select “Upload Data”.

Back to the top

Managing your Smart List Data

Managing your Smart List data is a simple, straightforward process. The best way to update your Smart List database is to download it, edit the CSV, and then replace it with a re-upload.

To download your current data, you will navigate to Manage >Smart Lists > in the Hub, and click on the gear icon next to the Smart List you want to update > Select "Download Data":

This will provide you with all your existing data, in its correct structure. You are now free to add your additional data to your CSV Database, without tampering with the structure (headers).

Once your data file is as you'd like it, you can go ahead and re-upload it. These steps are just as straightforward as before: Navigate to Manage > Smart Lists in the Hub, and click on the gear icon next to the Smart List you want to update. Select Replace Data:

This will then prompt you with an "Are you sure" window:

1. Select "Replace"
2. Locate your new data CSV
3. Select "Open"

And there you have it: your data has successfully been replaced.

Best Practices

These practices will help you effectively structure your Smart Lists for optimal performance and usability:

• Each row in your Smart List data must have a unique value for whatever field is specified as your Unique Identifier.
• If you marked a field as Required = Yes in your data structure, your Smart List data must always contain a value for that field.
• Short Text fields can support up to 300 characters.
• Number fields must contain whole numbers (no decimals).
• Decimal fields will be rounded to the nearest hundredth (e.g. 4.568 will become 4.57)
• Yes/No Type fields can also support values including True, False, 1, and 0; the values are not case sensitive.
• If you get stuck or have any additional questions about setting up your Smart List, contact our support team for assistance.

• • Back to the top

FAQs

What if I want to change the structure of my Smart List?

Changing the structure of your Smart List can be accomplished through preparation of an updated CSV file with your desired structure.

• If you haven’t yet uploaded your Smart List data, you can simply re-import your Smart List structure. To do this, go to Manage > Smart Lists. Click the gear icon and select “Edit Setup”. On the next page, click the “Import” button above your table of fields.
• If you have already uploaded your Smart List data, you’ll need to create a new Smart List. Go to Manage > Smart Lists and click the Add button.

What if I have changes to my Smart List data that include both additional records and updates to existing records?

Easy peasy! Just select Update Data from the gear icon and upload your new CSV file. Any records matching and existing unique identifier will be updated. Any records not matching an existing unique identifier will be added.

I’m uploading a Smart List file with a lot of records. Will I be locked out of QorusDocs while it’s uploading? How soon will my list be available to use?

If you have an especially large data set, we’ll be managing the upload in the background so you can still work on other things in the Hub even if the data upload takes some time. A success message will appear when the upload is completed.

If you have >10,000 records in your Smart List, we’d strongly recommend importing that data through a custom integration. Contact your Customer Success Manager for details.

What if I need my Smart List to look up data from another Smart List?

QorusDocs does support these types of relational list structures, but it does require a Professional Services engagement. Contact your Customer Success Manager for details.

What if my CSV data contains commas within the fields?

The nature of CSV (Comma Separated Value) files is that commas are used as an indicator of a separate field. If your data contains commas that should not be used to indicate a field split, you’ll need to “escape” your data. Note that Excel does this for you automatically, but if you’re working in any other application, you’ll want to put double quotes around and data value that contains commas.

Do Smart Lists support HTML data?

No. We recommend that any styling or HTML be incorporated into your Smart Layout template. Smart Lists are for hosting the data to insert into your template; templates are for hosting the styling and design.

Back to the top