CreateAssessmentDefinition

Applies to the following products: 
Questionmark OnDemand
Questionmark Perception
Questionmark OnPremise
Applies to the following Perception versions: 
Perception 5.7

This method creates an assessment definition for the assessment information supplied and returns the Assessment_ID of the new assessment.

The information that must be provided is the Assessment Name, name of the person who created the assessment definition, template used by the assessment , description of the assessment and at least one assessment block, containing:

  • The block name
  • The introduction text
  • At least one item (question) selection, containing:
    • The selection method
    • The Topic_ID, unless items (questions) are selected individually
    • If items (questions) are selected randomly, the number of questions selected
    • The Question_ID, unless all items (questions) in a topic are selected
  • At least one assessment outcome, containing the assessment outcome name

The assessment created will be stored in the first assessment folder that appears in the repository (as viewed through Authoring Manager).

If using this method in Perception 5, you can also set the language of the assessment definition being created. For example, if you are including questions in German you can identify the assessment as being in German. This can then be used to schedule the assessment in the given language.

If the language is not defined or you are using Perception 4, it is assumed that the language of the assessment is in the base language of your Perception installation.

A SOAP fault will be returned in the following cases:

  • An assessment name is not provided
  • A timed assessment is not given a positive integer as the time limit
  • No template is specified
  • No assessment blocks are defined
  • An assessment block in not named
  • An assessment block that uses its own template does not have a template specified for it
  • An assessment block contains no items (questions)
  • The item (question) selection method is not defined properly
  • The items (questions) cannot be selected as required by the selection method
  • No assessment outcomes are defined
  • An assessment outcome name is not provided
  • The minimum percentage score for an assessment outcome is less than 0 or greater than the maximum percentage score
  • The maximum percentage score for an assessment outcome is greater than 100 or less than the minimum percentage score
  • An assessment outcome branches to another assessment or a URL that is not defined
Available in:
  • Version 4.1 +
  • Version 5.1 +

Parameters

Input name         Description Data type Optional field?

Assessment

 

 

 

 

 

 

 

 

Assessment_ID

 

 

 

Enter a predetermined Assessment_ID for this definition

Integer

Y

 

Revision

 

 

 

The new assessment definition's current revision

Integer

N

 

Session_Name

 

 

 

The new assessment definition's name or title

String

N

 

Author

 

 

 

The name of the new assessment definition's creator

String

N

 

Save_Answers

 

 

 

This indicates whether to save the answers in the answer tables

Boolean

N

 

Save Answer_Data

 

 

 

This indicates whether to save the data to all answer tables, or only to the results and assessment tables

Boolean

N

 

Open_Session

 

 

 

This indicates whether the assessment can be presented with open.dll or open.php

Boolean

N

 

Session_Password

 

 

 

The assessment's password (blank if no password is set)

String

N

 

Session_Timed

 

 

 

This indicates whether the assessment has a time limit (if so, the value is contained in the field Time_Limit below)

Boolean

N

 

Time_Limit

 

 

 

The number of minutes for which the assessment is available (used if Session_Timed above is set)

Integer

N

 

Template_Name

 

 

 

The default template file for the assessment (each assessment block can be set to use its own template file)

String

N

 

When_Feedback

 

 

 

0 - No Feedback at all 1 - Feedback shown after each block 3 - Feedback shown at the end of the assessment

Integer

N

 

End_Feedback

 

 

 

If When_Feedback above is zero: 0 - All questions get feedback 1 - Only wrong or unanswered questions get feedback 2 - Only wrong questions get feedback 3 - All answered questions get feedback

Integer

N

 

Exclude_Unscored

 

 

 

If When_Feedback above is not zero, this indicates whether questions with a maximum score of zero should show feedback

Boolean

N

 

Folder_ID

 

 

 

The Folder_ID of the assessment folder where the assessment should be placed

Integer

N

 

Lang*

 

 

 

