Create.Course.Element.Survey

Deprecation notice

The old survey element will be replaced with a new survey tool during the summer of 2023. This API will then be deprecated and it will no longer be possible to create surveys of the old type. We will monitor use to determine if we will replace the API and allow cretion of new surveys through the organisational API.

This method will create a survey element in a specified course.

  • Deadline is a UTC date.

  • Questions are assumed to be listed in the order they should appear in the survey. So each new question appears below the last. This is the way the UI works, but is different to the ordering system used in Course.CreatePageElement.

  • In multiple choice the alternatives will be listed in order they should appear. So each new alternative appears below the previous.

  • In the Matrix question type the row labels and column labels repeat and should be sent in the order (row top to bottom, column left to right).

  • In multiple choice questions limit the number of alternative to 50.

What is a survey?

  • Surveys are used to gather information on a subject from a group of respondents. In itslearning, respondents may be anonymous, but they may also be identified by name.

  • Surveys can be open to the public or only accessible from within itslearning. This is set through the ?Type? field.

  • Surveys support four different types of question in itslearning:

    • Yes or No

    • Multiple Choice

    • Open Ended

    • Matrix

Input

Name

Description

Type

M/O

CourseId

Id of the course where the element is to be created.

Integer

O/M

SiteId

Site where action will be executed

Integer

O

VendorId

VendorId which will be associated with created content

Text

O

CourseSyncKey

SyncKey of the course where the element is to be created.

Text

O/M

ParentID

ID of the folder where the element is to be created. If not specified then create in root

Integer

O

ParentSyncKey

SyncKey of the folder where the element is to be created. If not specified then create in root

Text

O

UserId

UserId of the creator.

Integer

O/M

UserSyncKey

User SyncKey of the creator.

Text

O/M

SyncKey

External SyncKey for the created content.

Text

M

Title

Description of the survey.

TextMust not be blank.Must follow same rules as UI.

M

Introduction

Text (rich content) description of the assignment.

Rich content text

O

Deadline

If Deadline is missing blank then set to "no deadline".If a date is specified then set to the time / date ? even if in the past.

Text.Valid UTC date.

O

Type

Type of survey. This denotes if it can be Anonymous or accessed externally.Default is "Anonymous".External maps to "Open externally" (Anonymous).

TextAnonymousNot anonymousExternal.

O

ShowQuestions

Denotes is all are shown on one page.True = Show all questions on page.Default is "Show all questions on page."

Boolean.

O

Mandatory

Is the assignment mandatory?True = "Mandatory".False = "Not Mandatory".If not specified then assume mandatory.

Boolean.

O

Active

Is the element active?True = "Active".False = "Not Active".Default is "Active".

Boolean.

O


Optional Repeating Blocks:

YesNoQuestion

Question

Text (rich content) questionMust not be blank.

TextSee user story on importing rich content for description of parsing.Use same rules as UI.

M

MultipleChoiceQuestion

Question

Text (rich content) question.Must not be blank.

Rich content text

M

MultipleAnswers

Can the user select multiple answers?Defaults to "False"

Text"True" or "False"

O

Repeating Block

Alternative

Alternative answers for the user to select.

TextCannot be blank.Follow same rules as UI.

M

OpenQuestion

Question

Text (rich content) questionMust not be blank.

Rich content text

M

MatrixQuestion

Question

Text (rich content) question.Must not be blank.

Rich content text

M

Repeating Block

RowLabel

Label for the rows.

TextCannot be blank.Follow same rules as UI.

M

ColumnLabel

Label for the rows.

TextCannot be blank.Follow same rules as UI.

M

Notes

Either UserId or UserSyncKey must be specified. This means specify at least one is mandatory.
Either CourseId or CourseSyncKey must be specified. This means specify at least one is mandatory.Both ParentID and ParentSyncKey are optional. Possible use only one of them either ParentID or ParentSyncKey.

Validation

  • Input matches the schema below.

  • SyncKey is unique.

  • User must exist.

  • User must not be external. Check the flag (external_user_id and external_customer_id for user created AICC).

  • User must not be deleted.

  • Course must exist.

  • Course must not be external.

  • Course must not be deleted.

  • Course must not be archived.

  • If specified: ParentId must be an element ID within the course.

  • If specified: ParentId must be a folder.

  • If specified: ParentId must not be deleted.

  • If specified: ParentSyncKey must be an element ID within the course.

  • If specified: ParentSyncKey must be a folder.

  • If specified: ParentSyncKey must not be deleted.

  • Consumer must have access to organisation where course is created.

Output

Finished Status

If the assignment was created successfully.

Warning Status

Unknown assessment (grade) ID - "No assessment" assumed.

Errors Status

  • Invalid format / parameters (different to specified schema).

  • Message contains duplicates for syncKeys: {0}. Make sure your syncKeys are globally unique.

  • User with specified UserId/UserSyncKey is not valid.

  • User with specified UserId/UserSyncKey is deleted.

  • User with specified UserId/UserSyncKey is external.

  • Course does not exist.

  • Course is external.

  • Course is be deleted.

  • Course is be archived.

  • ParentSyncKey/ParentId is not an element within the course.

  • ParentSyncKey/ParentId is not a folder.

  • Folder related to ParentSyncKey/ParentId has been deleted or removed.

  • Message must contain valid ParentId.

  • ParentSyncKey is deleted.

  • Invalid or unknown ParentSyncKey .

  • Tile missing or incorrectly formatted.

  • Introduction rich content badly formatted or invalid.

  • Deadline date not in UTC format

  • Multiple choice - you must specify at least two alternatives.

  • Multiple choice - blank alternative answer.

  • Matrix question - missing or blank row label.

  • Matrix question - missing or blank column level

  • Your security settings doesn't allow you to perform that operation. Please contact administration to grant you an access to {HieararchyName} organisation.

  • Unable to add all questions to a survey.

  • An unknown error occurred while creating a survey.

