diff --git a/source/images/kobotoolbox_monday_integration/app-marketplace.png b/source/images/kobotoolbox_monday_integration/app-marketplace.png new file mode 100644 index 00000000..f35589b2 Binary files /dev/null and b/source/images/kobotoolbox_monday_integration/app-marketplace.png differ diff --git a/source/images/kobotoolbox_monday_integration/create-rest-service.png b/source/images/kobotoolbox_monday_integration/create-rest-service.png new file mode 100644 index 00000000..349abf8e Binary files /dev/null and b/source/images/kobotoolbox_monday_integration/create-rest-service.png differ diff --git a/source/images/kobotoolbox_monday_integration/dynamic-linking.png b/source/images/kobotoolbox_monday_integration/dynamic-linking.png new file mode 100644 index 00000000..d04c522d Binary files /dev/null and b/source/images/kobotoolbox_monday_integration/dynamic-linking.png differ diff --git a/source/images/kobotoolbox_monday_integration/kobo-integration.png b/source/images/kobotoolbox_monday_integration/kobo-integration.png new file mode 100644 index 00000000..364225fc Binary files /dev/null and b/source/images/kobotoolbox_monday_integration/kobo-integration.png differ diff --git a/source/images/kobotoolbox_monday_integration/kobo-monday-data.png b/source/images/kobotoolbox_monday_integration/kobo-monday-data.png new file mode 100644 index 00000000..01911142 Binary files /dev/null and b/source/images/kobotoolbox_monday_integration/kobo-monday-data.png differ diff --git a/source/images/kobotoolbox_monday_integration/monday-board-integrate.png b/source/images/kobotoolbox_monday_integration/monday-board-integrate.png new file mode 100644 index 00000000..c4d419f1 Binary files /dev/null and b/source/images/kobotoolbox_monday_integration/monday-board-integrate.png differ diff --git a/source/images/kobotoolbox_monday_integration/recipe.png b/source/images/kobotoolbox_monday_integration/recipe.png new file mode 100644 index 00000000..8524a9a8 Binary files /dev/null and b/source/images/kobotoolbox_monday_integration/recipe.png differ diff --git a/source/images/kobotoolbox_monday_integration/rest-service-modal.png b/source/images/kobotoolbox_monday_integration/rest-service-modal.png new file mode 100644 index 00000000..feb9edfc Binary files /dev/null and b/source/images/kobotoolbox_monday_integration/rest-service-modal.png differ diff --git a/source/images/kobotoolbox_monday_integration/webhook-url.png b/source/images/kobotoolbox_monday_integration/webhook-url.png new file mode 100644 index 00000000..efbf01c6 Binary files /dev/null and b/source/images/kobotoolbox_monday_integration/webhook-url.png differ diff --git a/source/index.rst b/source/index.rst index 5d4073ae..13ca0a29 100644 --- a/source/index.rst +++ b/source/index.rst @@ -133,6 +133,7 @@ Search the knowledge base, browse our resources and visit our forum for more det api data_storage transcription-translation + kobotoolbox_monday_integration .. toctree:: diff --git a/source/kobotoolbox_monday_integration.md b/source/kobotoolbox_monday_integration.md index f3f0380a..890f8a2c 100644 --- a/source/kobotoolbox_monday_integration.md +++ b/source/kobotoolbox_monday_integration.md @@ -1,87 +1,143 @@ # KoboToolbox Integration on monday.com +**Last updated:** 24 Jun 2023 -The KoboToolbox Integration allows users to easily synchronize their project data from a KoboToolbox project to a monday.com board. -In just a few steps you can set up the integration to automatically copy data submissions received in KoboToolbox to any of your monday.com boards. This integration significantly reduces the manual work involved in copy-pasting project data between the two platforms. +The KoboToolbox Integration allows users to easily synchronize their project +data from a KoboToolbox project to a monday.com board. In just a few steps you +can set up the integration to automatically copy data submissions received in +KoboToolbox to any of your monday.com boards. This integration significantly +reduces the manual work involved in copy-pasting project data between the two +platforms. ## Features -- Simplified process of connecting KoboToolbox projects with monday.com boards -- Easy mapping of monday.com fields to KoboToolbox questions using any label language defined in the form -- Real-time synchronization of newly created submissions to create new items + +- Simplified process of connecting KoboToolbox projects with monday.com boards +- Easy mapping of monday.com fields to KoboToolbox questions using any label + language defined in the form +- Real-time synchronization of newly created submissions to create new items ## Installation & First Use ### Prerequisites -1. Create an account on KoboToolbox if you don't have one yet. Use this [guidance](https://support.kobotoolbox.org/creating_account.html) to set up your free account. -2. Prepare a monday.com board mirroring the structure of your KoboToolbox project so that all fields from your KoboToolbox project are represented on a monday.com board. -3. During the application setup of the integration, there is a need to authenticate access to your account by providing your KoboToolbox API token. To get your API token, use any of the methods described [here](https://support.kobotoolbox.org/api.html?highlight=api%20token). + +1. Create an account on KoboToolbox if you don't have one yet. Use this + [guidance](https://support.kobotoolbox.org/creating_account.html) to set up + your free account. +2. Prepare a monday.com board mirroring the structure of your KoboToolbox + project so that all fields from your KoboToolbox project are represented on + a monday.com board. +3. During the application setup of the integration, there is a need to + authenticate access to your account by providing your KoboToolbox API token. + To get your API token, use any of the methods described + [here](https://support.kobotoolbox.org/api.html?highlight=api%20token). ### Installation -1. Install the KoboToolbox integration from [monday.com apps marketplace](https://monday.com/marketplace). -2. Once installed, go to your previously prepared board to set up the integration. + +1. Install the KoboToolbox integration from + [monday.com apps marketplace](https://monday.com/marketplace). +2. Once installed, go to your previously prepared board to set up the + integration. ### First-time Use + 1. Go to the integration menu on the top right. - ![](https://lh3.googleusercontent.com/HiYRiisqIzMvR0UFWunDkVOUD7ftah5pB_6UIyC9adS8U5QQV0Wx4xMBPMibVLZGQxxgSv60GJkFjaynZZhjcNTQr5erx4LlZ7_cCf6x7-KMzaikA95EVBnx9Zs43k3xVwC2LmdomOkX7rdNaibGCd0) + ![monday-board-integrate](/images/kobotoolbox_monday_integration/monday-board-integrate.png) 2. Find KoboToolbox in the Integrations Center. - ![](https://lh5.googleusercontent.com/BZn80u4DUPYct7M7YnMAicg0DkHZSlJRmMnj2ul8oizSub1rJkc07_4QXohjIQm7zT-L2ZQmRJuuRlv7qWCiRg8pubLJ7hKf2hns-I80coH_bFsmVCZPDo8jrh1_7IIKwkqmStFU_b-6_7s6kcKDHF0) + ![app-marketplace](/images/kobotoolbox_monday_integration/app-marketplace.png) 3. Click on the integration and choose the included recipe. - ![](https://lh6.googleusercontent.com/5RB_8n-L-DCDduXA0EzL7zj-9YuXb52_OFz2J7w99Ayu82WuQkIGPCbh0Ytw9VvB85CqVeR2lpLFJ93L1Du24jeo1Y0enEoCFbXPOlLQk8Fu0osZsRFF1IAKeNrXuQwFxBHcX01gerQoUq40mlYpSz4) + ![kobo-integration](/images/kobotoolbox_monday_integration/kobo-integration.png) 4. For recipe configuration, set up the following parameters 1. Select the appropriate server 2. Provide your API key prepared earlier - 3. Choose the appropriate KoboToolbox project from the dropdown. Only deployed projects are available for selection - 4. Choose the label language from the dropdown. If your form contains more than one language, select the one that should be used to map questions to columns. The selected language will only be displayed to map KoboToolbox questions with monday.com columns. The data displayed in the monday.com board will always use the underlying XML data structure instead of translated Select One or Select Multiple labels. + 3. Choose the appropriate KoboToolbox project from the dropdown. Only + deployed projects are available for selection + 4. Choose the label language from the dropdown. If your form contains more + than one language, select the one that should be used to map questions + to columns. The selected language will only be displayed to map + KoboToolbox questions with monday.com columns. The data displayed in the + monday.com board will always use the underlying XML data structure + instead of translated Select One or Select Multiple labels. 5. Click "Item" to set up the mapping of questions to columns . - ![](https://lh3.googleusercontent.com/01WPMqWtTNx8SNcBUK7fQ0mNIKkJm2ZtPN5KQz9PRY2N9LY6sSbqGWRkVv5BYNuSxZidbuSGeHxpgHuwuP0s0Rv3CcTdLOmfDYFxemZgQJHx2LAK02ryXi9cSbHTstEFRwUPldZ9KrXUtTDLwd46EeM) -5. Once you are done with the recipe configuration, click the "Add to Board" button. - ![](https://lh5.googleusercontent.com/95uVH4RyuVDtZ7PQwx7fwPUcy7q1moGPBQC-wlZx3EaEWOS90MJ34QRkGNyWd9kHxpd3Hr5m-6jooj2pz1wQUvSuj4ovfdtK1Ig2kVHIh8dKUYWHquYBJzBbOKe8HVohwo-xA9fFp_AI6J3vbAW0lhs) -6. Now that you have the integration in place, there is a last step to configure REST Server on the KoboToolbox side. This is required to tell your KoboToolbox project to automatically forward data to monday.com. To do that, execute the following steps: - 1. Copy the integration link from the notification message sent to you on successful integration setup. The same link is added to the board description, so you can get it from there as well.\ - ![](https://lh5.googleusercontent.com/rbbcjdTQfJaQdLgky3XjbIfYYj3XtskkEbC7cgqdtIFjVI5djVgVpEaSN5NVNsFqPwC7ogIjMJlmpSo81CBU6oMdnZGnCVPsLmB77Vcvsog9XwQ2WXwuhI2qKdDOVrbHafzPUQ5Qc2A_qKrVhV35Joc) + ![dynamic-linking](/images/kobotoolbox_monday_integration/dynamic-linking.png) +5. Once you are done with the recipe configuration, click the "Add to Board" + button. ![recipe](/images/kobotoolbox_monday_integration/recipe.png) +6. Now that you have the integration in place, there is a last step to + configure REST Server on the KoboToolbox side. This is required to tell your + KoboToolbox project to automatically forward data to monday.com. To do that, + execute the following steps: + 1. Copy the integration link from the notification message sent to you on + successful integration setup. The same link is added to the board + description, so you can get it from there as well.\ + ![webhook-url](/images/kobotoolbox_monday_integration/webhook-url.png) 2. Log into your KoboToolbox account - 3. Go to the appropriate project. Then open the Settings tab, chooseREST Services, and click on 'Register a new service' button\ - ![](https://lh5.googleusercontent.com/l6B6B5RZQMiz-wV1U5p_Q8gb6VNI1oNhWv-DqQkOy035R_oVqVkUKwnUl6FEDeYLjVxLI8hv5m3DqFkfvs4M25-HitrfMtcPFv-N6ISkzZ6LTIFd7Zi00yyA76up1dEVPE871C-LL3qkbLdmXAUupEw) - 4. Enter "monday.com integration" as the Service Name and paste the previously copied integration link in the "Endpoint URL" field. - 5. In the "Custom HTTP Headers" section, insert the value "webhook-auth" in the "Name" field and put your Kobo API token in the "Value" field.\ - ![](https://lh5.googleusercontent.com/jpexd8mXdsCx66Yf-qYVslYW7n6mXIaFZiCLjpxpJbrD42jhMkpRcPC4Os3BhestICIUyVYyvitL08bcZM5yGfy53KGgaopYE6XX6z-VxgjXB5MdqJPQwiikgpzcuUM2gZXUSUrXqDmXwLUQgnW6pPY) + 3. Go to the appropriate project. Then open the Settings tab, chooseREST + Services, and click on 'Register a new service' button\ + ![create-rest-service](/images/kobotoolbox_monday_integration/create-rest-service.png) + 4. Enter "monday.com integration" as the Service Name and paste the + previously copied integration link in the "Endpoint URL" field. + 5. In the "Custom HTTP Headers" section, insert the value "webhook-auth" in + the "Name" field and put your Kobo API token in the "Value" field.\ + ![rest-service-modal](/images/kobotoolbox_monday_integration/rest-service-modal.png) 6. Click the 'Create' button. -7. That's all! Now each new submission to the KoboToolbox project will be automatically be added to your monday.com board according to your recipe configuration.\ - ![](https://lh4.googleusercontent.com/DI1U4zkdzMiVuktzaYHLWDtls0tjHV3pEBcd2z7cACnPk_BndZ8AYhNH9BJoOU_vxABfDFY36z4eFYj87V5w_HrEbdHdfh0xlD_DeCx1Uecui5fl4uzKx2e_teQhcx1i_FAxTjlLViKYRTf2PSiA9ZM) -Note: Any updates made to a form or individual submission in KoboToolbox project which is already sent to monday.com board will not be automatically synced at this point. Such changes like removing or renaming a question, changing group hierarchy, changing a group to a repeat group, or editing labels in the KoboToolbox form will not affect the items on monday.com board. +7. That's all! Now each new submission to the KoboToolbox project will be + automatically be added to your monday.com board according to your recipe + configuration.\ + + ![kobo-monday-data](/images/kobotoolbox_monday_integration/kobo-monday-data.png) + Note: Any updates made to a form or individual submission in KoboToolbox + project which is already sent to monday.com board will not be automatically + synced at this point. Such changes like removing or renaming a question, + changing group hierarchy, changing a group to a repeat group, or editing + labels in the KoboToolbox form will not affect the items on monday.com + board. ## FAQ + **What is the REST Service?** -More information about REST Services could be found in the following [guidance](https://support.kobotoolbox.org/rest_services.html). +More information about REST Services could be found in the following +[guidance](https://support.kobotoolbox.org/rest_services.html). **What is the dynamic fields mapping?** -Dynamic fields mapping is a pairing of fields represented on the monday.com board with the appropriate questions from the KoboToolbox project. +Dynamic fields mapping is a pairing of fields represented on the monday.com +board with the appropriate questions from the KoboToolbox project. **What happens if I change my data in the Kobo account?** -Any updates made to a form or individual submission in KoboToolbox project which is already sent to monday.com board will not be automatically synced at this point. +Any updates made to a form or individual submission in KoboToolbox project which +is already sent to monday.com board will not be automatically synced at this +point. **What happens if I change my data on the monday.com board?** -Changes made to data represented on the monday.com board will not be reflected in the KoboToolbox project. +Changes made to data represented on the monday.com board will not be reflected +in the KoboToolbox project. **What happens if I need to later change the language?** -Language selection affects only the dynamic fields mapping view on integration recipe configuration step. Board data will not be translated. +Language selection affects only the dynamic fields mapping view on integration +recipe configuration step. Board data will not be translated. **What happens if I delete the board on Kobo?** -If a project is deleted in Kobo, the integration would not run until the integration recipe is updated with a new project. +If a project is deleted in Kobo, the integration would not run until the +integration recipe is updated with a new project. **How do multiple select questions on Kobo transfer to monday?** -For multi select questions a column with Dropdown type should be used on monday.com board to have all selected options correctly transferred to the board. +For multi select questions a column with Dropdown type should be used on +monday.com board to have all selected options correctly transferred to the +board. **How do single select questions on Kobo transfer to monday?** -For single select questions columns with Dropdown or Text types can be used to have the selected option correctly transferred to the board. +For single select questions columns with Dropdown or Text types can be used to +have the selected option correctly transferred to the board. **What column types from Kobo shift to what column types from monday?** -All column types except File and External XML are supported by monday.com. If you can't find the appropriate column type on monday.com board, use a column with Text type. For the Area Kobo column type, it's better to use the Text column on monday side despite the fact that there is Location column type for this matter. +All column types except File and External XML are supported by monday.com. If +you can't find the appropriate column type on monday.com board, use a column +with Text type. For the Area Kobo column type, it's better to use the Text +column on monday side despite the fact that there is Location column type for +this matter. diff --git a/source/recently_updated.md b/source/recently_updated.md index 5a51f221..d4bbf433 100644 --- a/source/recently_updated.md +++ b/source/recently_updated.md @@ -1,6 +1,7 @@ # Recently updated Support Articles +1. [KoboToolbox Integration on monday.com](kobotoolbox_monday_integration.md) (24 Jun 2023) 1. [Question Matrix Response Type](matrix_response.md) (15 Mar 2023) 1. [General Data Protection Regulation (GDPR)](gdpr.md) (14 Mar 2023) 1. [Restricting Text Responses With Regular Expressions](restrict_responses.md) (9 Mar 2023) @@ -10,4 +11,3 @@ 1. [Adding Another Language in the Project Dashboard](language_dashboard.md) (1 Nov 2022) 1. [Editing Responses in Multiple Submissions](howto_edit_multiple_submissions.md) (22 Sep 2022) 1. [Exporting and Downloading Your Data](export_download.md) (22 Sep 2022) -1. [Form Settings and Metadata](form_meta.md) (25 Aug 2022)