Using the Repository

Although it is possible to copy items directly from one survey into another (as described in Reusing Questions and Other Survey Objects), repository items – questions, question tables, and Text/HTML items – provide several advantages over items borrowed from other surveys.

Guaranteed Consistency

Illume maintains some restrictions on repository items to guarantee that they are consistent on all surveys in which they appear. A repository item’s scale value codes, for example, cannot change. This allows for reliable cross-survey queries.

Cross-survey Queries

Because a repository item includes a common set of scale value codes in all surveys in which it appears, it is possible to query responses to that question across multiple surveys.

For example, a repository question asks “What is the most important factor in your decision to purchase a computer?” The options are: 1) Price, 2) Features, and 3) Ease of Use.

This question can be used in a dozen different surveys spanning a period of several months or years.

Because repository restrictions guarantee that this question is structurally the same across all of the surveys in which it appears, it is possible to run a cross-survey query on this question that will examine all of the question’s responses across all of the surveys in which it appeared.

Parameterization

In many cases, a question must be reused with only a slight change to the question prompt. For example, it might ask “How satisfied are you with your purchase of such-and-such product,” changing only the name of the product from one survey to the next.

This question can be added to the repository with a placeholder in the place of the product name, and then use a survey parameter to replace the placeholder on each survey in which the question appears.

The question prompt would look something like this:

• How satisfied are you with the purchase of {ParamValue:ProductName}?

Because each survey enables the definition any parameters, this question becomes reusable on any number of product surveys.

For more information on how to use placeholders and survey parameters, see “Working with Survey Parameters and Piping Data”.

Universal Access

There may be cases in which a designer wants to reuse a question from an older survey, but the designer does not have permission to view the survey itself. When this happens, the designer has no way of accessing a potentially useful resource.

The repository provides a way to work around this limitation without compromising the security of the survey to which a designer is legitimately denied access. By adding the item to the repository, it is available to all designers.

Ease of Location

While Illume’s Survey Search enables users to locate entire surveys by category, the repository’s search tool enables users to locate individual questions, question tables, and Text/HTML items. This provides more convenient access for those users who want to locate only a single item for reuse.

Accessing the Repository

The Repository Explorer can only be accessed if the user is connected to an Illume Server. The links to the Repository will remain for objects while Working Locally, but items cannot be added or edited in the Repository.

The repository uses a system of categories and values to organize its contents.  These serve as labels to assist in organizing and finding the contents.  The repository’s categories and values are similar in concept and in use to survey categories and values; however, the repository maintains its own distinct category/value list that is not associated in any way with the survey category/value list.

The repository can hold Questions, Question Tables, and Text/HTML items. It cannot hold Collections.

To add an item to the repository, follow these steps:

1. In the right pane of the Survey Editor, right click on the item to add to the repository and choose Submit Item(s). This presents the Repository Submission dialog.

   

2. (Optional) Type in any comments to attach to this item in the repository. These comments will appear in the item’s History field when users choose to view the item’s details
3. (Optional) Choose a category under which to file this item
4. (Optional) If a category has been selected, select a value under which to file the item
5. Click OK
6. When asked to save the submission, click OK , or the repository submission will be aborted

   

NOTE: It is possible to submit more than one item at a time to the repository. Hold down the Control key on the keyboard while clicking on each of the items to add, then follow the steps above.

The item will appear in the repository, under the category and value that was specified. If a category and value were not specified, the item will appear in the Uncategorized folder. Categories and values can be assigned to the item even after it has been submitted.

If the item does not appear in the Repository Viewer, choose View Refresh to update the view.

Notice that the item appears in red text. This indicates that it has not yet been approved for reuse. Until it is approved, no users will be able to drop it into their surveys.

See “Approving Repository Items” for information on how to approve a newly submitted item.

Using the Repository Drop

When a designer with sufficient privileges is editing a survey, it is possible to add a question to the repository using the Repository Drop.

Drag the question to the bottom left of the survey editor into the Repository Drop folder. Then follow the steps for adding an item above.

The first step to organizing a searchable collection of repository items is to define the categories under which the items will be organized. The repository maintains its own set of categories and values.

