diff --git a/src/.vitepress/sidebar/en.js b/src/.vitepress/sidebar/en.js index 2ce1f768..4f2886bd 100644 --- a/src/.vitepress/sidebar/en.js +++ b/src/.vitepress/sidebar/en.js @@ -100,7 +100,8 @@ export default { collapsed: true, items: [ { text: 'Custom Mobile App', link: '/dev/customapp/' }, - { text: 'Integrate Mergin Maps', link: '/dev/integration/' }, + { text: 'Python API Client', link: '/dev/integration/' }, + { text: 'C++ API Client', link: '/dev/integration-cpp/' }, { text: 'PostgreSQL DB Sync', link: '/dev/dbsync/' }, { text: 'Media Sync', link: '/dev/media-sync/' }, { text: 'Work Packages', link: '/dev/work-packages/' }, diff --git a/src/dev/integration-cpp/index.md b/src/dev/integration-cpp/index.md new file mode 100644 index 00000000..af5d8462 --- /dev/null +++ b/src/dev/integration-cpp/index.md @@ -0,0 +1,30 @@ +# C++ API Client +[[toc]] + +Do you want to integrate ? is an open platform that aims to be developer friendly and it has been designed to allow easy integration with other software. + +## Installation +C++ API client is completely without any dependencies. To install the client, just download the binary for your platform from and use it from the command line. + +The client uses Qt-based used by the to sync the projects in the mobile application. Go to repository for more information on how to use it. + +## Command line interface +When the client is installed, it comes with `mergin` command line tool. + +```bash +$ mergin --help +Usage: mergin [OPTIONS] COMMAND [ARGS]... + +Options: + --help Show this message and exit. + --version Show the version information. + --username Mergin username (or MERGIN_USERNAME env. variable) + --password Mergin password (or MERGIN_PASSWORD env. variable) + --url Mergin url (defaults to app.merginmaps.com) + +Commands: + create Create a new project on Mergin server + download Download last version of mergin project + sync Pull&Push the changes + remove Remove project from server. +``` diff --git a/src/dev/integration/index.md b/src/dev/integration/index.md index ac3af4a7..3f095bf0 100644 --- a/src/dev/integration/index.md +++ b/src/dev/integration/index.md @@ -1,13 +1,14 @@ -# Integrate Mergin Maps +--- +outline: deep +--- + +# Python API Client [[toc]] Do you want to integrate ? is an open platform that aims to be developer friendly and it has been designed to allow easy integration with other software. - -## Python client module -The Python client module is the easiest way to programmatically use . You can use Python API or a command-line tool to easily work with projects, such as to get project status, push and pull changes, or to download, create and delete projects. - -The repository contains the source code of the Python client module and more information on how to use it. +## Installation +The Python client module is the easiest way to programmatically use . 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. Python client is available in the PyPI repository and can be installed with `pip`: @@ -15,59 +16,195 @@ Python client is available in the PyPI repository and can be installed with `pip pip3 install mergin-client ``` -### Python module +## 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 projects, push/pull changes, create or delete projects and more. + +For example, to download a project to a local folder: +``` +mergin download john/project1 ~/mergin/project1 +``` +For more details, visit . + +## Python module To use from Python, just create `MerginClient` object and then use it. Here, for instance, to download a project: ```python import mergin -client = mergin.MerginClient(login='john', password='topsecret') +client = mergin.MerginClient(login='john', password='T0p_secret') client.download_project('lutraconsulting/Basic survey', '/tmp/basic-survey') ``` If you have installed and you want to use it from the QGIS' Python console ```python import Mergin.mergin as mergin -client = mergin.MerginClient(login='john', password='topsecret') +client = mergin.MerginClient(login='john', password='T0p_secret') ``` -### 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 projects, push/pull changes, create or delete projects and more. +## API reference - users -For example, to download a project to a local folder: +You can create new users and manage their roles using the following methods. + +::: warning API availability +The following methods are available for Python API Client versions `0.10.0` or higher, using server versions `2025.2.0` or higher. +::: + +### Create a user + +```python +client.create_user(, , , , [username], [notify_user]) ``` -mergin download john/project1 ~/mergin/project1 + +The caller must be a workspace admin, owner or server administrator. + +Arguments: + +`email` (string): Must be a unique email. + +`password` (string): Must meet security requirements. + +`workspace_id` (int) :information_source: : The workspace ID where the user will be added. + +`workspace_role` (string) :information_source: : The user’s role in the workspace. [See the roles options](../../manage/permissions/index.md#workspace-member-roles-overview). + +`username` (string, optional): If not provided, it will be automatically generated from the email address. + +`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`. + +Example: +```python +client.create_user("jill@example.com", "T0p_secret", 1, "editor", notify_user=True) ``` -For more details, visit . -## C++ standalone client -C++ Client has advantage over Python that it is completely without any dependencies. +> :information_source: `workspace_id` and `workspace_role` arguments are ignored on Community edition servers. + +--- + +### Workspace members methods + +These methods are available for Cloud and Enterprise edition servers. + +::: warning API availability +The following methods are available for Python API Client versions `0.10.0` or higher, using server versions `2025.2.0` or higher. +::: -To install the C++ client, just download the binary for your platform from and use it from the command line. +The caller of the following methods must be a workspace admin, owner or server administrator. -Go to repository for more information on how to use it. +#### List members -### C++ Command line tool -When the client is installed, it comes with `mergin` command line tool. +```python +client.list_workspace_members() +``` +Arguments: -```bash -$ mergin --help -Usage: mergin [OPTIONS] COMMAND [ARGS]... +`workspace_id` (int): ID of the workspace. -Options: - --help Show this message and exit. - --version Show the version information. - --username Mergin username (or MERGIN_USERNAME env. variable) - --password Mergin password (or MERGIN_PASSWORD env. variable) - --url Mergin url (defaults to app.merginmaps.com) +#### Get member detail -Commands: - create Create a new project on Mergin server - download Download last version of mergin project - sync Pull&Push the changes - remove Remove project from server. +```python +client.get_workspace_member(, ) ``` +Arguments: + +`workspace_id` (int): ID of the workspace. + +`user_id` (int): ID of the user. + +#### Update member role + +```python +client.update_workspace_member(, , , [reset_projects_roles]) +``` +Arguments: + +`workspace_id` (int): ID of the workspace. + +`user_id` (int): ID of the user. + +`workspace_role` (string): New role. [See the roles options](../../manage/permissions/index.md#workspace-member-roles-overview). + +`reset_projects_roles` (Boolean, optional): If true, overridden project roles (explicitly shared projects access) will be reset. Default is `False`. + +#### Remove member + +```python +client.remove_workspace_member(, ) +``` +Arguments: + +`workspace_id` (int): ID of the workspace. + +`user_id` (int): ID of the user. + +> The user account is not removed. This method only removes their access to the workspace. + +--- + +### Project collaborators methods + +These methods are available for all server types. + +::: warning API availability +The following methods are available for Python API Client versions `0.10.0` or higher, using server versions `2025.2.0` or higher. +::: + +The caller of the following methods must be a workspace admin, owner, project owner or server administrator. + +The following methods accept project ids (of type `uuid`). You can find project id via and methods. + +#### List project collaborators + +```python +client.list_project_collaborators() +``` +Arguments: + +`project_id` (string): ID of the project. + +#### Add project collaborator + +Adds a user as project collaborator. This method is good for sharing projects with guests or upgrading roles of members for specific projects. +On Cloud, the user must be a in the workspace where the project belongs. + +```python +client.add_project_collaborator(, , ) +``` +Arguments: + +`project_id` (string): ID of the project. + +`user` (string): Email or username of the user to be added to the project. + +`project_role`: (string): Role of the user in the project. [See the roles options](../../manage/permissions/index.md#project-permissions-overview) + +#### Update project collaborator role + +```python +client.update_project_collaborator(, , ) +``` +Arguments: + +`project_id` (string): ID of the project. + +`user_id` (int): ID of the user. + +`project_role`: (string): New role. [See the roles options](../../manage/permissions/index.md#project-permissions-overview) + +> 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. + +#### Remove project collaborator + +```python +client.remove_project_collaborator(, ) +``` +Arguments: + +`project_id` (string): ID of the project. + +`user_id` (int): ID of the user. + +> The user account is not removed, only the project access. -### C++ Mergin Maps API core library +## Further details -Client is based on the Qt-based used by the to sync the projects in the mobile application. +The repository contains the source code and more information on how to use it. diff --git a/src/index.md b/src/index.md index e20aa554..d932867a 100644 --- a/src/index.md +++ b/src/index.md @@ -96,7 +96,8 @@ The ecosystem consist of various components: ## For Developers - [Custom Mobile App](./dev/customapp/) -- [Integrate Mergin Maps](./dev/integration/) +- [Python Client Module Integration](./dev/integration/) +- [C++ Standalone Client Integration](./dev/integration-cpp/) - [PostgreSQL DB Sync](./dev/dbsync/) - [Media Sync](./dev/media-sync/) - [Work Packages](./dev/work-packages/) @@ -108,11 +109,11 @@ The ecosystem consist of various components: - [Security](./server/security/) - [Upgrade](./server/upgrade/) - [Administer](./server/administer/) -- [Troubleshoot Custom Servers](./server/troubleshoot/) - [Administration Panel](./server/dashboard/) +- [Troubleshoot Custom Servers](./server/troubleshoot/) - [Using Mergin Maps Mobile App and QGIS Plugin with a Custom Server](./server/plugin-mobile-app/) -## Migrate +## Migrate to Mergin Maps - [From QField](./migrate/qfield/) - [From ArcGIS](./migrate/arcgis/) - [From Fulcrum](./migrate/fulcrumapp/) diff --git a/src/migrate/arcgis/index.md b/src/migrate/arcgis/index.md index e91a0de8..794b9a51 100644 --- a/src/migrate/arcgis/index.md +++ b/src/migrate/arcgis/index.md @@ -27,9 +27,10 @@ Here is a comparison of the main components of both ecosystems: | ArcGIS QuickCapture | | field survey application | | ArcGIS Survey123 | | form-based field survey application | | ArcGIS Field Maps** | | field survey application | -| ArcGIS Maps SDK | [Python client](../../dev/integration/#python-client-module) and QGIS API| developer SDK | +| ArcGIS Maps SDK | [Python client](../../dev/integration/) and QGIS API| developer SDK | *ArcGIS Pro replaced [ArcMap](https://en.wikipedia.org/wiki/ArcMap) + **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/) ## Migrate from ArcGIS to QGIS