Satisfaction surveys
:: services/surveys module

This is a BETA module. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this module, please let us know. Then, we will work with you and move it out of beta as soon as we can.

These methods allow students to view and fill out surveys. They also allow lecturers to view survey results.

There are two main types of surveys in USOS:

  • course surveys - surveys that evaluate lecturer in context of a course unit.

    To let the student unambiguously identify such surveys you need to matched them by lecturer name, course name, term name and classtype. You may also add a group name to this set, but in terms of distinguishing course surveys this information is actually redundant, as the student cannot be a member of two groups of the same course unit.

    Course survey objects will always have "null" values under "programme" key, because "programme" does not apply to this type of survey.

  • general surveys - general purpose surveys, not connected to any course. These surveys may evaluate eg. deanery, library or any other aspect of the university life.

    General survey may be carried out in context of a specific programme. In that case you'll get info about the programme under "programme" key in the survey object. You should always make your user aware of this context of general survey by providing him/her at least with programme name.

    General survey does not have to specify such a context. In such cases, it means that a student is expected to answer questions only once, and with no connection to any programme he/she studies (or studied). In that case, you'll get "null" under the "programme" key.

    General survey objects will always have "null" values under "group", "groups_conducted", and "lecturer" keys, because these keys do not apply to this type of survey.

Methods of this module may be called by both students and lecturers. However, some methods (or fields) cannot be called (or accessed) if the caller is not a student (or not a lecturer):

  • Students may view surveys_to_fill and fill_out surveys. In case of course surveys, if the caller is a student of this course, then the group key will describe the group the student is member of. (This membership entitles the student to fill out the survey.)
  • Lecturers may view surveys that concern them (surveys_about_me) and view a "live" (status) of each survey. In case of course surveys, if the caller is a lecturer of this course, then the groups_conducted key will describe all groups conducted by this lecturer, and which are also part of the course unit evaluated by this survey.

Methods

fill_out (deprecated) BETA Post a survey result in the name of a user.
fill_out2 BETA Post a survey result in the name of a user.
survey (deprecated) BETA Get a single survey.
survey2 BETA Get a single survey.
surveys (deprecated) BETA Get surveys.
surveys2 BETA Get surveys.
surveys_about_me (deprecated) BETA Retrieve all surveys "about" the caller.
surveys_about_me2 BETA Retrieve all surveys "about" the caller.
surveys_to_fill (deprecated) BETA Get the list of surveys waiting to be filled out by the user.
surveys_to_fill2 BETA Get the list of surveys waiting to be filled out by the user.

services/surveys/fill_out

Consumer: required Token: required Scopes: surveys_filling SSL: required
https://usosapi.awf.krakow.pl/services/surveys/fill_out

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

This method is deprecated, please avoid using it - read more

Suggested replacement: services/surveys/fill_out2

Post a survey result in the name of a user.
survey_id required ID of the survey.
answers required

A JSON-formatted object, mapping question IDs to their answers: {"question1_id": "possible_answer_id", "question2_id": "possible_answer_id"}.

Note, that all values of this objects are strings (because the IDs of possible answers are strings).
comment optional

Default value: (empty string)

An optional comment to be submitted along the answer.
format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

An empty dictionary returned if the method has been executed successfully. Some keys may be added in the future.

Thrown errors:

  • object_forbidden - access to object denied.

    Possible reasons:

    • already_answered - survey was already answered;

    • not_entitled_to_fill_out - user is not entitled to fill out this survey.

  • object_invalid - object is in invalid state.

    Possible reasons:

    • comment_too_long - comment cannot exceed 3000 characters;

    • invalid_answer - answer outside of possible answers scope for the question;

    • no_answers - to save survey results at least one question has to be answered.

  • object_not_found - some of the referenced objects do not exist.

    Possible reasons:

    • survey_not_found - referenced survey does not exist.

services/surveys/fill_out2

Consumer: required Token: required Scopes: surveys_filling SSL: required
https://usosapi.awf.krakow.pl/services/surveys/fill_out2

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Post a survey result in the name of a user.
survey_id required ID of the survey.
answers required

A JSON-formatted object, mapping question IDs to their answers:

{"question1_id": {"answers": ["possible_answer1_id", "possible_answer2_id", ...], "comment": "comment or null"}, "question2_id": ...}

Note, that all values of this objects are strings (because the IDs of possible answers are strings). If comment should be left empty or the question does not allow comments, null has be passed in comment field.
comment optional

Default value: (empty string)

An optional comment to be submitted along the answer. Note that this parameter has to be null if the survey does not allow final comment.
format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

An empty dictionary returned if the method has been executed successfully. Some keys may be added in the future.

