Clearance slips
:: services/slips 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 allows your user to access and manage clearance slips and its templates.

Many methods in this module are designed for localized validation of user-supplied data, so that you don't have to validate the data on the client-side. Please read about the user_messages field before you start using this feature.

Methods

add_question BETA Add a new question to a template
create_template BETA Create a new slip template
delete_question BETA Delete a question from the template
delete_slip BETA Delete an issued slip
delete_template BETA Delete a template
issue_slip BETA Issue a new slip instance
question BETA Get information on a single question
questions BETA Get information on multiple questions
search_slips BETA Search among the issued slips
search_templates BETA Search the list of templates
slip BETA Get information on a single issued slip
slipquestion BETA Get information on a single slipquestion
slipquestions BETA Get information on multiple slipquestions
slips BETA Get information on multiple issued slips
template BETA Get information on a given template
templates BETA Get information on multiple templates
to_be_answered BETA Browse slipquestions to be answered
update_question BETA Edit an existing question
update_slip BETA Edit an existing issued slip
update_slipquestion BETA Edit an existing slipquestion object
update_template BETA Edit an existing slip template
user_roles BETA Return the description of user's roles

services/slips/add_question

Consumer: required Token: required Scopes: slips_admin 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.

Add a new question to a template.

Note, that your user has to hold proper privileges in order for you to use this method. However, if he does not, you will still receive a HTTP 200 response (see "returns" section).

tpl_id required

ID of the template to which you want to add the question.

question required

The question. This should be short, but unambiguous, preferably 20-50 characters. The current limit is 100. It also must end with a question mark.

Note, that there are no multiple fields for multiple languages here. Language is left for the user to choose. In other words, if the user ever needs to create a multilingual template, he will need to create two separate templates and describe when to use which.