The User must be an Administrator, Publisher, or Power User to add or edit repository categories and values. The following instructions refer to the Repository Explorer, which can be reached from the Survey Manager by choosing View \ Repository

To add repository search categories:

1. Select Repository \ Add/Edit Repository Search Categories from the Repository Explorer

   

2. Type the name of a new repository category in the Name field.
3. Click the Add button next to the name field to add the new category

   

4. The newly-added category should be highlighted in the list of categories. While this item is highlighted, type a value into the Value field below, then click the Add button next to the Value field

   

5. Repeat step 4 to add as many values as needed to the new category. Repeat steps 2 and 3 to add more categories.
6. Click Done when finished. This will close the Category Editor and save your changes.

   

To add values to a category that already exists, simply click on the category in the Categories list and follow step 4 above.

Editing repository search categories and values essentially means changing their names. When the name of a search category or value is changed, the repository items filed under that category/value retain their association to the category/value.

For example, if there are ten questions filed under a category named “Personal Questions”, and the name of that category is changed to “Demographics”, the ten questions will now be filed under “Demographics”.

To edit repository categories and values:

1. Select Repository \ Add/Edit Repository Search Categories from the Repository Explorer
2. Click on the name of the category or value you want to edit
3. To change the category name, type the new name into the Name field and click Replace
4. To edit a value within the category, click on the value in the Category Values list
5. To change the value name, type the new name into the Value field and click Replace

   

Deleting Categories

To delete categories, follow these steps:

1. Select Repository \ Add/Edit Repository Search Categories from the Repository Explorer
2. In the Categories list, click on the name of the category to delete
3. Click the Delete button

   

NOTE: When a Category is deleted all of the category’s values are deleted as well. The repository items associated with the category will remain, but they will no longer retain their association to the deleted category.

Deleting Category Values

To delete category values, follow these steps:

1. Select Repository \ Add/Edit Repository Search Categories from the Repository Explorer.
2. In the Categories list, click on the name of the category that contains the value to be deleted.
3. In the Values list, click on the name of the value to be deleted.
4. Click the Delete button beneath the Category Values list. This will delete the value. (If the Delete button that appears under the Categories list is clicked, the entire category will be deleted!)
5. Read the confirmation message carefully and click OK to commit the change.

   

NOTE: When a category value is deleted, the repository items associated with that value will remain, but they will no longer retain their association to the deleted value.

In other words, if there are ten repository questions filed under “Race Category”, and the value “Race Questions” is deleted from the “Demographics” category, there will still be ten questions, but they will no longer be able to be located by searching for repository items belonging to the “Demographics”, “Race Questions” category.

Once categories and values have been defined to organize repository items, each item can be associated with one or more values. This enables Illume users to easily locate repository items using the Repository Explorer’s search tool.

For more background on the category/value system, See “Understanding Survey Search Categories and Values”.

Adding Categories and Values to a Repository Item

Only Users with Administrator or Reviewer roles can associate repository items with categories and values.

To associate repository items with categories and values, follow these steps:

1. Locate the item to work with in the right pane of either the Browse Categories or Search Results tab of the Repository Explorer.
2. Right click on the item and choose Edit Category Values from the context menu.
3. In the list of Categories, click on the name of the category to which this item should belong. Notice that all of the values belonging to this category appear in the list to the right.
4. Click on a value in the list, and click the Add button to associate the value with this item.
5. Repeat steps 3 and 4 for each of the values to associate.
6. Click OK to save the changes and close the editor.

   

Removing Categories and Values from a Repository Item

Only Users with Administrator or Reviewer roles can edit a repository item’s category values.

To remove categories and values from a repository item, follow these steps:

1. Locate the item to work with in the right pane of either the Browse Categories or Search Results tab of the Repository Explorer.
2. Right click on the item and choose Edit Category Values… from the context menu.
3. In the category/value list at the bottom of the Categories/Values editor, click on the value to remove.
4. Click the Remove button.
5. Repeat steps 3 and 4 for each of the values you want to remove.
6. Click OK to save your changes and close the editor.

   

