Accessing information on administration documents
:: services/adm_documents module

These methods allow you to search for administration documents and access information on them.

Methods

document Get information on administration document by id.
generate_code Generate receive code and send it by e-mail.
get_upd Get selected administration document UPD of a given user.
get_upo Get selected administration document UPO of a given user.
receive Receive document using authorization code.
user_documents Get information on administration documents of a given user.

services/adm_documents/document

Consumer: required Token: optional Scopes: adm_documents SSL: required
https://usosapps.demo.usos.edu.pl/services/adm_documents/document

Get information on administration document by id.

id required ID of document
fields optional

Default value: id|published_date|delivered_date|id_blobbox|actions|name|status|type|type_name

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

format optional

Default value: json

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

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • id - document ID;

  • published_date - document publication date;

  • delivered_date - document delivery date;

  • id_blobbox - ID of document in blobbox;

  • actions - allowed actions.

    List of allowed actions for the document. Possible values:

    • RECEIVE_DOCUMENT - the document can be received (see receive)
    • GET_DOCUMENT - the document can be downloaded from blobbox (see services/blobbox/get)
    • GET_UPO - UPO for the document can be downloaded via get_upo
    • GET_UPD - UPD for the document can be downloaded via get_upd
  • name - LangDict - name of document;

  • status - LangDict - name of document status.

    Note that this field is meant only for showing its value for user. Use actions field to differentiate between document states.

  • type - Document type.

    Possible values: D, P, W, Z.

    Use type_name field for human-friendly document type names.

  • type_name - LangDict - document type name.

Thrown errors:

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

services/adm_documents/generate_code

Consumer: required Token: optional Scopes: adm_documents SSL: required
https://usosapps.demo.usos.edu.pl/services/adm_documents/generate_code

Generate receive code and send it by e-mail.

id required document ID
lang optional

Default value: pl

e-mail language, one of pl, 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 optional oauth_token for Token authorization.

Returned value:

A dictionary of the following structure:

  • email - e-mail address, which will receive the message with code
  • date - timestamp of code sending

services/adm_documents/get_upd

Consumer: required Token: required Scopes: adm_documents SSL: required
https://usosapps.demo.usos.edu.pl/services/adm_documents/get_upd

Get selected administration document UPD of a given user.

adm_document_id required ID of Administration document
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:

HTTP 200 response with raw contents of UPD as XML file.

If no such document exists, does not have UPD or you don't have access to it, this method will respond with HTTP 400 error.

Thrown errors:

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

services/adm_documents/get_upo

Consumer: required Token: required Scopes: adm_documents SSL: required
https://usosapps.demo.usos.edu.pl/services/adm_documents/get_upo

Get selected administration document UPO of a given user.

adm_document_id required ID of Administration document
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:

HTTP 200 response with raw contents of UPO as XML file.

If no such document exists, does not have UPO or you don't have access to it, this method will respond with HTTP 400 error.

Thrown errors:

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

services/adm_documents/receive

Consumer: required Token: optional Scopes: adm_documents SSL: required
https://usosapps.demo.usos.edu.pl/services/adm_documents/receive

Receive document using authorization code.

id required document ID
code required authorization code, see generate_code 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:

Empty dict on success.

On error: dictionary of the following structure:

  • status - the value will be set to Err
  • message - LangDict, message to show to user about attempts left or if code reset is required

Thrown errors:

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

  • param_invalid - parameter has invalid value.

services/adm_documents/user_documents

Consumer: required Token: optional Scopes: adm_documents SSL: required
https://usosapps.demo.usos.edu.pl/services/adm_documents/user_documents

Get information on administration documents of a given user.

fields optional

Default value: id|published_date|delivered_date|id_blobbox|actions|name|status|type|type_name

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

List of documents. Selected fields and their values defined in the document method.

USOS API ver. 6.7.0.0-0, 364a2eca (2021-06-21)