Flat Item Table - campsych/concerto-platform GitHub Wiki

This page explains how to create and store your item bank as a Flat Table and how this method works in the assessment node.

In this guide we’re going to:

• Understand the different variables and column names used
• Learn how to create a Flat Item table and use it in an assessment node
• Learn how to add a custom fields to item bank

Download Example Item Bank in Flat Table Format as .csv

The flat table is one method of passing items to an assessment node. It is useful when you don’t want to write JSON, as it splits all of the properties of a question into separate columns. The starter content table called assessmentFlatItems can be used as a starting point, but you can also delete columns from it that you don’t need, and you can add extra columns which will be automatically mapped by Concerto provided you follow the naming convention. For example, the starter content table has 4 response options, but if you want to add a fifth, then you would add columns called responseLabel5,responseValue5,responseScore5 and (optionally) responseTrait5. Then, in the assessment node, you only need to map the first column containing response options (i.e. responeLabel1) and the remainder will automatically be processed. In the guide below, we refer to responseLabelN where N just means the index of that response option:

• id : Each item should have a unique item id.
• fixedIndex : This column can be used when you want to fix the order in which items are shown. It should contain indices. In the assessment node you can specify that fixed index should be used if that’s the case, or you can leave it blank when using ‘manual’ or ‘random’ question order, or CAT
• trait : Specify which trait each item belongs to. This is required if you want to calculate trait scores with the assessment node
• question: content of the question. This can be any HTML. If you want to show an image as the question then you need to use its full path (e.g. “”/bundles/concertopanel/files/images/myImage.png"/>")
• p1 : Discrimination parameter
• p2 : Difficulty parameter
• p3 : Guessing parameter
• p4 : Inattention (d) parameter
• responseLabelN : HTML to show in the response option button. This can be any HTML.
• responseValueN: This is the value sent to the database if the given response option is selected and submitted by the user.
• responseScoreN : This is the score value of a given response option. For example this score would be 0 for incorrect response options, or 1 for the correct response option in a dichotomous test. Or in a personality test you might score 5 likert scale options as 0-4 from ‘Strongly Disagree’ to ‘Strongly Agree’
• responseTraitN: Optional. This column specifies which trait a given response option belongs to. It can be useful in ipsative tests where different response options to the same question may load on different scales, for example. If you’re not using it you can delete all of the columns named ‘responseTraitN’ from your data table.
• type : Required. This specifies the item format. The built-in item formats are response options or open text input. Setting this value to “options” means you want to show response options based on the values of your columns that define response options (e.g. responseLabel1, responseLabel2, etc). Setting this value to “open” for a question means that you want the user to enter free text.
• skippable: Allows you to specify whether a given item can be skipped. If left blank, the options specified in the test development process will apply to all items.
• instructions : Optional text field which can be shown in the top left of the default test page. This can be used for example to show a sentence of instructions that applies to the whole page, such as ‘Please answer all of the questions below’.

You can also add additional columns to your flat table and use them to perform further functions in the assessment node. The new columns can have any name, you just need to map them within the assessment node. Functions, with example column names, include:

• randomOptions – boolean value of whether to randomise the order in which response options are shown.
• optionsColumnNumber – numeric value for how many columns to show response options in. This can be useful, for example, if you have 8 response options as images and you want to show them in two rows rather than a single row, in which case you would set this value to ‘4’
• responseIndexN – imagine you want one of your six options to always appear ‘first’ in order, and the remaining five options to appear in random order. You could set the value of the column responseIndex1 to ‘1’ to achieve this. You can fix the index of any number of response options you want
• gracelyScale – boolean value of whether to show a gracely scale as the item type
• painMannequinGender – gender of the pain mannequin. possible values are: male OR female
• painMannequinMultiMarks – boolean value of whether to allow multiple marks to be made on the pain mannequin item type

You can also add custom fields to your item bank. E.g. let’s imagine we want to add two new properties:

• audio – URL for instructions audio that we want to play on each item page
• correctAnswer – correct answer value that we need to score our custom item type

Two steps are required for this:

1. Add new columns to your item bank: audio, correctAnswer
   
2. Define Item Bank Extra Fields in assessment node. Whatever is defined here will be made accessible on item object available from both test logic (server side) and template (client side) context. There might be case where you have sensitive data that should never be transmitted to client side. In our example such data is correctAnswer. We don’t want test participant to be able to look up this data through browser tools, but we want to be able to use this value on server side when scoring response given. To prevent property being accessible on client side, you need to flag it as Sensitive.