Skip to content

Draft: Add user management methods to py-client integration page #563

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 90 additions & 0 deletions src/dev/integration.md
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should add a comment here for our CE users what they need to do to use this API

Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,96 @@ import Mergin.mergin as mergin
client = mergin.MerginClient(login='john', password='topsecret')
```

#### User and roles management
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this relevant only to the Python module or also to the Python command line interface? If both, this should be a subsection (### User and role management) and moved below the Python CLI subsection,

The #### level of subsection is in my opinion the last subsection level that looks okay. ##### subsections (that are used here) do not look very good when the page is compiled, so I would avoid using them. If it's necessary to structure the page this way, I would considering making separate pages for Python integration and C++ integration (to remove one level of subsections).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm.. the new commands are available only in the Python module so far. It'll be added to the CLI soon but the syntax is different anyway.
As the content will grow, the dedicated pages make sense.

You can create new users and manage their permissions using the following methods:

##### Create a user
```python
client.create_user(<email>, <password>, <workspace_id>, <workspace_role>, [username], [notify_user])
```
Arguments:
`email` (str): Must be a unique email
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we try some other description instead of "unique email"? Maybe something like: "an email that is not yet used on the server" or "email not yet associated with an account"

Also, I would considering writing the data types in full (i.e. string, integer, etc.) to be consistent with this for instance.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1, sure - unique email is confusing, indeed
2, shall we put the arguments in the table like in the link?

`passowrd` (str): Must meet security requirements.
`workspace_id` (int): The workspace ID where the user will be added.
`workspace_role`(str): The user’s role in the workspace. [See the roles options](../manage/permissions.md)
`username` (str, optional): Custom username; autogenerated if not provided.
`notify_user` (bool, optional): Flag for email notifications (invitations, access requests etc.). Default is `False`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`notify_user` (bool, optional): Flag for email notifications (invitations, access requests etc.). Default is `False`
`notify_user` (bool, optional): Sends a confirmation email to the `email` address and enables email communication for the new account (invitation emails, access request emails and more). Default is `False`.


Example:
```python
client.create_user("[email protected]", "topsecret", 1, "editor", notify_user=True)
```

##### Get a workspace member detail
```python
client.get_workspace_member(<workspace_id>, <user_id>)
```
Arguments:
`workspace_id` (int): The workspace where the user will be added.
`user_id` (int): ID of the user to be added.

##### Get a list of workspace members
```python
client.list_workspace_members(<workspace_id>)
```
Arguments:
`workspace_id` (int): The workspace ID to list the members.

##### Update workspace role
```python
client.update_workspace_member(<workspace_id>, <user_id>, <workspace_role>, [reset_projects_roles])
```
Arguments:
`workspace_id` (int): Workspace ID where to update user's role.
`user_id` (int): User to be updated.
`workspace_role` (str): New role.
`reset_projects_roles` (bool, optional): Flag to remove all project specific roles.

##### Remove a user from a workspace
```python
client.remove_workspace_member(<workspace_id>, <user_id>)
```
Arguments:
`workspace_id` (int): Workspace ID from which to remove the user.
`user_id` (int): ID of the user to be removed.

##### Get a list of project collaborators
```python
client.list_project_collaborators(<project_id>)
```
Arguments:
`project_id` (int): Project ID to list the users.

##### Add a user to project
```python
client.add_project_collaborator(<project_id>, <user>, <project_role>)
```
Arguments:
`project_id` (int): Project ID to add the user.
`user` (str): Email or username of the user to be added to the project.
`project_role`: (str): Role of the user in the project.

##### Update project role
```python
client.update_project_collaborator(<project_id>, <user_id>, <project_role>)
```
Arguments:
`project_id` (int): Project ID in which the role will be updated.
`user_id` (int): ID of the user to update.
`project_role`: (str): New role.

Note:
The user must have a project role to update it. You create one using the previous method.

##### Update project role
```python
client.remove_project_collaborator(<project_id>, <user_id>)
```
Arguments:
`project_id` (int): Project ID to remove the user.
`user_id` (int): ID of the user to remove from the project.


### Python command line interface
For those who prefer using terminal, there is `mergin` command line tool shipped with the Python client. With several built-in commands, it is possible to download <MainPlatformName /> projects, push/pull changes, create or delete projects and more.

Expand Down
Loading