Users' permissions and roles within faculties
:: services/facperms 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.

Please note, that most developers SHOULD NOT use this module.

All meaningful effective permissions (and roles) are propagated and enforced in all the other USOS API modules and methods. E.g. Depending on the method, if user X doesn't have the permission to view some field, then you may simply receive null when you attempt to access this field using the user X's Access Token, etc.

In other words, you should avoid using the facperms module to determine if you are allowed to do some action or not. Instead, use the proper fields exposed by methods in other modules. One good example of such is the set of can_i_do_something fields exposed in the slips module (however, every module can handle it differently).

Important: We won't move this module out of BETA any time soon! We believe that the current granularity exposed by these methods may not be "enough" in the future. Some permissions may need to be redefined, which may require the interface of many methods to be changed (or completely rewritten) in a backward-incompatible way. Use this module only if you MUST.

Methods

delete BETA DELETE an existing user-faculty-permission row. (administrative)
effective_fac_ids BETA Get a list of faculty IDs in which the user has a role. (administrative)
fpclass BETA Get information on a given permission class.
fpclass_index BETA Get the full list of faculty permission classes.
fpclasses BETA Get information on multiple permission classes.
has_facperm BETA Check if access token issuer has selected facperm
replace BETA INSERT new or UPDATE existing user-faculty-permission row. (administrative)
select BETA Perform a SELECT on the user-faculty-permission rows. (administrative)

services/facperms/delete

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
https://usosapi.panschelm.edu.pl/services/facperms/delete

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 user-faculty-permission row.
fpclass_id required Faculty permission class ID.
user_id required User ID.
fac_id required Faculty ID.
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:

{"success": true, "existed": true} if the row existed and was successfully deleted.

{"success": true, "existed": false} if the row did not exist.

In case of failure (e.g. due to insufficient permissions), use the user_messages field to display a proper message for the user.

services/facperms/effective_fac_ids

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
https://usosapi.panschelm.edu.pl/services/facperms/effective_fac_ids

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

Get a complete list of all faculty IDs in which the given user has a given effective role/permission.

In cases when the user has been granted the role with the with_subfaculties flag set, the list will include all those subfaculties. (You cannot achieve this effect with the select method.)
fpclass_id required ID of the faculty permission class.
user_id required ID of the user.
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:

Unordered list of strings - IDs of the faculties.

services/facperms/fpclass

Consumer: required Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/facperms/fpclass

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 faculty permission class.
fpclass_id required

ID of the faculty permission class.

Many of the IDs are not backward-compatible. They may either disappear or change their meaning at any time. You should avoid hardcoding IDs in your code. Use the fpclass_index method instead.
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. Token is not required.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • id - the ID of the permission class;

  • title - A LangDict object. A short title for the permission/role (in plaintext);

  • summary - A LangDict object.

    A short description of the permission/role - usually one or two sentences in a single paragraph. May contain simple HTML markup and links to external resources.

services/facperms/fpclass_index

Consumer: required Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/facperms/fpclass_index

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

Get the full list of faculty permission classes.
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 of fpclass 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:

Ordered list of fpclass objects (currently there are no categories to group them by, just this list).

services/facperms/fpclasses

Consumer: required Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/facperms/fpclasses

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 faculty permission classes.
fpclass_ids required Pipe-separated list of faculty permission class IDs.
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 of fpclass 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:

A dictionary: your fpclass_ids will be mapped to dictionary's keys, and each value will contain the description of one permission class, as defined in the fpclass method.

services/facperms/has_facperm

Consumer: required Token: required Scopes: none SSL: required
https://usosapi.panschelm.edu.pl/services/facperms/has_facperm

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.

Check if access token issuer has selected facperm
fpclass_id required ID of the faculty permission class.
faculty_id optional

Default value: (empty string)

ID of a faculty. If not selected, true will be returned if userhas persmission in some faculty
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:

True if user has permission, false in the other case

services/facperms/replace

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
https://usosapi.panschelm.edu.pl/services/facperms/replace

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.

INSERT new or UPDATE existing user-faculty-permission row.
fpclass_id required Faculty permission class ID.
user_id required User ID.
fac_id required Faculty ID.
with_subfaculties required By default, the permissions are propagated down the tree of facultues. Set this to false if you want the permission to effect only this single faculty (without its subfaculties).
auto_remove_redundant optional

Default value: false

By default, if the change would have rendered some of the existing permissions redundant, then the change will be aborted (with a proper user message).

Set this to true if you'd like all the redundant entries removed instead.
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:

{"success": true, "existed": false} if the insert succeeded.

{"success": true, "existed": true} if the exact same row was already present and it was updated.

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

services/facperms/select

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
https://usosapi.panschelm.edu.pl/services/facperms/select

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.

Perform a SELECT on the user-faculty-permission rows.

You may wonder why this module uses a SQL-like interface (which is uncommon in USOS API). This seems practical in this particular case. There are three separate entities joined here (user, faculty and permission class). This interface allows you to choose various sets of data with just a single method, e.g.:

  • Show all the permissions granted to a single user.
  • Show all the users which have been granted a specified permission.
  • Show all the faculties in which the given permission is in effect for the given user. (If you want the subfaculties included too, then you should probably have a look at the effective_fac_ids method.)
  • Etc.

See also this diagram.
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.

fpclass_ids optional

Default value: (empty string)

Pipe-separated list of faculty permission class IDs. If given, then only such rows will be returned which contain any of the given IDs.

The validity of these references is validated lazily. This means that you won't get a HTTP 400 error if you provide an invalid reference here.
user_ids optional

Default value: (empty string)

Pipe-separated list of user IDs. If given, then only such rows will be returned which contain any of the given IDs.

The validity of these references is validated lazily. This means that you won't get a HTTP 400 error if you provide an invalid reference here.
fac_ids optional

Default value: (empty string)

Pipe-separated list of faculty IDs. If given, then only such rows will be returned which contain any of the given IDs.

The validity of these references is validated lazily. This means that you won't get a HTTP 400 error if you provide an invalid reference here.
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:

Unordered list of dictionaries. Each dictionary will contain the fields you have asked for in the fields parameter. Available fields:

  • fpclass - the object with the faculty permission class description.

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

  • user - the object with the user description.

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

  • faculty - the object with the faculty description;

  • with_subfaculties - Boolean. True if the permission is propagated to all the subfaculties of the selected faculty..
USOS API ver. 7.1.0.0-4, 0e1fe7fc (2024-08-27)