The right pane of the Repository Explorer’s Browse Categories tab and the right pane of the Search Results tab each display a lists of items.

The Repository Explorer’s View menu enables you to choose whether the text describing each item in the list comes from the item’s prompt or from the item’s description.

Choose View \ View Question Text to switch the view back and forth between the prompt text and description.

View Description

View Prompt

NOTE: For Question Tables, the View Question Text option displays the collection’s instructions. For Text/HTML objects, it displays nothing but the Text/HTML icon.

NOTE: Only Users with Administrator or Reviewer roles can edit a repository item.

To edit an item in the repository:

1. Locate the item in the right pane of either the Browse Categories or Search Results tab of the Repository Explorer.
2. Double click on the item in the right pane of the Repository Explorer. This causes an editable version of the item to appear.
3. Edit the item as needed. (Descriptions on how to use the various types of editors are available in the section “Using the Survey Designer.”)
4. Click OK.
5. A dialog asks “Would you like to approve these changes for immediate use?” Answering “yes” will save the changes and make the item immediately available to all designers. Answering “no” will save the changes and leave the item unavailable to designers until the changes have been approved.

A Note on Versions

Once the item has been edited, its version number increases by one. Any surveys that include this item will continue to include the item without the changes just made.

This is by design, for the following reasons:

Assume that a question in the repository asks “What is your age?” The question has three response options:
1) Under 30, 2) 31-60 and 3) Over 60. The version number of the question is V1.

Three surveys include this question, and two of them are running.

A user goes into the repository and edits the question so that the options are now: 1) Under 18, 2) 18-35, 3) 36-50,
4) 51-64, 5) 65 or older.

When the user saves these changes, the version changes to V2.

The three existing surveys that include this question will continue to include version V1 of the question because changing this question in a published survey would likely result in unreliable data.

Participants who saw version V1 of the question would have been indicating an age “Over 60” when they checked option number 3, while those who saw version V2 of the question would have been indicating an age between 36 and 50 when checking option number 3.

In such a case, there would be no way of knowing what a participant intended when he or she chose option 3 in response to the question.

This is why changing an item in the repository does not automatically change the item in surveys that have included the item prior to the change.

If you want your survey to include the updated version, you must open the survey and manually update the repository item using the Get Latest Repository Version menu option.

Items in the repository are available for reuse only when they are approved. Approved items are displayed with black text. Unapproved items are displayed with red text.

To approve a repository item:

1. Locate the item in the right pane of either the Browse Categories or Search Results tab of the Repository Explorer.
2. Right click on the item and select Approve for General Use from the context menu.

   

3. (Optional) Add comments. These will be displayed as part of the item’s history, wherever the history appears.
4. Click OK

   

To view all items in the repository:

1. Click on the Search tab of the Repository Explorer.
2. Click the Clear All Search Criteria button.
3. Click the Search button.

   

All repository items will appear.

NOTE: Retired items will not appear. To see retired items the User must be an Administrator, and must specifically search for retired items. See “Reactivating Repository Items”.

There are two ways to see detailed information about repository items:

Viewing Item Details

To get more information about an item:

1. In the right pane, right click on the item
2. Choose “View Item Details”

   

Illume will present the following items:

• Creator – The name of the Illume user who added this item to the repository.
• Latest Version – The current version number of the item. Each time the item is revised, the version number increases by one. This number is important! See the note on versions under Editing Repository Items.
• Description – This is a brief text description of the item.
• Search Category Values – This is a list of all of the repository categories and values with which this item is
• associated. Note that this refers to repository categories and values, which are separate from survey search categories and values.
• Survey References – A list of all surveys that use this repository item. Each entry in the list follows the format Survey Name (ITEM NAME). ITEM NAME is the name under which the repository item appears in the survey.
• History – This is a brief description of any changes or administrative actions (such as approval) that have been applied to this item.
• HTML Preview – This is what the item looks like to a participant.

  

Editing Repository Items

Double click on an item to see the item in an editor.

Questions will appear in the usual question editor, question tables in the Question Table Editor, and Text/HTML items in the Text/HTML editor.

