Registration for course exams
:: services/exams 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.

This module contains methods that return information on exams, exams' registrations, exams' groups.

Methods

active_examination_sessions BETA Get list of active examination sessions (administrative)
administrator BETA Get information on a exams administrated by user.
batch_register_exam BETA Register multiple users at one request (administrative)
batch_registration BETA Unregister and register multiple users at one request (administrative)
batch_unregister_exam BETA Unregister multiple users at one request (administrative)
condition BETA Get information on a admission condition.
exam BETA Get information on a given exam.
examination_session BETA Get information on a given examination session
examination_sessions BETA Get information on a given examination sessions
exams BETA Get information on a given exam.
faculty_examination_sessions BETA Get list of active examination sessions (administrative)
group BETA Get information on a given exam group
slot BETA Get information on a given slot
user BETA Get information on a exams assigned to user. (administrative)
user_by_login BETA Get user_id using login (administrative)

services/exams/active_examination_sessions

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: ignored Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

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 list of objects returned by examination_session for all active examination sessions
fields optional

Default value: id|status|exams|faculty

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of examination_session 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. Token is not required.

Returned value:

List of active examination sessions

services/exams/administrator

Consumer: required Token: required Scopes: staff_perspective SSL: required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

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 information on a exams administrated by user.

fields optional

Default value: id|status|exams|faculty

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of examination_session 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:

Dictionary mapping faculty ids (fetched using method services/facperms/effective_fac_ids for permission named "ROLA_ZARZADZANIE_REJESTRACJAMI") to list of examination session objects.

services/exams/batch_register_exam

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: ignored Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

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.

Register multiple users at one request

exam_id required Id of an exam
values required Dictionary of group's numbers to dictionaries mapping slot numbers to lists of user IDs.
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. Token is not required.

Returned value:

Dictionary of structure similar to values parameter. But instead of user IDs dictionaries mapping user IDs to one of following statuses are returned:
  • success
  • w_already_registered
  • e_already_registered
  • e_not_permitted

Thrown errors:

  • object_not_found - some of the referenced objects do not exist; param_name is equal to exam_id.

services/exams/batch_registration

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: ignored Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

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.

Method combines methods batch_unregister_exam and batch_register_exam in one. Firstly unregisters users using parameter "unregister", then registers users using parameter "register".
exam_id required Id of an exam
unregister required Dictionary mapping groups numbers to dictionaries mapping slots numbers to lists of user IDs that should be unregistered.
register required Dictionary mapping groups numbers to dictionaries mapping slots numbers to lists of users IDs that should be registered.
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. Token is not required.

Returned value:

Dictionary of following fields mapping user IDs to one of following statuses:

Thrown errors:

  • object_not_found - some of the referenced objects do not exist; param_name is equal to exam_id.

services/exams/batch_unregister_exam

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: ignored Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

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.

Unregister multiple users at one request

exam_id required Id of an exam
values required Dictionary of group's numbers to dictionaries mapping slot numbers to lists of user IDs that should be unregistered.
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. Token is not required.

Returned value:

Dictionary mapping user IDs to one of following statuses:
  • success
  • w_already_not_registered

Thrown errors:

  • object_not_found - some of the referenced objects do not exist; param_name is equal to exam_id.

services/exams/condition

Consumer: optional Token: optional Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

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 information on a admission condition.

exam_id required Id of an exam.
examrep_id required Id of an exam report
fields optional

Default value: examrep|grade_value

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 optional standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • examrep - Related exam report.

    This field references objects returned by services/examrep/exam method. See its returns section for possible subfields (only primary are allowed).

  • grade_value - Null or dictionary of following structure:

    • symbol - e.g. 5, ZAL
    • passes - boolean, true if student passes course with this grade
    • decimal_value - numerical value of the grade
    • name - a LangDict object with the grade name
    • order_key - int used for ordering grades (should not be displayed for users)
    Null means that any grade that passes is required. If dictionary is returned, described grade or higher is required..

Thrown errors:

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

services/exams/exam

Consumer: optional Token: optional Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

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 information on a given exam.

id required Id of an exam.
fields optional

Default value: id|examination_session_id|term|course|registration_start|registration_end|examiners_visible|groups|code|has_priorities|preferences_limit

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 optional standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • Primary:

    • id - ID of an Exam;

    • examination_session_id - ID of the Examination session object;

    • term - Academic Term during which the Course Edition is conducted.

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

    • course - ID of a course.

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

    • registration_start - a DateTime string (or null), indicates when does the registration for this exam starts;

    • registration_end - a DateTime string (or null), indicates when does the registration for this exam ends;

    • examiners_visible - boolean, indicates if the list of examiners is visible (if false, then null will be returned instead of list);

    • name - a LandDict object with the name of an exam (there may be many exams for one course, each will usually have a different name);

    • description - a LangDict object with some additional exam's description;

    • groups - List of exam groups.

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

    • code - Unique code of exam;

    • has_priorities - Boolean - true if students' preferences have priorities;

    • preferences_limit - Maximal number of preferences that student can make in this exam;

    • micro_round_length - Micro-round length in seconds;

    • micro_break_length - Micro-break length in seconds;

    • register_until - a DateTime string (or null), indicates when registrations for exam are allowed;

    • unregister_until - a DateTime string (or null), indicates when unregistrations from exam are allowed;

    • exchange_until - a DateTime string (or null), indicates when exchanges are allowed;

    • examrep_session - an object representing session for examrep module.

      This field references objects returned by services/examrep/exam_session method. See its returns section for possible subfields (only primary are allowed).

    • students_count - Number of students allowed to pass the course..

  • Secondary:

    • admission_conditions - Dictionary mapping exam report IDS to objects representing conditions.

      This field references objects returned by condition method. See its returns section for possible subfields.

    • admitted_students - List of IDs of users that are admitted to registration;

      Additional permissions note: Consumer key with administrative access is required.

    • unadmitted_students - Dictionary mapping user's IDs to lists of exam report ids, that fails admission conditions.

      Additional permissions note: Consumer key with administrative access is required.

