.. _user-group-methods-ref:

user_group methods
==================

add_user_to_user_group 
----------------------

.. py:function:: add_user_to_user_group(apiuser, usergroupid, userid)

   Adds a user to a `user group`. If the user already exists in the group
   this command will return false.

   This command can only be run using an |authtoken| with admin rights to
   the specified user group.

   This command takes the following options:

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param usergroupid: Set the name of the `user group` to which a
       user will be added.
   :type usergroupid: int
   :param userid: Set the `user_id` of the user to add to the group.
   :type userid: int

   Example output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : {
         "success": True|False # depends on if member is in group
         "msg": "added member `<username>` to user group `<groupname>` |
                 User is already in that group"

     }
     error :  null

   Example error output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : null
     error :  {
       "failed to add member to user group `<user_group_name>`"
     }


create_user_group 
-----------------

.. py:function:: create_user_group(apiuser, group_name, description=<Optional:''>, owner=<Optional:<OptionalAttr:apiuser>>, active=<Optional:True>, sync=<Optional:None>)

   Creates a new user group.

   This command can only be run using an |authtoken| with admin rights to
   the specified repository.

   This command takes the following options:

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param group_name: Set the name of the new user group.
   :type group_name: str
   :param description: Give a description of the new user group.
   :type description: str
   :param owner: Set the owner of the new user group.
       If not set, the owner is the |authtoken| user.
   :type owner: Optional(str or int)
   :param active: Set this group as active.
   :type active: Optional(``True`` | ``False``)
   :param sync: Set enabled or disabled the automatically sync from
       external authentication types like ldap. If User Group will be named like
       one from e.g ldap and sync flag is enabled members will be synced automatically.
       Sync type when enabled via API is set to `manual_api`
   :type sync: Optional(``True`` | ``False``)

   Example output:

   .. code-block:: bash

       id : <id_given_in_input>
       result: {
                 "msg": "created new user group `<groupname>`",
                 "user_group": <user_group_object>
               }
       error:  null

   Example error output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : null
     error :  {
       "user group `<group name>` already exist"
       or
       "failed to create group `<group name>`"
     }


delete_user_group 
-----------------

.. py:function:: delete_user_group(apiuser, usergroupid)

   Deletes the specified `user group`.

   This command can only be run using an |authtoken| with admin rights to
   the specified repository.

   This command takes the following options:

   :param apiuser: filled automatically from apikey
   :type apiuser: AuthUser
   :param usergroupid:
   :type usergroupid: int

   Example output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : {
       "msg": "deleted user group ID:<user_group_id> <user_group_name>"
     }
     error :  null

   Example error output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : null
     error :  {
       "failed to delete user group ID:<user_group_id> <user_group_name>"
       or
       "RepoGroup assigned to <repo_groups_list>"
     }


get_user_group 
--------------

