Plum Insight Documentation
metadata_manager

Metadata Manager

Overview

The Metadata Database Manager allows users to create and edit databases associated with your survey(s). This association is made by means of the Metadata Filter and Metadata Store survey question types. Be sure to familiarize yourself with these questions types before utilizing a metadatabase in your surveys. A thorough understanding of how the Metasurvey question type works is critical when using a metadatabase.

Metadata Filter

The Metadata Filter question type provides a way to filter the rows of a metadatabase from within a survey. A Metadata Filter question allows you to choose a column from your metadatabase to apply a filter to. When the end user takes this survey, the value entered for the Metadata Filter question type will be the value the metadatabase is filtered on when the question is processed.

Example:

Assume you have the following metadatabase (represented as CSV):

“userID”,“FirstName”,“LastName”,“FavoriteColor”
“1”,“Dennis”,“Seidenberg”,“blue”
“2”,“Adam”,“McQuaid”,“red”
“3”,“Zdeno”,“Chara”,“black”
“4”,“Dougie”,“Hamilton”,“green”
“5”,“Tory”,“Krug”,“blue”
“6”,“Kevan”,“Miller”,“orange”

The Metadata Filter question type in the survey filters results on the “FavoriteColor” column.

What happens when a user takes the survey and enters the value “blue” for this Metadata Filter question?

Insight searches the metadata column “FavoriteColor” for the value “blue” and keeps the rows that have “blue” in the “FavoriteColor” column.

Based on the metadatabase in the example, the Metadata Filter matches the following rows:

“1”,“Dennis”,“Seidenberg”,“blue”
“5”,“Tory”,“Krug”,“blue”

Subsequent Metadata Filter questions that come after the “FavoriteColor” filter question will filter on the matched data set that resulted from the first “FavoriteColor” filter question.

For example, add another Metadata Filter question to the example survey after the “FavoriteColor” filter question that filters on the “LastName” column.

When the end user entered a value of “blue” for the first Metadata Filter question type, the question returned the following matches:

“1”,“Dennis”,“Seidenberg”,“blue”
“5”,“Tory”,“Krug”,“blue”

The same end user then enters a value of “Krug” for the second Metadata Filter question that filters on the “LastName” column. The filtered results at this point match both Metadata Filter questions. Therefore, the filter returned every row that contains a “FavoriteColor” value of “blue” and a “LastName” value of “Krug”. Based on these parameters, these Metadata Filter questions return a single row.

“5”,“Tory”,“Krug”,“blue”

You can only filter on each column once. For example, an attempt to filter the above results on “FavoriteColor” again, this time with a value of “red” would return no matches because there is no row that contains both a “LastName” value of “Krug” and a “FavoriteColor” value of “red.”

Note: When taking a survey over the phone it is only possible to filter on numeric data. End users cannot speak a phrase and match it to the metadatabase. Non-numeric values must be associated with a numeric ID that can be used to match the metadata.

Filtered metadata results can be used further with the Metadata Store question type.

Metadata Store

The Metadata Store question type stores the column values for any rows matched in your Metadata Filter question types.

This example uses the above example to demonstrate how to store column values from previously filtered and matched metadata rows.

Begin with the same metadatabase:

“userID”,“FirstName”,“LastName”,“FavoriteColor”
“1”,“Dennis”,“Seidenberg”,“blue”
“2”,“Adam”,“McQuaid”,“red”
“3”,“Zdeno”,“Chara”,“black”
“4”,“Dougie”,“Hamilton”,“green”
“5”,“Tory”,“Krug”,“blue”
“6”,“Kevan”,“Miller”,“orange”

Add a Metadata Filter on the “FavoriteColor” column with the end user selecting “blue” as their answer.

“1”,“Dennis”,“Seidenberg”,“blue”
“5”,“Tory”,“Krug”,“blue”

To store some values from the matched metadata rows add a Metadata Store question to your survey.

When adding a Metadata Store question type, you need to specify which metadatabase column you wish to store as the question's answer. For example, assume you chose to store the “userID” column.

Note: Be sure to place the Metadata Store question after the Metadata Filter questions in your survey. To be effective, it is necessary to filter the metadatabase before storing values from it.

With a Metadata Store question created to store values from the “UserID” column, Insight stores the following values as the answer to the Metadata Store question, based on the matched rows:

“1”,“5”

This is how you filter a metadatabase on columns using the Metadata Filter question type and then store the column values from the matched rows using the Metadata Store question type.

Layout