The language of the assessment. If no topic or question exists in the specified language then an exception will be thrown. If the input language is "-" (base language), then a base language topic/question(s) must exist. The input language must be valid and should be available in languages.config file on the Perception server.

String

Y

 

Description

 

 

 

This is a short comment for the assessment definition

String

N

 

Monitored

 

 

 

0 - Assessment not monitored 1 - Assessment monitored

Boolean

N

 

Editor

 

 

 

The last user who modified the new assessment definition

String

N

 

Version

 

 

 

The version of Assessment Manager last used to modify the new assessment

Integer

N

 

Permit_External_Call

 

 

 

This is placed in the database field S_Header.Permit_External_Call

Boolean

N

 

Created_Date

 

 

 

The date on which the new assessment definition was created

Date

N

 

Modified_Date

 

 

 

The last date on which the new assessment definition was modified

Date

N

AssessmentBlockList

 

 

 

 

 

 

 

 

AssessmentBlock

(zero or more repetitions)

 

 

 

 

 

 

 

 

Block_Name

 

 

The name of this assessment block

String

N

 

 

Feedback

 

 

This indicates whether feedback is enabled or disabled for this block

Boolean

Y

 

 

Shuffle_Questions

 

 

This indicates whether questions are shuffled or not within this block

Boolean

Y

 

 

Suspend_Time_Limit

 

 

If a Time_Limit is set for the assessment, this indicates whether this block is excluded from it

Boolean

Y

 

 

Use_Template_File

 

 

This indicates whether this block uses its own template independently of the template used for the assessment

Boolean

Y

 

 

Template_Name

 

 

This is the template used for this block

String

Y

 

 

Introduction_Text

 

 

This is the introductory text used for this block

String

Y

 

 

ItemList

 

 

     

 

 

 

Item

(zero or more repetitions)

 

This parameter (if used) is in the form of sets of item (question) information, as detailed

   

 

 

 

 

Method

0 - If this item (question) was selected randomly 1 - If all items (questions) in a topic were selected 2 - If this item (question) was selected as a single question

Integer

N

 

 

 

 

Include_Sub_Topics

If the Method is 0 or 1, this indicates whether subtopics were included in the item (question) selection

Boolean

Y

 

 

 

 

Topic_ID

If the Method is 0 or 1, this is the Topic ID of the topic from which this item (question) was selected

Boolean

N

 

 

 

 

Number_Of_Questions

If the Method is 0, this is the number of items (questions) selected

Integer

N

 

 

 

 

Question_ID

If the Method is 0 or 2, this is the Question ID of the selected item (question)

Integer

Y

AssessmentOutcomeList

 

 

 

 

     

 

AssessmentOutcome

(zero or more repetitions)

 

 

 

     

 

 

Outcome_Name

 

 

The name of this assessment outcome

String

N

 

 

Session_Score

 

 

This indicates whether to show the total topic score

Integer

N

 

 

Topic_Scores

 

 

This indicates whether to show the topic scoring

Integer

Y

 

 

Topic_Feedback

 

 

This indicates whether to show the topic feedback

Boolean

Y

 

 

Branch

 

 

0 - Do not branch after this assessment outcome 1 - Branch to another assessment after this assessment outcome 2 - Branch to a URL after this assessment outcome

Integer

Y

 

 

Assessment_ID

 

 

If Branch is 1, this is the Assessment ID of the assessment to branch to

Integer

Y

 

 

Destination

 

 

If Branch is 2, this is the URL to branch to

String

N

 

 

Message

 

 

This is the message given as feedback with this assessment outcome

String

N

 

 

Min_Percent

 

 

This is the lowest percentage score that will activate this assessment outcome

Real

Y

 

 

Max_Percent

 

 

This is the highest percentage score that will activate this assessment outcome

Real

N

* only used in Perception Version 5.1 and higher

Response

Output name Description Data type

Assessment_ID

The Assessment_ID of the new assessment definition

Integer

Troubleshooting

Please refer to the following page for any error codes that are displayed when using this method.

Appendix - Error codes