From e80f62af5a5fbb2450d0b4bb8a57f1224a881edb Mon Sep 17 00:00:00 2001 From: Johnny Sequeira Date: Fri, 11 Oct 2024 17:30:17 -0600 Subject: [PATCH 01/10] 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 02/10] 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 03/10] 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 04/10] 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 05/10] 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 06/10] 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 07/10] 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 713001c49fd7d67b9a77c56323cf859db5b802d5 Mon Sep 17 00:00:00 2001 From: Johnny Sequeira Date: Thu, 17 Oct 2024 17:15:15 -0600 Subject: [PATCH 08/10] Adding dependency and config for Icons and content tabs --- 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 From eeaff6e3e2279692aace91490ab3fb2915eabf8f Mon Sep 17 00:00:00 2001 From: Johnny Sequeira Date: Thu, 24 Oct 2024 15:08:20 -0600 Subject: [PATCH 09/10] Improving the documentation and adding advance commands examples --- docs/docs/examples.md | 336 ++++++++++++++++++++++++++++++++---------- 1 file changed, 259 insertions(+), 77 deletions(-) diff --git a/docs/docs/examples.md b/docs/docs/examples.md index 2561990..21eae89 100644 --- a/docs/docs/examples.md +++ b/docs/docs/examples.md @@ -19,13 +19,13 @@ Once installed, you're ready to manage your projects directly from the command l First, log in to your QFieldCloud account. -=== ":material-linux: Linux" +=== ":material-bash: Bash" ```bash qfieldcloud-cli login 'ninjamaster' 'secret_password123' ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell qfieldcloud-cli login "ninjamaster" "secret_password123" @@ -37,29 +37,59 @@ You can explicitly pass the authentication token via passing `--token` CLI argum The easier approach is to set an environment variable with your token: -=== ":material-linux: Linux" +=== ":material-bash: Bash" ```bash export QFIELDCLOUD_TOKEN='123abcXYZ987exampleToken' ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell $env:QFIELDCLOUD_TOKEN = "123abcXYZ987exampleToken" ``` -#### Create a project +You may want to extract the session token directly from the JSON output of the `qfieldcloud-cli` login command. This is especially useful if you're automating tasks or chaining multiple commands. + +In this example, we'll use the `jq` tool to parse the JSON response and retrieve the session token. + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli --json login 'ninjamaster' 'secret_password123' | jq .session_token + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli --json login "ninjamaster" "secret_password123" | jq ".session_token" + ``` + +This command will output only the session token, which can be stored in an environment variable for future use: + +=== ":material-bash: Bash" + + ```bash + export QFIELDCLOUD_TOKEN=$(qfieldcloud-cli --json login 'ninjamaster' 'secret_password123' | jq -r .session_token) + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + $env:QFIELDCLOUD_TOKEN = (qfieldcloud-cli --json login "ninjamaster" "secret_password123" | jq ".session_token") + ``` + +### **Create a project** Create a project called `Tree_Survey` within your organization: -=== ":material-linux: Linux" +=== ":material-bash: Bash" ```bash qfieldcloud-cli create-project --owner 'My_Organization_Clan' --description 'Daily work project' --is-private 'Tree_Survey' ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell qfieldcloud-cli create-project --owner "My_Organization_Clan" --description "Daily work project" --is-private "Tree_Survey" @@ -68,17 +98,49 @@ Create a project called `Tree_Survey` within your organization: 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. +If you forgot to copy your project ID, you can always check the list of all the projects on QFieldCloud. + +#### **List Your Projects** + +To list all projects associated with your account: + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli list-projects + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli list-projects + ``` + +To include public projects in the list: + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli list-projects --include-public + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli list-projects --include-public + ``` + ### **Upload Local Files to QFieldCloud** Prepare your local project files and upload them to QFieldCloud: -=== ":material-linux: Linux" +=== ":material-bash: Bash" ```bash qfieldcloud-cli upload-files '123e4567-e89b-12d3-a456-426614174000' '/home/ninjamaster/QField/cloud/Tree_survey' ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell qfieldcloud-cli upload-files "123e4567-e89b-12d3-a456-426614174000" "C:\Users\ninjamaster\QField\cloud\Tree_survey" @@ -86,47 +148,157 @@ Prepare your local project files and upload them to QFieldCloud: You can also upload specific files by using the `--filter` option. For instance, to upload only `.gpkg` files: -=== ":material-linux: Linux" +=== ":material-bash: Bash" ```bash qfieldcloud-cli upload-files '123e4567-e89b-12d3-a456-426614174000' '/home/ninjamaster/QField/cloud/Tree_survey' --filter '*.gpkg' ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell qfieldcloud-cli upload-files "123e4567-e89b-12d3-a456-426614174000" "C:\Users\ninjamaster\QField\cloud\Tree_survey" --filter "*.gpkg" ``` +Now you can see your files on QFieldCloud... + +#### **List Files in a Project** + +To view all files in a specific project: + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli list-files '123e4567-e89b-12d3-a456-426614174000' + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli list-files "123e4567-e89b-12d3-a456-426614174000" + ``` + +### **Manage Members and Collaborators** + +QFieldCloud is a collaborative platform, so you can manage your fieldworks.... + +You can add, remove, or change the roles of members on your Organization. + +- **Add a Member to an Organization:** + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli members-add 'My_Organization_Clan' 'ninja007' admin + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli members-add "My_Organization_Clan" "ninja007" admin + ``` + +- **Change a Member's Role:** + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli members-patch 'My_Organization_Clan' 'ninja007' member + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli members-patch "My_Organization_Clan" "ninja007" member + ``` + +- **Remove a Member in an Organization:** + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli members-remove 'My_Organization_Clan' 'ninja007' + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli members-remove "My_Organization_Clan" "ninja007" + ``` + +You can add, remove, or change the roles of collaborators on your project. + +- **Add a Collaborator in a project:** + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli collaborators-add '123e4567-e89b-12d3-a456-426614174000' 'ninja007' admin + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli collaborators-add "123e4567-e89b-12d3-a456-426614174000" "ninja007" admin + ``` + +- **Change a Collaborator’s Role in a project:** + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli collaborators-patch '123e4567-e89b-12d3-a456-426614174000' 'ninja001' editor + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli collaborators-patch "123e4567-e89b-12d3-a456-426614174000" "ninja001" editor + ``` + +- **Remove a Collaboratorin a project:** + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli collaborators-remove '123e4567-e89b-12d3-a456-426614174000' 'ninja007' + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli collaborators-remove "123e4567-e89b-12d3-a456-426614174000" "ninja007" + ``` + ### **Schedule and Trigger a Package Job** Suppose your company packages the project every morning at 8:47 AM.: -=== ":material-linux: Linux" +=== ":material-bash: Bash" ```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/) + This triggers the package job daily at the specified time. For more information about [cronjob](https://crontab.guru/). -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```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) + 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" +=== ":material-bash: Bash" ```bash qfieldcloud-cli job-trigger '123e4567-e89b-12d3-a456-426614174000' package --force ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell qfieldcloud-cli job-trigger "123e4567-e89b-12d3-a456-426614174000" package --force @@ -136,31 +308,77 @@ To manually trigger a package job at any time and force if require: After triggering a job, monitor its status to ensure successful completion: -=== ":material-linux: Linux" +- **List all jobs for a specific project**: + +Before checking the status of a job, you can list all jobs associated with a project by using the `list-jobs` command. + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli list-jobs '123e4567-e89b-12d3-a456-426614174000' --type package + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli list-jobs "123e4567-e89b-12d3-a456-426614174000" --type package + ``` + +- **Check the status of a specific job**: + +Once you have the job ID, you can check its status using the `job-status` command: + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli job-status '321e4567-e89b-12d3-a456-426614174987' + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli job-status "321e4567-e89b-12d3-a456-426614174987" + ``` + +- **Continuously check job status until completion**: + +To automate the process of checking a job's status until it is finished, you can use a loop that will keep checking the status until the job either succeeds or fails. + +=== ":material-bash: Bash" ```bash - qfieldcloud-cli list-jobs '123e4567-e89b-12d3-a456-426614174000' --type package - qfieldcloud-cli job-status '321e4567-e89b-12d3-a456-426614174987' + JOB_STATUS=$(qfieldcloud-cli --json job-status '321e4567-e89b-12d3-a456-426614174987' | jq '.output' -r) + while [[ "$JOB_STATUS" != "success" && "$JOB_STATUS" != "failed" ]]; do + echo "Job is still running... Status: $JOB_STATUS" + sleep 10 # Wait for 10 seconds before checking again + JOB_STATUS=$(qfieldcloud-cli --json job-status '321e4567-e89b-12d3-a456-426614174987' | jq '.output' -r) + done + echo "Job finished with status: $JOB_STATUS" ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell - qfieldcloud-cli list-jobs "123e4567-e89b-12d3-a456-426614174000" --type package - qfieldcloud-cli job-status "321e4567-e89b-12d3-a456-426614174987" + $JOB_STATUS = (qfieldcloud-cli --json job-status "321e4567-e89b-12d3-a456-426614174987" | jq ".output" -r) + while ($JOB_STATUS -ne "success" -and $JOB_STATUS -ne "failed") { + Write-Host "Job is still running... Status: $JOB_STATUS" + Start-Sleep -Seconds 10 # Wait for 10 seconds before checking again + $JOB_STATUS = (qfieldcloud-cli --json job-status "321e4567-e89b-12d3-a456-426614174987" | jq ".output" -r) + } + Write-Host "Job finished with status: $JOB_STATUS" ``` ### **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" +=== ":material-bash: Bash" ```bash qfieldcloud-cli package-download '123e4567-e89b-12d3-a456-426614174000' '/home/ninjamaster/backup_folder/DCIM/2024-11-10/' --filter '*.jpg' ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell qfieldcloud-cli package-download "123e4567-e89b-12d3-a456-426614174000" "C:\Users\ninjamaster\backup_folder\DCIM\2024-11-10\" --filter "*.jpg" @@ -168,13 +386,13 @@ Once the package job is complete, download the project files for backup. To down If files already exist locally and you want to overwrite them, use the `--force-download` option: -=== ":material-linux: Linux" +=== ":material-bash: Bash" ```bash qfieldcloud-cli package-download '123e4567-e89b-12d3-a456-426614174000' '/home/ninjamaster/backup_folder/DCIM/2024-11-10/' --force-download ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell qfieldcloud-cli package-download "123e4567-e89b-12d3-a456-426614174000" "C:\Users\ninjamaster\backup_folder\DCIM\2024-11-10\" --force-download @@ -184,13 +402,13 @@ If files already exist locally and you want to overwrite them, use the `--force- To free up storage on QFieldCloud, you can delete unnecessary files, such as `.jpg` files: -=== ":material-linux: Linux" +=== ":material-bash: Bash" ```bash qfieldcloud-cli delete-files '123e4567-e89b-12d3-a456-426614174000' --filter '*.jpg' ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell qfieldcloud-cli delete-files "123e4567-e89b-12d3-a456-426614174000" --filter "*.jpg" @@ -198,68 +416,32 @@ To free up storage on QFieldCloud, you can delete unnecessary files, such as `.j You can also delete specific files by specifying their exact path: -=== ":material-linux: Linux" +=== ":material-bash: Bash" ```bash qfieldcloud-cli delete-files '123e4567-e89b-12d3-a456-426614174000' 'DCIM/tree-202411202334943.jpg' ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell qfieldcloud-cli delete-files "123e4567-e89b-12d3-a456-426614174000" "DCIM\tree-202411202334943.jpg" ``` -### **Other Useful QFieldCloud CLI Commands** +### **Delete a Project** -#### **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** +Once you are done with a project, you can delete it... 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:** +=== ":material-bash: Bash" -```shell -qfieldcloud-cli collaborators-remove "123e4567-e89b-12d3-a456-426614174000" "ninja007" -``` + ```bash + qfieldcloud-cli delete-project '123e4567-e89b-12d3-a456-426614174000' + ``` -- **Change a Collaborator’s Role:** +=== ":material-powershell: PowerShell" -```shell -qfieldcloud-cli collaborators-patch "123e4567-e89b-12d3-a456-426614174000" "ninja001" editor -``` + ```powershell + qfieldcloud-cli delete-project "123e4567-e89b-12d3-a456-426614174000" + ``` From a1c1bd3998d286bc1a8bafbb0675dac0c478e43c Mon Sep 17 00:00:00 2001 From: Johnny Sequeira Date: Thu, 24 Oct 2024 15:11:58 -0600 Subject: [PATCH 10/10] Fixing indentation --- docs/docs/examples.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/docs/examples.md b/docs/docs/examples.md index 21eae89..ad98363 100644 --- a/docs/docs/examples.md +++ b/docs/docs/examples.md @@ -314,9 +314,9 @@ Before checking the status of a job, you can list all jobs associated with a pro === ":material-bash: Bash" - ```bash - qfieldcloud-cli list-jobs '123e4567-e89b-12d3-a456-426614174000' --type package - ``` + ```bash + qfieldcloud-cli list-jobs '123e4567-e89b-12d3-a456-426614174000' --type package + ``` === ":material-powershell: PowerShell" @@ -330,15 +330,15 @@ Once you have the job ID, you can check its status using the `job-status` comman === ":material-bash: Bash" - ```bash - qfieldcloud-cli job-status '321e4567-e89b-12d3-a456-426614174987' - ``` + ```bash + qfieldcloud-cli job-status '321e4567-e89b-12d3-a456-426614174987' + ``` === ":material-powershell: PowerShell" - ```powershell - qfieldcloud-cli job-status "321e4567-e89b-12d3-a456-426614174987" - ``` + ```powershell + qfieldcloud-cli job-status "321e4567-e89b-12d3-a456-426614174987" + ``` - **Continuously check job status until completion**: