Exam reports
:: services/examrep2 module

Retrieving information about exam reports, exam sessions and course participants grades.

Methods

class_group Get class group and grades in given group for given exam report
examinee Get exam reports that allows access token issuer to update grades of given student
examrep Get info about exam report
examrep_session Get info about exam report session.
examrep_session_access Get access token issuer to exam report
examrep_type Exam report type
grade_type Get info about grade type.
grade_value Get information about grade value
grader Get exam reports that access token issuer has access
student_grade Get information about single user's grade
student_grades Get information about all user's grade from single exam report
update_student_grade BETA Update user's grade.
user_grade Get information about access token user's grade

services/examrep2/class_group

Consumer: required Token: required Scopes: grades SSL: required
https://usosapi.awf.krakow.pl/services/examrep2/class_group

Get class group and grades in given group for given exam report
examrep_id required ID of exam report
course_unit_id required ID of course unit
group_number required group number
fields required

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 and their values.

Available fields:

  • class_group - Object representing group.

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

  • grades - List of grades objects.

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

services/examrep2/examinee

Consumer: required Token: required Scopes: grades SSL: required
https://usosapi.awf.krakow.pl/services/examrep2/examinee

Get exam reports that allows access token issuer to update grades of given student
user_id required ID of student
fields optional

Default value: id|description|is_general_report|sessions

Selector of result fields you are interested in. The selector must contain subset of primary fields, which are described in the returns section of examrep 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 exam report objects that allows access token issuer to update grade of given student

services/examrep2/examrep

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapi.awf.krakow.pl/services/examrep2/examrep

Get info about exam report
examrep_id required identifier of exam report
fields optional

Default value: id|description|is_general_report|sessions

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 - identifier of exam report;

    • description - description of exam report (LangDict object);

    • counts_into_average - True if grades given in this exam report counts into average;

    • grade_type - Grade type related to given exam report.

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

    • is_general_report - True if report is a general report assigned to course edition;

    • sessions - List of exam report session objects related to this report. Ordered by session number.

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

    • edit_access - Flag describing access rights.

  • Secondary:

    • course_edition - Course edition that report is assigned to.

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

    • course_unit - Report may be assigned to course unit. If it is, related object will be returned.

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

    • active_sessions - List of exam report sessions that have status allowing edition and deadline is in the future.

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

services/examrep2/examrep_session

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapi.awf.krakow.pl/services/examrep2/examrep_session

Get info about exam report session.
examrep_id required ID of an exam report
examrep_session_number required number of exam report session
fields optional

Default value: examrep_id|number|status|description|deadline|is_open

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:

    • examrep_id - ID of exam report;

    • number - number of exam session;

    • status - exam session's status;

    • description - description of an exam session (LangDict object);

    • deadline - a datetime string, date when exam session becomes expired;

    • is_open - true if exam session is not expired yet, and has status allowing edition.;

    • is_acquisition_date_required - true if setting grades for this exam session requires passing acquisition date.

  • Secondary:

    • all_grades - List of all grades in this exam report that access token issuer can read..

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

      Additional permissions note: Access token with extra scope grades is needed, and SSL connection is required.

    • issuer_grade - Access token issuer grade.

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

      Additional permissions note: Access token with extra scope grades is needed, and SSL connection is required.

    • read_access - Access for read grades in this exam report session.

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

    • write_access - Access for write grades in this exam report session.

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

services/examrep2/examrep_session_access

Consumer: required Token: required Scopes: grades SSL: required
https://usosapi.awf.krakow.pl/services/examrep2/examrep_session_access

Get access token issuer to exam report
examrep_id required Id of exam report
examrep_session_number required Number of exam report session
type required type of access
fields optional

Default value: cause|groups|exam_groups|unassigned

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:

List of dictionaries of selected fields will be returned. Available fields:

  • cause - Information from derives access to exam report. Possible vlaues: coordinator, lecturer, examiner;

  • groups - If access is granted to selected groups, list of them is returned.

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

  • exam_groups - If access is granted to selected exam groups, list of them is returned.

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

  • unassigned - True if access is granted to users not assigned to any group.

services/examrep2/examrep_type

Consumer: ignored Token: ignored Scopes: n/a SSL: required
https://usosapi.awf.krakow.pl/services/examrep2/examrep_type

Exam report type
examrep_type_id required Identifier of exam report type
fields optional

Default value: id|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.
No additional OAuth arguments are required. If you provide any, they will be ignored.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • id - identifier of exam report type;

  • name - name of exam report type (LangDict object);

  • grade_type - Grade type related to given exam report type.

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

services/examrep2/grade_type

Consumer: ignored Token: ignored Scopes: n/a SSL: required
https://usosapi.awf.krakow.pl/services/examrep2/grade_type

Get info about grade type.
grade_type_id required Identifier of the type.
fields optional

Default value: id|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.
No additional OAuth arguments are required. If you provide any, they will be ignored.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • Primary:

    • id - Identifier of the grade type;

    • name - a LangDict object with the grade type name.

  • Secondary:

    • values - Array of dictionaries that describe grades.

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

