Custom groups
:: services/csgroups 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 provides methods for accessing and manipulating custom groups created by users. You can create custom group by adding:

  • a primary group,

  • another custom group,

  • an individual user,

  • an individual email address.

Methods

create BETA Create a custom group.
custom_group BETA Get information on a given custom group.
custom_groups BETA Get information on multiple custom groups.
delete BETA Delete custom groups.
update BETA Update a custom group.
user BETA Get user's custom groups.

services/csgroups/create

Consumer: required Token: required Scopes: mailclient | studies SSL: required
https://usosapps.us.edu.pl/services/csgroups/create

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 custom group.

name required

Name of the group. No more than 100 characters.

primary_group_ids optional

Default value: (empty string)

List of primary group IDs that are part of this group.

custom_group_ids optional

Default value: (empty string)

List of custom group IDs that are part of this group.

user_ids optional

Default value: (empty string)

List of user IDs that are part of this group.

emails optional

Default value: (empty string)

List of email addresses that are part of this group.

strict optional

Default value: true

Should a nonexistent object referenced by primary_group_ids, custom_group_ids or user_ids argument cause an error? If set to false, all invalid references will be silently discarded.

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:

  • custom_group_id - created group ID.

Thrown errors:

  • object_not_found - custom group could not be found; param_name is equal to custom_group_ids;

  • 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_ids.

services/csgroups/custom_group

Consumer: required Token: required Scopes: mailclient | studies SSL: required
https://usosapps.us.edu.pl/services/csgroups/custom_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 custom group.

custom_group_id required

Custom group 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. Plus required oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • Primary:

    • id - group ID;

    • name - group name.

  • Secondary:

    • primary_groups - list of dictionaries describing primary groups that were added to this group.

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

    • custom_groups - list of dictionaries describing custom groups that were added to this group; each dictionary contains primary fields described in this section.

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

    • users - list of dictionaries describing users that were added to this group.

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

    • emails - list of individual email addresses added to this group.

Thrown errors:

  • object_not_found - custom group could not be found; param_name is equal to custom_group_id.

services/csgroups/custom_groups

Consumer: required Token: required Scopes: mailclient | studies SSL: required
https://usosapps.us.edu.pl/services/csgroups/custom_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 custom groups.

custom_group_ids required

List of custom group 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 custom_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 custom group IDs to dictionaries describing the groups (as returned by custom_group method). If specified group could not be found, null is returned instead of a dictionary.

services/csgroups/delete

Consumer: required Token: required Scopes: mailclient | studies SSL: required
https://usosapps.us.edu.pl/services/csgroups/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 custom groups.

custom_group_ids required

List of custom 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 required oauth_token for Token authorization.

Returned value:

A dictionary of the following structure:

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

services/csgroups/update

Consumer: required Token: required Scopes: mailclient | studies SSL: required
https://usosapps.us.edu.pl/services/csgroups/update

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 custom group.

custom_group_id required

Custom group ID.

name optional

Default value: (unchanged)

Name of the group. No more than 100 characters.

primary_group_ids optional

Default value: (unchanged)

List of primary group IDs that are part of this group.

custom_group_ids optional

Default value: (unchanged)

List of custom group IDs that are part of this group.

user_ids optional

Default value: (unchanged)

List of user IDs that are part of this group.

emails optional

Default value: (unchanged)

List of email addresses that are part of this group.

strict optional

Default value: true

Should a nonexistent object referenced by primary_group_ids, custom_group_ids or user_ids argument cause an error? If set to false, all invalid references will be silently discarded.

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:

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

Thrown errors:

  • object_not_found - custom group could not be found; param_name is equal to custom_group_id;

  • object_not_found - custom group could not be found; param_name is equal to custom_group_ids;

  • 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_ids.

services/csgroups/user

Consumer: required Token: required Scopes: mailclient | studies SSL: required
https://usosapps.us.edu.pl/services/csgroups/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 user's custom 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 custom_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 custom groups (as returned by custom_group method).

USOS API ver. 7.1.0.0-7, d04098c0 (2024-11-07)