Thrown errors:

  • object_forbidden - access to object denied.

    Possible reasons:

    • already_answered - survey was already answered;

    • not_entitled_to_fill_out - user is not entitled to fill out this survey.

  • object_invalid - object is in invalid state.

    Possible reasons:

    • comment_not_allowed - comment is not allowed in this survey;

    • comment_too_long - comment cannot exceed 3000 characters;

    • invalid_answer - answer outside of possible answers scope for the question;

    • no_answers - to save survey results at least one question has to be answered;

    • schema_invalid - passed answers object does not conform to schema;

    • too_many_answers - too many answers provided for the question.

  • object_not_found - some of the referenced objects do not exist.

    Possible reasons:

    • survey_not_found - referenced survey does not exist.

services/surveys/survey

Consumer: required Token: required Scopes: none SSL: required
https://usosapi.awf.krakow.pl/services/surveys/survey

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

This method is deprecated, please avoid using it - read more

Suggested replacement: services/views/survey2

Deprecation reason: This method does not support some surveys (e.g. surveys with open questions) and will treat them as non-existent.

Get a single survey (either general or course survey).
survey_id required

ID of the survey.

You may notice that this ID is constructed from a set of survey attributes, but you should not construct it by yourself, as its structure is subject to change. Use dedicated methods (eg. surveys_to_fill) to obtain proper survey IDs.
fields optional

Default value: id|survey_type|name

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section.

format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

A dictionary of selected fields:

  • Primary:

    • id - Id of the survey;

    • survey_type - string, type of the survey.

      This will be one of the two values: "course" or "general". See module's introduction for details on differences between those two!

    • name - LangDict object, name of the survey.

      This is supposed to be displayed as the "header" of this survey. The contents are plaint-text, they cannot contain HTML. Clients SHOULD escape HTML control characters before embedding this title on a web page.

    • headline_html - string, additional HTML headline for this survey.

      This is supposed to be displayed below the survey name. It contains a short description of the survey. It MAY contain user-provided HTML, so client developers SHOULD expect anything here (including XSS vectors).

    • start_date - datetime string or null.

      This indicates the time when collecting the answers starts. It MAY be null, in which case this time is in the past, but its exact value is unknown.

    • end_date - datetime string or null.

      This indicates the time when collecting the answers ends. It MAY be null, in which case this time is in the future, but its exact value is unknown.

    • can_i_fill_out - Can I fill out this survey?.

      True, if the requesting user is entitled to fill out this survey. Note, that once the user has filled it out, he is no longer entitled to fill it out.

    • did_i_fill_out - Did I already fill out this survey?.

      True, if requesting user already filled out this survey, false otherwise.

    • group - A group the survey refers to (null for general surveys).

      This field references objects returned by services/groups/group method. See its returns section for possible subfields.

    • groups_conducted - List of groups.

      If the method is invoked by a lecturer being evaluated by this survey, then this field will contain a list of groups conducted by this lecturer (and which also being surveyed). If this is a general survey, then this list will always be empty.

      This field references objects returned by services/groups/group method. See its returns section for possible subfields.

    • lecturer - Lecturer being evaluated by this survey, or null in case of general surveys.

      This field references objects returned by services/users/user method. See its returns section for possible subfields.

    • faculty - Faculty that defined the survey.

      You can use primary subfields from the services/fac/faculty method

    • programme - The programme which the survey refers to, or null for course surveys or general surveys that are not carried out in context of a specific programme..

      This field references objects returned by services/progs/programme method. See its returns section for possible subfields.

    • filled_out_count - integer or null.

      If the requesting user has access to survey results (see can_i_view_results field), then this field will contain the number of times this survey has been filled out. Otherwise, it will contain null.

    • entitled_count - integer or null.

      If the requesting user has access to survey results (see can_i_view_results field), then this field will contain a total number of users entitled to fill out this survey. Note, that this number is NOT decremented after a user fills out the survey.

      Otherwise, it will contain null.

    • can_i_view_results - boolean, indicates if the requesting user is entitled to view results of this survey.

      Currently, survey results consist of the number of entitled users (entitled_count), and number of students who filled out the survey (filled_out_count), but more fields may come in the future.

    • why_cant_i_view_results - LangDict object or null.

      If can_i_view_results is false, then this will contain a LangDict object with an explanation why the requesting user can't see results of this survey.

    • questions - List of survey questions.

      This list is ordered and it has a tree-like structure. Every question on this list is an object of the following structure:

      • id - string, an ID of the question,
      • number - string, a chapter-like label to be used for question numbering.

        These values are not supplied by users, they are instead dynamically generated by USOS API. They will always come in form of "N.N.N", where each N is an integer, and the number of dots is equal to the value of level field (e.g. "1" or "1.2").

      • level - integer, a 0-based level/indent of the question (for example, in case of "1.2" number, this will be 1),

        Clients may assume that these levels will be consistent, and that they will describe a tree (in a DFS-order). The level of first question will always be zero (note, that other entries also MAY have the zero level).

      • display_text_html - string, the content of the question. It may contain any content, including user-provided HTML, so your application should consider this data unsafe (e.g. prone to XSS attacks),

      • possible_answers - a list of objects, each describing an answer.

        Each answer will have the following structure:

        • id - string, an ID of a possible answer,
        • display_text_html - string, content of the answer. It may contain any content, including user-provided HTML, so your application should consider this data unsafe (e.g. prone to XSS attacks),