Edits to a repository item have to be approved.  Surveys which consume an older version of the repository item will continue to use the older version until the repository items in the survey are explicitly updated.

To see a list of what’s in the repository, select View \ Explore Repository… from the DatStat Illume Survey Manager’s menu.

The repository opens with the Browse Categories tab showing. In this view, all repository items are organized into folders that correspond to your organization’s custom-defined categories and values for repository items.

Click on any folder and the folder’s contents will appear in the right pane of the Repository Explorer.

To get more information about an item in the right pane, right click on it and choose View Item Details.

To reach the repository search screen follow these steps:

1. Make sure you are Logged in.  You will not have access to the repository if you are not logged in.
2. Select Repository – Explore from the DatStat Illume Survey Manager.
3. Click the Search tab.

Searching by Category and Value

To search by category and value:

1. From the Search for list, choose the type of item to locate, or choose “All” to search through all repository items.
2. From the Item status list, choose the status of the item(s) to find, or “All” to include items of any status in the search.
3. Choose a category from the Category list.
4. Choose one or more values from the Value list. Notice that the contents of the value list changes when the category changes.
5. Choose either “is” or “is not” from the list of conditions.
6. Click the Add button to add the conditions and values to the search criteria.
7. Repeat steps 3-6 to add criteria to the search.
8. Select “And” or “Or” to group the criteria (details below).
9. Click Search .

The Search Results tab will appear, displaying the results of the search.

Searching the Text of Prompts and Scale Value

To search the texts of question prompts and scale values:

1. Within the search tab, select the tab labeled Word Search.
2. From the Search Text list, choose whether to search question prompts, or scale values, or choose “All” to search both.
3. Select either “contains” or “does not contain.”
4. Type a search word or phrase into the Phrase field.
5. Click the Add button.
6. Repeat steps 3-5 to add more conditions. (For example, a query could look for questions that contain “automobile” and do not contain “Yugo.”)
7. Select “And” or “Or” to group the criteria (details below).
8. Click Search.

Grouping Criteria with And / Or

Grouping search criteria with “And” will almost always produce fewer results than grouping search criteria with “Or.”

When grouping search criteria with “And,” it is telling Illume to list items that match ALL of the criteria specified.

When grouping search criteria with “Or,” it is telling Illume to list items that match ANY of the criteria specified.

While “Or” searches generally return a broader range of results, “And” searches return a very specific set of results.

Mixing ‘And’ and ‘Or’ in a Single Search

In some cases, a search may use both “And” and “Or” conditions in a single search. This can be done, to a limited extent, when performing a category/value search.

If more than one value from the value list (as described in step 6 under searching by category/value above)is checked, and the Add button is clicked, the values appear on a single line in the list of criteria, and they are separated by “or.”

Several sets of values can be added in this way. After adding all of the sets, choose “And” as the group option, the result will be a set of criteria like this:

Demographics is ‘Age’ or ‘Gender’ And Disease is ‘Colorado tick fever’ or ‘Measles’ or ‘Mumps’

The repository Search tool will include only values belonging to a common category in these one-line “or” conditions.

NOTE: And / Or cannot be mixed when in the Word Search tab.

Restoring the Full Repository List

After running a search, the survey list will display only those items that met the criteria. To restore the repository list so that all items appear, go back to the Search tab, click Clear All Criteria , and then click Search again.

Adding an Item from the Repository to a Survey

While working within a survey it is possible to explore the repository and use an item in the open survey.

While in the Survey select Repository \ Explore

Follow the steps in “Browsing the Repository” to find the correct Item.

Drag the Item from the repository to the survey.

If there is already an item in the survey with the same name, a dialog box will appear prompting for a new name.

Breaking a Link to the Repository

If survey items exist in the repository, it will not be possible to edit certain properties of that item while editing the survey.

Repository items are marked by one of the following icons:

• Repository Text/HTML Item
• Repository Question
• Repository Question Table

To edit these properties, it is possible to break the item’s link to the repository.

1. Click on the item in the right pane of the Survey Editor.
2. Choose Break Link from the Repository menu. (This option is also available from the context menu by right-clicking on the repository item.)

