Primary groups
:: services/prgroups 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.

Primary groups of users are defined by the USOS system administrators. They form a single tree, where each group contains subgroups and individual users.

Users can normally access only certain groups, so only a small part of the primary group tree is visible to them. If the user has been assigned access to the group (so called full access), he/she can view all its contents (subgroups and users). In order to actually reach such groups, which may lay down deep in the tree, the user also needs access to all supergroups. This kind of access is called partial: the user cannot see the list of attached users of the partially accessible group and the list of subgroups is only limited to those whose access is either full or partial.

Primary groups are identified by their IDs, which are strings of ASCII printable characters. The ID of the root is an empty string and subgroup IDs of a given group are created by appending subgroup-specific suffix. This way you can easily check if one group is a subgroup of another just by looking at their IDs.

Methods

admin BETA Get user's primary groups
auto_assign_users BETA Auto assign users for this descriptor. (administrative)
create_descriptor BETA Create a descriptor of primary groups. (administrative)
delete_descriptors BETA Delete descriptors of primary groups. (administrative)
descriptor BETA Get information on a given descriptor of primary groups. (administrative)
descriptors BETA Get information on multiple descriptors of primary groups. (administrative)
descriptors_all BETA Get a list of all descriptors of primary groups. (administrative)
primary_group BETA Get information on a given primary group.
primary_groups BETA Get information on multiple primary groups.
schema BETA Get a schema of descriptors of primary groups. (administrative)
update_descriptor BETA Update a descriptor of primary groups. (administrative)
update_user BETA Change primary groups assigned to the user. (administrative)
user BETA Get user's primary groups

services/prgroups/admin

Consumer: required Token: required Scopes: studies SSL: required
https://apps.umcs.pl/services/prgroups/admin

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 list of user's primary groups. Only those groups with full access will be included which supergroup access is partial.
user_id optional

Default value: (unused)

ID of a user whose group contents should be returned. This argument may be used only by users with proper administrative privileges.
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 of primary_group 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 list of dictionaries describing primary groups. Each dictionary contains keys listed in fields argument.

Thrown errors:

  • object_not_found - user could not be found; param_name is equal to user_id.

services/prgroups/auto_assign_users

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://apps.umcs.pl/services/prgroups/auto_assign_users

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.

Auto assign users for this descriptor.
descriptor_id required

Descriptor 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:

Empty dict on success

Thrown errors:

  • object_not_found - primary group descriptor could not be found; param_name is equal to descriptor_id.

services/prgroups/create_descriptor

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://apps.umcs.pl/services/prgroups/create_descriptor

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 descriptor of primary groups.
source required

An XML representation of the descriptor.
dry_run optional

Default value: false

Validate submitted arguments, but do not perform any persistent changes.
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 the following structure:

  • descriptor_id - created descriptor ID.

    This key will be available even if you set dry_run argument to true - in this case the value is just extracted from the source of the descriptor.

Thrown errors:

  • object_invalid - object is in invalid state.

    Possible reasons:

    • id_duplicated - descriptor ID is already in use;

    • parse_error - descriptor source could not be parsed; an additional key parse_messages with the list of parse error messages will be provided.

services/prgroups/delete_descriptors

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://apps.umcs.pl/services/prgroups/delete_descriptors

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 descriptors of primary groups.
descriptor_ids required

List of descriptor IDs.
format optional

Default value: json

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

Required only if you've chosen jsonp as a return format.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required.

Returned value:

A dictionary of the following structure:

  • matched - a list of descriptor IDs which were actually deleted.

services/prgroups/descriptor

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://apps.umcs.pl/services/prgroups/descriptor

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 descriptor of primary groups.
descriptor_id required

Descriptor ID.
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.
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:

  • Primary:

    • id - descriptor ID;

    • name - a LangDict object with the name of the descriptor.

  • Secondary:

    • source - XML representation of the descriptor;

    • assigned_users - list of users that have some groups assigned from this descriptor.

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

    • auto_assigned_users - list of users that have some groups assigned by sql in descriptor.

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

Thrown errors:

  • object_not_found - primary group descriptor could not be found; param_name is equal to descriptor_id.

services/prgroups/descriptors

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://apps.umcs.pl/services/prgroups/descriptors

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 descriptors of primary groups.
descriptor_ids required

List of descriptor IDs.
fields optional

Default value: id|name

Selector of result fields you are interested in. The selector must contain subset of primary fields, which are described in the returns section of descriptor 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 mapping descriptor IDs to dictionaries describing the descriptors (as returned by descriptor method). If specified descriptor could not be found, null is returned instead of a dictionary.

services/prgroups/descriptors_all

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://apps.umcs.pl/services/prgroups/descriptors_all

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 list of all descriptors of primary groups.
fields optional

Default value: id|name

Selector of result fields you are interested in. The selector must contain subset of primary fields, which are described in the returns section of descriptor 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 list of dictionaries describing descriptors (as returned by descriptor method).

services/prgroups/primary_group

Consumer: required Token: required Scopes: studies SSL: required
https://apps.umcs.pl/services/prgroups/primary_group

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 primary group.
primary_group_id required

Primary group ID. Note that an empty string is a valid ID value.
user_id optional

Default value: (unused)

ID of a user whose group contents should be returned. This argument may be used only by users with proper administrative privileges.
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.
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:

    • id - primary group ID;

    • access - user access level - can be either full or partial.

      If user_id argument is provided, an additional none value may be returned in case the referenced user does not have currently access to the group.

    • auto_assigned - if access is "full" and access is assigned automatically.

      If user_id argument is provided, an additional none value may be returned in case the referenced user does not have currently access to the group.

    • admin_access - administrator access level - can be either full or partial;

    • name - a LangDict object with the group name.

  • Secondary:

    • subgroups - list of dictionaries describing subgroups.

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

    • subgroups_deep - List of subgroups. Note that subgroups will also have their subgroups_deep field filled using the same subselector..

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

    • users - list of dictionaries describing users that belong to this group or null if you do not have full access to the group.

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

Thrown errors:

  • object_not_found - primary group could not be found; param_name is equal to primary_group_id;

  • object_not_found - user could not be found; param_name is equal to user_id.

services/prgroups/primary_groups

Consumer: required Token: required Scopes: studies SSL: required
https://apps.umcs.pl/services/prgroups/primary_groups

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 primary groups.
primary_group_ids required

List of primary group IDs.
user_id optional

Default value: (unused)

ID of a user whose group contents should be returned. This argument may be used only by users with proper administrative privileges.
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 of primary_group 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 mapping primary group IDs to dictionaries describing the groups (as returned by primary_group method). If specified group could not be found, null is returned instead of a dictionary.

Thrown errors:

  • object_not_found - user could not be found; param_name is equal to user_id.

services/prgroups/schema

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://apps.umcs.pl/services/prgroups/schema

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 schema of descriptors of primary groups.
(this method takes no parameters)
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:

An XML Schema file.

services/prgroups/update_descriptor

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://apps.umcs.pl/services/prgroups/update_descriptor

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 a descriptor of primary groups.
descriptor_id required

Descriptor ID.
source required

An XML representation of the descriptor.
dry_run optional

Default value: false

Validate submitted arguments, but do not perform any persistent changes.
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:

An empty dictionary returned if the method has been executed successfully. Some keys may be added in the future.

Thrown errors:

  • object_invalid - object is in invalid state.

    Possible reasons:

    • id_mismatched - supplied source does not refer to the current descriptor;

    • parse_error - descriptor source could not be parsed; an additional key parse_messages with the list of parse error messages will be provided.

  • object_not_found - primary group descriptor could not be found; param_name is equal to descriptor_id.

services/prgroups/update_user

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

Consumer: required (administrative) Token: optional Scopes: n/a SSL: not required
https://apps.umcs.pl/services/prgroups/update_user

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 primary groups assigned to the user.

Currently calling this method with access token causes a method_forbidden error.
user_id required

User ID.
primary_group_ids required

List of primary group 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 optional oauth_token for Token authorization.

Returned value:

An empty dictionary returned if the method has been executed successfully. Some keys may be added in the future.

Thrown errors:

  • object_not_found - primary group could not be found; param_name is equal to primary_group_ids;

  • object_not_found - user could not be found; param_name is equal to user_id.

services/prgroups/user

Consumer: required Token: required Scopes: studies SSL: required
https://apps.umcs.pl/services/prgroups/user

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 list of user's primary groups. Only those groups with full access will be included which supergroup access is partial.
user_id optional

Default value: (unused)

ID of a user whose group contents should be returned. This argument may be used only by users with proper administrative privileges.
fields optional

Default value: id|name

Selector of result fields you are interested in. The selector must contain subset of primary fields, which are described in the returns section of primary_group method.

access optional

Default value: full

Filter groups with selected user access
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 list of dictionaries describing primary groups. Each dictionary contains keys listed in fields argument.

Thrown errors:

  • object_not_found - user could not be found; param_name is equal to user_id.
USOS API ver. 7.1.0.0-4, 0e1fe7fc, dirty (2024-08-27)