Skip to content

Commit 0afabe1

Browse files
harminiusalex-cittomasMizera
authored
Add user management methods to py-client integration page (#563)
Co-authored-by: Alexandra <[email protected]> Co-authored-by: Tomas Mizera <[email protected]>
1 parent e4a0f48 commit 0afabe1

File tree

5 files changed

+211
-41
lines changed

5 files changed

+211
-41
lines changed

‎src/.vitepress/sidebar/en.js

+2-1
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,8 @@ export default {
100100
collapsed: true,
101101
items: [
102102
{ text: 'Custom Mobile App', link: '/dev/customapp/' },
103-
{ text: 'Integrate Mergin Maps', link: '/dev/integration/' },
103+
{ text: 'Python API Client', link: '/dev/integration/' },
104+
{ text: 'C++ API Client', link: '/dev/integration-cpp/' },
104105
{ text: 'PostgreSQL DB Sync', link: '/dev/dbsync/' },
105106
{ text: 'Media Sync', link: '/dev/media-sync/' },
106107
{ text: 'Work Packages', link: '/dev/work-packages/' },

‎src/dev/integration-cpp/index.md

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# C++ API Client
2+
[[toc]]
3+
4+
Do you want to integrate <MainPlatformNameLink />? <MainPlatformName /> is an open platform that aims to be developer friendly and it has been designed to allow easy integration with other software.
5+
6+
## Installation
7+
C++ API client is completely without any dependencies. To install the client, just download the binary for your platform from <GitHubRepo id="MerginMaps/cpp-api-client/releases"/> and use it from the command line.
8+
9+
The client uses Qt-based <GitHubRepo id="MerginMaps/mobile/tree/master/core" desc="Mergin Maps API core library" /> used by the <MainDomainNameLink desc="mobile app" /> to sync the projects in the mobile application. Go to <GitHubRepo id="MerginMaps/cpp-api-client" /> repository for more information on how to use it.
10+
11+
## Command line interface
12+
When the client is installed, it comes with `mergin` command line tool.
13+
14+
```bash
15+
$ mergin --help
16+
Usage: mergin [OPTIONS] COMMAND [ARGS]...
17+
18+
Options:
19+
--help Show this message and exit.
20+
--version Show the version information.
21+
--username Mergin username (or MERGIN_USERNAME env. variable)
22+
--password Mergin password (or MERGIN_PASSWORD env. variable)
23+
--url Mergin url (defaults to app.merginmaps.com)
24+
25+
Commands:
26+
create Create a new project on Mergin server
27+
download Download last version of mergin project
28+
sync Pull&Push the changes
29+
remove Remove project from server.
30+
```

‎src/dev/integration/index.md

+173-36
Original file line numberDiff line numberDiff line change
@@ -1,73 +1,210 @@
1-
# Integrate Mergin Maps
1+
---
2+
outline: deep
3+
---
4+
5+
# Python API Client
26
[[toc]]
37

48
Do you want to integrate <MainPlatformNameLink />? <MainPlatformName /> is an open platform that aims to be developer friendly and it has been designed to allow easy integration with other software.
59

6-
7-
## Python client module
8-
The Python client module is the easiest way to programmatically use <MainPlatformNameLink />. You can use Python API or a command-line tool to easily work with <MainPlatformName /> projects, such as to get project status, push and pull changes, or to download, create and delete projects.
9-
10-
The <GitHubRepo id="MerginMaps/python-api-client" /> repository contains the source code of the Python client module and more information on how to use it.
10+
## Installation
11+
The Python client module is the easiest way to programmatically use <MainPlatformNameLink />. You can use Python API or a command-line tool to easily work with your projects, such as to get project status, push and pull changes. You can also create user accounts and manage their roles.
1112

1213
Python client is available in the PyPI repository and can be installed with `pip`:
1314

1415
```
1516
pip3 install mergin-client
1617
```
1718

18-
### Python module
19+
## Command line interface
20+
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.
21+
22+
For example, to download a <MainPlatformName /> project to a local folder:
23+
```
24+
mergin download john/project1 ~/mergin/project1
25+
```
26+
For more details, visit <GitHubRepo id="MerginMaps/python-api-client" />.
27+
28+
## Python module
1929
To use <MainPlatformNameLink /> from Python, just create `MerginClient` object and then use it. Here, for instance, to download a project:
2030

2131
```python
2232
import mergin
2333

24-
client = mergin.MerginClient(login='john', password='topsecret')
34+
client = mergin.MerginClient(login='john', password='T0p_secret')
2535
client.download_project('lutraconsulting/Basic survey', '/tmp/basic-survey')
2636
```
2737
If you have <QGISPluginName /> installed and you want to use it from the QGIS' Python console
2838

2939
```python
3040
import Mergin.mergin as mergin
31-
client = mergin.MerginClient(login='john', password='topsecret')
41+
client = mergin.MerginClient(login='john', password='T0p_secret')
3242
```
3343

34-
### Python command line interface
35-
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.
44+
## API reference - users
3645

37-
For example, to download a <MainPlatformName /> project to a local folder:
46+
You can create new users and manage their roles using the following methods.
47+
48+
::: warning API availability
49+
The following methods are available for Python API Client versions `0.10.0` or higher, using server versions `2025.2.0` or higher.
50+
:::
51+
52+
### Create a user
53+
54+
```python
55+
client.create_user(<email>, <password>, <workspace_id>, <workspace_role>, [username], [notify_user])
3856
```
39-
mergin download john/project1 ~/mergin/project1
57+
58+
The caller must be a workspace admin, owner or server administrator.
59+
60+
Arguments:
61+
62+
`email` (string): Must be a unique email.
63+
64+
`password` (string): Must meet security requirements.
65+
66+
`workspace_id` (int) <span title="Ignored on Community edition servers">:information_source:</span> : The workspace ID where the user will be added.
67+
68+
`workspace_role` (string) <span title="Ignored on Community edition servers">:information_source:</span> : The user’s role in the workspace. [See the roles options](../../manage/permissions/index.md#workspace-member-roles-overview).
69+
70+
`username` (string, optional): If not provided, it will be automatically generated from the email address.
71+
72+
`notify_user` (Boolean, optional): If true, confirmation email and other email communication will be sent to the email address (invitations, access requests etc.). Default is `False`.
73+
74+
Example:
75+
```python
76+
client.create_user("[email protected]", "T0p_secret", 1, "editor", notify_user=True)
4077
```
41-
For more details, visit <GitHubRepo id="MerginMaps/python-api-client" />.
4278

43-
## C++ standalone client
44-
C++ Client has advantage over Python that it is completely without any dependencies.
79+
> :information_source: `workspace_id` and `workspace_role` arguments are ignored on Community edition servers.
80+
81+
---
82+
83+
### Workspace members methods
84+
85+
These methods are available for Cloud and Enterprise edition servers.
86+
87+
::: warning API availability
88+
The following methods are available for Python API Client versions `0.10.0` or higher, using server versions `2025.2.0` or higher.
89+
:::
4590

46-
To install the C++ client, just download the binary for your platform from <GitHubRepo id="MerginMaps/cpp-api-client/releases"/> and use it from the command line.
91+
The caller of the following methods must be a workspace admin, owner or server administrator.
4792

48-
Go to <GitHubRepo id="MerginMaps/cpp-api-client" /> repository for more information on how to use it.
93+
#### List members
4994

50-
### C++ Command line tool
51-
When the client is installed, it comes with `mergin` command line tool.
95+
```python
96+
client.list_workspace_members(<workspace_id>)
97+
```
98+
Arguments:
5299

53-
```bash
54-
$ mergin --help
55-
Usage: mergin [OPTIONS] COMMAND [ARGS]...
100+
`workspace_id` (int): ID of the workspace.
56101

57-
Options:
58-
--help Show this message and exit.
59-
--version Show the version information.
60-
--username Mergin username (or MERGIN_USERNAME env. variable)
61-
--password Mergin password (or MERGIN_PASSWORD env. variable)
62-
--url Mergin url (defaults to app.merginmaps.com)
102+
#### Get member detail
63103

64-
Commands:
65-
create Create a new project on Mergin server
66-
download Download last version of mergin project
67-
sync Pull&Push the changes
68-
remove Remove project from server.
104+
```python
105+
client.get_workspace_member(<workspace_id>, <user_id>)
69106
```
107+
Arguments:
108+
109+
`workspace_id` (int): ID of the workspace.
110+
111+
`user_id` (int): ID of the user.
112+
113+
#### Update member role
114+
115+
```python
116+
client.update_workspace_member(<workspace_id>, <user_id>, <workspace_role>, [reset_projects_roles])
117+
```
118+
Arguments:
119+
120+
`workspace_id` (int): ID of the workspace.
121+
122+
`user_id` (int): ID of the user.
123+
124+
`workspace_role` (string): New role. [See the roles options](../../manage/permissions/index.md#workspace-member-roles-overview).
125+
126+
`reset_projects_roles` (Boolean, optional): If true, overridden project roles (explicitly shared projects access) will be reset. Default is `False`.
127+
128+
#### Remove member
129+
130+
```python
131+
client.remove_workspace_member(<workspace_id>, <user_id>)
132+
```
133+
Arguments:
134+
135+
`workspace_id` (int): ID of the workspace.
136+
137+
`user_id` (int): ID of the user.
138+
139+
> The user account is not removed. This method only removes their access to the workspace.
140+
141+
---
142+
143+
### Project collaborators methods
144+
145+
These methods are available for all server types.
146+
147+
::: warning API availability
148+
The following methods are available for Python API Client versions `0.10.0` or higher, using server versions `2025.2.0` or higher.
149+
:::
150+
151+
The caller of the following methods must be a workspace admin, owner, project owner or server administrator.
152+
153+
The following methods accept project ids (of type `uuid`). You can find project id via <GitHubRepo id="MerginMaps/python-api-client/blob/634237890afd9f28f03953e5a01376b56f5abf5c/mergin/client.py#L572" desc="projects_list" /> and <GitHubRepo id="MerginMaps/python-api-client/blob/634237890afd9f28f03953e5a01376b56f5abf5c/mergin/client.py#L641" desc="project_info" /> methods.
154+
155+
#### List project collaborators
156+
157+
```python
158+
client.list_project_collaborators(<project_id>)
159+
```
160+
Arguments:
161+
162+
`project_id` (string): ID of the project.
163+
164+
#### Add project collaborator
165+
166+
Adds a user as project collaborator. This method is good for sharing projects with guests or upgrading roles of members for specific projects.
167+
On Cloud, the user must be a in the workspace where the project belongs.
168+
169+
```python
170+
client.add_project_collaborator(<project_id>, <user>, <project_role>)
171+
```
172+
Arguments:
173+
174+
`project_id` (string): ID of the project.
175+
176+
`user` (string): Email or username of the user to be added to the project.
177+
178+
`project_role`: (string): Role of the user in the project. [See the roles options](../../manage/permissions/index.md#project-permissions-overview)
179+
180+
#### Update project collaborator role
181+
182+
```python
183+
client.update_project_collaborator(<project_id>, <user_id>, <project_role>)
184+
```
185+
Arguments:
186+
187+
`project_id` (string): ID of the project.
188+
189+
`user_id` (int): ID of the user.
190+
191+
`project_role`: (string): New role. [See the roles options](../../manage/permissions/index.md#project-permissions-overview)
192+
193+
> The user must be first added to the project (via [Add project collaborator](./index.md#add-project-collaborator)) before calling this method, even if he/she is already a workspace member or guest.
194+
195+
#### Remove project collaborator
196+
197+
```python
198+
client.remove_project_collaborator(<project_id>, <user_id>)
199+
```
200+
Arguments:
201+
202+
`project_id` (string): ID of the project.
203+
204+
`user_id` (int): ID of the user.
205+
206+
> The user account is not removed, only the project access.
70207
71-
### C++ Mergin Maps API core library
208+
## Further details
72209

73-
Client is based on the Qt-based <GitHubRepo id="MerginMaps/mobile/tree/master/core" desc="Mergin Maps API core library" /> used by the <MainDomainNameLink desc="Mergin Maps mobile app" /> to sync the projects in the mobile application.
210+
The <GitHubRepo id="MerginMaps/python-api-client" /> repository contains the source code and more information on how to use it.

‎src/index.md

+4-3
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,8 @@ The ecosystem consist of various components:
9696

9797
## For Developers
9898
- [Custom Mobile App](./dev/customapp/)
99-
- [Integrate Mergin Maps](./dev/integration/)
99+
- [Python Client Module Integration](./dev/integration/)
100+
- [C++ Standalone Client Integration](./dev/integration-cpp/)
100101
- [PostgreSQL DB Sync](./dev/dbsync/)
101102
- [Media Sync](./dev/media-sync/)
102103
- [Work Packages](./dev/work-packages/)
@@ -108,11 +109,11 @@ The ecosystem consist of various components:
108109
- [Security](./server/security/)
109110
- [Upgrade](./server/upgrade/)
110111
- [Administer](./server/administer/)
111-
- [Troubleshoot Custom Servers](./server/troubleshoot/)
112112
- [Administration Panel](./server/dashboard/)
113+
- [Troubleshoot Custom Servers](./server/troubleshoot/)
113114
- [Using Mergin Maps Mobile App and QGIS Plugin with a Custom Server](./server/plugin-mobile-app/)
114115

115-
## Migrate
116+
## Migrate to Mergin Maps
116117
- [From QField](./migrate/qfield/)
117118
- [From ArcGIS](./migrate/arcgis/)
118119
- [From Fulcrum](./migrate/fulcrumapp/)

‎src/migrate/arcgis/index.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,10 @@ Here is a comparison of the main components of both ecosystems:
2727
| ArcGIS QuickCapture | <MobileAppName /> | field survey application |
2828
| ArcGIS Survey123 | <MobileAppName /> | form-based field survey application |
2929
| ArcGIS Field Maps** | <MobileAppName /> | field survey application |
30-
| ArcGIS Maps SDK | [Python client](../../dev/integration/#python-client-module) and QGIS API| developer SDK |
30+
| ArcGIS Maps SDK | [Python client](../../dev/integration/) and QGIS API| developer SDK |
3131

3232
*ArcGIS Pro replaced [ArcMap](https://en.wikipedia.org/wiki/ArcMap)
33+
3334
**ArcGIS Field Maps replaced ArcGIS Collector since the end of [2021](https://www.Esri.com/arcgis-blog/products/collector/field-mobility/arcgis-collector-on-windows-platform-is-retired/)
3435

3536
## Migrate from ArcGIS to QGIS

0 commit comments

Comments
 (0)