XML

Schema
<?xml version="1.0" encoding="utf-8"?>
 
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="urn:message-schema" elementFormDefault="qualified"
targetNamespace="urn:message-schema">
<xs:element name="Message">
<xs:complexType>
<xs:sequence>
<xs:element name="SyncKeys" minOccurs="0" maxOccurs="1">
<xs:complexType>
<xs:sequence>
<xs:element name="SyncKey" minOccurs="0" maxOccurs="1" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="CreateCourseElementSurvey" minOccurs="1" maxOccurs="1">
<xs:complexType>
<xs:sequence>
<xs:choice minOccurs="1" maxOccurs="1">
<xs:element name="CourseId" type="xs:integer" />
<xs:element name="CourseSyncKey" type="xs:string" />
</xs:choice>
<xs:choice minOccurs="0" maxOccurs="1">
<xs:element name="ParentId" type="xs:integer" />
<xs:element name="ParentSyncKey" type="xs:string" />
</xs:choice>
<xs:choice minOccurs="1" maxOccurs="1">
<xs:element name="UserId" type="xs:integer" />
<xs:element name="UserSyncKey" type="xs:string" />
</xs:choice>
<xs:element name="Title" minOccurs="1" maxOccurs="1" type="xs:string" />
<xs:element name="Introduction" minOccurs="0" maxOccurs="1" type="xs:string" />
<xs:element name="Deadline" type="xs:dateTime" minOccurs="0" maxOccurs="1" />
<xs:element name="Type" minOccurs="0" maxOccurs="1" type="SurveyType" />
<xs:element name="ShowQuestions" minOccurs="0" maxOccurs="1" type="xs:boolean" default="true" />
<xs:element name="Mandatory" type="xs:boolean" minOccurs="0" maxOccurs="1" default="true" />
<xs:element name="Active" type="xs:boolean" minOccurs="0" maxOccurs="1" default="true" />
<xs:choice id="Questions" minOccurs="1" maxOccurs="unbounded">
<xs:element name="YesNoQuestion" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element name="Question" minOccurs="1" maxOccurs="1" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="MultipleChoiceQuestion" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element name="Question" minOccurs="1" maxOccurs="1" type="xs:string" />
<xs:element name="MultipleAnswers" minOccurs="0" maxOccurs="1" type="xs:boolean" />
<xs:element name="Alternative" minOccurs="2" maxOccurs="50" type="nonEmptyString" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="OpenQuestion" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element name="Question" minOccurs="1" maxOccurs="1" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="MatrixQuestion" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element name="Question" minOccurs="1" maxOccurs="1" type="xs:string" />
<xs:element name="RowLabel" minOccurs="1" maxOccurs="100" type="nonEmptyString" />
<xs:element name="ColumnLabel" minOccurs="2" maxOccurs="20" type="nonEmptyString" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:choice>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:simpleType name="nonEmptyString">
<xs:restriction base="xs:string">
<xs:minLength value="1"/>
<xs:pattern value=".*[^\s].*" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="SurveyType">
<xs:restriction base="xs:string">
<xs:enumeration value="Anonymous" />
<xs:enumeration value="Not anonymous" />
<xs:enumeration value="External" />
</xs:restriction>
</xs:simpleType>
</xs:schema>
Sample request
<Message xmlns="urn:message-schema">
<CreateCourseElementSurvey>
<CourseId>1</CourseId>
<UserId>1</UserId>
<Title>Title1</Title>
<Deadline>1900-01-01T01:01:01+01:00</Deadline>
<Type>Anonymous</Type>
<ShowQuestions>true</ShowQuestions>
<Mandatory>true</Mandatory>
<Active>true</Active>
<YesNoQuestion>
<Question>
&lt;img src=&quot;http://myvle.com/images/smiley.gif&quot; alt=&quot;Smiley face&quot; height=&quot;42&quot; width=&quot;42&quot; /&gt;
</Question>
</YesNoQuestion>
<YesNoQuestion>
<Question>
&lt;img src=&quot;http://myvle.com/images/smiley.gif&quot; alt=&quot;Smiley face&quot; height=&quot;42&quot; width=&quot;42&quot; /&gt;
</Question>
</YesNoQuestion>
<MultipleChoiceQuestion>
<Question>
&lt;img src=&quot;http://myvle.com/images/smiley.gif&quot; alt=&quot;Smiley face&quot; height=&quot;42&quot; width=&quot;42&quot; /&gt;
</Question>
<MultipleAnswers>true</MultipleAnswers>
<Alternative>Alternative1</Alternative>
<Alternative>Alternative2</Alternative>
<Alternative>Alternative3</Alternative>
</MultipleChoiceQuestion>
<OpenQuestion>
<Question>
&lt;img src=&quot;http://myvle.com/images/smiley.gif&quot; alt=&quot;Smiley face&quot; height=&quot;42&quot; width=&quot;42&quot; /&gt;
</Question>
</OpenQuestion>
<MatrixQuestion>
<Question>
&lt;img src=&quot;http://myvle.com/images/smiley.gif&quot; alt=&quot;Smiley face&quot; height=&quot;42&quot; width=&quot;42&quot; /&gt;
</Question>
<RowLabel>RowLabel1</RowLabel>
<RowLabel>RowLabel2</RowLabel>
<RowLabel>RowLabel3</RowLabel>
<ColumnLabel>ColumnLabel1</ColumnLabel>
<ColumnLabel>ColumnLabel2</ColumnLabel>
<ColumnLabel>ColumnLabel3</ColumnLabel>
</MatrixQuestion>
</CreateCourseElementSurvey>
</Message>