Thrown errors:

  • object_not_found - some of the referenced objects do not exist; param_name is equal to id.

services/exams/examination_session

Consumer: optional Token: optional Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

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 information on a given examination session

id required ID of a examination session
fields optional

Default value: id|status|exams|faculty

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 optional standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • id - Examination session ID;

  • name - a LangDict object with the name of the examination session;

  • description - a LangDict object with additional description of the examination session;

  • status - an internal status flag of this examination session.

    Possible values:
    • in_preparation
    • closed
    • archived
    • active_reg_only
    • active
    Note that examination sessions with status "active" will be returned by method active_examination_sessions
  • exams - List of exams related to examination session.

    This field references objects returned by exam method. See its returns section for possible subfields (only primary are allowed).

  • faculty - Dictionary that represents an assigned faculty containing fields: id, name.

Thrown errors:

  • object_not_found - some of the referenced objects do not exist; param_name is equal to id.

services/exams/examination_sessions

Consumer: optional Token: optional Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

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 information on a given examination sessions

ids required List of ids of a examination sessions
fields optional

Default value: id|status|exams|faculty

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of examination_session 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 optional standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

Returned value:

Dictionary mapping selected ids to objects returned by method examination_session

services/exams/exams

Consumer: optional Token: ignored Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

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 information on a given exam.

ids required Id of an exam.
fields optional

Default value: id|examination_session_id|term|course|registration_start|registration_end|examiners_visible|groups|code|has_priorities|preferences_limit

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of exam 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 optional standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required.

Returned value:

Dictionary mapping selected IDs to objects returned by exam method

services/exams/faculty_examination_sessions

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: ignored Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

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 list of objects returned by examination_session for all active examination sessions
faculty_id required Examinations sessions
status required

List of status values. All messages with different status will be filtered out.

fields optional

Default value: id|status|exams|faculty

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of examination_session 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. Token is not required.

Returned value:

List of examinations sessions

services/exams/group

Consumer: optional Token: optional Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

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 information on a given exam group. Note that slot's attendees will be returned only for trusted consumer keys
exam_id required ID of an exam
group_number required Number of an exam group
fields optional

Default value: exam_id|number|exam_start|exam_end|capacity|number_of_slots|slots|examiners

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 optional standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • exam_id - ID of an Exam,;

  • number - number of this group within the Exam,;

  • exam_start - a DateTime string, indicates when the examination starts,;

  • exam_end - a DateTime string, indicates when the examination ends,;

  • capacity - positive integer, the maximum number of Exam Attendees this group is allowed to have (these places are evenly distributed between group's slots),;

  • number_of_slots - positive integer, the number of slots the Exam Group is divided into,;

  • slots - List of dictionaries describing slots.

    This field references objects returned by slot method. See its returns section for possible subfields.

  • examiners - List of group's examiners;

  • room - Room where exam takes place.

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

  • is_examiner - Boolean value, indicates if access token issuer is examiner;

  • register_until - a DateTime string (or null), indicates when registrations for exam are allowed;

  • unregister_until - a DateTime string (or null), indicates when unregistrations from exam are allowed;

  • registration_start - a DateTime string (or null), indicates when does the registration for this exam group starts.

Thrown errors:

  • object_forbidden - access to list of attendees is forbidden.

    Possible reasons:

    • coordinator_only - only coordinator has access to all exam attendees;

    • examiner_only - only examiner or coordinator has access to attendees.

  • object_not_found - some of the referenced objects do not exist; param_name is equal to id.

services/exams/slot

Consumer: optional Token: optional Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

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 information on a given slot

exam_id required ID of an exam
group_number required Number of an exam group
slot_number required Number of a slot
fields optional

Default value: number|capacity|attendees_count|attendees

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 optional standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • number - number of slot;

  • capacity - maximal number of attendees for this slot;

  • attendees_count - Number of attendees;

  • attendees - List of user IDs. Note that only examiners and course coordinators have access to list of attendees;

    Additional permissions note: Consumer key with administrative access is required.

  • start - time of start;

  • end - time of end.

Thrown errors:

  • object_not_found - some of the referenced objects do not exist; param_name is equal to exam_id;

  • object_not_found - some of the referenced objects do not exist; param_name is equal to group_number;

  • object_not_found - some of the referenced objects do not exist; param_name is equal to slot_number.

services/exams/user

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

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.

If authenticated user is coordinator of course all exam groups will be returned.

fields optional

Default value: id|status|exams|faculty

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of examination_session 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 examination sessions

services/exams/user_by_login

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: ignored Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

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 user_id using login

login required 'User's login
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. Token is not required.

Returned value:

ID of selected user
USOS API ver. 6.1.2.0-bc1aa53 (2016-06-07)