AnswerKey
Description
The AnswerKey data structure specifies answers for a Qualification test, and a mechanism to use to calculate a score from the key and a Worker's answers.
An AnswerKey data structure is a string value that consists of XML data. The XML data must conform to the AnswerKey schema. See WSDL and Schema Locations for the location of this schema. For more information about using XML data as parameter or return value, see Using XML Parameter Values.
The AnswerKey data structure is used as a parameter for the following operations:
-
CreateQualificationType
The AnswerKey data structure is used as a return value for the following operations:
-
GetQualificationType
All elements in a AnswerKey
belong to a namespace whose name is
identical to the URL of the AnswerKey
schema document for the version of
the API you are using.
The Structure of an Answer Key
An answer key is contained in a AnswerKey
element. This element contains
a Question
element for each question in the Qualification test, and an
optional QualificationValueMapping
element that describes how to calculate
the Qualification value from the answer key and the Worker's answers.
Question
A Question
element contains a
QuestionIdentifier
element, which identifies the question for this
answer. This value corresponds to a QuestionIdentifier
in the
QuestionForm.
A Question
element has one or more
AnswerOption
elements, one for each combination of selections in the
multiple-choice question that affects the Worker's test score.
Each AnswerOption
contains one or more
SelectionIdentifier
elements that correspond to identifiers for the
selections in the QuestionForm. It also contains an AnswerScore
element, a number that is added to the Worker's test score if the Worker's answer matches this
option. The Worker must select all of the selections specified by the
SelectionIdentifier
elements, and no others, to earn the score.
Tip
An AnswerScore
for an AnswerOption
may be
negative.
The Question
may have an optional
DefaultScore
, a number that is added to the Worker's test score if none
of the answer options exactly match the Worker's answer for the question.
DefaultScore
is optional, and defaults to 0.
<AnswerOption> <SelectionIdentifier>apples</SelectionIdentifier> <AnswerScore>10</AnswerScore> </AnswerOption>
QualificationValueMapping
The Question
may have an optional
QualificationValueMapping
element that describes how to calculate
the Worker's overall score from the scores of the Worker's answers. It contains either a
PercentageMapping
element, a ScaleMapping
element, or a RangeMapping
element.
If no QualificationValueMapping
is specified, the sum of the scores
of the answers is used as the Qualification value.
<QualificationValueMapping> ... </QualificationValueMapping>
A PercentageMapping
specifies a maximum score for the test, as a
MaximumSummedScore
element. The Qualification value is calculated
as the sum of the scores of the selected answers, divided by the maximum, multiplied by 100
and rounded to the nearest integer to produce a percentage.
... <PercentageMapping> <MaximumSummedScore>15</MaximumSummedScore> </PercentageMapping>
A ScaleMapping
specifies a multiplier, as a decimal value in a
SummedScoreMultiplier
element. The Qualification value is
calculated as the sum of the scores of the selected answers, multiplied by the multiplier.
... <ScaleMapping> <SummedScoreMultiplier>3</SummedScoreMultiplier> </ScaleMapping>
A RangeMapping
assigns specific Qualification values to ranges of
total test scores. It contains one or more SummedScoreRange
elements,
each of which specify an InclusiveLowerBound
element, an
InclusiveUpperBound
element, and a
QualificationValue
that becomes the Qualification value if the sum of
the scores of the selected answers falls within the specified range. Finally, the
RangeMapping
includes a single
OutOfRangeQualificationValue
, which specifies the Qualification
value if the sum of the scores of the selected answers do not fall within a specified range.
Note
Ranges cannot overlap. If ranges overlap, the behavior is undefined.
... <RangeMapping> <SummedScoreRange> <InclusiveLowerBound>5</InclusiveLowerBound> <InclusiveUpperBound>7</InclusiveUpperBound> <QualificationValue>5</QualificationValue> </SummedScoreRange> <SummedScoreRange> <InclusiveLowerBound>8</InclusiveLowerBound> <InclusiveUpperBound>10</InclusiveUpperBound> <QualificationValue>10</QualificationValue> </SummedScoreRange> <OutOfRangeQualificationValue>0</OutOfRangeQualificationValue> </RangeMapping>
Example
The following is an example of a complete AnswerKey
data structure.
Remember that to pass this structure in as a parameter to an operation, XML characters
must be escaped as character entities. For more information,
see Using XML Parameter Values.
<AnswerKey xmlns="
[the AnswerKey schema URL]
"> <Question> <QuestionIdentifier>nextmove</QuestionIdentifier> <AnswerOption> <SelectionIdentifier>D</SelectionIdentifier> <AnswerScore>5</AnswerScore> </AnswerOption> </Question> <Question> <QuestionIdentifier>favoritefruit</QuestionIdentifier> <AnswerOption> <SelectionIdentifier>apples</SelectionIdentifier> <AnswerScore>10</AnswerScore> </AnswerOption> </Question> <QualificationValueMapping> <PercentageMapping> <MaximumSummedScore>15</MaximumSummedScore> </PercentageMapping> </QualificationValueMapping> </AnswerKey>