Note, that if your question is too long or otherwise "incorrect", you will still receive a HTTP 200 response (see "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:

{"success": true, "question_id": "<id of the new question>"}

In case of failure, use the user_messages field to display a proper message for the user.

services/slips/create_template

Consumer: required Token: required Scopes: slips_admin 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.

Create a new slip template. You have to have some active slip templates before you can create actual slips.

Note, that your user has to hold proper privileges in order for you to use this method. However, if he does not, you will still receive a HTTP 200 response (see "returns" section).

fac_id required

ID of the faculty. Each template has to be bound to a single faculty.

name required

Name for your template. This should be short, but unambiguous, preferably 20-30 characters. The current limit is 75.

The template editors can freely choose the language in which they want to create their templates. Most clearance slips need to be defined in one language only.

Note, that if it's too long or otherwise "incorrect", you will still receive a HTTP 200 response (see "returns" section).

lang optional

Default value: pl

Language which will be used within the template. All the questions and answers should also be given in the language given here.

Currently, only two values are allowed: pl or en.

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:

{"success": true, "tpl_id": "<id of the new template>"}

In case of failure, use the user_messages field to display a proper message for the user.

services/slips/delete_question

Consumer: required Token: required Scopes: slips_admin 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.

Delete a question from within a template.

Important: Only some question can be directly deleted (currently, only the ones contained within draft templates). Other should be marked as obsolete and wait to be garbage-collected. You can use the can_i_delete field of the question method to check if the question can be deleted.

question_id required ID of the question to be deleted.
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:

{"success": true}

In case of failure, use the user_messages field to display a proper message for the user.

services/slips/delete_slip

Consumer: required Token: required Scopes: slips 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.

Delete an existing issued slip.

slip_id required ID of the slip to be deleted.
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:

{"success": true}

In case of failure, use the user_messages field to display a proper message for the user.

services/slips/delete_template

Consumer: required Token: required Scopes: slips_admin 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.

Delete an existing template.

Important: Only some templates can be directly deleted (drafts and possibly some more specific cases). Others should be marked as obsolete and wait to be garbage-collected.

tpl_id required ID of the template to be deleted.
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:

{"success": true}

In case of failure, use the user_messages field to display a proper message for the user.

services/slips/issue_slip

Consumer: required Token: required Scopes: slips 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.

Issue a new slip instance. The issued slip will initially be closed, so that it can be edited before its questions begin to be answered.

tpl_id required

ID of the slip template to be used for the slip.

client_user_id required

ID of the user to whom the slip is to be issued.

student_programme_id optional Optional ID of the student's programme which is said to be "bound" to the issued slip instance.
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:

{"success": true, "slip_id": "<id of the new slip>"}

In case of failure, use the user_messages field to display a proper message for the user.

services/slips/question

Consumer: required 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 single question.

question_id required ID of the question.
fields optional

Default value: question

Pipe-separated list of fields 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 optional oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • id - ID of the question,
  • tpl_id - ID of the template to which the question is attached,
  • question - plaintext, the content of the question.
  • desc_for_answerers - plaintext, possible multiline, additional description of the question, for the answerers.

    The question fields must be simple and short, but many such questions require some additional explanation (especially if the question's answerer is the slip's client). This field was created for that purpose. It's content should be easily accessible for anyone allowed see the question itself (especially, the client answerers).

  • answerers - a list of user objects; these are the users which are allowed to answer this question, regardless of the slip it is on (should not be confused with extra answerers, see update_slipquestion method.

    A user object will contain three fields: id, first_name and last_name (see the services/users/user method).

  • is_included_by_default - boolean, set to true if the question should be "initially checked" when a new slip is being issued. (The issuer can still uncheck the question and exclude it from the slip.)
  • can_client_answer - boolean, set to true if the client (the issuee) is allowed to answer this question on his own.
  • can_issuers_answer - boolean, set to true if the issuers are allowed to answer this question on his own.
  • can_issuers_assign_answerers - boolean, set to true if the issuers are allowed to define extra answerers. These answerers are bound to the issued slip, NOT its template.
  • is_obsolete - boolean, marks if the question is obsolete. Such questions cannot be included in newly issued slips. They can only be present in the slips released in the past.
  • regexp_cleared - regular expression, if it is successfully matched against an answer to this question, then the answer gets a dynamic "cleared" status. See answer_status in the slipquestion method.
  • regexp_rejected - regular expression, works as the one above, but the matched answer gets the "rejected" status.

    If an answer does not match any of these two expressions, or it matches both of them, if will get an "unclear" status.

  • quick_answers - pipe-separated list of strings, each of which is a common answer to this question. When defined, these answers should be displayed to the answerers, allowing them to answer quickly.
  • can_i_delete - boolean, indicates if the current user is allowed to delete this question. Access Token and the 'slips_admin' scope is required to access this field.
  • why_cant_i_delete - LangDict or null, if the current user cannot delete the question, it will briefly explain why. This is intended to be displayed for the users.

services/slips/questions

Consumer: required 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 multiple questions. They don't have to belong to one template. If your looking for an ordered list of questions for a given template, see questions field of the template method.

question_ids required

Pipe-separated list of question IDs.

fields optional

Default value: question

Pipe-separated list of fields you're interested in. This must be any subset of keys, which are described in the returns section of the question 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 optional oauth_token for Token authorization.

Returned value:

A dictionary. Question IDs will be mapped to keys of this dictionary. Each value will be a dictionary of the same structure as described in the question method.

For all invalid references, the value will be null (instead of a dictionary).

services/slips/search_slips

Consumer: required Token: required Scopes: slips 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.

This method allows you to search among the list of all issued slips which your user has access to. You can use various filters in your search - they should allow you to use this method in many contexts.

Note: Slips visibility may depends on the scopes the user has provided access to you.

langpref required A code of the preferred language ("pl" or "en"). It may influence the order and other display properties of the returned matches.
fields optional

Default value: id

Pipe-separated list of slip fields you'd like to receive along the results. See the slip method for the list of valid values.
tpl_fields deprecated

Default value: id

Deprecated. Use a subfield selector instead (e.g. fields=template[id]).

Pipe-separated list of template fields you'd like to receive in the template field. See the template method for the valid values.

my_role optional

Default value: (all possible roles)

Pipe-separated list of user roles, as defined in the slip method. If given, the results will contain only these slips in which the current user "has" at least one of the referenced roles.

Note: Some roles (i.e. "template_admin") require access to higher scopes ("slips_admin") in order for the slips to become visible.

issued_by optional Pipe-separated list of user IDs. If given, the results will contain only these slips which were issued by one of the referenced users (the possible issuers of the slip).
issued_for optional Pipe-separated list of user IDs. If given, the results will contain only these slips which were issued for one of the referenced users (the possible clients of the slip).
state optional Pipe-separated list of slip states. If given, the results will contain only these slips which are in any of these states.
tpl_ids optional Pipe-separated list of template IDs. If given, the results will contain only these slips which were issued using any of the given templates.
fac_ids optional Pipe-separated list of faculty IDs. If given, the results will contain only these slips which were issued using a template bound to any of the given faculties.
programme_ids optional Pipe-separated list of study programme IDs. If given, the results will contain only these slips which were bound to any of the given study programmes.
num optional

Default value: 6

The number of search results to return. The maximum allowed value is 20.
start optional

Default value: 0

The index of the first matching search result that is to be included in the response (zero-based).

Note, that no more than 100 results will be returned for any query, even if more than 100 matches were found.

order_by optional

Default value: -date_created

Pipe-separated list of fields to order by. This must be a subset of what you have given in your fields parameter. Each field reference might be preceded with a dash to indicate descending order. Currently allowed fields to order by:

  • state,
  • date_created.
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 the following structure:

  • items - a list of matching clips. Each item is a clip object, as returned by the slip method. It will contain all the fields requested with the fields parameter (only id by default).

  • next_page - boolean, indicates if there is a next page of results for this query.

services/slips/search_templates

Consumer: required 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.

This method allows you to search through the list of all templates using some basic filters. The results will vary on your user's internal permissions and the scopes he had given you access to.

langpref required A code of the preferred language ("pl" or "en"). It may influence the order and other display properties of the returned matches.
query optional The query to search with. Part of template's name or its ID, etc.
fields optional

Default value: id|match

Pipe-separated list of slip fields you'd like to receive along the results. Allowed values:

  • All the fields defined in the template method, plus one more:
  • match - HTML string. It will include template's name, but it may also contain other data (such as template's code). Fragments that have matched your query will be highlighted with a <b> tag.
issuable_only optional

Default value: false

If set to true, then the results will contain only these templates which can be issued by the user making the query. Access Token and the 'slips' scope is required in order to use this.
editable_only optional

Default value: false

If set to true, then the results will contain only these templates which can be edited by the user making the query. Access Token and the 'slips_admin' scope is required in order to use this.
fac_ids optional Pipe-separated list of faculty IDs. If given, then the results will contain only such templates which are bound (directly) to any of the given faculties.
num optional

Default value: 6

The number of search results to return. The maximum allowed value us 20.
start optional

Default value: 0

The index of the first matching search result that is to be included in the response (zero-based).

Note, that no more than 100 results will be returned for any query, even if more than 100 matches were found.

order_by optional

Pipe-separated list of fields to order by. This must be a subset of what you have given in your fields parameter. Each field reference might be preceded with a dash to indicate descending order. Currently allowed fields to order by:

  • state,
  • can_i_edit,
  • name,
  • fac.name (influenced by the lang parameter).
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 optional oauth_token for Token authorization.

Returned value:

A dictionary of the following structure:

  • items - a list of matching templates. Each item is a template object, as returned by the template method. It will contain all the fields requested with the fields parameter (only id by default).

  • next_page - boolean, indicates if there is a next page of results for this query.

services/slips/slip

Consumer: required Token: required Scopes: slips 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 single issued slip.

slip_id required ID of the slip.
fields optional

Default value: template

Pipe-separated list of fields described in the returns section.
tpl_fields deprecated

Default value: id|name

Deprecated. Use a subfield selector instead (e.g. fields=template[id|name]).

Pipe-separated list of fields to be included in the template field. See the template method for the list of allowed values.

ctpl_fields deprecated

Default value: id|name

Deprecated. Use a subfield selector instead.

Pipe-separated list of fields to be included in the connected_tpls field. See the template method for the list of allowed values.

ctpl_q_fields deprecated

Default value: id|question

Deprecated. Use a subfield selector instead.

Pipe-separated list of fields to be included in the connected_tpls.questions. See the question method for the list of allowed values.

sq_fields deprecated

Default value: id

Deprecated. Use a subfield selector instead.

Pipe-separated list of fields to be included in each of the slipquestion objects in the questions field. See the slipquestion method for the list of allowed values.

sq_q_fields deprecated

Default value: question

Deprecated. Use a subfield selector instead.

Pipe-separated list of fields to be included in each of the slipquestion.question objects in the questions.question field. See the question method for the list of allowed values.

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:

  • id - ID of the slip,
  • template - the slip's template. See the template method for the list of allowed subfields.
  • connected_tpls - an ordered list of template objects.

    The list begins with the primary slip's template. Then, all templates referenced in the primary template's connected_tpl_ids_deep field. In the end, all templates which were not listed before and which are used in the questions field.

    When the slip contains large number of templates, this is our estimate of the proper order of templates in which the questions should be ordered.

    Important: Currently, this field can be accessed only when you are reading exactly one slip ID (it doesn't work in the slips method).

  • issuer - an object describing the user who issued the slip. You may use subfield selector to access more subfields (id, first_name and last_name by default).
  • client - an object describing the user who is the client of the slip. You may use subfield selector to access more subfields.
  • student_programme - this is either null or a dictionary. If the client is a student then this field may reference one of his/hers student programmes, which is said to be "bound" to this slip instance.

    The format of the dictionary is the same as the one returned by the student_programme method. Use the subfield selector in the fields parameter to access individual fields.

  • state - this can be "closed" or "active".
  • user_roles - a list of roles which the current user "has" in regard of this slip. Possible roles are (more may be coming):

    • template_admin - the user is a template admin. He can view all the slips which were issued using any of the template he has access to. This role will be included only if your user allowed you access to the slips_admin scope.
    • issuer - the user can issue template in the faculty of the slip's template.
    • answerer - the user was appointed to answer one of the questions included in the slip.
    • client - the user is the client of the slip.
    • More roles may be introduced in the future. Your app must be ready for that!
  • date_created - datetime string, the time when the slip was first created. Please note, that slips are created in the "closed" state, but they are usually made "active" just a moment later.
  • date_last_closed - datetime string, the time when the slip was last closed, or null if the slip has never changed its state from active to closed. Slips can be made "active" and "closed" unlimited number of times.
  • issuers_comment - issuers' comment. This is visable by everyone who can view the slip (including the client), but only the current issuers can edit it.
  • can_i_edit - boolean, true if the user can edit the slip (change which questions are included, assign extra answerers, change the state, etc.).
  • why_cant_i_edit - LangDict or null, if the current user cannot edit the slip, it will briefly explain why. This is intended to be displayed for the users.
  • can_i_delete - boolean, true if the user can delete the slip.
  • why_cant_i_delete - LangDict or null, if the current user cannot delete the slip, it will briefly explain why. This is intended to be displayed for the users.
  • questions - this object describes which questions are included in this slip, grouped by their template. It has the structure of a dictionary.

    • The keys of this dictionary are template IDs.
    • The values are ordered lists of slipquestion objects, bound to the given template and included on the slip. See the slipquestion method for the list of available subfields.

    Please note, that questions may refer to any template. I.e. the template may not be present on the connected_tpl_ids_deep list of the slip's template.

services/slips/slipquestion

Consumer: required Token: required Scopes: slips 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 single slipquestion.

Clarification: A "slipquestion" is an entity that binds slips and questions. In other words, all questions included in the slip are represented as "slipquestion" entities (some of these questions are answered, some are not).

sq_id required ID of the slipquestion.
fields optional

Default value: id|question_id

Pipe-separated list of fields described in the returns section.
slip_fields deprecated

Default value: id

Deprecated. Use a subfield selector instead (e.g. fields=slip[id]).

Pipe-separated list of fields to be returned in the slip field. See the slip method for the list of available fields.

question_fields deprecated

Default value: id|question

Deprecated. Use a subfield selector instead.

Pipe-separated list of fields to be returned in the question field. See the question method for the list of available fields.

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:

  • id - ID of the slipquestion,
  • slip_id - ID of the slip the question "is on",
  • slip - a slip object, as it would be returned by the slip method.
  • question_id - ID of the question the slip "includes",
  • question - the question object, as it would be returned by the question method.
  • extra_answerers - the list of user objects (with "id|first_name|last_name" fields). These users have been specified as extra answerers to this question. That is, they are appended to the list of default answerers defined for this question (see answerers field in the question method.
  • answerer - a user object or null. If the question has been answered, it will contain an object describing the user who had answered it (with "id|first_name|last_name" fields)
  • answerer_user_id - as above, but only user's ID will be returned (string or null).
  • answer - string or null. This is the actual answer to the question. It can be any string. If the question is not answered, it will be null.
  • answer_status - automatically computed status of the answer. One of the following values:

    • pending - the question is not answered,
    • cleared - the question is answered and the answer "is positive" (the exact meaning of "being positive" depends on the question),
    • rejected - the question is answered and the answer "is negative" (the exact meaning of "being negative" depends on the question),
    • unclear - the question is answered, but we cannot determine whether the answer is positive or negative.

    Currently this status is computed by matching the answer agains regexp_cleared and regexp_rejected expressions defined in the question. However, you should not assume that this algorithm will not change (you should ask USOS API for the value of this status instead of computing it yourself).

  • date_answered - a datetime string or null; if the question was answered, it will contain the exact date and time when it was answered.
  • can_i_answer - boolean, indicates if the current user is allowed to post the answer to this slipquestion.
  • why_cant_i_answer - LangDict or null; if the current user cannot post the answer, it will briefly explain why. This is intended to be displayed for the users.
  • can_i_remove_answer - boolean, indicates if the current user is allowed to remove the answer to this slipquestion (so that it can be answered again, by someone else).
  • why_cant_i_remove_answer - LangDict or null; if the current user cannot remove the answer, it will briefly explain why. This is intended to be displayed for the users.
  • can_i_change_extra_answerers - boolean, indicates if the current user is allowed to edit the list of extra answerers.
  • why_cant_i_change_extra_answerers - LangDict or null; if the current user cannot change extra answerers, it will briefly explain why. This is intended to be displayed for the users.

services/slips/slipquestions

Consumer: required Token: required Scopes: slips 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 multiple slipquestions.

sq_ids required

Pipe-separated list of slipquestion IDs.

fields optional

Default value: id|question_id

As in the slipquestion method.
question_fields deprecated

Default value: id|question

Deprecated. As in the slipquestion method.
slip_fields deprecated

Default value: id

Deprecated/ As in the slipquestion 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. Slipquestion IDs will be mapped to keys of this dictionary. Each value will be a dictionary of the same structure as described in the slipquestion method.

For all invalid references, the value will be null (instead of a dictionary).

services/slips/slips

Consumer: required Token: required Scopes: slips 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 multiple issued slips.

slip_ids required

Pipe-separated list of slip IDs.

fields optional

Default value: template

As in the slip method.
tpl_fields deprecated

Default value: id|name|fac

Deprecated. As in the slip method.
ctpl_fields deprecated

Default value: id|name

Deprecated. As in the slip method.
ctpl_q_fields deprecated

Default value: id|question

Deprecated. As in the slip method.
sq_fields deprecated

Default value: id

Deprecated. As in the slip method.
sq_q_fields deprecated

Default value: question

Deprecated. As in the slip 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. Slip IDs will be mapped to keys of this dictionary. Each value will be a dictionary of the same structure as described in the slip method.

For all invalid references, the value will be null (instead of a dictionary).

services/slips/template

Consumer: required 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 template.

tpl_id required ID of the template.
fields optional

Default value: name

Pipe-separated list of fields described in the returns section.
question_fields deprecated

Default value: id|question

Deprecated. Use a subfield selector instead (e.g. fields=questions[id|question]).

Which fields should be included in the each of the question objects listed in the questions field? You have to include 'questions' in your fields in order for this parameter to work.

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 optional oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • id - ID of the template,
  • name - the name of the template, in plaintext (note, that this is NOT a LangDict object),
  • lang - ISO 639-1 language code, the language in which the template was defined.

    Important: Currently there are only two values in use (pl and en), but it may change in the future. Your application must be prepared to receive other language codes.

  • desc_for_issuers - plaintext, possibly multiline description of the template, to be displayed for the slip issuers (other users may find it irrelevant or misleading),
  • fac - faculty with which the template is bound, a dictionary of the following structure:

    • id - ID of the faculty,
    • name - a LangDict object with the faculty name.
  • state - state code of this template. One of the following values:

    • draft - Only template editors can see draft templates. Once out of this state, the template cannot return to it.
    • active - Issuers can issue slips using this template. Template editors can still change a template after it is published.
    • obsolete - Issuers may still see this template (view its structure, answerers, etc.), but cannot issue new slips anymore. It can be moved back to an "active" state. Template editors can still change a template after it was marked obsolete.
  • can_i_issue - boolean, indicates if the current user is allowed to issue a new slip using this template. Access Token and the 'slips' scope is required to access this field.
  • why_cant_i_issue - LangDict or null; if the current user cannot issue the slip, it will briefly explain why. This is intended to be displayed for the users.
  • can_i_edit - boolean, indicates if the current user is allowed to edit this template. Access Token and the 'slips_admin' scope is required to access this field.
  • why_cant_i_edit - LangDict or null, if the current user cannot edit the slip, it will briefly explain why. This is intended to be displayed for the users.
  • can_i_delete - boolean, indicates if the current user is allowed to delete this template. Access Token and the 'slips_admin' scope is required to access this field.
  • why_cant_i_delete - LangDict or null, if the current user cannot delete the slip, it will briefly explain why. This is intended to be displayed for the users.
  • questions - a list of questions. Each question is an object of the structure described in the question method.

  • slips_stats - a dictionary of the following structure:

    • active - number of active slips of this template,
    • closed - number of closed slips of this template.
  • connected_tpl_ids - IDs of the templates which have been connected to this template (are issued together with its slips).

  • connected_tpl_ids_deep - this is similar to connected_tpl_ids, but the list is aggregated recursively - i.e. all indirect connections will also be included (This graph is not a DAG, it may contain cycles!).

    Note: Whenever a clearance slip is issued using a template, all questions from its connected templates are also included in this slip. The graph can be altered later in time, but the questions bound to the issued slip will remain unchanged.

  • coordinators - a list of people designated to coordinate this template. It should be displayed to the template issuers, so that they may contact each other easily.

    Each item on the list is a user object (with id, first_name and last_name fields).

    Currently, all the people allowed to edit the template are considered its coordinators. This may change in future though!

services/slips/templates

Consumer: required 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 multiple templates.

tpl_ids required

Pipe-separated list of template IDs.

fields optional

Default value: id|name

Pipe-separated list of informational fields/sections you're interested in. This must be any subset of keys, which are described in the returns section of the template method.
question_fields deprecated

Default value: id|question

Deprecated. Same as in the question 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 optional oauth_token for Token authorization.

Returned value:

A dictionary. Template IDs will be mapped to keys of this dictionary. Each value will be a dictionary of the same structure as described in the template method.

For all invalid references, the value will be null (instead of a dictionary).

services/slips/to_be_answered

Consumer: required Token: required Scopes: slips 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.

This method allows you to browse through the list of all questions which are waiting to be answered by the user.

langpref required A code of the preferred language ("pl" or "en"). It may influence the order and other display properties of the returned objects.
unanswered_before optional Datetime string. By default, the list will contain only unanswered questions. With this parameter you may include some recently answered questions (answered after the specified date). This might be helpful for review.
fields optional

Default value: id|slip|question

As in the slipquestion method.
question_fields deprecated

Default value: id|question

Deprecated. As in the slipquestion method.
slip_fields deprecated

Default value: id|client

Deprecated. As in the slipquestion method.
num optional

Default value: 6

The number of search results to return. The maximum allowed value is 20.
start optional

Default value: 0

The index of the first matching search result that is to be included in the response (zero-based).

Note, that no more than 100 results will be returned for any query, even if more than 100 matches were found.

order_by optional

Default value: slip.date_created|question.question

Pipe-separated list of fields to order by. Each field reference might be preceded with a dash to indicate descending order. Currently allowed fields to order by:

  • slip.date_created,
  • slip.client,
  • question.question.
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 the following structure:

  • items - a list of matching clips. Each item is a clip object, as returned by the slip method. It will contain all the fields requested with the fields parameter (only id by default).

  • next_page - boolean, indicates if there is a next page of results for this query.

services/slips/update_question

Consumer: required Token: required Scopes: slips_admin 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.

Edit an existing question of a template.

Note, that your user has to hold proper privileges in order for you to use this method. However, if he does not, you will still receive a HTTP 200 response (see "returns" section).

question_id required

ID of the question.

question optional

New question content. For more information see add_question method. If not given, question content will not change.

Important: If the template is no longer in a draft state, then it is crucial that you ask your user if the new content of the question changed the meaning of the question. See is_meaning_changed.

desc_for_answerers optional

New content of the additional description for the answerers. For more information see question method. If not given, the description will not change.

is_meaning_changed optional

Default value: true

Boolean. This should be supplied by user, whenever he edits the question content of a non-draft template. One of the two values:

  • false - The meaning was not changed. That is, all the answers to this question remain correct. Every answerer would answer exactly the same to the new question as he did answer to the old one.
  • true - The meaning might have been changed. Some answerers might have answered differently to the new question than they did answer to the old one.

Important: If the meaning is changed, we may decide that the question should be forked into two questions, instead of being changed. In such case:

  • A new question will be created. An exact copy of the old one.
  • The old question will be marked as obsolete.
  • All changes submitted in your query will be applied to both questions (except the question value which will be applied only to the new one).
  • You will receive an additional question_id in your result. This is the ID of the new question (the one with the actually changed question field).
  • You should inform your user of what happened.
answerers optional

Pipe-separated list of user IDs. This is the default set of people allowed to answer this question.

Only template editors are allowed to change this set. However, slip issuers may be allowed to define extra answerers for some questions. See can_issuers_assign_answerers parameter for more information.

is_included_by_default optional Boolean. If given, changes the value of the is_included_by_default field described in the question method.
can_client_answer optional Boolean. As above. See the question method for more information on these fields.
can_issuers_answer optional Boolean. As above.
can_issuers_assign_answerers optional Boolean. As above.
is_obsolete optional Boolean. As above.
regexp_cleared optional String. As above.
regexp_rejected optional String. As above.
quick_answers optional String. As above.
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:

{"success": true}

If your request was successful AND the edit caused a new question to be "forked", then the question_id of this new (forked) question will be included in the returned dictionary.

In case of failure, use the user_messages field to display a proper message for the user.

services/slips/update_slip

Consumer: required Token: required Scopes: slips 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.

Change attributes of an existing issued slip.

Note, that your user has to hold proper privileges in order for you to use this method. However, if he does not, you will still receive a HTTP 200 response (see "returns" section).

Important: Please note the difference between:

  • passing the parameter with an empty string value - in this case we will try to set the value of the appropriate field to an empty string,
  • not passing the parameter at all - in this case the current state of the field will not be changed.
slip_id required ID of the template been edited.
state optional

New slip state. For more information see slip method.

student_programme_id optional ID of the student's programme which is said to be "bound" to the issued slip instance or an empty string to remove the existing reference.
issuers_comment optional

New value of the issuers' comment.

question_ids optional

Pipe-separated list of question IDs which are to be included in this slip. If you want to edit other properties of the questions, use the update_slipquestion method.

Important: There are strict rules regarding as to which questions are allowed on which slip. Short extract:

  • Issuers are allowed to remove any existing question from the template, but it is possible that they won't be able to re-add it.
  • Issuer is allowed to add a question if the question is not obsolete and it is present on any of the active templates currently connected to the primary template of this slip.
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:

{"success": true}

In case of failure, use the user_messages field to display a proper message for the user.

services/slips/update_slipquestion

Consumer: required Token: required Scopes: slips 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.

Change attributes of an existing slipquestion object. The set of attributes which you can change depends on the roles of your user within the slip.

Note, that your user has to hold proper privileges in order for you to use this method. However, if he does not, you will still receive a HTTP 200 response (see "returns" section).

Important: Please note the difference between:

  • passing the parameter with an empty string value - in this case we will try to set the value of the appropriate field to an empty string,
  • not passing the parameter at all - in this case the current state of the field will not be changed.
sq_id required ID of the slipquestion been edited.
answer optional

New answer to the question. Setting this to empty string will remove the previous answer.

Please note, that when you're allowing your user to answer, you should present him with quick_answers too (see the question method.

extra_answerers optional New value of extra_answerers field. Pipe-separated list 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. Plus required oauth_token for Token authorization.

Returned value:

{"success": true}

In case of failure, use the user_messages field to display a proper message for the user.

services/slips/update_template

Consumer: required Token: required Scopes: slips_admin 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.

Change attributes of an existing slip template. To edit template's questions, use add_question and update_question methods.

Note, that your user has to hold proper privileges in order for you to use this method. However, if he does not, you will still receive a HTTP 200 response (see "returns" section).

Important: Please note the difference between:

  • passing the parameter with an empty string value - in this case we will try to set the value of the appropriate field to an empty string,
  • not passing the parameter at all - in this case the current state of the field will not be changed.
tpl_id required ID of the template been edited.
fac_id optional

New faculty ID. For more information see create_template method. If not given, faculty ID will not change.

name optional

New template name. For more information see create_template method.

lang optional

New template language. For more information see create_template method.

state optional

Code of the new state for this template. One of the values described state field in the template method.

desc_for_issuers optional Additional description for the issuers. This should be filled in case of templates which require some extra action while being issued. E.g. if the issuer needs to include some questions which are not included by default, or to define extra answerers, etc.
questions_order optional If given, it must be a pipe-separated list of question IDs. All of these questions must belong to this template. Questions will be reordered according to the order in which they appeared in your list. If the template contains more questions than you supplied, they will be moved to the end of the list.
connected_tpl_ids optional

If given, it must be a pipe-separated list of template IDs. If given, it will replace the current values of connected_tpl_ids field. If you provide an empty string, all the connections will be removed!

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:

{"success": true}

In case of failure, use the user_messages field to display a proper message for the user.

services/slips/user_roles

Consumer: required Token: required Scopes: none 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.

Return the description of user's roles within the slips system.

Important: The result of this method depends on the scopes used. I.e. you must have access to slips_admin scope to retrieve information if the user is a slip template editor.

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 the following structure:

  • template_admin - dictionary of the following strucutre:

    • has_role - boolean, true if the user is a template admin. He can view all the slips which were issued using any of the templates he has access to.
    • faculties - a dictionary of faculty objects, as returned by the services/fac/faculties method (with id|name fields). These are the faculties within which the user has the template admin role.

    Important: This entry will be included only if your user allowed you access to the slips_admin scope!

  • issuer - a dictionary of the following structure:

    • has_role - boolean, true if the user is a slips issuer. He can view all the slips which were issued using any of the templates he is allowed to issue.
    • faculties - a dictionary of faculty objects, as returned by the services/fac/faculties method (with id|name fields). These are the faculties within which the user has the slips issuer role.

    Important: This entry will be included only if your user allowed you access to the slips scope!

  • answerer - a dictionary of the following structure:

    • has_role - boolean, true if the user is, or recently was, designated to answer at least one question.
    • is_default_answerer - boolean, true if the user is currently assigned as the default answerer of at least one question.

    Important: This entry will be included only if your user allowed you access to the slips scope!

  • client - a dictionary of the following structure:

    • has_role - boolean, true if the user is a client of at least one clearance slip.

    Important: This entry will be included only if your user allowed you access to the slips scope!

USOS API ver. 6.1.2.0-bc1aa53 (2016-06-07)