.. py:function:: get_user_group(apiuser, usergroupid)

   Returns the data of an existing user group.

   This command can only be run using an |authtoken| with admin rights to
   the specified repository.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param usergroupid: Set the user group from which to return data.
   :type usergroupid: str or int

   Example error output:

   .. code-block:: bash

       {
         "error": null,
         "id": <id>,
         "result": {
           "active": true,
           "group_description": "group description",
           "group_name": "group name",
           "permissions": [
             {
               "name": "owner-name",
               "origin": "owner",
               "permission": "usergroup.admin",
               "type": "user"
             },
             {
             {
               "name": "user name",
               "origin": "permission",
               "permission": "usergroup.admin",
               "type": "user"
             },
             {
               "name": "user group name",
               "origin": "permission",
               "permission": "usergroup.write",
               "type": "user_group"
             }
           ],
           "permissions_summary": {
             "repositories": {
               "aa-root-level-repo-1": "repository.admin"
             },
             "repositories_groups": {}
           },
           "owner": "owner name",
           "users": [],
           "users_group_id": 2
         }
       }


get_user_groups 
---------------

.. py:function:: get_user_groups(apiuser)

   Lists all the existing user groups within RhodeCode.

   This command can only be run using an |authtoken| with admin rights to
   the specified repository.

   This command takes the following options:

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser

   Example error output:

   .. code-block:: bash

       id : <id_given_in_input>
       result : [<user_group_obj>,...]
       error : null


grant_user_group_permission_to_user_group 
-----------------------------------------

.. py:function:: grant_user_group_permission_to_user_group(apiuser, usergroupid, sourceusergroupid, perm)

   Give one user group permissions to another user group.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param usergroupid: Set the user group on which to edit permissions.
   :type usergroupid: str or int
   :param sourceusergroupid: Set the source user group to which
       access/permissions will be granted.
   :type sourceusergroupid: str or int
   :param perm: (usergroup.(none|read|write|admin))
   :type perm: str

   Example output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : {
       "msg": "Granted perm: `<perm_name>` for user group: `<source_user_group_name>` in user group: `<user_group_name>`",
       "success": true
     }
     error :  null


grant_user_permission_to_user_group 
-----------------------------------

.. py:function:: grant_user_permission_to_user_group(apiuser, usergroupid, userid, perm)

   Set permissions for a user in a user group.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param usergroupid: Set the user group to edit permissions on.
   :type usergroupid: str or int
   :param userid: Set the user from whom you wish to set permissions.
   :type userid: str
   :param perm: (usergroup.(none|read|write|admin))
   :type perm: str

   Example output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : {
       "msg": "Granted perm: `<perm_name>` for user: `<username>` in user group: `<user_group_name>`",
       "success": true
     }
     error :  null


remove_user_from_user_group 
---------------------------

.. py:function:: remove_user_from_user_group(apiuser, usergroupid, userid)

   Removes a user from a user group.

   * If the specified user is not in the group, this command will return
     `false`.

   This command can only be run using an |authtoken| with admin rights to
   the specified user group.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param usergroupid: Sets the user group name.
   :type usergroupid: str or int
   :param userid: The user you wish to remove from |RCE|.
   :type userid: str or int

   Example output:

   .. code-block:: bash

       id : <id_given_in_input>
       result: {
                 "success":  True|False,  # depends on if member is in group
                 "msg": "removed member <username> from user group <groupname> |
                         User wasn't in group"
               }
       error:  null


revoke_user_group_permission_from_user_group 
--------------------------------------------

.. py:function:: revoke_user_group_permission_from_user_group(apiuser, usergroupid, sourceusergroupid)

   Revoke the permissions that one user group has to another.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param usergroupid: Set the user group on which to edit permissions.
   :type usergroupid: str or int
   :param sourceusergroupid: Set the user group from which permissions
       are revoked.
   :type sourceusergroupid: str or int

   Example output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : {
       "msg": "Revoked perm for user group: `<user_group_name>` in user group: `<target_user_group_name>`",
       "success": true
     }
     error :  null


revoke_user_permission_from_user_group 
--------------------------------------

.. py:function:: revoke_user_permission_from_user_group(apiuser, usergroupid, userid)

   Revoke a users permissions in a user group.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param usergroupid: Set the user group from which to revoke the user
       permissions.
   :type: usergroupid: str or int
   :param userid: Set the userid of the user whose permissions will be
       revoked.
   :type userid: str

   Example output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : {
       "msg": "Revoked perm for user: `<username>` in user group: `<user_group_name>`",
       "success": true
     }
     error :  null


update_user_group 
-----------------

.. py:function:: update_user_group(apiuser, usergroupid, group_name=<Optional:''>, description=<Optional:''>, owner=<Optional:None>, active=<Optional:True>, sync=<Optional:None>)

   Updates the specified `user group` with the details provided.

   This command can only be run using an |authtoken| with admin rights to
   the specified repository.

   :param apiuser: This is filled automatically from the |authtoken|.
   :type apiuser: AuthUser
   :param usergroupid: Set the id of the `user group` to update.
   :type usergroupid: str or int
   :param group_name: Set the new name the `user group`
   :type group_name: str
   :param description: Give a description for the `user group`
   :type description: str
   :param owner: Set the owner of the `user group`.
   :type owner: Optional(str or int)
   :param active: Set the group as active.
   :type active: Optional(``True`` | ``False``)
   :param sync: Set enabled or disabled the automatically sync from
       external authentication types like ldap. If User Group will be named like
       one from e.g ldap and sync flag is enabled members will be synced automatically.
       Sync type when enabled via API is set to `manual_api`
   :type sync: Optional(``True`` | ``False``)

   Example output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : {
       "msg": 'updated user group ID:<user group id> <user group name>',
       "user_group": <user_group_object>
     }
     error :  null

   Example error output:

   .. code-block:: bash

     id : <id_given_in_input>
     result : null
     error :  {
       "failed to update user group `<user group name>`"
     }