services/surveys/survey2

Consumer: required Token: required Scopes: none SSL: required
https://usosapi.awf.krakow.pl/services/surveys/survey2

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Get a single survey (either general or course survey).
survey_id required

ID of the survey.

You may notice that this ID is constructed from a set of survey attributes, but you should not construct it by yourself, as its structure is subject to change. Use dedicated methods (eg. surveys_to_fill) to obtain proper survey IDs.
fields optional

Default value: id|survey_type|name

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section.

format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

A dictionary of selected fields:

  • Primary:

    • id - Id of the survey;

    • survey_type - string, type of the survey.

      This will be one of the two values: "course" or "general". See module's introduction for details on differences between those two!

    • name - LangDict object, name of the survey.

      This is supposed to be displayed as the "header" of this survey. The contents are plaint-text, they cannot contain HTML. Clients SHOULD escape HTML control characters before embedding this title on a web page.

    • headline_html - string, additional HTML headline for this survey.

      This is supposed to be displayed below the survey name. It contains a short description of the survey. It MAY contain user-provided HTML, so client developers SHOULD expect anything here (including XSS vectors).

    • start_date - datetime string or null.

      This indicates the time when collecting the answers starts. It MAY be null, in which case this time is in the past, but its exact value is unknown.

    • end_date - datetime string or null.

      This indicates the time when collecting the answers ends. It MAY be null, in which case this time is in the future, but its exact value is unknown.

    • can_i_fill_out - Can I fill out this survey?.

      True, if the requesting user is entitled to fill out this survey. Note, that once the user has filled it out, he is no longer entitled to fill it out.

    • did_i_fill_out - Did I already fill out this survey?.

      True, if requesting user already filled out this survey, false otherwise.

    • group - A group the survey refers to (null for general surveys).

      This field references objects returned by services/groups/group method. See its returns section for possible subfields.

    • groups_conducted - List of groups.

      If the method is invoked by a lecturer being evaluated by this survey, then this field will contain a list of groups conducted by this lecturer (and which also being surveyed). If this is a general survey, then this list will always be empty.

      This field references objects returned by services/groups/group method. See its returns section for possible subfields.

    • lecturer - Lecturer being evaluated by this survey, or null in case of general surveys.

      This field references objects returned by services/users/user method. See its returns section for possible subfields.

    • faculty - Faculty that defined the survey.

      You can use primary subfields from the services/fac/faculty method

    • programme - The programme which the survey refers to, or null for course surveys or general surveys that are not carried out in context of a specific programme..

      This field references objects returned by services/progs/programme method. See its returns section for possible subfields.

    • filled_out_count - integer or null.

      If the requesting user has access to survey results (see can_i_view_results field), then this field will contain the number of times this survey has been filled out. Otherwise, it will contain null.

    • entitled_count - integer or null.

      If the requesting user has access to survey results (see can_i_view_results field), then this field will contain a total number of users entitled to fill out this survey. Note, that this number is NOT decremented after a user fills out the survey.

      Otherwise, it will contain null.

    • can_i_view_results - boolean, indicates if the requesting user is entitled to view results of this survey.

      Currently, survey results consist of the number of entitled users (entitled_count), and number of students who filled out the survey (filled_out_count), but more fields may come in the future.

    • why_cant_i_view_results - LangDict object or null.

      If can_i_view_results is false, then this will contain a LangDict object with an explanation why the requesting user can't see results of this survey.

    • questions - List of survey questions.

      This list is ordered and it has a tree-like structure. Every question on this list is an object of the following structure:

      • id - string, an ID of the question,
      • number - string, a chapter-like label to be used for question numbering.

        These values are not supplied by users, they are instead dynamically generated by USOS API. They will always come in form of "N.N.N", where each N is an integer, and the number of dots is equal to the value of level field (e.g. "1" or "1.2").

      • level - integer, a 0-based level/indent of the question (for example, in case of "1.2" number, this will be 1),

        Clients may assume that these levels will be consistent, and that they will describe a tree (in a DFS-order). The level of first question will always be zero (note, that other entries also MAY have the zero level).

      • display_text_html - string, the content of the question. It may contain any content, including user-provided HTML, so your application should consider this data unsafe (e.g. prone to XSS attacks),

      • possible_answers - a list of objects, each describing an answer.

        Each answer will have the following structure:

        • id - string, an ID of a possible answer,
        • display_text_html - string, content of the answer. It may contain any content, including user-provided HTML, so your application should consider this data unsafe (e.g. prone to XSS attacks),

      • allow_comment - boolean, indicates if a text comment can be passed in answer to the question,

      • comment_length - integer or null, maximum length of a text comment in answer to the question or null if the text comment cannot be passed in answer.

    • has_final_comment - Can I add final comment to survey?.

      True if the survey allows to put final comment, false otherwise.