services/examrep2/grade_value

Consumer: ignored Token: ignored Scopes: n/a SSL: required
https://usosapi.awf.krakow.pl/services/examrep2/grade_value

Get information about grade value
grade_type_id required ID of grade type
order_key required Order key of grade value
fields optional

Default value: order_key|symbol|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.
No additional OAuth arguments are required. If you provide any, they will be ignored.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • grade_type - Grade type.

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

  • order_key - numberic value used to identify and sort grades;

  • symbol - Grade symbolic value, e.g. 5, ZAL;

  • passes - boolean, true if student passes course with this grade;

  • decimal_value - numerical value of this grade;

  • name - LangDict object with grade description.

services/examrep2/grader

Consumer: required Token: required Scopes: grades SSL: required
https://usosapi.awf.krakow.pl/services/examrep2/grader

Get exam reports that access token issuer has access
only_writable optional

Default value: false

return only reports that can be edited by access token issuer right now
active_terms_only optional

Default value: true

return only reports from active academic terms
fields optional

Default value: id|description|is_general_report|sessions

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

services/examrep2/student_grade

Consumer: required Token: required Scopes: grades SSL: required
https://usosapi.awf.krakow.pl/services/examrep2/student_grade

Get information about single user's grade
examrep_id required ID of exam report
examrep_session_number required Number of exam report session
student_id required ID of student
fields optional

Default value: grade_value|comment|private_comment|user

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 and their values.

Available fields:

  • Primary:

    • grade_value - Grade value, may be null.

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

    • comment - Comment for student;

    • private_comment - Comment for graders;

    • user - Graded student.

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

    • grader - User who was last editing grade.

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

    • last_updated - Datetime of last edition of grade;

    • is_editable - True if access token issuer has write access to grade;

    • resignation - True if student resigned from passing course;

    • inactive_links - True if course is linked to inactive course;

    • why_cannot_edit - If is_editable is not true, one of following values will be returned:resignation, inactive_links, inactive_links_only;

    • date_acquisition - datetime of grade acquisition.

  • Secondary:

    • examrep_session - Exam report session.

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

services/examrep2/student_grades

Consumer: required Token: required Scopes: grades SSL: required
https://usosapi.awf.krakow.pl/services/examrep2/student_grades

Get information about all user's grade from single exam report
examrep_id required ID of exam report
student_id required ID of student
fields optional

Default value: grade_value|comment|private_comment|user

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

services/examrep2/update_student_grade

Consumer: required Token: required Scopes: grades_write SSL: not required
https://usosapi.awf.krakow.pl/services/examrep2/update_student_grade

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.

Update user's grade.
student_id required ID of user whoose grade will be updated
examrep_id required ID of an exam
examrep_session_number required number of exam session
value_symbol optional Symbolic value of a grade
comment optional Public comment
private_comment optional Private comment
date_modified optional Date used to avoid concurrency problems. If you expect that grade doesn't exist in database you should pass empty string.
date_acquisition optional Date of grade acquisition. This field is optional, however you may sometimes be forced to input the date (if the grade doesn't exist and the exam session requires this date, see is_acquisition_date_required field of examrep_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:

Empty dict on success

Thrown errors:

  • object_forbidden - access to object denied.

    Possible reasons:

    • grade_forbidden - access token issuer does not have access to grade;

    • grade_write_forbidden - Access token issuer is not permitted to update grades. Permission rules:

      • course coordinator may update all grades;
      • lecturer may update grates in course unit exam report for participants of lectured groups.
      You need to use another methods to check if user has permissions.

  • object_invalid - object is in invalid state.

    Possible reasons:

    • exam_session_expired - Exam session is currently expired. Updating grades is prohibited;

    • invalid_exam_status - Exam session is not in the state that allows grade modifications.

  • object_invalid - object is in invalid state.

    Possible reasons:

    • grade_not_editable - Grade is not editable due to resignations, inactive links etc.;

    • invalid_value - Grade has invalid value. If this error is returned, 'grades' is set to dictionary mapping user IDs to dictionaries describing errors;

    • missing_acquisition_date - Acquisition date is required for this protocol, but was not set;

    • updated_concurrently - Some grade was to be changed concurrently. If this error is returned 'grades' is set to dictionary mapping user IDs to results of method services/grades/grade for all passed grades.

services/examrep2/user_grade

Consumer: required Token: required Scopes: grades SSL: required
https://usosapi.awf.krakow.pl/services/examrep2/user_grade

Get information about access token user's grade
examrep_id required ID of exam report
examrep_session_number required Number of exam report session
fields optional

Default value: grade_value|comment|last_updated

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 and their values.

Available fields:

  • grade_value - Grade value, may be null.

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

  • comment - Comment for student;

  • user - Graded student.

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

  • grader - User who was last editing grade.

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

  • last_updated - Datetime of last edition of grade.
USOS API ver. 7.1.0.0-4, 0e1fe7fc, dirty (2024-08-27)