From e80f62af5a5fbb2450d0b4bb8a57f1224a881edb Mon Sep 17 00:00:00 2001 From: Johnny Sequeira Date: Fri, 11 Oct 2024 17:30:17 -0600 Subject: [PATCH 1/8] Real Use Case for Automating QFieldCloud Project Management --- docs/docs/examples.md | 168 ++++++++++++++++++++++++++++++++++++++++++ docs/mkdocs.yml | 1 + 2 files changed, 169 insertions(+) create mode 100644 docs/docs/examples.md diff --git a/docs/docs/examples.md b/docs/docs/examples.md new file mode 100644 index 0000000..7958d54 --- /dev/null +++ b/docs/docs/examples.md @@ -0,0 +1,168 @@ +# Real Use Case: Automating QFieldCloud Project Management + +## CLI Example Usage + +### **1. Install QFieldCloud SDK** + +To interact with the QFieldCloud API, start by installing the official QFieldCloud SDK. Ensure you have Python 3.6 or higher installed, then run the following command: + +```bash +pip install qfieldcloud-sdk +``` + +Once installed, you're ready to manage your projects directly from the command line. + +### **2. Log in to QFieldCloud and Create a New Project** + +First, log in to your QFieldCloud account (ensure variables are enclosed in double quotes): + +```bash +qfieldcloud-cli login "ninjamaster" "secret_password123" +``` + +After logging in, export the `QFIELD_CLOUD_TOKEN`: + +```bash +export QFIELDCLOUD_TOKEN="123abcXYZ987exampleToken" +``` + +Next, create a project called "Tree_Survey" within your organization: + +```bash +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. + +### **3. Upload Local Files to QFieldCloud** + +Prepare your local project files and upload them to QFieldCloud. For example, if your files are located in `/home/ninjamaster/QField/cloud/Tree_survey`: + +```bash +qfieldcloud-cli upload-files "123e4567-e89b-12d3-a456-426614174000" "/home/ninjamaster/QField/cloud/Tree_survey" +``` + +You can also upload specific files by using the `--filter` option. For instance, to upload only `.gpkg` files: + +```bash +qfieldcloud-cli upload-files "123e4567-e89b-12d3-a456-426614174000" "/home/ninjamaster/QField/cloud/Tree_survey" --filter "*.gpkg" +``` + +### **4. Schedule and Trigger a Package Job** + +Suppose your company packages the project every morning at 8:47 AM. You can automate this process using a cron job: + +```bash +47 8 * * * qfieldcloud-cli job-trigger "123e4567-e89b-12d3-a456-426614174000" package +``` + +This command triggers the package job daily at the specified time. Here's what the cron job format means: + +- `47`: Minute (47th minute). +- `8`: Hour (8 AM). +- `*`: Every day of the month. +- `*`: Every month. +- `*`: Every day of the week. + +To manually trigger a package job at any time: + +```bash +qfieldcloud-cli job-trigger "123e4567-e89b-12d3-a456-426614174000" package +``` + +You can force the job to re-run even if one is already queued: + +```bash +qfieldcloud-cli job-trigger "123e4567-e89b-12d3-a456-426614174000" package --force +``` + +### **5. Monitor Job Status** + +After triggering a job, monitor its status to ensure successful completion: + +```bash +qfieldcloud-cli list-jobs "123e4567-e89b-12d3-a456-426614174000" --type package +qfieldcloud-cli job-status "321e4567-e89b-12d3-a456-426614174987" +``` + +### **6. 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): + +```bash +qfieldcloud-cli package-download "123e4567-e89b-12d3-a456-426614174000" "/home/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: + +```bash +qfieldcloud-cli package-download "123e4567-e89b-12d3-a456-426614174000" "/home/ninjamaster/backup_folder/DCIM/2024-11-10/" --force-download +``` + +### **7. Delete Files to Save Space** + +To free up storage on QFieldCloud, you can delete unnecessary files, such as `.jpg` files: + +```bash +qfieldcloud-cli delete-files "123e4567-e89b-12d3-a456-426614174000" --filter "*.jpg" +``` + +You can also delete specific files by specifying their exact path: + +```bash +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: + +```bash +qfieldcloud-cli list-projects +``` + +To include public projects in the list: + +```bash +qfieldcloud-cli list-projects --include-public +``` + +#### **List Files in a Project** + +To view all files in a specific project: + +```bash +qfieldcloud-cli list-files "123e4567-e89b-12d3-a456-426614174000" +``` + +#### **Delete a Project** + +To permanently delete a project (be cautious—this action cannot be undone): + +```bash +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:** + +```bash +qfieldcloud-cli collaborators-add "123e4567-e89b-12d3-a456-426614174000" "ninja007" admin +``` + +- **Remove a Collaborator:** + +```bash +qfieldcloud-cli collaborators-remove "123e4567-e89b-12d3-a456-426614174000" "ninja007" +``` + +- **Change a Collaborator’s Role:** + +```bash +qfieldcloud-cli collaborators-patch "123e4567-e89b-12d3-a456-426614174000" "ninja001" editor +``` diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 21a0f82..08dad8d 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -14,3 +14,4 @@ markdown_extensions: nav: - QFieldCloud SDK: index.md - CLI: cli.md + - Examples: examples.md From 7081d318c51f3ca701dda5040337916f4503b838 Mon Sep 17 00:00:00 2001 From: Johnny <77129293+SeqLaz@users.noreply.github.com> Date: Thu, 17 Oct 2024 12:21:48 -0600 Subject: [PATCH 2/8] Update docs/docs/examples.md Co-authored-by: Ivan Ivanov --- docs/docs/examples.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/examples.md b/docs/docs/examples.md index 7958d54..76f9c0e 100644 --- a/docs/docs/examples.md +++ b/docs/docs/examples.md @@ -4,7 +4,7 @@ ### **1. Install QFieldCloud SDK** -To interact with the QFieldCloud API, start by installing the official QFieldCloud SDK. Ensure you have Python 3.6 or higher installed, then run the following command: +To interact with the QFieldCloud API, start by installing the official QFieldCloud SDK: ```bash pip install qfieldcloud-sdk From bed3530a4a308ec35caac2850df9496012fe8e93 Mon Sep 17 00:00:00 2001 From: Johnny <77129293+SeqLaz@users.noreply.github.com> Date: Thu, 17 Oct 2024 12:22:06 -0600 Subject: [PATCH 3/8] Update docs/docs/examples.md Co-authored-by: Ivan Ivanov --- docs/docs/examples.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/docs/examples.md b/docs/docs/examples.md index 76f9c0e..1bf4377 100644 --- a/docs/docs/examples.md +++ b/docs/docs/examples.md @@ -14,7 +14,8 @@ Once installed, you're ready to manage your projects directly from the command l ### **2. Log in to QFieldCloud and Create a New Project** -First, log in to your QFieldCloud account (ensure variables are enclosed in double quotes): +First, log in to your QFieldCloud account. +Note that all values are enclosed in single or double quote characters, depending on your operating system's shell. ```bash qfieldcloud-cli login "ninjamaster" "secret_password123" From 4e101488d680988f3d8a67a53c02542ed1cf454b Mon Sep 17 00:00:00 2001 From: Johnny <77129293+SeqLaz@users.noreply.github.com> Date: Thu, 17 Oct 2024 12:22:41 -0600 Subject: [PATCH 4/8] Update docs/docs/examples.md Co-authored-by: Ivan Ivanov --- docs/docs/examples.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/docs/examples.md b/docs/docs/examples.md index 1bf4377..91066d5 100644 --- a/docs/docs/examples.md +++ b/docs/docs/examples.md @@ -21,7 +21,10 @@ Note that all values are enclosed in single or double quote characters, dependin qfieldcloud-cli login "ninjamaster" "secret_password123" ``` -After logging in, export the `QFIELD_CLOUD_TOKEN`: +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: ```bash export QFIELDCLOUD_TOKEN="123abcXYZ987exampleToken" From 375b4819d3e23368303262085c4b25d78c3f7f20 Mon Sep 17 00:00:00 2001 From: Johnny <77129293+SeqLaz@users.noreply.github.com> Date: Thu, 17 Oct 2024 12:23:08 -0600 Subject: [PATCH 5/8] Update docs/docs/examples.md Co-authored-by: Ivan Ivanov --- docs/docs/examples.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/docs/examples.md b/docs/docs/examples.md index 91066d5..a2d2797 100644 --- a/docs/docs/examples.md +++ b/docs/docs/examples.md @@ -30,7 +30,9 @@ The easier approach is to set an environment variable with your token: export QFIELDCLOUD_TOKEN="123abcXYZ987exampleToken" ``` -Next, create a project called "Tree_Survey" within your organization: +#### Create a project + +Create a project called "Tree_Survey" within your organization: ```bash qfieldcloud-cli create-project --owner "My_Organization_Clan" --description "Daily work project" --is-private "Tree_Survey" From 79fce4406d6128d4be2f9e9c48b15c3a3bb1024b Mon Sep 17 00:00:00 2001 From: Johnny <77129293+SeqLaz@users.noreply.github.com> Date: Thu, 17 Oct 2024 12:23:45 -0600 Subject: [PATCH 6/8] Update docs/docs/examples.md Co-authored-by: Ivan Ivanov --- docs/docs/examples.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/docs/examples.md b/docs/docs/examples.md index a2d2797..2cec677 100644 --- a/docs/docs/examples.md +++ b/docs/docs/examples.md @@ -38,7 +38,8 @@ Create a project called "Tree_Survey" within your organization: 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. +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. ### **3. Upload Local Files to QFieldCloud** From df6b1771e591d5c04d75bf2be0ba7de64f7daf3a Mon Sep 17 00:00:00 2001 From: Johnny Sequeira Date: Thu, 17 Oct 2024 14:48:17 -0600 Subject: [PATCH 7/8] Improving documentation and adding differentiation for unix and Windows users --- docs/docs/examples.md | 226 +++++++++++++++++++++++++++++------------- 1 file changed, 158 insertions(+), 68 deletions(-) diff --git a/docs/docs/examples.md b/docs/docs/examples.md index 2cec677..2561990 100644 --- a/docs/docs/examples.md +++ b/docs/docs/examples.md @@ -2,123 +2,213 @@ ## CLI Example Usage -### **1. Install QFieldCloud SDK** +Here it is typical user story, for **Bash** (Linux/macOS) and **PowerShell** (Windows): -To interact with the QFieldCloud API, start by installing the official QFieldCloud SDK: +### **Install QFieldCloud SDK** -```bash +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. -### **2. Log in to QFieldCloud and Create a New Project** +### **Log in to QFieldCloud and Create a New Project** First, log in to your QFieldCloud account. -Note that all values are enclosed in single or double quote characters, depending on your operating system's shell. -```bash -qfieldcloud-cli login "ninjamaster" "secret_password123" -``` +=== ":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: -```bash -export QFIELDCLOUD_TOKEN="123abcXYZ987exampleToken" -``` +=== ":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: +Create a project called `Tree_Survey` within your organization: -```bash -qfieldcloud-cli create-project --owner "My_Organization_Clan" --description "Daily work project" --is-private "Tree_Survey" -``` +=== ":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. -### **3. Upload Local Files to QFieldCloud** +### **Upload Local Files to QFieldCloud** -Prepare your local project files and upload them to QFieldCloud. For example, if your files are located in `/home/ninjamaster/QField/cloud/Tree_survey`: +Prepare your local project files and upload them to QFieldCloud: -```bash -qfieldcloud-cli upload-files "123e4567-e89b-12d3-a456-426614174000" "/home/ninjamaster/QField/cloud/Tree_survey" -``` +=== ":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: -```bash -qfieldcloud-cli upload-files "123e4567-e89b-12d3-a456-426614174000" "/home/ninjamaster/QField/cloud/Tree_survey" --filter "*.gpkg" -``` +=== ":material-linux: Linux" -### **4. Schedule and Trigger a Package Job** + ```bash + qfieldcloud-cli upload-files '123e4567-e89b-12d3-a456-426614174000' '/home/ninjamaster/QField/cloud/Tree_survey' --filter '*.gpkg' + ``` -Suppose your company packages the project every morning at 8:47 AM. You can automate this process using a cron job: +=== ":material-microsoft-windows: Windows" -```bash -47 8 * * * qfieldcloud-cli job-trigger "123e4567-e89b-12d3-a456-426614174000" package -``` + ```powershell + qfieldcloud-cli upload-files "123e4567-e89b-12d3-a456-426614174000" "C:\Users\ninjamaster\QField\cloud\Tree_survey" --filter "*.gpkg" + ``` -This command triggers the package job daily at the specified time. Here's what the cron job format means: +### **Schedule and Trigger a Package Job** -- `47`: Minute (47th minute). -- `8`: Hour (8 AM). -- `*`: Every day of the month. -- `*`: Every month. -- `*`: Every day of the week. +Suppose your company packages the project every morning at 8:47 AM.: -To manually trigger a package job at any time: +=== ":material-linux: Linux" -```bash -qfieldcloud-cli job-trigger "123e4567-e89b-12d3-a456-426614174000" package -``` + ```bash + 47 8 * * * qfieldcloud-cli job-trigger '123e4567-e89b-12d3-a456-426614174000' package + ``` -You can force the job to re-run even if one is already queued: + This triggers the package job daily at the specified time. For more information about [cronjob](https://crontab.guru/) -```bash -qfieldcloud-cli job-trigger "123e4567-e89b-12d3-a456-426614174000" package --force -``` +=== ":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: -### **5. Monitor Job Status** +=== ":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: -```bash -qfieldcloud-cli list-jobs "123e4567-e89b-12d3-a456-426614174000" --type package -qfieldcloud-cli job-status "321e4567-e89b-12d3-a456-426614174987" -``` +=== ":material-linux: Linux" + + ```bash + qfieldcloud-cli list-jobs '123e4567-e89b-12d3-a456-426614174000' --type package + qfieldcloud-cli job-status '321e4567-e89b-12d3-a456-426614174987' + ``` -### **6. Download Files for Backup** +=== ":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): -```bash -qfieldcloud-cli package-download "123e4567-e89b-12d3-a456-426614174000" "/home/ninjamaster/backup_folder/DCIM/2024-11-10/" --filter "*.jpg" -``` +=== ":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: -```bash -qfieldcloud-cli package-download "123e4567-e89b-12d3-a456-426614174000" "/home/ninjamaster/backup_folder/DCIM/2024-11-10/" --force-download -``` +=== ":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" -### **7. Delete Files to Save Space** + ```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: -```bash -qfieldcloud-cli delete-files "123e4567-e89b-12d3-a456-426614174000" --filter "*.jpg" -``` +=== ":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: -```bash -qfieldcloud-cli delete-files "123e4567-e89b-12d3-a456-426614174000" DCIM/tree-202411202334943.jpg -``` +=== ":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** @@ -126,13 +216,13 @@ qfieldcloud-cli delete-files "123e4567-e89b-12d3-a456-426614174000" DCIM/tree-20 To list all projects associated with your account: -```bash +```shell qfieldcloud-cli list-projects ``` To include public projects in the list: -```bash +```shell qfieldcloud-cli list-projects --include-public ``` @@ -140,7 +230,7 @@ qfieldcloud-cli list-projects --include-public To view all files in a specific project: -```bash +```shell qfieldcloud-cli list-files "123e4567-e89b-12d3-a456-426614174000" ``` @@ -148,7 +238,7 @@ qfieldcloud-cli list-files "123e4567-e89b-12d3-a456-426614174000" To permanently delete a project (be cautious—this action cannot be undone): -```bash +```shell qfieldcloud-cli delete-project "123e4567-e89b-12d3-a456-426614174000" ``` @@ -158,18 +248,18 @@ You can add, remove, or change the roles of collaborators on your project. - **Add a Collaborator:** -```bash +```shell qfieldcloud-cli collaborators-add "123e4567-e89b-12d3-a456-426614174000" "ninja007" admin ``` - **Remove a Collaborator:** -```bash +```shell qfieldcloud-cli collaborators-remove "123e4567-e89b-12d3-a456-426614174000" "ninja007" ``` - **Change a Collaborator’s Role:** -```bash +```shell qfieldcloud-cli collaborators-patch "123e4567-e89b-12d3-a456-426614174000" "ninja001" editor ``` From 0e3da0f936fbe1c2a353a9a71fec5a7da7aca9f9 Mon Sep 17 00:00:00 2001 From: Johnny Sequeira Date: Thu, 17 Oct 2024 16:19:43 -0600 Subject: [PATCH 8/8] Dependency config for tabbed content --- docs/mkdocs.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 08dad8d..dcaa082 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -10,6 +10,12 @@ 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