The Tagged Text File import method uses special tags (codes) to tell it when each item begins and ends and to specify all of its additional information to be imported into your item bank. This Appendix describes how to use these tags, which are sometimes called “@@ codes” because they begin with two @ characters. Each file to be imported continues with as many items as necessary, each beginning with an @@ line.
To prepare your items for import, open your file of item texts in your word processor. Insert the required tags into your file at the start and end of each item, then save your file. Inserting the tags is easiest by repeatedly pasting a set of basic tags lines at the beginning of each item (based on what you need), then editing those lines accordingly for each item. The Mail Merge functionalities in word processors can also offer a substantial timesaver, as can Search and Replace functionality.
Please note: If you are using a Mail Merge to move items from Excel to Word before importing into FastTest, the Mail Merge feature has a limit for each cell of 255 characters. This means that longer text will be cut off.
The item import functionality has the following additional considerations:
- Blank lines in the file are ignored, unless they appear in the Item Text or Notes fields. Then they are imported as blank lines.
- Once the appropriate coding is added to a Word (or other word processor) file, you must save it as an RTF file or a TXT file to be imported.
All tags must begin with @@, where xx represents the relevant tag. For example, the tag for item identification (name) is @@ID. If the tag represents a short piece of information, it is followed immediately (no spaces!) by an = sign, followed immediately by the information. For example, if you want to import an item with the keyword “Algebra” you would state it as below.
For information that is likely to include multiple lines, a different approach is taken. The item stem, item answers, and notes fields all use a tag to note beginning and ending. For example, an algebra item stem would be specified as below.
@@BT 4 + 3x = 19 Solve for x. @@ET
There are three required pieces of information to import an item: the item identification or name (and category path if needed), the item stem, and the item answers (option/alternatives). This translates to five required tags: identification line (@@), begin text (@@BT), end text (@@ET), begin answer (@@BA), and end answer (@@EA). The first 3 (ID, BT, and ET) are used only once per item; the latter two (BA and EA) are used as many times as there are answers for an item.
All other tags are optional.
The Item Identifier Tag
This is the first required tag. Its format is:
Without this tag, no items will be found when the file is processed. This tag uses the following format:
@@ID=<Category Path>:<Item Identifier>
i.e., the Category Path followed by the Item Identifier, separated by a colon (“:”). Note that items will all be imported into the bank for which you right-clicked and chose Import Items; the path refers to the categories within that bank.
- This can be a full path, including the item identifier, or just a category name.
- If the @@ID line includes just a category name, the item will be placed in the category and its identifier will be <none>, e.g., @@ID=Algebra.
- You can then later change an item’s identifier, and can drag and drop items into other categories.
- If you provide an item identifier (as shown above), the item identifier follows the category path, separated by a colon (:), e.g., @@ID=Algebra:Item 13. This will import Item 13 into the Algebra category of the bank you specified upon import.
- You can specify the specific location of an item in your bank structure on the ID line, by specifying the complete path of the item in the hierarchical structure.
- The Category Path can consist of a series of sub-folder names separated by the backslash character (“”).
- The following characters are not allowed in bank and folder name: asterisk (“*”), percent (“%”), forward slash (“/”) and vertical line (“|”). If used in the bank path, the forward slash (“/”) will be replaced with a backslash (“”).
- Leading spaces are also not allowed and will be removed.
- Ordinarily, the colon (“:”) can be used in a folder name. However, because the @@ID= tag uses the colon to separate the Bank Path from the Item Identifier, do not use the colon in the bank path because anything beyond the colon will be considered to be the Item Identifier.
- If the category path that you provide already exists in the workspace that you import to, that path will be used. Otherwise, the path will be created.
- If the Item Identifier provided already exists in the workspace, it will not be overwritten, but a new item will be created with the same name.
The Begin and End Text Tags
The second required tag lines identify the text of each item. Because the Item Text field will likely contain more than one line of text, two tags are needed. These tag lines enclose the text of each item. The required format (beginning in column 1) is the Begin Text tag @@BT, while the End Text tag is @@ET. Place the End Text tag on a separate line following the item text. Take the algebra item shown previously: multiple choice item might have the answers as a table with two columns and four rows, like this:
@@BT 4 + 3x = 19 Solve for x. @@ET
Any blank lines between the Begin Text and End Text tags will be included in the Item Text field. Do not place any tag or information lines used by this import utility between @@BT and @@ET because any @@ combination of characters will result in any item text beyond this combination of characters to be ignored. On the extremely rare occasions that you need to use two @ characters together as actual item text between the Begin Text and End Text tags, place a space between them and make a note to yourself to use the FastTestItem Editor to remove the space after the item has been imported.
The Begin Answer and End Answer Tags
Because FastTest stores item answers separately to facilitate formatting of online tests, all answers must be imported separately. Similarly to the item stem, you must place a Begin Answer (@@BA) tag on the line before and an End Answer (@@EA) on the line after. So continuing with the same example, if the four answers to the item are 4, 5, 6, and 7, it would be imported as below.
@@BA 4 @@EA
@@ID=bank2 @@BT What is the capital of Minnesota? @@ET
This will create an item identified as <none> in a category called bank2 at the top level of the destination bank, because there is no colon (:) followed by an item identifier. There are also no answers to the item.
@@ID=MathAlgebra:ALG_001 @@BT 4 + 3x = 19 Solve for x. @@ET @@BA 4 @@EA @@BA 5 @@EA @@BA 6 @@EA @@BA 7 @@EA
This code will create an item named ALG_001 in the Algebra subcategory of the Math category. When delivered online with alphabetical labels, this item would appear as shown below.
4 + 3x = 19 Solve for x. A. 4 B. 5 C. 6 D. 7
Additional (Optional) Lines of Information
Additional lines of information provide information to be stored in the other fields in each item’s record in the item bank. Additional @@ lines are optional, with each beginning on a new line. Additional lines can appear in any order, and can precede or follow a text block. All additional information lines are assumed to be associated with the most recent @@ID= line. Spaces are not allowed adjacent to = signs.
Because the Notes field can contain more than one line of text, two tags are needed. The Begin Notes tag is @@BN and the End Notes tag is @@EN. Place these tags on a separate line before and following your notes. Neither the @@BN nor the @@EN tag lines have any further information on them. Any blank lines between the Begin Notes and End Notes tag will be imported into the Notes field.
@@BN This is a difficult item. It requires the student to apply three different operations in a particular sequence, and then recognize the fact that the resulting answer is a prime number. @@EN
Do not place any tag or information lines between @@BN and @@EN because any @@ combination of characters will result in any Notes text beyond this combination of characters to be ignored.
Default Value: Blank
The Author information tag is:
Place the author text after the equal sign (“=”) in the Author information line. The Author field may contain up to 128 characters.
Default Value: Blank.
The Source information tag is:
Place the source text after the equal sign (“=”) in the Source information line. The Source field can contain up to 128 characters.
@@SO=Page 27 of the textbook, Intro to algebra, Third Edition
Default Value: Blank.
The Description information tag is:
Place the description text after the equal sign (“=”) in the Description information line. The Description field can contain up to 255 characters.
@@DE=Intermediate algebra with prime number
Default Value: Blank.
The Keywords information tag is:
Place the keywords text after the equal sign (“=”) in the Keywords information line. The Keywords field can contain up to 128 characters. You may separate keywords with either commas or spaces. The keywords will be imported as they appear following the equals sign.
@@KW=addition, subtraction, prime number, division
Default Value: Blank.
The Date Created information tag is:
Place the date you want entered into the Date Created field following the equals sign. If the date used in the Date Created information line is invalid or cannot be interpreted, the default value will be used. Note that dates can be represented in U.S. format (MM/DD/YYYY) or the more internationally aware YYYY-MM-DD.
Default Value: The date the file is imported.
The Item Type information tag is:
Place the two-letter item type following the equals sign. The following six two-letter types are allowed:
- MC : Multiple Choice
- MR : Multiple Response
- FR : Free Response
- IN : Instructional
- SU : Survey
Default Value: MC.
The Keyed/Correct Answer tag is:
Keyed answers are not allowed for the Free Response, Instructional, or Survey Item Types. A single value is allowed for the Multiple Choice and True/False Item Types. The Multiple Response Item Type allows for multiple keyed answers.
For Numeric answers, place a single number between the range of 1 to number of answers following the equals sign. For example, if @@NA for that particular item, the @@KA value must be between 1 and 4 inclusive. “@@KA=3” would be acceptable, “@@KA=6” would be outside of the acceptable range.
For Alphabetic answers, place a single letter between the range of A to the letter of the alphabet corresponding to the number of answers following the equals sign. For example, if @@NA=4 for that particular item, the @@KA= value must be between “A” and “D” inclusive- “D”, being the fourth letter of the alphabet. “@@KA=C” would be acceptable, “@@KA=F” would be outside of the acceptable range.
For the Multiple Response Item Type, you may provide more than one correct answer. Place the string of acceptable answers separated by commas (“,”) or spaces following the equal sign. As before, the values must be in the range of “1” to the number of answers for numeric answers, or between “A” and the letter of the alphabet corresponding to the number of answers for alphabetic answers. Values outside of the acceptable range will be ignored.
If the Keyed Answer information line is not provided, the value is not in acceptable range, is incorrectly specified for the Item Type or otherwise invalid the default value will be used.
Default Value: Blank.
IRT Model and a, b, c Parameters
The IRT Model tag is:
Place the IRT model specifier following the equals sign, and follow it with the a, b, and c parameters.
The IRT model specifier consists of one of the following:
- 1P – 1 parameter (Rasch) model
- 2P – 2 parameter model
- 3P – 3 parameter model
Follow the IRT model specifier with a comma (“,”) followed by the a, b and c parameters separated by commas. The IRT Model information line should follow the format:
@@IR=<IRT Model specifier>, <a Parameter>, <b Parameter>, <c Parameter>
You may also skip the unnecessary a, b, or c parameters that are not required for that particular model.
The 1-parameter model only allows for the b parameter to be entered. You can supply only the necessary b parameter value or you may leave the unused values blank. For instance, the following example for the 1-parameter model may be entered as either:
@@IR=1P, 1.2 or @@IR=1P, , 1.2,
The 2-parameter model allows for the a and b parameters to be entered. You may supply only the necessary a and b parameter values or you may leave the unused c value blank. For instance, the following example for the 2-parameter model may be entered as either:
@@IR=2P, 2.2, 1.2, or @@IR=2P, 2.2, 1.2
For the 3-parameter model the a, b, and c parameters must be entered. The following is an example for the 3-parameter model:
@@IR=3P, 2.2, 1.2, 0.25
For all IRT Models, the a, b and c parameters must be in the proper ranges:
- The a parameter must be in the range 0.00 to 10.00
- The b parameter must be in the range -10.00 to 10.00
- The c parameter must be in the range 0.00 to 1.00
If the IRT Model information line is not provided, the values are not in acceptable range, are incorrectly specified, or otherwise invalid, the default values will be used.
IRT Model: None
a Parameter: Blank
b Parameter: Blank
c Parameter: Blank
Classical Test Theory Statistics
The Classical Test Theory Statistics tag is:
Place the classical test theory statistics in the order p-value and item-total correlation, separated by a comma after the equals sign. Skip a parameter by leaving it blank. If only one parameter is included it will be presumed to be the p-value.
@@CT=0.83, -0.23 @@CT=0.83 @@CT= , -0.23
The p-value and item-total correlation must be in the correct ranges. The range for the p-value must be between 0 and 1 inclusive. The range for the item-total correlation must be between -1 and +1 inclusive. If the classical test theory statistics are not provided, the values are not in acceptable range, or are otherwise invalid the default values will be used.
Item-total correlation: Blank
The User-defined Statistics tag is:
Place the User 1, User 2, and User 3 statistics separated by a comma after the equals sign. Skip a statistic by leaving it blank. If only one statistic is present, it will be presumed to be the User 1 statistic.
@@US=5.63, 4.52, 9.54 @@US= , 4.52 @@US=5.63
If the user statistics are not provided, are not a number, or are otherwise invalid the default value will be used.
Default Value: Blank.
If you have defined custom fields for your workspace, those can also be imported. The tag to begin the field (similar to “Begin Answer”) is
@@BF, and must be followed by @@EF for “end field.”
For example, suppose you have added a custom field for cognitive processing level named “CognitiveLevel.” If an item is at the recall level, it would use a tag as follows. Note that the colon after the field name is necessary.
The following is an expansion of the previous example, now including optional information. The correct answer is 5, which is the second option, so the Keyed Answer is B.
@@ID=MathAlgebra:ALG_001 @@KW=algebra,addition @@DE=Easy algebra item @@TY=MC @@KA=B @@CT=0.96,0.07 @@SO=Page 22, Intro to Algebra textbook @@BT 4 + 3x = 19 Solve for x. @@ET @@BA 4 @@EA @@BA 5 @@EA @@BA 6 @@EA @@BA 7 @@EA
- Make sure you have your items saved as an RTF file or TXT. The file should include all the information you wish to import. RTF files can contain text formatting and images while TXT supports just plain text. Note that RTF does not support Microsoft Word objects, like math equations, path diagrams, and text boxes. For best support for special characters (such as foreign languages) in the TXT file, save the TXT file using the UTF-8 encoding.
- Paste the ID line at the beginning of each item. It looks like this:
@@ID=Folder:ItemNameIf you have Algebra items in a Math category, it would look like this:
You can have more than one level of folder if you specify a path, like:
- Update the information in that line accordingly for each item. In the previous example, you would likely want to change the numbers in the item name. If you have a large number of items, and they are sequentially numbered, a Mail Merge might work well.
- Paste @@BT before each item stem and @@ET after each item stem.SHORTCUT TIP: You can paste the @@BT at the same time you paste the ID line, like this:
- Paste @@BA before each item answer (option) and @@EA after each item answer.SHORCUT TIP: You can paste the @@EA and the subsequent @@BA at the same time. That is, you can copy the following text, and paste it between Option A and Option B, Option B and Option C, etc. See the full example above.
- Paste in any other tags, such as keywords, description, or statistics.
- Import the RTF file and make sure everything appears in order.
- You must manually import or recreate special objects, such as multimedia, text boxes, and math equations.