Repercussions

One of the benefits of repository items is that they are guaranteed to be the same in all of the surveys that use them. This makes them ideal for Cross Survey Views, which show responses to similar questions across multiple surveys. Once the link is broken it cannot be re-linked.

An Alternative to Breaking the Repository Link

One alternative to breaking the question’s link to the repository is to update the question directly in the repository, and then to get the latest repository version. Updating the question in the repository will not affect any existing surveys that use the repository item. All future surveys, however, will use the newest version of the item.

NOTE: Updating repository items may require special privileges. For more information, See “Editing Repository Items and Getting the Latest Repository Version”.

If a survey includes an item from the repository, and the item has been updated in the repository after it was added to the survey, it will need to be updated manually to retrieve the updated version.   Illume will not automatically update repository items in a survey, for reasons described in “Editing Repository Items”.

Repository items are marked by one of the following icons:

• Repository Text/HTML Item
• Repository Question
• Repository Question Table

To get the latest repository version of an item, click on the item in the right pane of the Survey Designer and choose Get Latest Version from the Repository menu. (This option is also available from the context menu by right-clicking on the repository item.)

If there is a newer version to get, Illume will display a message confirming that it has retrieved the latest version.  Otherwise, Illume will not present any message.

NOTE: All Repository linked items in a survey can be updated at the same time.

1. Click on Repository in the Menu Bar
2. Select Update All Repository Items

To retire a repository item means to make it unavailable for use in future surveys. If you retire an item that has previously been included in published surveys (including currently running surveys), those surveys will not be affected: they will still include those items.

To retire a repository item, the User must be an Administrator, Publisher or Power User, and the item itself must be approved. (Unapproved repository items cannot be included in surveys, so there is no point in retiring them. An unapproved repository item can be deleted if it is of no use.

Follow these steps to retire a repository item:

1. Locate the item in the right pane of either the Browse Categories or Search Results tab of the Repository Explorer.
2. Right click on the item and select Retire from the context menu.

3. Click OK in the warning dialog.

4. (Optional) Add any comments that may be helpful, such as the reason for the item’s retirement. This will become part of the item’s history, and may be helpful in the future when deciding whether or not to reactivate the item.

5. Click OK

Administrators can reactivate retired repository items. See “Reactivating Repository Items” for more information.

Illume Administrators can reactivate repository items, making them once again available to users for inclusion in new surveys.

Follow these steps to reactivate a repository item:

1. Click on the Search tab of the Repository Explorer.
2. In the Search for list, choose either All or the specific type of item to reactivate.
3. In the Item status list, choose “Retired.”
4. Click the Search button.

5. The Search Results tab with a list of folders in the left pane and a list of items in the right pane will open. The All Results folder should be selected.
6. In the right pane, right click on the name of the item to reactivate, and select Reactivate from the context menu.

7. Click OK in the warning dialog.

8. (Optional) Enter comments to describe why the item is being reactivated. These comments become part of the item’s history.

9. Click OK

To delete an item from the repository:

1. Locate the item in the right pane of either the Browse Categories or Search Results tab of the Repository Explorer.
2. Right click on the item and select Delete from the context menu.

3. Click OK in the warning dialog. (The warning note is explained below, under A Note On Deleting Repository Items.)

NOTE: The delete option will be disabled on the context menu for any item that the User is not authorized to delete.

A repository item may be deleted if the following conditions are true:

• The logged in User submitted the item to the repository, or is an Administrator
• The item is not included in any published surveys

Removing a Published Repository Item

Although repository items that appear in published surveys cannot be deleted, they can be retired. The difference is that deleted items are removed from the repository altogether, while retired items are simply made unavailable for future use.

Published surveys that already use a retired repository item can continue to use them. Once the item is retired, however, it will no longer appear in the repository, and users will not be able to add it to future surveys. See “Retiring Repository Items”.

A Note on Deleting Repository Items

When a repository item is deleted, there may be unpublished surveys that Illume doesn’t yet know about that refer to this item. If so, these surveys will not be able to include a copy of the repository item, and the item will have to be manually re-created in the survey.