services/surveys/surveys

Consumer: required Token: required Scopes: none SSL: required
https://usosapi.awf.krakow.pl/services/surveys/surveys

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

This method is deprecated, please avoid using it - read more

Suggested replacement: services/surveys/surveys2

Deprecation reason: This method does not support some surveys (e.g. surveys with open questions) and will treat them as non-existent.

Get general or course surveys.
survey_ids required Pipe-separated list of survey IDs, as described in survey method.
fields optional

Default value: id|survey_type|name

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of survey method.

format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

A dictionary that will map your survey_ids to survey objects, as defined in the survey method.

services/surveys/surveys2

Consumer: required Token: required Scopes: none SSL: required
https://usosapi.awf.krakow.pl/services/surveys/surveys2

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Get general or course surveys.
survey_ids required Pipe-separated list of survey IDs, as described in survey2 method.
fields optional

Default value: id|survey_type|name

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of survey2 method.

format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

A dictionary that will map your survey_ids to survey objects, as defined in the survey2 method.

services/surveys/surveys_about_me

Consumer: required Token: required Scopes: surveys_reports SSL: required
https://usosapi.awf.krakow.pl/services/surveys/surveys_about_me

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

This method is deprecated, please avoid using it - read more

Suggested replacement: services/surveys/surveys_about_me2

Deprecation reason: This method does not support some surveys (e.g. surveys with open questions) and will treat them as non-existent.

This method allows the lecturer to retrieve a list of all surveys by which he or she is evaluated.

Note that lecturers can be evaluated only the the "course"-type surveys. Hence, all of the returned surveys will always have the type of "course".
term_ids optional

Default value: (empty string)

Pipe-separated list of academic term IDs. If given, then the results will be narrowed down to only such course surveys which refer to course units of specified term_ids.
fields optional

Default value: id|survey_type|name

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of survey method.

format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

List of survey objects, as defined in the survey method.

services/surveys/surveys_about_me2

Consumer: required Token: required Scopes: surveys_reports SSL: required
https://usosapi.awf.krakow.pl/services/surveys/surveys_about_me2

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

This method allows the lecturer to retrieve a list of all surveys by which he or she is evaluated.

Note that lecturers can be evaluated only the the "course"-type surveys. Hence, all of the returned surveys will always have the type of "course".
term_ids optional

Default value: (empty string)

Pipe-separated list of academic term IDs. If given, then the results will be narrowed down to only such course surveys which refer to course units of specified term_ids.
fields optional

Default value: id|survey_type|name

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of survey2 method.

format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

List of survey objects, as defined in the survey2 method.

services/surveys/surveys_to_fill

Consumer: required Token: required Scopes: surveys_filling SSL: required
https://usosapi.awf.krakow.pl/services/surveys/surveys_to_fill

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

This method is deprecated, please avoid using it - read more

Suggested replacement: services/surveys/surveys_to_fill2

Deprecation reason: This method does not support some surveys (e.g. surveys with open questions) and will treat them as non-existent.

Get the list of surveys waiting to be filled out by the user.
include_filled_out optional

Default value: false

Boolean. "true" if already filled out surveys should be included in results
fields optional

Default value: id|survey_type|name

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of survey method.

format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

List of survey objects, as defined in the survey method.

services/surveys/surveys_to_fill2

Consumer: required Token: required Scopes: surveys_filling SSL: required
https://usosapi.awf.krakow.pl/services/surveys/surveys_to_fill2

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Get the list of surveys waiting to be filled out by the user.
include_filled_out optional

Default value: false

Boolean. "true" if already filled out surveys should be included in results
fields optional

Default value: id|survey_type|name

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of survey2 method.

format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

List of survey objects, as defined in the survey2 method.
USOS API ver. 7.1.0.0-4, 0e1fe7fc, dirty (2024-08-27)