diff --git a/docs/docs/examples.md b/docs/docs/examples.md new file mode 100644 index 0000000..2561990 --- /dev/null +++ b/docs/docs/examples.md @@ -0,0 +1,265 @@ +# Real Use Case: Automating QFieldCloud Project Management + +## CLI Example Usage + +Here it is typical user story, for **Bash** (Linux/macOS) and **PowerShell** (Windows): + +### **Install QFieldCloud SDK** + +To interact with the QFieldCloud API, start by installing the official QFieldCloud SDK. The installation command is the same for both Bash and PowerShell: + +```shell +pip install qfieldcloud-sdk +``` + +Once installed, you're ready to manage your projects directly from the command line. +> Note: All values are enclosed in quotes, with single quotes (`'`) recommended for Bash (_but not mandatory_) and double quotes (`"`) for PowerShell. + +### **Log in to QFieldCloud and Create a New Project** + +First, log in to your QFieldCloud account. + +=== ":material-linux: Linux" + + ```bash + qfieldcloud-cli login 'ninjamaster' 'secret_password123' + ``` + +=== ":material-microsoft-windows: Windows" + + ```powershell + qfieldcloud-cli login "ninjamaster" "secret_password123" + ``` + +After signing in, the QFieldCloud CLI will output the value of the authentication token. +The authentication token will be sent to QFieldCloud API to authorize you instead of sending the username and password. +You can explicitly pass the authentication token via passing `--token` CLI argument for every command. + +The easier approach is to set an environment variable with your token: + +=== ":material-linux: Linux" + + ```bash + export QFIELDCLOUD_TOKEN='123abcXYZ987exampleToken' + ``` + +=== ":material-microsoft-windows: Windows" + + ```powershell + $env:QFIELDCLOUD_TOKEN = "123abcXYZ987exampleToken" + ``` + +#### Create a project + +Create a project called `Tree_Survey` within your organization: + +=== ":material-linux: Linux" + + ```bash + qfieldcloud-cli create-project --owner 'My_Organization_Clan' --description 'Daily work project' --is-private 'Tree_Survey' + ``` + +=== ":material-microsoft-windows: Windows" + + ```powershell + qfieldcloud-cli create-project --owner "My_Organization_Clan" --description "Daily work project" --is-private "Tree_Survey" + ``` + +The project is now created in your QFieldCloud organization, and its project ID (e.g., `123e4567-e89b-12d3-a456-426614174000`) is returned. +You’re now ready for file uploads. + +### **Upload Local Files to QFieldCloud** + +Prepare your local project files and upload them to QFieldCloud: + +=== ":material-linux: Linux" + + ```bash + qfieldcloud-cli upload-files '123e4567-e89b-12d3-a456-426614174000' '/home/ninjamaster/QField/cloud/Tree_survey' + ``` + +=== ":material-microsoft-windows: Windows" + + ```powershell + qfieldcloud-cli upload-files "123e4567-e89b-12d3-a456-426614174000" "C:\Users\ninjamaster\QField\cloud\Tree_survey" + ``` + +You can also upload specific files by using the `--filter` option. For instance, to upload only `.gpkg` files: + +=== ":material-linux: Linux" + + ```bash + qfieldcloud-cli upload-files '123e4567-e89b-12d3-a456-426614174000' '/home/ninjamaster/QField/cloud/Tree_survey' --filter '*.gpkg' + ``` + +=== ":material-microsoft-windows: Windows" + + ```powershell + qfieldcloud-cli upload-files "123e4567-e89b-12d3-a456-426614174000" "C:\Users\ninjamaster\QField\cloud\Tree_survey" --filter "*.gpkg" + ``` + +### **Schedule and Trigger a Package Job** + +Suppose your company packages the project every morning at 8:47 AM.: + +=== ":material-linux: Linux" + + ```bash + 47 8 * * * qfieldcloud-cli job-trigger '123e4567-e89b-12d3-a456-426614174000' package + ``` + + This triggers the package job daily at the specified time. For more information about [cronjob](https://crontab.guru/) + +=== ":material-microsoft-windows: Windows" + + ```powershell + schtasks /create /tn "QFieldCloud Job Trigger" /tr "qfieldcloud-cli job-trigger '123e4567-e89b-12d3-a456-426614174000' package" /sc daily /st 08:47 + ``` + + This triggers the package job daily at the specified time. For more information about [schtasks](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/schtasks) + +To manually trigger a package job at any time and force if require: + +=== ":material-linux: Linux" + + ```bash + qfieldcloud-cli job-trigger '123e4567-e89b-12d3-a456-426614174000' package --force + ``` + +=== ":material-microsoft-windows: Windows" + + ```powershell + qfieldcloud-cli job-trigger "123e4567-e89b-12d3-a456-426614174000" package --force + ``` + +### **Monitor Job Status** + +After triggering a job, monitor its status to ensure successful completion: + +=== ":material-linux: Linux" + + ```bash + qfieldcloud-cli list-jobs '123e4567-e89b-12d3-a456-426614174000' --type package + qfieldcloud-cli job-status '321e4567-e89b-12d3-a456-426614174987' + ``` + +=== ":material-microsoft-windows: Windows" + + ```powershell + qfieldcloud-cli list-jobs "123e4567-e89b-12d3-a456-426614174000" --type package + qfieldcloud-cli job-status "321e4567-e89b-12d3-a456-426614174987" + ``` + +### **Download Files for Backup** + +Once the package job is complete, download the project files for backup. To download all files or filter specific ones (e.g., `.jpg` files): + +=== ":material-linux: Linux" + + ```bash + qfieldcloud-cli package-download '123e4567-e89b-12d3-a456-426614174000' '/home/ninjamaster/backup_folder/DCIM/2024-11-10/' --filter '*.jpg' + ``` + +=== ":material-microsoft-windows: Windows" + + ```powershell + qfieldcloud-cli package-download "123e4567-e89b-12d3-a456-426614174000" "C:\Users\ninjamaster\backup_folder\DCIM\2024-11-10\" --filter "*.jpg" + ``` + +If files already exist locally and you want to overwrite them, use the `--force-download` option: + +=== ":material-linux: Linux" + + ```bash + qfieldcloud-cli package-download '123e4567-e89b-12d3-a456-426614174000' '/home/ninjamaster/backup_folder/DCIM/2024-11-10/' --force-download + ``` + +=== ":material-microsoft-windows: Windows" + + ```powershell + qfieldcloud-cli package-download "123e4567-e89b-12d3-a456-426614174000" "C:\Users\ninjamaster\backup_folder\DCIM\2024-11-10\" --force-download + ``` + +### **Delete Files to Save Space** + +To free up storage on QFieldCloud, you can delete unnecessary files, such as `.jpg` files: + +=== ":material-linux: Linux" + + ```bash + qfieldcloud-cli delete-files '123e4567-e89b-12d3-a456-426614174000' --filter '*.jpg' + ``` + +=== ":material-microsoft-windows: Windows" + + ```powershell + qfieldcloud-cli delete-files "123e4567-e89b-12d3-a456-426614174000" --filter "*.jpg" + ``` + +You can also delete specific files by specifying their exact path: + +=== ":material-linux: Linux" + + ```bash + qfieldcloud-cli delete-files '123e4567-e89b-12d3-a456-426614174000' 'DCIM/tree-202411202334943.jpg' + ``` + +=== ":material-microsoft-windows: Windows" + + ```powershell + qfieldcloud-cli delete-files "123e4567-e89b-12d3-a456-426614174000" "DCIM\tree-202411202334943.jpg" + ``` + +### **Other Useful QFieldCloud CLI Commands** + +#### **List Your Projects** + +To list all projects associated with your account: + +```shell +qfieldcloud-cli list-projects +``` + +To include public projects in the list: + +```shell +qfieldcloud-cli list-projects --include-public +``` + +#### **List Files in a Project** + +To view all files in a specific project: + +```shell +qfieldcloud-cli list-files "123e4567-e89b-12d3-a456-426614174000" +``` + +#### **Delete a Project** + +To permanently delete a project (be cautious—this action cannot be undone): + +```shell +qfieldcloud-cli delete-project "123e4567-e89b-12d3-a456-426614174000" +``` + +#### **Manage Collaborators** + +You can add, remove, or change the roles of collaborators on your project. + +- **Add a Collaborator:** + +```shell +qfieldcloud-cli collaborators-add "123e4567-e89b-12d3-a456-426614174000" "ninja007" admin +``` + +- **Remove a Collaborator:** + +```shell +qfieldcloud-cli collaborators-remove "123e4567-e89b-12d3-a456-426614174000" "ninja007" +``` + +- **Change a Collaborator’s Role:** + +```shell +qfieldcloud-cli collaborators-patch "123e4567-e89b-12d3-a456-426614174000" "ninja001" editor +``` diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 21a0f82..dcaa082 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -10,7 +10,14 @@ markdown_extensions: - admonition - codehilite - mkdocs-click + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg nav: - QFieldCloud SDK: index.md - CLI: cli.md + - Examples: examples.md