This is the Metadata Manager interface.

  1. Metadatabase Name: The name of the currently selected metadatabase. You can edit the name by clicking on it and modifying the text.
  2. Metadatabase Description: An optional, brief description for the metadatabase. You can edit this description by clicking on it and modifying the text.
  3. Save: Save any changes you have made to the metadatabase. This includes changes to the name or description of the metadatabase and the removal/modification/addition of rows, columns, and cells. Note: No changes are permanent until the changes are saved.
  4. Close: Close the current metadatabase and takes it out of edit mode. Note: All unsaved changes will be lost when the metadatabase is taken out of edit mode.
  5. Download CSV: Download your entire metadatabase to a CSV file. This is a quick way to create a new metadatabase from a CSV file or to make bulk changes to your database in an external program like excel, which can be more convenient than using the editor itself.
  6. Upload CSV: Displays a dialog that allows users to upload a CSV file to overwrite the existing metadatabase. Uploading a new CSV overwritse the columns and data of the current metadatabase with the columns and data in the uploaded CSV file. It is recommended to use this feature in conjunction with the Download CSV function in order to make bulk changes to a metadatabase in an external program and then overwrite the old database by uploading the new, modified CSV file.
  7. Metadatabases: Select a metadatabase to put it into edit mode. A metadatabase must be in edit mode for a user to modify it. Metadatabases associated with a survey will have a purple icon in this list. Hovering over the database displays the name of any surveys associated with that metadatabase.
  8. Delete Metadatabase: Click the trash can icon for a metadatabase to delete it. Insight prompts users with a dialog window to confirm the deletion of a metadatabase.
  9. Add Row: Add a new, empty row at the end of your metadatabase.
  10. Add Column: Add a new column to your metadatabase. The default naming of new columns follows the “ColumnX” convention where x is the numeric value for the column. For example, adding a column to a metadatabase with four columns will default to the name “Column5” because it is the fifth column in your metadatabase.
  11. Modify Column Name: Click on the column name to modify it.
  12. Delete Column: Click on the 'x' when hovering over a column name to delete the column. If any surveys utilize this column, Insight prompts users with a dialog window to inform them of that fact and asks to confirm the deletion.
  13. Delete Row: Click on the 'x' when hovering over a row number to delete that row.

Creating a Metadatabase

To create a new metadatabase, first make sure that no metadatabase is currently selected in the list of metadatabases. Then click the “New Metadatabase” button. This will open a dialog window.

This window contains three inputs:

  • Database Name: The name for the new metadatabase; this is the only required field. Metadatabase names can range from 1-255 characters. Note: Each metadatabase requires a unique name. Insight does not support duplicate metadatabase names.
  • Database Description: Enter an optional description for the metadatabase in this field. The metadatabase description can range from 1-255 characters. It is not necessary to add a description for the metadatabase and this field can be left empty if desired.
  • Upload CSV: Use a CSV file to pre-populate the columns and data of a metadatabase. Uploading a CSV file is optional. Failure to do so simply results in a new, empty database.

Click the yellow “Submit” button to create the metadatabase. To dismiss this window and abandon the creation of a new database click the grey “Cancel” button or the 'x' in the upper right hand corner.

Creating An Empty Metadatabase

To create a new, empty metadatabase:

  1. Make sure no metadatabase is currently selected in the metadatabase list.
  2. Click “New Database” to open the “create metadatabase” dialog window.
  3. Fill in the Database Name and, optionally, the Database Description fields.
  4. Click “Submit.”

A new metadatabase appears in the list of metadatabases. If any errors occur during this process, such as a metadatabase with a duplicate name, the dialog window will remain open and display the corresponding error.

Note: when creating an empty metadatabase the default columns follow the “ColumnX” convention, e.g., “Column1”,“Column2”,“Column3”,“Column4”,“Column5”.

Creating a Metadatabase from an Existing CSV

To create a metadatabase and pre-populate it with columns and data from a CSV file:

  1. Make sure no metadatabase is currently selected in the list of metadatabases.
  2. Click “New Database” to open the “create metadatabase” dialog window.
  3. Fill in the Database Name and, optionally, the Database Description fields. Then click “Select Files” to browse your computer for the CSV file and upload it.
  4. Once the upload completes, click “Submit.”

The dialog window closes and the new metadatabase appears in the list of metadatabases. If any errors occur during this process, such as a metadatabase with a duplicate name, the dialog window will remain open and display the corresponding error.

Viewing/Editing a Metadatabase

Users that need to make extensive changes to a metadatabase, may prefer to download an entire metadatabase, make edits in an external program, like Excel, and then upload that modified file to Insight, overwriting the current metadatabase. Insight's user interface allows users to modify a metadatabase within the platform as well.

Note: It is necessary to “Save” any changes made to a metadatabase before selecting a different metadatabase or navigating away from the page. Any unsaved changes will be lost.

Editing the Metadatabase Name and Description

