The repository stores questions, question tables and Text/HTML items for reuse on multiple surveys, providing several advantages including: consistency, cross-survey queries, and universal access.
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.
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.
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.
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:
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”.
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.
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:
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.
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:
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:
To delete categories, follow these steps:
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.
To delete category values, follow these steps:
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”.
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:
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:
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.
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:
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:
To view all items in the repository:
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:
To get more information about an item:
Illume will present the following 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:
To search by category and value:
The Search Results tab will appear, displaying the results of the search.
To search the texts of question prompts and scale values:
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.
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.
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.
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
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.
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:
To edit these properties, it is possible to break the item’s link to the repository.
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.
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:
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.
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:
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:
To delete an item from the repository:
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:
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”.
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.