When the metadatabase is in edit more, click on either the metadatabase name or description to edit them. This makes the respective field editable, allowing users make changes as necessary.


Adding a Column

To add a new column to a metadatabase, select a metadatabase in the metadatabase list and put it into edit mode. Click “Add Column” in the upper right hand corner of the window. This adds a new column to the metadatabase with the naming taxonomy of “ColumnX” where X represents the number of columns in the metadatabase. Click the name of the newly added column to modify its name.

Adding a New Row

To add a new row to a metadatabase, select a metadatabase in the metadatabase list and put it into edit mode. Click “Add Row” at the bottom of the metadatabase window. This adds a new, empty row to the metadatabase. Click in the cells of the row to add data to the cells in that row.

Note: Adding a row to a large database shifts the view of the metadatabase to display the new row, located at the bottom of the list of rows.

Deleting a Row

To delete a row, hover over the row number and a small red 'x' appears in the upper right hand corner of the cell. Clicking on the red 'x' removes the row from the metadatabase.

Deleting a Column

To delete a column, hover over the column name and a small red 'x' appears in the upper right hand corner of the cell. Clicking on the red 'x' removes the column from the metadatabase.

If the column being deleted is used in any survey questions, Insight prompts users with a dialog window to confirm the column deletion. Deleting a column that is in use removes any metadata questions from your surveys that reference the column. Note: Insight automatically saves the metadatabase after deleting a column with dependencies.

If no surveys utilize the column then it will simply be deleted.

Editing a Cell

The edit the value in a specific cell of the metadatabase, simply click in the desired cell and enter or modify the data there as desired.

Saving Changes

It is necessary to click the 'Save' button to commit changes to a metadatabase. All edits remain as pending changes until the 'Save' button is clicked. When conducting a significant number of edits to a metadatabase within the Insight platform, it is best to click the 'Save' button regularly to ensure all the changes are saved.

Deleting a Metadatabase

To delete a metadatabase, select the metadatabase from the metadatabase list. Click the trash can icon next to the metadatabase name. This opens a dialog window to confirm the metadatabase deletion.

Clicking “Yes” confirms the deletion. Clicking 'Close' or the 'x' in the upper right of the dialog window dismisses the window without making any changes to the metadatabase.

Deleting With Dependencies

Any metadatabase currently being utilized by a survey has a purple icon displayed in the metadatabase list.

Hover over the purple database icon to see a list of surveys that utilize a given metadatabase. Deleting an active metadatabase results in the the removal of all metadata question types that use that metadatabase from all surveys that are dependent on the metadatabase.

In other words, deleting an active metadatabase deletes all of the questions associated with that metadatabase in all of your surveys.

Downloading a Metadatabase

To download a metadatabase as a CSV:

  1. Select the metadatabase from the metadatabase list and put it in edit mode
  2. Click “Download CSV”
  3. Insight outputs a CSV file of the metadatabase to view or save to a local computer

Uploading a Metadatabase

Uploading a CSV overwrites metadatabase columns and data values.

  1. Select the metadatabase from the metadatabase list and put it into edit mode
  2. Click “Upload CSV”
  3. Click “SELECT FILES”
  4. This opens a window that allows users to navigate their local drive to select a file to upload.
  5. Once the upload completes, click “Yes” to commit the overwrite. To dismiss the upload and not overwrite the existing metadatabase click “Close” or the “x” in the upper right corner of the dialog window.

Formatting Metadatabase CSV

CSV files uploaded to Insight for use as a metadatabase must be properly formatted.

The first row of the CSV file must only contain the column names. If actual data is in the first row, Insight will recognize that data as the column names. An example header is:
“userID”,“FirstName”,“LastName”

Every row afterwards should contain the actual data. To match the above header, we could have the following sample rows:
“1”,“Jerry”,“Garcia”
“2”,“Harry”,“Nilsson”
“3”,“David”,“Bowie”
“4”,“Paul”,“Simon”
“5”,“George”,“Harrison”

Compiled together the complete CSV file looks like:
“userID”,“FirstName”,“LastName”
“1”,“Jerry”,“Garcia”
“2”,“Harry”,“Nilsson”
“3”,“David”,“Bowie”
“4”,“Paul”,“Simon”
“5”,“George”,“Harrison”

If you have difficulty formatting a metadatabase, one workaround is to create a new, empty metadatabase in Insight. Then, populate a single row with data. This does not need to be any specific data as this is simply for formatting purposes. Next, download the CSV using the “Download CSV” button. Open the CSV file and modify it as necessary.

To convert a pre-existing .XLX or .XLSX to a CSV, be sure to select “save as” when saving the file and changing the file type to CSV.

metadata_manager.txt · Last modified: 2016/07/20 14:31 by jason