From 0ca1af58d2fceb7906bef4eac4ef730643d69765 Mon Sep 17 00:00:00 2001 From: rudrapratik30 Date: Mon, 4 Aug 2025 12:19:49 +0530 Subject: [PATCH] [docs]: LTS 3.16 Version --- docs/docusaurus.config.js | 8 +- .../actions/_category_.json | 5 + .../version-3.16.0-LTS/actions/close-modal.md | 19 + .../actions/control-component.md | 102 + .../actions/copy-to-clipboard.md | 18 + .../actions/generate-file.md | 56 + .../version-3.16.0-LTS/actions/go-to-app.md | 18 + .../version-3.16.0-LTS/actions/logout.md | 18 + .../actions/open-webpage.md | 18 + .../version-3.16.0-LTS/actions/run-query.md | 18 + .../actions/set-localstorage.md | 58 + .../actions/set-page-var.md | 36 + .../actions/set-table-page.md | 24 + .../actions/set-variable.md | 24 + .../version-3.16.0-LTS/actions/show-alert.md | 23 + .../version-3.16.0-LTS/actions/show-modal.md | 18 + .../version-3.16.0-LTS/actions/switch-page.md | 55 + .../actions/unset-all-page-var.md | 20 + .../actions/unset-all-var.md | 20 + .../actions/unset-page-var.md | 27 + .../actions/unset-variable.md | 23 + .../app-builder/anti-patterns.md | 131 + .../app-builder/building-ui/canvas.md | 69 + .../building-ui/component-library.md | 28 + .../building-ui/component-properties.md | 43 + .../building-ui/component-state.md | 36 + .../app-builder/building-ui/pages.md | 136 + .../accessing-query-results.md | 24 + .../binding-data-to-components.md | 52 + .../creating-managing-queries.md | 110 + .../transforming-data.md | 64 + .../custom-code/constants-secrets.md | 58 + .../custom-code/controlling-components.md | 60 + .../custom-code/fx-dynamic-behaviour.md | 57 + .../custom-code/manage-variables.md | 128 + .../app-builder/custom-code/transform-data.md | 145 + .../app-builder/custom-theme.md | 121 + .../app-builder/debugging/inspector.md | 76 + .../app-builder/debugging/logs.md | 65 + .../app-builder/events/event-triggers.md | 40 + .../app-builder/events/overview.md | 41 + .../app-builder/events/use-case/csa.md | 40 + .../app-builder/events/use-case/page-nav.md | 43 + .../app-builder/events/use-case/variables.md | 69 + .../app-builder/import-export-apps.md | 61 + .../import-external-lib-js.md | 125 + .../import-external-lib-py.md | 126 + .../app-builder/modules/create-module.md | 41 + .../app-builder/modules/data-flow.md | 79 + .../app-builder/modules/import-export.md | 51 + .../app-builder/modules/input-output.md | 100 + .../app-builder/modules/overview.md | 22 + .../app-builder/modules/use-cases.md | 67 + .../app-builder/modules/using-module.md | 28 + .../app-builder/overview.md | 76 + .../walkthrough/row-level-security.md | 61 + .../build-with-ai/ai-docs-assitant.md | 56 + .../build-with-ai/generate-applications.md | 58 + .../build-with-ai/overview.md | 40 + .../build-with-ai/tooljet-mcp.md | 300 + .../contributing-guide/_category_.json | 5 + .../contributing-guide/code-of-conduct.md | 81 + .../documentation-guidelines/introduction.md | 40 + .../documentation-guidelines/pr-checklist.md | 15 + .../documentation-guidelines/style-guide.md | 236 + .../contributing-guide/l10n.md | 69 + .../marketplace/creating-a-plugin.md | 424 + .../marketplace/marketplace-setup.md | 80 + .../contributing-guide/setup/_category_.json | 5 + .../contributing-guide/setup/architecture.md | 25 + .../contributing-guide/setup/codespaces.md | 117 + .../contributing-guide/setup/docker.md | 189 + .../contributing-guide/setup/macos.md | 150 + .../setup/system-requirements.md | 24 + .../contributing-guide/setup/ubuntu.md | 164 + .../contributing-guide/setup/windows.md | 18 + .../contributing-guide/slackcoc.md | 90 + .../contributing-guide/testing.md | 62 + .../troubleshooting/eslint.md | 46 + .../troubleshooting/runpy-limits.md | 40 + .../tutorials/_category_.json | 5 + .../tutorials/create-widget.md | 27 + .../data-sources/_category_.json | 5 + .../data-sources/airtable.md | 269 + .../data-sources/amazonses.md | 77 + .../data-sources/appwrite.md | 149 + .../version-3.16.0-LTS/data-sources/athena.md | 103 + .../data-sources/azureblob.md | 142 + .../data-sources/baserow.md | 292 + .../data-sources/bigquery.md | 197 + .../data-sources/clickhouse.md | 174 + .../data-sources/cosmosdb.md | 128 + .../data-sources/couchdb.md | 284 + .../data-sources/custom-js.md | 176 + .../data-sources/databricks.md | 137 + .../data-sources/dynamodb.md | 312 + .../data-sources/elasticsearch.md | 489 + .../data-sources/firestore.md | 175 + .../version-3.16.0-LTS/data-sources/gcs.md | 127 + .../data-sources/google.sheets.md | 171 + .../data-sources/graphql.md | 124 + .../version-3.16.0-LTS/data-sources/grpc.md | 86 + .../data-sources/influxdb.md | 212 + .../data-sources/mailgun.md | 63 + .../data-sources/mariadb.md | 194 + .../version-3.16.0-LTS/data-sources/minio.md | 144 + .../data-sources/mongodb.md | 591 + .../version-3.16.0-LTS/data-sources/mssql.md | 151 + .../version-3.16.0-LTS/data-sources/mysql.md | 136 + .../version-3.16.0-LTS/data-sources/n8n.md | 73 + .../version-3.16.0-LTS/data-sources/nocodb.md | 163 + .../version-3.16.0-LTS/data-sources/notion.md | 463 + .../data-sources/openapi.md | 40 + .../data-sources/oracledb.md | 115 + .../data-sources/overview.md | 56 + .../data-sources/permissions.md | 28 + .../data-sources/postgresql.md | 138 + .../version-3.16.0-LTS/data-sources/redis.md | 101 + .../data-sources/restapi/authentication.md | 130 + .../data-sources/restapi/configuration.md | 82 + .../restapi/metadata-and-cookies.md | 105 + .../data-sources/restapi/querying-rest-api.md | 175 + .../data-sources/rethinkdb.md | 228 + .../version-3.16.0-LTS/data-sources/run-py.md | 208 + .../version-3.16.0-LTS/data-sources/s3.md | 181 + .../data-sources/sample-data-sources.md | 75 + .../data-sources/saphana.md | 48 + .../data-sources/sendgrid.md | 70 + .../version-3.16.0-LTS/data-sources/slack.md | 76 + .../version-3.16.0-LTS/data-sources/smtp.md | 74 + .../data-sources/snowflake.md | 57 + .../data-sources/soapapi.md | 63 + .../version-3.16.0-LTS/data-sources/stripe.md | 198 + .../version-3.16.0-LTS/data-sources/twilio.md | 57 + .../data-sources/typesense.md | 141 + .../data-sources/woocommerce.md | 91 + .../data-sources/zendesk.md | 116 + .../backup/gitsync-backup.md | 16 + .../development-lifecycle/cicd/example.md | 283 + .../development-lifecycle/cicd/gitsync-api.md | 135 + .../development-lifecycle/cicd/overview.md | 36 + .../environment/cloud/example.md | 30 + .../environment/cloud/multi-environment.md | 84 + .../environment/self-hosted/example.md | 30 + .../self-hosted/multi-environment.md | 84 + .../self-hosted/multi-instance/example.md | 81 + .../multi-instance/instance-as-environment.md | 29 + .../gitsync/delete-gitsync.md | 24 + .../gitsync/gitsync-config.md | 98 + .../development-lifecycle/gitsync/overview.md | 26 + .../development-lifecycle/gitsync/pull.md | 34 + .../development-lifecycle/gitsync/push.md | 134 + .../gitsync/ssh-config.md | 119 + .../development-lifecycle/overview.md | 27 + .../release/release-rollback.md | 45 + .../release/share-app.md | 30 + .../release/version-control.md | 38 + .../version-3.16.0-LTS/doc-home-page.mdx | 343 + .../getting-started/platform-overview.md | 65 + .../getting-started/quickstart-guide.md | 155 + .../version-3.16.0-LTS/homePageData.js | 219 + .../version-3.16.0-LTS/homepage.css | 3 + .../version-3.16.0-LTS/how-to/_category_.json | 5 + .../how-to/access-cellvalue-rowdata.md | 81 + .../how-to/access-users-groups.md | 44 + .../how-to/access-users-location.md | 65 + .../how-to/build-dynamic-forms.md | 70 + .../how-to/build-plugin-for-marketplace.md | 381 + .../bulk-update-multiple-rows-in-table.md | 150 + .../conditionally-display-components.md | 44 + .../how-to/conditionally-format-table.md | 160 + .../how-to/delete-multiple-rows-table.md | 148 + .../display-listview-record-new-page.md | 61 + .../how-to/intentionally-fail-js-query.md | 40 + .../how-to/loading-image-pdf-from-db.md | 128 + .../pass-query-params-in-custom-components.md | 97 + .../how-to/pass-values-in-rest-api.md | 55 + .../how-to/print-multitabs.md | 245 + .../how-to/run-action-from-runjs.md | 268 + .../run-query-at-specified-intervals.md | 115 + .../how-to/s3-custom-endpoint.md | 22 + .../how-to/serverside-pagination.md | 92 + .../version-3.16.0-LTS/how-to/setup-syslog.md | 101 + .../how-to/upload-files-aws.md | 162 + .../how-to/upload-files-gcs.md | 90 + .../version-3.16.0-LTS/how-to/use-axios.md | 68 + .../how-to/use-custom-parameters.md | 100 + .../how-to/use-events-on-chart.md | 258 + .../how-to/use-form-component.md | 102 + .../how-to/use-inspector.md | 92 + .../use-s3-presigned-url-to-upload-docs.md | 138 + .../version-3.16.0-LTS/how-to/use-to-py.md | 75 + .../how-to/use-url-params-on-load.md | 122 + .../marketplace/marketplace_overview.md | 87 + .../marketplace/plugins/amazon-redshift.md | 119 + .../marketplace/plugins/anthropic.md | 53 + .../marketplace/plugins/azurerepos.md | 120 + .../marketplace/plugins/cohere.md | 168 + .../marketplace/plugins/engagespot.md | 126 + .../marketplace/plugins/gemini.md | 115 + .../marketplace/plugins/github.md | 77 + .../marketplace/plugins/google-calendar.md | 75 + .../marketplace/plugins/harperdb.md | 288 + .../marketplace/plugins/huggingface.md | 112 + .../marketplace/plugins/jira.md | 446 + .../marketplace/plugins/lambda.md | 39 + .../marketplace/plugins/mistral.md | 100 + .../marketplace/plugins/openai.md | 219 + .../marketplace/plugins/pinecone.md | 224 + .../marketplace/plugins/plivo.md | 46 + .../marketplace/plugins/pocketbase.md | 88 + .../marketplace/plugins/portkey.md | 232 + .../marketplace/plugins/prestodb.md | 59 + .../marketplace/plugins/qdrant.md | 169 + .../marketplace/plugins/salesforce.md | 83 + .../marketplace/plugins/sharepoint.md | 806 + .../marketplace/plugins/supabase.md | 160 + .../marketplace/plugins/textract.md | 60 + .../marketplace/plugins/weaviate.md | 523 + .../project-overview/release-notes.md | 72 + .../version-3.16.0-LTS/security/audit-logs.md | 225 + .../version-3.16.0-LTS/security/compliance.md | 55 + .../security/constants/constants.md | 133 + .../security/constants/variables.md | 51 + .../version-3.16.0-LTS/setup/_category_.json | 5 + .../version-3.16.0-LTS/setup/ami.md | 126 + .../setup/azure-container.md | 121 + .../setup/choose-your-tooljet.md | 61 + .../setup/cloud-v3-migration.md | 260 + .../version-3.16.0-LTS/setup/digitalocean.md | 85 + .../version-3.16.0-LTS/setup/docker.md | 168 + .../version-3.16.0-LTS/setup/ecs.md | 241 + .../version-3.16.0-LTS/setup/env-vars.md | 368 + .../setup/google-cloud-run.md | 161 + .../version-3.16.0-LTS/setup/helm.md | 48 + .../version-3.16.0-LTS/setup/http-proxy.md | 34 + .../version-3.16.0-LTS/setup/index.md | 10 + .../setup/kubernetes-aks.md | 100 + .../setup/kubernetes-eks.md | 88 + .../setup/kubernetes-gke.md | 123 + .../version-3.16.0-LTS/setup/kubernetes.md | 91 + .../version-3.16.0-LTS/setup/openshift.md | 97 + .../setup/system-requirements.md | 42 + .../setup/tooljet-subpath.md | 33 + .../version-3.16.0-LTS/setup/try-tooljet.md | 51 + .../setup/upgrade-to-lts.md | 32 + .../setup/upgrade-to-v3.16.md | 58 + .../version-3.16.0-LTS/setup/upgrade-to-v3.md | 284 + .../version-3.16.0-LTS/setup/v2-migration.md | 37 + .../version-3.16.0-LTS/tj-setup/instances.md | 40 + .../tj-setup/licensing/cloud.md | 108 + .../tj-setup/licensing/self-hosted.md | 104 + .../tj-setup/org-branding/custom-domain.md | 35 + .../tj-setup/org-branding/white-labeling.md | 57 + .../version-3.16.0-LTS/tj-setup/overview.md | 22 + .../tj-setup/smtp-setup/configuration.md | 73 + .../tj-setup/smtp-setup/email-providers.md | 38 + .../tj-setup/tj-deployment.md | 42 + .../version-3.16.0-LTS/tj-setup/workspaces.md | 125 + .../version-3.16.0-LTS/tooljet-api.md | 1381 + .../tooljet-db/constraints/foreign-key.md | 124 + .../tooljet-db/constraints/primary-key.md | 87 + .../tooljet-db/data-types.md | 36 + .../tooljet-db/database-editor.md | 174 + .../tooljet-db/querying-tooljet-db.md | 274 + .../tooljet-db/table-operations.md | 79 + .../tooljet-db/tooljet-database.md | 103 + .../version-3.16.0-LTS/tooljetcli.md | 93 + .../version-3.16.0-LTS/tracking.md | 13 + .../tutorial/_category_.json | 5 + .../version-3.16.0-LTS/tutorial/actions.md | 31 + .../tutorial/adding-a-datasource.md | 36 + .../tutorial/adding-widget.md | 66 + .../tutorial/building-queries.md | 53 + .../tutorial/creating-app.md | 32 + .../version-3.16.0-LTS/tutorial/debugger.md | 19 + .../tutorial/keyboard-shortcuts.md | 25 + .../tutorial/mobile-layout.md | 26 + .../tutorial/sharing-and-deploying.md | 55 + .../tutorial/versioning-and-release.md | 112 + .../authentication/cloud-login.md | 56 + .../self-hosted/instance-login.md | 76 + .../authentication/self-hosted/overview.md | 61 + .../authentication/self-hosted/pat.md | 108 + .../self-hosted/workspace-login.md | 62 + .../instance-level/oidc-instance.md | 108 + .../workspace-level/oidc-workspace.md | 64 + .../onboard-users/archive-user.md | 91 + .../onboard-users/bulk-invite-user.md | 69 + .../onboard-users/invite-user.md | 66 + .../user-management/onboard-users/overview.md | 27 + .../onboard-users/self-signup-user.md | 71 + .../onboard-users/user-metadata.md | 43 + .../user-management/overview.md | 13 + .../profile-management/reset-password.md | 43 + .../profile-management/user-details.md | 25 + .../profile-management/user-profile.md | 25 + .../role-based-access/access-control.md | 102 + .../role-based-access/custom-groups.md | 53 + .../role-based-access/super-admin.md | 62 + .../role-based-access/user-roles.md | 55 + .../user-management/sso/github.md | 48 + .../user-management/sso/google.md | 54 + .../user-management/sso/ldap.md | 43 + .../user-management/sso/oidc/azuread.md | 34 + .../user-management/sso/oidc/google.md | 31 + .../user-management/sso/oidc/okta.md | 26 + .../user-management/sso/oidc/setup.md | 44 + .../user-management/sso/oidc/ssouserinfo.md | 36 + .../user-management/sso/overview.md | 15 + .../user-management/sso/saml/okta.md | 65 + .../user-management/sso/saml/setup.md | 51 + .../version-3.16.0-LTS/versions.md | 50 + .../widgets/_category_.json | 5 + .../version-3.16.0-LTS/widgets/bounded-box.md | 157 + .../widgets/button-group.md | 104 + .../version-3.16.0-LTS/widgets/button.md | 104 + .../version-3.16.0-LTS/widgets/calendar.md | 228 + .../version-3.16.0-LTS/widgets/chart/chart.md | 88 + .../widgets/chart/charts-examples.md | 281 + .../chart/transforming-data-for-charts.md | 324 + .../version-3.16.0-LTS/widgets/chat/csa.md | 31 + .../widgets/chat/markdown.md | 475 + .../widgets/chat/overview.md | 58 + .../widgets/chat/properties.md | 56 + .../version-3.16.0-LTS/widgets/checkbox.md | 130 + .../widgets/circular-progressbar.md | 82 + .../version-3.16.0-LTS/widgets/code-editor.md | 194 + .../widgets/color-picker.md | 108 + .../version-3.16.0-LTS/widgets/container.md | 70 + .../widgets/currency-input.md | 124 + .../widgets/custom-component.md | 142 + .../version-3.16.0-LTS/widgets/date-picker.md | 130 + .../widgets/date-range-picker.md | 176 + .../version-3.16.0-LTS/widgets/datepicker.md | 121 + .../widgets/datetime-picker-v2.md | 142 + .../version-3.16.0-LTS/widgets/divider.md | 59 + .../version-3.16.0-LTS/widgets/dropdown.md | 170 + .../version-3.16.0-LTS/widgets/email-input.md | 113 + .../version-3.16.0-LTS/widgets/file-picker.md | 116 + .../version-3.16.0-LTS/widgets/form/csa.md | 31 + .../widgets/form/custom-schema.md | 487 + .../version-3.16.0-LTS/widgets/form/form.md | 118 + .../widgets/form/properties.md | 51 + .../version-3.16.0-LTS/widgets/html.md | 87 + .../version-3.16.0-LTS/widgets/icon.md | 71 + .../version-3.16.0-LTS/widgets/iframe.md | 74 + .../version-3.16.0-LTS/widgets/image.md | 88 + .../widgets/kanban-board.md | 142 + .../version-3.16.0-LTS/widgets/link.md | 94 + .../version-3.16.0-LTS/widgets/listview.md | 223 + .../version-3.16.0-LTS/widgets/map.md | 113 + .../version-3.16.0-LTS/widgets/modal.md | 80 + .../version-3.16.0-LTS/widgets/multiselect.md | 165 + .../widgets/number-input.md | 160 + .../version-3.16.0-LTS/widgets/overview.md | 138 + .../widgets/package-lock.json | 32216 ++++++++++++++++ .../version-3.16.0-LTS/widgets/pagination.md | 89 + .../widgets/password-input.md | 153 + .../version-3.16.0-LTS/widgets/pdf.md | 89 + .../version-3.16.0-LTS/widgets/phone-input.md | 120 + .../version-3.16.0-LTS/widgets/qr-scanner.md | 86 + .../widgets/radio-button.md | 133 + .../widgets/range-slider.md | 101 + .../widgets/rich-text-editor.md | 94 + .../version-3.16.0-LTS/widgets/spinner.md | 59 + .../version-3.16.0-LTS/widgets/star-rating.md | 90 + .../version-3.16.0-LTS/widgets/statistics.md | 82 + .../version-3.16.0-LTS/widgets/steps.md | 76 + .../version-3.16.0-LTS/widgets/svg-image.md | 78 + .../widgets/table/columns.md | 576 + .../widgets/table/csa-and-variables.md | 44 + .../widgets/table/dynamic-column.md | 112 + .../widgets/table/properties.md | 199 + .../table/serverside-operations/filter.md | 116 + .../table/serverside-operations/overview.md | 41 + .../table/serverside-operations/pagination.md | 80 + .../table/serverside-operations/search.md | 67 + .../table/serverside-operations/sort.md | 70 + .../version-3.16.0-LTS/widgets/tabs.md | 96 + .../version-3.16.0-LTS/widgets/tags.md | 78 + .../version-3.16.0-LTS/widgets/text-input.md | 153 + .../version-3.16.0-LTS/widgets/text.md | 102 + .../version-3.16.0-LTS/widgets/textarea.md | 122 + .../version-3.16.0-LTS/widgets/time-picker.md | 129 + .../version-3.16.0-LTS/widgets/timeline.md | 91 + .../version-3.16.0-LTS/widgets/timer.md | 96 + .../widgets/toggle-switch.md | 127 + .../version-3.16.0-LTS/widgets/tree-select.md | 154 + .../widgets/vertical-divider.md | 62 + .../workflows/how-to/trigger-from-app.md | 41 + .../how-to/trigger-using-scheduler.md | 77 + .../workflows/how-to/trigger-using-webhook.md | 74 + .../version-3.16.0-LTS/workflows/logs.md | 12 + .../version-3.16.0-LTS/workflows/nodes.md | 70 + .../version-3.16.0-LTS/workflows/overview.md | 123 + .../workflows/permissions.md | 57 + .../version-3.16.0-LTS/workflows/results.md | 59 + .../version-3.16.0-LTS/workflows/triggers.md | 133 + .../version-3.16.0-LTS-sidebars.json | 821 + docs/versions.json | 1 + 401 files changed, 76110 insertions(+), 2 deletions(-) create mode 100644 docs/versioned_docs/version-3.16.0-LTS/actions/_category_.json create mode 100644 docs/versioned_docs/version-3.16.0-LTS/actions/close-modal.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/actions/control-component.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/actions/copy-to-clipboard.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/actions/generate-file.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/actions/go-to-app.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/actions/logout.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/actions/open-webpage.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/actions/run-query.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/actions/set-localstorage.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/actions/set-page-var.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/actions/set-table-page.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/actions/set-variable.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/actions/show-alert.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/actions/show-modal.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/actions/switch-page.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/actions/unset-all-page-var.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/actions/unset-all-var.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/actions/unset-page-var.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/actions/unset-variable.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/anti-patterns.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/building-ui/canvas.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/building-ui/component-library.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/building-ui/component-properties.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/building-ui/component-state.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/building-ui/pages.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/connecting-with-data-sources/accessing-query-results.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/connecting-with-data-sources/binding-data-to-components.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/connecting-with-data-sources/creating-managing-queries.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/connecting-with-data-sources/transforming-data.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-code/constants-secrets.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-code/controlling-components.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-code/fx-dynamic-behaviour.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-code/manage-variables.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-code/transform-data.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-theme.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/debugging/inspector.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/debugging/logs.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/events/event-triggers.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/events/overview.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/events/use-case/csa.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/events/use-case/page-nav.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/events/use-case/variables.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/import-export-apps.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/import-libraries/import-external-lib-js.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/import-libraries/import-external-lib-py.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/create-module.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/data-flow.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/import-export.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/input-output.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/overview.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/use-cases.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/using-module.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/overview.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/app-builder/walkthrough/row-level-security.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/build-with-ai/ai-docs-assitant.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/build-with-ai/generate-applications.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/build-with-ai/overview.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/build-with-ai/tooljet-mcp.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/_category_.json create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/code-of-conduct.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/documentation-guidelines/introduction.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/documentation-guidelines/pr-checklist.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/documentation-guidelines/style-guide.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/l10n.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/marketplace/creating-a-plugin.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/marketplace/marketplace-setup.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/_category_.json create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/architecture.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/codespaces.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/docker.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/macos.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/system-requirements.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/ubuntu.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/windows.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/slackcoc.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/testing.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/troubleshooting/eslint.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/troubleshooting/runpy-limits.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/tutorials/_category_.json create mode 100644 docs/versioned_docs/version-3.16.0-LTS/contributing-guide/tutorials/create-widget.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/_category_.json create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/airtable.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/amazonses.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/appwrite.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/athena.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/azureblob.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/baserow.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/bigquery.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/clickhouse.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/cosmosdb.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/couchdb.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/custom-js.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/databricks.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/dynamodb.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/elasticsearch.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/firestore.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/gcs.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/google.sheets.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/graphql.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/grpc.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/influxdb.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/mailgun.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/mariadb.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/minio.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/mongodb.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/mssql.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/mysql.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/n8n.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/nocodb.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/notion.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/openapi.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/oracledb.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/overview.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/permissions.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/postgresql.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/redis.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/restapi/authentication.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/restapi/configuration.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/restapi/metadata-and-cookies.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/restapi/querying-rest-api.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/rethinkdb.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/run-py.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/s3.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/sample-data-sources.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/saphana.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/sendgrid.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/slack.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/smtp.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/snowflake.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/soapapi.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/stripe.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/twilio.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/typesense.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/woocommerce.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/data-sources/zendesk.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/backup/gitsync-backup.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/cicd/example.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/cicd/gitsync-api.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/cicd/overview.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/cloud/example.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/cloud/multi-environment.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/self-hosted/example.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/self-hosted/multi-environment.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/self-hosted/multi-instance/example.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/self-hosted/multi-instance/instance-as-environment.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/delete-gitsync.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/gitsync-config.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/overview.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/pull.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/push.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/ssh-config.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/overview.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/release/release-rollback.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/release/share-app.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/release/version-control.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/doc-home-page.mdx create mode 100644 docs/versioned_docs/version-3.16.0-LTS/getting-started/platform-overview.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/getting-started/quickstart-guide.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/homePageData.js create mode 100644 docs/versioned_docs/version-3.16.0-LTS/homepage.css create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/_category_.json create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/access-cellvalue-rowdata.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/access-users-groups.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/access-users-location.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/build-dynamic-forms.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/build-plugin-for-marketplace.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/bulk-update-multiple-rows-in-table.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/conditionally-display-components.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/conditionally-format-table.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/delete-multiple-rows-table.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/display-listview-record-new-page.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/intentionally-fail-js-query.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/loading-image-pdf-from-db.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/pass-query-params-in-custom-components.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/pass-values-in-rest-api.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/print-multitabs.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/run-action-from-runjs.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/run-query-at-specified-intervals.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/s3-custom-endpoint.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/serverside-pagination.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/setup-syslog.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/upload-files-aws.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/upload-files-gcs.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/use-axios.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/use-custom-parameters.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/use-events-on-chart.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/use-form-component.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/use-inspector.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/use-s3-presigned-url-to-upload-docs.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/use-to-py.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/how-to/use-url-params-on-load.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/marketplace_overview.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/amazon-redshift.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/anthropic.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/azurerepos.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/cohere.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/engagespot.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/gemini.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/github.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/google-calendar.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/harperdb.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/huggingface.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/jira.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/lambda.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/mistral.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/openai.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/pinecone.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/plivo.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/pocketbase.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/portkey.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/prestodb.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/qdrant.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/salesforce.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/sharepoint.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/supabase.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/textract.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/weaviate.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/project-overview/release-notes.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/security/audit-logs.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/security/compliance.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/security/constants/constants.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/security/constants/variables.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/_category_.json create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/ami.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/azure-container.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/choose-your-tooljet.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/cloud-v3-migration.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/digitalocean.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/docker.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/ecs.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/env-vars.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/google-cloud-run.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/helm.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/http-proxy.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/index.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/kubernetes-aks.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/kubernetes-eks.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/kubernetes-gke.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/kubernetes.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/openshift.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/system-requirements.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/tooljet-subpath.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/try-tooljet.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/upgrade-to-lts.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/upgrade-to-v3.16.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/upgrade-to-v3.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/setup/v2-migration.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tj-setup/instances.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tj-setup/licensing/cloud.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tj-setup/licensing/self-hosted.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tj-setup/org-branding/custom-domain.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tj-setup/org-branding/white-labeling.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tj-setup/overview.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tj-setup/smtp-setup/configuration.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tj-setup/smtp-setup/email-providers.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tj-setup/tj-deployment.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tj-setup/workspaces.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tooljet-api.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tooljet-db/constraints/foreign-key.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tooljet-db/constraints/primary-key.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tooljet-db/data-types.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tooljet-db/database-editor.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tooljet-db/querying-tooljet-db.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tooljet-db/table-operations.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tooljet-db/tooljet-database.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tooljetcli.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tracking.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tutorial/_category_.json create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tutorial/actions.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tutorial/adding-a-datasource.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tutorial/adding-widget.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tutorial/building-queries.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tutorial/creating-app.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tutorial/debugger.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tutorial/keyboard-shortcuts.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tutorial/mobile-layout.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tutorial/sharing-and-deploying.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/tutorial/versioning-and-release.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/authentication/cloud-login.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/authentication/self-hosted/instance-login.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/authentication/self-hosted/overview.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/authentication/self-hosted/pat.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/authentication/self-hosted/workspace-login.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/group-sync/instance-level/oidc-instance.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/group-sync/workspace-level/oidc-workspace.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/onboard-users/archive-user.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/onboard-users/bulk-invite-user.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/onboard-users/invite-user.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/onboard-users/overview.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/onboard-users/self-signup-user.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/onboard-users/user-metadata.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/overview.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/profile-management/reset-password.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/profile-management/user-details.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/profile-management/user-profile.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/role-based-access/access-control.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/role-based-access/custom-groups.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/role-based-access/super-admin.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/role-based-access/user-roles.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/sso/github.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/sso/google.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/sso/ldap.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/sso/oidc/azuread.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/sso/oidc/google.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/sso/oidc/okta.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/sso/oidc/setup.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/sso/oidc/ssouserinfo.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/sso/overview.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/sso/saml/okta.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/user-management/sso/saml/setup.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/versions.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/_category_.json create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/bounded-box.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/button-group.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/button.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/calendar.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/chart/chart.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/chart/charts-examples.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/chart/transforming-data-for-charts.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/chat/csa.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/chat/markdown.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/chat/overview.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/chat/properties.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/checkbox.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/circular-progressbar.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/code-editor.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/color-picker.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/container.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/currency-input.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/custom-component.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/date-picker.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/date-range-picker.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/datepicker.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/datetime-picker-v2.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/divider.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/dropdown.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/email-input.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/file-picker.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/form/csa.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/form/custom-schema.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/form/form.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/form/properties.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/html.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/icon.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/iframe.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/image.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/kanban-board.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/link.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/listview.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/map.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/modal.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/multiselect.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/number-input.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/overview.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/package-lock.json create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/pagination.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/password-input.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/pdf.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/phone-input.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/qr-scanner.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/radio-button.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/range-slider.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/rich-text-editor.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/spinner.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/star-rating.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/statistics.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/steps.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/svg-image.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/table/columns.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/table/csa-and-variables.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/table/dynamic-column.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/table/properties.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/table/serverside-operations/filter.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/table/serverside-operations/overview.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/table/serverside-operations/pagination.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/table/serverside-operations/search.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/table/serverside-operations/sort.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/tabs.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/tags.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/text-input.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/text.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/textarea.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/time-picker.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/timeline.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/timer.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/toggle-switch.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/tree-select.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/widgets/vertical-divider.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/workflows/how-to/trigger-from-app.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/workflows/how-to/trigger-using-scheduler.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/workflows/how-to/trigger-using-webhook.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/workflows/logs.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/workflows/nodes.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/workflows/overview.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/workflows/permissions.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/workflows/results.md create mode 100644 docs/versioned_docs/version-3.16.0-LTS/workflows/triggers.md create mode 100644 docs/versioned_sidebars/version-3.16.0-LTS-sidebars.json diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 9568f9530b..9a32991807 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -261,10 +261,10 @@ module.exports = { // Please change this to your repo. editUrl: 'https://github.com/ToolJet/Tooljet/blob/develop/docs/', includeCurrentVersion: true, - lastVersion: '3.5.0-LTS', + lastVersion: '3.16.0-LTS', versions: { current: { - label: '3.11.0-Beta 🚧', + label: 'Beta 🚧', path: 'beta', banner: 'none', badge: false @@ -280,6 +280,10 @@ module.exports = { "3.5.0-LTS": { banner: 'none', badge: false + }, + "3.16.0-LTS": { + banner: 'none', + badge: false } } }, diff --git a/docs/versioned_docs/version-3.16.0-LTS/actions/_category_.json b/docs/versioned_docs/version-3.16.0-LTS/actions/_category_.json new file mode 100644 index 0000000000..f5b2dfe045 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/actions/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Actions Reference", + "position": 7, + "collapsed": true +} \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/actions/close-modal.md b/docs/versioned_docs/version-3.16.0-LTS/actions/close-modal.md new file mode 100644 index 0000000000..bb772142f9 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/actions/close-modal.md @@ -0,0 +1,19 @@ +--- +id: close-modal +title: Close modal +--- + +Use this action to close the modal that is already shown. + +Debounce field is empty by default, you can enter a numerical value to specify the time in milliseconds after which the action will be performed. ex: `300` + +:::info +You can also trigger actions from the **JavaScript code**. Check it out [here](/docs/how-to/run-actions-from-runjs). +::: + +
+ +ToolJet - Action reference - Close modal + +
+ diff --git a/docs/versioned_docs/version-3.16.0-LTS/actions/control-component.md b/docs/versioned_docs/version-3.16.0-LTS/actions/control-component.md new file mode 100644 index 0000000000..bab10a66bb --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/actions/control-component.md @@ -0,0 +1,102 @@ +--- +id: control-component +title: Control component (Component Specific Actions) +--- + +Control component action invokes the component specific actions. Component specific actions are the actions that are exclusive actions for a particular component. Component specific actions can be triggered either through the event handlers or from the Run JavaScript code query. + +You can find the component specific actions for the specific component in their respective documentation. For example, you can find the component specific actions for the **Bounded Box** component in the [Bounded Box](/docs/widgets/bounded-box) documentation. + +
+ Currently, Component specific actions are supported only by the below listed components. +
+ +
+
+ +:::info +Check out the **[demo](https://youtu.be/JIhSH3YeM3E)** of Component specific actions demonstrated in one of our community call. +::: + +## Using Component Specific Actions + +### Set a value for text input component using button's event handler + +- Drag a **Text Input** and a **Button** component onto the canvas. + +- Go to the **Inspector** on the left sidebar to check the exposed variables available for the `textinput1` component under the `components`. You'll see that the variable `value` is an empty string because the field value of the text input component is empty right now. + +
+ +![ToolJet - Action reference - Control Component](/img/actions/controlcomponent/inspector.png) + +
+ +- Now enter some value in the text input component and you'll see that the `value` in inspector has been updated. + +
+ +![ToolJet - Action reference - Control Component](/img/actions/controlcomponent/updated.png) + +
+ +- Now, click on the button's component handler to open up its properties in the right sidebar and then add a event handler for **On Click** event to trigger **Control Component** action. Select `textinput1` in component dropdown, `Set text` as Action, and in `Text` field enter the text that you want to update in the field value. + +
+ +![ToolJet - Action reference - Control Component](/img/actions/controlcomponent/button.png) + +
+ +- Now when you'll click on the button you'll see that the field value of the text input component has been updated with value that you set. + +
+ +![ToolJet - Action reference - Control Component](/img/actions/controlcomponent/set.png) + +
+ + +### Clear value of text input component using JavaScript query + +- Let's clear the value that we set in the previous section, using Run JavaScript code. Create a new Run JavaScript Code query and call the component and the CSA that component provides. + +**Syntax:** +```js +await components.textinput1.clear() +``` + +
+ +![ToolJet - Action reference - Control Component](/img/actions/controlcomponent/jsoption.png) + +
+ + +
+ +![ToolJet - Action reference - Control Component](/img/actions/controlcomponent/clear.png) + +
+ +- Finally, hit the **save and run** query button to fire up the query, and you'll see that the field value of the text input component has been cleared. + diff --git a/docs/versioned_docs/version-3.16.0-LTS/actions/copy-to-clipboard.md b/docs/versioned_docs/version-3.16.0-LTS/actions/copy-to-clipboard.md new file mode 100644 index 0000000000..81f97c360e --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/actions/copy-to-clipboard.md @@ -0,0 +1,18 @@ +--- +id: copy-to-clipboard +title: Copy to clipboard +--- + +Use this action to copy the text to the clipboard. + +Debounce field is empty by default, you can enter a numerical value to specify the time in milliseconds after which the action will be performed. ex: `300` + +:::info +You can also trigger actions from the **JavaScript code**. Check it out [here](/docs/how-to/run-actions-from-runjs). +::: + +
+ +ToolJet - Action reference - Copy to clipboard + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/actions/generate-file.md b/docs/versioned_docs/version-3.16.0-LTS/actions/generate-file.md new file mode 100644 index 0000000000..5e969b87a8 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/actions/generate-file.md @@ -0,0 +1,56 @@ +--- +id: generate-file +title: Generate file +--- + +# Generate file + +This action allows you to construct files on the fly and let users download it. + +## Options + +| Option | Description | +|--------|-------------| +| Type | Type of file to be generated. Types: `CSV`, `Text` and `PDF` | +| File name | Name of the file to be generated | +| Data | Data that will be used to construct the file. Its format will depend on the file type, as specified in the following section | +| Debounce | Debounce field is empty by default, you can enter a numerical value to specify the time in milliseconds after which the action will be performed. ex: `300` | + +:::tip +Check how to run **[generate file action using RunJS](/docs/how-to/run-actions-from-runjs/#generate-file)**. +::: + +### CSV Data Format + +To use the `CSV` file format, the data field should contain an array of objects. ToolJet assumes that the keys in each object are the same and represent the column headers of the CSV file. + +Example: + +```javascript +{{ + [ + { name: 'John', email: 'john@tooljet.com' }, + { name: 'Sarah', email: 'sarah@tooljet.com' }, + ] +}} +``` + +Using the above code snippet will generate a CSV file with the following content: + +```csv +name,email +John,john@tooljet.com +Sarah,sarah@tooljet.com +``` + +### Text Data Format + +To use the `Text` file format, the data field should contain a string. + +If you want to generate a text file based on an array of objects, you need to stringify the data before providing it. + +For example, if you are using the table component to provide the data, you can enter **`{{JSON.stringify(components.table1.currentPageData)}}`** in the Data field. + +### PDF data format + +The PDF data format supports two types of input: either a `string` or an `array of objects`. When using an array of objects, the resulting PDF will display the data in a tabular format with columns and rows. On the other hand, if a string is provided, the generated PDF will consist of plain text. diff --git a/docs/versioned_docs/version-3.16.0-LTS/actions/go-to-app.md b/docs/versioned_docs/version-3.16.0-LTS/actions/go-to-app.md new file mode 100644 index 0000000000..e38e00468e --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/actions/go-to-app.md @@ -0,0 +1,18 @@ +--- +id: go-to-app +title: Go to app +--- + +This action allows you to open any released ToolJet application when an event occurs. Only the apps that are released can be opened using this action. + +Debounce field is empty by default, you can enter a numerical value to specify the time in milliseconds after which the action will be performed. ex: `300` + +:::info +You can also trigger actions from the **JavaScript code**. Check it out [here](/docs/how-to/run-actions-from-runjs). +::: + +
+ +ToolJet - Action reference - Open webpage + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/actions/logout.md b/docs/versioned_docs/version-3.16.0-LTS/actions/logout.md new file mode 100644 index 0000000000..0e3187471c --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/actions/logout.md @@ -0,0 +1,18 @@ +--- +id: logout +title: Logout +--- + +This action allows you to log out of the application (ToolJet). + +Debounce field is empty by default, you can enter a numerical value to specify the time in milliseconds after which the action will be performed. ex: `300` + +:::info +You can also trigger actions from the **JavaScript code**. Check it out [here](/docs/how-to/run-actions-from-runjs). +::: + +
+ +ToolJet - Action reference - Logout + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/actions/open-webpage.md b/docs/versioned_docs/version-3.16.0-LTS/actions/open-webpage.md new file mode 100644 index 0000000000..749b205eb9 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/actions/open-webpage.md @@ -0,0 +1,18 @@ +--- +id: open-webpage +title: Open webpage +--- + +You can use this action to open a webpage(on a new tab) for any event. + +Debounce field is empty by default, you can enter a numerical value to specify the time in milliseconds after which the action will be performed. ex: `300` + +:::info +You can also trigger actions from the **JavaScript code**. Check it out [here](/docs/how-to/run-actions-from-runjs). +::: + +
+ +ToolJet - Action reference - Open webpage + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/actions/run-query.md b/docs/versioned_docs/version-3.16.0-LTS/actions/run-query.md new file mode 100644 index 0000000000..55eb1f16aa --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/actions/run-query.md @@ -0,0 +1,18 @@ +--- +id: run-query +title: Run Query +--- + +This action allows you to fire queries when an event occurs. + +Debounce field is empty by default, you can enter a numerical value to specify the time in milliseconds after which the action will be performed. ex: `300` + +:::info +You can also trigger actions from the **JavaScript code**. Check it out [here](/docs/how-to/run-actions-from-runjs). +::: + +
+ +ToolJet - Action reference - Run Query + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/actions/set-localstorage.md b/docs/versioned_docs/version-3.16.0-LTS/actions/set-localstorage.md new file mode 100644 index 0000000000..bfa52c0a5e --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/actions/set-localstorage.md @@ -0,0 +1,58 @@ +--- +id: set-localstorage +title: Set localStorage +--- + +# Set localStorage + +This action allows you to specify a `key` and its corresponding `value` to be stored in local storage of the browser. Local storage can be useful in a lot of scenarios. Some of the most common use cases of the local storage includes: +- Saving form values so that users don't accidentally lose them if they reload the page +- Storing any kind of data that is not going to be transferred to the database + +
+ +## Example: Setting a Component Value Based on Local Storage + +1. Add **Text Input**, **Button** and **Text** components to the canvas. + +
+ Add Components To The Canvas +
+ + +2. Select the Button, add a new event handler, and add a `Set local storage` action with `key` set to `localtest` and `value` set to `{{components.textinput1.value}}`. + +
+ Set Local Storage +
+ + This will set a local storage value with `localtest` as the key and the value entered in the Text Input component as its value. + +3. Create a `Run JavaScript code` query, and enter the code below: + + ```js + return localStorage.getItem("localtest"); + ``` +
+ Create RunJS Query +
+ + Click on the **Run** button in the Query Panel. This query will fetch the `localtest` local storage variable that we had set earlier. + +4. Select the **Text** component. Under its `Text` property, enter `{{queries.runjs1.data}}`. Now, the Text component will display the value returned by the `Run JavaScript code` query - the local variable we had set earlier. +
+ Update Value Of Text Component Based On Local Storage +
+ +5. Select the Button component. Add a new event handler to it, add a `Run query` action, select `runjs1` as the query, and set a debounce of `300`. +
+ Updating Text On Button Click +
+ + Now, every time you click on the Button component, it will set the local storage value, and the Text component will display the value set in local storage. + + :::info + Debounce field is empty by default, you can enter a numerical value to specify the time in milliseconds after which the action will be performed. ex: `300` + ::: + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/actions/set-page-var.md b/docs/versioned_docs/version-3.16.0-LTS/actions/set-page-var.md new file mode 100644 index 0000000000..5c50bab3ee --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/actions/set-page-var.md @@ -0,0 +1,36 @@ +--- +id: set-page-variable +title: Set page variable +--- + +Page variables are restricted to the page where they are created and cannot be accessed throughout the entire application like regular variables. + +Use this action to establish a variable and assign a value to it within the [Multipage Apps](/docs/tutorial/pages). + +By default, the debounce field is left empty. However, you can input a numeric value to indicate the time in milliseconds before the action is executed. For example, `300`. + +
+ +ToolJet - Action reference - Switch page + +
+ +## Using RunJS query to set page variable + +Alternatively, the set page variable action can be triggered via a RunJS query using the following syntax: +```js +await actions.setPageVariable('',) +``` + +`variablekey` must be provided as a string (enclosed in quotes), while the `variablevalue` does not require quotation marks if it is a numerical value. + +
+ +ToolJet - Action reference - Switch page + +
+ +:::info +For instructions on how to run actions from a RunJS query, refer to the how-to guide [Running Actions from RunJS Query](/docs/how-to/run-actions-from-runjs). +::: + diff --git a/docs/versioned_docs/version-3.16.0-LTS/actions/set-table-page.md b/docs/versioned_docs/version-3.16.0-LTS/actions/set-table-page.md new file mode 100644 index 0000000000..6c6414650c --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/actions/set-table-page.md @@ -0,0 +1,24 @@ +--- +id: set-table-page +title: Set Table Page +--- + +Use this action to change the page index in the table widget. + +## Options + +| Option | Description | +|--------|-------------| +| Table | Select table from the dropdown | +| Page Index | Numerical value for the page index. ex: `{{2}}` | +| Debounce | Debounce field is empty by default, you can enter a numerical value to specify the time in milliseconds after which the action will be performed. ex: `300` | + +:::info +You can also trigger actions from the **JavaScript code**. Check it out [here](/docs/how-to/run-actions-from-runjs). +::: + +
+ +ToolJet - Action reference - Open webpage + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/actions/set-variable.md b/docs/versioned_docs/version-3.16.0-LTS/actions/set-variable.md new file mode 100644 index 0000000000..ef611d43ba --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/actions/set-variable.md @@ -0,0 +1,24 @@ +--- +id: set-variable +title: Set variable +--- + +This action allows you to create a variable and assign a `value` to it. + +## Options + +| Option | Description | +|--------|-------------| +| Key | Name(String) of the variable through which you can access the value | +| Value | A value can be a string, number, boolean expression, array, or object | +| Debounce | Debounce field is empty by default, you can enter a numerical value to specify the time in milliseconds after which the action will be performed. ex: `300` | + +:::info +You can also trigger actions from the **JavaScript code**. Check it out [here](/docs/how-to/run-actions-from-runjs). +::: + +
+ +ToolJet - Action reference -Set variable + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/actions/show-alert.md b/docs/versioned_docs/version-3.16.0-LTS/actions/show-alert.md new file mode 100644 index 0000000000..f92ec12cd7 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/actions/show-alert.md @@ -0,0 +1,23 @@ +--- +id: show-alert +title: Show alert +--- + +This action allows you to display an alert message. + +You can set a custom **message** for the alert and choose a particular alert type. + +There are 4 types of alert messages - **Info**, **Success**, **Warning**, and **Error**. + +Debounce field is empty by default, you can enter a numerical value to specify the time in milliseconds after which the action will be performed. ex: `300` + +:::info +You can also trigger actions from the **JavaScript code**. Check it out [here](/docs/how-to/run-actions-from-runjs). +::: + +
+ +ToolJet - Action reference - Show Alert + +
+ diff --git a/docs/versioned_docs/version-3.16.0-LTS/actions/show-modal.md b/docs/versioned_docs/version-3.16.0-LTS/actions/show-modal.md new file mode 100644 index 0000000000..10f5d9ab17 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/actions/show-modal.md @@ -0,0 +1,18 @@ +--- +id: show-modal +title: Show modal +--- + +Use this action to show the modal for an event. + +Debounce field is empty by default, you can enter a numerical value to specify the time in milliseconds after which the action will be performed. ex: `300` + +:::info +You can also trigger actions from the **JavaScript code**. Check it out [here](/docs/how-to/run-actions-from-runjs). +::: + +
+ +ToolJet - Action reference - Show modal + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/actions/switch-page.md b/docs/versioned_docs/version-3.16.0-LTS/actions/switch-page.md new file mode 100644 index 0000000000..2438fb45e7 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/actions/switch-page.md @@ -0,0 +1,55 @@ +--- +id: switch-page +title: Switch Page +--- + +Utilize this action with various event handler to transition to a different page within the [Multipage App](/docs/tutorial/pages). + +By default, the debounce field is left empty. However, you can input a numeric value to indicate the time in milliseconds before the action is executed. For example, `300`. + +
+ +ToolJet - Action Reference - Page Switching + +
+ +## Query Params + +Query parameters can be passed through action such as `Switch Page`. The parameters are appended to the end of the application URL and are preceded by a question mark (`?`). + +Query parameters are composed of key-value pairs, where the `key` and `value` are separated by an equals sign (`=`). Multiple query parameters can be included by clicking on the `+` button. + +
+ +ToolJet - Action Reference - Page Switching + +
+ +In the above screenshot, we have provided the `username` as the key and the value is `{{globals.currentUser.email}}` which gets the email of the signed in user dynamically. When the button is clicked to trigger the `Switch Page` event handler attached to it then the URL on the switched page will have the parameters. + +They are commonly used to provide additional information to the server or to modify the behavior of a web page. They can be used for filtering search results, pagination, sorting, and various other purposes. + +
+ +ToolJet - Action Reference - Page Switching + +
+ +## Using RunJS query to switch page + +Alternatively, the switch page action can be activated via a RunJS query using the following syntax: +```js +await actions.switchPage('') +``` + +:::info +For instructions on how to run actions from a RunJS query, refer to the how-to guide [Running Actions from RunJS Query](/docs/how-to/run-actions-from-runjs). +::: + +### Switch page with query params + +The switch page action can also be triggered along with query parameters using the following syntax: + +```js +actions.switchPage('', [['param1', 'value1'], ['param2', 'value2']]) +``` diff --git a/docs/versioned_docs/version-3.16.0-LTS/actions/unset-all-page-var.md b/docs/versioned_docs/version-3.16.0-LTS/actions/unset-all-page-var.md new file mode 100644 index 0000000000..3adef08f49 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/actions/unset-all-page-var.md @@ -0,0 +1,20 @@ +--- +id: unset-all-page-var +title: Unset All Page Variables +--- + +Using this action you can unset all the page level variables at once. + +## Options + +|
Option
| Description | +|:-------|:------------| +| Run Only if | Add a condition. | +| Debounce | Debounce field is empty by default, you can enter a numerical value to specify the time in milliseconds after which the action will be performed. For example: `300` | + + +:::info +You can also trigger actions from the **JavaScript code**. Check it out [here](/docs/how-to/run-actions-from-runjs). +::: + +ToolJet - Action reference -Unset variable diff --git a/docs/versioned_docs/version-3.16.0-LTS/actions/unset-all-var.md b/docs/versioned_docs/version-3.16.0-LTS/actions/unset-all-var.md new file mode 100644 index 0000000000..b14c42aa17 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/actions/unset-all-var.md @@ -0,0 +1,20 @@ +--- +id: unset-all-var +title: Unset All Variables +--- + +Using this action you can unset all the app level variables at once. + +## Options + +|
Option
| Description | +|:-------|:------------| +| Run Only if | Add a condition. | +| Debounce | Debounce field is empty by default, you can enter a numerical value to specify the time in milliseconds after which the action will be performed. For example: `300` | + + +:::info +You can also trigger actions from the **JavaScript code**. Check it out [here](/docs/how-to/run-actions-from-runjs). +::: + +ToolJet - Action reference -Unset variable diff --git a/docs/versioned_docs/version-3.16.0-LTS/actions/unset-page-var.md b/docs/versioned_docs/version-3.16.0-LTS/actions/unset-page-var.md new file mode 100644 index 0000000000..933721c12d --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/actions/unset-page-var.md @@ -0,0 +1,27 @@ +--- +id: unset-page-variable +title: Unset page variable +--- + +Utilize this action to clear a variable that was established using the [set page variable action](/docs/actions/set-page-variable). + +By default, the debounce field is left empty. However, you can input a numeric value to indicate the time in milliseconds before the action is executed. For example, `300`. + +
+ +ToolJet - Action reference - Switch page + +
+ +## Using RunJS query to unset variable + +Alternatively, the unset page variable action can be triggered via a RunJS query using the following syntax: +```js +await actions.unsetPageVariable('') +``` + +`variablename` is the key of the variable that was provided while creating the variable. + +:::info +For instructions on how to run actions from a RunJS query, refer to the how-to guide [Running Actions from RunJS Query](/docs/how-to/run-actions-from-runjs). +::: \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/actions/unset-variable.md b/docs/versioned_docs/version-3.16.0-LTS/actions/unset-variable.md new file mode 100644 index 0000000000..7da5a78161 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/actions/unset-variable.md @@ -0,0 +1,23 @@ +--- +id: unset-variable +title: Unset variable +--- + +This action allows you to remove the variable that was created using the set variable action. + +## Options + +| Option | Description | +|--------|-------------| +| Key | Name(String) of the variable through which you can access the value | +| Debounce | Debounce field is empty by default, you can enter a numerical value to specify the time in milliseconds after which the action will be performed. ex: `300` | + +:::info +You can also trigger actions from the **JavaScript code**. Check it out [here](/docs/how-to/run-actions-from-runjs). +::: + +
+ +ToolJet - Action reference -Unset variable + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/anti-patterns.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/anti-patterns.md new file mode 100644 index 0000000000..096f10ad1f --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/anti-patterns.md @@ -0,0 +1,131 @@ +--- +id: anti-patterns +title: Anti-Patterns to Avoid +--- + +When building applications with ToolJet, it's essential to follow best practices to ensure your apps are efficient, maintainable, and provide a smooth user experience. This documentation outlines common anti-patterns to avoid while using ToolJet and offers solutions to optimize your applications. + +--- + +## 1. Unmanaged Component Naming + +- **Anti-Pattern**: Using default or non-descriptive names for components. +- **Solution**: **Rename all components with meaningful names to make the apps more manageable as they grow.** +- **Reason**: Descriptive names improve readability, making it easier for you and others to understand and maintain the app's structure. + +--- + +## 2. Exceeding Component Limits + +- **Anti-Pattern**: Having more than 2,500 components in a single app. +- **Solution**: **Limit each app to a maximum of 2,500 components.** +- **Reason**: Exceeding this number can slow down the app builder and live apps, impacting both development speed and user experience. + +--- + +## 3. Client-Side Operations for Large Data Sets + +- **Anti-Pattern**: Handling large data sets with client-side operations on the Table component. +- **Solution**: **Implement [server-side operations](/docs/widgets/table/serverside-operations/overview) for handling large data sets.** +- **Reason**: Server-side operations reduces the amount of data loaded at once, improving load times and performance. + +--- + +## 4. Simultaneous Execution of Multiple JavaScript Queries + +- **Anti-Pattern**: Triggering a large amount of JavaScript queries simultaneously through a single event. For example, using an event to trigger a **Run JavaScript code** query that contains code to execute 15-20 other **Run JavaScript code** queries within the application. +- **Solution**: **Limit the number of simultaneous JavaScript queries triggered by a single event.** +- **Reason**: Triggering numerous Run JavaScript queries at the same time can significantly degrade browser performance as it each JavaScript query creates **[new execution environment](https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API/Microtask_guide/In_depth#javascript_execution_contexts)** within the browser. JavaScript in browsers runs on a single main thread. When multiple scripts are executed concurrently, they compete for execution time on this thread. + +--- + +## 5. Storing Base64 Data in Variables + +- **Anti-Pattern**: Capturing and storing Base64 data directly in variables. +- **Solution**: **Store large data, like base64 images, in a database and retrieve it as needed.** +- **Reason**: Storing Base64 data in variables can consume significant memory and slow down the app. Retrieving data from a database as needed optimizes performance. + +--- + +## 6. Loading All Tabs Simultaneously + +- **Anti-Pattern**: Loading all items in the Tab component at once when there are numerous tabs. +- **Solution**: **Enable the β€œRender only active tabs” option.** +- **Reason**: This prevents unnecessary loading of inactive tabs, reducing initial load times and improving performance. + +--- + +## 7. Excessive Number of Pages in an App + +- **Anti-Pattern**: Including too many pages within a single app. +- **Solution**: **Limit the number of pages per app to maintain optimal performance.** +- **Reason**: An excessive number of pages can slow down the app and make it difficult to manage. Organize content efficiently and consider splitting the app if necessary. + +--- + +## 8. Using Non-Blocking Commands in JavaScript for Synchronous Operations + +- **Anti-Pattern**: Using non-blocking commands like `Promise.all` and `setTimeout` in the **Run JavaScript code** query when an accurate isLoading state is needed. +- **Solution**: **Avoid non-blocking operations in JavaScript Queries if you require an accurate isLoading status. Ensure your code is synchronous within the Run JavaScript code query.** +- **Reason**: Non-blocking operations can cause **Run JavaScript code** query to exit before these commands complete, leading to an incorrect isLoading status and potentially confusing users. + +--- + +## 9. Triggering Unnecessary Queries on Page Load + +- **Anti-Pattern**: Triggering all queries on page load, regardless of their necessity. +- **Solution**: **For multi-page apps, only trigger queries on page load that are needed for the specific page.** +- **Reason**: Loading unnecessary data consumes resources and slows down page load times. Optimizing queries enhances performance. + +--- + +## 10. Using Actions inside Loop Functions +- **Anti-Pattern**: Using actions inside loop functions. + +Example: +You have a Table displaying data from `{{page.variables.data}}` and a **Save Changes** button that updates the data. When users edit rows and click **Save Changes**, you might initially implement the update like this: + +```javascript +const data = page.variables.data; +Object.values(components.table1.dataUpdates).forEach(ele => { + data[ele.id] = ele; + actions.setPageVariable("data", data); +}); +``` + +The setPageVariable action is executed inside the loop for each row update. This causes the table to re-render every time the variable is updated, leading to significant performance degradation, especially when multiple rows or cells are updated simultaneously. + +- **Solution**: **Modify your code to update the page variable once after all changes are processed**: + +```javascript +const data = page.variables.data; +Object.values(components.table1.dataUpdates).forEach(ele => { + data[ele.id] = ele; +}); +actions.setPageVariable("data", data); +``` + +- **Reason**: By updating the variable after the loop completes, the table re-renders only once. This reduces unnecessary processing and significantly improves performance when handling multiple updates. + +--- + +## 11. Direct Mutation of Data + +- **Anti-Pattern**: Directly mutating data structures through JavaScript code, such as using `queries.getEmployees.data = []`. +- **Solution**: Always use ToolJet's built in **[actions](/docs/how-to/run-actions-from-runjs/)** to manipulate data. +- **Reason**: Direct mutation of data can lead to unexpected bugs and make debugging more complex. + +--- + +## 12. Naming Component/Query with Hyphen or Space + +- **Anti-Pattern**: Naming components or queries with hyphens or spaces in between, such as `run-py1` or `my query`. +- **Solution**: **Use names without hyphens or spaces**, or reference them using bracket notation (e.g., `{{queries['run-py1'].isLoading}}`). +- **Reason**: Hyphens and spaces can cause syntax issues. Using bracket notation or avoiding these characters ensures consistency and prevents errors in query or component references. + +--- + +## Conclusion + +Avoiding these anti-patterns when using ToolJet ensures that your applications are efficient, responsive, and maintainable. By following these best practices, you can enhance user experience and simplify app management. Always consider the impact of your development choices on both performance and scalability. + diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/building-ui/canvas.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/building-ui/canvas.md new file mode 100644 index 0000000000..116a033ee3 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/building-ui/canvas.md @@ -0,0 +1,69 @@ +--- +id: canvas +title: Canvas and Layout +--- + +**Canvas** is the main area in the app-builder where you build your application and design the user interface. + +App Builder: Canvas + +## Customizing Canvas + +Through Global Settings, you can customize the following properties of the **Canvas**: + +- **Max width of canvas**: Defines the maximum width of the canvas, which can be set in pixels or as a percentage of the screen size. The height of the canvas expands automatically as more components are added. +- **Canvas background**: Sets the background color of the canvas. This can also be controlled dynamically by clicking on **fx** and entering a logical expression. +- **App mode**: You can choose from three theme modes + - **Auto**: Adapts to the browser's theme settings or allows users to switch between light and dark modes. + - **Light**: Keeps the app in light mode, users cannot switch to dark mode. + - **Dark**: Keeps the app in dark mode, users cannot switch to light mode. + +App Builder: Canvas + +## Building the User Interface + +To build the user interface, components can be dragged from the [Components Library](/docs/beta/app-builder/building-ui/component-library) on the right. Use the Component Handle to reposition a component. A component can be resized from any of its edges or corners. + +App Builder: Canvas + +### Grid, Snapping and Markers + +ToolJet's Canvas provides a grid background, smart snapping, and visual markers to support precise alignment and positioning of components. Components automatically snap to grid lines and nearby elements, reducing the need for manual adjustments. Each cell on the canvas grid has a fixed height of 10 pixels. The width of each cell adjusts based on the screen size. + +App Builder: Canvas + +## Creating Layout + +In ToolJet, components can be grouped using a Layout component such as a **[Container](/docs/widgets/container)** or a **[Form](/docs/widgets/form)**. You can drag and drop the relevant components into the layout components on the canvas to create a section. + +App Builder: Canvas + +## Managing Components on Canvas + +#### Select and Move Multiple Components + +You can select multiple components by clicking and dragging over them, or by clicking individually while holding the Shift key. Once selected, all components can be moved together as a group. + +#### Copy Components + +Components on the canvas can be copied using **Cmd/Ctrl + C**. + +App Builder: Canvas + +#### Paste Components + +Copied components can be pasted onto the canvas using **Cmd/Ctrl + V**. + +App Builder: Canvas + +#### Clone Components + +Components on the canvas can be cloned using **Cmd/Ctrl + D**. Unlike copy and paste, cloning creates a duplicate of the selected component instantly. + +App Builder: Canvas + +

+ +:::note +For additional shortcuts, refer to the [Keyboard Shortcuts Guide](/docs/tutorial/keyboard-shortcuts). +::: diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/building-ui/component-library.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/building-ui/component-library.md new file mode 100644 index 0000000000..6ce18fbb1d --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/building-ui/component-library.md @@ -0,0 +1,28 @@ +--- +id: component-library +title: Component Library +--- + +**Components** are the building blocks of ToolJet applications, used to create interactive user interfaces. The **Component Library**, located on the right, contains all [available components](#available-components). + +Components can be added to the canvas by dragging and dropping them onto the canvas at your desired location. + +App Builder: Component library + +## Available Components + +| Category | Components | +|:----------|:------------| +| **Buttons** | [Button](/docs/widgets/button), [Button Group](/docs/widgets/button-group) | +| **Data** | [Table](/docs/widgets/table/), [Chart](/docs/widgets/chart/)| +| **Layouts** | [Form](/docs/widgets/form), [Modal](/docs/widgets/modal), [Container](/docs/widgets/container), [Tabs](/docs/widgets/tabs), [ListView](/docs/widgets/listview), [Kanban](/docs/widgets/kanban), [Calendar](/docs/widgets/calendar) | +| **Text Inputs** | [Text Input](/docs/widgets/text-input), [Text Area](/docs/widgets/textarea), [Email Input](/docs/widgets/email-input), [Password Input](/docs/widgets/password-input), [Rich Text Editor](/docs/widgets/rich-text-editor) | +| **Number Inputs** | [Number Input](/docs/widgets/number-input), [Phone Input](/docs/widgets/phone-input), [Currency Input](/docs/widgets/currency-input), [Range Slider](/docs/widgets/range-slider), [Star Rating](/docs/widgets/star-rating) | +| **Select Inputs** | [Dropdown](/docs/widgets/dropdown), [Multi-Select](/docs/widgets/multiselect), [Toggle Switch](/docs/widgets/toggle-switch-v2), [Radio Button](/docs/widgets/radio-button), [Checkbox](/docs/widgets/checkbox), [Tree Select](/docs/widgets/tree-select) | +| **Date and Time Inputs** | [Date-range Picker](/docs/widgets/date-range-picker), [Date Picker](/docs/widgets/date-picker-v2), [Time Picker](/docs/widgets/time-picker), [Date-Time Picker](/docs/widgets/datetime-picker-v2) | +| **Navigation** | [Link](/docs/widgets/link), [Pagination](/docs/widgets/pagination), [Steps](/docs/widgets/steps) | +| **Media** | [Icon](/docs/widgets/icon), [Image](/docs/widgets/image), [SVG Image](/docs/widgets/svg-image), [PDF](/docs/widgets/pdf), [Map](/docs/widgets/map) | +| **Presentation** | [Text](/docs/widgets/text), [Tags](/docs/widgets/tags), [Circular Progressbar](/docs/widgets/circular-progress-bar), [Timeline](/docs/widgets/timeline), [Divider](/docs/widgets/divider), [Vertical Divider](/docs/widgets/vertical-divider), [Spinner](/docs/widgets/spinner), [Statistics](/docs/widgets/statistics), [Timer](/docs/widgets/timer) | +| **Custom** | [Custom Component](/docs/widgets/custom-component), [HTML Viewer](/docs/widgets/html), [iFrame](/docs/widgets/iframe) | +| **Miscellaneous** | [Filepicker](/docs/widgets/file-picker), [Code Editor](/docs/widgets/code-editor), [Color Picker](/docs/widgets/color-picker), [Bounded Box](/docs/widgets/bounded-box), [QR Scanner](/docs/widgets/qr-scanner) | +| **Legacy** | [Modal](/docs/widgets/modal), [Datetime Picker](/docs/widgets/datepicker/), [Radio Button](/docs/widgets/radio-button), [Toggle Switch](/docs/widgets/toggle-switch), [Dropdown](/docs/2.50.0-LTS/widgets/dropdown), [Multiselect](/docs/widgets/multiselect) | diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/building-ui/component-properties.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/building-ui/component-properties.md new file mode 100644 index 0000000000..04740d55ce --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/building-ui/component-properties.md @@ -0,0 +1,43 @@ +--- +id: component-properties +title: Component Properties +--- + +**Component properties** define the appearance, behavior, and interactivity of UI components in ToolJet. It also allows you to configure component-level permissions, enabling only selected users or user groups to interact with the component. + +Each component includes a unique set of properties based on its functionality. Here’s an overview of common types of configurable properties: + +- **Labels and Data Fields**: For input components, you can configure the label, add placeholders, default values, define validation rules, etc. +- **Data**: Populate components with static values or dynamic data through queries. +- **Events**: Events are actions or triggers that respond to user interactions or specific conditions in your application. They let you define custom logic (like running a query, navigating to a page, or showing a toast) in response to user activity or application changes β€” without writing backend code. +- **Styles**: Define visual attributes like colors, spacing, alignment, and border radius to adjust how the component appears. +- **State**: Control component states such as loading, visibility, or whether the component is disabled. You can toggle these manually or control them using logical expressions. +- **Device**: Configure whether the component should be visible on specific devices, such as mobile or desktop. + +App Builder: Component library + +These are just a few commonly used property types. For detailed information on any specific component and its properties, refer to their individual documentation. + +## Component Level Permissions + +You can configure component-level permissions to allow only selected end users or user groups to interact with the component. The component will not render at all for users who don’t have access. + +Suppose you're building an app to manage customer license details. Sales representatives should be able to create, update, and delete customer information. Meanwhile, Product, Marketing, and Customer Success teams should only view this data. To enforce this, you can configure component-level permissions to hide the Edit and Delete buttons from non-sales users. These buttons won’t render at all for users without access. + +### Configuring Component Level Permission + +Follow these steps to configure component level permission: + +**Role Required**: Admin or Builder + +1. Select the component, then click the kebab menu (three dots) next to the component name in the properties panel. + App Builder: Component library +2. Select **Component permission**.
+ App Builder: Component library +3. Select the **Type**: + - **All users with access to the app**: Grants access to all users who can access the application. + - **Users**: Select specific users from the dropdown. Note: These users must already have access to the application. + - **User groups**: Restricts access to members of selected user groups. Note: The selected user groups must have access to the application. + App Builder: Component library + +**Note**: If a component's permissions have been configured by an admin and the builder is not included in the allowed users or groups, the builder will not be able to modify the component’s permissions. diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/building-ui/component-state.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/building-ui/component-state.md new file mode 100644 index 0000000000..f8523301f3 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/building-ui/component-state.md @@ -0,0 +1,36 @@ +--- +id: component-state +title: Component State +--- + +Every ToolJet component maintains a stateβ€”a set of values representing its current data and configuration. This state can be accessed through exposed variables, which allow components to interact with other parts of the application. For example, the value entered into a text input component can be passed to a query to fetch data from the database. + +Each component has a unique set of exposed variables based on its functionality β€” for example, a **Table** component exposes `selectedRow`, a checkbox exposes `isChecked`, and so on. + +Component states in ToolJet are dynamic and can be modified at runtime using built-in functions called [Component-Specific Actions (CSAs)](/docs/beta/app-builder/events/use-case/csa), such as `reset()`, `setValue()`, and `setVisibility()`. These actions let you trigger logic in response to user interactions. + +Component states can be used across the application to build interactive and reactive experiences: +- In queries β€” to send user inputs or component values as parameters. +- In other components β€” to conditionally display, update, or interact with components. + +## Available Component States + +In the App-Builder, you can view all available component states using the Inspector located in the left sidebar. For more details, refer to the [Inspector](/docs/beta/app-builder/debugging/inspector) guide. + +App Builder: Properties Panel + +- Open the Components dropdown inside the Inspector. +- Select the component whose state you want to inspect. +- A secondary dropdown will appear showing all the available states. + +You can also copy the state value or its path, which can be used to access it from another component or query. When you hover over a state in the Inspector, two icons appear β€” one for copying the path and one for copying the value. + +App Builder: Properties Panel + +## Accessing Component State + +You can access a component’s state using the following syntax:
+`{{components..}}` + +Example: `{{components.numberinput1.value}}` - This will fetch the value entered by the user in the **numberinput1** component. + diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/building-ui/pages.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/building-ui/pages.md new file mode 100644 index 0000000000..96a7a985e9 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/building-ui/pages.md @@ -0,0 +1,136 @@ +--- +id: pages +title: Pages and Navigation +--- + +ToolJet allows the creation of multi-page applications, helping you break your application into different sections. Instead of building everything on a single screen, you can create separate pages to organize different functionalities or enable navigation within your application. + +You can add the following items to the navigation menu in ToolJet: + +1. **New Page**: Create new pages to support multi-page applications and organize functionalities more effectively. +2. **Web Pages**: Add external URLs to the navigation menu to redirect users to specific webpages. +3. **ToolJet Application**: Link to other ToolJet applications directly from the nav menu. Note: The application must be a released app within the same workspace. +4. **Nav Group**: Group related navigation items together to simplify navigation in complex applications. For example, all admin-related items can go under one group, and user-related items under another. + +This guide discusses how pages and navigation menu work, how to create new navigation items manage them. + +## Page Properties + +Each page in ToolJet comes with properties that define its identity and behavior. These properties help in organizing, referencing, and securing pages within your application. + +App Builder: Canvas + +### Name + +A display name for the page, shown in the application's navigation menu. It is also used to reference the page within the ToolJet application. You can optionally add an icon to make the page easier to identify in the menu. The page name and icon can be updated using the kebab menu (three dots) next to the page name and then going to edit page details. + +App Builder: Canvas + +### Handle + +The page handle is a unique identifier used to generate a shareable URL for the page. It is appended as a slug to the end of your application URL. By default, it's auto-generated from the page name. You can change it manually from edit page details option. + +### Home Page + +The home page is the default landing page when the app launches. Only one page can be designated as the home page in your application. It cannot be deleted, disabled, or hidden from the page menu. A page can be marked as the home page using the kebab menu (three dots) next to the page name or by going to edit page details option. + +### Permissions + +Page permissions control who can access a particular page. You can choose to: + +- Allow access to all users with application access +- Restrict access to selected users +- Restrict access to selected [user groups](/docs/user-management/role-based-access/user-roles) + +To configure page permissions, click the kebab menu (three dots) next to the page name, select Page permission, and select a permission option from the popup. + +### Disable Page + +**Disable Page** allows you to disable a page, making it inaccessible in the released application. A page marked as Home cannot be disabled. + +### Hide Page on Navigation Menu + +You can hide a page from the navigation menu in the released application. However, hidden pages can still be accessed using the Switch Page action or by navigating directly to the page URL. Pages set as Home cannot be hidden. + +## Header and Navigation Menu + +### App Header + +The app header section allows you to control what is displayed in the application’s header. + +App Builder: Canvas + +- **Show app header**: Toggle this on to display the app header. +- **Show logo**: Toggle this on to display the application logo. You can update the logo from the [white labeling](/docs/tj-setup/org-branding/white-labeling/) settings. +- **Title**: Set a title for the application. This will be displayed in the app header. + +### Navigation Menu + +The **Navigation Menu** lets users navigate between pages, external web pages and other ToolJet applications in your application. You can customize how it looks and works, or even hide certain pages from it. + +#### Show Navigation Menu +Toggle this on to display the navigation menu. When disabled, no navigation menu will be displayed, but users will be still able to navigate using events and page urls. + +#### Position +Choose whether to display the navigation menu at the top or on the side of the application. + +**Top Navigation Menu**
+App Builder: Canvas + +**Side Navigation Menu**
+App Builder: Canvas + +#### Style + +**Top Navigation Menu**
+Choose the display style for the top navigation menu: Text only or Text + Icon. The top navigation menu cannot be collapsed. + +**Side Navigation Menu**
+Choose display styles from: Text only, Icon only, or Text + Icon. The side navigation menu also supports a collapsible layout. + +## Event Handlers + +The Page Event Handler lets you trigger actions automatically when a page loads. Use it to prepare data, set default values, or run any required logic. + +For example, it can run a query to fetch the latest data from the database and populate it in a table component. This ensures the page is ready with up-to-date information whenever it is loaded. + +App Builder: Canvas + +## Exposed Variables + +Exposed variables are values from a page that can be accessed throughout the application. These include default page-level values like page name, page ID, and page handle. In addition to the default ones, custom page variables can also be defined and accessed as exposed variables. + +| Variable | Description | How To Access | +| ----------- | ----------- | ------------- | +| handle | Represents the slug of the page within the app. It is automatically set when a page is created, but can be [renamed](#handle) from the page options. | `{{page.handle}}`| +| name | Indicates the name of the page. | `{{page.name}}` | +| id | Each page in the ToolJet application receives a unique identifier upon creation. | `{{page.id}}` | +| variables | Variables object contains all the variables created for a specific page using the [Set Page Variable](/docs/actions/set-page-variable) action. | `{{page.variables.}}`, where `` refers to the variable name. | + +## Manage Navigation Item + +### New Page + +You can add a new page to organize the application navigation or to separate different parts of your app. To add a new page, click on the **+ New page** button at the bottom of the Pages and menu panel. Enter the page name and press enter to create the page. + +App Builder: Canvas + +### Web Page + +To link an external web page to the navigation menu, click the kebab menu (three dots) next to the **+ New Page** button, then select **Add nav item with URL**. +Enter a name and provide the URL. You can also choose whether to open the web page in a new tab or in the same tab, and optionally select an icon for the navigation item. + +App Builder: Canvas + +### ToolJet App + +To add a ToolJet application to the navigation menu, click the kebab menu (three dots) next to the **+ New Page** button, then select **Add nav item ToolJet app**. +Enter a name and select the application from the dropdown. Only the release application from the same workspace will appear in the dropdown. You can also choose whether to open the application in a new tab or in the same tab, and optionally select an icon for the navigation item. + +App Builder: Canvas + +### Nav Group + +Related navigation item can be grouped together using the nav group. To add a new nav group, click the kebab menu (three dots) next to the **+ New Page** button, then select **Add nav group**. Enter the group name and press enter to create the group. You can then drag items into the group folder. You can also add an icon to the group for better visual identification. + +App Builder: Canvas diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/connecting-with-data-sources/accessing-query-results.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/connecting-with-data-sources/accessing-query-results.md new file mode 100644 index 0000000000..2f366ae757 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/connecting-with-data-sources/accessing-query-results.md @@ -0,0 +1,24 @@ +--- +id: accessing-query-results +title: Accessing Query Results +--- + +Once your query is created and executed, the next step is to actually use the data, whether you’re displaying it in a table, populating dropdowns, or using it in logic for another query. Let’s walk through how you can work with query results. + +To better understand what your query is returning, use the Inspector panel. Click on the Inspect button, select your query from the query dropdown. You'll find the following keys: +- **data**: The processed response returned from the query. This is the data you typically bind to components. +- **rawData**: The original API response. It's useful for debugging. +- **isLoading**: A boolean indicating whether the query is currently running. Great for showing loaders or disabling buttons during fetches. + +App Builder: Query Panel + +
+ +You can pass query results to a component by using the `{{ }}` syntax. For example, if you have a query named *getEmployees*, you can pass its data to a Table component by setting the table's data property to `{{queries.getEmployees.data}}`. Learn more about binding queries to components [here](/docs/app-builder/connecting-with-data-sources/binding-data-to-components). + +### Quick Actions +In the Inspector panel, when you hover over a property like data, you’ll see two icons. These icons allow you to quickly copy either the path or value of that property. Here’s what they do: +1. Copy Path - Copies the full path (e.g., `{{queries.getEmployees.data}}`) so you can reference it directly into component fields. +2. Copy Value - Copies the actual data returned, useful when inspecting values or mocking responses. + +These icons are available for every property, making it easier to wire up your data to components. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/connecting-with-data-sources/binding-data-to-components.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/connecting-with-data-sources/binding-data-to-components.md new file mode 100644 index 0000000000..b78ce125fd --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/connecting-with-data-sources/binding-data-to-components.md @@ -0,0 +1,52 @@ +--- +id: binding-data-to-components +title: Binding Data to Components +--- + +In this section, you’ll learn how to connect and bind data to components within ToolJet, whether the data comes from a data source or other components in your app. + +You can display data from your data source queries in the components using the `{{ }}` syntax. For instance, you can pass data to a **Table** component's Data property using the following format: `{{ queries..data }}` + +For example, you are working on an Employee Directory app where you want to show all employees in a table. If you have a query named *listEmployees* that returns an array of employee objects, you can pass its data to a **Table** component by setting the table's data property to `{{queries.listEmployees.data}}`. + +App Builder: bininding data to components + + +ToolJet also supports JavaScript expressions inside `{{ }}`, allowing you to dynamically transform data before display. Here are a few use cases: + +## Use cases +### Filtering Data +If you want to show only employees from the β€˜Engineering’ department: + +```js +{{ queries.listEmployees.data + .filter(employee => employee.department === 'Engineering') }} +``` +### Map Data + +If you want to show only employee names in a dropdown: + +```js +{{ queries.listEmployees.data + .map(employee => employee.name) }} +``` + +### Conditional Rendering + +If you want to show a greeting if an employee is selected in a table: + +```js +{{ components.table1.selectedRow ? `Hello, ${components.table1.selectedRow.name}` : "" }} +``` + +### Chaining Expressions + +You can also chain multiple JavaScript methods for more complex transformations. For example, filtering and then mapping: + +```js +{{ queries.listEmployees.data + .filter(emp => emp.department === 'Engineering') + .map(emp => emp.name.toUpperCase()) }} +``` + +These expressions give you control over how data is displayed and interacted with inside your ToolJet applications. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/connecting-with-data-sources/creating-managing-queries.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/connecting-with-data-sources/creating-managing-queries.md new file mode 100644 index 0000000000..c18b338667 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/connecting-with-data-sources/creating-managing-queries.md @@ -0,0 +1,110 @@ +--- +id: creating-managing-queries +title: Creating and Managing Queries +--- + +A query is a way to interact with your **[data sources](/docs/data-sources/overview)** and acts as the link between your app’s UI and your data. Queries connect your app to configured data sources such as SQL, NoSQL, vector databases, APIs, spreadsheets, and cloud services. Whether it’s retrieving records from your MongoDB collection or updating data in a SQL database, you can use queries to interact with them. + +Queries are created in the Query Panel, located at the bottom of the App Builder, where you can either use a visual form-based builder or write code/SQL manually. + +App Builder: Query Panel + + +## Creating a New Query + +- Click on the **+** button in the Query Panel to open a menu listing the available data sources or you can add a new data source by clicking on **+ Add new Data Source** button. +- Select the desired data source. + +App Builder: Create queries + +## Configuring the Query + +The interface for configuring queries depends on the type of data source. If you are using any SQL data source, you can configure your query using either GUI mode or SQL mode. Rest of the data sources can be configured using form-based GUI. + +### GUI mode + +- For the Postgres data source, when using GUI mode (as shown in the image below), you’ll need to select the operations you want to perform and then fill out the required fields. + App Builder: configure PostgreSQL queries + +- In this example using the AWS S3 data source, you can perform the **Upload object** operation to upload a file to an S3 bucket. You’ll need to provide details such as the bucket name, key, and other relevant parameters based on the selected operation. + + App Builder: configure AWS S3 queries + + +### SQL mode + +For data sources such as MYSQL, PostgreSQL or SQL Server, you can choose SQL mode where you can write the SQL query to perform your desired operation. + +App Builder: configure PostgreSQL queries + + + + +## Custom Parameters +You often need a query to fetch different data based on user input, component state, or other logic. Custom parameters allow you to pass dynamic values into a query, making it reusable without hard-coding values. + +Let's say you have a query that fetches employee details based on department. Instead of creating a separate query for each department, you can define a parameter like `departmentName`, and use it to filter results dynamically. + +To add parameters, simply click the **+ Add** button next to the Parameters label in the query editor. + +For each parameter, you need to specify: +- **Name**: The identifier for the parameter. +- **Default value**: This value can be a constant string, number, or object. + +**Syntax for utilizing the parameter:** Employ `parameters.` in your query. It's important to note that parameters can only be utilized within the specific query where they are defined. + +Learn more about **[Using Custom Parameters](/docs/how-to/use-custom-parameters)**. + +Custom Parameters + +## Preview and Run + +Before connecting a query to your app’s UI, use the Preview button to check what it returns. This is especially useful when working with external APIs or complex SQL. You can inspect the raw or JSON response, debug any issues, and make sure the data matches what your components need. + +Once things look good, use the Run button to execute the query and verify how it interacts with your components and other queries. + +## Query Level Permission + +You can configure query-level permissions to allow only selected end users or user groups to run the query. + +### Configuring Query Level Permission + +Follow these steps to configure query level permission: + +**Role Required**: Admin or Builder + +1. Select the query, then click the kebab menu (three dots) next to the query name on the query panel.
+ App Builder: Create queries +2. Select **Query permission**.
+ App Builder: Component library +3. Select the **Type**: + - **All users with access to the app**: Grants access to all users who can access the application. + - **Users**: Select specific users from the dropdown. Note: These users must already have access to the application. + - **User groups**: Restricts access to members of selected user groups. Note: The selected user groups must have access to the application. + App Builder: Component library + +**Note**: If a query's permissions have been configured by an admin and the builder is not included in the allowed users or groups, the builder will not be able to run or modify the query or its permissions. + +## Triggers + +Triggers allow you to control when and how a query executes within your application. You can find them under the **Settings** tab in the query editor. Following are the triggers available: + +### Run This Query on Application Load + +You can use this when you want data to be available as soon as the page loads, like auto-fetching a user’s dashboard data or populating dropdown options without requiring user input. + +### Request Confirmation Before Running Query +For actions that modify or delete data, enable this to prompt users for confirmation. It acts as a safeguard against accidental clicks that could alter critical records. + App Builder: confirmation dialog + +### Show Notification on Success +Let users know when actions are completed successfully. This improves UX by giving real-time feedback. You can customize the message and how long it stays visible. + App Builder: notification on query run + +### Retry on Network Errors +This setting is only available for REST API queries. Here, you get an option to automatically retry REST API requests in case of certain network errors or specific HTTP status codes. By default, it retries a failed API request up to 3 times before marking it as failed. Refer to [REST API Documentation](/docs/data-sources/restapi/querying-rest-api/#retry-on-network-errors) for more details. + + + diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/connecting-with-data-sources/transforming-data.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/connecting-with-data-sources/transforming-data.md new file mode 100644 index 0000000000..ef5d8b84c1 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/connecting-with-data-sources/transforming-data.md @@ -0,0 +1,64 @@ +--- +id: transforming-data +title: Transforming Data +--- + +Transformations help you clean up your data before passing it to UI components. While building applications, the raw data you fetch from an API or database often needs customization before displaying it in the components. You might need to: + +- Convert raw ISO timestamps into DD/MM/YYYY. +- Flatten deeply nested objects for use in tables or dropdowns. +- Convert currency, distance, or temperature values before display. +- Adjust field names to match component expectations. + +That’s where data transformations come in. It helps you to shape your backend data into a frontend-friendly format, keeping your UI logic simple and your app easier to maintain. + +You can write transformation code in JavaScript or Python. Let’s say you’re building an employee management dashboard, and your getEmployees API returns a lot of extra data: + +```json +[ + { + "id": 1, + "name": "John Doe", + "email": "john@example.com", + "phone_number": "+91876543210", + "department_id": 1, + "salary": "$50k" + }, + { ... } +] +``` + +But in your table, you only want to display *id*, *name*, *designation* fields. Instead of changing the API or manually filtering inside every component, you can transform the data once, at the query level. + +## Using JavaScript + +Head to the Transformations tab of your query and write your javascript code: + +```javascript +return data.map(item => ({ + id: item.id, + name: item.name, + designation: item.designation +})); +``` + +This ensures every time the query runs, your components receive exactly the shape of data they need. + +App Builder: query transformations + +## Using Python + +If you’re more comfortable with Python, just switch the language in the transformation tab and use a similar approach: + +```python +[ + {"id":item['id'], + "name": item['name'], + "designation": item['designation'] + } for item in data +] +``` + +App Builder: query transformations + +Transformations provide you with an easy way to adjust your data before using it in your applications. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-code/constants-secrets.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-code/constants-secrets.md new file mode 100644 index 0000000000..4004362fcb --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-code/constants-secrets.md @@ -0,0 +1,58 @@ +--- +id: constants-secrets +title: Referencing Constants and Secrets +--- + +When building applications in ToolJet, you often need to reuse fixed values (such as URLs or environment flags) or securely handle sensitive information (such as API keys or database credentials). [Workspace Constants and Secrets](/docs/security/constants/) make this process easy, safe, and maintainable, especially when working across multiple apps or with larger teams. + +In this guide, you'll learn how to use Workspace Constants and Secrets within your ToolJet apps. + +You can create a global constant or secret directly from the ToolJet Dashboard. Once created, these constants and secrets can be referenced by builders within the app-builder. + +CMS Page + +## Characteristics and Usage + +Both constants and secrets allow you to store reusable values for your apps. However, they serve different purposes and have distinct characteristics as shown below: + +| Characteristic | Global Constants | Secrets | +|-------------------------|:-----------------------------:|:-------------------------:| +| Components | βœ… | ❌ | +| Data Queries | βœ… | βœ… | +| Encrypted in DB | βœ… | βœ… | +| Masked in Frontend | ❌ | βœ… | +| Resolved on Client Side | βœ… | ❌ | +| Resolved on Server Side | ❌ | βœ… | +| Naming Convention | `{{constants.constant_name}}` | `{{secrets.secret_name}}` | + +## Access Control + +To maintain security and governance: +- Only Admins can create, edit, or delete Constants and Secrets. +- Builders can reference them in their applications but cannot modify them. + +## Use Cases + +### Reusable Values Across Apps with Global Constants + +Imagine you’re building an app that fetches product prices from an API. The base URL of your API is the same across multiple queries. + +Instead of hard-coding this URL everywhere, define a Global Constant. Now, if the base URL ever changes, you only need to update it in one place, reducing errors and improving maintainability. + +- Name: `API_BASE_URL` +- Value: `https://api.example.com/v1` + +You can now reference it in your queries or custom code: + +constant usecase + +### Handling Sensitive Credentials with Secrets + +Let’s say your application uses a third-party service such as OpenAI that requires an API key. Storing this key directly in queries or code isn’t a good practice. Instead, define a Secret: + +- Name: `OPENAI_API_KEY` +- Value: `sk_****************` + +secret usecase + +Secrets are encrypted and can only be accessed within queries and data sources. They are not accessible in components, ensuring your credentials remain secure. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-code/controlling-components.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-code/controlling-components.md new file mode 100644 index 0000000000..025c39e138 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-code/controlling-components.md @@ -0,0 +1,60 @@ +--- +id: control-components +title: Controlling Components Using Code +--- + +Apart from [**events**](/docs/docs/app-builder/events/use-case/csa), Component-Specific Actions (CSAs) can also be triggered using code to modify component properties and state. + +Let’s say you want to: +- Reset a **Form** automatically after submission +- Show or hide components based on a condition +- Update a **Text Input** based on another field’s value +- Disable a button during API calls +- Change the active tab programmatically + +In each of these cases, you can use CSAs with JavaScript or Python queries. + +## How It Works + +Each component in ToolJet comes with a set of CSAs. Below are some examples of CSAs: +- setValue() – Sets or updates a component’s value +- clear() – Clears the value of an input +- setLoading() – Sets or unsets the loading state +- setDisable() – Enables or disables a component +- setVisibility() – Dynamically controls component visibility + +You can trigger these actions from your JavaScript or Python queries. + +For example, if you have a **Button** that triggers a query and want to show a loader until the data is loaded. You could use `setLoading()` to show a spinner: + +```js +await components.button1.setLoading(queries.getData.isLoading) +``` + +## Use Cases + +### Pre-fill a Form Field Based on User Selection + +When a user selects a product from a **Dropdown**, automatically set the price in a **Text Input** component: + +```js +await components.textInput1.setValue(components.dropdown1.value) +``` + +### Clear Fields After Submitting a Form: + +After a user submits a **Form**, reset all inputs: + +```js +await components.formInput.resetForm() +``` + +### Close the Modal after Form Submission: + +If you are using a **Modal** for collecting data, close it once the **Form** has been submitted successfully: + +```js +await components.modal1.close() +``` + +Using CSAs in your code lets you dynamically control component behavior based on custom logic. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-code/fx-dynamic-behaviour.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-code/fx-dynamic-behaviour.md new file mode 100644 index 0000000000..99fe660a2e --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-code/fx-dynamic-behaviour.md @@ -0,0 +1,57 @@ +--- +title: Using fx for Dynamic Behaviour +id: fx-dynamic-behaviour +--- + +In ToolJet, you can make your applications more interactive by writing logic directly in component properties using the **fx** editor. For instance, you might want to disable a **Button** until all required form fields are filled, or change the color of an input field based on whether the entered value is valid. You can define this conditional logic using JavaScript expressions in the **fx** editor. + +This makes it easy to build intuitive interfaces, with components that respond in real time to user actions and data updates. + +## How fx Works +Whenever you see the **fx** icon next to a property in the component settings, it means you can switch to expression mode. Clicking the icon opens an input box where you can write custom logic using JavaScript inside `{{ }}`. You can reference query results, component states, and app-level variables directly within these expressions. ToolJet supports full JavaScript syntax here, including conditional logic, string interpolation, array methods like map, filter, and reduce, and more. + +Let’s say you’re building a form that takes user input. You want the **Submit button** to be enabled only if all form validations pass. + +With ToolJet’s **fx** support, you can achieve this in the Disabled property of the button component like so: + + button disable + +This expression disables the **Button** when the **Form** is invalid. No manual toggling needed. Similarly, you could use the same approach to update other properties such as visibility, background color, font size etc. for different components. + +If you are new to ToolJet and want to learn how to access component properties, check out [this guide](/docs/app-builder/building-ui/component-state#available-component-states). + +## Use Cases + +### Loading States + +Display loading indicators until the data is loaded. + +Example: In an app where you are loading data in the table component, you might want to show a loading spinner while fetching employee data. + + button disable + +### Conditional Styling + +Apply conditional styling (colors, fonts, sizes) based on values from queries or application state. + +**Example:** In an employee directory with a user list, you can display different background colors on **Table** cells based on whether the user is active or inactive. + + button disable + +### Form Validation + +Enable or disable submit buttons based on the validity of form inputs. + +**Example:** In **Forms**, you can enable the Submit button only when all required fields are correctly filled. + + button disable + +### Conditional Visibility + +Show or hide components based on specific conditions. + +**Example:** In an employee directory application, within the personal details **Form**, you can conditionally display a **Text Input** for entering a custom country name when the user selects β€œother” from the country dropdown. + + button disable + +Using the **fx** editor, you can easily add dynamic behavior to your applications with minimal code. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-code/manage-variables.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-code/manage-variables.md new file mode 100644 index 0000000000..9bdd2c22c7 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-code/manage-variables.md @@ -0,0 +1,128 @@ +--- +id: managing-variables +title: Managing Variables +--- + +Variables in ToolJet allow you to store and manage temporary data across pages or within a single page. They’re useful for passing values between components, persisting state, and building dynamic applications. + +This guide explains how to manage [variables](/docs/beta/app-builder/events/use-case/variables) using code in your applications. + +## Set, Get, and Unset Variables + +Setting, getting, and unsetting variables lets you control the state of a variable. Use set to create variables or update their values, get to access them in components or queries, and unset to delete them. + +### Set Variables + +To set a variable in an application using code in a RunJS or RunPy query, use the `setVariable` function and pass the variable name and value. + +```js +actions.setVariable("", "") +``` + +**Example:** If you’re building an internal tool for order management and want to store the *orderId* of a newly created order. You can use the following code: + +```js +actions.setVariable('currentOrderId', 'ORD-10293') +``` + +Similarly, if you want to set a page variable use the `setPageVariable` function: + +```js +actions.setPageVariable("", "") +``` + +**Example:** If you want to set a page variable named *userPreferences*, with an object containing all the user preferences, like `{theme:'dark', language:'en'}`, you can use the following code: + +```js +actions.setPageVariable('userPreferences', { theme: 'dark', language: 'en' }); +``` + +### Get Variables +To access variables you can use the `getVariable` and `getPageVariable` functions. These functions take one argument: the name of the variable. + +```js +// To get app-level variable +actions.getVariable(""); + +// To get page-level variable +actions.getPageVariable(""); +``` + +**Example:** If you previously stored a variable named *currentOrderId* and now want to access it, You can use the code below: + +```js +const orderId = actions.getVariable('currentOrderId'); +``` + +### Unset Variables +To unset(delete) a variable, you can use the `unsetVariable` and `unsetPageVariable` functions. These functions take one argument: the name of the variable. + +```js +// To delete app-level variable +actions.unsetVariable("") + +// To delete page-level variable +actions.unsetPageVariable("") +``` + +**Example:** If you want to unset a page variable named *userPreference*, you would write: + +```js +actions.unsetPageVariable('userPreferences'); +``` + +## Use Cases + +### Sharing Data Across Pages + +You can share data across different pages by setting a variable on one page and accessing it on another. + +For instance, in a content management system, the homepage might display a list of posts (as shown in the image below). When a user clicks the **View Post** button, they’re taken to a new page to see the full content. To enable this, the *postId* is stored as a global variable so it can be accessed on both the homepage and the post details page. + + CMS Page + +On the homepage, you could add a click event handler to the **View Post** button that sets a variable called *selectedListViewIndex* with the ID of the selected post. Then, on the second page, you could retrieve this variable and use it to fetch the full post from the database. + +CMS variable + +```js +// Saving the post ID to a variable +actions.setVariable("selectedListViewIndex", components.postList.selectedRow.id); + +// Retrieving the post ID +const postId = actions.getVariable("selectedListViewIndex"); +``` + +### Setting Up Form Payload for a Multi-Step Form + +If you’re building a multi-step **Form**, each step may require different fields and appear on separate pages. You can use variables to construct the payload based on the currently active page. + +Let’s say your **Form** has three steps: personal details, educational background, and work experience. Each step has its own set of fields. If you want to construct a final payload to be sent as the body when the submit button is clicked on the last step, you can create a RunJS query that checks which step is active and constructs the payload accordingly. Here’s how you might implement this: + +```js +let payload = {}; + +if (page.handle === "personalDetails") { + payload.firstName = components.firstName.value; + payload.lastName = components.lastName.value; + payload.email = components.email.value; +} +else if (page.handle === "education") { + payload.educationLevel = components.educationLevel.value; + payload.major = components.major.value; + payload.graduationYear = components.graduationYear.value; +} +else if (page.handle === "workExperience") { + payload.companyName = components.companyName.value; + payload.startDate = components.startDate.value; + payload.endDate = components.endDate.value; + payload.jobTitle = components.jobTitle.value; +} + +actions.setVariable("formPayload", payload); +``` + +You can now pass this payload to a query that sends it to your backend API endpoint. + +Variables help maintain data across pages, while page variables help manage localized, page-specific logic. Use page variables for temporary, page-specific UI state, and use app-level variables when data must persist across multiple pages. + diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-code/transform-data.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-code/transform-data.md new file mode 100644 index 0000000000..d66b7d1676 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-code/transform-data.md @@ -0,0 +1,145 @@ +--- +id: transform-data +title: Transforming Data +--- + +Data isn’t always available in a ready-to-use format from a single source. Often, you’ll need to transform or combine data before displaying it. Common use cases include: + +- Merging results from multiple data sources +- Restructuring API responses before referencing them to components +- Applying business logic such as filtering, sorting, or grouping +- Formatting fields like dates, currency values, or nested JSON objects + +If you need to transform data from a single query, you can use the [transformation](/docs/beta/app-builder/connecting-with-data-sources/transforming-data) option within the query. + +App Builder: query transformations + +However, if your use case involves combining data from multiple queries or components, you’ll need to use RunJS or RunPy queries. + +For example, let's say you're building an inventory management application and want to display a list of items along with their current stock levels. You have inventory data stored in a PostgreSQL database and product data coming from a ToolJet Database. To display the item names alongside their current stock levels, you would need to merge the results from these two queries using a RunJS query as shown below. + +App Builder: query transformations + +ToolJet allows you to write RunJS or RunPy queries to perform these transformations without requiring changes to your backend. This guide demonstrates how to transform data for real-world use cases. + +## How It Works + +ToolJet allows you to access data from: +- Configured data source queries (e.g., PostgreSQL, REST APIs, MongoDB, etc.) +- Component values (like inputs, dropdowns, tables) + +With RunJS or RunPy queries, you can write code to manipulate data from multiple sources. + +## Use Cases + +### 1. Merging Data from Two APIs + +Let's say you want to show a list of users with their order counts. The user data comes from a REST API, and the order data comes from a MySQL database. Now, if you want to show a combined list of users along with their respective order counts, you can use a RunJS or RunPy query to combine the results: + +```js +// Assuming getUsers and getOrders are already defined as queries +// Run queries to fetch users and their orders +await queries.getUsers.run(); +await queries.getOrders.run(); + +// Retrieve data from both queries +const userList = queries.getUsers.getData(); // Array of user records +const orderList = queries.getOrders.getData(); // Array of order records + +// Enrich each user with their corresponding order count +const usersWithOrderCount = userList.map(user => { + // Find all orders placed by the current user + const userOrderHistory = orderList.filter(order => order.userId === user.id); + + return { + ...user, + orderCount: userOrderHistory.length + }; +}); + +return usersWithOrderCount; +``` +
+ +Data from getUsers query + +```js +[ + { id: 1, name: "Alice", email: "alice@example.com" }, + { id: 2, name: "Bob", email: "bob@example.com" }, + { id: 3, name: "Charlie", email: "charlie@example.com" }, + { id: 4, name: "David", email: "david@example.com" }, + { id: 5, name: "Eva", email: "eva@example.com" }, + { id: 6, name: "Frank", email: "frank@example.com" } +] +``` + +
+ +
+ +Data from getOrders query + +```js +[ + { id: 101, userId: 1, total: 120.00 }, + { id: 102, userId: 1, total: 45.50 }, + { id: 103, userId: 2, total: 89.99 }, + { id: 104, userId: 1, total: 60.00 }, + { id: 105, userId: 3, total: 150.00 }, + { id: 106, userId: 3, total: 200.00 }, + { id: 107, userId: 4, total: 75.00 }, + { id: 108, userId: 5, total: 50.00 }, + { id: 109, userId: 4, total: 90.00 } +] +``` + +
+ +
+ +Data from usersWithOrderCount query + +```js +[ + { id: 1, name: "Alice", email: "alice@example.com", orderCount: 3 }, + { id: 2, name: "Bob", email: "bob@example.com", orderCount: 1 }, + { id: 3, name: "Charlie", email: "charlie@example.com", orderCount: 2 }, + { id: 4, name: "David", email: "david@example.com", orderCount: 2 }, + { id: 5, name: "Eva", email: "eva@example.com", orderCount: 1 }, + { id: 6, name: "Frank", email: "frank@example.com", orderCount: 0 } +] +``` + +
+ +Now you can reference this data in your app, for instance, in a **Table** component. + +### 2. Grouping and Sorting Data with Custom Business Logic + +Let's say you have a list of products and want to group them by category and sort each group by stock (highest to lowest). This helps display organized inventory in a component like a nested list or grouped table. You can use a RunJS query to transform the data: + +```js +// Trigger the query and retrieve the data +await queries.getProducts.run(); +const products = queries.getProducts.getData(); + +const grouped = {}; + +products.forEach(product => { + const category = product.category; + if (!grouped[category]) { + grouped[category] = []; + } + grouped[category].push(product); +}); + +// Sort each category group by stock in descending order +for (const category in grouped) { + grouped[category].sort((a, b) => b.stock - a.stock); +} + +return grouped; +``` + +This is how you can use RunJS or RunPy queries to transform data in ToolJet. Keep in mind that while writing code offers flexibility, it can also introduce complexity. Always consider performance implications when writing complex transformations. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-theme.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-theme.md new file mode 100644 index 0000000000..d67eb71575 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/custom-theme.md @@ -0,0 +1,121 @@ +--- +id: custom-theme +title: Custom Theme +--- + +ToolJet supports Custom Themes at the workspace level, giving teams complete control over the look and feel of their applications. With this feature, you can define and manage multiple themes and apply them across your apps in a consistent and reusable way. + +Each workspace can have one or more themes configured, and any application within that workspace can use any of the defined themes. This helps in maintaining visual consistency across applications, improves brand alignment, and enhances user experience. + +## What is a Custom Theme? +A Custom Theme allows you to customize the UI components of your ToolJet apps by configuring a set of visual styles such as: + +- Brand Colors (Primary, Secondary, Tertiary) + +- Text colors + +- Border and surface styling + +- System state colors (e.g., error, success) + +Configure custom theme + +You can configure these settings for both light and dark modes, and instantly preview changes using the built-in preview panel. + +Each theme includes configurable values like: + +- Primary: Used for buttons, links, focus states, and other interactive elements. +- Secondary (optional): For additional visual hierarchy. +- Tertiary (optional): Useful for complex color relationships. + +Once saved, the theme becomes available for use in any app under the workspace. + +Configure custom theme + +## Why Use Custom Themes? +Custom Themes empower your organization by: + +- Brand consistency: Align your internal tools with your company’s visual identity. + +- Reusability: Define once, use across multiple apps. + +- Customization: Update the look of all your apps in one go by editing the theme. + +- Collaboration: Teams working on different apps can maintain a unified design system. + +This is especially useful for teams with apps across different environments (e.g., internal tools, client-facing apps, admin panels) where each might need a slightly different yet consistent visual identity. + +## How to Use Custom Themes + +Using Custom Themes in ToolJet involves two simple steps β€” **creating the theme** and **applying it to your applications**. + +### 1. Create a Custom Theme + +- Go to your **Workspace Settings**. +- Click on the **Custom Theme** tab. +- Click **Create new theme**. +- Configure your theme styles: + - Set your **Brand colors**: Primary, Secondary, Tertiary + - Define **Text**, **Border**, **System status**, and **Surface** colors + - Choose styles for both **Light** and **Dark** modes +- Click **Save** once you're done. + + You can create multiple themes as per your needs β€” for different teams, environments, or clients. + +### 2. Apply the Theme to Your Application + +- Open the app where you want to use the theme. +- Click the **Settings icon** in the **left sidebar** to open **Global Settings**. +- Scroll down to the **Theme** section. +- You’ll see a dropdown showing the currently selected theme (usually the default). +- Click the dropdown to view and select from all your configured themes. + +Configure custom theme + +Once selected, your app will now use the chosen theme as the base style for components. + +### 3. Use Theme Styles in Your Components + +To make your components adopt the theme styles: + +- Select a component in the app canvas. +- Go to the **Style** tab of the component. +- Wherever color can be set (background, border, text), you’ll see a **Theme** option next to the color picker. Once selected you'll see the list of theme colors such as Brand/Primary, Brand/Secondary, Text/Primary, etc. + +These options map directly to what you configured during theme setup. + + +Configure custom theme + + +Once components are styled using theme options, changing the theme from Global Settings will instantly update all those components, making your app visually consistent and easy to update. + +## Scenarios +Here are some scenarios where custom themes shine: + +- Brand-specific apps: Create different themes for different brands/clients your company serves. + +- Dark & light mode toggle: Provide a seamless visual switch for end-users between light and dark modes. + +- Multi-team organizations: Let each team within your org create and maintain their own theme without affecting others. + +## Example + +Here’s an example showing how an application interface looks before and after applying a custom theme. + +### Before (Default Theme) + +This is the default ToolJet UI without any custom theme applied. It uses the standard branding and neutral colors. +Configure custom theme + +### After (Custom Theme Applied) + +Configure custom theme + +This is the same application after applying the "Coral" custom theme. Notice the button color, primary accents, and overall visual alignment now reflect the chosen palette. + + + +By simply configuring a theme once at the workspace level, you can instantly apply a fresh look across all apps, improving usability, clarity, and brand identity. + + diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/debugging/inspector.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/debugging/inspector.md new file mode 100644 index 0000000000..9d5640f86f --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/debugging/inspector.md @@ -0,0 +1,76 @@ +--- +id: inspector +title: Inspecting Values +--- + +ToolJet's Inspector is a built-in utility that provides real-time visibility into the data and state of your application. With Inspector, developers can quickly diagnose issues, understand the flow of data, and ensure that all components, queries, and variables are functioning as intended. + +Inspector is accessible via the left sidebar in the App Builder. It is divided into six main sections, each offering a different perspective into your application’s runtime environment: + +- [Queries](#queries) +- [Components](#components) +- [Globals](#globals) +- [Variables](#variables) +- [Page](#page) +- [Constants](#constants) + +## Accessing Inspector + +Values that are displayed inside the inspector can be referenced in other components and queries to create interactive applications. You can access the current state of components, queries, variables, page handle, and more directly from the inspector. + +You can refer to a value using the dot notation (e.g., `{{components.numberInput1.value}}`), or hover over any property in the inspector to copy its reference path. This makes it easy to connect components, reuse data, and configure logic throughout your application without writing extra code. + +For example, let's say you have a **Table** displaying a list of users, and you want to fetch the details of a particular user when they are selected. You can refer to the selected row's data using the reference path in the Inspector. + +You can either type this path manually or hover over the property in the Inspector to copy its path directly. This path can then be used in your query to refer to the value. Additionally, you can add an event handler to the table to automatically run this query whenever a user is selected. + +Events Architecture Diagram + +### Queries + +Under the Queries section, you can inspect the specifics of any query you’ve created. The data for a query is only visible after the query has been executed. This allows you to verify the output and troubleshoot any issues with data retrieval or manipulation. The Inspector exposes the following properties for each query: + +- **isLoading** – A boolean indicating whether the query is currently in progress. This can be used to control the loading state of components that depend on the query's result. +- **data** – The transformed data returned by the query. +- **rawData** – The original response fetched from the data source. +- **id** – A unique identifier automatically assigned to every query in ToolJet. + +Refer to the [Binding Data with Component](/docs/beta/app-builder/connecting-with-data-sources/binding-data-to-components) guide to learn how to bind the query data to the component. + +### Components + +The Components section provides a detailed view of each component present on your app’s canvas. You can see the current state, properties, and values of each component, helping you understand how data flows through your application and how components interact with each other. Only the components of the current page are visible in this section. + +Each component exposes a different set of states and CSAs based on its functionality. For example: +- A **Text** component exposes a `text` state and a `setText` CSA. +- A **Checkbox** component exposes a `label` state and a `setValue` CSA. + +To learn more about a specific component and its exposed properties, refer to the [individual component](/docs/beta/app-builder/building-ui/component-library) guide. + +Refer to the [Accessing Component State](/docs/beta/app-builder/building-ui/component-state) guide to learn how to use component state. + +### Globals + +By using the Globals properties in the Inspector, you can view various details about your application and its environment, such as: +- **Current User** - Information about the logged-in user, including email, name, avatar, groups, roles, and SSO details. Useful for building role-based UI or showing personalized content. +- **Environment** - Indicates the current ToolJet environment β€” development, staging, or production. +- **Mode** - Indicates whether the app is opened in the editor or not. +- **Theme** - Refers to the active UI theme (light or dark). You can use this to dynamically style components based on the selected theme. +- **URL Params** - These are query parameters appended to the page URL, commonly used to pass data between pages. + +### Variables + +The Variables section in the Inspector lets you view all app-level variables available within the current application. These variables can be used to store and share data across components and queries. You can inspect their current values here, making it easier to debug and manage dynamic behavior in your app. + +### Page + +The Page section displays page-specific properties (such as page handle and name) and page-level variables. Unlike app-level variables, page-level variables are only accessible within their respective pages. + +- **handle** - The page handle is a unique identifier used to generate a shareable URL for the page. It is appended as a slug to the end of your application URL. +- **id** - A unique identifier automatically assigned to every page in ToolJet. +- **name** - The display name of the page, shown in the app's navigation menu. Set by the user. +- **variables** - List of page level variables in the key-value pair. + +### Constants + +Workspace Constants are predefined values that you can use across different applications within your workspace. They are useful for storing frequently used data such as API URLs, configuration settings, or sensitive information like API keys and database credentials. In the inspector, you can view all constants as key-value pairs, secret constant values are masked for security. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/debugging/logs.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/debugging/logs.md new file mode 100644 index 0000000000..b85bc83923 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/debugging/logs.md @@ -0,0 +1,65 @@ +--- +id: understanding-logs +title: Understanding Logs +--- + +Debugging is a critical part of building applications, and ToolJet makes it easier with a built-in Debugger that tracks and displays logs in real time. Whether it’s a query success or failure, or a component malfunction, the debugger logs will help you get to the root of the problem quickly. + +This guide walks you through making the most of ToolJet’s logs, with practical examples that explain why they matter and how to use them effectively. + +## How Logs Work + +ToolJet captures real-time events and organizes them in the debugger panel. + +When you’re in the app-builder, you can look for the Debugger icon on the left sidebar. Click it to open the debugger panel. This panel becomes your main console for inspecting the query execution results (success/failure) +and component-level issues. + +Events Architecture Diagram + +## Custom Logs + +In ToolJet, you can use custom log methods to capture errors, debug info, and runtime events in your app. These functions work similarly to JavaScript’s console.log() but offer clearer intent and structured logging. + +### Log Errors + +Logs an error. Useful for failed API calls, exceptions, or critical issues. + +```js +actions.logError("API failed"); +``` + +### Log Information + +Logs informational messages. Use for successful actions or state changes. + +```js +actions.logInfo("User logged in"); +``` + +### Log Messages + +Generic log for debugging or checkpoints. + +```js +actions.log("Reached step 2"); +``` + +## Use Case + +### Debugging Queries + +Let’s say you’re building an app and have integrated a REST API to fetch products. You’ve connected this query to a **Table** component, but when you run it, the data doesn’t show up. To troubleshoot this, open the debugger and navigate to the Logs tab. There, you’ll find detailed information about the query execution, including: +- Whether the query succeeded or failed +- Any error messages returned +- The request payload and response body +- The status code returned by the server + +This information helps you identify what went wrong and where to start troubleshooting. + +### Troubleshooting Component Related Issues + +Let’s say you’ve fetched user data from a database using a query, and connected it to a table component. The query runs without errors, but the table still appears empty. To investigate this, open the debugger and head to the Error Logs tab. Here, you’ll find error logs related to the component’s behavior, including: +- Errors related to misconfigured properties +- Invalid expressions used in bindings + +These logs help you determine whether the issue stems from component configuration or its interaction with the query result, making it easier to fix problems and get your UI working as expected. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/events/event-triggers.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/events/event-triggers.md new file mode 100644 index 0000000000..120e2daed8 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/events/event-triggers.md @@ -0,0 +1,40 @@ +--- +id: event-triggers +title: Setting Up Events +--- + +Events define how your app should respond when a user interacts with a component or when a specific system condition is met. Whether it's clicking a **Button** component, selecting an item from a **Dropdown**, or completing a query, events let you tie in logic that makes your app interactive and reactive. + +You can use event triggers to run queries, update variables, show alerts, navigate to different pages, and more. Each event can be configured to trigger one or more actions in sequence, allowing you to build complex logic flows easily. Refer to the individual [component guide](/docs/beta/app-builder/building-ui/component-library) to see the full list of supported events, and check out the [Action Reference](/docs/category/actions-reference) for all available actions. + +## Configuring an Event Handler + +Suppose you're building a feedback form using a **Form** component that submits user input to a database whenever the user clicks on the submit button. To achieve this, you can configure the submit button to trigger a query when clicked. + +First, create a query and name it *addData*. This query inserts **Form** values into the database. Then, configure the **Button** with the following event handler: +- Event: **On Click** +- Action: **Run Query** +- Query: **addData** + +Events Architecture Diagram + +This setup ensures that every time the button is clicked, the **Form** data is sent to your database. + +Events Architecture Diagram + +## Configuring Sequential Event Handler + +Continuing the previous example. After submitting the form, you may want to update the UI by fetching the latest data. To do this, create a new query and name it *fetchData* that retrieves updated records from the database. + +Next, configure an event handler that runs sequentially after the *addData* query succeeds: +- Event: **Query Success** +- Action: **Run Query** +- Query: **fetchData** + +Events Architecture Diagram + +This setup ensures that the *fetchData* query is triggered automatically when the *addData* query completes successfully. + +Events Architecture Diagram + +Whether it's submitting a form, running a query, or updating your UI, events and actions let you define dynamic, logic-driven behavior without writing backend code. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/events/overview.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/events/overview.md new file mode 100644 index 0000000000..fc4dafde8e --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/events/overview.md @@ -0,0 +1,41 @@ +--- +id: overview +title: Overview +--- + +In ToolJet, you can build dynamic, logic-driven applications using Events, Actions, Variables, and Component-Specific Actions (CSAs). These features let you define how your app responds to user interactions and system events without writing any backend code. Each component has a unique set of available events and CSAs based on its functionality. Refer to the [individual component](/docs/beta/app-builder/building-ui/component-library) guides for more details. + +## Events + +Events are triggers that respond when certain conditions are met β€” either through user interaction (for example, clicking a **Button** component or selecting a **Dropdown** option) or system-level changes (for example, the completion of a query). You can configure events using event handlers on components or queries. Each handler defines the trigger and the actions that should follow. + +For example, when a user clicks a **Button**, it can trigger a query to refresh data. Once that query completes, a second event can run to show a confirmation alert. + +Events Architecture Diagram + +## Actions + +Actions specify the outcome when an event is triggered. ToolJet supports a wide range of actions such as running queries, showing alerts, navigating between pages, copying text to the clipboard, and more. You can configure actions directly within event handlers or [dynamically using JavaScript](/docs/beta/app-builder/custom-code/control-components) via RunJS queries. For a complete list of available actions, refer to the [Action Reference](/docs/category/actions-reference) guide. + +Events Architecture Diagram + +## Component Specific Actions (CSAs) + +Component-Specific Actions (CSAs) are built-in functions that allow you to control a component's state and behavior at runtime. Each component has its own set of CSAs based on its capabilities. For example, a **Text** component supports the `setText()` action, while a **Radio Button** component offers `selectOption()`. + +Events Architecture Diagram + +## Variables + +Variables let you store and manage data either across your entire application or within specific pages. They're essential for maintaining state, controlling logic, and creating personalized user experiences. +ToolJet supports the following types of variables: + +- App-level variables – accessible throughout the entire app. +- Page-level variables – scoped to a specific page. + +Events Architecture Diagram + +

+ +In addition, ToolJet provides built-in [exposed variables](/docs/beta/app-builder/building-ui/component-state) for components and queries, which represent their current runtime state. + diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/events/use-case/csa.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/events/use-case/csa.md new file mode 100644 index 0000000000..0807e915ad --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/events/use-case/csa.md @@ -0,0 +1,40 @@ +--- +id: csa +title: Controlling Component State +--- + +Component-Specific Actions (CSAs) are built-in functions that allow you to control the component state and behavior in the application. Each component has its own set of CSAs based on its capabilities. + +For example, a Text component supports the `setText()` action, while a Radio Button component offers `selectOption()`. + +You can trigger these actions via event handlers or by using expressions in your queries. Refer to the individual [component guide](/docs/beta/app-builder/building-ui/component-library) for a complete list of supported CSAs. + +## Controlling Components + +Suppose you've used a **Form** component to build a feedback form and want to clear all inputs after the data is submitted to the database. ToolJet provides a `resetForm` function to help with this, which can be triggered in two ways: +- [Using an Event Handler](#using-an-event-handler) +- [Using a JS Expression in a Query](#using-a-javascript-expression-in-a-query) + +### Using an Event Handler + +Suppose you have a query named **addData**, which is being used to insert the form data into the database. To clear the **Form** using an event handler, add the following configuration to your **addData** query: +- Event: **Query Success** +- Action: **Control Component** +- Component: **feedbackForm** (Select your **Form** component from the dropdown) +- Actions: **Reset Form** + +Events Architecture Diagram

+ +This setup ensures that the **Form** component is cleared automatically when the **addData** query completes successfully. + +Events Architecture Diagram + +### Using a JavaScript Expression in a Query + +Alternatively, you can reset the **Form** directly within your query by appending this JavaScript expression: + +```js +await components.feedbackForm.resetForm() +``` + +Component-Specific Actions give you precise control over how components behave at runtime, making your applications more interactive and responsive. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/events/use-case/page-nav.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/events/use-case/page-nav.md new file mode 100644 index 0000000000..29b6bc9ac1 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/events/use-case/page-nav.md @@ -0,0 +1,43 @@ +--- +id: page-nav +title: Implementing Navigation Using Actions +--- + +ToolJet offers page navigation out of the box. For any custom navigation needs, such as implementing a navigation bar, you can use event handlers and actions. You can also pass query parameters during navigation, making it easy to share context between pages. + +## Building Custom Navigation Menu + +Follow these steps to build a custom navigation menu: + +1. Add a container to serve as your navigation wrapper. +2. Place icons, text or button components inside the container for each page you want to link to. +3. For each navigation item: + - Select the component (icon or text). + - Add an event handler. + - Event: **On click** + - Action: **Switch page** + - Page: *Select the target page from the dropdown* + +Events Architecture Diagram

+ +Once configured, clicking on a navigation item will take the user to the corresponding page. + +Events Architecture Diagram + +## Passing Data Between Pages + +Suppose you're building a ticket management system where Page 1 displays a list of all tickets, and clicking on a ticket redirects the user to Page 2, which shows the details of the selected ticket. Here's how to set it up: + +1. On Page 1, display all the tickets using a **Table** component. +2. Add an event handler to the table: + - Event: **Row clicked** + - Action: **Switch page** + - Page: **Page 2** *(Select the ticket details page.)* + - Query parameters: + - **Key**: `ticketId` + - **Value**: `{{components.ticketTable.selectedRow.ticket_id}}` +3. On Page 2, design the UI to display the ticket details. +4. Use the query parameter to fetch or display the selected ticket's data: + - Reference it with: `{{globals.urlparams.ticketId}}` + +This setup enables users to click on a ticket in the table and seamlessly navigate to a detailed view of that specific ticket, with the necessary data passed between pages using query parameters. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/events/use-case/variables.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/events/use-case/variables.md new file mode 100644 index 0000000000..cd006e241a --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/events/use-case/variables.md @@ -0,0 +1,69 @@ +--- +id: variables +title: Setting Variables +--- + +Variables let you store and manage data across your entire application. You can use them to manage component state, control logic, store user input or to create a personalized user experiences. By setting a value once in a variable, you can reuse it across different parts of your app. This makes your app easier to build and maintain, without needing to store everything in a database. + +ToolJet supports two types of variables: + +- **App-level variables** are available across all pages in your app. To set an app-level variable, use the `setVariable` action. +- **Page-level variables** are only available on the page where they are created. To set a page-level variable, use the `setPageVariable` action. + +## Set Variables + +### App Level Variable + +Suppose you are building a multi-page application where, on the first page, you ask the user for their name and want to use it in the other pages. Here’s how to do it: +1. Add a **Text Input** component to collect the user’s name. +2. Add a **Button** component to submit the name. +3. Set up this event handler on the **Button** component: + - Event: **On Click** + - Action: **Set variable** + - Key: `username` *(Variable name of your choice.)* + - Value: `{{components.usernameinput.value}}` *(Refer to the user input in the **Text Input** component.)* + +Events Architecture Diagram

+ +When the user clicks the **Button** component, their name will be stored in the app-level variable `username`. You can access this variable anywhere in your app with this syntax: + +```js +{{variables.username}} +``` + +### Page Level Variable + +Now, suppose you have a **Form** in your application and want to store the user’s contact number only on that page when they submit the **Form**. To do this, set this event handler on the **Button** component: + +- Event: **On Click** +- Action: **Set page variable** +- Key: `contact` *(Variable name of your choice.)* +- Value: `{{components.feedbackForm.data.contact.value}}` *(Refer to the user input in the **Number Input** component.)* + +When the user clicks on the **Button** component, their contact number will be saved in a page-level variable named `contact`. This variable can only be used on that specific page with this syntax: + +```js +{{page.variables.contact}} +``` + +## Unset Variables + +### App Level Variables + +In your multi-page app, you may want to clear (unset) the `username` variable when the user clicks the **Button** component named "Finish" on the last page. To do this, set the following event handler on the **Button** component: + +- Event: **On Click** +- Action: **Unset variable** +- Key: `username` *(Variable name you want to unset.)* + +### Page Level Variables + +In your **Form** app, you might want to clear the page-level `contact` variable when the user clicks the **Button** component named "Next Page". To do this, set this event handler on the **Button** component: + +- Event: **On Click** +- Action: **Unset page variable** +- Key: `contact` *(Variable name you want to unset.)* + +:::info +You can also manage variables using code. Refer to the [Manage Variables](/docs/app-builder/custom-code/managing-variables) guide for more information. +::: \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/import-export-apps.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/import-export-apps.md new file mode 100644 index 0000000000..cd735ac09a --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/import-export-apps.md @@ -0,0 +1,61 @@ +--- +id: importing-exporting-applications +title: Import and Export Applications +--- + +This documentation explains the process of exporting and importing applications in ToolJet. + +
+ +## Exporting Applications + +- Navigate to the dashboard. +- Click on the settings icon located in the top right corner of the application. +- Click on the **Export app** button. + +
+ Export App Button +
+ +- If you select `Export All`, all the versions of the application will be exported in JSON format. If you select `Export selected version`, only the selected version will be exported in JSON format. +- Ticking the `Export ToolJet table schema` checkbox will also export the related ToolJet Database table schemas with your application. In this case, when you import the application in a workspace, the related ToolJet Database tables will also be created. + + +
+ Export App Options +
+ +
+ +
+ +## Importing Applications + +- Navigate to the dashboard. +- Click on the ellipses on the **Create new app** button and select `Import`. + +
+ Import App Button +
+ +- After clicking on `Import`, choose the relevant JSON file that you previously downloaded during the application export process. + + +
+ Select App To Import +
+ +
+ +## Module Behavior During Application Import and Export + +**Import**: + +- When you import an application, the platform automatically checks for any existing modules with matching names in your workspace or instance. If a module with the same name already exists, the imported application connects to the existing module, avoiding duplication. +- However, if no matching module is found, the platform creates a new module from the imported JSON file. +- This approach ensures that your application imports smoothly while maintaining consistency and preventing redundant modules. + +**Export**: + +- When you export an application, all associated modules linked to the application are automatically included in the export. +- This ensures that any reusable components or features built as modules are preserved and can be seamlessly imported along with the app into any other workspace. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/import-libraries/import-external-lib-js.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/import-libraries/import-external-lib-js.md new file mode 100644 index 0000000000..c79035c2f7 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/import-libraries/import-external-lib-js.md @@ -0,0 +1,125 @@ +--- +id: runjs +title: Using RunJS +--- + + +ToolJet allows you to use external JavaScript libraries such as Compromise for natural language processing or PapaParse for parsing CSV data in your application using RunJS queries. This helps you avoid writing complex logic from scratch. + +This guide walks you through the process of importing and utilizing these libraries effectively. + +## Choosing Libraries + +You can import various JavaScript libraries using their Content Delivery Network (CDN) links. Find the CDN links for your desired open-source projects on [jsDelivr](https://www.jsdelivr.com/). + +## How to Import Libraries + +Let’s walk through how to import libraries using RunJS. For example, we’ll use: + +- [Compromise](https://github.com/spencermountain/compromise): for natural language processing +- [PapaParse](https://www.papaparse.com/): for parsing CSV data + +### Create a RunJS Query + +Open the query panel and create a new **RunJS** query. + +### Add the Following Code Snippet + +```js +// Function to add script dynamically +function addScript(src) { + return new Promise((resolve, reject) => { + const scriptTag = document.createElement('script'); + scriptTag.setAttribute('src', src); + scriptTag.addEventListener('load', resolve); + scriptTag.addEventListener('error', reject); + document.body.appendChild(scriptTag); + }); +} + +try { + await addScript('https://cdn.jsdelivr.net/npm/compromise@13.11.3/builds/compromise.min.js'); + await addScript('https://cdn.jsdelivr.net/npm/papaparse@5.4.1/papaparse.min.js'); + await actions.showAlert("success", "Compromise and PapaParse imported"); +} catch (error) { + console.error(error); +} +``` + +After adding the code, click on the **Run** button in the query panel. An alert will appear with the message "Compromise and PapaParse imported". + + Use FlattenJS +:::tip +Enable the **Run this query on application load** option in the query settings to make the libraries available throughout the application as soon as the app is loaded. +::: + +## Use Cases + +Let’s look at how you can apply these libraries in real-world use cases. + +### Extracting Action Items from Meeting Notes using Compromise (NLP) + +Let's say you are building an internal project management tool where users paste raw meeting notes. You want to auto-extract action items, dates, and team names. You can use the following code to process the notes using NLP: + +```js +const notes = nlp("Met with John, Priya, and Marcus from the marketing team on Thursday. Discussed launch strategy for the Q3 campaign. Priya will draft the blog post by next Tuesday. John to prepare budget estimates. Marcus will handle email outreach by Friday. Next sync on July 10th."); + +const people = notes.people().out('array'); +const actions = notes.sentences().filter(s => s.has('#Verb')).out('array'); + +return { people, actions }; +``` + +Preview the output in the query manager or click **Run** in the query panel to see the output as shown below. + + + Use compromise + +### Bulk Upload Employee Data into an Employee Directory + +Let’s say your HR team maintains employee records in spreadsheets and wants a way to import this data quickly into your internal Employee Directory application. You can use the following code to clean up the data: + +```js +const csvData = components.filepicker1.file[0].content; + +const parsedData = Papa.parse(csvData, { + header: true, + skipEmptyLines: true +}); + +return parsedData; +``` + + Use Compromise + +## Built-in JavaScript Libraries + +ToolJet comes with some essential JavaScript libraries preloaded in the RunJS environment, so you don’t need to import them manually: +- [Moment.js](https://momentjs.com/docs/) – for date/time formatting and manipulation +- [Lodash](https://lodash.com/docs/) – for working with arrays, objects, and collections +- [Axios](https://axios-http.com/docs/intro) – for making HTTP requests + +You can use these libraries directly in RunJS to simplify your logic, transform data, or integrate with APIs. + +Example: + +```js +// Format Timestamps for UI Display +const raw = '2025-06-05T15:42:00Z'; +return moment(raw).format('MMM D, YYYY, h:mm A');// "Jun 5, 2025, 9:12 PM" + +// Deep Comparison of Records with Lodash +const a = { name: 'Alice', dept: { id: 1, name: 'HR' } }; +const b = { name: 'Alice', dept: { id: 1, name: 'HR' } }; + +return _.isEqual(a, b); // true + +// Posting JSON Data with Error Handling +axios.post('https://api.company.com/inventory', { + name: 'Laptop', + quantity: 10, +}).then(res => res.data) + .catch(err => console.error(err.response.data)); +``` + +Use RunJS to easily import and leverage external JavaScript libraries in your ToolJet app for advanced data processing and logic. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/import-libraries/import-external-lib-py.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/import-libraries/import-external-lib-py.md new file mode 100644 index 0000000000..5fbeb26efd --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/import-libraries/import-external-lib-py.md @@ -0,0 +1,126 @@ +--- +id: runpy +title: Using RunPy +--- + +In this guide, we will learn to import Python libraries in your applications. + +If you are new to using RunPy queries, check out our [guide](/docs/data-sources/run-py/) on how to get started with RunPy. ToolJet supports installing libraries using **micropip**. Check out [this](https://pyodide.org/en/stable/usage/packages-in-pyodide.html) documentation for a list of supported libraries. + +## Installing Python Packages + +In ToolJet, you can write Python code for custom logic, and for intensive data processing tasks, you can use Python libraries without needing to write complex code from scratch. Here’s how you can use them: + +You can use **micropip** to install packages like Pandas and NumPy as follows: + +```python +import micropip +await micropip.install('pandas') +await micropip.install('numpy') +``` + +Trigger this RunPy query once to install these packages. + + Installing py modules + +:::tip +Enable the **Run this query on application load** option in the query settings to make the libraries available throughout the application as soon as the app is loaded. +::: + +## Use Cases + +### Parse CSV Data + +Let’s say you want users to upload a CSV and view the parsed output. Here’s how you can use pandas and Python’s CSV module. Create a RunPy query to parse CSV data using `StringIO`, `csv`, and `Pandas` module. + +```python +from io import StringIO +import csv +import pandas as pd + +scsv = components.filepicker1.file[0].content + +f = StringIO(scsv) +reader = csv.reader(f, delimiter=',') + +df = pd.DataFrame(reader) + +print(df.info()) +print(df) +``` + + Installing py modules + +- Add a File Picker to your app and change the file type to CSV. +- In the File Picker’s event settings: + - Event: On File Loaded + - Action: Run Query β†’ choose your RunPy script +- Upload a CSV file. When you trigger the RunPy query, it will parse the data and output it in the browser console + +### Prompt Preprocessing for AI APIs + +When building apps that integrate with AI APIs (like OpenAI, Cohere, or HuggingFace), you often need to send long-form text inputsβ€”like meeting transcripts, user feedback, or document excerpts to the API. However, many AI APIs have input size limitations (e.g., 4,096 tokens for GPT-3.5), and they often work best when the input is clean and concise. + +So, before sending the data, you may want to: +- Clean and normalize the text (remove line breaks, extra spaces, non-ASCII characters) +- Chunk the text into API-safe sizes (e.g., 500 characters or 300 words) +- Optionally, remove irrelevant sections (like headers, boilerplate, or disclaimers) + +Here's an example of how to do this preprocessing step using regular expressions (`re`): + +```python +import re + +# Get raw text from a multi-line input component (like a long form or a textarea) +raw_text = components.textarea1.text + +# 1. Clean the text +cleaned = re.sub(r"\s+", " ", raw_text).strip() + +# 2. Chunk the cleaned text into slices of 500 characters each +chunks = [cleaned[i:i+500] for i in range(0, len(cleaned), 500)] + +# Output the cleaned and chunked data +print({"chunks": chunks}) +``` + +
+ +Input - Meeting notes + +We discussed the Q3 roadmap and agreed to prioritize performance improvements. There were also suggestions to improve the onboarding experience. + +Action items: + - Alice will investigate caching issues and report back by next Monday. + - Bob will look into UI responsiveness across different screen sizes. + - Carol will start planning for the user feedback survey in Q4. + +Additional Discussion: +- A proposal was made to reduce build times by moving to a newer CI/CD system. +- Concerns were raised about backend API reliability and latency issues. +- Data team mentioned they are behind on setting up the new dashboard pipeline. + +Next Steps: +- Weekly check-ins will resume starting next Tuesday. +- Each team will submit a biweekly progress report. +- Planning for the product demo scheduled for November 15th will start next week. + +
+ + +
+ +Output - Chunked data + +```json +{ + "chunks": [ + "We discussed the Q3 roadmap and agreed to prioritize performance improvements. There were also suggestions to improve the onboarding experience. Action items: - Alice will investigate caching issues and report back by next Monday. - Bob will look into UI responsiveness across different screen sizes. - Carol will start planning for the user feedback survey in Q4.", + + "Additional Discussion: - A proposal was made to reduce build times by moving to a newer CI/CD system. - Concerns were raised about backend API reliability and latency issues. - Data team mentioned they are behind on setting up the new dashboard pipeline. Next Steps: - Weekly check-ins will resume starting next Tuesday. - Each team will submit a biweekly progress report. - Planning for the product demo scheduled for November 15th will start next week." + ] +} +``` + +
+ diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/create-module.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/create-module.md new file mode 100644 index 0000000000..e11495d51d --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/create-module.md @@ -0,0 +1,41 @@ +--- +id: create-module +title: Creating a Module +--- + +A module is a reusable interface that can be imported into applications. It allows you to build complex functionality once and reuse it across multiple applications without having to rewrite code each time. This guide explains how to create a module in ToolJet. + +Follow these steps to get started with creating a module: + +- Go to the **Modules** section from the ToolJet dashboard. + + + +- Click on the **Create Module** button. In the popup, enter a name for the module. +Create Module + +- Add components, queries, and actions just like you would in a normal app. place and resize your components on the **Module container**. + +Module Builder + +- Click on the module container to open the properties panel Here you can see the **Input** and **Output** that help in defining how the module communicates with the parent application. These settings define how the module communicates with the parent app, making it easier to build dynamic, reusable modules that work across different data sets and queries. + +Properties Panel + + + +Please refer to the **[Input and Output](/docs/beta/app-builder/modules/input-output)** documentation for detailed information on how to manage the inputs and outputs of a module. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/data-flow.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/data-flow.md new file mode 100644 index 0000000000..db23999f2c --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/data-flow.md @@ -0,0 +1,79 @@ +--- +id: data-flow +title: Data Flow +sidebar_label: Data Flow +--- + +This section explains how data flows work between the parent application and the module. + +There are two types of data flows between the parent application and the module: +- **From Parent to Module** +- **From Module to Parent** + +## From Parent to Module + +When you add a module to an app: +- The parent can pass input values to the module. +- These values can be used anywhere inside the module (UI, queries, logic). + +Data flow from parent to module + +For example, let's say you want to pass the **userData** from the parent application to the module. Here's what happens: + +```js +// Passed from parent +{ + "userData": {{ queries.getUser.data }} +} +``` +You can access these values in the module using the `input` object. For instance, to access the userData, you'd use `{{input.userData}}`. + +```js +// Consumed in module +{{input.userData}} +``` + +## From Module to Parent + +The module can send data back to the parent using outputs: +- Output values are evaluated inside the module. +- The parent application reads the output values using the components object. + +Data flow from module to parent + +For example, let's say you have a module that submits a form and sends the submitted data back to the parent app. Here's what happens: + +```js +// Sent from module +{ + "submittedFormData": {{ components.form.formData }} +} +``` + +You can access these values in the parent application using the `components` object. For instance, to access the submittedFormData, you'd use `{{components..submittedFormData}}`. + +```js +// Received in parent app +{{components..submittedFormData}} +``` + +## Query Execution Options + +You have two options for managing queries in modules: + +### Parent-triggered Queries +- Define queries inside the module. +- From the parent application, trigger them using module Input query. +- Use this when you want full control from the app. + + + +### Self-contained Queries +- Let the module handle its own queries internally (e.g., run on load or button click inside the module). +- These queries remain invisible to the parent app. +- Use this for fully encapsulated behavior. + + + +Choose based on whether the parent should control the module behavior or let the module manage itself. + diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/import-export.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/import-export.md new file mode 100644 index 0000000000..7320518893 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/import-export.md @@ -0,0 +1,51 @@ +--- +id: import-export-modules +title: Import and Export Modules +--- + + +ToolJet allows you to export and import modules, making it easy to share, reuse, or migrate modules across different workspaces. + +This guide walks you through the steps to export an existing module and import it into another workspace. + +## Exporting Modules + +- Navigate to the **Modules** tab from the dashboard. +- Click on the menu icon of the module card you want to export. +- Click on the **Export module** button. + + Export Module Button + +- The selected module will be exported as a JSON file. + +- This file will include all the components, logic, queries, and properties defined within the module. + +Once downloaded, you can use this file to import the module into any other ToolJet workspace. + + +## Importing Modules + +- Navigate to the **Modules** tab. +- Click on the menu icon next to the **Create new module** button in the top right corner. + + + Import Module Button + + +- Choose the module JSON file that you previously exported. + +Once imported, the module will appear in your modules list and can be used across your applications. + + +## Module Behavior During Application Import and Export + +**Import**: + +- When you import an application, the platform automatically checks for any existing modules with matching names in your workspace or instance. If a module with the same name already exists, the imported application connects to the existing module, avoiding duplication. +- However, if no matching module is found, the platform creates a new module from the imported JSON file. +- This approach ensures that your application imports smoothly while maintaining consistency and preventing redundant modules. + +**Export**: + +- When you export an application, all associated modules linked to the application are automatically included in the export. +- This ensures that any reusable components or features built as modules are preserved and can be seamlessly imported along with the app into any other workspace. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/input-output.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/input-output.md new file mode 100644 index 0000000000..b10f67c82f --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/input-output.md @@ -0,0 +1,100 @@ +--- +title: "Configuring Inputs and Outputs" +id: "input-output" +--- + +Modules have their own inputs and outputs which enable them to interact with the parent application. You can configure inputs and outputs of a module from the properties panel. + +## Inputs +Inputs allow the parent application to send data or trigger actions inside the module. You can access inputs in the module using the **input** object. + +### Input Types +- **Data**: Use this to pass values like string, number, boolean, array, or object. +- **Query**: Use this to trigger queries inside the module from the parent app. + +Input Types + +### How to Define Inputs +In the properties panel, go to the **Inputs** section and click **Add new**. Then, provide the following: + +#### Data Input + +For **Data** inputs, define the following parameters: + +- **Name**: A unique name for the input +- **Type**: Select **Data** +- **Default Value** (optional) + +For example, to pass a form title from the parent application, create an input with the name **formTitle** and type **Data**. You can also set a default value. + +Module Input + +To use this input in the module, use the following syntax: + +```js +{{input.}} +``` + +For our case, we’ll use `{{input.formTitle}}` to access the form title in the component. +```js +{{input.formTitle}} +``` + + +When you import this module into an application, you’ll see the input field in the module settings. If you set the **formTitle** value to **User Details**, the form will display that as the title. + +Input Settings + +#### Query Input + +For **Query** inputs, define the following parameters: +- **Name**: A unique name for the input +- **Type**: Select Query + +For example, if you want to trigger a query named **submitForm** from the parent application, create an input named **submit** and select **Query** as the type. + +Query Input + +To handle this input in the module, add an event handler to a component that should trigger the query. Set the action to **Run Query** and select the query as the input (e.g., submit) from the dropdown. + +Event Handler + +When you import the module into an applications, you’ll see the query input in the module settings. You can then select any available query in the parent application to be triggered. + +Query Input Settings + +## Testing Inputs + +You can test how a module behaves before importing it into an application in the **Test Input** section in the properties panel of the module builder. To do this, open the module's properties panel and scroll to the **Test Input** section. Enter sample values for each input. + +For example, if the module has an input named **formTitle**, you can enter a sample value like **User Details** to see how it's rendered in the module. + +You can also test query inputs by creating a query inside the module builder and triggering it using the defined query input. + +Test Input + +## Outputs + +Outputs allow the module to send data back to the parent app. You can access outputs from the module in the parent application using the components object. + +For example, if you want to send submitted form data back to the parent application, create an output named **formData** and pass the form data **From** the component. + +Module Output + +To access this output in the parent application, use the following syntax: + +```js +{{components..}} +``` + +In this case, use the following reference to access the form data. + +```js +{{components.formModule.formData}} +``` + +Output Consumption + +To explore more on how data flows between modules and apps, check out [Data Flow](/docs/beta/app-builder/modules/data-flow) guide. + diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/overview.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/overview.md new file mode 100644 index 0000000000..42bcc67146 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/overview.md @@ -0,0 +1,22 @@ +--- +title: "Overview" +id: overview +--- + +**Modules** in ToolJet are reusable user interfaces that bundle components, queries, actions, and logic. Think of them as mini-apps you can plug into multiple applications within the same workspace. They help eliminate duplication, ensure consistency, and speed up developmentβ€”especially for repeatable patterns like headers, forms, dashboards, or table views. + +Once created, modules can be reused across your workspace. Any updates you make to a module automatically reflect in every app where it's used. This ensures a single source of truth and significantly reduces maintenance effort. + +## When to Use Modules + +Use modules when: + +- You need a shared UI element, like a customer profile or navigation bar, across multiple apps. +- You’re building repeatable flows such as approval forms, data filters, or input panels. +- You want to simplify complex logic so others can use it with minimal setup. + +Instead of copy-pasting components or logic across apps, modules give you a centralized, reusable way to build features, fully configurable through inputs and outputs to fit any context. + +Module Builder + +To get started with modules, check out the [Create Module](/docs/beta/app-builder/modules/create-module) guide. Once your module is built, you can [use it inside any app](/docs/beta/app-builder/modules/use-module) in your workspace. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/use-cases.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/use-cases.md new file mode 100644 index 0000000000..fc1d6ff5f0 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/use-cases.md @@ -0,0 +1,67 @@ +--- +id: use-cases +title: Use Cases +sidebar_label: Use Cases +--- + +Modules let you reuse blocks of functionality across different applications. They help you save time by reducing repetitive work and make app development faster and more consistent. + +This guide explains how modules work and showcases common use cases where they can improve your development workflow. + +## Common Use Cases for ToolJet Modules + +Here are some scenarios where ToolJet Modules are especially useful: + +### Reusable User Authentication Form + +- Build a user authentication form module using the built-in login block. +- Add this module to any app that requires user login. +- Customize the design and behavior as needed for each app. + +### Standard Address or Contact Input Block + +- Create a reusable module with text fields for address or contact inputs. +- Use this module in apps that collect user contact details. +- Adjust the fields and validation rules to match your needs. + +### File Uploader with Preview and Validations + +- Build a file uploader module using the file upload block. +- Use it in apps that require file submissions. +- Set file type restrictions, size limits, and other validations in the module. + +### Comment or Feedback Box + +- Create a feedback module using the textarea block. +- Include it in apps where users need to leave comments or feedback. +- Customize the placeholder, character limit, and other properties. + +### Order Summary with Pricing Logic + +- Build an order summary module using the table block. +- Add it to apps that need to show order details and pricing. +- Configure columns, data sources, and styles within the module. + +### Notification Banner with Custom Message + +- Create a notification banner module using the alert block. +- Use it in apps that need to show alerts or system messages. +- Customize the text, colors, and display duration. + +### Pagination and Filter Toolbar + +- Build a pagination and filter toolbar module using buttons and dropdowns. +- Use it in apps that display paginated or filtered lists. +- Customize the layout, filters, and button actions. + +### Embedded Chart with Dynamic Data + +- Create a chart module using the built-in chart block. +- Use it in apps that need to visualize data. +- Pass dynamic datasets to the module via inputs or variables. + +### Table with Sorting, Filtering, and Export + +- Build a table module with sorting, filtering, and export features. +- Add it to apps that display structured data. +- Customize functionality to fit your data and user needs. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/using-module.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/using-module.md new file mode 100644 index 0000000000..e8d03c6d0d --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/modules/using-module.md @@ -0,0 +1,28 @@ +--- +title: "Using Modules" +id: "using-modules" +--- + +Once a module is created, it becomes available in the **Module** section of the component panel inside the App-Builder. You can use it like any other component by dropping it on the canvas and configuring it. + + +### Steps to Use a Module: + +1. Open the application in which you want to use a module. + +2. In the component library panel, switch to the **Module** section. + +3. **Drag and drop** the Module onto the canvas. + +Module Builder + +5. You can select the module, to see a list of required **inputs** (if any) defined in the module. + +6. Bind the inputs to values from your data source or configure static values if needed. + +7. If your module has **outputs**, you can reference them using: + ```js + {{components..}} + ``` + +You can reuse the same module multiple times in a single application by dropping it multiple times on the canvas and configuring each instance with different input bindings. diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/overview.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/overview.md new file mode 100644 index 0000000000..4c56833857 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/overview.md @@ -0,0 +1,76 @@ +--- +id: overview +title: Overview +--- + +ToolJet’s app-builder offers an AI-native, low-code environment that helps you build and deploy internal tools quickly without extensive coding knowledge. Whether it’s dashboards, approval workflows, tracking systems, or scheduling apps, you can create powerful tools in minutes. + +Teams across engineering, product, operations, and business can build applications with ease, following four simple steps to get up and running in minutes. + +1. **Build the Interface** – Design visually with drag-and-drop components. + +2. **Connect Your Data** – Integrate with databases, APIs, and third-party services. + +3. **Make It Interactive** – Add actions, events, and logic to bring your application to life. + +4. **Handle Complex Logic** – Use JavaScript anywhere for advanced workflows. + +In this guide, you’ll walk through each step and see how they fit together to bring your application to life. + +
Components Preview
+ + +## 1. Building the Interface + +Start designing your application’s interface with 60+ pre-built components, from **Tables** and **Forms** to **Charts** and **Buttons**. Just drag and drop components onto the canvas, resize, reposition, and fine-tune them through the Properties Panel. + +
Components Preview
+ +Each component comes with built-in styling options. You can customize text, colors, visibility, and more through the Style Panel. These components are dynamic, allowing you to manage state and events just like you would in your favorite frontend framework. + +## 2. Connecting Your Data + +You can connect your application to multiple [data sources](/docs/data-sources/overview) including SQL, NoSQL, vector databases, APIs, spreadsheets, and cloud services. Once connected, you can fetch, update, or manipulate data using queries. + +A query is an action that interacts with your data source, whether it's fetching records, filtering results, or writing data. It acts as the bridge between your UI and your data. + +
Queries Preview
+ + +Use the **Query Panel** to build queries, either with a form-based interface or by writing code/SQL directly. You can use them to fetch data to display in components or to push user inputs back to your database. They can run manually or be triggered using events like page load, user actions on components, or the success or failure of other queries. + +## 3. Making Apps Interactive + +Make your apps interactive by adding events to components, queries, and pages. Events define how your application responds to user actions or specific conditions, bringing interactivity to your application. ToolJet provides a declarative Events system, similar to JavaScript event handlers, allowing you to control application behavior without writing repetitive code. + +
Events Preview
+ +Events can be triggered by various actions such as a button click, form submission, page load, or the completion of a query. When triggered, you can execute actions like running a query, opening a modal, showing a notification, or navigating to another page. + +You can also chain multiple events and actions together, enabling complex multi-step workflows without writing boilerplate code. + +## 4. Handling Custom Logic + +ToolJet makes it easy to build apps without code, but when you need more control, it offers the ability to add custom code to write your logic. You can create JavaScript or Python queries in application builder to perform calculations, transform data, trigger other queries, or update UI components. These snippets have full access to the component’s properties, other queries’ outputs, and the entire app’s state, allowing you to write custom logic for any use cases like conditional behavior, data processing, or dynamic UI updates. + +
Custom Code Preview
+ +This gives developers the ability to handle complex scenarios with code, while still leveraging ToolJet’s low-code environment. + +## Use Cases +With ToolJet, you can build a wide range of internal tools including but not limited to: + +* Inventory management system +* Purchase order tracker +* Customer onboarding portal +* Loan origination and underwriting tool +* Fraud detection dashboard +* Expense approval workflow +* Timesheet tracker +* Employee onboarding app +* Internal ticketing system +* Compliance reporting dashboard +* Sales pipeline tracker +* Digital asset management portal + +From simple dashboards to complex data-driven tools, ToolJet's app-builder helps you build applications with speed and precision. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/walkthrough/row-level-security.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/walkthrough/row-level-security.md new file mode 100644 index 0000000000..a1c8c0dbae --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/walkthrough/row-level-security.md @@ -0,0 +1,61 @@ +--- +id: row-level-security +title: Setup Row Level Security +--- + +Row-level security in ToolJet lets you control which records a user can see or interact with, even when multiple users access the same table. This is useful when you want to restrict access to specific rows based on [custom groups](/docs/user-management/role-based-access/custom-groups/) or [default user roles](/docs/user-management/role-based-access/user-roles#default-user-roles). Row-level security is applied on the server side, ensuring the logic is secure and hidden from the client. + +The below syntax fetches the groups for the current user from the server side. Groups include both custom groups and default user roles like `admin` and `end-user`. + +```bash +{{globals.server.currentUser.groups}} +``` + +*The above syntax will work with all data sources except Run Javascript and Run Python.* + +## Example: Department-Specific View Using a PostgreSQL Data Source + +If you're using PostgreSQL, you can filter records by referencing the user’s group(s) directly in your SQL query. This ensures each user only sees data relevant to them. + +Suppose you're building an internal issue tracking tool for your company. Each department (like β€œEngineering”, β€œHR”, "Marketing") logs and manages its own issues in a shared table with the below structure: + +- Table name: **issue_reports** +- Columns: **id**, **title**, **status** and **department** +- Access control: Each user is assigned to department-based Custom Groups matching department names in the database. + +To ensure users only see reports from their own department(s), you can use the following SQL query: + +```SQL + SELECT * FROM issue_reports + WHERE department = ANY ( + string_to_array('{{globals.server.currentUser.groups}}', ',') + ); +``` + +**How This Works:** +- `{{globals.server.currentUser.groups}}` fetches the user’s groups securely from the server. +- `string_to_array(...)` converts the comma-separated string containing groups into a usable array. +- `department = ANY (...)` ensures users only see issues filed under their own departments. + +### Filtered Results Based on Departments: + +Based on the query logic, users assigned to the Engineering and HR groups will see the following issues: + +| id | title | status | department | +|:---|:----------------------------------|:---------|:------------| +| 1 | Login bug on portal | Open | Engineering | +| 3 | Leave approval stuck | Open | HR | +| 4 | Data sync error | Open | Engineering | +| 5 | Employee onboarding delay | Pending | HR | +| 9 | GitHub webhook failure | Open | Engineering | + +Users assigned to the Marketing group will see only the issues related to their department: + +| id | title | status | department | +|:---|:----------------------------------|:---------|:---------------| +| 2 | Deliver failure issues | Pending | Marketing | +| 7 | Campaign budget approval delayed | Pending | Marketing | +| 8 | Social media calendar not updated | Open | Marketing | + +This setup ensures that a shared internal tool remains secure, with minimal query changes and no duplication of logic or views, making it ideal for HR dashboards, ticketing systems, CRM tools, and more. + diff --git a/docs/versioned_docs/version-3.16.0-LTS/build-with-ai/ai-docs-assitant.md b/docs/versioned_docs/version-3.16.0-LTS/build-with-ai/ai-docs-assitant.md new file mode 100644 index 0000000000..47f52240b9 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/build-with-ai/ai-docs-assitant.md @@ -0,0 +1,56 @@ +--- +id: ai-docs-assistant +title: AI Docs Assistant +--- + +The **AI Docs Assistant** is an intelligent assistant designed to help you navigate ToolJet’s documentation with ease. Whether you need quick answers, step-by-step guides, or concept explanations, this assistant provides instant support by summarizing docs, troubleshooting issues, and guiding you through best practices. + +You can access the AI Docs Assistant under the **Learn** tab in the Build with AI sidebar. Simply ask a question or describe what you're looking for, and the assistant will provide relevant documentation and insights. + +
+ +tooljet ai doc assistant + +
+ +### What You Can Do with the AI Docs Assistant +- Get guidance on setting up workspaces, managing users, and configuring roles. +- Quickly understand complex topics with clear, actionable steps +- Find answers to common questions and resolve issues efficiently. +- Explore how to connect databases, APIs, and external tools. +- Discover best practices for securing your applications. +- Get up to speed with key functionalities and platform best practices. + +### Examples + +1. Custom Schema in [Form](/docs/widgets/form/) component: + + **Prompt**: Can you create a custom schema for a Form component with two input fields for name, phone number, and a dropdown for gender? + +
+ +tooljet ai doc assistant + +
+ + + 2. Dynamic columns in [Table](/docs/widgets/table/table-properties/) component: + + **Prompt**: Can you explain dynamic columns in the Table component? + +
+ +tooljet ai doc assistant + +
+ + + 3. Plotly JSON in [Chart](/docs/widgets/chart/) component: + + **Prompt**: Can you help me with the structure of the Plotly JSON that I can pass into Chart components? + +
+ +tooljet ai doc assistant + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/build-with-ai/generate-applications.md b/docs/versioned_docs/version-3.16.0-LTS/build-with-ai/generate-applications.md new file mode 100644 index 0000000000..dd676660c9 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/build-with-ai/generate-applications.md @@ -0,0 +1,58 @@ +--- +id: generate-applications +title: Generate Applications +--- + +This guide explains how to quickly generate and modify business applications using ToolJet. You can create an app from scratch with a single prompt or enhance an existing app with AI-powered assistance. + +## Creating Application +To create an application, follow these steps: + +1. **Enter a prompt** – Describe the business application you want to build in the prompt input on the dashboard. +
+ +tooljet generate apps + +
+ +2. **Accept or modify requirements** – After submitting your prompt, the app will be created, and you’ll be taken to the App Builder, where a list of features, a database schema, design details, and query specifications will be generated based on your prompt. +
+ +tooljet generate apps + +
+ +You can accept or modify these application requirements after reviewing them thoroughly. +
+ +tooljet generate apps + +
+ +3. **App Generation** – Once you confirm the requirements, ToolJet will build the application inside the App Builder. + +
+ +tooljet generate apps + +
+ +## Modifying Application + +You can modify any application in ToolJet with AI assistance, whether it's a newly created app or an existing one. You can update components and queries within your application with just a prompt. + +For example, if you want to add a button in your app you can write a prompt for the same. +
+ +tooljet generate apps + +
+ +## Limitations + +ToolJet supports generating queries with AI for the following data sources: + +- [Postgres](/docs/data-sources/postgresql/) +- [MySQL](/docs/data-sources/mysql/) +- [SQL Server](/docs/data-sources/mssql/) +- [RunJS Queries](/docs/data-sources/run-js) diff --git a/docs/versioned_docs/version-3.16.0-LTS/build-with-ai/overview.md b/docs/versioned_docs/version-3.16.0-LTS/build-with-ai/overview.md new file mode 100644 index 0000000000..e1118e3db9 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/build-with-ai/overview.md @@ -0,0 +1,40 @@ +--- +id: overview +title: Overview +--- +With ToolJet, you can build business applications effortlessly using natural language. Whether you're starting from scratch or refining an existing app, it simplifies the process with it's intelligence. + +Additionally, it comes with an AI-powered [documentation assistant](/docs/build-with-ai/ai-docs-assistant), ready to answer any questions about ToolJet's features, components, and integrations, helping you build faster. + +Follow these step-by-step instructions to create an inventory management application: +1. **Describe your application** – Provide a prompt detailing the business application you want to create. (Example: "Inventory management system for a manufacturing company.") +
+ +tooljet ai overview + +
+2. **Refine the requirements** – Review and accept or modify the application requirements suggested. +
+ +tooljet ai overview + +
+3. **Customize your application** – Use AI to customize the generated application to your specific needs, adjusting components and styles, and also data source queries. + +- **Generated Application** +
+ +tooljet ai overview + +
+ +- **Customizing Application** + +
+ +tooljet ai overview + +
+ + +Refer to [Generate Applications](/docs/build-with-ai/generate-applications) and [AI Docs Assistant](/docs/build-with-ai/ai-docs-assistant) documentation to learn more. diff --git a/docs/versioned_docs/version-3.16.0-LTS/build-with-ai/tooljet-mcp.md b/docs/versioned_docs/version-3.16.0-LTS/build-with-ai/tooljet-mcp.md new file mode 100644 index 0000000000..979530422c --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/build-with-ai/tooljet-mcp.md @@ -0,0 +1,300 @@ +--- +id: tooljet-mcp +title: ToolJet MCP + +--- + +
+ Self Hosted +
+The [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is a standard for connecting Large Language Models (LLMs) to platforms like ToolJet. This guide covers how to connect ToolJet to AI tools using MCP, enabling your AI assistants to interact with and manage your ToolJet instance. + +## What is ToolJet MCP? + +ToolJet MCP is a bridge that connects AI assistants to your ToolJet platform through the Model Context Protocol. This allows AI tools to: + +- Manage users and workspaces +- Access app information +- Perform administrative tasks +- Interact with your ToolJet instance programmatically + +## Supported AI Tools + +You can connect ToolJet to the following AI tools using MCP: + +- [Cursor](#cursor) +- [Windsurf](#windsurf) (Codium) +- [Visual Studio Code](#visual-studio-code-copilot) (Copilot) +- [Cline](#cline) (VS Code extension) +- [Claude desktop](#claude-desktop) +- [Claude code](#claude-code) + +## Prerequisites + +Before you begin, you'll need: + +1. A ToolJet instance with admin access +2. An API access token from your ToolJet instance +3. Node.js (v14 or higher) +4. An MCP-compatible AI assistant + +## Getting Started + +### Step 1: Get an Access Token + +Get an access token from your ToolJet instance. You'll need this token to authenticate the MCP server. Refer to the [ToolJet API](https://docs.tooljet.ai/docs/tooljet-api#enabling-tooljet-api) documentation for more details on how to generate an API token. + +### Step 2: Configure Your AI Tool + +Follow the instructions below to configure your preferred AI tool to connect with ToolJet MCP. + +#### Cursor + +1. Open [Cursor](https://www.cursor.com/) and create a `.cursor` directory in your project root if it doesn't exist. +2. Create a `.cursor/mcp.json` file if it doesn't exist and open it. +3. Add the following configuration: + +```json +{ + "mcpServers": { + "tooljet": { + "command": "npx", + "args": [ + "-y", + "@tooljet/mcp", + ], + "env": { + "TOOLJET_ACCESS_TOKEN": "", + "TOOLJET_HOST": "https://your-tooljet-instance.com" + } + } + } +} +``` + +Replace `` with your ToolJet access token and update the host URL to point to your ToolJet instance. + +4. Save the configuration file. +5. Open Cursor and navigate to **Settings/MCP**. You should see a green active status after the server is successfully connected. + +#### Windsurf + +1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. +2. Tap on the hammer (MCP) icon, then **Configure** to open the configuration file. +3. Add the following configuration: + +```json +{ + "mcpServers": { + "tooljet": { + "command": "npx", + "args": [ + "-y", + "@tooljet/mcp", + ], + "env": { + "TOOLJET_ACCESS_TOKEN": "", + "TOOLJET_HOST": "https://your-tooljet-instance.com" + } + } + } +} +``` + +Replace `` with your ToolJet access token and update the host URL to point to your ToolJet instance. + +4. Save the configuration file and reload by tapping **Refresh** in the Cascade assistant. +5. You should see a green active status after the server is successfully connected. + +#### Visual Studio Code (Copilot) + +1. Open [VS Code](https://code.visualstudio.com/) and create a `.vscode` directory in your project root if it doesn't exist. +2. Create a `.vscode/mcp.json` file if it doesn't exist and open it. +3. Add the following configuration: + +```json +{ + "inputs": [ + { + "type": "promptString", + "id": "tooljet-access-token", + "description": "ToolJet access token", + "password": true + }, + { + "type": "promptString", + "id": "tooljet-host", + "description": "ToolJet host URL", + "default": "https://your-tooljet-instance.com" + } + ], + "servers": { + "tooljet": { + "command": "npx", + "args": ["-y", "@tooljet/mcp"], + "env": { + "TOOLJET_ACCESS_TOKEN": "${input:tooljet-access-token}", + "TOOLJET_HOST": "${input:tooljet-host}" + } + } + } +} +``` + +4. Save the configuration file. +5. Open Copilot chat and switch to "Agent" mode. You should see a tool icon that you can tap to confirm the MCP tools are available. Once you begin using the server, you will be prompted to enter your access token and host URL. + +For more info on using MCP in VS Code, see the [Copilot documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers). + +#### Cline + +1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. +2. Tap **Configure MCP Servers** to open the configuration file. +3. Add the following configuration: + +```json +{ + "mcpServers": { + "tooljet": { + "command": "npx", + "args": [ + "-y", + "@tooljet/mcp", + ], + "env": { + "TOOLJET_ACCESS_TOKEN": "", + "TOOLJET_HOST": "https://your-tooljet-instance.com" + } + } + } +} +``` + +Replace `` with your ToolJet access token and update the host URL to point to your ToolJet instance. + +4. Save the configuration file. Cline should automatically reload the configuration. +5. You should see a green active status after the server is successfully connected. + +#### Claude desktop + +1. Open [Claude desktop](https://claude.ai/download) and navigate to **Settings**. +2. Under the **Developer** tab, tap **Edit Config** to open the configuration file. +3. Add the following configuration: + +```json +{ + "mcpServers": { + "tooljet": { + "command": "npx", + "args": [ + "-y", + "@tooljet/mcp", + ], + "env": { + "TOOLJET_ACCESS_TOKEN": "", + "TOOLJET_HOST": "https://your-tooljet-instance.com" + } + } + } +} +``` + +Replace `` with your ToolJet access token and update the host URL to point to your ToolJet instance. + +4. Save the configuration file and restart Claude desktop. +5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. + +#### Claude code + +1. Create a `.mcp.json` file in your project root if it doesn't exist. +2. Add the following configuration: + +```json +{ + "mcpServers": { + "tooljet": { + "command": "npx", + "args": [ + "-y", + "@tooljet/mcp", + ], + "env": { + "TOOLJET_ACCESS_TOKEN": "", + "TOOLJET_HOST": "https://your-tooljet-instance.com" + } + } + } +} +``` + +Replace `` with your ToolJet access token and update the host URL to point to your ToolJet instance. + +3. Save the configuration file. +4. Restart [Claude code](https://claude.ai/code) to apply the new configuration. + +## Platform-Specific Setup + +### Windows Users + +If you're using Windows, prefix the command with `cmd /c`: + +```json +{ + "mcpServers": { + "tooljet": { + "command": "cmd", + "args": [ + "/c", + "npx", + "-y", + "@tooljet/mcp", + ], + "env": { + "TOOLJET_ACCESS_TOKEN": "", + "TOOLJET_HOST": "https://your-tooljet-instance.com" + } + } + } +} +``` + +## Available Tools + +ToolJet MCP provides several tools that AI assistants can use to interact with your ToolJet instance: + +### User Management + +| Tool | Description | +| --- | --- | +| `get-all-users` | Retrieve a list of all users in your ToolJet instance | +| `get-user` | Get detailed information about a specific user | +| `create-user` | Create a new user in a specified workspace | +| `update-user` | Update a user's profile information | +| `update-user-role` | Change a user's role within a workspace | + +### Workspace Management + +| Tool | Description | +| --- | --- | +| `get-all-workspaces` | List all workspaces in your ToolJet instance | + +### Application Management + +| Tool | Description | +| --- | --- | +| `get-all-apps` | List all applications within a specific workspace | + +## Example Usage + +Once connected, your AI assistant can perform tasks like: + +- "Show me all users in my ToolJet instance" +- "Create a new user named John Doe in the Marketing workspace" +- "List all the apps in the Development workspace" +- "Update the role of user@example.com to Admin in the Sales workspace" + + +For a full list of tools available, see the [GitHub README](https://github.com/ToolJet/tooljet-mcp). If you experience any issues, [submit a bug report](https://github.com/ToolJet/tooljet-mcp/issues/new). + + + diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/_category_.json b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/_category_.json new file mode 100644 index 0000000000..317067020d --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Contributing Guide", + "position": 11, + "collapsed": true +} \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/code-of-conduct.md b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/code-of-conduct.md new file mode 100644 index 0000000000..03f7184d51 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/code-of-conduct.md @@ -0,0 +1,81 @@ +--- +id: code-of-conduct +title: Contributor Code of Conduct +--- + +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to make participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies within all project spaces, and it also applies when +an individual is representing the project or its community in public spaces. +Examples of representing a project or community include using an official +project e-mail address, posting via an official social media account, or acting +as an appointed representative at an online or offline event. Representation of +a project may be further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at hello@tooljet.com . All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see +https://www.contributor-covenant.org/faq \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/documentation-guidelines/introduction.md b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/documentation-guidelines/introduction.md new file mode 100644 index 0000000000..e574a4f7b8 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/documentation-guidelines/introduction.md @@ -0,0 +1,40 @@ +--- +id: introduction +title: Introduction +--- + +Welcome to the ToolJet Documentation guide! We're thrilled to have you here and can't wait to see the contributions you'll make to our docs. Your insights and improvements will help thousands of users get the most out of ToolJet πŸš€. + +In the following sections, you'll find everything you need to get started with contributing to our documentation. + +## What Makes Good Documentation? + +Good documentation is all about clarity, simplicity, and effectiveness. It should guide users through the usage and workings of ToolJet with precision, making it as easy as possible for them to build and deploy internal tools. + +Documentation is a cornerstone of our product. It's one of the most visited sections of our website, second only to our homepage. Without well-crafted, thorough documentation, users can't fully utilize the power of ToolJet, and their experience may suffer as a result. + +### The Golden Rule + +If a ToolJet feature lacks comprehensive documentation, it isn't considered complete. Quality documentation is essential for the success of our product and the satisfaction of our users. It’s often through documentation that users discover new features or decide to upgrade their tools. + +As a contributor, you can create detailed, user-centric content that thoroughly covers the features you're documenting in an engaging and accurate way. + +## Types of Documentation + +We aim to create rich, informative content across three key areas of documentation: + +1. **ToolJet Concepts**: Basic explanations of specific topics, offering general insights into how ToolJet features work. +2. **How-to Guides**: Step-by-step instructions that help users accomplish specific tasks within ToolJet. +3. **Reference**: Concise, lookup-style documentation that covers all possible usages, definitions, and edge cases for ToolJet features. + +As you document features, consider which of these categories your content fits best. Sometimes a feature might require multiple types of documentation to be fully covered. + +### Measuring Impact and Gathering Feedback + +The quality of our documentation isn't just determined by how well it's writtenβ€”it's also measured by how well it serves our users. We regularly use analytics and feedback tools to assess the impact of our documentation and make data-driven improvements. + +## Next Steps... + +Once you've set up your local environment, take some time to explore our [Style Guide](/docs/contributing-guide/documentation-guidelines/style-guide), understand our page structures, and learn how to work with Docusaurus, the framework we use for our documentation. + +We look forward to your contributions and are excited to see how you'll help make ToolJet documentation even better! diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/documentation-guidelines/pr-checklist.md b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/documentation-guidelines/pr-checklist.md new file mode 100644 index 0000000000..1d3fe3a7cb --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/documentation-guidelines/pr-checklist.md @@ -0,0 +1,15 @@ +--- +id: pr-checklist +title: Pull Request Review Checklist +--- + +Use this quick checklist to catch common issues and maintain consistency across your project. + +- Review spelling and grammar using tools like ChatGPT or Grammarly. +- Ensure no compilation issues arise due to formatting. +- Verify that all h2 and h3 headings follow title case. +- Confirm that every section starting with h2 has a 24px padding-top. +- Test for broken links, missing images, and any incorrect code. +- Ensure new internal links use root-relative file paths. +- Identify opportunities for relevant cross-linking. +- Ensure that the changes are implemented in all the required versions. diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/documentation-guidelines/style-guide.md b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/documentation-guidelines/style-guide.md new file mode 100644 index 0000000000..65f70547da --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/documentation-guidelines/style-guide.md @@ -0,0 +1,236 @@ +--- +id: style-guide +title: Style Guide +--- + +Welcome to the ToolJet's Style Guide for creating clear, consistent, and accessible documentation. In this guide, you will find recommendations on text formatting, proper use of headers, code snippet styling, accessibility practices, and much more. + +## 1. Text Formatting Guidelines + +Different elements in your projects should be formatted consistently for clarity. Here are some recommendations: + +a. Italics are used for names given to Queries, Database Tables, and Components. + +**Examples:** +- Create a new query and rename it to *getEmployees*. +- Select **ToolJetDB** as the the data source and *Employees* table as the data source. +- Pass the returned data to the *allEmployees* component. + +b. Bold is applied for Workspace Constants, Clickable Buttons, fx, Data Sources, and Components. + +**Examples:** +- Select the **Button** component and change its label to "Save". +- Drag andn drop a **Table** component and rename it to *todosTable*. +- Expand the query panel at the bottom and click on the **Add** button to create a new **REST API** query. + + +c. Use Single Ticks for Inline Code and Triple Ticks for Multi-Line Code. + +**Examples:** +- The **fx** option next to the Loading state property can be used to add a loader to the component. For instance, you can enter `{{queries.getData.isLoading === true}}` to show the loader while the *getData* query is running. +- Use the below code to fetch data: +```js +// this code is wrapped in triple ticks +const fetchData = async () => { +const response = await api.get('/users'); +console.log(response.data); +}; +``` + +**Additional Items**: +- API Endpoints: Use code ticks for API endpoints (e.g., `GET /api/v1/resources`). +- Labels or User Inputs: Use double quotes to highlight labels or user inputs (e.g., "Enter your username"). + +--- + +## 2. Headings + +Proper use of headers is crucial for organizing content and improving readability. Use the following guidelines to determine which header level to apply: + +- **Title Casing**: Apply title casing for all headers to maintain consistency. +- **Main Header**: Use a single hash (`#`) for the main topic of the document or section. This should be used once per document for the main header. +- **Secondary Header**: Use double hashes (`##`) for subtopics or main sections within a major section. This level of header should organize content under the main header. +- **Tertiary Header**: Use triple hashes (`###`) for more detailed points or subsections under a secondary header. This header is useful for going deeper into specifics within a section. +- **Quaternary Header**: Use four hashes (`####`) for even more granular details within a tertiary section. This header is rarely needed but can be useful in complex documentation. +- **Spacing**: Ensure there’s a blank line before and after each header to maintain readability and to separate the sections clearly. +- **Header Frequency**: Avoid using more than three levels of headers to prevent overcomplication. If additional granularity is needed, consider breaking the content into separate sections or documents. + +--- + +## 3. Markdown Tables + +To efficiently present extensive and repetitive information about features, such as the properties of a component, use markdown tables. This format helps organize and display the data clearly and concisely. + +Ensure all tables are left-aligned for consistency. This aids in readability and ensures that the content is easy to scan. + +**Example**: +|
Variable
|
Description
|
How To Access
| +|:---------- | :---------- | :------------ | +| chartTitle | Holds the title of the chart component. | Accessible dynamically with JS (for e.g., `{{components.chart1.chartTitle}}`). | +| xAxisTitle | Contains the title for the X-axis of the chart. | Accessible dynamically with JS (for e.g., `{{components.chart1.xAxisTitle}}`). | +| yAxisTitle | Contains the title for the Y-axis of the chart. | Accessible dynamically with JS (for e.g., `{{components.chart1.yAxisTitle}}`). | +| clickedDataPoints | Stores details about the data points that were clicked.| Accessible dynamically with JS (for e.g., `{{components.chart1.clickedDataPoints}}`). Each data point includes `xAxisLabel`, `yAxisLabel`, `dataLabel`, `dataValue`, and `dataPercent`. | + +- Use **bold** formatting for all column headers to differentiate them from the table content. +- Avoid leaving empty cells in tables. If a cell doesn’t have applicable content, use a placeholder like "N/A" or "β€”" to indicate that the cell is intentionally blank. + +--- + +## 4. Admonitions + +Admonitions are blocks of content that are designed to draw attention to specific points in your documentation. Use them sparingly to avoid overwhelming the user. Reserve admonitions for critical or cautionary information only. + +- **Warning Admonitions**: Use `warning` type admonitions for high-risk actions or irreversible changes. This type of admonition should alert users to potential dangers or critical issues. + +**Example**: +:::warning +Ensure you back up your data before upgrading to the latest version. +::: + +- **Tip Admonitions**: Use `info` type admonitions to offer useful hints or best practices. These are generally positive and provide additional value to the user. + +**Example**: +:::info +Preview the changes before pushing them. +::: + +Overuse can dilute their impact. Use *italics* instead of admonitions whenever possible to emphasize important information instead of admonitions. This is a less intrusive way to draw attention to key details. + +--- + +## 5. Image Guidelines +Include images that closely align with real-world use cases. This makes the documentation more practical and relatable for the user. + +- Name images to reflect their purpose, such as `create-get-query.jpeg`. This helps maintain an organized file structure and makes it easier to locate specific images. +- Align images to the left. This is the standard alignment that works well with most content layouts. +- Set the image width to 100% to ensure it scales appropriately with different screen sizes. +- Keep image sizes under 300kb to balance load speed and quality. +- Alt text should be a concise description of the image, providing the same information as the image itself. This is essential for accessibility and for users who rely on screen readers. +- Skip phrases like "image of" or "graphic of" as screen readers handle this automatically. Focus on describing what is important about the image. +- Use `WEBP` or `PNG` formats for web images due to their balance between quality and file size. +- Use `SVG` for logos or icons to ensure scalability without loss of quality. + +--- + +## 6. Tone and Clarity + +Maintaining a clear and consistent tone throughout your documentation is crucial for effective communication. The goal is to be concise, informative, and user-friendly. + +- Keep language straightforward and concise. Avoid jargon unless it's essential for the audience and provide explanations where necessary. +- Always proofread content using Grammarly or a similar tool before submitting a PR. This helps catch errors that might be missed during the initial writing process. +- Use the active voice wherever possible to make the content more direct and engaging. Passive voice can make sentences longer and more difficult to understand. + + +--- + +## 7. Bullet Points + +Use bullet points to break down steps or lists for clarity. This makes the content easier to scan and understand. + +- Avoid using bullet points for a single item. If there is only one point to make, integrate it into the main text instead. +- Ensure subpoints are correctly indented in markdown. This maintains the hierarchy and relationship between the main point and subpoints. +- End bullet points that are complete sentences with a period. This helps maintain proper grammar and readability. +- Do not insert blank lines between bullet points. This keeps the list compact and visually connected. +- Use nested bullet points for items that require further explanation or hierarchy within a list. + +--- + +## 9. Specific Language Guidelines + +Use the below language guidelines to ensure clarity and consistency. + +### HTTP Formatting + +- All HTTP headers should be capitalized like this: `First-Letter-Capitalized`. This follows the standard convention and makes the headers easier to distinguish. + **Example**: +``` +Content-Type: application/json +Authorization: Bearer +``` + +- HTTP blocks should be ready to run when pasted into tools like Postman or `cURL` commands. This means including all necessary components like headers, body, and method. **Example**: +```bash +curl -X POST https://api.example.com/resource \ +-H 'Content-Type: application/json' \ +-H 'Authorization: Bearer ' \ +-d '{"key": "value"}' +``` + +### JavaScript Guidelines + +- End statements with semicolons (`;`). While JavaScript can often infer semicolons, explicitly including them prevents potential issues, especially in complex code. **Example**: +```javascript +const name = 'John'; +console.log(name); +``` + +- Use single quotes for strings unless double quotes are necessary (e.g., to avoid escaping single quotes inside the string). **Example**: +```javascript +const greeting = 'Hello, world!'; +``` + +### JSON Formatting + +- Indent JSON by 2 spaces. This is a standard practice that improves readability. **Example**: +```json +{ + "name": "John Doe", + "age": 30, + "city": "New York" +} +``` + +- Avoid comments in JSON code, as JSON does not natively support comments. If explanations are needed, provide them outside the JSON block in the documentation. + +### Shell Scripting + +- Break separate commands into distinct code blocks or chain them with `&&` for readability. For multi-line commands, use `\` to break lines. **Example**: +```bash +sudo apt-get update && \ +sudo apt-get install -y curl +``` + +- Preface comments with `#` to explain the command's purpose. +**Example**: +```bash +# This command installs Node.js +sudo apt-get install -y nodejs +``` + +### SQL Queries + +- Format SQL queries with keywords in uppercase, and break down long queries into multiple lines for better readability. **Example**: +```sql +SELECT name, age, city +FROM users +WHERE age > 30 +ORDER BY name ASC; +``` + +--- + +## 10. Linking Guidelines + +- Use root-relative paths (e.g., `/schema/postgres/tables.mdx`) instead of relative links to avoid broken links during file moves. This practice ensures that links remain functional even if files are moved within the directory structure. **Example**:
+`[Postgres tables](/schema/postgres/tables.mdx)` links to the Postgres tables page. + +- When linking to a specific section within a page, use anchor links to direct the user precisely where needed. **Example**:
+`ToolJet supports [multiple environments,](https://docs.tooljet.ai/docs/#multiple-environments)` takes the user directly to the specific section. + + +--- + +## 11. Semantics and Terminology + +- Write in the second person (e.g., *you*, *your*). This makes the content more engaging and directly applicable to the reader. +- Ensure that case sensitivity is consistently applied across the document, particularly for technical terms or commands. This is important for commands and variables in code that are case-sensitive. +**Example**:
"`MyVariable` and `myvariable` are not the same." +- Define acronyms on first use and avoid using them excessively to maintain readability. This helps readers who may not be familiar with all acronyms. +**Example**:
"The Content Delivery Network (CDN) is used to deliver content to users efficiently." +- Maintain consistent terminology throughout the document. If you start with "user," don't switch to "customer" later in the same context. + +--- + + + +By following these guidelines, you can ensure that your documentation is clear, consistent, and easy to use for a wide range of audiences. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/l10n.md b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/l10n.md new file mode 100644 index 0000000000..cb74a19611 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/l10n.md @@ -0,0 +1,69 @@ +--- +id: l10n +title: Localization +--- + +Welcome to ToolJet Localization Guide. The goal of the Localization is to make ToolJet easy to use and close to all countries, languages, and general cultural groups. On this page, you will find instructions on how to contribute to ToolJet through Localization and make a more friendly ToolJet for all regions. + +## Adding Translations + +- For adding the translations of your language in ToolJet, you'll need to create a new **languagecode.json** file which will include all the translations for the keywords in your language, and then list the language in the **languages.json** file for the language to be listed in the dashboard of the ToolJet. + +- Go to the **frontend** directory which is at the root of ToolJet, then go to the **assets** and inside assets, you'll find the **translations** directory. You have created a new json file with the **language code** as the file name. The language code should follow [ISO 639-1 Code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). + + ``` + \frontend + |--\assets + |--\--\translations + |--\--\--\languages.json + |--\--\--\en.json + ``` + +
+ + files + +
+ +- Let's localize ToolJet in the **French** language. Create a new json file inside the translations directory and name it **fr.json**. `fr` is the language code for French. + +- After creating the new file, open the **en.json** file and copy all the contents of the file to the newly created **fr.json**. + +
+ + files + +
+ +- Once copied, you can now start adding the translations for the keywords in the french language. + +- After completing the translation, all you need to do is list the language in **languages.json** file. You'll need to add an object with three key-value pairs. **lang** - the name of the language that you added, **code** - the language code, and the **nativeLang** - name of language in the native. + + ```js + { + "languageList": + [ + { "lang": "English", "code": "en", "nativeLang": "English" }, + { "lang": "French", "code": "fr", "nativeLang": "FranΓ§ais" } + ] + } + ``` + + + +:::note +Feel free to reach us on [Slack](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) for any help related to Localization. +::: diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/marketplace/creating-a-plugin.md b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/marketplace/creating-a-plugin.md new file mode 100644 index 0000000000..a7a9cdf67b --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/marketplace/creating-a-plugin.md @@ -0,0 +1,424 @@ +--- +id: creating-a-plugin +title: 'Marketplace: Creating plugins' +--- + +## What are plugins + +ToolJet’s development has centered on extensibility, allowing developers to utilize plugins that expand their capabilities. Currently, these plugins are limited to connectors, including data source connectors like PostgreSQL, MySQL, Twilio, Stripe, and more. Using JavaScript/TypeScript, developers can develop plugins to enhance ToolJet's functionality and publish these plugins on the ToolJet Marketplace. + +This guide will provide step-by-step instructions for creating ToolJet plugins using the `tooljet` CLI. + +The `tooljet` CLI is a user-friendly command-line tool designed to simplify the plugin building process. As part of this guide, we will create a basic plugin for GitHub. + +## Step 1: Creating a New Plugin - GitHub Plugin + +The first step is to bootstrap a new plugin for the ToolJet marketplace. The plugin will authenticate users with a GitHub Personal Access Token and include fundamental operations such as fetching user details, repositories, issues, and pull requests. + +If you have completed the **[Setup](/docs/contributing-guide/marketplace/marketplace-setup)** guide, you can begin developing the plugin using the `tooljet` CLI. To initiate plugin development, enter the following command in the terminal: +```bash +# create a new plugin +tooljet plugin create github +``` + +When prompted, enter the **plugin name** and select the **plugin type**, which is api in this case. Additionally, select **yes** when prompted to create a new plugin for the marketplace. + +If your plugin is hosted on GitHub, please provide the **repository URL** when prompted. Otherwise, leave it blank. + +When a plugin is created using the `ToolJet` CLI, an object is added to the **plugins.json** file in the **`ToolJet/server/src/assets/marketplace/`** directory. This object includes metadata about the plugin, such as its name, description, version, author, and other relevant details. + +The plugins.json file serves as a registry of all available plugins for use in ToolJet. When the ToolJet server starts up, it reads the plugins.json file and loads all plugins that are listed in it. + +:::info +It is important to note that the plugins.json file should not be manually edited, as it is automatically generated by the `ToolJet CLI`. Making changes to this file can result in issues with the proper functioning of the plugins in the system. +::: + +All marketplace plugins are stored in the **`/marketplace`** directory of the ToolJet repository. You can find the GitHub plugin **[here](https://github.com/ToolJet/ToolJet/tree/develop/marketplace/plugins/github)**. + +The structure of a typical ToolJet plugin directory appears as follows: +```bash +github/ + package.json + lib/ + icon.svg + index.ts + operations.json + manifest.json +``` + +In this structure, the file **manifest.json** contains information about the plugin's name, description, and other details. The file **operations.json** contains metadata about all the operations that the plugin supports. The main file, **index.ts**, creates a QueryService for the plugin, which handles queries, connection testing, caching, and more. The **icon.svg** file serves as the plugin's icon, while **package.json** is automatically generated by the CLI. + +:::info +**Why do we need a manifest.json file or a operations.json file?** + +The manifest.json file is used by a React component to create a dynamic UI for connection forms. It defines the schema of an API or data source, including its name, type, and any exposed variables, as well as options for authentication and other customizable properties. The properties section specifies the required fields and their types for connecting to the API or data source. By reading the manifest.json file, the React component generates the necessary UI components based on the schema, such as text inputs, dropdowns, checkboxes, and other elements. + +On the other hand, the operations.json file contains a schema definition for a specific data source, like Github. It describes the available operations and their parameters that can be used to query the data source. A React component uses this schema to create queries in ToolJet applications, generating a UI that allows users to select the desired operation and provide the required parameters. The component uses the properties defined in the operations.json file to create various UI elements, such as dropdowns and input fields, and handle user interactions to create the final query. Once the user fills in the required parameters, the component uses them to generate a query that can be executed against the data source and return the results to the user. + +Overall, *manifest.json* and *operations.json* files are essential for creating dynamic UI components in ToolJet applications. They define the schema for data sources and available operations, which React components then use to generate user-friendly UI elements. By utilizing these files, ToolJet enables users to easily connect to various APIs and data sources, perform queries, and retrieve data in an intuitive and efficient manner. +::: + +## Step 2: Defining the manifest.json file + +To construct the connection form, it's important to include the necessary options in the manifest.json file. Here's an example of how to do it: +```json + "properties": { + "credentials": { + "label": "Authentication", + "key": "auth_type", + "type": "dropdown-component-flip", + "description": "A single select dropdown to choose credentials", + "list": [ + { + "value": "personal_access_token", + "name": "Use Personal Access Token" + } + ] + }, + "personal_access_token": { + "token": { + "label": "Token", + "key": "personal_token", + "type": "password", + "description": "Enter your personal access token", + "hint": "You can generate a personal access token from your Github account settings." + } + } + } +``` +This manifest.json file includes information about authentication options, specifically a dropdown to choose a type of credentials and a field to enter a personal access token. The label, key, type, description, and hint properties are used to define the specific fields and their types required for connecting to the API or data source. + +In this particular code, there are two main properties defined: **`credentials`** and **`personal_access_token`**. + +The **`credentials`** property specifies the authentication method to be used. It contains several keys: +- **`label`**: a user-friendly label for the authentication method, set to "Authentication" +- **`key`**: a unique identifier for the authentication method, set to "auth_type" +- **`type`**: the type of the authentication method, set to "dropdown-component-flip" +- **`description`**: a description of the authentication method, set to "A single select dropdown to choose credentials" +- **`list`**: an array of objects representing the different authentication methods available. In this case, there is only one method available: a personal access token. The `value` key in the object is set to "personal_access_token" and the `name` key is set to "Use Personal Access Token". + +The **`personal_access_token`** property specifies the details of the personal access token authentication method. It contains a `token` key, which specifies the actual personal access token to be used. The `token` key contains several keys: +- **`label`**: a user-friendly label for the personal access token, set to "Token" +- **`key`**: a unique identifier for the personal access token, set to "personal_token" +- **`type`**: the type of the personal access token, set to "password" +- **`description`**: a description of the personal access token, set to "Enter your personal access token" +- **`hint`**: a hint for the personal access token, set to "You can generate a personal access token from your Github account settings." + +The available `type` options are: + +However, based on the code you provided, the available **`type`** options are: +- **`password`**: used to input a secret value, such as a password or an access token. +- **`dropdown-component-flip`**: used to create a dropdown menu that flips its position relative to the component that triggers it. +- **`text`**: used to input a single line of text. +- **`textarea`**: used to input multiple lines of text. +- **`toggle`**: used to create a simple on/off switch. +- **`react-component-headers`**: used to display headers for React components. +- **`codehinter`**: is a specialized input field used for entering code and has additional functionality, such as resolving JavaScript code within double curly braces`{{}}`. + +:::tip +The **manifest.json** file is utilized by the connection modal component, which appears to prompt users to enter their datasource credentials. Meanwhile, the **operations.json** file is used by the query manager when users generate a specific query for a connected datasource. **Both files utilize a similar schema**. +::: + +## Step 3: Defining the operations.json file +```json + "properties": { + "operation": { + "label": "Operation", + "key": "operation", + "type": "dropdown-component-flip", + "description": "Single select dropdown for operation", + "list": [ + { + "value": "get_user_info", + "name": "Get user info" + }, + { + "value": "get_repo", + "name": "Get repository" + }, + { + "value": "get_repo_issues", + "name": "Get repository issues" + }, + { + "value": "get_repo_pull_requests", + "name": "Get repository pull requests" + } + ] + }, + "get_user_info": { + "username": { + "label": "Username", + "key": "username", + "type": "codehinter", + "lineNumbers": false, + "description": "Enter username", + "width": "320px", + "height": "36px", + "className": "codehinter-plugins", + "placeholder": "Enter username" + } + }, + "get_repo": { + "owner": { + "label": "Owner", + "key": "owner", + "type": "codehinter", + "lineNumbers": false, + "description": "Enter owner name", + "width": "320px", + "height": "36px", + "className": "codehinter-plugins", + "placeholder": "developer" + }, + "repo": { + "label": "Repository", + "key": "repo", + "type": "codehinter", + "lineNumbers": false, + "description": "Enter repository name", + "width": "320px", + "height": "36px", + "className": "codehinter-plugins", + "placeholder": "tooljet" + } + }, + "get_repo_issues": { + "owner": { + "label": "Owner", + "key": "owner", + "type": "codehinter", + "lineNumbers": false, + "description": "Enter owner name", + "width": "320px", + "height": "36px", + "className": "codehinter-plugins", + "placeholder": "developer" + }, + "repo": { + "label": "Repository", + "key": "repo", + "type": "codehinter", + "lineNumbers": false, + "description": "Enter repository name", + "width": "320px", + "height": "36px", + "className": "codehinter-plugins", + "placeholder": "tooljet" + }, + "state": { + "label": "State", + "key": "state", + "className": "codehinter-plugins col-4", + "type": "dropdown", + "description": "Single select dropdown for choosing state", + "list": [ + { + "value": "open", + "name": "Open" + }, + { + "value": "closed", + "name": "Closed" + }, + { + "value": "all", + "name": "All" + } + ] + } + }, + "get_repo_pull_requests": { + "owner": { + "label": "Owner", + "key": "owner", + "type": "codehinter", + "lineNumbers": false, + "description": "Enter owner name", + "width": "320px", + "height": "36px", + "className": "codehinter-plugins", + "placeholder": "developer" + }, + "repo": { + "label": "Repository", + "key": "repo", + "type": "codehinter", + "lineNumbers": false, + "description": "Enter repository name", + "width": "320px", + "height": "36px", + "className": "codehinter-plugins", + "placeholder": "tooljet" + }, + "state": { + "label": "State", + "key": "state", + "type": "dropdown", + "className": "codehinter-plugins col-4", + "description": "Single select dropdown for choosing state", + "list": [ + { + "value": "open", + "name": "Open" + }, + { + "value": "closed", + "name": "Closed" + }, + { + "value": "all", + "name": "All" + } + ] + } + } + } +``` +The operations.json file specifies the available operations that can be executed on the data source. It provides details about the operation type, required fields to execute the operation, and the data type of each field. The label, key, type, description, and hint properties are used to define the specific fields and their types required to establish a connection with the API or data source. + +## Step 4: Add the npm package of GitHub to the plugin dependencies + +- Change directory to the plugin directory where the npm package needs to be installed and then install the package + ```bash + # change directory to the plugin directory and install the npm package + npm i octokit --workspace=@tooljet-marketplace/github + ``` + + :::info + Steps to install npm package to a plugin + + ```bash + npm i --workspace= + ``` + + The command `npm i --workspace=` is used to install a specific npm package into a particular workspace of a multi-package repository. + + The *--workspace* flag is used to specify the workspace where the package should be installed. In this case, we are installing the package in the *@tooljet-marketplace/github* workspace. + ::: + +## Step 5: Implement the query execution logic in index.ts + +In index.ts, the query execution logic needs to be implemented for the Github plugin's QueryService. The QueryService is responsible for handling the process of running queries and receives information about the data source, including credentials, configurations, and query parameters. + +For the Github data source, the sourceOptions will contain the necessary authentication credentials, like the personal access token, while the queryOptions will include the configurations and parameters specific to the query, like obtaining a list of repositories for a particular user. + +Using this information, the QueryService will create and execute API requests against the Github API. The resulting data will be returned to the caller for further processing as needed. + +Create a new file **query_operations.ts** in the **plugins/github/src** directory and add the following code to it. +```typescript +import { Octokit } from 'octokit' +import { QueryOptions } from './types' + + +export async function getUserInfo(octokit: Octokit, options: QueryOptions): Promise { + const { data } = await octokit.request( + 'GET /users/{username}', + { + username: options.username + } + ); + return data; +} + +export async function getRepo(octokit: Octokit, options: QueryOptions): Promise { + const { data } = await octokit.request( + 'GET /repos/{owner}/{repo}', + { + owner: options.owner, + repo: options.repo + } + ); + return data; +} + +export async function getRepoIssues(octokit: Octokit, options: QueryOptions): Promise { + const { data } = await octokit.request( + 'GET /repos/{owner}/{repo}/issues', + { + owner: options.owner, + repo: options.repo, + state: options.state || 'all' + + } + ); + return data; +} + +export async function getRepoPullRequests(octokit: Octokit, options: QueryOptions): Promise { + const { data } = await octokit.request( + 'GET /repos/{owner}/{repo}/pulls', + { + owner: options.owner, + repo: options.repo, + state: options.state || 'all' + } + ); + return data; +} + +``` + + +The query_operations.ts file comprises functions that will execute the queries and will be called by the QueryService in index.ts. + +The GitHub class has three methods: + +- **run**: This method executes a query and is invoked by passing sourceOptions and queryOptions as input, representing the source metadata and query configuration, respectively. The run method utilizes the octokit library to send API requests to the GitHub API and returns the query result in a QueryResult object. + +- **testConnection**: When adding a new data source to a ToolJet application, the connection can be tested. The testConnection method is used to test the connection, and it takes in sourceOptions as input, which represents the source metadata. The method tests the connection by trying to fetch the authenticated user and returns a ConnectionTestResult object indicating whether the connection was successful. + + :::note + Not all data sources may support testing connections. If it's not applicable for your data source, you can disable the test connection feature by adding "customTesting": true to your plugin's manifest.json. + ::: + +- **getConnection**: This method is a helper function that returns an authenticated octokit client, which is utilized to send requests to the GitHub API. It takes in sourceOptions as input, representing the source metadata, and returns an authenticated octokit client. + +## Step 6: Add Error Handling + +In case of an error, it is necessary to return the error message received from the Plugin SDK. To achieve this, include the `errorDetails` in the **run** method within the **index.ts** file. The specific parameters of the error may vary depending on the plugin.

+Additionally, the **data** field in the Plugin SDK corresponds to **errorDetails** in the code, and the dynamically generated **errorMessage** maps to the **description** field in the error preview. + +#### Example + +Consider the case of MongoDB. If an error occurs, such as the following: + +MongoDB Error + +You can implement error handling using the following code: + +```js +catch (error) { + let errorMessage = 'An unknown error occurred'; + let errorDetails = {}; + + if (error instanceof Error) { + errorMessage = error.message || errorMessage; + errorDetails = { + name: error.name, + code: (error as any).code || null, + codeName: (error as any).codeName || null, + keyPattern: (error as any).keyPattern || null, + keyValue: (error as any).keyValue || null, + }; + } + + throw new QueryError('Query could not be completed', errorMessage, errorDetails); +} +``` + +This code ensures that error messages and details are properly returned to the Plugin SDK, enabling meaningful error previews for the user. + +Query Error + +## Delete a plugin +To delete a plugin, enter the following command: + +```bash +tooljet plugin delete PLUGIN_NAME +``` + +The CLI will prompt users to verify if the plugin to be deleted is a marketplace plugin before proceeding with the deletion. + +## Publish a plugin +To release a plugin, submit a pull request on ToolJet's GitHub Repository after creating it. The ToolJet team will review the pull request, and if approved, the plugin will be included and published in the next release. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/marketplace/marketplace-setup.md b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/marketplace/marketplace-setup.md new file mode 100644 index 0000000000..05162870b3 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/marketplace/marketplace-setup.md @@ -0,0 +1,80 @@ +--- +id: marketplace-setup +title: 'Marketplace: Development Setup' +--- + +The Marketplace offers custom plugins that can be installed in your ToolJet instance. This guide aims to assist you in creating a new plugin for the ToolJet marketplace. + +## Requirements +- [Node.js](https://nodejs.org/en/download/) **(v18.18.2)** +- [npm](https://www.npmjs.com/get-npm) **(v9.8.1)** + +## Getting Started + +### Step 1. Setup ToolJet Locally + +To obtain the ToolJet repository via git, use the command: + +```bash +git clone https://github.com/ToolJet/ToolJet.git +``` + +Next, refer to the appropriate guide for your development environment to follow the Setup instructions: + +- **[MacOS](/docs/contributing-guide/setup/macos)** +- **[Docker](/docs/contributing-guide/setup/docker)** +- **[Ubuntu](/docs/contributing-guide/setup/ubuntu)** + +### Step 2. Enabling the Marketplace for your Instance + +To enable the marketplace for your ToolJet instance, you need to specify the following environment variables in your **`.env`** file: + +#### Marketplace Feature Enable + +Use this environment variable to enable/disable the feature that allows users to use the marketplace. + +| variable | value | +| -------------------------- | ----------------- | +| ENABLE_MARKETPLACE_FEATURE | `true` or `false` | + +#### Enable Marketplace Plugin Developement Mode + +The use of this environment variable facilitates plugin development by enabling automatic builds whenever package changes occur, thus simplifying the development process. Moreover, it also incorporates a reload button that retrieves all the recent local modifications from the file system for installed plugins, making it a valuable feature for improving the overall development experience. + +| variable | value | +| -------------------------- | ----------------- | +| ENABLE_MARKETPLACE_DEV_MODE | `true` or `false` | + + +Please note that the marketplace is not enabled by default. After updating the variable, restart your ToolJet instance. + +For information on running ToolJet on your local machine, please refer to the instructions provided **[here](/docs/contributing-guide/setup/architecture)**. You can access the marketplace by navigating to the **'/integrations'** route. + +### Step 3: Install the Required Packages + +The required packages must be installed from the marketplace root folder. Use the following commands to install the packages: + +``` bash +cd marketplace +npm install +``` + +After the packages are installed, run the following command to build the directory: + +``` bash +npm run build +``` + +### Step 4: Installation of tooljet-cli + +In order to manage plugins for the ToolJet marketplace, including creating, updating, and deleting, you will need to utilize **[tooljet-cli](https://www.npmjs.com/package/@tooljet/cli)**. This can be installed via npm by entering the following command: +```bash +npm install -g @tooljet/cli + +# Ensure the installation was successful +tooljet --version +``` + +Having completed the environment setup for Marketplace Developer mode, we can proceed to the next section and commence with [developing the first plugin](/docs/contributing-guide/marketplace/creating-a-plugin). + + diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/_category_.json b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/_category_.json new file mode 100644 index 0000000000..90bb09deae --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Setup", + "position": 1, + "collapsed": true +} diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/architecture.md b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/architecture.md new file mode 100644 index 0000000000..c61fd8b0f3 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/architecture.md @@ -0,0 +1,25 @@ +--- +id: architecture +title: Architecture +--- +# Introduction + +ToolJet has two main components: **ToolJet Server** and **ToolJet Client**. + +### 1. ToolJet Server + +ToolJet server is a Node.js API application. Server is responsible for authentication, authorization, persisting application definitions, running queries, storing data source credentials securely and more. + +**Dependencies:** +- **PostgreSQL** - ToolJet server persists data to a postgres database. +- **Email service** (SMTP/Sendgrid/Mailgun/etc) - Required to send user invitations and password reset emails. +- **PostgREST** - Standalone web server that converts PostgreSQL database into queryable RESTful APIs for ToolJet Database. + +### 2. ToolJet Client + +ToolJet client is a ReactJS application. Client is responsible for visually editing the applications, building & editing queries, rendering applications, executing events and their trigger, etc. + +## Requirements + +1. **Node version 18.18.2** +2. **npm version 9.8.1** diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/codespaces.md b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/codespaces.md new file mode 100644 index 0000000000..c64aacb24a --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/codespaces.md @@ -0,0 +1,117 @@ +--- +id: codespaces +title: GitHub Codespaces +--- + +Follow the steps below to set up ToolJet on GitHub Codespaces. We recommend reading our guide on [architecture](https://docs.tooljet.ai/docs/contributing-guide/setup/architecture) of ToolJet before proceeding. + +Open the terminal and run the commands below. + +## Setting up + +### 1. Set up the environment + +1. Install Node.js ( version: v18.18.2 ) and npm (version: v9.8.1) + +``` +nvm install 18.18.2 +nvm use 18.18.2 +npm install -g npm@9.8.1 +``` + +2. Install Postgres + +``` +sudo sh -c 'echo "deb [http://apt.postgresql.org/pub/repos/apt](http://apt.postgresql.org/pub/repos/apt) $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list' + +wget --quiet -O - [https://www.postgresql.org/media/keys/ACCC4CF8.asc](https://www.postgresql.org/media/keys/ACCC4CF8.asc) | sudo apt-key add - + +sudo apt-get update + +sudo apt-get install postgresql-13 postgresql-contrib-13 +``` + +To start the postgresql service run the below command: + +``` +sudo service postgresql start +``` + +If you wish to change the password of the installed postresql service run the below commands: + +``` +sudo su + +sudo -u postgres psql + +\password postgres + +\q +``` + +### 2. Set up environment variables + +Create a `.env` file by running the command `touch .env`. More information on the variables that can be set is given in the [environment variables reference](https://docs.tooljet.ai/docs/setup/env-vars) + +**For basic set-up you add the below env variables:** + +``` +TOOLJET_HOST=http://localhost:3000 + +LOCKBOX_MASTER_KEY= + +SECRET_KEY_BASE= + +PG_USER=postgres + +PG_HOST=localhost + +PG_PASS=postgres + +PG_DB=tooljet_prod + +SUB_PATH=/apps/tooljet/ + +NODE_ENV=production + +SERVE_CLIENT=true +``` + +> `SECRET_KEY_BASE` requires a 64 byte key. (If you have `openssl` installed, run `openssl rand -hex 64` to create a 64 byte secure random key) +> +> `LOCKBOX_MASTER_KEY` requires a 32 byte key. (Run `openssl rand -hex 32` to create a 32 byte secure random key) + +### 3. Install and build dependencies + +Make sure node version is set to 18.18.2 before running the below command: + +``` +npm install +npm install --prefix server +npm install --prefix frontend +npm run build:plugins +``` + + +### 4. Set up database + +``` +npm run --prefix server db:create +npm run --prefix server db:migrate +``` + +If at any point you need to reset the database, use this command `npm run --prefix server db:reset` + +### 5. Build client + +``` +cd ./frontend && NODE=production npm run build +``` + +### 6. Run server + +``` +cd ./server && npm run start:prod +``` + +The client will start on the **port 3000**, you can access the client by visiting the url created by codespace - `https:///apps/tooljet` diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/docker.md b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/docker.md new file mode 100644 index 0000000000..5f847f17e1 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/docker.md @@ -0,0 +1,189 @@ +--- +id: docker +title: Docker +--- + +:::warning +The following guide is intended for contributors to set up ToolJet locally. If you're interested in **self-hosting** ToolJet, please refer to the **[Setup](/docs/setup/)** section. +::: + +Docker Compose is the easiest way to set up the ToolJet server and client locally. + +_If you just want to try out ToolJet locally with docker, you can follow the steps [here](/docs/setup/try-tooljet)._ + +## Prerequisites + +Make sure you have the latest version of `docker` and `docker compose` installed. + +**[Official docker installation guide](https://docs.docker.com/desktop/)** + +**[Official docker-compose installation guide](https://docs.docker.com/compose/install/)** + +## Setting up + +:::warning +If you are setting up on a Windows machine, we advise you to set up Docker Desktop with WSL2. More information is available [here](https://docs.docker.com/desktop/windows/wsl/). + +Make sure to run it within the WSL2 terminal. +::: + +1. Fork the repository: + + Go to the [ToolJet GitHub repository](https://github.com/ToolJet/Tooljet), click on the **Fork** button to create a copy of the repository under your own GitHub account. + +2. Clone your forked repository: + + After forking, clone the forked repository to your local machine using the URL of your forked repo. + +```bash +git clone https://github.com//ToolJet.git +``` + +3. Create a `.env` file by copying `.env.example`. More information on the variables that can be set is given in the **[environment variables reference](/docs/setup/env-vars)**. + +```bash +cp ./deploy/docker/.env.internal.example .env +``` + +4. Populate the keys in the `.env` using the below the command: + +```bash +chmod +x ./deploy/docker/internal.sh && ./deploy/docker/internal.sh +``` + +:::warning +If you are setting up on a Windows machine, please ensure that the .env file line endings are set to LF, as they will be CRLF by default unless configured otherwise. +::: + +5. Build Docker images. + +```bash +docker compose build +docker compose run --rm plugins npm run build:plugins +``` + +6. Run ToolJet. + +```bash +docker compose up +``` + +ToolJet should now be served locally at `http://localhost:8082`. + +7. To shut down the containers, use the below commands: + +```bash +docker compose stop +``` + +## Making changes to the codebase + +If you make any changes to the codebase or pull the latest changes from upstream, the ToolJet server container will hot reload the application without any action required from you. + +**Note:** + +1. If the changes include database migrations or new npm package additions in `package.json`, you need to restart the ToolJet server container by running `docker compose restart server`. + +2. If you need to add a new binary or system library to the container itself, you would need to add those dependencies in `docker/server.Dockerfile.dev` and then rebuild the ToolJet server image. You can do that by running `docker compose build server`. After the build completes, you can start all services by running `docker compose up`. + +Example: +Let's say you need to install the `imagemagick` binary in your ToolJet server's container. You'd then need to make sure that `apt` installs `imagemagick` while building the image. The Dockerfile at `docker/server.Dockerfile.dev` for the server would then look something like this: + +```bash +FROM node:18.18.2-buster AS builder + +RUN apt update && apt install -y \ +build-essential \ +postgresql \ +freetds-dev \ +imagemagick + +RUN mkdir -p /app +WORKDIR /app + +COPY ./server/package.json ./server/package-lock.json ./ +RUN npm install + +ENV NODE_ENV=development + +COPY ./server/ ./ + +COPY ./docker/ ./docker/ + +COPY ./.env ../.env + +RUN ["chmod", "755", "entrypoint.sh"] +``` + +Once you've updated the Dockerfile, rebuild the image by running `docker compose build server`. After building the new image, start the services by running `docker compose up`. + +## Running Tests + +Test config picks up config from `.env.test` file at the root of the project. + +1. Run the following command to create and migrate data for test db: + +```bash +docker compose run --rm -e NODE_ENV=test server npm run db:create +docker compose run --rm -e NODE_ENV=test server npm run db:migrate +``` + +2. To run the unit tests: + +```bash +docker compose run --rm server npm run --prefix server test +``` + +3. To run e2e tests: + +```bash +docker compose run --rm server npm run --prefix server test:e2e +``` + +4. To run a specific unit test: + +```bash +docker compose run --rm server npm --prefix server run test +``` + +## Troubleshooting + +Please open a new issue at https://github.com/ToolJet/ToolJet/issues or join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) if you encounter any issues when trying to run ToolJet locally. + +## Debugging with Docker + +In this section, we provide guidance on how to enable debugging for ToolJet services using Docker and Visual Studio Code. These additions will significantly benefit contributors by streamlining the debugging process and enhancing the overall development experience. + +#### VSCode Launch Configuration: + +A new configuration has been added in `.vscode/launch.json` to facilitate launching the client and server in debug mode. This allows contributors to easily debug the application within the Visual Studio Code environment. Configurations include: + +- **Docker Debug Client**: Launch the client running in a Docker container for debugging within Visual Studio Code. +- **Docker Debug Server**: Debug the server in a Docker container, allowing developers to leverage Node.js debugging tools directly from their IDE. + +#### VSCode Task Configuration: + +A new task has been introduced in `.vscode/tasks.json` to manage Docker Compose commands for debugging. This includes tasks to start the client and server in detached mode, making it easier to initiate debugging sessions. + +#### Docker Compose Debug Configuration: + +The `docker-compose-debug.yaml` file defines the services for debugging, exposing the necessary port (9229) for Node.js debugging. This setup ensures that the server runs in debug mode, allowing for effective troubleshooting. + +### Benefits of Debugging Configuration + +These changes streamline the debugging process, making it more efficient for contributors to identify and fix issues. The integration with Visual Studio Code allows for advanced debugging features such as breakpoints and real-time variable inspection. Furthermore, standardizing the debugging setup fosters better collaboration among team members, facilitating knowledge sharing and improving the overall development workflow. + +By implementing these configurations, ToolJet aims to enhance the development experience, enabling contributors to resolve issues swiftly and maintain project momentum. + +If you want to run docker in debug mode use this command + +```bash +docker-compose -f docker-compose.yaml -f docker-compose-debug.yaml up --build +``` + +**Open the Project in VSCode**: Open the ToolJet directory in Visual Studio Code. + +Check Launch Configurations: + +- Open the debug view by clicking on the Debug icon in the Activity Bar on the side of the window. +- Select the appropriate configuration, such as Docker Debug Client or Docker Debug Server. diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/macos.md b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/macos.md new file mode 100644 index 0000000000..74e94c7ad2 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/macos.md @@ -0,0 +1,150 @@ +--- +id: macos +title: Mac OS +--- + +The following guide is intended for contributors to set-up ToolJet locally. If you're interested in **self-hosting** ToolJet, please refer to the **[Setup](/docs/setup/)** section. + + +To set up and run ToolJet on macOS for development, begin by opening your terminal and executing the commands listed below. For a better understanding of ToolJet's framework, we advise reviewing our [architecture guide](/docs/contributing-guide/setup/architecture) before proceeding. + +## Setting up + +1. Set up the environment + + 1.1 Install Homebrew + ```bash + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" + ``` + + 1.2 Install Node.js ( version: v18.18.2 ) and npm (version: v9.8.1) + ```bash + brew install nvm + export NVM_DIR=~/.nvm + source $(brew --prefix nvm)/nvm.sh + nvm install 18.18.2 + nvm use 18.18.2 + npm install -g npm@9.8.1 + ``` + + 1.3 Install Postgres + :::tip + ToolJet uses a postgres database as the persistent storage for storing data related to users and apps. We do not plan to support other databases such as MySQL. + ::: + + ```bash + brew install postgresql@13 + ``` + + 1.4 Install PostgREST + + :::info + Please use PostgREST version 12.2.0 + ::: + + ```bash + brew install postgrest + ``` + + 1.5 Fork the repository: + + Go to the [ToolJet GitHub repository](https://github.com/ToolJet/Tooljet), click on the **Fork** button to create a copy of the repository under your own GitHub account. + + 1.6 Clone your forked repository: + + After forking, clone the forked repository to your local machine using the URL of your forked repo. + + ```bash + git clone https://github.com//ToolJet.git + ``` + +2. Set up environment variables + + Create a `.env` file by copying `.env.example`. More information on the variables that can be set is given in the [environment variables reference](/docs/setup/env-vars) + ```bash + cp .env.example .env + ``` + +3. Populate the keys in the env file + :::info + `SECRET_KEY_BASE` requires a 64 byte key. (If you have `openssl` installed, run `openssl rand -hex 64` to create a 64 byte secure random key) + + `LOCKBOX_MASTER_KEY` requires a 32 byte key. (Run `openssl rand -hex 32` to create a 32 byte secure random key) + ::: + + Example: + ```bash + cat .env + TOOLJET_HOST=http://localhost:8082 + LOCKBOX_MASTER_KEY=1d291a926ddfd221205a23adb4cc1db66cb9fcaf28d97c8c1950e3538e3b9281 + SECRET_KEY_BASE=4229d5774cfe7f60e75d6b3bf3a1dbb054a696b6d21b6d5de7b73291899797a222265e12c0a8e8d844f83ebacdf9a67ec42584edf1c2b23e1e7813f8a3339041 + NODE_ENV=development + # DATABASE CONFIG + PG_HOST=localhost + PG_PORT=5432 + PG_USER=postgres + PG_PASS=postgres + PG_DB=tooljet_development + TOOLJET_DB=tooljet_db + TOOLJET_DB_USER=postgres + TOOLJET_DB_HOST=localhost + TOOLJET_DB_PASS=postgres + ORM_LOGGING=all + ``` + +4. Install and build dependencies + ```bash + npm install + npm install --prefix server + npm install --prefix frontend + npm run build:plugins + ``` + +5. Set up database + ```bash + npm run --prefix server db:create + npm run --prefix server db:reset + ``` + :::info + If at any point you need to reset the database, use this command `npm run --prefix server db:reset` + ::: + +6. Run plugins compilation in watch mode + ```bash + cd ./plugins && npm start + ``` + +7. Run the server + ```bash + cd ./server && npm run start:dev + ``` + +8. Run the client + ```bash + cd ./frontend && npm start + ``` + + The client will start on the port 8082, you can access the client by visiting: [http://localhost:8082](http://localhost:8082) + +9. Create login credentials + + Visiting [http://localhost:8082](http://localhost:8082) should redirect you to the login page, click on the signup link and enter your email. The emails sent by the server in development environment are captured and are opened in your default browser. Click the invitation link in the email preview to setup the account. + +## Running tests + +Test config requires the presence of `.env.test` file at the root of the project. + +To run the unit tests +```bash +npm run --prefix server test +``` + +To run e2e tests +```bash +npm run --prefix server test:e2e +``` + +To run a specific unit test +```bash +npm run --prefix server test +``` diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/system-requirements.md b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/system-requirements.md new file mode 100644 index 0000000000..7ee71bf0d1 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/system-requirements.md @@ -0,0 +1,24 @@ +--- +id: system-requirements-for-contributing +title: System Requirements +--- + +This page details the system requirements for setting up and running ToolJet on both Docker local and Bare-Metal setups. + +## Docker + +**Windows:** + +When configuring Docker Desktop on your Windows machine, ensure you have a minimum of 16GB RAM for optimal performance. + + +**Mac:** + +For Docker setups on Mac systems, it's advisable to use a machine with 16GB RAM to enhance operational efficiency. + + +## Bare-Metal Setup + +For those who prefer a [bare-metal](/docs/contributing-guide/setup/docker) setup over Docker, a minimum of 8GB RAM is recommended for smooth operation. + +Before initiating the installation process, please verify that your system meets these specified requirements. It's essential to customize server specifications based on the unique demands of your deployment scenario. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/ubuntu.md b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/ubuntu.md new file mode 100644 index 0000000000..91c457bf0f --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/ubuntu.md @@ -0,0 +1,164 @@ +--- +id: ubuntu +title: Ubuntu +--- + +:::warning +The following guide is intended for contributors to set-up ToolJet locally. If you're interested in **self-hosting** ToolJet, please refer to the **[Setup](/docs/setup/)** section. +::: + +Follow these steps to setup and run ToolJet on Ubuntu. Open terminal and run the commands below. + +## Setting up + +1. Set up the environment + + 1.1 Install NVM + ```bash + curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash + ``` + + Use the command to load NVM: + ```bash + source ~/.nvm/nvm.sh + ``` + + Close and reopen your terminal to start using nvm + ```bash + nvm install 18.18.2 + ``` + + Ensure you have the correct version of npm, or it will cause an error about fsevents. + ```bash + npm i -g npm@9.8.1 + ``` + + 1.2 Install Postgres + ```bash + sudo apt install postgresql postgresql-contrib + sudo apt-get install libpq-dev + ``` + + 1.3 Install PostgREST + + :::info + Please use PostgREST version 12.2.0 + ::: + + Please follow the installation [PostgREST](https://postgrest.org/en/stable/install.html) guide + +2. Setup the repository: + + 2.1 Fork the repository: + + Go to the [ToolJet GitHub repository](https://github.com/ToolJet/Tooljet), click on the **Fork** button to create a copy of the repository under your own GitHub account. + + 2.2 Clone your forked repository: + + After forking, clone the forked repository to your local machine using the URL of your forked repo. + + ```bash + git clone https://github.com//ToolJet.git + ``` + +3. Set up environment variables + + Create a `.env` file by copying `.env.example`. More information on the variables that can be set is given in the [environment variables reference](/docs/setup/env-vars) + ```bash + cp .env.example .env + ``` + +4. Populate the keys in the env file + :::info + `SECRET_KEY_BASE` requires a 64 byte key. (If you have `openssl` installed, run `openssl rand -hex 64` to create a 64 byte secure random key) + + `LOCKBOX_MASTER_KEY` requires a 32 byte key. (Run `openssl rand -hex 32` to create a 32 byte secure random key) + ::: + + ToolJet requires the following environment variables to be set. + + ```envs + TOOLJET_HOST=http://localhost:8082 + LOCKBOX_MASTER_KEY= + SECRET_KEY_BASE= + NODE_ENV=development + + PG_HOST=localhost + PG_PORT=5432 + PG_USER=postgres + PG_PASS=postgres + PG_DB=tooljet_development + + TOOLJET_DB=tooljet_db + TOOLJET_DB_USER=postgres + TOOLJET_DB_HOST=localhost + TOOLJET_DB_PASS=postgres + ``` + + ToolJet requires two separate databases to function correctly `pg_db` and `tooljet_db`, + While both databases can reside on the same PostgreSQL host, they must be separate databases to avoid conflicts. + +5. Install and build dependencies + ```bash + npm install + npm install --prefix server + npm install --prefix frontend + npm run build:plugins + ``` + + :::note + If the `npm run build:plugins` command fails due to some packages are missing, try running the following command to install the necessary packages: + `sudo apt install build-essential` + then proceed to `npm run build:plugins` step again. + ::: + +6. Set up database + ```bash + npm run --prefix server db:create + npm run --prefix server db:reset + ``` + :::info + If at any point you need to reset the database, use this command `npm run --prefix server db:reset` + ::: + +7. Run plugins compilation in watch mode + ```bash + cd ./plugins && npm start + ``` + +8. Run the server + ```bash + cd ./server && npm run start:dev + ``` + +9. Run the client + ```bash + cd ./frontend && npm start + ``` + + + The client will start running on the port 8082, you can access the client by visiting: [http://localhost:8082](http://localhost:8082) + +10. Create login credentials + + Visiting https://localhost:8082 should redirect you to the login page, click on the signup link and enter your email. The emails sent by the server in development environment are captured and are opened in your default browser. Click the invitation link in the email preview to setup the account. + + +## Running tests + +Test config requires the presence of `.env.test` file at the root of the project. + +To run the unit tests +```bash +npm run --prefix server test +``` + +To run e2e tests +```bash +npm run --prefix server test:e2e +``` + +To run a specific unit test +```bash +npm run --prefix server test +``` diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/windows.md b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/windows.md new file mode 100644 index 0000000000..e08d76b153 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/setup/windows.md @@ -0,0 +1,18 @@ +--- +id: windows +title: Windows +--- + +To run ToolJet, please install it in an Ubuntu environment using **[Windows Subsystem for Linux 2](https://learn.microsoft.com/en-us/windows/wsl/install-manual#step-2---check-requirements-for-running-wsl-2)**. You can obtain the Ubuntu environment from the **Microsoft Store** by visiting this [link](https://apps.microsoft.com/store/detail/ubuntu-22042-lts/9PN20MSR04DW). + +After successfully installing the Ubuntu environment, you will have access to a terminal window similar to the one shown below: + +
+ Windows setup +
+ +:::warning +If you are setting up ToolJet on a Windows machine, ensure that the line endings in the **.env** file are changed to LF. By default, they may be set to CRLF, which is not compatible unless configured specifically for Windows machines. +::: + +Once the environment is set up, you can proceed with the steps outlined in the Ubuntu documentation at **[Contributing Guide - Ubuntu Setup](/docs/contributing-guide/setup/ubuntu)**. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/slackcoc.md b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/slackcoc.md new file mode 100644 index 0000000000..e9a3f7e4d3 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/slackcoc.md @@ -0,0 +1,90 @@ +--- +id: slackcoc +title: Slack Code of Conduct +--- + +# Slack Code of Conduct + +This code of conduct governs ToolJet's Slack Community events and discussions. + +--- + +## Introduction + +- Diversity and inclusion make our community strong. We encourage participation from the most varied and diverse backgrounds possible and want to be very clear about where we stand. + +- Our goal is to maintain a safe, helpful and friendly community for everyone, regardless of experience, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, nationality, or other defining characteristic. + +- This code and related procedures apply to unacceptable behavior occurring in all community venues, including behavior outside the scope of community activities β€” online and in-personβ€” as well as in all one-on-one communications, and anywhere such behavior has the potential to adversely affect the safety and well-being of community members. + +## Expected behavior + +- Be welcoming. +- Be kind. +- Look out for each other. + +## Unacceptable Behavior + +- Conduct or speech which might be considered sexist, racist, homophobic, transphobic, ableist or otherwise discriminatory or offensive in nature. + - Do not use unwelcome, suggestive, derogatory or inappropriate nicknames or terms. + - Do not show disrespect towards others. (Jokes, innuendo, dismissive attitudes.) +- Intimidation or harassment (online or in-person). +- Disrespect towards differences of opinion. +- Inappropriate attention or contact. Be aware of how your actions affect others. If it makes someone uncomfortable, stop. +- Not understanding the differences between constructive criticism and disparagement. +- Sustained disruptions. +- Violence, threats of violence or violent language. + +## Where does the Code of Conduct apply? + +This Code of Conduct applies to all spaces managed by ToolJet. This includes: + +- Conferences (including social events and peripheral activities) +- Unconferences and sprints +- Meetups, including their discussion boards +- Workshops +- Presentation materials used in talks or sessions +- Slack +- GitHub +- Twitter hashtag and mentions +- Any forums created by the ToolJet which the community uses for communication. + +The Code of Conduct does not exclusively apply to slack or events on an official agenda. For example, if after a scheduled social event you go to a bar with a group of fellow participants, and someone harasses you there, we would still treat that as a CoC violation. Similarly, harassment in Twitter direct messages related to ToolJet can still be covered under this Code of Conduct. + +In addition, violations of this code outside our spaces may affect a person’s ability to participate in them. + +## Enforcement + +- Understand that speech and actions have consequences, and unacceptable behavior will not be tolerated. +- If you are the subject of, or witness to any violations of this Code of Conduct, please contact us via email at hello@tooljet.com or dm @navaneeth on slack. +- If violations occur, organizers will take any action they deem appropriate for the infraction, up to and including expulsion. + +:::info +Portions derived from the [Django Code of Conduct](https://www.djangoproject.com/conduct/), [The Rust Code of Conduct](https://www.rust-lang.org/conduct.html) and [The Ada Initiative](https://adainitiative.org) under a Creative Commons Attribution-ShareAlike license. +::: + +--- + +## Etiquettes to follow + +#### 1. Be nice to everyone + +#### 2. Check off your resolved questions + +If you have received a useful reply to your question, please drop a βœ… reaction or a reply for affirmation. + +#### 3. Try not to repost question + +If you have asked a question and have not got a response in 24hrs, please review your question for clarity and revise it. If you still feel you haven't received adequate response, feel free to ping @navaneeth. + +#### 4. Post in public + +Please don't direct message any individual member of ToolJet community without their explicit permission, independent of reason. Your question might be helpful for other community members. + +#### 5. Don't spam tags + +ToolJet's community of volunteer is very active and helpful, generally avoid tagging members unless it is urgent. + +#### 6. Use threads for discussion + +To keep the main channel area clear, we request to use threads to keep an ongoing conversation organized. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/testing.md b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/testing.md new file mode 100644 index 0000000000..0439d61a9d --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/testing.md @@ -0,0 +1,62 @@ +--- +id: testing +title: Testing +--- + +Follow the steps below to setup and run the test specifications using Cypress. We recommend [setting up ToolJet locally](/docs/contributing-guide/setup/macos) before proceeding. + +## Setting up + +- Navigate to the `cypress-tests` directory and enter the following command: + ```bash + npm install + ``` + +## Running Tests + +#### Headed mode + +- To run cypress in **headed** mode, run the following command: + ```bash + npm run cy:open + ``` +- In **headed** mode, the user will be able to choose the test specs from the test runner: +
+ + Cypress headed mode + +
+ +#### Headless mode + +- To run cypress in **headless** mode, run the following command: + + ```bash + npm run cy:run + ``` + +- To run a specific spec in headless mode, run the following command: + + ```bash + npm run cy:run -- --spec "cypress/e2e/dashboard/multi-workspace/manageSSO.cy.js + ``` + +
+ + Cypress headless mode + +
+ + :::caution + If some test specs need the environment variables, the user can pass them similar to the following command: + + ```bash + npm run cy:open -- --env='{"pg_host":"localhost","pg_user":"postgres", "pg_password":"postgres"}' + ``` + + or the user can add env-vars in the **cypress.config.js** file + ::: + +:::info +Check all the Cypress commands [here](https://docs.cypress.io/guides/guides/command-line#Commands) +::: diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/troubleshooting/eslint.md b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/troubleshooting/eslint.md new file mode 100644 index 0000000000..8caacce4c9 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/troubleshooting/eslint.md @@ -0,0 +1,46 @@ +--- +id: eslint +title: EsLint +--- + +# ESLint + +ESLint as a code quality tool is a tool that checks your code for errors and helps you to fix them and enforces a coding style. + + +## Setup + + +1. Install the [ESLint extension](https://eslint.org/docs/latest/user-guide/integrations) for your code editor. +2. Set your editor's default formatter to `ESLint`. + +:::tip +For VSCode users, you can set the formatter to `ESLint` in the [**settings.json**](https://code.visualstudio.com/docs/getstarted/settings#_settingsjson). +::: + +3. Install the dependencies. + ```bash + npm install + npm install --prefix server + npm install --prefix frontend + ``` +4. Run the linter. + ```bash + npm run --prefix server lint + npm run --prefix frontend lint + ``` +5. Fix the ESlint errors and warnings. + ```bash + npm run --prefix server format + npm run --prefix frontend format + ``` + + +## Requirements + +1. **Node version 18.18.2** +2. **npm version 9.8.1** + +:::tip +It is recommended to check the VSCode **Setting.json**(Press `ctrl/cmnd + P` and search `>Settings (JSON)`) file to ensure there are no overrides to the eslint config rules. Comment the following rules for eslint: **eslint.options: `{...}`**. +::: \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/troubleshooting/runpy-limits.md b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/troubleshooting/runpy-limits.md new file mode 100644 index 0000000000..dd2390612d --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/troubleshooting/runpy-limits.md @@ -0,0 +1,40 @@ +--- +id: runpy-limitations +title: RunPy limitations +--- + +### Limitation: Unable to Open External URLs with urlopen in RunPy + +When using the `urlopen` function within a RunPy query, you may encounter an error when trying to open external URLs, such as `https://api.baserow.io`. This limitation is due to the underlying framework used by RunPy, Pyodide, which has certain constraints and may not support all features available in a standard Python environment. + +### Solution: Using fetch function with JavaScript + +To overcome this limitation, you can utilize the `fetch` function from JavaScript, as Pyodide supports interoperability between Python and JavaScript. Here's an example of how to make an HTTP request using the `fetch` function in a RunPy query: + +```python +from js import fetch +import json + +async def push_data(url, data): + response = await fetch( + url, + method='POST', + headers=[ + ["Authorization", "Token "], + ["Content-Type", "application/json"] + ], + body=data + ) + reply = await response.json() + return reply + +url = "https://api.baserow.io/api/database/rows/table/.../?user_field_names=true" +reply = await push_data(url, json.dumps()) +reply +``` + +In the example above, the `fetch` function is used to make an HTTP POST request to the specified URL. The `Authorization` header is included to provide the necessary authentication token, and the request body is passed as JSON data. + +By using the `fetch` function and incorporating JavaScript interoperability, you can successfully make HTTP requests within a RunPy query in scenarios where `urlopen` may encounter limitations. + +It's important to note that the solution provided here assumes you have the necessary authorization token and data to push to the Baserow table. Adjust the code accordingly to fit your specific requirements. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/tutorials/_category_.json b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/tutorials/_category_.json new file mode 100644 index 0000000000..0d7c9bc587 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/tutorials/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Tutorials", + "position": 2, + "collapsed": true +} diff --git a/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/tutorials/create-widget.md b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/tutorials/create-widget.md new file mode 100644 index 0000000000..999e1999db --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/contributing-guide/tutorials/create-widget.md @@ -0,0 +1,27 @@ +--- +id: creating-widget +title: Creating Widgets +--- + +# Creating Widgets + +These are some of the most useful properties and functions passed to the widget + +### properties + +The `properties` object will contain the configurable properties of a widget, initially obtained from its definition on `widgetConfig.js`. +The values inside `properties` change whenever the developer makes changes to the inspector panel of ToolJet editor. + +### exposedVariables + +The `exposedVariables` object will contain the values of all exposed variables as configured in `widgetConfig.js`. + +### setExposedVariable('exposedVariableName', newValue) + +This function allows you to update the value of an exposed variable to `newValue`. + +### validate(value) + +This function validates the `value` passed based on the validation settings configured on the inspector panel for the widget. +It returns an array `[isValid, validationError]`, which represents respectively, whether the `value` passed is valid, +and the error message if there is one. diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/_category_.json b/docs/versioned_docs/version-3.16.0-LTS/data-sources/_category_.json new file mode 100644 index 0000000000..c6ad9ffd74 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Datasource Reference", + "position": 5, + "collapsed": true +} diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/airtable.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/airtable.md new file mode 100644 index 0000000000..0e104540f0 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/airtable.md @@ -0,0 +1,269 @@ +--- +id: airtable +title: Airtable +--- + +ToolJet can connect to your **Airtable** account to read and write data. + +
+ +## Connection + +To establish a connection with the **Airtable** data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview/)** page from the ToolJet dashboard. + +ToolJet requires the following to connect to your Airtable: +- **Personal Access Token** + +You can generate the Personal Access Token by visiting **[Developer Hub from your Airtable profile](https://support.airtable.com/docs/creating-and-using-api-keys-and-access-tokens#understanding-personal-access-token-basic-actions)**. + +
+ Airtable Data Source Connection +
+ +
+ +:::info +Airtable API has a rate limit, and at the time of writing this documentation, the limit is five(5) requests per second per base. You can read more about rate limits here **[Airtable API](https://airtable.com/api)**. +::: + + +
+ +## Querying Airtable + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **Airtable** datasource added in previous step. +3. Select the desired operation from the dropdown and enter the required parameters. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +Airtable Data Source Operations + +
+ +
+ +## Supported Operations + +- **[List records](#list-records)** +- **[Retrieve record](#retrieve-record)** +- **[Create record](#create-record)** +- **[Update record](#update-record)** +- **[Delete record](#delete-record)** + +
+ +### List Records + +This operation retrieves a list of records from the specified table. + +#### Required Parameters + +- **Base ID**: The unique identifier of the Airtable base. +- **Table name**: The name or ID of the table to retrieve records from. + +#### Optional Parameters* + +- **Page size**: The number of records to return per page. +- **Offset**: Used for pagination to fetch the next set of records. +- **Filter by formula**: A formula to filter records. +- **Fields**: Specifies which fields to include in the response. +- **Timezone**: The timezone to use for date and time fields. +- **User locale**: The locale to use for formatting date and time fields. +- **Cell format**: Determines how cell values are returned. Possible values are: + - **json**: Returns cell values as JSON objects, depending on the field type. + - **string**: Returns cell values as strings. +- **View**: Specifies the view to retrieve records from. +- **Sort**: Defines the sorting order of records. + +:::info +Timezone and User locale are mutually dependent. If you provide a timezone, you must also provide a user locale and vice versa. These properties are only applied when cell format is set to string. To correctly format date and time fields, make sure the coloumn type is set to Date or Date Time in Airtable. +::: + +Airtable List Records Query + + +
+**Example Values** + +```json +Base ID: appO4WnRU3eTWnrDB +Table name: tblAPbj6KMjS8pxhH // Can be Table name or Table ID +Page size: 100 +Offset: itrU18e2y6ITuMs1n/recjR8UdOZKjZ7aK3 +Fields: ["Date", "Email", "Usage (# Weeks)"] +Filter by formula: IF({Usage (# Weeks)} < 10, 1, 0) // Only records with Usage (# Weeks) less than 10 +Timezone: America/Chicago +User locale: en-gb +Cell format: string // Cell format needs to be string for Timezone and User locale to work +View: All Responses +Sort: createdTime // Select direction: Ascending or Descending +``` + +
+ + +
+ **Response Example** + + ```json + { + "records": [ + { + "id": "recToGRP6bWUG6djd", + "createdTime": "2016-11-21T20:21:40.000Z", + "fields": { + "Usage (# Weeks)": "3", + "Email": "Edith Lindon", + "Date": "11-21-2016" + } + }, + { + "id": "recnUVJ8wwZbdECLk", + "createdTime": "2016-11-21T20:21:40.000Z", + "fields": { + "Usage (# Weeks)": "3", + "Email": "Marcellus Wong", + "Date": "11-21-2016" + } + }, + { + "id": "recStKhQYw4Fn2qpj", + "createdTime": "2016-11-21T20:21:40.000Z", + "fields": { + "Usage (# Weeks)": "2", + "Email": "Lorraine Ljuba", + "Date": "11-21-2016" + } + } + ] + } + ``` +
+ +### Retrieve Record + +This operation fetches a specific record from the specified table. + +#### Required Parameters + +- **Base ID** +- **Table name** +- **Record ID** + +Airtable Retrieve Record Query + +
+ **Response Example** + ```json + { + "id": "recu9xMnUdr2n2cw8", + "fields": { + "Notes": "Discuss project timeline", + "Name": "Michael Scott" + }, + "createdTime": "2021-05-12T14:30:33.000Z" + } + ``` +
+ +### Create Record + +This operation creates a new record in the specified table. + +#### Required Parameters + +- **Base ID** +- **Table name** +- **Records** + +Airtable Create Record Query + +#### Example + +```json title="Records" +[{ + "fields": { + "Name": "Katrina Petersons", + "Email": "katrina.petersions@example.com" + } +}] +``` +
+ **Response Example** + ```json + { + "records": [ + { + "id": "recu6jhA7tzv4K66s", + "createdTime": "2024-06-11T06:01:44.000Z", + "fields": { + "Name": "Katrina Petersons", + "Email": "katrina.petersions@example.com", + "Date": "06-11-2024", + } + } + ] + } + ``` +
+ +### Update record + +Update a specific record by providing new data. + +#### Required parameters: + +- **Base ID** +- **Table name** +- **Record ID** +- **Body** + +Airtable Update Record Query + +#### Example + +```json +{ + "Email": "katrina.petersions2@example.com" +} +``` +
+ **Response Example** + ```json + { + "records": [ + { + "id": "recu6jhA7tzv4K66s", + "createdTime": "2024-06-11T07:01:44.000Z", + "fields": { + "Name": "Katrina Petersons", + "Email": "katrina.petersions2@example.com", + "Date": "06-11-2024", + } + } + ] + } + ``` +
+ +### Delete record + +This operation removes a record from the specified table. + +#### Required parameters: + +- **Base ID** +- **Table name** +- **Record ID** + +Airtable Delete Record Query + +
+ **Response Example** + ```json + { + deleted: true + id: "recIKsyZgqI4zoqS7" + } + ``` +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/amazonses.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/amazonses.md new file mode 100644 index 0000000000..9563584a86 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/amazonses.md @@ -0,0 +1,77 @@ +--- +id: amazonses +title: Amazon SES +--- + +ToolJet can connect to your Amazon SES account to send emails. + +
+ +## Connection + +To establish a connection with the **Amazon SES** data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page through the ToolJet dashboard. + +ToolJet requires the following to connect to Amazon SES: + +- **Region** +- **Authentication** +- **Access key** +- **Secret key** + +**Note:** It is recommended to create a new IAM user for the database so that you can control the access levels of ToolJet. + +
+ +Amazon SES + +
+ +
+ +
+ +## Querying Amazon SES + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **Amazon SES** datasource added in previous step. +3. Select **Email service** as operation from the dropdown and enter the required parameters. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +Amazon SES + +
+ +
+ +## Supported Operation + +### Email service + +#### Required parameters: +- **Send email to** +- **Send email from** +- **Subject** +- **Body** + + +#### Optional parameters: +- **CC Addresses** +- **BCC Addresses** + +Amazon SES + + +:::info +**Send mail to** - accepts an array/list of emails separated by comma. +For example: +`{{["dev@tooljet.io", "admin@tooljet.io"]}}`. + +**Send mail from** - accepts a string. +For example: `admin@tooljet.io` +::: + +:::tip +**Send a single email to multiple recipients** - The `Send mail to` field can contain an array of recipients, which will send a single email with all of the recipients in the field. +::: + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/appwrite.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/appwrite.md new file mode 100644 index 0000000000..b7ca75656f --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/appwrite.md @@ -0,0 +1,149 @@ +--- +id: appwrite +title: Appwrite +--- + +ToolJet can connect to appwrite database to read/write data. + +
+ +## Connection + +To establish a connection with the Appwrite data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page from the ToolJet dashboard. + +ToolJet requires the following to connect to your Appwrite: + +- **Host (API endpoint)** +- **Project ID** +- **Secret Key** + +You'll find the Secret Key and other credentials on your Appwrite's project settings page. You may need to create a new key if you don't have one already. + +:::info +You should also set the scope for access to a particular resource. Learn more about the **API keys and scopes** [here](https://appwrite.io/docs/keys). +::: + +
+ +Appwrite intro + +
+ +
+ +
+ +## Querying Appwrite + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **Appwrite** datasource added in previous step. +3. Select the operation you want to perform. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +
+ +Appwrite intro + +
+ +:::tip +Query results can be transformed using Transformations. Read our **Transformation Documentation** [here](/docs/beta/app-builder/custom-code/transform-data). +::: + +
+ +
+ +## Supported Operations + +- **[List Documents](#list-documents)** +- **[Get Document](#get-document)** +- **[Add Document to Collection](#add-document-to-collection)** +- **[Update Document](#update-document)** +- **[Delete Document](#delete-document)** + +### List Documents + +This operation is used to get a list of all the user documents. + +#### Required Parameters + +- **Collection ID** + +#### Optional Parameters + +- **Limit** +- **Order fields** +- **Order types** +- **Field** +- **Operator** +- **Value** + +
+ +Appwrite List + +
+ +### Get Document + +Use this operation to get a document from a collection by its unique ID. + +#### Required Parameters + +- **Collection ID** +- **Document ID** + +
+ +Appwrite get + +
+ +### Add Document to Collection + +Use this operation to create a new document in a collection. + +#### Required Parameters + +- **Collection ID** +- **Body** + +
+ +Appwrite add + +
+ +### Update Document + +Use this operation to update a document. + +#### Required Parameters + +- **Collection ID** +- **Document ID** +- **Body** + +
+ +Appwrite update + +
+ +### Delete Document + +Use this operation for deleting a document in the collection. + +#### Required Parameters + +- **Collection ID** +- **Document ID** + +
+ +Appwrite delete + +
+ +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/athena.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/athena.md new file mode 100644 index 0000000000..215d334494 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/athena.md @@ -0,0 +1,103 @@ +--- +id: athena +title: Athena +--- + +ToolJet can connect to **Amazon Athena** which is an interactive query service that makes it easy to analyze data in Amazon S3 using standard SQL. + +
+ +## Connection + +To establish a connection with the **Amazon Athena** data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page from the ToolJet dashboard and choose **Amazon Athena** as the data source. + +ToolJet requires the following to connect to your Athena. + +- **Database** +- **S3 output location** +- **Access key** +- **Secret key** +- **Region** + +:::info +You can also configure for **[additional optional parameters](https://github.com/ghdna/athena-express)**. +::: + +
+ +Athena connection + +
+ +
+ +
+ +## Querying Amazon Athena + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **Amazon Athena** datasource added in previous step. +3. Select the SQL Query from the dropdown and enter the query. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +:::tip +**Refer amazon athena docs here for more info:** [link](https://docs.aws.amazon.com/athena/latest/ug/what-is.html) +::: + +
+ +Athena connection + +
+ +
+ +
+ +## Basic Queries + +### Creating Table + +This query is used to create an external table within the database. The data for this table is stored in an S3 bucket at the provided URL (`s3://athena-express-akiatfa53s-2022/` in this example). + +```sql +CREATE EXTERNAL TABLE student ( + name STRING, + age INT +) LOCATION 's3://athena-express-akiatfa53s-2022/'; +``` + +Athena connection + +### Inserting to Table + +This query is attempting to insert a new record into the *student* table in a database. + +```sql +INSERT INTO student +VALUES ('Lansing',1) +``` + +Athena connection + +### Select Operation + +This query retrieves all records from the *student* table where the age of the student is exactly 1 year. + +```sql +SELECT * from student WHERE AGE=1 +``` + +Athena connection + +### List Tables + +This query is used to display a list of all tables in the current database. + +```sql +SHOW TABLES +``` + +Athena connection + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/azureblob.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/azureblob.md new file mode 100644 index 0000000000..9a206f24d4 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/azureblob.md @@ -0,0 +1,142 @@ +--- +id: azureblobstorage +title: Azure Blob +--- + +ToolJet offers the capability to establish a connection with Azure Blob storage in order to read and store large objects. + +## Connection + +To establish a connection with the Azure Blob data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page from the ToolJet dashboard and choose Azure Blob as the data source. + +ToolJet requires the following to connect to your Azure Blob. + +- **Connection String** + +
+ +Azure Blob - ToolJet + +
+ +
+ +## Querying Azure Blob + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **Azure Blob** datasource added in previous step. +3. Select the desired **operation** from the dropdown and enter the required **parameters**. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +:::tip +Query results can be transformed using Transformation. For more information on transformations, please refer to our documentation at **[link](/docs/beta/app-builder/custom-code/transform-data)**. +::: + +
+ +Azure Blob - ToolJet + +
+ +
+ +
+ +## Supported Operations + +1. **[Create container](#create-container)** +2. **[List containers](#list-containers)** +3. **[List blobs](#list-blobs)** +4. **[Upload blob](#upload-blob)** +5. **[Read blob](#read-blob)** +6. **[Delete blob](#delete-blob)** + +### Create Container + +The create container operation enables the creation of new containers within Azure Blob storage. Containers serve as logical units for organizing and managing blob data. Users can provide a unique name for the container. Once created, the container is available for use in storing and organizing blob data. If the container with the same name already exists, the operation fails. + +#### Required Parameters + +- **Container Name** + +
+ +Azure blob: create container operation + +
+ +### List Containers + +The list container operation allows you to retrieve a list of containers within Azure Blob storage. + +
+ +Azure blob: list container operation + +
+ +### List Blobs + +The list blobs operation enables you to retrieve a list of blobs within a specific container in Azure Blob storage. + +#### Required Parameter + +- **Container** +- **Page Size** + +#### Optional Parameters + +- **Prefix** +- **Continuation Token** + +
+ +Azure blob: list blobs operation + +
+ +### Upload Blob + +The upload blob operation allows you to upload a new blob or update an existing blob in Azure Blob storage. It provides a convenient way to store data such as files, images, or documents in the specified container. + +#### Required Parameters + +- **Container** +- **Blob Name** +- **Content Type** +- **Upload Data** +- **Encoding** + +Azure blob: upload blobs operation + +### Read Blob + +The read blob operation allows you to retrieve the content of a specific blob stored in Azure Blob storage. It enables you to access and retrieve the data stored within the blob for further processing or display. + +#### Required Parameters + +- **Container** +- **Blob Name** + +
+ +Azure blob: read blob operation + +
+ +### Delete Blob + +The delete blob operation allows you to remove a specific blob from Azure Blob storage. This operation permanently deletes the blob and its associated data, freeing up storage space and removing the blob from the container. + +#### Required Parameters + +- **Container** +- **Blob Name** + +
+ +Azure blob: delete blob operation + +
+ +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/baserow.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/baserow.md new file mode 100644 index 0000000000..28af4a4327 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/baserow.md @@ -0,0 +1,292 @@ +--- +id: baserow +title: Baserow +--- + +ToolJet can connect to your Baserow account to read and write data. + +
+ +## Connection + +To establish a connection with the **Baserow** data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page through the ToolJet dashboard. + +ToolJet requires the following to connect to Baserow: + +- **API token** +- **Host** +- **Base URL** + +
+ +Baserow intro + +
+ +
+ +
+ +## Querying Baserow + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **Baserow** datasource added in previous step. +3. Select the desired operation from the dropdown and enter the required parameters. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +Amazon SES + +
+ +
+ +## Supported Operations + +- **[List fields](#list-fields)** +- **[List rows](#list-rows)** +- **[Get row](#get-row)** +- **[Create row](#create-row)** +- **[Update row](#update-row)** +- **[Move row](#move-row)** +- **[Delete row](#delete-row)** + +### List Fields + +This query lists all the fields in a table. + +#### Required Parameter + +- **Table ID** + +Baserow list fields + +
+ **Response Example** + + ```yaml + [ + { + "id": 331156, + "table_id": 57209, + "name": "Name", + "order": 0, + "type": "text", + "primary": true, + "text_default": "" + }, + { + "id": 331157, + "table_id": 57209, + "name": "Last name", + "order": 1, + "type": "text", + "primary": false, + "text_default": "" + }, + { + "id": 331158, + "table_id": 57209, + "name": "Notes", + "order": 2, + "type": "long_text", + "primary": false + }, + { + "id": 331159, + "table_id": 57209, + "name": "Active", + "order": 3, + "type": "boolean", + "primary": false + } + ] + ``` + +
+ +### List Rows + +This query lists all the rows in a table. + +#### Required Parameter + +- **Table ID** + +Baserow list + +
+ **Response Example** + + ```json + { + "count": 3, + "next": null, + "previous": null, + "results": [ + { + "id": 2, + "order": "0.99999999999999999991", + "Name": "Bill", + "Last name": "Gates", + "Notes": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce dignissim, urna eget rutrum sollicitudin, sapien diam interdum nisi, quis malesuada nibh eros a est.", + "Active": false + }, + { + "id": 3, + "order": "0.99999999999999999992", + "Name": "Mark", + "Last name": "Zuckerberg", + "Notes": null, + "Active": true + }, + { + "id": 1, + "order": "0.99999999999999999997", + "Name": "Elon", + "Last name": "Musk", + "Notes": null, + "Active": true + } + ] + } + ``` + +
+ +### Get Row + +#### Required Parameters + +- **Table ID** +- **Row ID** + +Baserow get + +
+ **Response Example** + + ```json + { + "id": 1, + "order": "0.99999999999999999997", + "Name": "Elon", + "Last name": "Musk", + "Notes": null, + "Active": true + } + ``` + +
+ +### Create Row + +#### Required Parameters +- **Table ID** +- **Records** + +Bserow create + +#### Example + +```json +{ + "Name": "Test", + "Last name": "Test Name", + "Notes": "Test Note", + "Active": true +} +``` + +
+ **Response Example** + + ```json + { + "id": 19, + "order": "0.99999999999999999996", + "Name": "Test", + "Last name": "Test Name", + "Notes": "Test Note", + "Active": true + } + ``` + +
+ +### Update Row + +#### Required Parameters + +- **Table ID** +- **Row ID** +- **Records** + +Baserow update + +#### Example + +```json +{ + "Name": "Test", + "Last name": "Test Name", + "Notes": "Test Note", + "Active": true +} +``` + +
+ **Response Example** + + ```json + { + "id": 19, + "order": "0.99999999999999999996", + "Name": "Test", + "Last name": "Test Name", + "Notes": "Test Note", + "Active": true + } + ``` + +
+ +### Move Row + +#### Required Parameters + +- **Table ID** +- **Row ID** + +#### Optional Parameters + +- **Before ID** (The row will be moved before the entered ID. If not provided, then the row will be moved to the end ) + +Baserow move row + +
+ **Response Example** + + ```json + { + "id": 3, + "order": "2.00000000000000000000", + "Name": "Mark", + "Last name": "Zuckerburg", + "Notes": null, + "Active": true + } + ``` + +
+ +### Delete Row + +#### Required Parameters +- **Table ID** +- **Row ID** + +Baserow delete + +While deleting a row, the response will be either success or failure from Baserow. + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/bigquery.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/bigquery.md new file mode 100644 index 0000000000..671b7b64ad --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/bigquery.md @@ -0,0 +1,197 @@ +--- +id: bigquery +title: BigQuery +--- + +ToolJet can connect to **BigQuery** databases to run BigQuery queries. + +
+ +## Connection + +To establish a connection with the **BigQuery** data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page from the ToolJet dashboard and choose BigQuery as the data source. + +ToolJet requires the following to connect to your BigQuery: + +- **Private key** + +How to get a Private key? + +1. You need to enable BigQuery API in your Google Cloud Console. You can follow the steps to enable BigQuery API from **[Google Cloud](https://cloud.google.com/bigquery/docs/bigquery-web-ui)**. +2. You need to create a service account and generate a key for the same. You can follow the steps to create a service account from **[Google Cloud](https://cloud.google.com/iam/docs/creating-managing-service-accounts)**. +3. Once you have created the service account after following the steps mentioned in the Google Cloud guide, create a new **Key** and download it in a JSON file. +4. Now, copy and paste the data from the downloaded JSON file into the **Private key** field in the BigQuery data source form. + +BQ create + +**The JSON file should look like this:** + +```json +{ + "type": "service_account", + "project_id": "long-sonar-324407", + "private_key_id": "63f4415e600bd7879bc14fd1157a4aabe227c204", + "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDRGgDmfwYcKp4q\n3ce4DkrKv0vTn/Jn2Z2vEHp+oOz5ebZqmE3v56c6YIvtVRblANILPrOsB5ZvkF5f\nEzZBXn7ZI3+dqKBrpxbJqF6bKTLENdgFZRTbXHtGDpmwX4A+ufir9QNoezRw0i5L\nnVZiVC54f/Qt/cKT8794qSnrxNX1TneZLGxJWou9VAl3xT9h2HdL56gYIuleWXDK\nnXkb3Leh9AMZCdFPMyC24MWefWrUbNkqJ7V8FHo7bMrAcFNuSoF2NfK1v6IPLkEs\nwAU0CJ9VSg6rrahQOqIJ04cdYs2OUh4lRvRB6pqlVvtl6EdJB6dHln1nDzpgHbnb\n+acfwEDnAgMBAAECggEAGs/mSKgGDQuL73wztU6j2X6RBwhN6XIWjZGj22PgLxcj\nxGRWLgp6v3oMxzhvcJrb1BRMrqTkbdbJuxA4F0a6JjaukPVD6Lnqqp37z5KHT3CG\nDB8LfxtLNU7+9wYv6Bspn0cSEk4mCcdxp0F8B6y6rrndgh41WopZRWwPk4tQUh1r\nor67AAYd3rtzGMLoghs+8UE+UYa8wbpsbmHEYgqvXQAkNsl8WdNwqmI0G4lf+pgx\n7Rm27LJrtdBBHc48RUhg2eiN05HLCsnwkrnSj0rLL/L7T1yoSfCSUuv1mTUesxQ1\nXUEsPQQTTsNsqKOxT71CzQLElrPfwZkN4Y/IOJqX3QKBgQD6u0idi2r54hMjBSuk\npLgXygH5AWfHc4QqMCui7HZrFOJ4U4AreI/zZrM3Gemgs+1l27wsUjoxADW2Egyq\nX5AVe94RKSV3cCIIty38VOUBVsgyxj38d8yWkpJKJ2FcAgqEzPDDo0TCaOEq01oA\nYqjkgBz7Sh4XhQ5xwzfnOPRPtQKBgQDVfsly/k03wAJo1xlUZeq9mAnba5Hz07x9\nJ3REAwrtOaD891rKbkqDZKdGHTMweFGeEW2Hx7Q5iRS4WDKFO14wgSHFTkkVoSKR\n2W7XMomUQPFojQwgkDhrxsGE8O1DqfQ0+A5AJn2ASv/cyVGE3V2xg2rGr/HWi6Wq\nUp4FxebXqwKBgQDNIcCNNG03N6EUe7xzHViIDfuDL4UqhvXQVky9JNzVSubmLtqj\ntiV/q7xgDlE36z0EorvXPwbg5B0NcsLt+PU2vnq2a4V9rD4MB2IWGZaqe8ea0toP\n3iuB3TTWelWLIxhcAhfQ15j/vTLLCNOPkShAmhgb902bTH6+0ErCX7RyKQKBgQCe\nDOeLpvF5VT8zaBILZgva4eRiOQdqz5RZvsyW0P3U0vX4cBIZjH7DOM+Q22sa9efO\nMi6490HX2kCpnDmCYon/NInQrHz0cz7JZINm8rXhOBa/hLO2o63xM8nt5gJwNjBg\nykaafSQpxtwWEj+0McD7+kMg5f4OC4HQTqtHsNONUwKBgAoWGGRPja068BPIiUMB\nezsdYPP5TdASiBeAEPaQXQHlJxPDu9KoKqM5xvWIdR8eH1z7cuQ3RP89hYT03/UT\nBvWXHk2MJQZK7BZDw9KMZAKexK9/qxwHS6i7HhErD+Au3UaRX8dfjJzX8WAwuAwp\nVDwHncN3n4mPFQl7eijnQZ/F\n-----END PRIVATE KEY-----\n", + "client_email": "tooljettest@long-sonar-324407.iam.gserviceaccount.com", + "client_id": "103664451567222591066", + "auth_uri": "https://accounts.google.com/o/oauth2/auth", + "token_uri": "https://oauth2.googleapis.com/token", + "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", + "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/tooljettest%40long-sonar-324407.iam.gserviceaccount.com", + "universe_domain": "googleapis.com" +} +``` + +
+ +
+ +## Querying BigQuery + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **BigQuery** datasource added in previous step. +3. Select the desired operation from the dropdown and enter the required parameters. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +
+ +BQ query + +
+ +:::tip +Query results can be transformed using transformations. Read our transformations documentation to see how: [link](/docs/beta/app-builder/custom-code/transform-data) +::: + +
+ +
+ +## Supported Operations + +- **[Query](#query)** +- **[List Datasets](#list-datasets)** +- **[List Tables](#list-tables)** +- **[Insert Record ](#insert-record)** +- **[Delete Record ](#delete-record)** +- **[Update Record](#update-record)** +- **[Create View](#create-view)** +- **[Create Table](#create-table)** +- **[Delete Table](#create-table)** + +### Query + +This operation returns the data based on the **Query**. + +**Note**: Follow the reference given in **Google Cloud** about the operations: **[Query options](https://cloud.google.com/bigquery/docs/reference/rest/v2/Job)** and **[Query results options](https://cloud.google.com/nodejs/docs/reference/bigquery/latest/overview#_google_cloud_bigquery_QueryResultsOptions_type)**. + +#### Required Parameters + +- **Query** +- **Query options** +- **Query results options** + +BQ query + +### List Datasets + +This operation returns the list of datasets. + +BQ list datasets + +### List Tables + +This operation returns the list of tables within a dataset. + +#### Required Parameter + +- **Dataset ID** + +BQ list tables + +### Create Table + +This operation is used to create a table. + +#### Required Parameters + +- **Table ID** +- **Dataset ID** +- **Options** + +BQ create tables + +**NOTE:** Visit https://github.com/googleapis/nodejs-bigquery/blob/main/samples/createTable.js for more info on schema. + +### Delete Table + +This operation is used to delete a table. + +#### Required Parameters + +- **Table ID** +- **Dataset ID** + +BQ delete tables + +### Create View + +This operation is used to create a view. + +#### Required Parameters + +- **Table ID** +- **Dataset ID** +- **View name** +- **View columns** +- **Condition** +- **Query options** +- **Query results options** + +BQ create view + +### Insert Record + +This operation is used to insert a record. + +#### Required parameters: + +- **Table ID** +- **Dataset ID** +- **Rows** + +BQ insert + +### Delete Record + +Use this operation to delete a record. + +#### Required parameters: + +- **Table ID** +- **Dataset ID** +- **Condition** +- **Query options** +- **Query results options** + +BQ delete + +:::warning +NOTE: Be careful when deleting records in a table. If you omit the WHERE clause, all records in the table will be deleted! +::: + +### Update Record + +Use this operation to update a record. + +#### Required parameters: + +- **Table ID** +- **Dataset ID** +- **Columns** +- **Condition** +- **Query results options** + +BQ update + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/clickhouse.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/clickhouse.md new file mode 100644 index 0000000000..4f01ec89aa --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/clickhouse.md @@ -0,0 +1,174 @@ +--- +id: clickhouse +title: ClickHouse +--- + +ToolJet can connect to the ClickHouse to read and write data. + +:::info +ToolJet uses this [NodeJS](https://github.com/TimonKK/clickhouse) client for ClickHouse. +::: + +## Connection + +To establish a connection with the Clickhouse data source, you can either click on the **+ Add new data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page through the ToolJet dashboard. + +ToolJet requires the following to connect to your ClickHouse Database: + +- **Username** +- **Password** +- **Host** +- **Port** +- **Database Name** +- **Protocol** +- **Use Post** +- **Trim Query** +- **Use Gzip** +- **Debug** +- **Raw** + +ClickHouse connection + +
+ +## Querying ClickHouse + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **ClickHouse** datasource added in previous step. +3. Select the operation you want to perform and enter the query. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to create and trigger the query. + +:::info +For more details on clickhouse visit [Clickhouse Docs](https://clickhouse.com/docs/en/quick-start). +::: + +
+ +
+ +## Supported Operations + +- **[SQL Query](#sql-query)** +- **[Insert array of objects](#insert-array-of-objects)** + +### SQL Query + +Use this to operation to enter **[ClickHouse SQL Statements](https://clickhouse.com/docs/en/sql-reference/statements/)**. These statements represent various kinds of action you can perform using SQL queries. + +#### Example SQL queries + +#### SELECT: + +```sql +SELECT * from test array; +``` + +ClickHouse SQL Statement operation + +#### CREATE: + +```sql +CREATE TABLE test array3 ( + date Date, + str String, + arr Array(String), + arr2 Array (Date) + arr3 Array(UInt32) , + id1 UUID +)ENGINE=MergeTree () ORDER BY(str) +``` + +ClickHouse SQL Statement operation + +#### ALTER TABLE (add column) + +```sql +ALTER TABLE test array1 ADD COLUMN Added2 UInt32; +``` + +ClickHouse SQL Statement operation + +#### SELECT WITH WHERE CLAUSE +```sql +SELECT * FROM test array1 WHERE str='Somethingl...' +``` + +ClickHouse SQL Statement operation + +#### UPDATE +```sql +ALTER TABLE test_array1 UPDATE arr = (12] WHERE str='Somethingl...' +``` + +ClickHouse SQL Statement operation + +#### DELETE +```sql +ALTER TABLE test_array1 DELETE WHERE str= 'Somethingl...' +``` + +ClickHouse SQL Statement operation + +#### NORMAL INSERT + +##### Step 1 - Creating Table + +```sql +CREATE TABLE test array4 ( + name String, + date Date +)ENGINE=MergeTree () ORDER BY (name) +``` + +ClickHouse SQL Statement operation + +#### Step 2 - Insert + +```sql +INSERT INTO test_array4 (*) VALUES ('juvane', '1996-01-13') +``` + +ClickHouse SQL Statement operation + +:::info +**Giving Primary Key** +```sql +CREATE TABLE db.table_name +( + name1 type1, name2 type2, ..., + PRIMARY KEY(expr1[, expr2,...])] +) +ENGINE = engine; + +OR + +CREATE TABLE db.table_name +( + name1 type1, name2 type2, ... +) +ENGINE = engine +PRIMARY KEY(expr1[, expr2,...]); +``` +::: + +### Insert Array of Objects + +Use this operation for inserting array of objects. + +#### Required Parameters: +- **Body** +- **Table name** +- **Fields** + +**Example Body value:** +```javascript +[ + { "id": 1, "name": "Alice", "age": 25 }, + { "id": 2, "name": "Bob", "age": 30 }, + { "id": 3, "name": "Charlie", "age": 28 } +] +``` + +ClickHouse Insert array of objects operation + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/cosmosdb.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/cosmosdb.md new file mode 100644 index 0000000000..2b792319e2 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/cosmosdb.md @@ -0,0 +1,128 @@ +--- +id: cosmosdb +title: CosmosDB +--- + +ToolJet can connect to CosmosDB databases to read and write data. + +## Connection + +To establish a connection with the CosmosDB data source, you can either click on the **+ Add new data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page through the ToolJet dashboard. + +ToolJet requires the following to connect to your Cosmos DB. + +- **Cosmos DB Account End point** +- **Cosmos DB Account Key** + +:::info +**Azure Cosmos DB End Point** is the URL of the Cosmos DB service. +**Azure Cosmos DB Key** is the key that is used to access the Cosmos DB service. +You can find the endpoint and key in the **[Azure Portal](https://portal.azure.com/)**. +::: + +
+ +ToolJet - Data source - CosmosDB + +
+ +
+ +## Querying CosmoDB + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **CosmoDB** datasource added in previous step. +3. Select the operation you want to perform and enter the query. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to create and trigger the query. + +ToolJet - Data source - CosmosDB + +
+ +
+ +## Supported Queries + +- **[List databases](#list-databases)** +- **[List containers](#list-containers)** +- **[Insert items](#insert-items)** +- **[Read item](#read-item)** +- **[Delete item](#delete-item)** +- **[Query database](#query-database)** + +### List Databases + +This query lists all the databases in a Cosmos DB. + +ToolJet - Data source - CosmosDB + +### List Containers + +This query lists all the containers of a database in a Cosmos DB. + +#### Required Parameter +- **Database** + +ToolJet - Data source - CosmosDB + +### Insert Items + +This query inserts one or more items in a container of a database in a Cosmos DB. + +#### Required Parameter +- **Database** +- **Container** +- **Items** + +ToolJet - Data source - CosmosDB + +#### Example + +```yaml +{ + "id": "123", + "product": "Laptop", + "price": 1200, + "customer_id": "C001" +} +``` + +### Read Item + +To read a single item from a container of a database in a Cosmos DB, use the following query. + +#### Required Parameter +- **Database** +- **Container** +- **Item ID** + +ToolJet - Data source - CosmosDB + +### Delete Item + +To delete an item from a container of a database in a Cosmos DB, use the following query. + +#### Required Parameter +- **Database** +- **Container** +- **Item ID** + +ToolJet - Data source - CosmosDB + +### Query Database + +To query documents from a container of a database in a Cosmos DB using SQL-like syntax, use the following query. + +#### Required Parameter +- **Database** +- **Container** +- **Query** + +ToolJet - Data source - CosmosDB + +#### Example +```yaml +SELECT * FROM c WHERE c.age > 20 AND c.age <= 30 +``` + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/couchdb.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/couchdb.md new file mode 100644 index 0000000000..ef7a46561d --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/couchdb.md @@ -0,0 +1,284 @@ +--- +id: couchdb +title: CouchDB +--- + +ToolJet can connect to CouchDB databases to read and write data. + +
+ +## Connection + +To establish a connection with the CouchDB data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page through the ToolJet dashboard. + +ToolJet requires the following to connect to your CouchDB. +- **Username** +- **Password** + +Couch listing + +
+ +
+ +## Querying CouchDB + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **CouchDB** datasource added in previous step. +3. Select the operation you want to perform and enter the query. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to create and trigger the query. + +Couch listing + +
+ +
+ +## Supported Queries + +- **[List Records](#list-records)** +- **[Retrieve Record](#retrieve-record)** +- **[Create Record](#create-record)** +- **[Update Record](#update-record)** +- **[Delete Record](#delete-record)** +- **[Find](#find)** +- **[Get View](#get-view)** + +### List Records + +This query lists all the records in a database. + +#### Optional Parameters + +- **Include docs** +- **Descending order** +- **Limit** +- **Skip** + +Couch listing + +
+ **Response Example** + ```json +{ + "total_rows": 3, + "offset": 0, + "rows": [ + { + "id": "23212104e60a71edb42ebc509f000dc2", + "key": "23212104e60a71edb42ebc509f000dc2", + "value": { + "rev": "1-0cc7f48876f15883394e5c139c628123" + } + }, + { + "id": "23212104e60a71edb42ebc509f00216e", + "key": "23212104e60a71edb42ebc509f00216e", + "value": { + "rev": "1-b3c45696b10cb08221a335ff7cbd8b7a" + } + }, + { + "id": "23212104e60a71edb42ebc509f00282a", + "key": "23212104e60a71edb42ebc509f00282a", + "value": { + "rev": "1-da5732beb913ecbded309321cac892d2" + } + }, + ] +} +``` +
+ +### Retrieve Record + +This operation fetches a single record by its record ID. + +#### Required Parameters: + +- **Record ID** + + +Couch retrieve view + +
+ **Response Example** +```json +{ + "_id": "e33dc4e209689cb0400d095fc401a1e0", + "_rev": "1-a62af8e14451af88c150e7e718b7a0e8", + "0": { + "name": "test data" + } +} +``` +
+ +### Create Record + +Inserts a new record into the database. + +#### Required Parameters: + +- **Records** + + +Couch create view + +#### Example + +```json + [{"name":"tooljet"}] +``` + +
+ **Response Example** + ```json + { + "ok": true, + "id": "23212104e60a71edb42ebc509f0049a2", + "rev": "1-b0a625abc4e21ee554737920156e911f" + } + ``` +
+ +### Update Record + +You can get the revision id value, by sending a GET request to get the document details. +You get the document as JSON in the response. For each update to the document, the revision field "_rev" gets changed. + +#### Required Parameters: +- **Record ID** +- **Revision ID** + + +Couch update view + + +#### Example + +```json +[{"name":"tooljet"}] +``` + +
+ **Response Example** + ```json + { + "ok": true, + "id": "23212104e60a71edb42ebc509f0049a2", + "rev": "2-b0a625abc4e21ee554737920156e911f" + } + ``` +
+ +### Delete Record + +Removes a record from the database by its record ID. + +#### Required Parameters: +- **Record ID** +- **Revision ID** + + +Couch delete view + +
+ **Response Example** + ```json + { + "ok": true, + "id": "rev_id=2-3d01e0e87139c57e9bd083e48ecde13d&record_id=e33dc4e209689cb0400d095fc401a1e0", + "rev": "1-2b99ef28c03e68ea70bb668ee55ffb7b" + } + ``` +
+ +### Find + +Find documents using a declarative JSON querying syntax. + +#### Required Parameters: +- **Mangoquery** + +:::info +NOTE: +selector syntax: https://pouchdb.com/guides/mango-queries.html +::: + + +Couch find + + +#### Example + +```json +{ + "selector": { + "year": {"$gte": 2015} + }, + "fields": ["year"] +} +``` + +Example response from CouchDB: + +Couch find response + +### Get View + +Views are the primary tool used for querying and reporting on CouchDB documents. + +#### Required Parameters +- **View url** + + +#### Optional Parameters: +- **Start key** +- **End key** +- **Limit** +- **Skip** + +Couch get view + +
+ **Response Example** + ```json + { + "total_rows": 4, + "offset": 0, + "rows": [ + { + "id": "23212104e60a71edb42ebc509f000dc2", + "key": "23212104e60a71edb42ebc509f000dc2", + "value": { + "rev": "1-0cc7f48876f15883394e5c139c628123" + } + }, + { + "id": "23212104e60a71edb42ebc509f00216e", + "key": "23212104e60a71edb42ebc509f00216e", + "value": { + "rev": "1-b3c45696b10cb08221a335ff7cbd8b7a" + } + }, + { + "id": "23212104e60a71edb42ebc509f00282a", + "key": "23212104e60a71edb42ebc509f00282a", + "value": { + "rev": "1-da5732beb913ecbded309321cac892d2" + } + }, + { + "id": "23212104e60a71edb42ebc509f002cbd", + "key": "23212104e60a71edb42ebc509f002cbd", + "value": { + "rev": "1-ca5bb3c0767eb42ea6c33eee3d395b59" + } + } + ] + } + ``` +
+ +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/custom-js.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/custom-js.md new file mode 100644 index 0000000000..b39f9633e7 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/custom-js.md @@ -0,0 +1,176 @@ +--- +id: run-js +title: Run JavaScript Code +--- + +The **Run JavaScript Code** feature in ToolJet allows custom JavaScript code to be executed to enhance application interactivity. This feature is useful for performing calculations, generating values, or interacting with queries and components. + +
+ +## Creating a Run JavaScript Query + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select **Run JavaScript Code** from the list of available data sources. +3. Add the JavaScript Code. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +Run JavaScript code + +
+ +
+ +## Parameters in Run JavaScript Code + +Parameters allow for dynamic control over the JavaScript code execution without altering the core script. This provides flexibility by allowing the same code to execute with different inputs. + +Each parameter requires: + +- **Name**: Name for the parameter +- **Default value**: The value can be constant strings, numbers and object. + +### Steps to Add a Parameter + +1. In the RunJS query editor, click the **Parameters +** button to create a new parameter. +2. Provide a **Name** for the parameter. +3. Set a Default **Value**, which can be a string, number, or object. + +Once added, the **parameter can be referenced in the code using the syntax**: `parameters.`. + +
+ +Run JavaScript code + +
+ +### Displaying a Parameter Value in an Alert Box + +Let's create a new parameter named _newAlert_ and set the value as object `Displaying the Parameter Value in an Alert Box` and use the alert js method to show the value on the pop-up. + +Syntax: + +``` +alert(parameters.newAlert) +``` + +When the query is triggered the alert will show the parameters value. + +Run JavaScript code + +### Calling Another Query with Parameters + +Parameters can also be used to trigger other queries and pass custom values. Below is an example of how to call one query from another by providing custom parameters. + +1. Begin by creating a new RunJS query named _multiply_. + + - In this query, add the following parameters: + + - _num1_ with a default value of **10** + - _num2_ with a default value of **2**. + + - Add the following JavaScript Code: + + ```javascript + return parameters.num1 * parameters.num2; + ``` + + - To display the result, place a text component on the canvas and set its text to `{{queries.multiply.data}}`. +
+ Run JavaScript code + +2. Now, let's create another RunJS query called _callMultiply_, where we will invoke the _multiply_ query created earlier using custom parameter values. Here's the code snippet for _callMultiply_: + + ```js + queries.multiply.run({ num1: 20, num2: 7 }); + ``` + + By executing this code within _callMultiply_, we trigger the _multiply_ query with specific values for its parameters. + + Run JavaScript code + +With this setup, the _multiply_ query can be called from other queries, such as _callMultiply_, by providing custom parameter values. This allows you to reuse the _multiply_ query with different inputs and display the results accordingly. + +
+ +
+ +## RunJS Example Queries + +### Generating a Random Number + +This example demonstrates how to generate and display a random number using JavaScript. + +1. Drag a **button** and a **text** widget inside a **container** widget. +2. Click on the **+ Add** on the query panel to create a query and select **Run JavaScript code** from the available datasources. +3. Write the code in **JavaScript editor** and run the query. + +```js +const a = Math.floor(Math.random() * (10 - 1)) + 1; +return a; +``` + +4. Edit the properties of widgets: + 1. Add an event handler to the button: + 1. Select event as **On Click** + 2. Action as **Run Query** + 3. Select the _runjs1_ query that we created. This will run the JavaScript code every time the button is clicked. + 2. Edit the property of text widget: + 1. In the text field enter **Random number:** `{{queries.runjs1.data}}`. It will display the output as Random number: _result from JS code_ + +Run JavaScript code + +### Generating a Unique ID + +The following code generates a unique ID in the format "id" followed by a sequence of random hexadecimal characters. + +```js +var id = "id" + Math.random().toString(16).slice(2); +return id; +``` + +For example, it could be something like "id2f4a1b". + +Run JavaScript code + +### Generating a Timestamp-Based Unique ID + +In this code, the resulting ID will have the format "timestamp + randomHex", where "timestamp" is the current time in base-32 and "randomHex" is a random hexadecimal value. + +```js +return String(Date.now().toString(32) + Math.random().toString(16)).replace( + /\./g, + "" +); +``` + +This ID will be longer than the one generated earlier, and it could look like "2g3h1d6a4h3". + +Run JavaScript code + +:::tip Resources + +- You can also write custom JavaScript code to get the data from **External APIs** and manipulate the response for graphical representation. Here's the [tutorial](https://blog.tooljet.ai/build-github-stars-history-app-in-5-minutes-using-low-code/) on how we used custom JavaScript code to build an app using GitHub API. +- [Import external libraries](/docs/how-to/import-external-libraries-using-runjs) using RunJS. +- [Intentionally Fail](/docs/how-to/intentionally-fail-js-query) a RunJS query. +- [Trigger query at specified intervals](/docs/how-to/run-query-at-specified-intervals) using RunJS. + ::: + +
+ +
+ +## Libraries + +ToolJet allows you to internally utilize these libraries: + +| Name | Documentation | +| ------ | ---------------------------------------------------------------------- | +| Moment | [https://momentjs.com/docs/](https://momentjs.com/docs/) | +| Lodash | [https://lodash.com/docs/](https://lodash.com/docs/) | +| Axios | [https://axios-http.com/docs/intro](https://axios-http.com/docs/intro) | + +:::info +Issues with writing custom JavaScript code? Ask in our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA). +::: + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/databricks.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/databricks.md new file mode 100644 index 0000000000..4255e03354 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/databricks.md @@ -0,0 +1,137 @@ +--- +id: databricks +title: Databricks +--- + +Databricks is a cloud-based platform for data processing, analytics, and machine learning. ToolJet connects to Databricks, allowing your applications to access and update your data in your Databricks Warehouses directly using SQL queries. + +
+ Install Databricks +
+ +
+ +## Configuration + +ToolJet's Databricks integration relies on a configuration form that supports the following parameters: + +#### Required Parameters + +- **Server hostname**: The server hostname or the IP address of your Databricks Warehouse. For example, `62596234423488486.6.gcp.databricks.com`. +- **HTTP Path**: The API endpoint path for the Databricks resource you want to access. For example, `/sql/1.0/warehouses/44899g7346c19m95`. +- **Personal access token**: Personal access tokens are used for secure authentication to the Databricks API instead of passwords. For example, `dapi783c7d155d138d8cf14`. + +#### Optional Parameters + +- **Port**: The port number of your Databricks Warehouse. The default port number is `443`. +- **Default Catalog**: The default catalog to use for the connection. +- **Default Schema**: The default schema to use for the connection. + +### Setup + +- Navigate to your Databricks workspace, select the desired SQL Warehouse, and find **Server Hostname** and **HTTP Path** within the connection details tab. + +Databricks: Connection Details + +- To generate a personal access token, access your Databricks User Settings, select the Developer tab, click Manage under Access Tokens, and then click on the **Generate New Token** button. + +Databricks: Access Tokens + +- Navigate to the Databricks datasource configuration form in ToolJet, fill in the required parameters, and click the **Save** button. You can test the connection by clicking the **Test Connection** button. + +Databricks: Setup Paramaters + +
+ +
+ +## Querying Databricks + +1. Click on + Add button of the query manager at the bottom panel of the editor. +2. Select the **Databricks** datasource added in previous step. +3. Select the **SQL Mode** from the dropdown. (ToolJet currently supports only SQL mode for Databricks interactions.) +4. Click on the **Preview** button to preview the output or Click on the **Run** button to create and trigger the query. + +
+ +Databricks: Query Setup + +
+ +:::tip +You can apply transformations to the query results. Refer to our transformations documentation for more information: [link](/docs/beta/app-builder/custom-code/transform-data) +::: + +
+ +
+ +## Supported Queries + +Databricks supports standard SQL commands for data manipulation tasks. + +### Read Data + +The following example demonstrates how to read data from a table. The query selects all the columns from the _customers_ table. + +```sql +SELECT * FROM customers +``` + +Databricks: Read Data Query + +### Write Data + +The following example demonstrates how to write data to a table. The query inserts a new row into the _customers_ table. + +```sql +INSERT INTO customers ( + customer_id, + first_name, + last_name, + email, + phone, + city, + state, + zip_code, + country +) VALUES ( + '1001' + 'Tom', + 'Hudson', + 'tom.hudson@example.com', + '50493552', + 'San Clemente', + 'CA', + '92673', + 'USA' +); +``` + +Databricks: Write Data Query + +### Update Data + +The following example demonstrates how to update data in a table. The query updates the _first_name_ and _email_ column of the _customers_ table. + +```sql +UPDATE customer +SET first_name = 'John', + email = 'john.hudson@example.com' +WHERE customer_id = 1001; +``` + +Databricks: Update Data Query + +### Delete Data + +The following example demonstrates how to delete data from a table. The query deletes a row from the _customers_ table. + +```sql +DELETE FROM customer +WHERE customer_id = 1001; +``` + +Databricks: Delete Data Query + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/dynamodb.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/dynamodb.md new file mode 100644 index 0000000000..7673fe7ea0 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/dynamodb.md @@ -0,0 +1,312 @@ +--- +id: dynamodb +title: DynamoDB +--- + +**DynamoDB** is a managed non-relational database service provided by Amazon. ToolJet has the capability to connect to DynamoDB for reading and writing data. + +
+ +## Connection + +To establish a connection with the **DynamoDB** data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data sources](/docs/data-sources/overview)** page through the ToolJet dashboard. + +
+ +DynamoDB + +
+ +ToolJet supports connecting to DynamoDB using three methods: **IAM Credentials**, **AWS Instance Credentials**, or **AWS ARN Role**. + +When using **IAM Credentials**, you will need to provide the following information: + +- **Region** +- **Access key** +- **Secret key** + +It is recommended to create a dedicated IAM user for the database in order to have granular control over ToolJet's access levels. + +
+ +ToolJet - DynamoDB connection + +
+ +To connect to DynamoDB using an **AWS Instance Credentials**, select the option to **Use AWS Instance Credentials**. This will utilize the IAM role attached to the EC2 instance where ToolJet is running. The WebIdentityToken parameter obtained from a successful login with an identity provider is used to access the metadata service of an ECS container and the EC2 instance. + +
+ +ToolJet - DynamoDB connection + +
+ +If you prefer to use an **AWS ARN Role**, you will need to provide the following details: + +- **Region** +- **Role ARN** + +
+ +ToolJet - DynamoDB connection + +
+ +
+ +
+ +## Querying DynamoDB + +To perform queries on **DynamoDB**, click on the **+ Add** button in the query manager located at the bottom panel of the editor. Select the previously added database as the data source for the query. Choose the desired operation and click on the **Run** button to run the query. + +
+ +ToolJet - DynamoDB connection + +
+ +:::tip +You can apply transformations to the query results. Refer to our transformations documentation for more information: [link](/docs/beta/app-builder/custom-code/transform-data) +::: + +#### Supported Operations + +- **[List Tables](#list-tables)** +- **[Get Item](#get-item)** +- **[Query Table](#query-table)** +- **[Scan Table](#scan-table)** +- **[Delete Item](#delete-item)** +- **[Update Item](#update-item)** +- **[Describe Table](#describe-table)** +- **[Create Table](#create-table)** +- **[Put Item](#put-item)** + +
+ +### List Tables + +Returns an array of table names associated with the current account and endpoint. The output from _List Tables_ is paginated, with each page returning a maximum of 100 table names. + +
+ +ToolJet - DynamoDB operations + +
+ +### Get Item + +Retrieves a single item from a table. You must specify the primary key for the item that you want. You can retrieve the entire item, or just a subset of its attributes. + +#### Required Parameter + +- **Table** +- **Key name** + +#### Example + +```json +{ + "Key": { + "ForumName": { + "S": "Amazon DynamoDB" + }, + "Subject": { + "S": "How do I update multiple items?" + } +} +``` + +
+ +ToolJet - DynamoDB operations + +
+ +### Query Table + +Retrieves all items that have a specific partition key. You must specify the partition key value. You can retrieve entire items, or just a subset of their attributes. Optionally, you can apply a condition to the sort key values so that you only retrieve a subset of the data that has the same partition key. You can use this operation on a table, provided that the table has both a partition key and a sort key. You can also use this operation on an index, provided that the index has both a partition key and a sort key. + +#### Required Parameter + +- **Query condition** + +#### Example + +```yaml +{ + "TableName": "Reply", + "IndexName": "PostedBy-Index", + "Limit": 3, + "ConsistentRead": true, + "ProjectionExpression": "Id, PostedBy, ReplyDateTime", + "KeyConditionExpression": "Id = :v1 AND PostedBy BETWEEN :v2a AND :v2b", + "ExpressionAttributeValues": + { + ":v1": { "S": "Amazon DynamoDB#DynamoDB Thread 1" }, + ":v2a": { "S": "User A" }, + ":v2b": { "S": "User C" }, + }, + "ReturnConsumedCapacity": "TOTAL", +} +``` + +
+ +ToolJet - DynamoDB operations + +
+ +### Scan Table + +Retrieves all items in the specified table or index. You can retrieve entire items, or just a subset of their attributes. Optionally, you can apply a filtering condition to return only the values that you are interested in and discard the rest. + +#### Required Parameter + +- **Scan condition** + +#### Example + +```yaml +{ "TableName": "" } +``` + +
+ +ToolJet - DynamoDB operations + +
+ +### Delete Item + +Deletes a single item from a table. You must specify the primary key for the item that you want to delete. + +#### Required Parameter + +- **Table** +- **Key name** + +#### Example + +```yaml +{ + "Key": + { + "ForumName": { "S": "Amazon DynamoDB" }, + "Subject": { "S": "How do I update multiple items?" }, + }, + "ConditionExpression": "attribute_not_exists(Replies)", + "ReturnValues": "ALL_OLD", +} +``` + +
+ +ToolJet - DynamoDB operations + +
+ +### Update Item + +Update an item in DynamoDB by specifying the primary key and providing new attribute values. If the primary key does not exist in the table then instead of updating it will insert a new row. + +#### Required Parameter + +- **Update Condition** + +#### Example + +```yaml +{ + "TableName": "USER_DETAILS_with_local", + "Key": { "USER_ID": 1, "USER_NAME": "Nick" }, + "UpdateExpression": "set USER_AGE = :age, USER_FEE = :fee", + "ExpressionAttributeValues": { ":age": 40, ":fee": 230545 }, +} +``` + +
+ +ToolJet - DynamoDB operations + +
+ +### Describe Table + +This operation in DynamoDB retrieves metadata and configuration details about a specific table. It provides information such as the table's name, primary key schema, provisioned throughput settings, and any secondary indexes defined on the table. + +#### Required Parameter + +- **Table** + +
+ +ToolJet - DynamoDB operations + +
+ +### Create Table + +This operation in DynamoDB enables you to create a new table by specifying its name, primary key schema, and optional configurations. + +#### Required Parameter + +- **Table Parameters** + +#### Example + +```yaml +{ + "AttributeDefinitions": + [ + { "AttributeName": "USER_ID", "AttributeType": "N" }, + { "AttributeName": "USER_FEE", "AttributeType": "N" }, + ], + "KeySchema": [{ "AttributeName": "USER_ID", "KeyType": "HASH" }], + "LocalSecondaryIndexes": + [ + { + "IndexName": "USER_FEE", + "KeySchema": + [ + { "AttributeName": "USER_ID", "KeyType": "HASH" }, + { "AttributeName": "USER_FEE", "KeyType": "RANGE" }, + ], + "Projection": { "ProjectionType": "KEYS_ONLY" }, + }, + ], + "ProvisionedThroughput": { "ReadCapacityUnits": 1, "WriteCapacityUnits": 1 }, + "TableName": "USER_FEE_LOCAL", + "StreamSpecification": { "StreamEnabled": false }, +} +``` + +
+ +ToolJet - DynamoDB operations + +
+ +### Put Item + +This operation allows you to create or replace an item in a table. It enables you to specify the table name, provide the attribute values for the new item, and define the primary key attributes to uniquely identify the item. + +#### Required Parameter + +- **New Item Details** + +#### Example + +```yaml +{ + "TableName": "USER_DETAILS_with_localS", + "Item": + { "USER_ID": 1, "USER_NAME": "NICK", "USER_AGE": 34, "USER_FEE": 1234.56 }, +} +``` + +
+ +ToolJet - DynamoDB operations + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/elasticsearch.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/elasticsearch.md new file mode 100644 index 0000000000..868473cf84 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/elasticsearch.md @@ -0,0 +1,489 @@ +--- +id: elasticsearch +title: Elasticsearch +--- + +ToolJet allows you to connect to your Elasticsearch cluster to perform data read/write operations and execute various queries. + +## Connection + +To connect to an Elasticsearch data source in ToolJet, you can either click the **+ Add new data source** button on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page in the ToolJet dashboard. + +:::info +Please make sure the **Host/IP** of the database is accessible from your VPC if you have self-hosted ToolJet. If you are using ToolJet cloud, please **whitelist** our IP. +::: + +To connect to your Elasticsearch cluster, the following details are required: + +- **Host** +- **Port** +- **Username** +- **Password** + +
+ Elastic Connect +
+ +ToolJet also supports SSL certificate-based connections: + +- You can use either CA or Client certificates. + +
+ Elastic SSL Connect +
+ +
+ +## Querying Elasticsearch + +1. Click the **+ Add** button in the query manager at the bottom of the editor and select the Elasticsearch data source added earlier. +2. Choose the operation you want to perform on your Elasticsearch cluster. + +:::tip +Query results can be transformed using transformations. Refer to our transformations documentation for more details: **[link](/docs/beta/app-builder/custom-code/transform-data)** +::: + +
+ +
+ +## Supported Operations + +ToolJet supports the following Elasticsearch operations: + +- **[Search](#search)** +- **[Index a Document](#index-a-document)** +- **[Get a Document](#get-a-document)** +- **[Update a Document](#update-a-document)** +- **[Delete a Document](#delete-a-document)** +- **[Bulk Operation](#bulk-operation)** +- **[Count Documents](#count-documents)** +- **[Check Document Existence](#check-document-existence)** +- **[Multi Get](#multi-get)** +- **[Scroll Search](#scroll-search)** +- **[Clear Scroll](#clear-scroll)** +- **[Get Cat Indices](#get-cat-indices)** +- **[Get Cluster Health](#get-cluster-health)** + +### Search + +This operation executes a search query and returns matching search hits. For more details, see the Elasticsearch search guide **[here](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-search.html)**. + +#### Required Parameter + +- **Index**: The name of the index to search in. +- **Query**: The search query in JSON format. + +#### Optional Parameter + +- **Scroll**: Scroll time. + +
+ Elastic search +
+ +#### Example: + +```yaml +Index: books +Query: { "query": { "match": { "title": "The Great Gatsby" } }, "size": 20 } +Scroll: 1m # Can be in the format of 1m, 1h, 1d. +``` + +### Index a Document + +This operation adds a JSON document to the specified index or data stream. For more details, see the Elasticsearch index guide **[here](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html)**. + +#### Required Parameter + +- **Index**: The name of the index to add the document to +- **Body**: The document body in JSON format + +
+ Elastic index +
+ +#### Example: + +```yaml +Index: books +Body: + { + "title": "1984", + "author": "George Orwell", + "year": 1949, + "genre": "Dystopian Fiction", + } +``` + +### Get a Document + +This operation retrieves the specified JSON document from the index. For more details, see the Elasticsearch get guide **[here](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-get.html)**. + +#### Required Parameter + +- **Index**: The name of the index to get the document from +- **Id**: The ID of the document to retrieve + +
+ Elastic get +
+ +#### Example: + +```yaml +Index: books +Id: FJXTSZEBsuzUn2y4wZ-W +``` + +### Update a Document + +This operation updates a document using the specified script. For more details, see the Elasticsearch update guide **[here](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-update.html)**. + +#### Required Parameter + +- **Index**: The name of the index containing the document +- **Id**: The ID of the document to update +- **Body**: The update script or partial document in JSON format + +
+ Elastic update +
+ +#### Example: + +```yaml +Index: books +Id: FJXTSZEBsuzUn2y4wZ-W +Body: +{ + "doc": { + "title": "1984", + "author": "George Orwell", + "year": 1949, + "genre": "Fiction" + } +} +``` + +### Delete a Document + +This operation removes a JSON document from the specified index. For more details, see the Elasticsearch delete guide **[here](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-delete.html)**. + +#### Required Parameter + +- **Index**: The name of the index containing the document +- **Id**: The ID of the document to delete + +
+ Elastic delete +
+ +#### Example: + +```yaml +Index: books +Id: FJXTSZEBsuzUn2y4wZ-W +``` + +### Bulk Operation + +This operation performs multiple index/update/delete operations in a single API call. For more details, see the Elasticsearch bulk guide **[here](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-bulk.html)**. + +#### Required Parameter + +- **Operations**: The bulk operations to perform in JSON format + +
+ Elastic bulk +
+ +#### Example: + +```yaml +[ + { "index": { "_index": "books", "_id": "book1" } }, + { + "title": "The Great Gatsby", + "author": "F. Scott Fitzgerald", + "year": 1925, + }, + { "delete": { "_index": "books", "_id": "book2" } }, + { "index": { "_index": "books", "_id": "book3" } }, + { "title": "Moby-Dick", "author": "Herman Melville", "year": 1851 }, + { "delete": { "_index": "books", "_id": "book4" } }, +] +``` + +### Count Documents + +This operation returns the number of matches for a search query. For more details, see the Elasticsearch count guide **[here](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-count.html)**. + +#### Required Parameter + +- **Index**: The name of the index to count documents in. + +#### Optional Parameter + +- **Query**: The query to filter documents in JSON format + +
+ Elastic count +
+ +#### Example: + +```yaml +{ "query": { "range": { "timestamp": { "gte": 1901 } } } } +``` + +### Check Document Existence + +This operation checks if a document exists in an index. For more details, see the Elasticsearch exists guide **[here](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-get.html#docs-get-api-response-codes)**. + +#### Required Parameter: + +- **Index**: The name of the index to check for document existence +- **Id**: The ID of the document to check + +
+ Elastic exists +
+ +#### Example: + +```yaml +Index: books +Id: FJXTSZEBsuzUn2y4wZ-W +``` + +### Multi Get + +This operation retrieves multiple documents in a single request. For more details, see the Elasticsearch multi-get guide **[here](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-multi-get.html)**. + +#### Required Parameter + +- **Operations**: The multi-get operations to perform in JSON format + +
+ Elastic multi get +
+ +#### Example: + +```yaml +{ + "docs": + [ + { "_index": "books", "_id": "book124" }, + { "_index": "books", "_id": "book125" }, + ], +} +``` + +### Scroll Search + +This operation retrieves large numbers of results from a single search request. For more details, see the Elasticsearch scroll guide **[here](https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html#scroll-search-results)**. + +#### Required Parameter + +- **Scroll ID**: The scroll ID for the search +- **Scroll**: The scroll time + +
+ Elastic scroll +
+ +#### Example: + +```yaml +Scroll ID: DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAOWQWYm9vbDItY1NCOUExal9TcTBjeUEyZw +Scroll: 60m +``` + +### Clear Scroll + +This operation clears the search context for a scroll. For more details, see the Elasticsearch clear scroll guide **[here](https://www.elastic.co/guide/en/elasticsearch/reference/current/clear-scroll-api.html)**. + +#### Required Parameter + +- **Scroll ID**: The scroll ID to clear + +
+ Elastic clear scroll +
+ +#### Example: + +```yaml +Scroll ID: DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAOWQWYm9vbDItY1NCOUExal9TcTBjeUEyZw +``` + +### Get Cat Indices + +This operation provides a compact, column-aligned view of indices in a cluster. For more details, see the Elasticsearch cat indices guide **[here](https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-indices.html)**. + +
+ Elastic cat indices +
+ +
+ **Response Example** +```json +{ + "body": [ + { + "health": "yellow", + "status": "open", + "index": "1", + "uuid": "JQOzqxK7Rdar7ROOlqXwkA", + "pri": "1", + "rep": "1", + "docs.count": "2", + "docs.deleted": "0", + "store.size": "9.2kb", + "pri.store.size": "9.2kb" + }, + { + "health": "yellow", + "status": "open", + "index": "recipes", + "uuid": "eNGdAsG4TMWvs9f0eLERlQ", + "pri": "1", + "rep": "1", + "docs.count": "20", + "docs.deleted": "0", + "store.size": "30kb", + "pri.store.size": "30kb" + }, + { + "health": "yellow", + "status": "open", + "index": "read_me", + "uuid": "EbE4V-5RRE2y-_P4z_auVQ", + "pri": "1", + "rep": "1", + "docs.count": "1", + "docs.deleted": "0", + "store.size": "5.1kb", + "pri.store.size": "5.1kb" + } + ], + "statusCode": 200, + "headers": { + "x-elastic-product": "Elasticsearch", + "content-type": "application/json", + "content-length": "558" + }, + "meta": { + "context": null, + "request": { + "params": { + "method": "GET", + "path": "/_cat/indices", + "body": null, + "querystring": "format=json", + "headers": { + "user-agent": "opensearch-js/1.2.0 (linux 6.5.0-1021-aws-x64; Node.js v18.18.2)" + }, + "timeout": 30000 + }, + "options": {}, + "id": 1 + }, + "name": "opensearch-js", + "connection": { + "url": "http://xx.2xx.183.199:9200/", + "id": "http://xx.2xx.183.199:9200/", + "headers": {}, + "deadCount": 0, + "resurrectTimeout": 0, + "_openRequests": 0, + "status": "alive", + "roles": { + "master": true, + "data": true, + "ingest": true + } + }, + "attempts": 0, + "aborted": false + } +} +``` +
+ +### Get Cluster Health + +This operation retrieves the status of the cluster’s health. For more details, see the Elasticsearch cluster health guide **[here](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-health.html)**. + +
+ Elastic cluster health +
+ +
+ **Response Example** +```json +{ + "body": { + "cluster_name": "docker-cluster", + "status": "yellow", + "timed_out": false, + "number_of_nodes": 1, + "number_of_data_nodes": 1, + "active_primary_shards": 10, + "active_shards": 10, + "relocating_shards": 0, + "initializing_shards": 0, + "unassigned_shards": 3, + "delayed_unassigned_shards": 0, + "number_of_pending_tasks": 0, + "number_of_in_flight_fetch": 0, + "task_max_waiting_in_queue_millis": 0, + "active_shards_percent_as_number": 76.92307692307693 + }, + "statusCode": 200, + "headers": { + "x-elastic-product": "Elasticsearch", + "content-type": "application/json", + "content-length": "405" + }, + "meta": { + "context": null, + "request": { + "params": { + "method": "GET", + "path": "/_cluster/health", + "body": null, + "querystring": "", + "headers": { + "user-agent": "opensearch-js/1.2.0 (linux 6.5.0-1021-aws-x64; Node.js v18.18.2)" + }, + "timeout": 30000 + }, + "options": {}, + "id": 1 + }, + "name": "opensearch-js", + "connection": { + "url": "http://xx.2xx.183.199:9200/", + "id": "http://xx.2xx.183.199:9200/", + "headers": {}, + "deadCount": 0, + "resurrectTimeout": 0, + "_openRequests": 0, + "status": "alive", + "roles": { + "master": true, + "data": true, + "ingest": true + } + }, + "attempts": 0, + "aborted": false + } +} +``` +
+ +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/firestore.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/firestore.md new file mode 100644 index 0000000000..941f1da041 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/firestore.md @@ -0,0 +1,175 @@ +--- +id: firestore +title: Cloud Firestore +--- + +ToolJet can connect to **Cloud Firestore** databases to read and write data. + +
+ +## Connection + +To establish a connection with the **Cloud Firestore** data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page from the ToolJet dashboard and choose Cloud Firestore as the data source. + +ToolJet requires the following to connect to your BigQuery: + +- **Private key** + +For generating a private key check out **[Firestore's official documentation](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#iam-service-account-keys-create-console)**. + +firestore add ds + +
+ +
+ +## Querying Firestore + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **Cloud Firestore** datasource added in previous step. +3. Select the desired operation from the dropdown and enter the required parameters. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +firestore QUERY + +:::tip +Query results can be transformed using transformations. Read our transformations documentation to see how: **[link](/docs/beta/app-builder/custom-code/transform-data)** +::: + +
+ +
+ +## Supported Operations + +- **[Get Document](#get-document)** +- **[Query collection](#query-collection)** +- **[Add Document to Collection](#add-document-to-collection)** +- **[Update Document](#update-document)** +- **[Set Document](#set-document)** +- **[Bulk update using document ID](#bulk-update-using-document-id)** +- **[Delete Document](#delete-document)** + +### Get Document + +Use this operation to get the data in a document. + +#### Required Parameters + +- **Path** + +firestore get + +### Query Collection + +Use this operation to query all the documents in a collection. Check firestore doc **[here](https://firebase.google.com/docs/reference/js/v8/firebase.database.Query)**. + +#### Required Parameters + +- **Path** + +#### Optional parameters + +- **Order type** +- **Limit** +- **Field** +- **Operator** +- **Value** + +firestore collection + +### Add Document to Collection + +Use this operation for creating a new document in a collection. + +#### Required Parameters + +- **Collection** +- **Body**. + +#### Example + +```json +{ + "Author": "Shubh", + "id": 5 +} +``` + +firestore document + +### Update Document + +Use this operation for updating the existing document in a collection. Also, it only updates fields if they exist, but doesn't replace an entire object like **[set operation](#set-document)**. + +#### Required Parameters + +- **Path** +- **Body** + +#### Example + +```json +{ + "Author": "Shubhendra", + "id": 3 +} +``` + +firestore update + +### Set Document + +This operation replaces your chosen object with the value that you provide. So if your object has 5 fields, and you use Set operation and pass object with 3 fields, it will now have 3 fields. + +#### Required Parameters + +- **Path** +- **Body** + +#### Example + +```json +{ + "Author": "Shefewfbh", + "id": 9 +} +``` + +firestore set + +### Bulk Update Using Document ID + +Use this operation for bulk updating documents. + +#### Required Parameters + +- **Collection** +- **Key for document ID** +- **Records** + +firestore bulk + +### Delete Document + +Use this operation for deleting a document in a collection. + +#### Required Parameters + +- **Path** + +firestore delete + +
+ +
+ +## Transforming Firestore Query Result for Table Widget + +The Firestore query result is in the form of object so we’ll need to transform it into array. + +```js +return (data = Array(data)); +``` + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/gcs.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/gcs.md new file mode 100644 index 0000000000..d4c3ad62e9 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/gcs.md @@ -0,0 +1,127 @@ +--- +id: gcs +title: Google Cloud Storage +--- + +ToolJet can connect to GCS buckets and perform various operation on them. + +
+ +## Connection + +To establish a connection with the Google Cloud Storage data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page through the ToolJet dashboard. + +ToolJet requires the following to connect to a GCS datasource: + +- **JSON Private Key** + +You can follow the [google documentation](https://cloud.google.com/docs/authentication/getting-started) to get started. + +gcs connection + +
+ +
+ +## Querying GCS + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **GCS** datasource added in previous step. +3. Select the Operation. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to create and trigger the query. + +:::tip +Query results can be transformed using transformations. Read our transformations documentation to see how: [link](/docs/beta/app-builder/custom-code/transform-data) +::: + +#### Supported operations + +- **[Read file](#read-file)** +- **[Upload file](#uplodad-file)** +- **[List buckets](#list-buckets)** +- **[List files in a bucket](#list-files-in-a-bucket)** +- **[Signed url for download](#signed-url-for-download)** +- **[Signed url for upload](#signed-url-for-upload)** + +gcs query + +### Read File + +Reads the content of a file from GCS. + +#### Required Parameter + +- **Bucket** +- **File Name** + +gcs query + +### Uplodad File + +Uploads a file to GCS. + +#### Required Parameter + +- **Bucket** +- **File name** +- **Upload data** + +#### Optional Parameter + +- **Content Type** +- **Encoding** + +gcs query + +### List Buckets + +Retrieves a list of available buckets. + +gcs query + +### List Files in a Bucket + +Lists files within a specific GCS bucket. + +#### Required Parameter + +- **Bucket** + +#### Optional Parameter + +- **Prefix** + +gcs query + +### Signed URL for Download + +Generates a signed URL for downloading a file. + +#### Required Parameter + +- **Bucket** +- **File Name** + +#### Optional Parameter + +- **Expires in** + +gcs query + +### Signed URL for Upload + +Generates a signed URL for uploading a file. + +#### Required Parameter + +- **Bucket** +- **File name** + +#### Optional Parameter + +- **Expires in** +- **Content Type** + +gcs query + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/google.sheets.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/google.sheets.md new file mode 100644 index 0000000000..4d8089268d --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/google.sheets.md @@ -0,0 +1,171 @@ +--- +id: googlesheets +title: Google Sheets +--- + +ToolJet has the capability to establish a connection with Google Sheet for both reading and writing data. By utilizing OAuth 2.0, ToolJet can establish a secure connection with Google Sheet, ensuring that the application's access to a user's account is restricted and limited appropriately. + +## Self-Hosted Configuration + +If you decide to self-host ToolJet, there are a few additional steps you need to take: + +1. Proceed with the setup steps provided in the [Google OAuth 2.0 guide](/docs/setup/env-vars#google-oauth) to configure the necessary settings. +2. Assign the corresponding values obtained from the previous step to the following environment variables: + - **GOOGLE_CLIENT_ID** + - **GOOGLE_CLIENT_SECRET** + - **TOOLJET_HOST** +3. Activate the Google Sheets API within the Google Cloud Platform (GCP) console. + +## Connection + +To establish a connection with the Google Sheet data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page through the ToolJet dashboard. + +### Authorization Scopes + +When connecting to a Google Sheets data source, you can choose between two permission scopes: + +1. **Read Only**: This scope allows you to access and retrieve data from the Google Sheet. +2. **Read and Write**: This scope grants you both read and write permissions, enabling you to retrieve and modify data within the Google Sheet. + +Google Sheet + +## Querying Google Sheet + +1. Click the **+ Add** button in the query manager located at the bottom panel of the editor. +2. Select the **Google Sheet** data source under the data source section. +3. Choose the desired operation from the dropdown. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to create and trigger the query. + +Using Google sheets data source you can perform several operations from your applications like: + + 1. **[Create a spreadsheet](#create-a-spreadsheet)** + 2. **[List all sheets of a spreadsheet](#list-all-sheets-of-a-spreadsheet)** + 3. **[Read data from a spreadsheet](#read-data-from-a-spreadsheet)** + 4. **[Append data to a spreadsheet](#append-data-to-a-spreadsheet)** + 5. **[Get spreadsheet info](#get-spreadsheet-info)** + 6. **[Update single row of a spreadsheet](#update-single-row-of-a-spreadsheet)** + 7. **[Delete row from a spreadsheet](#delete-row-from-a-spreadsheet)** + +Google Sheet Operations + +:::info +**Spreadsheet ID** can be obtained from the URL of the spreadsheet. For example, in the URL `https://docs.google.com/spreadsheets/d/1W2S4re7zNaPk9vqv6_CqOpPdm_mDEqmLmzjVe7Nb9WM/edit#gid=0`, the `1W2S4re7zNaPk9vqv6_CqOpPdm_mDEqmLmzjVe7Nb9WM` represents the spreadsheet ID. +::: + +### Create a Spreadsheet + +This operation can be used to create a new spreadsheet. + +#### Required Parameter +- **Title** + +create a spreadsheet + +### List All Sheets of a Spreadsheet + +This operation can be used to list all sheets of a spreadsheet. + +#### Required Parameter +- **Spreadsheet ID** + +create a spreadsheet + +### Read Data From a Spreadsheet + +This operation allows you to retrieve the table data from a spreadsheet in the form of a JSON object. + +#### Required Parameter +- **Spreadsheet ID** + +#### Optional Parameter +- **Range** +- **Sheet** + +Google Sheet Operations + +### Append Data to a Spreadsheet + +Add additional rows to a table by using the append operation. + +#### Required Parameter +- **Spreadsheet ID** +- **Rows** + +#### Optional Parameter +- **Sheet** + +Google Sheet Operations + +#### Example +```yaml +[ + { + "name": "John", + "email": "john@tooljet.com", + "date": "2024-09-16", + "status": "Confirmed", + "phone": "+123456789" + }, + { + "name": "Jane", + "email": "jane@tooljet.com", + "date": "2024-09-17", + "status": "Pending", + "phone": "+987654321" + }, + { + "name": "Doe", + "email": "doe@tooljet.com", + "date": "2024-09-18", + "status": "Cancelled", + "phone": "+112233445" + } +] +``` + +### Get Spreadsheet Info + +This operation allows you to retrieve basic information about the spreadsheet, including the number of sheets, theme, time zone, format, and URL, among others. + +google sheets get info + +### Update Single Row of a Spreadsheet + +This operation allows you to update existing data in a sheet. + +#### Required Parameters +- **Spreadsheet ID** +- **Where** +- **Operator** +- **Value** +- **Body** + +#### Optional Parameters +- **Range** +- **Sheet** + +Google Sheet Operations + +#### Example +```yaml +{ + "name": "Hugo Lefevre", + "position": "Product Manager", + "url": "https://abctech.com/hugo", + "date-applied": "2024-09-10", + "status": "Application Under Review" +} +``` + +### Delete Row From a Spreadsheet + +This operation allows you to delete a specific row from the sheet. + +#### Required Parameter +- **Spreadsheet ID** +- **Delete row number** + +#### Optional Parameter +- **GID** + +google sheets delete diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/graphql.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/graphql.md new file mode 100644 index 0000000000..29e79ad3aa --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/graphql.md @@ -0,0 +1,124 @@ +--- +id: graphql +title: GraphQL +--- + +ToolJet can establish connections with GraphQL endpoints, enabling the execution of queries and mutations. + +
+ +## Connection + +To establish a connection with the GraphQL global datasource, you can either click on the **+ Add new global datasource** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page through the ToolJet dashboard. + +
+ +ToolJet - Data source - GraphQL + +
+ +ToolJet requires the following to connect to a GraphQL datasource: + +- **URL**: URL of the GraphQL endpoint. +- **Headers**: Any headers the GraphQL source requires. +- **URL parameters**: Additional query string parameters. +- **Authentication Type**: The method of authentication to use with GraphQL requests. + - **None**: No credentials or tokens are required. + - **Basic**: Requires Username and Password. + - **Bearer**: Requires a token, typically a JSON Web Token (JWT), to grant access. + - **OAuth 2.0**: The OAuth 2.0 protocol mandates the provision of the following parameters: access token URL, access token URL custom headers, client ID, client secret, scopes, custom query parameters, authorization URL, custom authentication parameters, and client authentication. + +
+ +
+ +## Querying GraphQL + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **GraphQL** datasource added in previous step. +3. Add the Query. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to create and trigger the query. + +### Required Parameters: + +- **Query** + +### Optional Parameters + +- **Variable** +- **Headers** + +
+ +ToolJet - Data source - GraphQl + +
+ +#### Example + +```yaml +{ + todos { + id + description + } +} +``` + +:::tip +Query results can be transformed using transformations. Read our transformations documentation to see how: [link](/docs/beta/app-builder/custom-code/transform-data) +::: + +
+## Metadata + +Metadata is additional information about the data returned by the GraphQL query. It includes details such as the request URL, method, headers, and response status code. You can access this information using the `metadata` object. REST API. The metadata can be accessed within queries and components using the `{{queries..metadata}}` syntax. + +:::info +While accessing the properties of the metadata object, which contains a hyphen, you can use the bracket notation. For example, to access the `content-length` property, you can use `{{queries.graphql1.metadata.request.headers["content-length"]}}` or `{{queries.graphql1.metadata.request.headers."content-length"}}`. +::: + +
+**Example Metadata** + +```json +{ + "request": { + "url": "https://swapi-graphql.netlify.app/.netlify/functions/index?testParam=valueParam", + "method": "POST", + "headers": { + "user-agent": "got (https://github.com/sindresorhus/got)", + "header1key": "Header1value", + "content-type": "application/json", + "content-length": "275", + "accept-encoding": "gzip, deflate, br" + }, + "params": { + "testParam": "valueParam" + } + }, + "response": { + "statusCode": 200, + "headers": { + "access-control-allow-origin": "*", + "age": "0", + "cache-control": "no-cache", + "cache-status": ""Netlify Durable"; fwd=method, "Netlify Edge"; fwd=method", + "content-encoding": "br", + "content-length": "840", + "content-type": "application/json; charset=utf-8", + "date": "Fri, 13 Sep 2024 06:38:27 GMT", + "etag": "W/"18ad-ZANyCoLSJjHWg3k1SaMp6gH/gdQ"", + "netlify-vary": "query", + "server": "[REDACTED]", + "strict-transport-security": "max-age=31536000; includeSubDomains; preload", + "vary": "Accept-Encoding", + "x-nf-request-id": "01J7N1NG25V8Q9GY51RH11ACTN", + "x-powered-by": "Express", + "connection": "close" + } + } +} +``` + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/grpc.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/grpc.md new file mode 100644 index 0000000000..9584b36001 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/grpc.md @@ -0,0 +1,86 @@ +--- +id: grpc +title: gRPC +--- + +
Self-hosted only
+ +:::caution +Only self-hosted deployments will have access to a gRPC datasource that is capable of handling unary requests and responses. +::: + +
+ +## Setup + +### Step 1: Upgrade ToolJet to the Version 2.5 or Above + +Find instructions on how to do this in the setup guides located here: [ToolJet Setup](/docs/setup/). + +### Step 2: Add Proto Files + +At the root, create a directory named "*protos*" and add a "*service.proto*" file inside it. + + +### Step 3: Mount Volumes + +In the **docker-compose.yml** add the following to the *volumes* sections for **plugins** and **server** + +```bash +./protos:/app/protos +``` + +gRPC: datasource + +gRPC: datasource + +### Step 4: Reboot the Instance + +```bash +docker-compose up -d +``` + +
+ +
+ +## Querying gRPC + +After setting up your proto files, you should be able to establish a connection to gRPC by going to the [global datasource](/docs/data-sources/overview) page. + +### Connect the gRPC Datasource + +ToolJet requires the following to connect to gRPC servers: + +- **Server URL** +- **Authentication type** + - None + - Basic + - Bearer + - API key + +
+ +gRPC: connection + +
+ +Once you have added the gRPC from the global datasource page, you'll find it on the query panel of the application. + +
+ +gRPC: connection + +
+ +### Creating Query + +You can now query a particular RPC method of the added services. + +
+ +gRPC: connection + +
+ +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/influxdb.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/influxdb.md new file mode 100644 index 0000000000..dec39572ce --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/influxdb.md @@ -0,0 +1,212 @@ +--- +id: influxdb +title: InfluxDB +--- + +ToolJet can connect to InfluxDB databases to read and write data. Use the Token authentication scheme to authenticate to the InfluxDB API. For more info visit [InfluxDB docs](https://docs.influxdata.com/). + +
+ +## Connection + +ToolJet connects to InfluxDB using : + +- **API Token** +- **Host** +- **Port** +- **Protocol** (HTTP/HTTPS) + +:::info +For generating API Token visit [InfluxDB docs](https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token/). +::: + +
+ +influx auth + +
+ +
+ +
+ +## Supported Queries + +- **[Write data](#write-data)** +- **[Query data](#query-data)** +- **[Generate an Abstract Syntax Tree (AST) from a query](#generate-an-abstract-syntax-tree-ast-from-a-query)** +- **[Retrieve query suggestions](#retrieve-query-suggestions)** +- **[Retrieve query suggestions for a branching suggestion](#retrieve-query-suggestions-for-a-branching-suggestion)** +- **[Analyze a Flux query](#analyze-a-flux-query)** +- **[List buckets](#list-buckets)** +- **[Create a bucket](#create-a-bucket)** +- **[Retrieve a bucket](#retrieve-a-bucket)** +- **[Update a bucket](#update-a-bucket)** +- **[Delete a bucket](#delete-a-bucket)** + + +influx operations + + +### Write Data + +This operation writes data to a bucket. + +#### Required Parameters: + +- **Bucket** +- **Organization name or ID** +- **Data** + +#### Optional Parameters: + +- **Precision** + +influx operations + +### Query Data + +Retrieves data from InfluxDB buckets. + +#### Required Parameters: +- **Organization name or ID** +- **Flux query** + +influx operations + +#### Example + +```yaml +from(bucket: "sensor_data") +|> range(start: -1h) +|> filter(fn: (r) => r["_measurement"] == "temperature") +``` + +### Generate an Abstract Syntax Tree (AST) from a Query + +This operation analyzes flux query and generates a query specification. + +#### Required Parameters: + +- **Query** + +influx operations + +#### Example + +```yaml +from(bucket: "website_metrics") + |> range(start: -7d) + |> filter(fn: (r) => r["_measurement"] == "page_views") + |> group(columns: ["url"]) + |> sum(column: "_value") + |> sort(columns: ["_value"], desc: true) +``` + +### Retrieve Query Suggestions + +This query retrieve query suggestions. + +influx operations + +### Retrieve Query Suggestions for a Branching Suggestion + +This operation retrieve query suggestions for a branching suggestion. + +#### Required Parameters: +- **Name** + +influx operations + +### Analyze a Flux Query + +This Analyzes a Flux query. + +#### Required Parameters: + +- **Query** + +influx operations + +#### Example +```yaml +from(bucket: "sensor_data") + |> range(start: -1d) + |> filter(fn: (r) => r["_measurement"] == "humidity") + |> mean(column: "_value") +``` + +### List Buckets + +This operation lists all the buckets in a database. + +influx operations + +### Create a Bucket + +This operation creates a bucket in database. + +#### Required Parameters: + +- **Query** + +influx operations + +#### Example +```yaml +POST http://localhost:8086/api/v2/buckets +Content-Type: application/json +Authorization: Token your_auth_token + +{ + "name": "new_bucket", + "orgID": "your_org_id", + "retentionRules": [ + { + "everySeconds": 3600 + } + ] +} +``` + +### Retrieve a Bucket + +This operation retrieve a bucket in a database. + +#### Required Parameters: +- **Bucket ID** + +influx operations + +### Update a Bucket + +This operaition updates the bucket in database. + +#### Required Parameters: +- **Bucket ID** +- **Query** + +influx operations + +#### Example +```yaml +{ + "name": "updated_bucket_name", + "retentionRules": [ + { + "everySeconds": 7200 + } + ] +} +``` + +### Delete a Bucket + +This operation delete the bucket in database. + +#### Required Parameters: +- **Bucket ID** + +influx operations + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/mailgun.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/mailgun.md new file mode 100644 index 0000000000..8c966906c7 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/mailgun.md @@ -0,0 +1,63 @@ +--- +id: mailgun +title: Mailgun +--- + +ToolJet can connect to your Mailgun account to send emails. + +:::info +The Mailgun API Datasource supports for interaction with the mail endpoint of the [Mailgun API](https://documentation.mailgun.com/en/latest/api-intro.html#authentication-1). +::: + +
+ +## Connection + +To establish a connection with the **Mailgun** data source, click on the **+ Add new data source** button located on the query panel or navigate to the [Data Sources](/docs/data-sources/overview) page from the ToolJet dashboard. + +ToolJet requires the following to connect to your Mailgun: +- **API key** + +ToolJet - Data source - Mailgun + +:::tip +Mailgun API key is required to create an Mailgun datasource on ToolJet. You can generate API key by visiting [Mailgun account page](https://app.mailgun.com/app/account/security/api_keys). +::: + +
+ +
+ +## Supported Operations + +### Email Service + +#### Required parameters: + +- **Send email to** +- **Send email from** +- **Subject** +- **Body as text** + +#### Optional parameters: + +- **Body as HTML** + +ToolJet - Data source - Mailgun Query + +:::info +**Send mail to** - accepts a single email id. +For example: +`{{"dev@tooljet.io"}}`. + +**Send mail from** - accepts a string. +For example: `admin@tooljet.io` +::: + +:::tip +**Send a single email to multiple recipients** - The `Send mail to` field can contain an array of recipients, which will send a single email with all of the recipients in the field. + +**Send multiple individual emails to multiple recipients** - set Multiple recipients field to `{{true}}` and the `Send mail to` field will be split into multiple emails and send to each recipient. +::: + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/mariadb.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/mariadb.md new file mode 100644 index 0000000000..0247c7674b --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/mariadb.md @@ -0,0 +1,194 @@ +--- +id: mariadb +title: MariaDB +--- + +ToolJet can connect to both self-hosted and cloud-based MariaDB servers to read and write data. + +
+ +## Connection + +To establish a connection with the MariaDB global datasource, you can either click on the **+ Add new global datasource** button located on the query panel or navigate to the **[Global Datasources](/docs/data-sources/overview)** page through the ToolJet dashboard. + +**ToolJet requires the following connection details to connect to MariaDB:** + +- **Host:** The hostname or IP address of the MariaDB server. +- **Username:** The username for the MariaDB account. +- **Password:** The password for the MariaDB account. +- **Connection Limit:** The maximum number of concurrent connections allowed to the MariaDB server. +- **Port:** The port number of the MariaDB server. +- **Database:** The name of the database that you want to connect to. +- **SSL:** Whether or not to use SSL to connect to the MariaDB server. +- **SSL Certificate:** There are three options for the SSL Certificate connection detail: + - **CA Certificate:** This option allows you to use a certificate issued by a Certificate Authority (CA). This is the most secure option, as it ensures that the identity of the MariaDB server has been verified by a trusted third party. + - **Self-Signed Certificate:** This option allows you to use a self-signed certificate. This is less secure than using a CA certificate, as it does not ensure the identity of the MariaDB server has been verified by a trusted third party. However, it is a good option if you do not have access to a CA certificate. + - **None:** This option does not use SSL. This is the least secure option, as it allows anyone to intercept your communications with the MariaDB server. + +MariaDB + +
+ +
+ +## Querying MariaDB + +Once you have connected to the MariaDB datasource, follow these steps to write queries and interact with a MariaDB database from the ToolJet application: + +1. Click the **+ Add** button to open the list of available datasources. +2. Select **MariaDB** from the global datasource section. +3. Enter the SQL query in the editor. +4. Click **Preview** to view the data returned from the query or click **Run** to execute the query. + +:::tip +Query results can be transformed using Transformation. For more information on transformations, please refer to our documentation at **[link](/docs/beta/app-builder/custom-code/transform-data)**. +::: + +
+ +MariaDB query + +
+ +
+ +
+ +## CRUD Queries + +Suppose there exists a MariaDB database named _customers_. We can create an example table called _users_ with the following columns: + +- **id** (integer, auto-increment) +- **name** (varchar) +- **age** (integer) +- **email** (varchar) + +```sql +CREATE TABLE user( + id INT AUTO_INCREMENT PRIMARY KEY, + name VARCHAR(50), + age INT, + email VARCHAR(100) +); +``` + +The above command will create the _users_ table within the _customers_ database. Now, let's explore the CRUD commands for this table in MariaDB: + +### Create (Insert) + +#### To Insert a Single User: + +```sql +INSERT INTO user (name, age, email) +VALUES ('John Doe', 25, 'john@example.com'); +``` + +
+ +MariaDB query + +
+ +#### To Insert Multiple Users: + +```sql +INSERT INTO user (name, age, email) +VALUES + ('John Doe', 25, 'john@example.com'), + ('Jane Smith', 30, 'jane@example.com'), + ('Bob Johnson', 35, 'bob@example.com'); +``` + +
+ +MariaDB query + +
+ +### Read (Select) + +#### To Retrieve All Users: + +```sql +SELECT * FROM user; +``` + +
+ +MariaDB query + +
+ +#### To Retrieve Specific Columns From Users: + +```sql +SELECT name, age, email FROM user; +``` + +
+ +MariaDB query + +
+ +#### To Add Conditions and Filters to the Selection: + +```sql +SELECT name, age, email +FROM user +WHERE age > 25; +``` + +
+ +MariaDB query + +
+ +### Update + +#### To Update the Age of a User: + +```sql +UPDATE user +SET age = 26 +WHERE id = 1; +``` + +
+ +MariaDB query + +
+ +### Delete + +#### To Delete a User: + +```sql +DELETE FROM user WHERE id = 1; +``` + +
+ +MariaDB query + +
+ +Remember to adjust the values and conditions based on your specific needs. These commands will allow you to create the table, insert data, retrieve data, update data, and delete data in the _users_ table in MariaDB. + +
+ +
+ +## Troubleshooting Tips + +If you are having trouble connecting a MariaDB data source to ToolJet, try the following: + +- Make sure that your MariaDB server is running and accessible from the ToolJet server. +- Check the spelling and capitalization of your credentials. +- Try restarting the ToolJet server. + +If you are still having trouble, please contact [ToolJet support](mailto:hello@tooljet.com) or ask on [slack](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) for assistance. + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/minio.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/minio.md new file mode 100644 index 0000000000..bd3d5b61fd --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/minio.md @@ -0,0 +1,144 @@ +--- +id: minio +title: MinIO +--- + +ToolJet can connect to minio and perform various operation on them. + +
+ +## Connection + +To establish a connection with the MinIo data source, click on the **+ Add new data source** button located on the query panel or navigate to the [Data Sources](/docs/data-sources/overview) page from the ToolJet dashboard. + +ToolJet requires the following to connect to your DynamoDB: + +- **Host** +- **Port** +- **Access key** +- **Secret key** + +miniIo connect + +
+ +
+ +## Querying Minio + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the data source added in the previous step as the data source. +3. Select the operation that you want to perform. +4. Click on the **Run** button to run the query + +miniIo query + +:::tip +Query results can be transformed using transformations. Read our transformations documentation to see how: [link](/docs/beta/app-builder/custom-code/transform-data) +::: + +
+ +
+ +## Supported Operations + +- **[Read object](#read-object)** +- **[Put object](#put-object)** +- **[Remove object](#remove-object)** +- **[List buckets](#list-buckets)** +- **[List objects in a bucket](#list-objects-in-a-bucket)** +- **[Presigned url for download](#presigned-url-for-download)** +- **[Presigned url for upload](#presigned-url-for-upload)** + +minIo Operations + +### Read Object + +Retrieve an object from a bucket. + +#### Required Parameter: + +- **Bucket** +- **Object Name** + +minIo read object + +### Put Object + +Upload or update an object in a bucket. + +#### Required Parameter: + +- **Bucket** +- **Object Name** +- **Upload data** + +#### Optional Parameter: + +- **Content Type** + +minIo put object + +### Remove Object + +Delete an object from a bucket. + +#### Required Parameter: + +- **Bucket** +- **Object Name** + +minIo remove object + +### List Buckets + +Retrieve a list of all buckets. + +minIo list bucket + +### List Objects in a Bucket + +List objects within a specified bucket. + +#### Required Parameters + +- **Bucket** + +#### Optional Parametes + +- **Prefix** + +minIo list objects in a bucket + +### Presigned URL for Download + +Generate a presigned URL for downloading an object. + +#### Required Parameter: + +- **Bucket** +- **Object Name** + +#### Optional Parameter: + +- **Expires in** + +minIo presigned url for download + +### Presigned URL for Upload + +Generate a presigned URL for uploading an object. + +#### Required Parameter: + +- **Bucket** +- **Object Name** + +#### Optional Parameter: + +- **Expires in** + +minIo presigned url for download + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/mongodb.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/mongodb.md new file mode 100644 index 0000000000..4b130087ed --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/mongodb.md @@ -0,0 +1,591 @@ +--- +id: mongodb +title: MongoDB +--- + +ToolJet can connect to MongoDB to read and write data. + +
+ +## Manual Connection + +To establish a manual connection with the **MongoDB** data source, click on the **+ Add new data source** button located on the query panel or navigate to the [Data Sources](/docs/data-sources/overview) page from the ToolJet dashboard. + +:::info +Please make sure the **Host/IP** of the database is accessible from your VPC if you have self-hosted ToolJet. If you are using ToolJet cloud, please **whitelist** our IP. +::: + +ToolJet requires the following to connect to your MongoDB. + +- **Host** +- **Port** +- **Username** +- **Password** + +**Note:** It is recommended to create a new MongoDB user so that you can control the access levels of ToolJet. + +ToolJet - Mongo connection + +### Secure Sockets Layer (SSL) + +- **SSL Certificate**: SSL certificate to use with MongoDB. Supported Types: + - **None**: No SSL certificate verification. + - **CA Certificate**: Requires a CA certificate to verify the server certificate. + - **Client Certificate**: Requires a client certificate, client key, and CA certificate to authenticate with the server. + +MongoDB - SSL Certificate + +
+ +
+ +## Connect Using Connecting String + +You can also use a **Connection String** by switching the method from the dropdown. You will be prompted to enter the details of your MongoDB connection. + +ToolJet requires the following to connect to your MongoDB using Connecting String: + +- **Connection String** + +:::info +The connection string typically looks like this: `mongodb+srv://${username}:${password}@${cluster}/{database}`. + +For example: `mongodb+srv://tooljettest:dummypassword@cluster0.urul7.mongodb.net/hrms` +::: + +ToolJet - Mongo connection + +**Note:** Make sure to replace username, password, cluster, and database with your actual MongoDB details. If your MongoDB instance requires additional connection options, you can usually append these options to the connection string. + +
+ +
+ +## Querying MongoDB + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor and select the database added in the previous step as the data source. +2. Select the operation that you want to perform and click **Save** to save the query. +3. Click on the **Run** button to run the query. + +ToolJet - Mongo query + +:::tip +Query results can be transformed using transformations. Read our transformations documentation to see how: [link](/docs/beta/app-builder/custom-code/transform-data) +::: + +
+ +## Supported Operations + +- **[List Collections](#list-collections)** +- **[Find One](#find-one)** +- **[Find Many](#find-many)** +- **[Total Count](#total-count)** +- **[Count](#count)** +- **[Distinct](#distinct)** +- **[Insert One](#insert-one)** +- **[Insert Many](#insert-many)** +- **[Update One](#update-one)** +- **[Update Many](#update-many)** +- **[Replace One](#replace-one)** +- **[Find One and Update](#find-one-and-update)** +- **[Find One and Replace](#find-one-and-replace)** +- **[Find One and Delete](#find-one-and-delete)** +- **[Aggregate](#aggregate)** +- **[Delete One](#delete-one)** +- **[Delete Many](#delete-many)** +- **[Bulk Operations](#bulk-operations)** + +### List Collections + +Returns list of collections + +ToolJet - Mongo DB List Collection + +### Find One + +Return a document which satisfy the given filter and options. [Reference](https://docs.mongodb.com/drivers/node/v4.0/usage-examples/findOne) + +#### Required Parameters: + +- **Collection** + +#### Optional Parameters: + +- **Filter** +- **Option** + +ToolJet - Mongo DB Find One + +### Find Many + +Return list of documents which satisfy the given filter and options. [Reference](https://docs.mongodb.com/drivers/node/v4.0/usage-examples/find/) + +#### Required Parameters: + +- **Collection** + +#### Optional Parameters: + +- **Filter** +- **Option** + +ToolJet - Mongo DB Find Many + +### Total Count + +Returns an estimation of the number of documents in the collection based on collection metadata. [Reference](https://mongodb.github.io/node-mongodb-native/4.0/classes/collection.html#estimateddocumentcount) + +#### Required Parameters: + +- **Collection** + +#### Optional Parameters: + +- **Option** + +ToolJet - Mongo DB Total Count + +### Count + +Returns the number of documents based on the filter. [Reference](https://mongodb.github.io/node-mongodb-native/4.0/classes/collection.html#countdocuments) + +#### Required Parameters: + +- **Collection** + +#### Optional Parameters: + +- **Filter** +- **Option** + +ToolJet - Mongo DB Count + +### Distinct + +Retrieve a list of distinct values for a field based on the filter. [Reference](https://docs.mongodb.com/drivers/node/v4.0/usage-examples/distinct/) + +#### Required Parameters: + +- **Collection** +- **Field** + +#### Optional Parameters: + +- **Filter** +- **Option** + +ToolJet - Mongo DB Find One + +### Insert One + +Insert a document. [Reference](https://docs.mongodb.com/drivers/node/v4.0/usage-examples/insertOne/) + +#### Required Parameters: + +- **Collection** +- **Document** + +#### Optional Parameters: + +- **Option** + +ToolJet - Mongo DB Insert One + +#### Example: + +```json +{ + "name": "John Doe", + "age": 30 +} +``` + +### Insert Many + +Insert list of documents. [Reference](https://docs.mongodb.com/drivers/node/v4.0/usage-examples/insertMany/) + +#### Required Parameters: + +- **Collection** +- **Document** + +#### Optional Parameters: + +- **Option** + +ToolJet - Mongo DB Insert Many + +#### Example + +```json +[ + { + "name": "Product1", + "price": 100 + }, + { + "name": "Product2", + "price": 150 + } +] +``` + +### Update One + +Update a document based on the filter. [Reference](https://docs.mongodb.com/drivers/node/v4.0/usage-examples/updateOne/) + +#### Required Parameters: + +- **Collection** +- **Filter** +- **Update** + +#### Optional Parameters: + +- **Option** + +ToolJet - Mongo DB Update One + +#### Example + +##### Filter + +```json +{ + "name": "John Doe" +} +``` + +##### Update + +```json +{ + "$set": { + "age": 31 + } +} +``` + +### Update Many + +Update many documents based on the filter. [Reference](https://docs.mongodb.com/drivers/node/v4.0/usage-examples/updateMany/) + +#### Required Parameters: + +- **Collection** +- **Filter** +- **Update** + +#### Optional Parameters: + +- **Option** + +ToolJet - Mongo DB Update Many + +#### Example + +##### Filter + +```json +{ + "status": "pending" +} +``` + +##### Update + +```json +{ + "$set": { + "status": "completed" + } +} +``` + +### Replace One + +Replace a document based on filter. [Reference](https://docs.mongodb.com/drivers/node/v4.0/usage-examples/replaceOne/) + +#### Required Parameters: + +- **Collection** +- **Filter** +- **Replacement** + +#### Optional Parameters: + +- **Option** + +ToolJet - Mongo DB Find One + +#### Example + +##### Filter + +```json +{ + "product_id": 123 +} +``` + +##### Replacement + +```json +{ + "product_id": 123, + "name": "New Product", + "price": 200 +} +``` + +### Find One and Update + +If your application requires the document after updating, use this instead of **Update One**. [Reference](https://mongodb.github.io/node-mongodb-native/4.0/classes/collection.html#findoneandupdate) + +#### Required Parameters: + +- **Collection** +- **Filter** +- **Update** + +#### Optional Parameters: + +- **Option** + +ToolJet - Mongo DB Find One and Update + +#### Example + +##### Filter + +```json +{ + "employee_id": 456 +} +``` + +##### Update + +```json +{ + "$inc": { + "salary": 5000 + } +} +``` + +### Find One and Replace + +If your application requires the document after updating, use this instead of **Replace One**. [Reference](https://mongodb.github.io/node-mongodb-native/4.0/classes/collection.html#findoneandreplace) + +#### Required Parameters: + +- **Collection** +- **Filter** +- **Replacement** + +#### Optional Parameters: + +- **Option** + +ToolJet - Mongo DB Find One and Replace + +#### Example + +##### Filter + +```json +{ + "product_id": 789 +} +``` + +##### Replacement + +```json +{ + "product_id": 789, + "name": "Updated Product", + "price": 300 +} +``` + +### Find One and Delete + +If your application requires the document after deleting, use this instead of **Delete One**. [Reference](https://mongodb.github.io/node-mongodb-native/4.0/classes/collection.html#findoneanddelete) + +#### Required Parameters: + +- **Collection** +- **Filter** + +#### Optional Parameters: + +- **Option** + +ToolJet - Mongo DB Find One and Delete + +#### Example + +```json +{ + "order_id": 101 +} +``` + +### Aggregate + +Aggregation operations are expressions you can use to produce reduced and summarized results. [Reference](https://docs.mongodb.com/drivers/node/v4.0/fundamentals/aggregation/) + +#### Required Parameters: + +- **Collection** +- **Pipeline** + +#### Optional Parameters: + +- **Option** + +ToolJet - Mongo DB Aggregate + +#### Example + +```json +[ + { + "$match": { + "status": "completed" + } + }, + { + "$group": { + "_id": "$product_id", + "totalSales": { + "$sum": "$amount" + } + } + } +] +``` + +### Delete One + +Delete a record based on the filter. [Reference](https://docs.mongodb.com/drivers/node/v4.0/usage-examples/deleteOne/) + +#### Required Parameters: + +- **Collection** +- **Filter** + +#### Optional Parameters: + +- **Option** + +ToolJet - Mongo DB Find One + +#### Example + +```json +{ + "user_id": 123 +} +``` + +### Delete Many + +Delete many records based on the filter. [Reference](https://docs.mongodb.com/drivers/node/v4.0/usage-examples/deleteMany/) + +#### Required Parameters: + +- **Collection** +- **Filter** + +#### Optional Parameters: + +- **Option** + +ToolJet - Mongo DB Find One + +#### Example + +```json +{ + "status": "cancelled" +} +``` + +### Bulk Operations + +Perform bulk operations. [Reference](https://docs.mongodb.com/drivers/node/v4.0/usage-examples/bulkWrite/) + +#### Required Parameters: + +- **Collection** +- **Operations** + +#### Optional Parameters: + +- **Option** + +ToolJet - Mongo DB Bulk Operations + +#### Example + +```json +[ + { + "insertOne": { + "document": { + "item": "apple", + "quantity": 50 + } + } + }, + { + "updateOne": { + "filter": { + "item": "orange" + }, + "update": { + "$set": { + "quantity": 100 + } + } + } + }, + { + "deleteOne": { + "filter": { + "item": "banana" + } + } + } +] +``` + +
+ +
+ +## Dynamic Queries + +Dynamic queries in MongoDB can be used to create flexible and parameterized queries. + +#### Example + +```javascript +{ amount: { $lt: '{{ components.textinput1.value }}' }} + +// Dates +// supported: Extended JSON syntax +{ createdAt: { $date: '{{ new Date('01/10/2020') }}'} } +// not supported: MongoDB classic syntax +{ createdAt: new Date('01/10/2020') } +``` + +Reference on [mongodb extended JSON](https://docs.mongodb.com/manual/reference/mongodb-extended-json/) supported data types. + +
+ +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/mssql.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/mssql.md new file mode 100644 index 0000000000..4b12addb99 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/mssql.md @@ -0,0 +1,151 @@ +--- +id: mssql +title: MS SQL Server / Azure SQL Databases +--- + +ToolJet can connect to MS SQL Server & Azure SQL databases to read and write data. + +
+ +## Connection + +To establish a connection with the MS SQL Server data source, click on the **+ Add new Data source** button located on the query panel or navigate to the [Data Sources](/docs/data-sources/overview) page from the ToolJet dashboard. + +:::info +Please make sure the **Host/IP** of the database is accessible from your VPC if you have self-hosted ToolJet. If you are using ToolJet cloud, please **whitelist** our IP. +::: + +ToolJet requires the following to connect to your PostgreSQL database. + +- **Host** +- **Port** +- **Username** +- **Password** +- **Connection Options** +- **Azure** (Select this option if you are using Azure SQL databases) + +**Note:** It is recommended to create a new database user so that you can control the access levels of ToolJet. + +ToolJet - Redis connection + +### Connection Options + +You can add optional configurations in **key-value pairs** for the MS SQL data source connection. + +#### Example: +| Key | Value | +|:------------------------|:--------| +| trustServerCertificate | true | + +These options allow you to fine-tune the connection, such as enabling encryption when using a self-signed certificate. + +### Enabling Encryption with a Self-Signed Certificate + +To enhance security during data transfer, encryption can be enabled even with a self-signed certificate. + +#### Server-Side Configuration + +1. **Create and Install a Self-Signed Certificate:** + - Generate a self-signed certificate and install it on the SQL Server instance. +2. **Force Encryption:** + - Configure the SQL Server instance to force encrypted connections. + - For Azure SQL databases, turn on the **Encryption** toggle in the Azure portal. + +#### Client-Side Configuration + +1. Set the connection option `trustServerCertificate` to `true`. + - This bypasses certificate chain validation and is necessary when using a self-signed certificate. + +
+ +
+ +## Querying in SQL Mode + +SQL mode can be used to query MS SQL Server / Azure SQL Databases using SQL queries. + +1. Create a new query and select the MS SQL data source. +2. Select **SQL mode** from the dropdown. +3. Enter the SQL query in the editor. +4. Click on the **Run** button to run the query. + +#### Example + +```sql +SELECT * FROM users +``` + +ToolJet mssql sql mode + +### Parameterized Queries + +ToolJet offers support for parameterized SQL queries, which enhance security by preventing SQL injection and allow for dynamic query construction. To implement parameterized queries: + +1. Use `:parameter_name` as placeholders in your SQL query where you want to insert parameters. +2. In the **Parameters** section below the query editor, add key-value pairs for each parameter. +3. The keys should match the parameter names used in the query (without the colon). +4. The values can be static values or dynamic values using the `{{ }}` notation. + +
+Postgresql parameterized SQL queries +
+ +##### Example: + +```yaml +Query: SELECT * FROM users WHERE username = :username +``` +SQL Parameters: +- Key: username +- Value: oliver // or `{{ components.username.value }}` + +### Row Level Security + +In ToolJet, you can set up server-side row-level security to restrict access to specific rows based on custom groups or default user roles. Refer to the [Setup Row Level Security](#) guide for more information. + +### Query Timeout + +You can set the timeout duration for SQL queries by adding the `PLUGINS_SQL_DB_STATEMENT_TIMEOUT` variable to the environment configuration file. By default, it is set to 120,000 ms. + +### MS SQL Server Dynamic Functions and System Variables + +SQL Server provides dynamic functions that return information about the current connection, database, user, and server. These can help you write queries that automatically adapt to different environments without hardcoding values. + +| Function / Variable | Description | Example Output | +| ------------------- | -------------------------------------------------- | ------------------------------------ | +| `DB_NAME()` | Returns the name of the current database | `tooljet_db` | +| `SUSER_SNAME()` | Returns the login name of the current user | `app_user` | +| `USER_NAME()` | Returns the database user name of the current user | `dbo` | +| `SYSTEM_USER` | Returns the current system login (login name) | `app_user` | +| `@@SERVERNAME` | Returns the name of the SQL Server instance | `MSSQLSERVER01` | +| `@@VERSION` | Returns the SQL Server version and build info | `Microsoft SQL Server 2019 (RTM)...` | +| `@@SPID` | Returns the current session ID | `55` | + +
+ +
+ +## Querying in GUI Mode + +GUI mode can be used to query MS SQL Server / Azure SQL Databases without writing queries. + +1. Create a new query and select the MS SQL data source. +2. Select **GUI mode** from the dropdown. +3. Choose the operation **Bulk update using the primary key**. +4. Enter the **Table** name and **Primary key** column name. +5. In the editor, enter the records in the form of an array of objects. +6. Click on the **Run** button to run the query. + +#### Example + +```json +{{ [ {id: 1, channel: 33}, {id: 2, channel: 24} ] }} +``` + +ToolJet mssql gui mode + +:::tip +Query results can be transformed using transformations. Read our transformations documentation to see how: [link](/docs/beta/app-builder/custom-code/transform-data) +::: + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/mysql.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/mysql.md new file mode 100644 index 0000000000..6d8aa4fdfa --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/mysql.md @@ -0,0 +1,136 @@ +--- +id: mysql +title: MySQL +--- + +ToolJet can connect to MySQL databases to read and write data. + +
+ +## Connection + +To establish a connection with the MySQL data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page through the ToolJet dashboard. + +MySQL data source + +:::info +Please make sure the **Host/IP** of the database is accessible from your VPC if you have self-hosted ToolJet. If you are using ToolJet cloud, please **whitelist** our IP. +::: + +**ToolJet requires the following to connect to your MySQL database:** + +- **Username** +- **Password** +- **Database Name** +- **Connection Type** + +If you are using **Hostname** as the connection type, you will need to provide the following information: + +- **Host/IP** +- **Port** +- **SSL** +- **SSL Certificate**: + - **CA Certificate** + - **Self-signed Certificate** + - **None** + +If you are using **Socket** as the connection type, you will need to provide the following information: + +- **Socket Path** + +**Note:** It is recommended to create a new MySQL database user so that you can control the access levels of ToolJet. + +mysql + +
+ +
+ +## Querying in SQL Mode + +SQL mode can be used to query MySQL database using SQL queries. + +1. Create a new query and select the MySQL data source. +2. Select **SQL mode** from the dropdown. +3. Enter the SQL query in the editor. +4. Click on the **Run** button to run the query. + +**Example:** + +```sql +SELECT * FROM users +``` + +mysql + +### Parameterized Queries + +ToolJet offers support for parameterized SQL queries, which enhance security by preventing SQL injection and allow for dynamic query construction. To implement parameterized queries: + +1. Use `:parameter_name` as placeholders in your SQL query where you want to insert parameters. +2. In the **Parameters** section below the query editor, add key-value pairs for each parameter. +3. The keys should match the parameter names used in the query (without the colon). +4. The values can be static values or dynamic values using the `{{ }}` notation. + +mysql + +##### Example: + +```yaml +Query: SELECT * FROM users WHERE username = :username +``` +SQL Parameters: +- Key: username +- Value: oliver // or `{{ components.username.value }}` + +### Row Level Security + +In ToolJet, you can set up server-side row-level security to restrict access to specific rows based on custom groups or default user roles. Refer to the [Setup Row Level Security](#) guide for more information. + +### Query Timeout + +You can set the timeout duration for SQL queries by adding the `PLUGINS_SQL_DB_STATEMENT_TIMEOUT` variable to the environment configuration file. By default, it is set to 120,000 ms. + +### MySQL Dynamic Functions and System Variables + +MySQL offers dynamic functions and system variables that provide real-time information about the current database, user session, connection, and server environment. These can help you write queries that automatically adapt to different environments without hardcoding values. + +| Function / Variable | Description | Example Output | +| ------------------- | ----------------------------------------------------------------- | -------------------- | +| `DATABASE()` | Returns the name of the current database in use | `tooljet_db` | +| `USER()` | Returns the current MySQL user account (user\@host) | `app_user@localhost` | +| `CURRENT_USER()` | Returns the authenticated user account (can differ from `USER()`) | `app_user@%` | +| `VERSION()` | Returns the MySQL server version | `8.0.33` | +| `@@hostname` | Returns the MySQL server hostname | `db-server-01` | +| `@@port` | Returns the MySQL server port number | `3306` | +| `CONNECTION_ID()` | Returns the connection ID for the current session | `123456` | + + +## Querying in GUI Mode + +GUI mode can be used to query MySQL database without writing queries. + +1. Create a new query and select the MySQL data source. +2. Select **GUI mode** from the dropdown. +3. Choose the operation **Bulk update using primary key**. +4. Enter the **Table** name and **Primary key column** name. +5. In the editor enter the records in the form of an array of objects. +6. Click on the **Run** button to run the query. + +**Example:** + +```json +{{ [ {id: 1, channel: 33}, {id:2, channel:24} ] }} +``` + +
+ +mysql + +
+ +:::tip +Query results can be transformed using transformations. Learn more about transformations [here](/docs/beta/app-builder/custom-code/transform-data). +::: + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/n8n.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/n8n.md new file mode 100644 index 0000000000..efdc669060 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/n8n.md @@ -0,0 +1,73 @@ +--- +id: n8n +title: n8n +--- + +ToolJet can trigger n8n workflows using webhook URLs. Please refer [this](https://docs.n8n.io/) to know more about n8n. + +
+ +## Connection + +To establish a connection with the n8n data source, click on the **+ Add new Data source** button located on the query panel or navigate to the [Data Sources](/docs/data-sources/overview) page from the ToolJet dashboard. + +Webhooks in n8n can be configured to operate with or without **Authentication**. If no authentication is required, select `None` as the **Authentication type**. For webhooks that require authentication, choose the appropriate method from the dropdown and provide the corresponding credentials. + +### Authentication Types +- **Basic Auth**: To connect your n8n webhooks using basic auth you'll need to provide the following credentials: + - **Username** + - **Password** + +
+ +n8n basicauth + +
+ +- **Header Auth**: To connect your n8n webhooks using header auth the following fields are required: + - **Name / Key** + - **Value** + +
+ +n8n headerauth + +
+ +:::tip +Webhook credentials and instance credentials are different. Please use the credentials that you use with the webhook trigger. Know more: **[Webhook Authentication](https://docs.n8n.io/nodes/n8n-nodes-base.webhook/#:~:text=then%20gets%20deactivated.-,Authentication,-%3A%20The%20Webhook%20node)**. +::: + +
+ +
+ +## Trigger Workflow + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the database added in the previous step as the data source. + +Once the n8n data source is added, you can trigger a workflow with `GET/POST` URL. + +### GET Method + +Choose the GET Method from the dropdown. + +#### Optional Parameter: + - **URL parameters** + +n8n query + +### POST Method + +Choose the POST Method from the dropdown. + +#### Required Parameter: + - **Body** + +#### Optional Parameter: + - **URL parameters** + +n8n query + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/nocodb.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/nocodb.md new file mode 100644 index 0000000000..bfefb43859 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/nocodb.md @@ -0,0 +1,163 @@ +--- +id: nocodb +title: NocoDB +--- + +ToolJet lets you connect with NocoDB to perform actions and retrieve data. + +
+ +## Connection + +To connect to the NocoDB data source in ToolJet, you can either click on the **+ Add new data source** button on the query panel or navigate to the [Data Source](/docs/data-sources/overview/) page on the ToolJet Dashboard. + +Connecting to your NocoDB database requires the following details: + +- **API token** +- **Host** + +NocoDB Connection + +
+ +
+ +## Supported Operations + +ToolJet supports the following operations for NocoDB: + +- **[List records](#list-records)** +- **[Get count](#get-count)** +- **[Get record](#get-record)** +- **[Create record](#create-record)** +- **[Update record](#update-record)** +- **[Delete record](#delete-record)** + +### List Records + +This operation retrieves a list of records present in the specified table. + +#### Required Parameters +- **Table ID** + +#### Optional Parameters +- **Query String** + +NocoDB List Records + +
+**Example Values** + +```yaml +Table ID: your-table-id +``` + +
+ +### Get Count + +This operation can be used to fetch the number of records present in the table. + +#### Required Parameters +- **Table ID** + +#### Optional Parameters +- **Query String** + +NocoDB Get Count + +
+**Example Values** + +```yaml +Table ID: your-table-id +``` + +
+ +### Get Record + +This operation can be used to fetch the record specified by the Table ID and Row ID. + +#### Required Parameters +- **Table ID** +- **Row ID** + +#### Optional Parameters +- **Query String** + +NocoDB Get Record + +
+**Example Values** + +```yaml +Table ID: your-table-id +Row ID: your-row-id +``` + +
+ +### Create Record + +This operation can be used to create new records. + +#### Required Parameters +- **Table ID** +- **Records** + +NocoDB Create Record + +
+**Example Values** + +```yaml +Table ID: your-table-id +Records: {title: 'ToolJet'} +``` + +
+ +### Update Record + +This operation can be used to update the record. + +#### Required Parameters +- **Table ID** +- **Row ID** +- **Records** + +NocoDB Update Record + +
+**Example Values** + +```yaml +Table ID: your-table-id +Row ID: your-row-id +Records: {title: 'NocoDB'} +``` + +
+ +### Delete Record + +This operation can be used to delete a record. + +#### Required Parameters +- **Table ID** +- **Row ID** + +NocoDB Delete Record + +
+**Example Values** + +```yaml +Table ID: your-table-id +Row ID: your-row-id +``` + +
+ +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/notion.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/notion.md new file mode 100644 index 0000000000..5e281ad038 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/notion.md @@ -0,0 +1,463 @@ +--- +id: notion +title: Notion +--- + +ToolJet can connect to a Notion workspace to do operations on notion pages, databases, users and blocks. + +
+ +## Connection + +To establish a connection with the Notion data source, click on the **+ Add new Data source** button located on the query panel or navigate to the [Data Sources](/docs/data-sources/overview) page from the ToolJet dashboard. + +For integrating Notion with ToolJet we will need the API token. The API token can be generated from your Notion workspace settings. Read the official Notion docs for [Creating an internal integration with notion API](https://www.notion.so/help/create-integrations-with-the-notion-api). + +
+ +notion api + +
+ +
+ +
+ +## Querying Notion + +Notion API provides support for: + +- **[Database](#querying-notion-database)** +- **[Page](#querying-notion-page)** +- **[Block](#querying-notion-blocks)** +- **[User](#querying-notion-user)** + +notion querying + +:::info +**Database ID**, **View ID** and **Page ID** can be found using notion workspace URL. + +For example: + +URL: `https://www.notion.so/workspace/XXX?v=YYY&p=ZZZ` + +Here: +- `XXX` is the **Database ID** +- `YYY` is the **View ID** +- `ZZZ` is the **Page ID** + +::: + +:::tip + +Before querying Notion, you must share the database with your integration. Click the share button in your database view, find your integration name select it. + +notion share + +::: + +
+ +
+ +## Querying Notion Database + +On database resource you can perform the following operations: + +- **[Retrieve a database](#retrieve-a-database)** +- **[Query a database](#query-a-database)** +- **[Create a database](#create-a-database)** +- **[Update a database](#update-a-database)** + +notion db + +### Retrieve a Database + +This operations retrieves a Database object using the ID specified. + +#### Required Parameters: + +- **Database ID** + +notion db retrieve + +### Query a Database + +This operation gets a list of **Pages** contained in the database, filtered and ordered according to the filter conditions and sort criteria provided in the query. + +#### Required Parameters: + +- **Database ID** + +#### Optional Parameters: + +- **Filter** +- **Sort** +- **Limit** +- **Start Cursor** + +notion db query + +### Create a Database + +This operation creates a database as a subpage in the specified parent page, with the specified properties. + +#### Required Parameters: + +- **Database ID** +- **Page ID** +- **Properties** + +#### Optional Parameters: + +- **Title** +- **Icon type** +- **Icon value** +- **Cover type** +- **Cover value** + +notion db create + +#### Example: +##### Title +```yaml +[ + { + "type": "text", + "text": { + "content": "Project Tasks Database", + "link": null + } + } +] +``` + +##### Properties +```yaml +{ + "Task Name": { + "title": {} + }, + "Due Date": { + "date": {} + }, + "Completed": { + "checkbox": {} + } +} +``` + +### Update a Database + +This operation updates an existing database as specified by the parameters. + +#### Required Parameters: + +- **Database ID** + +#### Optional Parameters: + +- **Title** +- **Properties** +- **Icon type** +- **Icon value** +- **Cover type** +- **Cover value** + +notion db update + +#### Example: +##### Title +```yaml +[ + { + "type": "text", + "text": { + "content": "Updated Tasks Database" + } + } +] +``` + +##### Properties +```yaml +{ + "Priority": { + "select": { + "options": [ + { "name": "High", "color": "red" }, + { "name": "Medium", "color": "yellow" }, + { "name": "Low", "color": "green" } + ] + } + }, + "Assigned To": { + "people": {} + } +} +``` + +
+ +
+ +## Querying Notion Page + +On page resource you can perform the following operations: + +- **[Retrieve a page](#retrieve-a-page)** +- **[Create a page](#create-a-page)** +- **[Update a page](#update-a-page)** +- **[Retrieve a page property](#retrieve-a-page-property-item)** +- **[Archive a page](#archive-delete-a-page)** + +notion page + +### Retrieve a Page + +This operation retrieves a **Page** object using the ID specified. + +#### Required Parameters: + +- **Page ID** + +notion page retrieve + +### Create a Page + +This operation creates a new page in the specified database or as a child of an existing page. If the parent is a database, the property values of the new page in the properties parameter must conform to the parent database's property schema. If the parent is a page, the only valid property is title. + +#### Required Parameters: + +- **Parent Type** +- **Page/Database ID** +- **Properties** + +#### Optional Parameters: +- **Children (Blocks)** +- **Icon type** +- **Icon value** +- **Cover type** +- **Cover value** + +notion page create + +#### Example: +```yaml +{ + "Title": { + "title": [ + { + "type": "text", + "text": { + "content": "New Page Title" + } + } + ] + } +} +``` + +### Update a Page + +This operation updates page property values for the specified page. Properties that are not set via the properties parameter will remain unchanged. + +#### Required Parameters: + +- **Page ID** +- **Properties** + +#### Optional Parameters + +- **Icon type** +- **Icon value** +- **Cover type** +- **Cover value** + +notion page update + +#### Example: +```yaml +{ + "Title": { + "title": [ + { + "type": "text", + "text": { + "content": "Updated Page Title" + } + } + ] + }, + "Status": { + "select": { + "name": "In Progress" + } + } +} +``` + +### Retrieve a Page Property Item + +This operation retrieves a property_item object for a given page ID and property ID. Depending on the property type, the object returned will either be a value or a paginated list of property item values. See Property item objects for specifics. + +#### Required Parameter: + +- **Page ID** + +#### Optional Parameters: + +- **Property ID** +- **Limit** +- **Start cursor** + +notion page retrieve page property + +### Archive (delete) a Page + +This operation archive or un archive the page specified using Page ID. + +#### Required Parameters: + +- **Page ID** +- **Archive** + +notion page retrieve page property + +
+ +
+ +## Querying Notion Blocks + +The following operations can be performed on the block resource: + +- **[Retrieve a block](#retrieve-a-block)** +- **[Append block children](#append-new-block-children)** +- **[Retrieve block children](#retrieve-block-children)** +- **[Update a block](#update-a-block)** +- **[Delete a block](#delete-a-block)** + +notion block + +:::info +To get the id for blocks, simply click on the menu icon for the block and click "Copy link". Afterwards, paste the link in the browser and it should look like this: `https://www.notion.so/Creating-Page-Sample-ee18b8779ae54f358b09221d6665ee15#7fcb3940a1264aadb2ad4ee9ffe11b0e` the string after **#** is the block id i.e. `7fcb3940a1264aadb2ad4ee9ffe11b0e`. +::: + +### Retrieve a Block + +This operation retrieves a **Block** object using the ID specified. + +#### Required parameters: + +- **Block ID** + +notion block retrieve + +### Append New Block Children + +This operation creates and appends new children blocks to the parent block_id specified. + +#### Required parameters: + +- **Block ID** +- **Children** + +notion block append + +### Retrieve Block Children + +This operation retrieves a paginated array of child block objects contained in the block using the ID specified. + +#### Required parameters: + +- **Block ID** + +#### Optional Parameters: + +- **Limit** +- **Start cursor** + +notion block append + +### Update a Block + +This operation updates the content for the specified block_id based on the block type. + +#### Required parameters: + +- **Block ID** + +#### Optional Parameters: + +- **Properties** +- **Archive** + +notion block update + +#### Example +```yaml +{ + "Title": { + "title": [ + { + "type": "text", + "text": { + "content": "Updated Page Title" + } + } + ] + }, + "Status": { + "select": { + "name": "In Progress" + } + } +} +``` + +### Delete a Block + +#### Required Parameters: + +- **Block ID** + +notion block delete + +
+ +
+ +## Querying Notion User + +The following operations can be performed on the user notion resource: + +- **[Retrieve a user from current workspace](#retrieve-a-user-from-current-workspace)** +- **[Retrieve list of users of a workspace](#retrieve-list-of-users-of-a-workspace)** + +notion user + +### Retrieve a User From Current Workspace + +This operation retrieves a User using the ID specified. + +#### Required Parameters: + +- **User ID** + +notion user retrieve a user + +### Retrieve List of Users of a Workspace + +This operation returns a paginated list of Users for the workspace. + +#### Optional Parameters: + +- **Limit** +- **Start cursor** + +notion user list all user + +[Read more about notion API](https://developers.notion.com/reference/intro) + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/openapi.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/openapi.md new file mode 100644 index 0000000000..1b8e63caf8 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/openapi.md @@ -0,0 +1,40 @@ +--- +id: openapi +title: OpenAPI +--- + +OpenAPI is a specification for designing and documenting RESTful APIs. Using OpenAPI datasource, ToolJet can generate REST API operations from OpenAPI Specs. + +
+ +## Connection + +Connections are created based on OpenAPI specifications. The available authentication methods currently supported are Basic Auth, API Key, Bearer Token, and OAuth 2.0. It is also possible to use specifications that require multiple authentications. Learn more [here](https://swagger.io/docs/specification/authentication/). + +OpenAPI datasource accepts specifications in JSON or YAML format only. After providing a valid JSON or YAML spec and selecting OAuth2 as the authentication type, you can enter custom headers and client credentials. + +You can also configure different hosts for different environments from the configuration page. The host configured here takes precedence over the host defined in the query or the specs itself. + +OpenAPI + +
+ +
+ +## Querying OpenAPI + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **OpenAPI** datasource added in previous step. +3. Select the desired operation. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +**Note**: Operations will be automatically generated from the specifications, and each operation will be distinct from others. + +### Fields + +- **Host** +- **Operation** + +OpenAPI + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/oracledb.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/oracledb.md new file mode 100644 index 0000000000..8a9d53afc0 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/oracledb.md @@ -0,0 +1,115 @@ +--- +id: oracledb +title: Oracle DB +--- + +ToolJet can connect to Oracle databases to read and write data. + +
+ +## Connection + +To establish a connection with the OracleDB datasource, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data sources](/docs/data-sources/overview)** page through the ToolJet dashboard. + +ToolJet requires the following to connect to a OracleDB datasource: + +- **Host** +- **Port** +- **SID / Service Name** (Database name must be a SID / Service Name) +- **Database Name** +- **SSL** +- **Username** +- **Password** +- **Client Library Path** + +ToolJet - Data source - OracleDB + +:::info +ToolJet includes Oracle Instant Client versions 21.10 and 11.2. If you need to use a different client library version: + +- For cloud deployments: You can add a custom client library to a directory of your choice or mount it as a volume in the container. +- For local setups: You can specify the path to your custom Oracle Client Library. + +This allows ToolJet to locate and use the specific drivers for Oracle database connections. +::: + +### Client Versions and Compatibility + +ToolJet runs Oracle DB connections in thick mode. By default, ToolJet includes Oracle instant client versions 21.10 and 11.2. These client versions determine which Oracle Database versions you can connect to. + +#### Available Client Versions + +- Oracle Instant Client 21.10 +- Oracle Instant Client 11.2 + +#### Compatibility + +The instant client version affects which Oracle Database versions you can connect to: + +- Oracle Instant Client 21.10 is compatible with Oracle Database 11.2 and later versions. +- Oracle Instant Client 11.2 is compatible with Oracle Database 10.2 and later versions. + +
+ +
+ +## Querying Oracle DB + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **OracleDB** datasource added in previous step. +3. Select the desired query mode. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +
+ +
+ +## Supported Operations + +- **[SQL mode](/docs/data-sources/oracledb#sql-mode)** +- **[GUI mode](/docs/data-sources/oracledb#gui-mode)** + +ToolJet - Data source - OracleDB + +### SQL mode + +SQL mode can be used to write raw SQL queries. + +```sql +SELECT first_name, last_name, email +FROM employees +WHERE department_id = 10 +ORDER BY last_name; +``` + +ToolJet - Data source - OracleDB + +### GUI mode + +GUI mode can be used to query Oracle database without writing queries. + +1. Select GUI mode from the dropdown. +2. Choose the operation **Bulk update using primary key**. +3. Enter the **Table** name and **Primary key** column name. +4. In the editor, enter the records in the form of an array of objects. + +```json +[ + { + "id": 1, + "channel": 33 + }, + { + "id": 2, + "channel": 24 + } +] +``` + +ToolJet - Data source - OracleDB + +:::tip +Query results can be transformed using transformations. Read our transformations documentation to see how: **[link](/docs/beta/app-builder/custom-code/transform-data)** +::: + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/overview.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/overview.md new file mode 100644 index 0000000000..5b78358d58 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/overview.md @@ -0,0 +1,56 @@ +--- +id: overview +title: Overview +--- + +# Data Sources : Overview + +Data Sources pull in and push data to various sources, including databases, external APIs, and services. Once a data source is connected to a workspace, the connection can be shared with any application within that workspace. + +ToolJet offers a wide range of data sources. If needed, you can develop and integrate a plugin of your choice or use an available one from the marketplace. Checkout **[Marketplace Overview Guide](/docs/marketplace/marketplace-overview)** for more information. + +Data Sources: Overview + +## Connecting data sources + +1. **Create a new app** from the dashboard, and Click on the **+** button from the query panel. + Data Sources: Overview + Or you can directly go to the **Data Sources** page from the left sidebar of the dashboard. + +2. Within the **Data Sources** page, you'll find various categories of data sources on the left side, including Databases, APIs, Cloud Storages, and plugins. Click on each category to view the list of accessible data sources. As you hover over the desired data source, an **+ Add** button will appear. Upon clicking this button, the selected data source will be integrated into the workspace. + Overview of Data Sources + +3. Once the data source is added, you'll be required to input the configuration details for establishing a connection.
+ ***Note: For paid plans, configuration entry and saving are necessary to enable availability across [multiple environments](/docs/development-lifecycle/environment/self-hosted/multi-environment).*** + Overview of Data Sources + +4. Return to your application query panel. The recently added data source will be accessible within the query panel under the **Available data sources** section. Data Sources that have been added can now be utilized in both **existing applications** and **newly created applications**. + Overview of Data Sources + +5. At this point, you can create queries to the connected data sources. Within these queries, the option exists to switch between **distinct connections** associated with the same data source, in cases where multiple connections have been established. + Overview of Data Sources + +## Default data sources + +By default, 4 data sources will be available on every app on ToolJet: +- **[ToolJet Database](/docs/tooljet-db/tooljet-database/)** +- **[RestAPI](/docs/data-sources/restapi/)** +- **[Run JavaScript Query](/docs/data-sources/run-js/)** +- **[Run Python Query](/docs/data-sources/run-py/)** + +Data Sources: Overview + +## Changing Scope of Data Sources on an App Created on Older Versions of ToolJet + +On ToolJet versions below 2.3.0, the data source connection was made from within the individual apps. To make it backward compatible, we added an option to change the scope of the data sources and make it global data source. + +1. When dealing with apps that were created using ToolJet versions prior to 2.3.0, you will notice the presence of the data source manager in the left sidebar of the App Builder. + Data Sources: Overview + +2. To change the scope, locate the kebab menu situated next to the connected data source. From this menu, select the **change scope** option. + Data Sources: Overview + +3. Once you change the scope of the data source and make it global, you'll see that the **data source manager** is removed from the left sidebar and now you'll find the data source on the **query panel** under Global Data sources. You can now configure the data source from the Data Sources page on the **dashboard**. + +4. Once you have successfully changed the scope of the data source, thereby transforming it into a global data source, you will observe that the **data source manager** from the left sidebar is removed. Subsequently, the data source will be accessible within the **query panel** under the Available data sources section. Now you can configure this data source from the Data Sources page located on the **Dashboard**. + Data Sources: Overview diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/permissions.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/permissions.md new file mode 100644 index 0000000000..1766d0c925 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/permissions.md @@ -0,0 +1,28 @@ +--- +id: permissions +title: Data Source Permissions +--- + +Admins and Super Admins can configure various permissions for a data source within a workspace, for detailed information on other permissions and access control, refer to the **[Access Control](/docs/user-management/role-based-access/access-control#data-sources)** Guide. + +## Permissions + +### Creation and Deletion of Data Sources + +| Permission | Description | +|:---|:---| +| **Create** | Add new data sources and modify existing ones. Delete button will not be visible on hovering over the connected data source. | +| **Delete** | Remove connected data sources from the workspace. Delete button will show up on hovering over the connected data source. | +| **Create and Delete** | Add new data sources and remove connected data sources from the workspace. | +| **Neither Create nor Delete** | No access to the Data Sources page from the Dashboard. Error toast will popup on trying to access the Data Sources page using URL. | + +Data Sources: Overview + +### Configure or Build with Data Sources + +| Permission | Description | +|:---|:---| +| **Build with** | Connect to authorized data sources for their user group. Users can't update the credentials of authorized data sources. | +| **Configure** | Users can update the credentials of authorized data sources. | + +Data Sources: Overview diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/postgresql.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/postgresql.md new file mode 100644 index 0000000000..f36b4b0142 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/postgresql.md @@ -0,0 +1,138 @@ +--- +id: postgresql +title: PostgreSQL +--- + +ToolJet has the capability to connect to PostgreSQL databases for data retrieval and modification. + +
+ +## Establishing a Connection + +To establish a connection with the PostgreSQL data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page from the ToolJet dashboard and choose PostgreSQL as the data source. + +ToolJet offers two connection types to connect to your PostgreSQL database: + +- **[Manual connection](#manual-connection)** +- **[Connection string](#connection-string)** + +### Manual Connection + +To connect to PostgreSQL using Manual connection parameters, select **Manual connection** as the connection type and provide the following details: + +- **Host** +- **Port** +- **SSL** +- **Database Name** +- **Username** +- **Password** +- **Connection Options** +- **SSL Certificate** + +PG connection + +### Connection String + +To connect to PostgreSQL using a connection string, select **Connection String** as the connection type and provide the following details: + +- **Connection String** + +PG connection string + +

+ +**Note:** We recommend creating a new PostgreSQL database user to have control over ToolJet's access levels. + +:::info +Please make sure the **Host/IP** of the database is accessible from your VPC if you have self-hosted ToolJet. If you are using ToolJet cloud, please **whitelist** our IP. +::: + +
+ +
+ +## Querying in SQL Mode + +1. Create a new query and select the PostgreSQL data source. +2. Select the SQL query mode from the dropdown and enter the query. +3. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +PG connection + +### Parameterized Queries + +ToolJet offers support for parameterized SQL queries, which enhance security by preventing SQL injection and allow for dynamic query construction. To implement parameterized queries: + +1. Use `:parameter_name` as placeholders in your SQL query where you want to insert parameters. +2. In the **Parameters** section below the query editor, add key-value pairs for each parameter. +3. The keys should match the parameter names used in the query (without the colon). +4. The values can be static values or dynamic values using the `{{ }}` notation. + +Postgresql parameterized SQL queries + +#### Example: + +```yaml +Query: SELECT * FROM users WHERE username = :username +``` +SQL Parameters:
+- Key: username
+- Value: oliver or `{{ components.username.value }}` + +### Row Level Security + +In ToolJet, you can set up server-side row-level security to restrict access to specific rows based on custom groups or default user roles. Refer to the [Setup Row Level Security](#) guide for more information. + +### Query Timeout + +You can set the timeout duration for SQL queries by adding the `PLUGINS_SQL_DB_STATEMENT_TIMEOUT` variable to the environment configuration file. By default, it is set to 120,000 ms. + +### PostgreSQL Dynamic Functions and System Variables + +PostgreSQL offers dynamic functions that provide runtime information about the current session, connection, database, and server settings. These can help you write queries that automatically adapt to different environments without hardcoding values. + +| Function / Variable | Description | Example Output | +| -------------------- | --------------------------------------------------------------------- | ------------------------------------------- | +| `current_database()` | Returns the name of the current database | `tooljet_db` | +| `current_user` | Returns the name of the current user | `app_user` | +| `session_user` | Returns the session user (same as `current_user` unless role changes) | `app_user` | +| `version()` | Returns the PostgreSQL server version | `PostgreSQL 15.3 on x86_64-pc-linux-gnu...` | +| `inet_server_addr()` | Returns the IP address of the server | `192.168.1.10` | +| `inet_server_port()` | Returns the server port | `5432` | +| `pg_backend_pid()` | Returns the process ID of the current backend | `56789` | + +
+ +
+ +## Querying in GUI Mode + +1. Create a new query and select the PostgreSQL data source. +2. Select the GUI mode from the dropdown. +3. Select the operation **Bulk update using primary key**. +4. Provide the **Table** name and the **Primary key column** name. +5. Then, in the editor, input the **records** as an array of objects. +6. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +PG connection + +```json +[ + { + "customer_id": 1, + "country": "India" + }, + { + "customer_id": 2, + "country": "USA" + } +] +``` + +:::tip + +- You can apply transformations to the query results. Refer to our transformations documentation for more details: **[Transformation Tutorial](/docs/beta/app-builder/custom-code/transform-data)** +- Check out this how-to guide on **[bulk updating multiple rows](/docs/how-to/bulk-update-multiple-rows)** from a table component. + ::: + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/redis.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/redis.md new file mode 100644 index 0000000000..b5fab26f70 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/redis.md @@ -0,0 +1,101 @@ +--- +id: redis +title: Redis +--- + +ToolJet enables you to execute Redis commands on your Redis instances. + +
+ +## Connecting to Redis + +To establish a connection with the Redis data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page from the ToolJet dashboard and choose Redis as the data source. + +Redis Connection + +To connect ToolJet with Redis, you need to provide the following connection details: + +- **Host**: The address or hostname of the Redis server. +- **Port**: The port number used by the Redis server (default is 6379). +- **Username**: The username used for authentication. +- **Password**: The password used for authentication. +- **TLS**: Toggle to enable/disable TLS connection. +- **TLS Certificate**: Choose the type of TLS certificate (None, CA certificate, or Client certificate). + +Depending on the TLS certificate option selected, you may need to provide additional information: +- For **CA certificate**: + - **CA Cert**: The CA certificate for TLS connection. +- For **Client certificate**: + - **CA Cert**: The CA certificate for TLS connection. + - **Client Key**: The client key for TLS connection. + - **Client Cert**: The client certificate for TLS connection. + +
+ +
+ +## Querying Redis + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **Redis** datasource added in previous step. +3. Enter the query. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +Here are some examples of Redis commands and their usage. You can refer to the [Redis Official Documentation](https://redis.io/commands) for a complete list of supported commands. + +### PING Command + +The `PING` command is used to test the connection to Redis. If the connection is successful, the Redis server will respond with **PONG**. + +```shell +PING +``` + +Redis Connection + +### SET Command + +The `SET` command is used in Redis to assign a value to a specific key. + +```shell +SET key value +``` + +#### Example +When the input value contains spaces, you should encode the value before providing it as an input: + +```shell +SET products {{encodeURI('John Doe')}} +``` + +Redis Example Encode + +### GET Command + +The `GET` command is used in Redis to retrieve the value associated with a specific key. + +```shell +GET key +``` + +#### Example +To retrieve a value that was previously encoded while setting, you can use transformations. + +1. Enter the GET command in the editor: + ```shell + GET products + ``` + +2. Enable Transformations (JS) and use `decodeURI`: + + ```js + return JSON.parse(decodeURI(data)); + ``` + +
+ + Redis Example Decode + +
+ +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/restapi/authentication.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/restapi/authentication.md new file mode 100644 index 0000000000..987521a16f --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/restapi/authentication.md @@ -0,0 +1,130 @@ +--- +id: authentication +title: Authentication +--- + +ToolJet’s REST API data source supports various authentication types to authenticate the user with the REST API service. The supported authentication types are Basic, Bearer, and OAuth 2.0. + +## Basic Authentication + +ToolJet’s REST API data source supports Basic Authentication as the authentication type. Basic Authentication is a simple authentication scheme built into the HTTP protocol. + +### Configuring REST API Data Source with Basic Authentication + +1. Go to the **Data Sources** page from the ToolJet dashboard, select **API** category on sidebar and choose the **REST API** data source. +2. In the **Base URL** field, enter the base URL. The base URL specifies the network address of the API service. For example, `http://localhost:3001/api/basic-auth` +3. Enter the **Headers** if required. Headers are key-value pairs to include as headers with REST API requests. +4. Select **Authentication** type as *Basic* from the dropdown. +5. Enter the **Username** and **Password** in the respective fields. The username and password are the credentials required to authenticate the user. + +ToolJet - Data source - REST API + +## Bearer Token Authentication + +ToolJet’s REST API data source supports Bearer Token as the authentication type. Bearer Token is a security token that is issued by the authentication server to the client. The client then uses the token to access the protected resources hosted by the resource server. + +### Configuring REST API Data Source with Bearer Token + +1. Go to the **Data Sources** page from the ToolJet dashboard, select **API** category on sidebar and choose the **REST API** data source. +2. In the **Base URL** field, enter the base URL. The base URL specifies the network address of the API service. For example, `http://localhost:3001/api/bearer-auth` +3. Enter the **Headers** if required. Headers are key-value pairs to include as headers with REST API requests. +4. Select **Authentication** type as *Bearer* from the dropdown. +5. Enter the **Token** in the field. The token is a security token that is issued by the authentication server to the client. The client then uses the token to access the protected resources hosted by the resource server. + +ToolJet - Data source - REST API + +6. Now you have option to select the **SSL Certificate** if required. SSL certificate is used to verify the server certificate. By default, it is set to *None*. You can provide the **CA Certificate** or **Client Certificate** from the dropdown. + 1. **CA Certificate**: Requires a CA certificate to verify the server certificate. Copy the content of `server.crt` file and paste it in the **CA Cert** field. `server.crt` file is the certificate file that is used to verify the server certificate. + + ToolJet - Data source - REST API + + 2. **Client Certificate**: Requires a client certificate to authenticate with the server. **client.key**, **client.crt**, and **server.crt** files are the certificate files that are used to authenticate with the server. Copy the content of **client.key** file and paste it in the **Client Key** field. Copy the content of **client.crt** file and paste it in the **Client Cert** field. Copy the content of **server.crt** file and paste it in the **CA Cert** field. + + ToolJet - Data source - REST API + +7. Once you have configured the REST API data source, click on the **Save** button. + +### Authenticating REST API + +Create a query to make a `GET` request to the URL, and it will return a success message if the token is valid. + +
+ +ToolJet - Data source - REST API + +
+ +## OAuth 2.0 Authentication + +ToolJet’s REST API data source supports OAuth 2.0 as the authentication type. Supported OAuth 2.0 grant types are Authorization Code and Client Credentials. + +- **Authorization Code Grant Type**: This grant type is used by confidential and public clients to exchange an authorization code for an access token. +- **Client Credentials Grant Type**: This grant type is used by clients to obtain an access token outside of the context of a user. + +### Setting up Google Cloud Platform + +:::info +Before setting up the REST API data source in ToolJet, we need to configure the **Google Cloud Platform** to gather the API keys required for the authorization access. +::: + +Google Cloud Platform provides access to more than 350 APIs and Services that can allow us to access data from our Google account and its services. Let's create an OAuth application that can be given permission to use our Google profile data such as Name and Profile picture. + +1. Sign in to your [Google Cloud](https://cloud.google.com/) account, and from the console create a New Project. +2. Navigate to the **APIs and Services**, and then open the **OAuth consent screen** section from the left sidebar. +3. Enter the Application details and select the appropriate scopes for your application. We will select the profile and the email scopes. +4. Once you have created the OAuth consent screen, Create new credentials for the **OAuth client ID** from the **Credentials** section in the left sidebar. +5. Select the application type, enter the application name, and then add the following URIs under Authorized Redirect URIs(Callback URL): + 1. `https://app.tooljet.ai/oauth2/authorize` (if you’re using ToolJet cloud) + 2. `http://localhost:8082/oauth2/authorize` (if you’re using ToolJet locally) + +ToolJet - How To - REST API CallBack URL in OAuth 2.0 + +6. Now save and then you’ll get the **Client ID and Client secret** for your application. + +ToolJet - How To - REST API authentication using OAuth 2.0 + +### Configuring ToolJet Application with Google's OAuth 2.0 API + +### Grant Type: Authorization Code + +Let's follow the steps to authorize ToolJet to access your Google profile data: + +1. Go to the **Data Sources** page from the ToolJet dashboard, select API category on sidebar and choose the **REST API** data source. +2. In the **Base URL** field, enter the base URL `https://www.googleapis.com/oauth2/v1/userinfo`; the base URL specifies the network address of the API service. +3. Select **Authentication** type as *OAuth 2.0* +4. Keep the default values for **Grant Type**, **Add Access Token To**, and **Header Prefix** i.e. *Authorization Code*, *Request Header*, and *Bearer* respectively. +5. Enter **Access Token URL**: `https://oauth2.googleapis.com/token`; this token allows users to verify their identity, and in return, receive a unique access token. +6. Enter the **Client ID** and **Client Secret** that we generated from the [Google Console](http://console.developers.google.com/). +7. In the **Scope** field, enter `https://www.googleapis.com/auth/userinfo.profile`; Scope is a mechanism in OAuth 2.0 to limit an application's access to a user's account. Check the scopes available for [Google OAuth2 API here](https://developers.google.com/identity/protocols/oauth2/scopes#oauth2). +8. Enter **Authorization URL:** `https://accounts.google.com/o/oauth2/v2/auth`; the Authorization URL requests authorization from the user and redirects to retrieve an authorization code from identity server. +9. Create three **Custom Authentication Parameters:** + 1. **response_type**: code ( `code` refers to the Authorization Code) + 2. **client_id**: Client ID + 3. **redirect_url**: `http://localhost:8082/oauth2/authorize` if using ToolJet locally or enter this `https://app.tooljet.ai/oauth2/authorize` if using ToolJet Cloud. +10. Keep the default selection for **Client Authentication** and **Save** the data source. + +ToolJet - How To - REST API authentication using OAuth 2.0 + +### Grant Type: Client Credentials + +Let's follow the steps to authorize ToolJet to access your Google profile data: + +1. Go to the **Data Sources** page from the ToolJet dashboard, select API category on sidebar and choose the **REST API** data source. +2. In the **Base URL** field, enter the base URL `https://www.googleapis.com/oauth2/v1/userinfo`; the base URL specifies the network address of the API service. +3. Select **Authentication** type as *OAuth 2.0* +4. Select the **Grant Type** as *Client credentials*. +5. Enter **Access Token URL**: `https://oauth2.googleapis.com/token`; this token allows users to verify their identity, and in return, receive a unique access token. +6. Enter the **Client ID** and **Client Secret** that we generated from the [Google Console](http://console.developers.google.com/). +7. In the **Scope** field, enter `https://www.googleapis.com/auth/userinfo.profile`; Scope is a mechanism in OAuth 2.0 to limit an application's access to a user's account. Check the scopes available for [Google OAuth2 API here](https://developers.google.com/identity/protocols/oauth2/scopes#oauth2). +8. Enter the **Audience**, used to specify the intended recipient of the access token and depends on the identity provider (IdP) you are using. + +ToolJet - How To - REST API authentication using OAuth 2.0 + +### Authenticating REST API + +Let’s create a query to make a `GET` request to the URL, it will pop a new window and ask the user to authenticate against the API. + +- Add a new query and select the REST API data source from the dropdown +- In the **Method** dropdown select `GET` and enable the `Run query on application load?` +- Run the query. +- A new window will pop for authentication and once auth is successful, you can run the query again to get the user data like Name and Profile Picture. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/restapi/configuration.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/restapi/configuration.md new file mode 100644 index 0000000000..d4a1c5073c --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/restapi/configuration.md @@ -0,0 +1,82 @@ +--- +id: configuration +title: Configuration +slug: /data-sources/restapi/ +--- + +ToolJet can establish connections with any available REST API endpoint, allowing you to create queries and interact with external data sources seamlessly. + +## Setting up a REST API Data Source + +
+ +To establish a connection with the REST API data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page through the ToolJet dashboard. + +ToolJet - Data source - REST API + +ToolJet requires the following to connect to a REST API data source: + +- **[Credentials](#credentials)** +- **[Authentication](#authentication)** +- **[Secure Sockets Layer (SSL)](#secure-sockets-layer-ssl)** + +
+ +### Credentials + +- **Base URL**: The base URL specifies the network address of the API service. +- **Headers**: Key-value pairs to include as headers with REST API requests. +- **URL Parameters**: Key-value pairs to include as URL parameters with REST API requests. +- **Body**: Key-value pairs to include as the body of the request. +- **Cookies**: Key-value pairs to include as cookies with REST API requests. These cookies will be sent with every query created using this data source instance. + +REST API - Credentials + +
+ +
+ +### Authentication + +:::info +For a detailed explanation of the authentication types supported by REST API data sources, refer to the **[Authentication](/docs/data-sources/restapi/authentication)** section. +::: + +ToolJet supports the following authentication types for REST API data sources: + +- **None**: No authentication required. +- **Basic**: Requires Username and Password. +- **Bearer**: Requires a token, typically a JSON Web Token (JWT), to grant access. +- **OAuth 2.0**: Supports both Authorization Code and Client Credentials grant types. Required parameters vary based on the selected grant type and service provider. + - Access token URL + - Access token URL custom headers + - Client ID + - Client secret + - Scopes + - Custom query parameters + - Authorization URL + - Custom authentication parameters + - Client authentication method + +REST API - Authentication + +
+ +
+ +### Secure Sockets Layer (SSL) + +- **SSL Certificate**: SSL certificate to use with REST API requests. Supported Types: + - **None**: No SSL certificate verification. + - **CA Certificate**: Requires a CA certificate to verify the server certificate. + - **Client Certificate**: Requires a client certificate, client key, and CA certificate to authenticate with the server. + +REST API - SSL Certificate + +
+ +:::info +To interact with SOAP APIs, refer to the [SOAP API Documentation](/docs/data-sources/soap-api). +::: + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/restapi/metadata-and-cookies.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/restapi/metadata-and-cookies.md new file mode 100644 index 0000000000..55f107f579 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/restapi/metadata-and-cookies.md @@ -0,0 +1,105 @@ +--- +id: metadata-and-cookies +title: Metadata and Cookies +--- + +## Metadata + +Metadata is additional information about the data returned by the REST API. This information includes the request URL, method, headers, and response status code, headers, and body. The metadata can be accessed within queries and components using the `{{queries..metadata}}` syntax. + +:::info +While accessing the properties of the metadata object, which contains a hyphen, you can use the bracket notation. For example, to access the `user-agent` property, you can use `{{queries.restapi1.metadata.request.headers["user-agent"]}}` or `{{queries.restapi1.metadata.request.headers."user-agent"}}`. +::: + +
+**Example Metadata** + +```json +{ + "request": { + "url": "https://dummyjson.com/users", + "method": "GET", + "headers": { + "user-agent": "got (https://github.com/sindresorhus/got)", + "tj-x-forwarded-for": "103.171.99.41", + "accept-encoding": "gzip, deflate, br" + }, + "params": {} + }, + "response": { + "statusCode": 200, + "headers": { + "server": "[REDACTED]", + "report-to": "{"group":"heroku-nel","max_age":3600,"endpoints":[{"url":"https://nel.heroku.com/reports?ts=1726207652&sid=e11707d5-02a7-43ef-b45e-2cf4d2036f7d&s=1ICCahr5yl4s1cOLwZ5JI7Le2a5Hp57L8DugEP6oEZQ%3D"}]}", + "reporting-endpoints": "heroku-nel=https://nel.heroku.com/reports?ts=1726207652&sid=e11707d5-02a7-43ef-b45e-2cf4d2036f7d&s=1ICCahr5yl4s1cOLwZ5JI7Le2a5Hp57L8DugEP6oEZQ%3D", + "nel": "{"report_to":"heroku-nel","max_age":3600,"success_fraction":0.005,"failure_fraction":0.05,"response_headers":["Via"]}", + "connection": "close", + "access-control-allow-origin": "*", + "x-dns-prefetch-control": "off", + "x-frame-options": "SAMEORIGIN", + "strict-transport-security": "max-age=15552000; includeSubDomains", + "x-download-options": "noopen", + "x-content-type-options": "nosniff", + "x-xss-protection": "1; mode=block", + "x-ratelimit-limit": "100", + "x-ratelimit-remaining": "99", + "date": "Fri, 13 Sep 2024 06:07:32 GMT", + "x-ratelimit-reset": "1726207656", + "content-type": "application/json; charset=utf-8", + "etag": "W/"7d39-+rQ7kyHBCLIn9tjTeKVf4oegWkQ"", + "vary": "Accept-Encoding", + "content-encoding": "gzip", + "transfer-encoding": "chunked", + "via": "1.1 vegur" + } + } +} +``` +
+ +### Valid and Invalid Headers + +#### Valid Headers + +| Header Key | Header Value | Notes | +|------------|--------------|-------| +| Content-Type | 'application/json' | String values are valid and commonly used for specifying content type. | +| X-Number | 42 | Numeric values are valid (e.g., 42, 3.14, -7). | +| X-Boolean | true | Boolean values are valid (true or false). | +| X-Trim-Me |
' needs trimming '
| Valid after trimming. | +| X-Empty-String | '' | Empty string values are valid. | + +#### Invalid Headers + +| Header Key | Header Value | Reason Invalid | +|------------------------|-----------------------------|-----------------------------------------------| +| X-Null | null | null is not a valid header value. | +| X-Undefined | undefined | undefined is not a valid header value. | +| X-NaN | NaN | Special numeric values like NaN are invalid. | +| X-Infinity | Infinity | Infinity is not a valid primitive. | +| X-NegativeInfinity | -Infinity | -Infinity is also invalid. | +| X-Object | `{ key: 'value' } ` | Objects are not allowed as header values. | +| X-Array | [1, 2, 3] | Arrays are not valid as header values. | +| X-Function | ( ) => console.log('test') | Functions cannot be serialized into headers. | +| X-Symbol | Symbol('sym') | Symbols are non-serializable and invalid. | +| *(empty key)* | 'Empty key' | Header keys must not be empty. | + +## Cookies + +In addition to the data source level cookies, you can add query-specific cookies in the Query builder. These cookies will be sent only with the specific query created using this data source instance. + +To add cookies: + +1. In the Query builder, navigate to the **Setup** tab. +2. Find the **Cookies** section. +3. Add your cookies as key-value pairs. + +You can use both static values and dynamic values for cookie values. + +
+ToolJet - Query Builder - REST API Cookies +
+ +:::info +Query-specific cookies will override data source level cookies with the same name for that particular query. +::: \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/restapi/querying-rest-api.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/restapi/querying-rest-api.md new file mode 100644 index 0000000000..73eb97eda5 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/restapi/querying-rest-api.md @@ -0,0 +1,175 @@ +--- +id: querying-rest-api +title: Querying REST API +--- + +## Creating Queries + +Once you have connected to the REST API data source, you can easily write queries and interact with the REST API in the ToolJet application. Follow these steps to get started: + +1. Click on the **+ Add** button in the query manager at the bottom panel of the editor. +2. Select **REST API** from the Data Source section. +3. Enter the required query parameters. +4. Click **Preview** to view the data returned from the query or click **Run** to execute the query. + +:::tip +You can also transform the query results using the **[Transformations](/docs/beta/app-builder/custom-code/transform-data)** feature. +::: + +ToolJet supports the following REST HTTP methods: + +- **GET** +- **POST** +- **PUT** +- **PATCH** +- **DELETE** + +ToolJet - Data source - REST API + +:::info +To receive the string `"undefined"` instead of an actual `undefined` value, it must be explicitly handled in the query manager.
+Example: `"address": "{{components.table1.selectedRow?.address ?? 'undefined'}}"` +::: + +
+ +### Additional header + +Whenever a request is made to the REST API, a **tj-x-forwarded-for** header is added to the request, the value of the header will be the IP address of the user who is logged in to the ToolJet application. This header can be used to identify the user who is making the request to the REST API. + +ToolJet - Data source - REST API + +
+ +## Request/Content Types + +REST API sends a **JSON** formatted body by default. If you want to send a different type of body, you can enter the appropriate headers in the **Headers** section. + +For example, to send a **multipart/form-data** body, you can add the following header: + +```javascript + Content-Type: multipart/form-data; +``` + +ToolJet - Data source - REST API + +ToolJet - Data source - REST API +

+ +:::info Handling OAuth Token via REST API +To obtain an OAuth token via REST API, add the following custom header:
+`Content-Type: application/x-www-form-urlencoded` +::: + +## Response Types and Handling + +REST APIs can return data in a variety of formats, including **JSON** and **Base64**. JSON is a common format used for data exchange in REST APIs, while Base64 is often used for encoding binary data, such as images or video, within a JSON response. +When the response **content-type** is **image**, the response will be a **base64** string. + +
+**Example JSON response** + +```json +[ + { + "id": 1, + "title": "Fjallraven - Foldsack No. 1 Backpack, Fits 15 Laptops", + "price": 109.95, + "description": "Your perfect pack for everyday use and walks in the forest. Stash your laptop (up to 15 inches) in the padded sleeve, your everyday", + "category": "men's clothing", + "image": "https://fakestoreapi.com/img/81fPKd-2AYL._AC_SL1500_.jpg", + "rating": { + "rate": 3.9, + "count": 120 + } + }, + { + "id": 2, + "title": "Mens Casual Premium Slim Fit T-Shirts ", + "price": 22.3, + "description": "Slim-fitting style, contrast raglan long sleeve, three-button henley placket, light weight & soft fabric for breathable and comfortable wearing. And Solid stitched shirts with round neck made for durability and a great fit for casual fashion wear and diehard baseball fans. The Henley style round neckline includes a three-button placket.", + "category": "men's clothing", + "image": "https://fakestoreapi.com/img/71-3HjGNDUL._AC_SY879._SX._UX._SY._UY_.jpg", + "rating": { + "rate": 4.1, + "count": 259 + } + }, + { + "id": 3, + "title": "Mens Cotton Jacket", + "price": 55.99, + "description": "great outerwear jackets for Spring/Autumn/Winter, suitable for many occasions, such as working, hiking, camping, mountain/rock climbing, cycling, traveling or other outdoors. Good gift choice for you or your family member. A warm hearted love to Father, husband or son in this thanksgiving or Christmas Day.", + "category": "men's clothing", + "image": "https://fakestoreapi.com/img/71li-ujtlUL._AC_UX679_.jpg", + "rating": { + "rate": 4.7, + "count": 500 + } + }, + { + "id": 4, + "title": "Mens Casual Slim Fit", + "price": 15.99, + "description": "The color could be slightly different between on the screen and in practice. / Please note that body builds vary by person, therefore, detailed size information should be reviewed below on the product description.", + "category": "men's clothing", + "image": "https://fakestoreapi.com/img/71YXzeOuslL._AC_UY879_.jpg", + "rating": { + "rate": 2.1, + "count": 430 + } + } +] +``` + +The JSON response can be easily loaded on the components like **table** and **listview** using `{{queries..data}}` + +
+ +You can also use JS methods like **map** to load data on components like **dropdown** using **`{{queries.restapi1.data.map(i => i.title)}}`** + +ToolJet - Data source - REST API + +
+**Example base64 response** +```base64 +iVBORw0KGgoAAAANSUhEUgAAAOEAAADhCAMAAAAJbSJIAAAA/FBMVEVAYt79/f1AYt/9/f79/ftAY9s/Y93v/P89ZNv8/v38/f/9/vj9/vr+/Pz//P49ZNw8ZddUb86QpMlCYOX1//9AYeI6XdaXp+C1x+nL2fj+/vU2WMZVb8iPnsU3Xt00WNY7ZtU0WMuJncs8W8JDY801W986V9BTacRleMF+kNClt+CsvuFtiNYvVMRcedaZq9Lb5/eCl9K8zOJJWcqlr9xdb8C6w+w7XsCmvt3S5fs5ac1whs7l8v/6//B9j8wvVLrO2+o+Y7t6kMODotxPbL0+WOLf3/aesdVmfbvL5PentOmDl99RbtdMXcGOnNqTqdp+luIyVrLr7Pq/2/3mMzS8AAAKxUlEQVR4nO2cC1vbthrHLVmWJUuW3dlywWYkIRAorG1K6SgjgV5g3a3jbOf7f5fzygngcCvbeobN8/7a8rQl7eO/Jf3fiyV7HoIgCIIgCIIgCIIgCIIgCIIgCIIgCIIgCIIgCIIgCIIgCIIgCIIgCIIgCIL8H+CBI0kSzj3OA5Gm9V8EQojAsw99dV8DUMg5tzYDLLWgktbAb4CHvrqvwWwM6zETMJJpmgqRwg9qLeXiMUisFcK4cZifqxsbvXMKmtlHpNDrjarNrWdPt3d2luZ8JzzL004rdGvNERSD5y9eLo9DMkc7yDfrAYxr8MAX+XdxvunWmfPLwf6r3VASIiVjMYkJ/IzhK/mmECLrrEKPJmm/vy5sb3i4O5FRzMg1uq2QOmMRxej13liWpWKxeWwKnXfa3ovtEPQxwvwoemwKPS6qN9+HqixjYyLHo1IIJpMV+29DCbOTMOVm6XV9XVTo4h73wD8Tz1ZnIZGRE8ZqHo/CIEhFElTfHeRSkxtm5iNQmP4gNl7v5ErFxpfSRb/HpVCAh1aHk7zUxhg91ezRKYRM5vV2Pi1Bn/HZzQbTSYVgnlDtwQB6xQ9jaUzMyrLU0Q1R/gKfkA+FCLKgGwrTxEKVIIQdHYXEj30ia//0b1EXRQxuA/ku5WC8XagtKOTZnqvcs9FZLu+cmBcKGajfTD3riYe++ntBaZCmCaXPvydTJV3h8AWdkrBS58cCbk43Jilk2Wk/Fe8PdBzrmYbaQ28zGqYNm8p3VRcm6JwAbGb9/UGuiGlG+dvWIVMmLuV2QR/6uu8PLKji/YGMIqXmqmQjVviMRX5z3rLSN2V+tNoJhbCQXDaa2c1JTPxIsplCJiM11eO1N09enB3kGuLjZWyUxDCp2eT9Q1/7/eFBulFBGFyYiFJOXg0Lm9nB8GUOsaG5Jk2sS7JbPfR13w+oJayl6XBZl5crEEYpVuGbDYgFaSq86izXrKnfmHIqj2wnJil4jLVeMlxmoEk2FJr8Q5GlPF3vwwwevpOqqdCt18l+1hmFXnq8k8NKK7XvX0QIOd7niQD1NIOJuiZVvKCQkbdVK8fQXdP8ocOcwKNi+BHK3CiS9eidx4OdHuUW5mia9pPiDdELCmUsT1rZCqYZFQIGhQ6qwWhQOYaD0fGHUF4NfYy8LJLUlRpQcFBvhUC8uPxubNTSIG3lGEL9zr3R52c7yw0gGlxLXpjeGdnz50pUHBK1cAtYfrgqaCsVJnTwfu9PKbUq6868Zlorra8KhJg+Oc4srzVQWr2UC7NU5u+q7KG13Ai1XvUxJE4TY1o5Yqa0jK4k2j6sw/zVwNLZIKZ/jBe9VOZbvcy2MeemdLgkQRJoAkCYjHy//u3VdegbGZ4EM4V8/YMslbn4BNyOn0c2pS1TSF0d7w13ZclchyKGWVp3CSHXNjd0KyKj1MFm4W6KV2z9GU/PFcInYU4/O7X9llkpzdJ1TqvvCVGs7l+fd0ChkPevVUlQIhpd5pO1/UFRHB+F7hOzWQpVhVTkx+e2bSMIK1CIZHhG3Hh9oQs6V65Vnufjt5/ejqPmFGYxfOOoeGg9V6EeDaitPkifKPWlPu8MpWB16lKD7ZaNIfYlDP7y/kMLugaYvqDFYVi7p38/hRqSz3JaSskgWrJZtsPg7qh4ctLK3gwvPo/rBprv31a5L+CEgeeC386fOs3+lR9ruTd4aDE3we1gj6j6KZl/d5u3lgdOEysF4vyYXaxbxiT8EVJy58uzHLcd0CQBl6FbOcyx6F7jdy5o4Y++0XCH1DTcKtq2S4jzhHM+3M2Z+SsCrw+sli6EbFde0rJIkXC3p+KnUM4LpL8JK6UxSv+8T2nbHlUIDgIHu1DD/kOFviFy8p5n7VOYQAKyImNtIA/9BwqVgVz1MF21om21L7iMV237cWx8yD/dZp/4fMvPPYHlC2FGxiQ/G0F2K9L22GiN6NtsM3T1EqsLQlan3sb4vpQ37bC4Thzp6dQ3U/1LL6n/y5Yp9FKe/RpeI/eZi3j3mZ8liSDzZvnusdey+VlDsyD1fjtZucpTQspS3U8hjDozcnmYijbuCKYZTUUg6Oo5s72+We/bHOra+1gP064DrA72My5a2X3i1BOCpw04FyJNh9/m7IuVlMtr/MiHSH+wX1ietHEMvZTaQCT1luxgvjHbbbrg2fDbO/eSOHyXqYMdKbI8zGgAJVgbx7DuRHjzveezn/Uv6w3W8hJKjdsdNYJcFKoLJuXS/motrp0CbwFm7/CbHIr+Ut+m0Jdag9FMIRkNvFa2R2/k/EIFzfhw7U5HZYoZCKL5WWVtG+PEzVyMBKzEzA5qR731aTbECS0nTwb9fvqQ1/w3qX2Dg6MSdrtCn+jdz6c27bctF70der7/3nPOKpI7HRWybZiiG+7sCE14J2wGErjMZQCXtnG3o0ods6erwcWxhNbjLtSd5uGurTEbkrsdNVJOYWcmaP1kBpIZqGHT/nlD8G5HjRTrlkKv3uW8QbnbfzDjbkftlMJ6TqaJ5dWvK+40z7wTcbejyg4pnFkF5KjH2/n4xIOJOpPI3Yav2lFv2kwKCklHFFIL6Tf3RNZbIkaNV/ru/CC/dFQKjqpcJ2Zhz0UcO4VFJxR6roSCL71fpCGxnGyKdO6oNTNHlQYyGLOgUMvOKAygRqS297vURkdK/7iZWueoc4XgqN5wTfpQSiwqhAKyI7PUc3u4OX8RljFzYRwmKhWXjprWjvrJGWrzkFrs2lW/d0Qh5Fw8PV6GtcZkvTt0stlwVFE76lYOCnVjezcojMizrii0VKy/IjKXkfadzrJ2VDHfJ8WdyidhqV1PNbpUaAzZ6kjhlNr++v6YESn9+rESY/5kxSbNrgR9Ehq28MjJ9aDCzW7s0ONpJtaPmp013+STTds8S2BBoSYLh0V9ow8Gqw932X8BnlpbLTd3d0FlpMZPmi1eN4ZaNhVGpJRnvVY+074CrZ9ArYSzfTMzCayMVf6f4m6FchoOW7ev5Gao109eLZS6vlH505G4TWH9FWLF3qDfyh7pFdzB8/76LjNmdt4Hph9jJv9Y9a86zeUY+u5UkByvix9sFyRCOLB/TAxziadSzEDIV5OjChK3xmcuFYLRGshvGAu3NsT6bJa23VB5kJ1IwzSLIohxUNDny5sDzwbNFlpzDCEswt3IfyoyLjoSLfjqM1lHu9ht22Ph09enGU0WbLKpMNJlSSY/VVmW8NNOKPSC3ieoAN0zFqV1tDQsAtci9LIb1mGdD+RKHmxuQCLUmU5pMFrSsdsuJPNwaWsEhYVLvPk1p6lzmpgwOdmrYAFCRSK6InHwzm3Dk2R8tjIKkoSvur6iaE7TVVBI3HEnyOv+3DsZ9hPIzGlmk9a7jOdK/OzzRJPw3aeV54V75QWft4abSTVkbao+7zNZ2no+8gJeb/PuTKc0efLfnVcrw4F7Z8lsb/O1z8AYlpHMD9ZOKtoN/2zC+/1qULjn2zaZr6trGmAdynz3qCq4O5Lxb1/hP8Zt/QLTSO56O9dKuHsyPLX1C8v+zWv7OoBpBvVLulwmessA/Xb4mvJT1xZPu6eQu/d0uQNB1rvlAL17jlGcZn337jk+exLTrZlKvfmL5O78DKUBP//44+TRCkMQBEEQBEEQBEEQBEEQBEEQBEEQBEEQBEEQBEEQBEEQBEEQBEEQBEEQBEGQr8n/ABGyzAUL7/lcAAAAAElFTkSuQmCC +``` +
+ +Read the guide on **[loading base64 data](/docs/how-to/loading-image-pdf-from-db)**. + +ToolJet - Data source - REST API + +## Retry on Network Errors + +ToolJet provides an option to automatically retry REST API requests in case of certain network errors or specific HTTP status codes. By default, this feature is enabled and will retry the request up to 3 times in case of failure. This feature can be toggled on or off at both the data source level and the individual query level. When enabled, retries will occur for the following scenarios: + +1. Specific HTTP status codes: 408, 413, 429, 500, 502, 503, 504, 521, 522, 524. +2. Network errors: + - **ETIMEDOUT**: One of the timeout limits was reached. + - **ECONNRESET**: Connection was forcibly closed by a peer. + - **EADDRINUSE**: Could not bind to any free port. + - **ECONNREFUSED**: Connection was refused by the server. + - **EPIPE**: The remote side of the stream being written has been closed. + - **ENOTFOUND**: Couldn't resolve the hostname to an IP address. + - **ENETUNREACH**: No internet connection. + - **EAI_AGAIN**: DNS lookup timed out. + +You can configure this feature at two levels: + +### Data Source Level + +In the REST API data source configuration, you'll find a toggle for **Retry on network errors** This sets the default behavior for all queries using this data source. + +ToolJet - Data source - REST API + +### Query Level + +In the query builder for each REST API query, you'll find a similar toggle for for **Retry on network errors** under the **Settings** tab. This sets the behavior for that specific query. + +ToolJet - Data source - REST API + +:::info +If the data source-level configuration is enabled but a specific query has it disabled, the query-level setting takes precedence. +::: diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/rethinkdb.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/rethinkdb.md new file mode 100644 index 0000000000..df26fe970e --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/rethinkdb.md @@ -0,0 +1,228 @@ +--- +id: rethinkdb +title: RethinkDB +--- +# RethinkDB + +ToolJet can connect to RethinkDB databases to read and write data. For more info visit this [Rethink Docs](https://rethinkdb.com/api/javascript). + +
+ +## Connection + +To establish a connection with the RethinkDB data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page through the ToolJet dashboard. + +ToolJet requires the following to connect to a RethinkDB data source: + +- **Database** +- **Host** +- **Username** +- **Password** +- **Port** + + + +
+ +
+ +## Querying RethinkDB + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the RethinkDB data source added in the previous step. +3. Select the desired operation. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + + + +
+ +
+ +## Supported Queries + +- **[Create database](#create-database)** +- **[Create table](#create-table)** +- **[Delete database](#delete-database)** +- **[Delete table](#delete-table)** +- **[List all database](#list-all-database)** +- **[List all table](#list-all-table)** +- **[List all documents](#list-all-documents)** +- **[Insert document](#insert-document)** +- **[Retrieve document by key](#retrieve-document-by-key)** +- **[Update document using ID](#update-document-using-id)** +- **[Update all documents](#update-all-documents)** +- **[Delete document using ID](#delete-document-using-id)** +- **[Delete all documents](#delete-all-documents)** + +:::info +NOTE: The name field in all operations is the database name if not given will take the default database used for the connection. +::: + +### Create Database + +Creates a new database in RethinkDB. + +#### Required Parameter +- **Database Name** + + + + +### Create Table + +Creates a new table in a specified database. + +#### Required Parameter +- **Database Name** +- **Tablename** + + + + +### Delete Database + +Deletes an existing database in RethinkDB. + +#### Required Parameter +- **Database Name** + + + + +### Delete Table + +Deletes a table from a specified database. + +#### Required Parameter +- **Database Name** +- **Tablename** + + + + +### List All Database + +Lists all available databases. + + + + +### List All Table + +Lists all tables in a specified database. + +#### Required Parameter +- **Database Name** + + + + +### List All Documents + +Retrieves all documents from a specified table. + +#### Required Parameter +- **Database Name** +- **Tablename** + + + + +### Insert Document + +Inserts a new document into a specified table. + +#### Required Parameter +- **Database Name** +- **Tablename** +- **Data** + + + +#### Example + +```yaml +{ +Β  "name": "John Doe", +Β  "age": 30 +} +``` + + +### Retrieve Document by Key + +Fetches a document from a specified table by its key. + +#### Required Parameter +- **Database Name** +- **Tablename** +- **Primary key** + + + + +### Update Document Using ID + +Updates a specific document in a table using its ID. + +#### Required Parameter +- **Database Name** +- **Tablename** +- **Primary key** +- **Data** + + + +#### Example + +```yaml +{ +Β  "age": 31 +} +``` + + +### Update All Documents + +Updates all documents in a specified table. + +#### Required Parameter +- **Database Name** +- **Tablename** +- **Data** + + + +#### Example + +```yaml +{ +Β  "verified": true +} +``` + + +### Delete Document Using ID + +Deletes a specific document in a table using its ID. + +#### Required Parameter +- **Database Name** +- **Tablename** +- **Primary key** + + + + +### Delete All Documents + +Deletes all documents from a specified table. + +#### Required Parameter +- **Database Name** +- **Tablename** + + + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/run-py.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/run-py.md new file mode 100644 index 0000000000..56373e180c --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/run-py.md @@ -0,0 +1,208 @@ +--- +id: run-py +title: Run Python Code +--- + +In ToolJet, custom **Run Python Code** can be used to interact with components and queries, making it possible to customize actions and data handling. + +Run Python code + +
+ +## Using Python Code to Trigger Component Specific Actions + +1. Drag a **Text** component onto the canvas. We will set the text on the Text component using the Python query. +2. Create a query and select **Run Python code** from the available data sources +3. Paste the below code in the code editor and save the query: + +```python +class Person: + def __init__(self, name, age): + self.name = name + self.age = age + + def myfunc(self): + return "Hello my name is " + self.name + +p1 = Person(tj_globals.currentUser.firstName, 36) + +components.text1.setText(p1.myfunc()) +``` + +4. The above code has a function `myfunc` which returns a string and we are using a **[Component Specific Action](/docs/app-builder/events/use-case/csa)** to set the Text Component's value from the Python query. + +:::tip + +- As of now, Run Python code only supports the [Python standard library](https://docs.python.org/3/library/). +- Check **[RunPy Limitations](/docs/contributing-guide/troubleshooting/runpy-limitations)** to go through the limitations with using Python code + ::: + +
+ +
+ +## Trigger Queries Using Run Python Code + +To trigger queries in Python, you can use the below functions: + +```py +actions.runQuery('getSalesData') +#replace getSalesData with your query name +``` + +Or + +```py +queries.getSalesData.run() +#replace getSalesData with your query name +``` + +
+ +
+ +## Get Query Data + +To immediately access the data returned by a query in **Run Python code**, you can use the below functions: + +### Trigger a Query and Retrieve its Data + +```py +await queries.getSalesData.run() +#replace getSalesData with your query name + +value = queries.getSalesData.getData() +#replace getSalesData with your query name + +value +``` + +### Trigger a Query and Retrieve its Raw Data + +```py +await queries.getCustomerData.run() +#replace getCustomerData with your query name + +value = queries.getCustomerData.getRawData() +#replace getCustomerData with your query name + +value +``` + +### Trigger a Query and Retrieve its Loading State + +```py +await queries.getTodos.run() +#replace getTodos with your query name + +value = queries.getTodos.getLoadingState() +#replace getTodos with your query name + +value +``` + +
+ +
+ +## Get Variables + +To set and access variables or page variables in **Run Python code**, you can use the below functions: + +### Set a Variable + +```py +actions.setVariable('color','blue') +#replace color with your desired variable name +``` + +### Immediately Retrieve a Variable After Setting it + +```py +actions.setVariable('mode','dark') +#replace mode with your desired variable name + +actions.getVariable('mode') +#replace mode with your desired variable name +``` + +### Set a Page-Specific Variable + +```py +actions.setPageVariable('version', 1) +#replace version with your desired variable name +``` + +### Immediately Retrieve a Page-Specific Variable After Setting it + +```py +actions.setPageVariable('number',1) +#replace number with your desired variable name + +actions.getPageVariable('number') +#replace number with your desired variable name +``` + +
+ +
+ +## Using Transformations With Python + +**Run Python code** can be used to transform the data that is fetched in the queries. To test transformations using Python, create a new **REST API** query, leave the method as _GET_ and enter the below url under the **URL** property. + +```yaml +https://dummyjson.com/products +``` + +Click on the **Run** button and check the preview of the returned data, below is the data structure of the response: + +```js +products_data = { + "products": [ + {"title": "iPhone 9", ...}, + {"title": "iPhone X", ...}, + # Additional products... + ] +} +``` + +### Filter the Titles From the Response + +To extract a list of product titles from the given data structure, we iterate through the _products_ list and collect each product's _title_ using the below code. Enable **Transformations** in the Query Editor and use the below code: + +```python +return [product["title"] for product in data["products"]] +``` + +### Filter Products by Category + +To filter products by a specific category, such as _smartphones_, and extract their titles. Enable **Transformations** in the Query Editor and use the below code: + +```python +return [product["title"] for product in data["products"] if product["category"] == "smartphones"] +``` + +### Calculate Average Price of a Category + +To calculate the average price of products within the _laptops_ category. Enable **Transformations** in the Query Editor and use the below code: + +```python +return sum(product["price"] for product in data["products"] if product["category"] == "laptops") / len([product for product in data["products"] if product["category"] == "laptops"]) if len([product for product in data["products"] if product["category"] == "laptops"]) > 0 else 0 +``` + +
+ +
+ +## Refer Python Query Data in Components + +Just like other dynamic values, you can refer the data returned by **Run Python code** queries using double curly braces`{{}}`. + +For instance, if you have a **Run Python code** query named _updatedProductInfo_, you can pass `{{queries.updatedProductInfo.data}}` under the **Data** property of a Table component to populate it with the data returned by the _updatedProductInfo_ query. + +:::info +Issues with writing custom Python code? Ask in our [Slack community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA). +::: + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/s3.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/s3.md new file mode 100644 index 0000000000..3e4891e928 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/s3.md @@ -0,0 +1,181 @@ +--- +id: s3 +title: Amazon S3 +--- + +ToolJet can connect to **Amazon S3** buckets and perform various operations on them. + +
+ +## Connection + +To establish a connection with the **Amazon S3** data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview/)** page from the ToolJet dashboard. + +ToolJet supports connecting to AWS S3 using **IAM Access Keys**, **AWS Instance Credentials** or **AWS ARN Role**. + +If you are using **IAM Access Keys**, you will need to provide the following details: + +- **Region** +- **Access key** +- **Secret key** + +**Note:** It is recommended to create a new IAM user for the database so that you can control the access levels of ToolJet. + +aws s3 modal + +To connect to AWS S3 using **AWS Instance Credentials**, select the **Use AWS Instance Credentials**. This will use the IAM role attached to the EC2 instance where ToolJet is running. + +To access the metadata service of an ECS container and the EC2 instance, we use the WebIdentityToken parameter which is obtained from a successful login with an identity provider. + +aws s3 modal + +If you are using **AWS ARN Role**, you will need to provide the following details: + +- **Region** +- **Role ARN** + +aws s3 modal + +:::tip +You can now connect to **[different S3 Hosts using custom endpoints](/docs/how-to/s3-custom-endpoints)**. +::: + +
+ +
+ +## Querying AWS S3 + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **Amazon AWS S3** datasource added in previous step. +3. Select the desired operation from the dropdown and enter the required parameters. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +aws s3 query + +:::info +Query results can be transformed using transformations. Read our [transformations documentation](/docs/beta/app-builder/custom-code/transform-data). +::: + +
+ +
+ +## Supported Operations + +You can create query for AWS S3 data source to perform several actions such as: + +- **[Create a new bucket](#create-a-new-bucket)** +- **[Read object](#read-object)** +- **[Upload object](#upload-object)** +- **[Remove object](#remove-object)** +- **[List buckets](#list-buckets)** +- **[List objects in a bucket](#list-objects-in-a-bucket)** +- **[Signed URL for download](#signed-url-for-download)** +- **[Signed URL for upload](#signed-url-for-upload)** + +### Create a New Bucket + +You can create a new bucket in your S3 by using this operation. + +#### Required Parameters + +- **Bucket Name** + +Create a new bucket - S3 operation + +### Read Object + +You can read an object in a bucket by using this operation. + +#### Required Parameters + +- **Bucket** +- **Key** + +aws s3 read object + +### Upload Object + +You can use this operation to upload objects(files) to your S3 bucket. + +#### Required Parameters + +- **Bucket** +- **Key** +- **Content Type** +- **Upload data** + +aws s3 upload + +### Remove Object + +You can use this operation to remove an object from your S3 bucket. + +#### Required Parameters + +- **Bucket** +- **Key** + +Create a new bucket - S3 operation + +### List Buckets + +This operation will list all the buckets in your S3. This does not require any parameter. + +aws s3 bucket + +### List Objects in a Bucket + +This operation will fetch the list of all the files in your bucket. It requires the following parameters: + +#### Required Parameters + +- **Bucket** + +#### Optional Parameters + +- **Prefix** +- **Max keys** +- **Offset** +- **Next Continuation Token** + +:::info +**Next Continuation Token**
+For listing a bucket for objects that begin with a specific character or a prefix, then use the **Offset** parameter. For example, if you want to list all the objects that begin with **a**, then set the **Offset** parameter to **a**. Similarly, if you want to list all the objects that begin with **ab**, then set the **Offset** parameter to **ab**.
+The **Next Continuation Token** is used to list the next set of objects in a bucket. It is returned by the API when the response is truncated. The results will contain **Next Continuation Token** if there are more keys in the bucket that satisfy the list query. To get the next set of objects, set the **Next Continuation Token** parameter and run the query again.
+The results will continue from where the last listing finished. +::: + +aws s3 list object + +### Signed URL for Download + +The object owner can optionally share objects with others by creating a presigned URL, using their own security credentials, to grant time-limited permission to download the objects. + +#### Required Parameters + +- **Bucket** +- **Key** +- **Expires in** + +aws s3 signed download + +### Signed URL for Upload + +The presigned URLs are useful if you want your user/customer to be able to upload a specific object to your bucket, but you don't require them to have AWS security credentials or permissions. + +#### Required Parameters + +- **Bucket** +- **Key** +- **Expires in** +- **Content Type** + +aws s3 signed upload + +:::info +We built an app to view and upload files to AWS S3 buckets. Check out the complete tutorial **[here](https://blog.tooljet.ai/build-an-aws-s3-broswer-with-tooljet/)**. +::: + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/sample-data-sources.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/sample-data-sources.md new file mode 100644 index 0000000000..1189754cdb --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/sample-data-sources.md @@ -0,0 +1,75 @@ +--- +id: sample-data-sources +title: Sample Data Sources +--- + +# Sample Data Source in ToolJet + +ToolJet includes a built-in PostgreSQL sample data source that allows you to familiarize yourself with its features and components before connecting your own data. This database contains example tables and data for hands-on experimentation. The sample data source is a shared PostgreSQL connection available across all workspaces and applications. This means any changes or updates made to the data will be reflected in real-time for all users, regardless of the application or workspace. If are using ToolJet Cloud, the sample data resets daily at midnight. However, if you are using a self-hosted version of ToolJet, the data will not be reset. + + +### Getting Started with Sample Data Sources + +When you create a new application, the empty state will guide you on the next steps for connecting a data source. If you don't have your own data source ready, you can immediately start exploring and building by connecting to our sample data source. + +Canvas View + +## Connecting to Sample Data Sources + +You can connect to the sample data source in three different ways, depending on your requirements: + +### 1. Connect the Sample Data Source to a Newly Created Application. + +This method allows you to add a sample data source to an existing application that is in an empty state (i.e., has no pre-existing components) + + 1. Select/Create the application you want to connect to the sample data source. + 2. Once you select/create the new application, the empty state guides you through the initial setup for connecting the sample data source. + 3. Click on the **Connect to sample data source** button. This will create a query in the query panel which will retrieve all the tables names from the sample data source. + + + +
+ Connect via Canvas +
+ + +### 2. Connect the Sample Data Source to an Existing Application. + +This method allows you to connect the sample data source to an existing application from the query panel. + + 1. Open the **Query Panel** of the application you want to connect to the **Sample Data Source**. + 2. In the **Query Panel**, click on the **+Add** button to add a new query, and select **Sample Data Source**. + 3. This will create a new empty query. You can now write your SQL query to retrieved data from the sample data source. You can checkout the sample data source [schema](#sample-data-source-schema) to understand the tables and columns available in the sample data source. + + + +
+ Connect via query manager +
+ + +### 3. Create a Sample Application Using the Sample Data Source. + +This method enables the creation of a sample application with a pre-configured connection to the sample data source. The data will be already visualized on the application's canvas upon creation. + + 1. Navigate to the Data Sources page within the dashboard's left-hand sidebar. + 2. Under the **DATA SOURCES ADDED** section in the sidebar, you will find the **Sample Data Source (postgres)**. This is a default data source and cannot be deleted. + 3. Select **Sample Data Source (postgres)**. You can click on the **Test Connection** button to test your connection to your sample database. + 4. Click **Create sample application** to generate the new application. This application automatically includes the sample data source. + 5. By default, this application will feature a table component with tabs. These tabs will visually display the data retrieved from your sample data source. + +
+ Create Sample App +
+ + ## Sample Data Source Schema + +The sample data source contains various tables with different data types. + +| Table Name | Column Names| Number of Rows | +|:-------|:---------|:---------------| +| `public.sample_data_organizations` | `index`, `organization_id`, `name`, `website`, `country`, `description`, `founded`, `industry`, `number_of_employees` | 100 | +| `public.sample_data_country_gdp` | `country`, `area_sq_km, population`, `exports`, `imports, gdp`, `gdp_per_capita`, `gdp_real_growth_rate`, `inflation_rate_consumer_prices`, `investment_gross_fixed_of_gdp`, `labor_force`, `unemployment_rate` | 263 | +| `public.sample_data_users` | `first_name`, `last_name`, `company_name`, `address`, `city`, `county`, `state`, `zip`, `phone1`, `phone2`, `email`, `web` | 499 | +| `public.sample_data_orders` | `row_id`, `order_id`, `order_date`, `ship_date`, `ship_mode`, `customer_id`, `customer_name`, `segment`, `country`, `city`, `state`, `postal_code`, `region`, `product_id`, `category`, `sub_category`, `product_name`, `sales`, `quantity`, `discount`, `profit` | 500 | +| `public.sample_data_product_cars` | `car`, `mpg`, `cylinders`, `displacement`, `horsepower`, `weight`, `acceleration`, `model`, `origin` | 406 | diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/saphana.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/saphana.md new file mode 100644 index 0000000000..149553059a --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/saphana.md @@ -0,0 +1,48 @@ +--- +id: saphana +title: SAP HANA +--- + +ToolJet can connect to SAP HANA databases to read and write data. + +
+ +## Connection + +To establish a connection with the SAP HANA datasource, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page through the ToolJet dashboard. + +ToolJet requires the following to connect to your SAP HANA database: + +- **Host** +- **Port** +- **Username** +- **Password** + +:::info +Please make sure the **Host/IP** of the database is accessible from your VPC if you have self-hosted ToolJet. If you are using ToolJet cloud, please **whitelist** our IP. +::: + +ToolJet - Data source - SAP HANA + +
+ +
+ +## Querying SAP HANA + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **SAP HANA** datasource added in previous step. +3. Add the Query. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to create and trigger the query. + +saphana query + +```sql +select * from PRODUCTS +``` + +:::tip +Query results can be transformed using transformations. Read our transformations documentation to see how: **[link](/docs/beta/app-builder/custom-code/transform-data)** +::: + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/sendgrid.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/sendgrid.md new file mode 100644 index 0000000000..cae87d87d4 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/sendgrid.md @@ -0,0 +1,70 @@ +--- +id: sendgrid +title: SendGrid +--- + +ToolJet can connect to your SendGrid account to send emails. + +
+ +## Connection + +To establish a connection with the SendGrid datasource, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page through the ToolJet dashboard. + +ToolJet requires the following to connect to your SendGrid database: +- **SendGrid API key** + +ToolJet - Data source - SendGrid + +:::info +The SendGrid API Datasource supports for interaction with the mail endpoint of the [SendGrid v3 API](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/authentication). +::: + +
+ +
+ +## Querying SendGrid + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **SendGrid** datasource added in previous step. +3. Select **Email service** from the dropdown and enter the required parameters. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to create and trigger the query. + +
+ +
+ +## Supported Operations + +### Email Service + +#### Required Parameters +- **Multiple recipients** +- **Send email to** +- **Send email from** +- **Subject** +- **Body as text** + + +#### Optional Parameter +- **Body as HTML** + +ToolJet - Query SendGrid + +:::info +**Send mail to** - accepts an array/list of emails separated by comma. +For example: +`{{["dev@tooljet.io", "admin@tooljet.io"]}}`. + +**Send mail from** - accepts a string. +For example: `admin@tooljet.io` +::: + +:::tip +**Send a single email to multiple recipients** - The `Send mail to` field can contain an array of recipients, which will send a single email with all of the recipients in the field. + +**Send multiple individual emails to multiple recipients** - set Multiple recipients field to `{{true}}` and the `Send mail to` field will be split into multiple emails and send to each recipient. +::: + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/slack.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/slack.md new file mode 100644 index 0000000000..7b4a82326f --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/slack.md @@ -0,0 +1,76 @@ +--- +id: slack +title: Slack +--- + +ToolJet can connect to your Slack workspace to send messages. + +
+ +## Connection + +To establish a connection with the **Slack** datasource, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page through the ToolJet dashboard. + +Slack datasource: ToolJet + +
+ +Slack datasource: ToolJet + +
+ +:::note +The App (which credentials are provided) needs to be installed in the workspace to use the Slack data source, and it needs to be added to the channel where you want to post the message. +::: + +
+ +
+ +## Querying Slack + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **Slack** datasource added in previous step. +3. Select the desired operation. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to create and trigger the query. + +Slack datasource: ToolJet + +
+ +
+ +## Supported Operations + +1. **[List Members](#list-members)** +2. **[Send Message](#send-message)** +3. **[List Messages From a Channel](#list-messages)** + +### List Members + +This operation will return the data of all the members in your slack workspace. + +Slack datasource: ToolJet + +### Send Message + +This operation will send/post the message to a specified channel or posting to direct messages (also known as DMs or IMs) in your slack workspace. + +#### Required Parameters +- **Channel** +- **Message** + +Slack datasource: ToolJet + +### List Messages + +This operation will get the messages from a specified channel. + +#### Required Parameters +- **Channel** +- **Limit** +- **Next Cursor** + +Slack datasource: ToolJet + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/smtp.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/smtp.md new file mode 100644 index 0000000000..cd760e95f1 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/smtp.md @@ -0,0 +1,74 @@ +--- +id: smtp +title: SMTP +--- + +The SMTP datasource facilitates the connection between ToolJet applications and email servers, enabling the apps to send emails. + +
+ +## Connection + +To establish a connection with the SMTP data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview/)** page from the ToolJet dashboard and choose SMTP as the data source. + +ToolJet requires the following to connect to SMTP server: + +- **Host** +- **Port** +- **Username** +- **Password** + +### Finding Configuration Details + +The SMTP configuration details like host and port can usually be obtained from your email service provider. Here are some general settings for the most commonly used email providers: + +- **Gmail** + - **Host**: smtp.gmail.com + - **Port**: 587 or 465 (SSL) + - **Username**: Your Full Gmail Address + - **Password**: Your Gmail Password + +- **Yahoo Mail** + - **Host**: smtp.mail.yahoo.com + - **Port**: 465 (SSL) + - **Username**: Your Yahoo Email Address + - **Password**: Your Yahoo Mail Password + +- **Outlook.com/Hotmail** + - **Host**: smtp.office365.com + - **Port**: 587 or 465 (SSL) + - **Username**: your Outlook.com/Hotmail email address + - **Password**: your Outlook.com/Hotmail password. + + +smtp connect + +
+ +
+ +## Querying SMTP + +To create a query for sending an email, follow these steps: + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **SMTP** datasource added in previous step. +3. Enter the required parameters. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +#### Required Parameter + - **From**: Email address of the sender. + - **To**: Recipient's email address. + - **Subject** : Subject of the email. + - **Body** : You can enter the body text of the email in either raw text or html format, in their respective fields. + +#### Optional Parameter + - **From Name** : Name of the sender. + - **CC mail to** : Email address of the recipients that will receive a copy of the email, and their email addresses will be visible to other recipients. + - **BCC mail to** : Email address of the recipients that will receive a copy of the email but the email addressed will be hidden to other recipients. + - **Attachments** : You can add attachments to an SMTP query by referencing the file from the File Picker component in the attachments field. + - For instance, you can set the `Attachments` field value to `{{ components.filepicker1.file }}` or pass an object `{{ name: 'filename.jpg', dataURL: '......' }}` to include attachments. + +smtp connect + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/snowflake.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/snowflake.md new file mode 100644 index 0000000000..83f3f63133 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/snowflake.md @@ -0,0 +1,57 @@ +--- +id: snowflake +title: Snowflake +--- + +ToolJet can connect to Snowflake databases to read and write data. + +
+ +## Connection + +To establish a connection with the Snowflake data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview/)** page from the ToolJet dashboard and choose Snowflake as the data source. + +:::info +Please make sure the **Host/IP** of the database is accessible from your VPC if you have self-hosted ToolJet. If you are using ToolJet cloud, please **whitelist** our IP. + +You can find snowflake docs on network policies **[here](https://docs.snowflake.com/en/user-guide/network-policies.html)**. +::: + +ToolJet requires the following to connect to Snowflake database. + +- **Account** +- **Username** +- **Password** + +:::info +You can also configure for **[additional optional parameters](https://docs.snowflake.com/en/user-guide/nodejs-driver-use.html#additional-connection-options)**. +::: + +You can toggle on **Authentication required for all users** in the configuration. When enabled, users will be redirected to the OAuth consent screen the first time a query from this data source is triggered in the application. This ensures each user connects their own Google Calendar account securely. + +Note: After completing the OAuth flow, the query must be triggered again to load the data. + +ToolJet - Snowflake connection + +
+ +
+ +## Querying Snowflake + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **Snowflake** datasource added in previous step. +3. Select the **SQL Mode** form the dropdown and enter the query. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +ToolJet - Snowflake query + +```sql +select * from "SNOWFLAKE_SAMPLE_DATA"."WEATHER"."DAILY_14_TOTAL" limit 10; +``` + +:::tip +Query results can be transformed using transformations. Read our [transformations](/docs/beta/app-builder/custom-code/transform-data) documentation to learn more. +::: + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/soapapi.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/soapapi.md new file mode 100644 index 0000000000..d51388244f --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/soapapi.md @@ -0,0 +1,63 @@ +--- +id: soap-api +title: SOAP API +--- + +ToolJet can establish connections with SOAP APIs using its REST API integration. + +
+ +## Setting up a SOAP API Data Source + +To establish a connection with a SOAP API data source, you will need to add a REST API data source, as ToolJet handles SOAP APIs using REST API configurations. + +You can refer to [REST API Configuration Documentation](/docs/data-sources/restapi/) for more information. + +
+ +
+ +## Querying SOAP API + +Once you have connected to the REST API data source, you can easily write queries and interact with the SOAP API in the ToolJet application. Follow these steps to get started: + +1. Click on the **+ Add** button in the query manager at the bottom panel of the editor. +2. Select **REST API** from the Data Source section. +3. Select the **POST** Method and enter your SOAP API endpoint. +4. Add Headers + - **Content-Type** : **text/xml** (Specifies that the request body is XML.) + - Include any other required headers (e.g., Authorization, SOAPAction). +5. Add Request **Body** in XML format. +6. Click **Preview** to view the data returned from the query or click **Run** to execute the query. + +:::tip +You can also transform the query results using the **[Transformations](/docs/beta/app-builder/custom-code/transform-data)** feature. +::: + +**API Endpoint URL Example:** `http://www.dneonline.com/calculator.asmx` + +SOAP API Headers + +**Request Body Example:** + +```xml + + + + + 100 + 5 + + + +``` + +SOAP API Headers + +**Additional Notes:** + +- SOAP APIs typically use the POST method. Using a different method can cause errors. +- Ensure that you have added Content-Type: text/xml header. The server requires the correct header to interpret the request as SOAP. +- Include the SOAPAction header if specified in the API documentation. + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/stripe.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/stripe.md new file mode 100644 index 0000000000..101e9a0ba4 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/stripe.md @@ -0,0 +1,198 @@ +--- +id: stripe +title: Stripe +--- + +ToolJet can connect to your Stripe account to read or write customers' and payments' data. + +:::info +Check out the **[Stripe Refund App tutorial](https://blog.tooljet.ai/build-a-stripe-refund-tool-using-low-code/)** +::: + +
+ +## Connection + +To establish a connection with the Stripe data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview/)** page from the ToolJet dashboard and choose Stripe as the data source. + +ToolJet requires the following to connect to Stripe datasource. + +- **Stripe API key** + +ToolJet - Data source - Stripe + +You can get the Stripe API key from the dashboard of your Stripe account. Go to the Stripe account dashboard, click on the **Developers** on the top right, then on the left-sidebar go to the **API Keys**, you can simple reveal the **Secret Key** and copy-paste on ToolJet. + +ToolJet - Data source - Stripe + +
+ +
+ +## Querying Stripe + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **Stripe** datasource added in previous step. +3. Select the desired operation form the dropdown and enter the required parameter. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +:::tip +Query results can be transformed using transformations. Read our transformations documentation to see how: **[link](/docs/beta/app-builder/custom-code/transform-data)** +::: + +
+ +
+ +## Supported Operations + +You can check out the some of the operations mentioned below. All the operations for Stripe are available and can be performed from ToolJet. Check out the **[Stripe API documentation](https://stripe.com/docs/api/)** for the detailed information about each operation. + +

Account Operations

+ +| **Method** | **Endpoint** | **Description** | +| ---------- | ------------- | ------------------------ | +| DELETE | `/v1/account` | Delete an account | +| GET | `/v1/account` | Retrieve account details | +| POST | `/v1/account` | Create or update account | + +

Bank Accounts (Account)

+ +| **Method** | **Endpoint** | **Description** | +| ---------- | -------------------------------- | ----------------------------- | +| POST | `/v1/account/bank_accounts` | Add a bank account | +| DELETE | `/v1/account/bank_accounts/{id}` | Delete a bank account | +| GET | `/v1/account/bank_accounts/{id}` | Retrieve bank account details | +| POST | `/v1/account/bank_accounts/{id}` | Update bank account details | + +

Capabilities (Account)

+ +| **Method** | **Endpoint** | **Description** | +| ---------- | --------------------------------------- | ----------------------------- | +| GET | `/v1/account/capabilities` | Retrieve account capabilities | +| GET | `/v1/account/capabilities/{capability}` | Retrieve specific capability | +| POST | `/v1/account/capabilities/{capability}` | Update specific capability | + +

External Accounts (Account)

+ +| **Method** | **Endpoint** | **Description** | +| ---------- | ------------------------------------ | --------------------------------- | +| GET | `/v1/account/external_accounts` | Retrieve external accounts | +| POST | `/v1/account/external_accounts` | Add an external account | +| DELETE | `/v1/account/external_accounts/{id}` | Delete an external account | +| GET | `/v1/account/external_accounts/{id}` | Retrieve external account details | +| POST | `/v1/account/external_accounts/{id}` | Update external account details | + +

People (Account)

+ +| **Method** | **Endpoint** | **Description** | +| ---------- | ----------------------------- | -------------------------- | +| GET | `/v1/account/people` | Retrieve people associated | +| POST | `/v1/account/people` | Add a person to account | +| DELETE | `/v1/account/people/{person}` | Delete a person | +| GET | `/v1/account/people/{person}` | Retrieve person details | +| POST | `/v1/account/people/{person}` | Update person details | + +

Persons (Account)

+ +| **Method** | **Endpoint** | **Description** | +| ---------- | ------------------------------ | ----------------------- | +| POST | `/v1/account/persons` | Add a person | +| DELETE | `/v1/account/persons/{person}` | Delete a person | +| GET | `/v1/account/persons/{person}` | Retrieve person details | +| POST | `/v1/account/persons/{person}` | Update person details | + +

Other Account Operations

+ +| **Method** | **Endpoint** | **Description** | +| ---------- | ------------------------- | ----------------------------- | +| POST | `/v1/account/login_links` | Create login link for account | +| POST | `/v1/account_links` | Create account links | + +

Accounts (Specific) Operations

+ +| **Method** | **Endpoint** | **Description** | +| ---------- | ------------------------ | --------------------------------- | +| GET | `/v1/accounts` | Retrieve list of accounts | +| POST | `/v1/accounts` | Create a new account | +| DELETE | `/v1/accounts/{account}` | Delete a specific account | +| GET | `/v1/accounts/{account}` | Retrieve specific account details | +| POST | `/v1/accounts/{account}` | Update specific account details | + +

Bank Accounts (Specific)

+ +| **Method** | **Endpoint** | **Description** | +| ---------- | ------------------------------------------- | ----------------------------- | +| POST | `/v1/accounts/{account}/bank_accounts` | Add a bank account | +| DELETE | `/v1/accounts/{account}/bank_accounts/{id}` | Delete a bank account | +| GET | `/v1/accounts/{account}/bank_accounts/{id}` | Retrieve bank account details | + +

Capabilities (Specific)

+ +| **Method** | **Endpoint** | **Description** | +| ---------- | -------------------------------------------------- | ------------------------------------ | +| GET | `/v1/accounts/{account}/capabilities` | Retrieve account capabilities | +| GET | `/v1/accounts/{account}/capabilities/{capability}` | Retrieve specific capability details | +| POST | `/v1/accounts/{account}/capabilities/{capability}` | Update specific capability | + +

External Accounts (Specific)

+ +| **Method** | **Endpoint** | **Description** | +| ---------- | ----------------------------------------------- | --------------------------------- | +| GET | `/v1/accounts/{account}/external_accounts` | Retrieve external accounts | +| POST | `/v1/accounts/{account}/external_accounts` | Add an external account | +| DELETE | `/v1/accounts/{account}/external_accounts/{id}` | Delete an external account | +| GET | `/v1/accounts/{account}/external_accounts/{id}` | Retrieve external account details | + +

People (Specific)

+ +| **Method** | **Endpoint** | **Description** | +| ---------- | ---------------------------------------- | -------------------------- | +| GET | `/v1/accounts/{account}/people` | Retrieve people associated | +| POST | `/v1/accounts/{account}/people` | Add a person to account | +| DELETE | `/v1/accounts/{account}/people/{person}` | Delete a person | +| GET | `/v1/accounts/{account}/people/{person}` | Retrieve person details | +| POST | `/v1/accounts/{account}/people/{person}` | Update person details | + +

Persons (Specific)

+ +| **Method** | **Endpoint** | **Description** | +| ---------- | ----------------------------------------- | ----------------------- | +| POST | `/v1/accounts/{account}/persons` | Add a person | +| DELETE | `/v1/accounts/{account}/persons/{person}` | Delete a person | +| GET | `/v1/accounts/{account}/persons/{person}` | Retrieve person details | +| POST | `/v1/accounts/{account}/persons/{person}` | Update person details | + +

Other Account-Specific Operations

+ +| **Method** | **Endpoint** | **Description** | +| ---------- | ------------------------------------ | ----------------------------- | +| POST | `/v1/accounts/{account}/login_links` | Create login link for account | +| POST | `/v1/accounts/{account}/reject` | Reject an account | + +

Apple Pay Operations

+ +| **Method** | **Endpoint** | **Description** | +| ---------- | -------------------------------- | ---------------------------------- | +| GET | `/v1/apple_pay/domains` | Retrieve Apple Pay domains | +| POST | `/v1/apple_pay/domains` | Add a domain to Apple Pay | +| DELETE | `/v1/apple_pay/domains/{domain}` | Delete a domain from Apple Pay | +| GET | `/v1/apple_pay/domains/{domain}` | Retrieve specific Apple Pay domain | + +

Application Fees Operations

+ +| **Method** | **Endpoint** | **Description** | +| ---------- | ----------------------------------- | ---------------------------------- | +| GET | `/v1/application_fees` | Retrieve list of application fees | +| GET | `/v1/application_fees/{id}` | Retrieve specific application fee | +| POST | `/v1/application_fees/{id}/refund` | Refund an application fee | +| GET | `/v1/application_fees/{id}/refunds` | Retrieve list of refunds | +| POST | `/v1/application_fees/{id}/refunds` | Create a refund for an application | + +

Application Fee Refunds (Specific)

+ +| **Method** | **Endpoint** | **Description** | +| ---------- | ----------------------------------------- | -------------------------------- | +| GET | `/v1/application_fees/{fee}/refunds/{id}` | Retrieve specific refund details | + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/twilio.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/twilio.md new file mode 100644 index 0000000000..1ccaf075eb --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/twilio.md @@ -0,0 +1,57 @@ +--- +id: twilio +title: Twilio +--- + +ToolJet can connect to Twilio account to send sms. + +
+ +## Connection + +To establish a connection with the Twilio data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page from the ToolJet dashboard and choose Twilio as the data source. + +ToolJet requires the following to connect to Twilio: +- **Auth Token** +- **Account SID** +- **Messaging Service SID** + +You can get the **Auth Token and Account SID** on the dashboard of your Twilio account. + +ToolJet - Data source - Twilio + +For **Messaging Service SID**, you'll need to create a messaging service first from the Services under Messaging in the left-sidebar. + +ToolJet - Data source - Twilio + +ToolJet - Data source - Twilio + +
+ +
+ +## Querying Twilio + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **Twilio** datasource added in previous step. +3. Select **Send SMS** from the dropdown and enter the required parameters. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +
+ +
+ +## Supported operations + +### Send message + +This operation will send the specified message to specified mobile number. + +#### Required Parameters +- **To Number** +- **Body** + +ToolJet - Data source - Twilio + +
+ diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/typesense.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/typesense.md new file mode 100644 index 0000000000..95a928fe9a --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/typesense.md @@ -0,0 +1,141 @@ +--- +id: typesense +title: TypeSense +--- + +ToolJet can connect to your TypeSense deployment to read and write data. + +
+ +## Connection + +To establish a connection with the Typesense data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page from the ToolJet dashboard and choose Typesense as the data source. + +:::info +Please make sure the **Host/IP** of the database is accessible from your VPC if you have self-hosted ToolJet. If you are using ToolJet cloud, please **whitelist** our IP. +::: + +ToolJet requires the following to connect to TypeSense deployment: + +- **Host** +- **Port** +- **API Key** +- **Protocol** + +typesense connect + +
+ +
+ +## Querying TypeSense + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **Typesence** datasource added in previous step. +3. Select the desired operation from the dropdown and enter the required parameters. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +:::tip +Query results can be transformed using transformations. Read our transformations documentation to see how: **[link](/docs/beta/app-builder/custom-code/transform-data)** +::: + +
+ +
+ +## Supported Operations + +### Create a Collection + +With this operation you can easily create `Collections` in your TypeSense cluster. In the schema field, you'll need to define the schema for creating a new collection. Check out TypeSense docs to know more about collections **[here](https://typesense.org/docs/0.22.2/api/collections.html#create-a-collection)** + +#### Required Parameter + +- **Schema** + +typesense collection + +#### Example + +```yaml +[ + { "name": "id", "type": "string" }, + { "name": "name", "type": "string" }, + { "name": "price", "type": "float" }, +] +``` + +### Index a Document + +Use this operation to index a document to your collection. You'll need to specify the **Collection Name** where you want your document to be indexed and also provide the document data according the schema defined in the collection. Read more about Indexing a document in TypeSense **[here](https://typesense.org/docs/0.22.2/api/documents.html#index-a-single-document)**. + +#### Required Parameter + +- **Collection** +- **Document** + +typesense index + +```yaml +{ "id": "1", "name": "Laptop", "price": 999.99 } +``` + +### Search + +Use this operation to perform a search within the specified collection. Know more about the search parameters in the TypeSense doc **[here](https://typesense.org/docs/0.22.2/api/documents.html#search)**. + +#### Required Parameter + +- **Collection** + +typesense search + +```yaml +{ "filter_by": "price:<1000", "sort_by": "price:desc", "per_page": 10 } +``` + +### Get a Document + +Use this operation to fetch an individual document in a collection by providing the `id` of the document. Read more about it **[here](https://typesense.org/docs/0.22.2/api/documents.html#retrieve-a-document)**. + +#### Required Parameter + +- **Collection** +- **Id** + +typesense get + +### Update a Document + +Use this operation to update an individual document by providing the **Collection Name** and **Id** of the document. You'll need to provide the updated document data in the form of specified schema. Check out the TypeSense's doc on updating a document **[here](https://typesense.org/docs/0.22.2/api/documents.html#update-a-document)**. + +#### Required Parameter + +- **Collection** +- **Id** +- **Document** + +typesense update + +```yaml +{ "name": "Gaming Laptop", "price": 1199.99 } +``` + +### Delete a Document + +Delete a document from collection by providing the `Id` of the document. Check out the TypeSense's doc on deleting documents **[here](https://typesense.org/docs/0.22.2/api/documents.html#delete-documents)**. + +#### Required Parameter + +- **Collection** +- **Id** + +typesense delete + +

+ +:::tip +Make sure that you supply JSON strings instead of JavaScript objects for any document or schema that is being passed to the server, in any of the above operations. +::: + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/woocommerce.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/woocommerce.md new file mode 100644 index 0000000000..15a366870c --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/woocommerce.md @@ -0,0 +1,91 @@ +--- +id: woocommerce +title: WooCommerce +--- + +ToolJet can connect to WooCommerce databases to read and write data. + +
+ +## Connection + +To establish a connection with the WooCommerce data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page from the ToolJet dashboard and choose WooCommerce as the data source. + +ToolJet requires the following to connect to WooCommerce + +- **Host** +- **Consumer key** +- **Consumer secret** + +ToolJet - Data Source - Woocommerce + +:::info +NOTE: For generating keys visit admin dashboard of woocommerce , more info: https://woocommerce.github.io/woocommerce-rest-api-docs/?javascript#authentication +::: + +
+ +
+ +## Querying WooCommerce + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **WooCommerce** datasource added in previous step. +3. Select the desired resource from the dropdown and then select the desired operation and enter the required parameters. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +:::tip +Query results can be transformed using transformations. Read our transformations documentation to see how: **[link](/docs/beta/app-builder/custom-code/transform-data)** +::: + +
+ +
+ +## Resource + +### Customer + +#### Supported Operations + +- **list customer** +- **update customer** +- **delete customer** +- **batch update customer** +- **create customer** +- **retrieve customer** + +### Product + +#### Supported Operations + +- **list product** +- **update product** +- **delete product** +- **batch update product** +- **create product** +- **retrieve product** + +### Order + +#### Supported Operations + +- **list order** +- **update order** +- **delete order** +- **batch update order** +- **create order** +- **retrieve order** + +### Coupon + +#### Supported Operations + +- **list coupon** +- **create coupon** + +:::info +NOTE: For more info visit https://woocommerce.github.io/woocommerce-rest-api-docs/?javascript. +::: + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/data-sources/zendesk.md b/docs/versioned_docs/version-3.16.0-LTS/data-sources/zendesk.md new file mode 100644 index 0000000000..1fc7574516 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/data-sources/zendesk.md @@ -0,0 +1,116 @@ +--- +id: zendesk +title: Zendesk +--- + +ToolJet can connect to Zendesk APIs to read and write data using OAuth 2.0, which helps us to limit an application's access to a user's account. + +
+ +## Connection + +To establish a connection with the Zendesk data source, you can either click on the **+ Add new Data source** button located on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page from the ToolJet dashboard and choose Zendesk as the data source. + +ToolJet connects to your Zendesk app using : +- **Zendesk Sub-domain** +- **Client ID** +- **Client Secret** + +### Authorization Scopes + +You can create a Zendesk data source with one of either of the two permission scopes : +- **Read Only** +- **Read and Write** + +:::info +You must first be a verified user to make Zendesk API requests. This is configured in the Admin Center interface in **Apps and integrations > APIs > Zendesk APIs.** For more information, see Security and Authentication in the [Zendesk Support API reference](https://developer.zendesk.com/api-reference/ticketing/introduction/#security-and-authentication) or [check out Zendesk's docs](https://support.zendesk.com/hc/en-us/articles/4408845965210). +::: + +
+ +
+ +## Querying Zendesk + +1. Click on **+ Add** button of the query manager at the bottom panel of the editor. +2. Select the **Zendesk** datasource added in previous step. +3. Select the desired operation and enter the required parameters. +4. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query. + +ToolJet - Data source - Zendesk + +
+ + +
+ +## Supported Operations + +- **[List Tickets](#list-tickets)** +- **[List requested Tickets](#list-requested-tickets)** +- **[Show a Ticket](#show-tickets)** +- **[Update a Ticket](#update-tickets)** +- **[List Users](#list-users)** +- **[Get User](#get-user)** +- **[Search](#search)** + + +### List Tickets +Lists all the tickets in your Zendesk account. + +ToolJet - Data source - Zendesk + +### List Requested Tickets +Lists all the tickets requested by the user. + +#### Required Parameter +- **User ID** + +ToolJet - Data source - Zendesk + +### Show Tickets +Gets a ticket's properties with the given ID, though not the ticket comments. + +#### Required Parameter +- **Ticket ID** + +ToolJet - Data source - Zendesk + +### Update Tickets +Updates a ticket's properties with the given ID. + +#### Required Parameter +- **Ticket ID** +- **Body** + +ToolJet - Data source - Zendesk + +### List Users +Lists all the users in your Zendesk account. + +ToolJet - Data source - Zendesk + +### Get User +Gets a user's profile with the given ID. + +#### Required Parameter +- **User ID** + +ToolJet - Data source - Zendesk + +### Search + +The Search Query uses Zendesk's Search API to return tickets, users, and organizations with defined filters. + +#### Required Parameter +- **Query** + +Common filters include: +- `type:ticket` +- `type:user` +- `type:organization` +- `type:ticket organization:12345 status:open` + +ToolJet - Data source - Zendesk + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/backup/gitsync-backup.md b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/backup/gitsync-backup.md new file mode 100644 index 0000000000..8f72c6543e --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/backup/gitsync-backup.md @@ -0,0 +1,16 @@ +--- +id: gitsync-backup +title: GitSync Backup +--- + +GitSync enables users to back up their applications by pushing changes to a Git repository, ensuring a secured history. Whenever a change is pushed to the git repository, a commit is created. And this changes can be restored in ToolJet easily ensuring smooth back-up and restoring process. For details on configuring GitSync, refer to the **[GitSync Configuration](/docs/development-lifecycle/gitsync/gitsync-config)** guide. + +**Note**: Only the latest pushed version of the application is stored in the git repository, i.e. whenever a new version is pushed to the git repository, only the latest version is stored and all the previous versions are overridden. + +To know how to push changes to a git repository using GitSync, please refer to **[Push Changes to Git Repo](/docs/development-lifecycle/gitsync/push)** guide. + +## Restore Application + +Changes can be pulled from the git repository to restore an application. To know how to pull changes from a git repository using GitSync, please refer to **[Pull Changes from Git Repo](/docs/development-lifecycle/gitsync/pull)** guide. + +**Note:** A restored application from the git repository can't be edited. To edit the application you will need to create a clone of the application. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/cicd/example.md b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/cicd/example.md new file mode 100644 index 0000000000..030554d775 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/cicd/example.md @@ -0,0 +1,283 @@ +--- +id: example +title: Enable CI/CD with Jenkins +--- + +
+ Icon + Paid feature +
+ +In modern software development, teams often rely on CI/CD tools like **GitHub Actions**, **Jenkins**, **GitLab CI**, and **CircleCI** to automate application testing, version control, and deployments. These tools help enforce consistency across instances, reduce manual overhead, and improve release cycles by introducing automation at every stage of the software delivery process. + +With **ToolJet’s git sync CI/CD APIs**, organizations can bring the same level of automation and control to their internal applications built on ToolJet. By integrating git sync with CI/CD pipelines, you can: +- **Automate Git operations** such as syncing, pushing, and pulling app changes. +- **Deploy apps across environments** like development, staging, and production without manual intervention. + +In this guide, we will demonstrate how to integrate **git sync CI/CD** with **Jenkins**. The same approach can also be adapted to other automation tools like GitHub Actions or GitLab CI depending on your organization's preferences. + +We'll use a sample scenario of an organization called **Pyratech**, which manages internal ToolJet applications across multiple instances. + +## Setup Overview +- **Git Repository**: `https://github.com/pyratech/internal-apps.git` +- **Instances**: + - Development Instance: `https://dev.pyratech.com` + - Staging Instance: `https://staging.pyratech.com` + - Production Instance: `https://prod.pyratech.com` +- **Goal**: + - Developers commit changes from development instance to the configured GitHub repository. + - Jenkins pipelines handle syncing, pushing, pulling, and promoting apps across instances using ToolJet git sync CI/CD APIs. + + +Here are the key steps involved in setting up Jenkins integration with ToolJet git sync: + +## 1. Configure Git Sync for Each Instance + +Before setting up Jenkins, you need to configure git sync on each ToolJet instance using the **HTTPS Git Config API**. + +**Jenkins Example Shell Step** (optional script stage): +```bash +curl -X POST https://dev.pyratech.com/api/ext/organization/git \ + -H "Authorization: Basic $DEV_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "organizationId": "org-uuid", + "gitUrl": "https://github.com/pyratech/internal-apps.git", + "branchName": "main", + "githubAppId": "YOUR_APP_ID", + "githubAppInstallationId": "YOUR_INSTALLATION_ID", + "githubAppPrivateKey": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----" + }' +``` +Replace `$DEV_ACCESS_TOKEN` with the access token generated for the development environment. Similarly, set up git sync configurations for staging and production instances. + + +## 2. Setup Credentials in Jenkins: +1. In Jenkins, navigate to **Manage Jenkins > Manage Credentials > System**. +2. Click **Global credentials (unrestricted)**. +3. Add new credentials for each ToolJet instance such as BASE_URL, TOOLJET_ACCESS_TOKEN and GITHUB_ACCESS_TOKEN +4. Save the credentials. + +## 3. Jenkins Pipeline Setup with Git Sync Operations + +For our example, one of the approach would be to create a **single reusable [Jenkins pipeline](https://www.jenkins.io/doc/book/pipeline/)** that can execute different git sync CI/CD actions. + +With this pipeline setup: +- Developers or DevOps teams can select the desired git sync action (setup config, push, pull, deploy, etc.) when triggering the pipeline. +- Sensitive credentials like ToolJet tokens and GitHub App keys are securely stored in Jenkins using **Jenkins [Credentials Manager](https://www.jenkins.io/doc/book/security/credentials/)**. +- The pipeline dynamically triggers the appropriate ToolJet git sync API endpoint based on selected parameters. + +## 4. Jenkins Pipeline Actions + +The Jenkins pipeline should include several stages corresponding to various git sync actions. Here’s a high-level overview of what each stage might look like: + +**git sync Actions:** +| Action | Description | +|--------|-------------| +| **SETUP_GIT_CONFIG** | Configures the git sync connection for the organization with GitHub App credentials. | +| **PUSH_TO_GIT** | Pushes a specific app version from ToolJet to GitHub. | +| **CREATE_FROM_GIT** | Creates a new ToolJet application from the GitHub repository. | +| **SYNC_FROM_GIT** | Pulls the latest changes from GitHub into the specified ToolJet app. | +| **DEPLOY** | Deploys the app to the target environment. | + +Each of these actions maps to a specific REST API call handled within the pipeline functions like `setupGitConfig()`, `pushToGit()`, `syncFromGit()`, and `deployApp()`. Click [here](/docs/development-lifecycle/CI/CD/example#jenkins-pipeline-for-tooljet-git-sync) to see the full Jenkins file code snippet. + +## 5. Pipeline Example Flow + +Let’s break down an example using the same pipeline for multiple ToolJet instances: + +- **Dev Instance (Development)**: + - Developers push app changes to GitHub. + - Jenkins pipeline is triggered with: + - `ACTION = SYNC_FROM_GIT` + - `APP_ID = dev-app-id` + - Jenkins pulls latest GitHub changes into Dev instance. + +- **Staging Instance**: + - QA team triggers: + - `ACTION = PUSH_TO_GIT` (optional) β€” to sync Dev changes back to GitHub. + - `ACTION = SYNC_FROM_GIT` β€” to pull latest GitHub updates. + - `ACTION = DEPLOY` β€” to promote to staging environment. + +- **Production Instance**: + - Release Manager triggers: + - `ACTION = SYNC_FROM_GIT` + - `ACTION = DEPLOY` β€” to promote final changes to production. + +Following is the Jenkins pipeline configuration for Pyratech's git sync CI/CD flow we discussed above. + +
+Click to expand Jenkinsfile +``` +pipeline { + agent any + + environment { + TOOLJET_BASE_URL = credentials('TOOLJET_BASE_URL') // Example: https://dev.pyratech.com + TOOLJET_ACCESS_TOKEN = credentials('TOOLJET_ACCESS_TOKEN') + } + + parameters { + choice( + name: 'ACTION', + choices: [ + 'SETUP_GIT_CONFIG', + 'PUSH_TO_GIT', + 'CREATE_FROM_GIT', + 'SYNC_FROM_GIT', + 'DEPLOY' + ], + description: 'Select the Git sync action to perform' + ) + + string(name: 'APP_ID', defaultValue: '', description: 'App ID (required for PUSH_TO_GIT, SYNC_FROM_GIT, DEPLOY)') + string(name: 'VERSION_ID', defaultValue: '', description: 'Version ID (required for PUSH_TO_GIT)') + string(name: 'COMMIT_MESSAGE', defaultValue: 'Automated commit from Jenkins', description: 'Commit message for PUSH_TO_GIT') + string(name: 'ORG_ID', defaultValue: '', description: 'Organization ID (required for SETUP_GIT_CONFIG, CREATE_FROM_GIT)') + string(name: 'GIT_URL', defaultValue: '', description: 'Git HTTPS URL (required for SETUP_GIT_CONFIG)') + string(name: 'BRANCH_NAME', defaultValue: 'main', description: 'Git branch name (required for SETUP_GIT_CONFIG)') + string(name: 'GITHUB_APP_ID', defaultValue: '', description: 'GitHub App ID (required for SETUP_GIT_CONFIG)') + string(name: 'GITHUB_APP_INSTALLATION_ID', defaultValue: '', description: 'GitHub App Installation ID (required for SETUP_GIT_CONFIG)') + text(name: 'GITHUB_APP_PRIVATE_KEY', defaultValue: '', description: 'GitHub App Private Key PEM (required for SETUP_GIT_CONFIG)') + } + + stages { + stage('Perform git sync Action') { + steps { + script { + switch (params.ACTION) { + case 'SETUP_GIT_CONFIG': + validate(params.ORG_ID, 'ORG_ID') + validate(params.GIT_URL, 'GIT_URL') + validate(params.BRANCH_NAME, 'BRANCH_NAME') + validate(params.GITHUB_APP_ID, 'GITHUB_APP_ID') + validate(params.GITHUB_APP_INSTALLATION_ID, 'GITHUB_APP_INSTALLATION_ID') + validate(params.GITHUB_APP_PRIVATE_KEY, 'GITHUB_APP_PRIVATE_KEY') + setupGitConfig() + break + case 'PUSH_TO_GIT': + validate(params.APP_ID, 'APP_ID') + validate(params.VERSION_ID, 'VERSION_ID') + pushToGit(params.APP_ID, params.VERSION_ID, params.COMMIT_MESSAGE) + break + case 'CREATE_FROM_GIT': + validate(params.APP_ID, 'APP_ID') + validate(params.ORG_ID, 'ORG_ID') + createFromGit(params.APP_ID, params.ORG_ID) + break + case 'SYNC_FROM_GIT': + validate(params.APP_ID, 'APP_ID') + syncFromGit(params.APP_ID) + break + case 'DEPLOY': + validate(params.APP_ID, 'APP_ID') + deployApp(params.APP_ID) + break + default: + error "Invalid ACTION selected: ${params.ACTION}" + } + } + } + } + } + + post { + success { + echo "βœ… git sync action '${params.ACTION}' completed successfully." + } + failure { + echo "❌ git sync action '${params.ACTION}' failed. Please check logs." + } + } +} + +def validate(value, name) { + if (!value?.trim()) { + error "Missing required parameter: ${name}" + } +} + +def setupGitConfig() { + def privateKeyFormatted = params.GITHUB_APP_PRIVATE_KEY.replace('\\n', '\n') + def payload = [ + organizationId: params.ORG_ID, + gitUrl: params.GIT_URL, + branchName: params.BRANCH_NAME, + githubAppId: params.GITHUB_APP_ID, + githubAppInstallationId: params.GITHUB_APP_INSTALLATION_ID, + githubAppPrivateKey: privateKeyFormatted + ] + def response = httpRequest( + httpMode: 'POST', + url: "${env.TOOLJET_BASE_URL}/api/ext/organization/git", + contentType: 'APPLICATION_JSON', + customHeaders: [[name: 'Authorization', value: "Basic ${env.TOOLJET_ACCESS_TOKEN}"]], + requestBody: groovy.json.JsonOutput.toJson(payload) + ) + if (response.status != 201) { + error "Failed to set up Git config. Status: ${response.status}. Response: ${response.content}" + } +} + +def pushToGit(appId, versionId, commitMsg) { + def payload = [commitMessage: commitMsg] + def response = httpRequest( + httpMode: 'POST', + url: "${env.TOOLJET_BASE_URL}/api/ext/apps/${appId}/versions/${versionId}/git-sync/push", + contentType: 'APPLICATION_JSON', + customHeaders: [[name: 'Authorization', value: "Basic ${env.TOOLJET_ACCESS_TOKEN}"]], + requestBody: groovy.json.JsonOutput.toJson(payload) + ) + if (response.status != 200) { + error "Failed to push to Git. Status: ${response.status}. Response: ${response.content}" + } +} + +def createFromGit(appId, orgId) { + def payload = [ + gitAppId: appId, + gitVersionId: params.BRANCH_NAME, + organizationId: orgId + ] + def response = httpRequest( + httpMode: 'POST', + url: "${env.TOOLJET_BASE_URL}/api/ext/apps?createMode=git", + contentType: 'APPLICATION_JSON', + customHeaders: [[name: 'Authorization', value: "Basic ${env.TOOLJET_ACCESS_TOKEN}"]], + requestBody: groovy.json.JsonOutput.toJson(payload) + ) + if (response.status != 201) { + error "Failed to create app from Git. Status: ${response.status}. Response: ${response.content}" + } +} + +def syncFromGit(appId) { + def response = httpRequest( + httpMode: 'PUT', + url: "${env.TOOLJET_BASE_URL}/api/ext/apps/${appId}?createMode=git", + contentType: 'APPLICATION_JSON', + customHeaders: [[name: 'Authorization', value: "Basic ${env.TOOLJET_ACCESS_TOKEN}"]] + ) + if (response.status != 200) { + error "Failed to sync from Git. Status: ${response.status}. Response: ${response.content}" + } +} + +def deployApp(appId) { + def response = httpRequest( + httpMode: 'POST', + url: "${env.TOOLJET_BASE_URL}/api/ext/apps/${appId}/promote", + contentType: 'APPLICATION_JSON', + customHeaders: [[name: 'Authorization', value: "Basic ${env.TOOLJET_ACCESS_TOKEN}"]] + ) + if (response.status != 200) { + error "Failed to deploy app. Status: ${response.status}. Response: ${response.content}" + } +} +``` +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/cicd/gitsync-api.md b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/cicd/gitsync-api.md new file mode 100644 index 0000000000..fdd3c7b849 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/cicd/gitsync-api.md @@ -0,0 +1,135 @@ +--- +id: gitsync-api +title: GitSync API +--- + +
+ Icon + Paid feature +
+ +ToolJet’s git sync CI/CD APIs enable organizations to programmatically manage the complete lifecycle of their ToolJet applications within their existing CI/CD piplines. With these RESTful APIs, you can configure git sync, push and pull changes from Git repositories, and automate application deployments without manual intervention. + +By integrating these APIs into your CI/CD pipelines (e.g., Jenkins, GitHub Actions, GitLab CI), you can: +- **Automate git sync operations** to eliminate manual syncing via the ToolJet UI. +- **Implement enterprise-grade deployment strategies** with standardized governance. +- **Streamline development cycles**, ensuring your internal apps follow the same release processes as your core applications. + +The following APIs are available to manage git sync within your CI/CD pipeline. + +### Add GitHub HTTPS Git Configuration + + - **Description:** Configure GitHub HTTPS settings for an organization by associating a GitHub App and repo. + - **URL:** `/api/ext/organization/git` + - **Method:** POST + - **Authorization:** `Basic ` + - **Content-Type:** `application/json` + - **Body:** The body object can contain the following fields: + - `organizationId` (string, required): UUID of the organization. + - `gitUrl` (string, required): Full HTTPS Git URL. + - `branchName` (string, required): Branch to sync with (e.g., "main"). + - `githubAppId` (string, required): GitHub App ID. + - `githubAppInstallationId` (string, required): GitHub App installation ID. + - `githubAppPrivateKey` (string, required): GitHub App private key (PEM format). + +
+ +Request Body Example + +```json +{ + "organizationId": "45892c81-c1f0-48c6-8875-c2e4fca516f8", + "gitUrl": "https://github.com/username/repository.git", + "branchName": "main", + "githubAppId": "123456", + "githubAppInstallationId": "78910", + "githubAppPrivateKey": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----" +} +``` + +
+ + - **Response:** `201 Created` + +### Push an App Version to GitHub + + - **Description:** Push a specific app version to the configured GitHub repository. + - **URL:** `/api/ext/apps/:appId/versions/:versionId/git-sync/push` + - **Method:** POST + - **Authorization:** `Basic ` + - **Content-Type:** `application/json` + - **Params:** + - appId (string): The ID of the app. + - versionId (string): The ID of the app version. + - **Body:** The body object can contain the following fields: + - `commitMessage` (string, required): Git commit message. + +
+ +Request Body Example + +```json +{ + "commitMessage": "Updated app configuration and components" +} +``` + +
+ + - **Response:** `200 OK` + +### Create a New App from GitHub + + - **Description:** Creates a new ToolJet app from a GitHub repo. + - **URL:** `/api/ext/apps?createMode=git` + - **Method:** POST + - **Authorization:** `Basic ` + - **Content-Type:** `application/json` + - **Body:** The body object can contain the following fields: + - `gitAppId` (string, required): Git App ID. + - `gitVersionId` (string, required): Git version ID (branch or tag). + - `organizationId` (string, required): UUID of the organization. + +
+ +Request Body Example + +```json +{ + "gitAppId": "app-123456", + "gitVersionId": "main", + "organizationId": "45892c81-c1f0-48c6-8875-c2e4fca516f8" +} +``` + +
+ + - **Response:** `201 Created` + +### Sync and Pull Changes to Existing App from Git + + - **Description:** Sync and pull the latest changes from GitHub for an existing ToolJet app. + - **URL:** `/api/ext/apps/:appId?createMode=git` + - **Method:** PUT + - **Authorization:** `Basic ` + - **Content-Type:** `application/json` + - **Params:** + - appId (string): The ID of the app. + - **Body:** No body required. + - **Response:** `200 OK` + +### Auto Promote App + + - **Description:** Deploys an app by pulling the latest changes from Git and promoting the latest version to the production environment. + - **URL:** `/api/ext/apps/:appId/promote` + - **Method:** POST + - **Authorization:** `Basic ` + - **Params:** + - appId (string): ID of the app to deploy. + - **Body:** No body required. + - **Response:** `200 OK` \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/cicd/overview.md b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/cicd/overview.md new file mode 100644 index 0000000000..ed40a8331a --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/cicd/overview.md @@ -0,0 +1,36 @@ +--- +id: overview +title: Overview +--- +
+ Icon + Paid feature +
+ +ToolJet’s git sync CI/CD feature enables organizations to integrate ToolJet applications into their existing CI/CD pipelines using industry-standard tools such as Jenkins, GitHub Actions, CircleCI, and GitLab CI. This feature brings the power of git sync to your automation workflows through a set of ToolJet APIs, allowing your development teams to automate Git operations without relying on manual UI interactions. + +For example, teams managing internal reporting tools or approval workflows can automate deployment to staging and production environments, ensuring consistency without manual UI intervention. + +## Why Git Sync CI/CD + +Modern development teams rely on CI/CD pipelines to enforce consistency, streamline deployments, and enable faster iterations. Traditionally, ToolJet applications required manual interactions to perform Git operations like syncing, pushing, or pulling changes. + +With git sync CI/CD, you can: +- Automate Git operations (sync, push, pull) directly from your pipelines. +- Programmatically manage ToolJet application deployments as part of your broader SDLC process. +- Integrate with your existing DevOps tools and processes, reducing context-switching and operational overhead. + +## Key Benefits +- Enterprise-Grade Automation: Incorporate ToolJet applications into your organization’s enterprise CI/CD setup. +- Increased Developer Productivity: Developers can focus on building applications while CI/CD pipelines handle deployments and updates. +- Consistency and Governance: Maintain application lifecycle consistency across environments with Git-driven workflows. +- Easy Integration: Easily integrate with any DevOps tool using ToolJet's RESTful APIs. + +## Next Steps +- Refer to [Using Git Sync CI/CD APIs](/docs/development-lifecycle/CICD/gitsync-api) for detailed API usage. +- Check out [Git Sync CI/CD with Jenkins Example](/docs/development-lifecycle/CICD/example) for a practical implementation guide. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/cloud/example.md b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/cloud/example.md new file mode 100644 index 0000000000..dc0fda0597 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/cloud/example.md @@ -0,0 +1,30 @@ +--- +id: example-configuration +title: Example Configuraiton +--- + +This guide will walk you through setting up a multi-environment in ToolJet with a practical example. Imagine **Nexora Enterprises**, a company building an internal application using ToolJet. + +## Configuring Data Source + +In ToolJet, you can configure data sources for each environment, allowing your application to connect to different databases or APIs based on the environment. + +In this case, the company uses data from a Postgres data source for their ToolJet apps, with separate databases for development, staging, and production environments. They need to configure the Postgres data source for each environment in the Data Sources section. For more details, refer to the [Data Source](/docs/data-sources/overview) Documentation. + +self-hosted-env-concept + +## Configuring Constants + +The company also uses different global and secret constants for each environment. Global Constants are reusable values that can be applied consistently across the product, while Secrets are used for securely storing sensitive data. These can be configured in the Workspace Constants section. For more details, check the [Workspace Constants and Secrets](/docs/security/constants/) Documentation. + +self-hosted-env-concept + +## Multi-Environment Setup in ToolJet +- The company can configure data sources and constants for each environment, and ToolJet will automatically use the appropriate ones based on the target environment. +- Now developers can start building applications in the **development environment**, where they create and iterate on new features. In this environment, they have access to the development database, which is configured during data source setup. +- Once the application is ready, it moves to the **staging environment**, where the QA team tests it thoroughly. If any bugs or feedback arise, developers create a new version, implement the necessary changes, and promote the updated application back to staging for further testing. +- The data sources for each environment will be connected based on the configuration set in the previous step. +- For details on managing versions, check the **Version Control Documentation**. +- After successful testing, the application is promoted to **production** and released, making it available to end users. This environment uses the production database set up during data source configuration. + +self-hosted-env-concept \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/cloud/multi-environment.md b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/cloud/multi-environment.md new file mode 100644 index 0000000000..0981ba3e46 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/cloud/multi-environment.md @@ -0,0 +1,84 @@ +--- +id: multi-environment +title: Multi-Environment +--- +
+ Icon + Paid feature +
+ +Environments in ToolJet help manage different stages of application development, ensuring smooth transitions between development, testing, and production. This guide covers what environments are, their purpose, and how they function in ToolJet. + +Environments make it easier to develop and deploy applications without disrupting production. They keep changes isolated, so testing and debugging can happen without affecting live users. Teams can collaborate more efficiently, as different environments allow them to work independently. + +### What are Environments? + +An environment in ToolJet represents a separate configuration space where **applications**, **data** **sources**, and **constants** can be defined and managed. + +By default, ToolJet provides three environments: + +- **Development**: The Development environment is where application development and initial testing take place. It is a dedicated space for ToolJet developers to build, configure, and experiment with application features. Changes in this environment do not affect live users, allowing for frequent updates and debugging. + +- **Staging**: The Staging environment acts as a pre-production space where applications undergo thorough testing before deployment. It closely resembles the Production environment and helps ensure that all features, performance, and security aspects function as expected. Teams such as QA and product managers use this environment to validate and approve changes before releasing them to end-users. + +- **Production**: The Production environment is the final, live version of the application where end users interact with it. This environment is stable and optimized for performance after thorough testing in the Development and Staging environments. + + +### Multi-Environment Support in ToolJet + +ToolJet provides environment management across different components: + +#### Applications + +Each application has development, staging, and production environments. Developers build the application in the development environment and then move it to staging for testing. Your testing team can review the application in staging, and once it's thoroughly tested, you can promote it to production and release it to your end users. + +#### Data Sources + +Data sources can be configured separately for each environment, allowing applications to connect to different databases or APIs depending on the environment. This ensures secure and structured access to relevant data during each stage of development. + +#### Constants + +Constants such as API keys, credentials, or other configuration variables can be defined uniquely for each environment. This helps maintain security and prevents misconfigurations across different deployment stages. + +### Application Life cycle + +The application lifecycle in ToolJet involves managing applications across different environments development, staging, and production. You can build the application in development environment and promote it to staging for testing. After testing you can promote it to production and release the app for your end-users. + +You can configure data sources and constants for each environment, and ToolJet will automatically use the appropriate ones based on the target environment. + +- **Development** – Developers build and test the application in the ToolJet app builder. + +- **Staging** – The testing or product team validates requirements and tests the application using staging data. Apps and queries cannot be edited in this environment. + +- **Production** – After thorough testing in staging, the application is promoted to production. This can serve as a pre-release environment where you test with production data and constants before releasing the application to end users. Refer to [Release](/docs/development-lifecycle/release/release-rollback) documentation to learn more. + +self-hosted-env-concept + + +### Impacted behavior with environment permission + +Each environment has a different impact on your application. Please refer the following table for details. + +| Action | Development | Staging | Production | +|--------------------|------------|---------|------------| +| Edit versions | βœ… | ❌ | ❌ | +| Rename versions | βœ… | ❌ | ❌ | +| Delete versions | βœ… | ❌ | ❌ | +| Create new versions | βœ… | ❌ | ❌ | +| Promote | βœ… | βœ… | - | + + +Checkout the [Environment-Example](/docs/development-lifecycle/environment/cloud/example-configuration) guide to learn about multi-environment in ToolJet with a practical example. + +### Promote Application Permission + +Admin can configure the Promote Application permission from the [Permissions](/docs/user-management/role-based-access/user-roles#permissions-for-user-roles) page. This disables the **Promote** button for users who do not have the required permission, allowing only authorized roles, such as team leads, to promote the application from one environment to another. + +self-hosted-env-concept + + \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/self-hosted/example.md b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/self-hosted/example.md new file mode 100644 index 0000000000..5879783254 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/self-hosted/example.md @@ -0,0 +1,30 @@ +--- +id: example-configuration +title: Example Configuraiton +--- + +This guide will walk you through setting up a multi-environment in ToolJet with a practical example. Imagine **Nexora Enterprises**, a company building an internal application using ToolJet. + +## Configuring Data Source + +In ToolJet, you can configure data sources for each environment, allowing your application to connect to different databases or APIs based on the environment. + +In this case, the company uses data from a Postgres data source for their ToolJet apps, with separate databases for development, staging, and production environments. They need to configure the Postgres data source for each environment in the Data Sources section. For more details, refer to the [Data Source](/docs/data-sources/overview) Documentation. + +self-hosted-env-concept + +## Configuring Constants + +The company also uses different global and secret constants for each environment. Global Constants are reusable values that can be applied consistently across the product, while Secrets are used for securely storing sensitive data. These can be configured in the Workspace Constants section. For more details, check the [Workspace Constants and Secrets](/docs/security/constants/) Documentation. + +self-hosted-env-concept + +## Multi-Environment Setup in ToolJet +- The company can configure data sources and constants for each environment, and ToolJet will automatically use the appropriate ones based on the target environment. +- Now developers can start building applications in the **development environment**, where they create and iterate on new features. In this environment, they have access to the development database, which is configured during data source setup. +- Once the application is ready, it moves to the **staging environment**, where the QA team tests it thoroughly. If any bugs or feedback arise, developers create a new version, implement the necessary changes, and promote the updated application back to staging for further testing. +- The data sources for each environment will be connected based on the configuration set in the previous step. +- For details on managing versions, check the [Version Control Documentation](/docs/development-lifecycle/release/version-control). +- After successful testing, the application is promoted to **production** and released, making it available to end users. This environment uses the production database set up during data source configuration. + +self-hosted-env-concept \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/self-hosted/multi-environment.md b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/self-hosted/multi-environment.md new file mode 100644 index 0000000000..e49195de38 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/self-hosted/multi-environment.md @@ -0,0 +1,84 @@ +--- +id: multi-environment +title: Multi-Environment +--- +
+ Icon + Paid feature +
+ +Environments in ToolJet help manage different stages of application development, ensuring smooth transitions between development, testing, and production. This guide covers what environments are, their purpose, and how they function in ToolJet. + +Environments make it easier to develop and deploy applications without disrupting production. They keep changes isolated, so testing and debugging can happen without affecting live users. Teams can collaborate more efficiently, as different environments allow them to work independently. + +### What are Environments? + +An environment in ToolJet represents a separate configuration space where **applications**, **data** **sources**, and **constants** can be defined and managed. + +By default, ToolJet provides three environments: + +- **Development**: The Development environment is where application development and initial testing take place. It is a dedicated space for ToolJet developers to build, configure, and experiment with application features. Changes in this environment do not affect live users, allowing for frequent updates and debugging. + +- **Staging**: The Staging environment acts as a pre-production space where applications undergo thorough testing before deployment. It closely resembles the Production environment and helps ensure that all features, performance, and security aspects function as expected. Teams such as QA and product managers use this environment to validate and approve changes before releasing them to end-users. + +- **Production**: The Production environment is the final, live version of the application where end users interact with it. This environment is stable and optimized for performance after thorough testing in the Development and Staging environments. + + +### Multi-Environment Support in ToolJet + +ToolJet provides environment management across different components: + +#### Applications + +Each application has development, staging, and production environments. Developers build the application in the development environment and then move it to staging for testing. Your testing team can review the application in staging, and once it's thoroughly tested, you can promote it to production and release it to your end users. + +#### Data Sources + +Data sources can be configured separately for each environment, allowing applications to connect to different databases or APIs depending on the environment. This ensures secure and structured access to relevant data during each stage of development. + +#### Constants + +Constants such as API keys, credentials, or other configuration variables can be defined uniquely for each environment. This helps maintain security and prevents misconfigurations across different deployment stages. + +### Application Life cycle + +The application lifecycle in ToolJet involves managing applications across different environments development, staging, and production. You can build the application in development environment and promote it to staging for testing. After testing you can promote it to production and release the app for your end-users. + +You can configure data sources and constants for each environment, and ToolJet will automatically use the appropriate ones based on the target environment. + +- **Development** – Developers build and test the application in the ToolJet app builder. + +- **Staging** – The testing or product team validates requirements and tests the application using staging data. Apps and queries cannot be edited in this environment. + +- **Production** – After thorough testing in staging, the application is promoted to production. This can serve as a pre-release environment where you test with production data and constants before releasing the application to end users. Refer to [Release](/docs/development-lifecycle/release/release-rollback) documentation to learn more. + +self-hosted-env-concept + + +### Impacted behavior with environment permission + +Each environment has a different impact on your application. Please refer the following table for details. + +| Action | Development | Staging | Production | +|--------------------|------------|---------|------------| +| Edit versions | βœ… | ❌ | ❌ | +| Rename versions | βœ… | ❌ | ❌ | +| Delete versions | βœ… | ❌ | ❌ | +| Create new versions | βœ… | ❌ | ❌ | +| Promote | βœ… | βœ… | - | + + +Checkout the [Environment-Example](/docs/development-lifecycle/environment/self-hosted/example-configuration) guide to learn about multi-environment in ToolJet with a practical example. + +### Promote Application Permission + +Admin can configure the Promote Application permission from the [Permissions](/docs/user-management/role-based-access/user-roles#permissions-for-user-roles) page. This disables the **Promote** button for users who do not have the required permission, allowing only authorized roles, such as team leads, to promote the application from one environment to another. + +self-hosted-env-concept + + \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/self-hosted/multi-instance/example.md b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/self-hosted/multi-instance/example.md new file mode 100644 index 0000000000..b2e5291045 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/self-hosted/multi-instance/example.md @@ -0,0 +1,81 @@ +--- +id: example-configuration +title: Example Configuration +--- + + +In this guide, you'll learn how to migrate applications using GitSync in a multi-instance ToolJet setup through a practical example. + +Vertex Solutions, a company building internal applications with ToolJet, has three ToolJet instances for **development, staging, and production** environments. They have configured Gitsync in all the three instances with GitHub by following the setup instructions given in the [GitSync](/docs/development-lifecycle/gitsync/overview) documentation. + +## Creating the App + +The company wants to create an **Inventory Management System**. A developer starts by clicking **Create New App** on the dashboard. In the modal that appears, they enter the app name and select the **Commit changes** checkbox to save the app to the configured Git repository. Upon clicking **Create App**, the app will be added to your Git repository with a commit message. + +self-hosted-env-concept + +self-hosted-env-concept + +- Developers then build the app in the App Builder by dragging and dropping components and adding relevant queries. Once the changes are complete, they can use the GitSync button in the top bar to push a commit to the Git repository. + +self-hosted-env-concept + + +- Once committed, the updates appear in the Git repository, showing the commit message, author, and timestamp. +self-hosted-env-concept +- The development is done and the app is ready to be pulled into the staging instance for testing. + + +## Importing the App in Staging + +After configuring GitSync for the staging instance with the same Git repository as the development instance, testers can import the app by following these steps: + +- Navigate to the **ToolJet dashboard** of the staging instance. + +- Click on the **three dots** next to the **Create New App** button. +- Select **Import from Git Repository** to pull the app. + self-hosted-env-concept +- Choose the app from the dropdown list. The app name and last commit details appear. + +- Click **Import App** to import it into the staging instance. +self-hosted-env-concept + +- Once the apps are imported into the staging instance, all data sources are imported as well. However, for security reasons, passwords and secrets in the data source configuration are not included. +- To ensure the app functions properly in the staging instance and can be tested with staging data, users must re-enter these details in the configuration. +- After adding the data source configuration, testers can verify the app's features and functionality. The app will open in view-only mode. + +### Iterating and Fixing Issues + +If testers find bugs or require modifications, developers create a **new version** in the development instance. + +self-hosted-env-concept + +When committing a new version via **GitSync**: + +- The JSON file inside the app folder is updated with the version name. + +- The **meta.json** file in the .meta folder is modified with the new version ID and name. +self-hosted-env-concept + +After implementing necessary changes, developers commit the updates to the Git repository. + +### Pulling Updates in Staging + +Testers in the **staging instance** update the app by: + +- Clicking the **GitSync** button in the top bar. + +- A modal appears with an option to **Check for Updates**. +self-hosted-env-concept + +- Clicking **Check for Updates** fetches the latest changes from the Git repository. + +- Commit details (message, author, date) are displayed. + +- Clicking **Pull Changes** syncs the latest updates into the staging instance. + +self-hosted-env-concept + +### Deploying to Production + +Once the application passes testing in staging, it is imported into the **production instance** using the same GitSync process. The application is then released, making it available to end users. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/self-hosted/multi-instance/instance-as-environment.md b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/self-hosted/multi-instance/instance-as-environment.md new file mode 100644 index 0000000000..ea4e933e91 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/environment/self-hosted/multi-instance/instance-as-environment.md @@ -0,0 +1,29 @@ +--- +id: instance-as-environment +title: Instance as Enviroment +--- + + +In this guide, you will learn to manage a Multi-Instance ToolJet deployment. A Multi-Instance setup allows you to deploy multiple isolated ToolJet instances, each functioning as a separate environment, such as development, staging, and production, to support a structured Software Development Life Cycle (SDLC). In this setup each instance operates independently with a strict isolation of resources, users, and applications. + +## Setting Up Multi-Instance Environments + +To enable a multi-instance setup, you need to deploy separate ToolJet instances on your self-hosted infrastructure. Refer to the [setup](/docs/setup/try-tooljet) guide to learn about ToolJet self-hosted deployments. + +## Migrate applications between Instances + +ToolJet’s GitSync feature helps to migrate applications between instances by pushing and pulling changes through a Git repository. It supports Git providers such as GitHub, GitLab, Gitea and Bitbucket. For setup instructions, refer to the [GitSync documentation](/docs/development-lifecycle/gitsync/overview).With GitSync, users can effortlessly transfer applications between instances by committing and pushing changes to a shared repository. This ensures that once an application is developed in development instance, it can be easily synchronized with other instances like staging and production. + +## Pushing and Pulling Apps Between Instances via GitSync + +### Pushing Changes + +GitSync enables users to commit and push updates from your instance to your Git repository. New apps, renames, and version creations are auto-committed and you can also manually commit changes using the GitSync button in the App Builder. Refer to [Push-Gitsync](/docs/development-lifecycle/gitsync/push) doc to learn more. + +### Pulling Changes + +GitSync allows you to pull updates from a Git repository into your instance. You can import apps from Git through the ToolJet dashboard. Once pulled, the app will be in view-only mode. You can also check for updates, which fetches the latest commits with details like author and date. If updates are available, you can pull changes and sync them. Refer to [Pull-Gitsync](/docs/development-lifecycle/gitsync/pull) doc to learn more.Here is the diagram showing how you can use gitsync to migrate your apps across instances. + +self-hosted-env-concept + +Checkout the [Multi-Instance-Example](/docs/development-lifecycle/environment/self-hosted/multi-instance/example-configuration) guide to learn how to use GitSync for multi-instance setup in ToolJet with a practical example. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/delete-gitsync.md b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/delete-gitsync.md new file mode 100644 index 0000000000..65daf8c753 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/delete-gitsync.md @@ -0,0 +1,24 @@ +--- +id: delete-gitsync +title: Delete GitSync Configuration +--- + +In ToolJet, GitSync can be enabled, disabled, or deleted based on your requirements. + +- **Enabled**: When GitSync is enabled the users will be able to commit changes to the git repository. +- **Disabled**: + - **Non-Admin Users**: The users will not be able to commit changes to the git repository. They will see a dialogue box that the GitSync feature is not configured and they need to contact the admin to configure it. + - **For admin users**: The users will see a dialogue box with a link to configure the GitSync feature. +- **Delete GitSync Configuration**: Deleting the GitSync configuration will not delete the apps from the git repository. The apps will still be available in the git repository in the same state as they were before the GitSync configuration was deleted. + +## Enable/Disable GitSync + +To enable or disable the GitSync feature, go to the **Configure git** tab on the **Workspace settings** page, and toggle on/off the **Connect** switch. This is only available if the GitSync feature is configured. + +GitSync + +## Delete GitSync Configuration + +To delete the GitSync configuration, go to the **Configure git** tab on the **Workspace settings** page, and click on the **Delete configuration** button. This will delete the SSH key from the ToolJet configuration and the GitSync feature will be disabled. + +GitSync diff --git a/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/gitsync-config.md b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/gitsync-config.md new file mode 100644 index 0000000000..72b16e2e63 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/gitsync-config.md @@ -0,0 +1,98 @@ +--- +id: gitsync-config +title: Configure GitSync +--- + +In this guide, we will explore how to configure git sync using GitHub as the repository manager. By default git sync is configured for the **master** branch, but this can be configured to a different branch as well, refer to **[Configuring git sync on a Different Branch](#configuring-gitsync-on-a-different-branch)** section for more information. + +For more information on using other repository managers, such as GitLab or Gitea, refer to the **[SSH Configuration for Git Repo Manager](/docs/development-lifecycle/gitsync/ssh-config)** guide. + +## Setting up GitSync in ToolJet + +Role Required: **Admin** + +1. **Create a New Repository**
+ Create a new repository on your GitHub. The repository can be public or private. You can also use an existing repository. Make sure that the repository is empty. + git sync + +2. **Obtain the SSH URL**
+ When a repository is created, GitHub shows a screen with the SSH URL. + git sync + + OR + + If you are using an existing repository, then you can obtain the URL by clicking on the **Code** button. + git sync + + To generate the SSH URL for other git repository manager, such as GitLab and Gitea, follow the **[SSH Configuration](/docs/development-lifecycle/gitsync/ssh-config#generating-ssh-url)** guide. + +3. Go to the **Workspace settings**, and click on the **Configure git** tab.
+ (Example URL - `https://app.corp.com/nexus/workspace-settings/configure-git`) + + GitLab Repo + +4. Enter the **SSH URL** of the repository in the **Git repo URL** field. + +5. Click on the **Generate SSH key** button, and copy the SSH key that is generated. The SSH key is used to authenticate ToolJet with the repository. + + git sync + + There are two types of generated SSH keys: + - **ED25519**: This is a secure and efficient algorithm that is used for generating SSH keys. It is recommended to use this key type. VCS providers like GitHub and GitLab recommend using this key type + - **RSA**: This is an older algorithm that is used for generating SSH keys. It is not recommended to use this key type. Providers like Bitbucket recommend using this key type.

+ + git sync + +6. Go to the **Settings** tab of the GitHub repository, and click on the **Deploy keys** tab. Click on the **Add deploy key** button. + git sync + +7. Enter a title for the SSH key in the **Title** field. + +8. Paste the SSH key generated from the ToolJet. + +9. Make sure that the **Allow write access** checkbox is checked, especially when configuring the git sync feature to [push changes to Git](/docs/development-lifecycle/gitsync/push). However, it is not mandatory to check this option when setting up the git sync feature for [pulling changes from Git](/docs/development-lifecycle/gitsync/pull). + +10. Finally, click on the **Add key** button. + git sync + + To deploy the SSH key for other git repository manager, such as GitLab and Gitea, follow the **[SSH Configuration](/docs/development-lifecycle/gitsync/ssh-config#deploy-the-ssh-key)** guide. + +11. After deploying the SSH Key, go to the **Configure git** tab on ToolJet, and click on the **Finalize setup** button. If the SSH key is configured correctly, you will see a success message. + git sync + +## Configuring GitSync on a Different Branch + +ToolJet git sync allows you to sync your applications with a Git repository to enable version control and team collaboration. By default, git sync operates on the `main` branch, but in multi-environment setups (like staging, production, or feature development), teams often need to sync with custom branches. ToolJet supports this by allowing you to configure a custom Git branch for syncing. + + +You can configure the git sync target branch in two ways: + +### Using the ToolJet UI (Recommended) +ToolJet now supports setting the Git branch directly through the UI when configuring git sync for a workspace. + +- You’ll find an optional Target Branch input while setting up git sync. + +- Simply enter the desired branch name (e.g., develop, release/v1, etc.). + +- If left empty: + + - For new users, the default branch will be **main**. + + - For existing users, the default will be master to maintain backward compatibility. + +This is the preferred way to set the target branch going forward. + + git sync + + + +### Using the Environment Variable +ToolJet also supports configuring the target branch using an environment variable. This is configured at the instance level and applies globally to all workspaces with git sync enabled. The branch specified here must exist in all Git repositories used for git sync across your workspaces. + +To set this, add the following to your .env file:
+`GITSYNC_TARGET_BRANCH` = **branch-name** + +:::note +- Existing git sync users, who want to use a custom Git branch must first create a new custom branch from the master branch in the Git repository manager. +- If both the UI configuration and the environment variable are set, the environment variable (`GITSYNC_TARGET_BRANCH`) will take precedence over the UI setting. +::: diff --git a/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/overview.md b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/overview.md new file mode 100644 index 0000000000..c4cfb16149 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/overview.md @@ -0,0 +1,26 @@ +--- +id: overview +title: GitSync Overview +--- + +
+ Icon + Paid feature +
+ +The GitSync feature in ToolJet allows seamless synchronization of workspace applications with a Git repository which can be used for environment migration, and backup management. It supports both cloud-based and self-hosted Git providers offering flexibility in managing application development and deployment. GitSync can also be configured for a custom branch. Refer to **[Configure GitSync](/docs/development-lifecycle/gitsync/gitsync-config)** guide for more information. + +## Key Use-Cases + +### Application Migration + +GitSync can be used to facilitate the movement of application across different ToolJet instances such as from development to staging to production. Users can effortlessly transfer their applications across instances by pushing changes to a Git repository. This means that once an application is developed in one instance, it can be easily moved to another by simply syncing with the repository, ensuring a smooth transition without the need for manual configurations. Refer to the **[multi-instance](/docs/development-lifecycle/gitsync/gitsync-config)** guide for detailed steps. + +### Backup of Apps + +GitSync provides a straightforward solution for creating backups of your applications. By pushing changes to a Git repository, users can ensure a secure and versioned history of their application. This serves as a reliable backup mechanism, safeguarding against accidental application/version deletion or corruption. Refer to **[GitSync Backup](/docs/development-lifecycle/backup/gitsync-backup)** guide for more information. diff --git a/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/pull.md b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/pull.md new file mode 100644 index 0000000000..ff8e42bd87 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/pull.md @@ -0,0 +1,34 @@ +--- +id: pull +title: Pull Changes from Git Repo +--- + +Once the GitSync is configured and the changes are committed to the git repository, after that the changes can be pulled from the git repository to restore the application or to use multi instance as multi environment. + +## Restore Application + +To restore an application from a git repository, click on the kebab menu (three dots) on the right side of the **Create new app** button on the dashboard. Click on the **Import from git repository** option. + +GitSync + +On clicking the **Import from git repository** option, a modal will open with the dropdown to select the app to be imported from the git repository. Once the app is selected, the app name and the last commit will be displayed. Click on the **Import app** button to import the app from the git repository. + +GitSync + +**Note**: +- The app imported from the git repository cannot be edited. To edit the application, you will need to clone it. +- The app imported from the Git repository should have a unique name. If the app's name is the same as that of an existing app in the workspace, the user will need to either rename the existing app or delete it to successfully import another app with the same name. +- Workspace constants are not synced with the git repository. After pulling the app, if the app throws an error, the user will need to manually add the workspace constants. + +## Pull Changes + +You can check for updates and pull changes from the git repository by following these steps: + +1. Click on the **GitSync** button, a modal will open with the option to **Check for updates**. + +2. Click on the **Check for updates** button to check for updates in the git repository. If there are any updates, you will see the details of the updates such as commit message, author, and the date in the modal. + +3. Click on the **Pull changes** button to pull the changes from the git repository. + + GitSync + diff --git a/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/push.md b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/push.md new file mode 100644 index 0000000000..31d359c11d --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/push.md @@ -0,0 +1,134 @@ +--- +id: push +title: Push Changes to Git Repo +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Once the GitSync feature is configured, you can start pushing changes to the git repository on following points: + +- [App Creation](#app-creation) +- [Manual Commit Using GitSync Button](#manual-commit-using-gitsync-button) +- [Auto Commit on App Rename](#auto-commit-on-app-rename) +- [App Version Update](#app-version-update) +- [Auto Commit on Promoting Environment](#auto-commit-on-promoting-environment) +- [App Deletion](#app-deletion) + +## App Creation + +Whenever you create a new app, you will see an option to select the **Commit changes**. If you select the **commit changes** option, the changes will be committed to the git repository. + +**Note**: If the app name is same as the name of an existing app in the git repo, it will overwrite the existing app in the git repo. + +GitLab SSH Key + +Selecting the **Commit changes** option will create a new commit in the git repository. The commit message will be `App creation` and the author will be the user who created the app. + +During app creation, a **.meta** folder is generated, containing a **meta.json** file with details of the last commit. Then, an app folder is also created, storing **v1.json**, which holds app-specific details of v1 version. + + + + + + GitSync + + + + + + GitSync + + + + + +## Manual Commit Using GitSync Button + +Whenever a user makes a change in an app, they can make a commit to the git repository by following these steps: + +1. After making the changes, click on the **GitSync** button on the topbar. + GitSync Button + +2. On clicking the **GitSync** button, a modal will open with the option to enter the commit message. + GitSync Commit Message + +3. Enter the commit message and click on the **Commit changes** button to commit the changes to the git repository. + +Along with the commit message, the user can also see the connected **Git repo URL** and the last commit details. **Last commit details** helps the user to know the last commit message, author, date, and time. This helps the user to know the last commit details and make the commit message accordingly. + +Once the changes are committed, the user can see the commit message, author, and date in the git repository. + + + + + + GitSync + + + + + + GitSync + + + + + +## Auto Commit on App Rename + +Whenever an app is renamed, the changes will be automatically committed to the git repository. The commit message will be `App is renamed` and the author will be the user who renamed the app. Similarly an auto commit is generated whenever the version is renamed. + + + + + + GitSync + + + + + + GitSync + + + + + +## App Version Update + +Whenever a user creates a new version of an app, there will be an option to select **Commit changes**. If the user selects **commit changes** option, the new version of the app will be committed to the git repository and the old version will be overridden. + +GitLab SSH Key + +The **JSON** file in the app folder will be replaced with the new version of the app, the **meta.json** file in the **.meta** folder gets updated with the new version id and version name. The commit message will be **Version creation** and the author will be the user who created the new version of the app. + + + + + + GitSync + + + + + + GitSync + + + + + +## Auto Commit on Promoting Environment + +When you promote an environment, from **Development to Staging**, the changes will be automatically committed to the git repository. The commit message will be ` Version of promoted from to `. The author will be the user who promoted the environment. When you promote an environment, from **Staging to Production**, no changes will be committed to the git repository. + +GitSync + +This option can be enabled or disabled from the **Configure git** tab on the **Workspace settings** page. By default, this option is disabled. + +GitSync + +## App Deletion + +Whenever a user delete an app from the workspace, the app will not be deleted from the git repository. The app will be available in the git repository in the same state as it was before the app was deleted. diff --git a/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/ssh-config.md b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/ssh-config.md new file mode 100644 index 0000000000..7968b77f3f --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/gitsync/ssh-config.md @@ -0,0 +1,119 @@ +--- +id: ssh-config +title: SSH Configuration for Git Repo Manager +--- + +To configure a Git Manager with ToolJet using GitSync, you need the SSH URL from the Git Manager and then deploy the SSH key generated by ToolJet. You can use any Git Manager (cloud-based or self-hosted) that follows standard Git protocols. In this guide, we will cover the configuration for GitHub, GitLab, and Gitea. + +## Generating SSH URL + +### GitHub + +1. **Create a New Repository**
+ Create a new repository on your GitHub. The repository can be public or private. You can also use an existing repository. Make sure that the repository is empty and the default branch name should be **master**. + GitSync + +2. **Obtain the SSH URL**
+ When a repository is created, GitHub shows a screen with the SSH URL. + GitSync + + OR + + If you are using an existing repository, then you can obtain the URL by clicking on the **Code** button. + GitSync + +### GitLab + +1. **Create a New Repository**
+ Create a new repository on your GitLab. The repository can be public or private. You can also use an existing repository. Make sure that the repository is empty and the default branch name should be **master**. + GitSync + +2. **Obtain the SSH URL**
+ On GitLab, you can obtain the URL by clicking on the **Clone** button and selecting the **SSH** option. + GitSync + +### Gitea + +1. **Create a New Repository**
+ Create a new repository on your Gitea. You can also use an existing repository. Make sure that the repository is empty and the default branch name should be **master**. + GitSync + +2. **Obtain the SSH URL**
+ When a repository is created, Gitea shows a screen with the SSH URL. + GitSync + + +## Deploy the SSH Key + +### GitHub + +1. Go to the **Settings** tab of the GitHub repository, and click on the **Deploy keys** tab. Click on the **Add deploy key** button. + GitSync + +2. Enter a title for the SSH key in the **Title** field. + +3. Paste the SSH key generated from the ToolJet. + +4. Make sure that the **Allow write access** checkbox is checked, especially when configuring the GitSync feature to [push changes to Git](/docs/development-lifecycle/gitsync/push). However, it is not mandatory to check this option when setting up the GitSync feature for [pulling changes from Git](/docs/development-lifecycle/gitsync/pull). + +5. Finally, click on the **Add key** button. + GitSync + +### GitLab + +You have two options for adding the SSH key to GitLab, you can either add it globally to access all your repositories or deploy it for a specific repository. + +#### Option 1: Add as a User-Wide SSH Key + +Use this option for access to all your repositories. + +1. Click on your avatar in the top-left corner and select **Edit Profile**. + +2. Navigate to the **SSH Keys** tab and click the **Add new key** button. + GitLab SSH Key + +3. In the **Key** field, paste the SSH key you generated from the ToolJet. + +4. Give your key a descriptive title. + +5. Set **Usage type** to **Authentication & signing**. + +6. Optionally, set an expiration date. + +7. Click **Add key** to save. + GitLab SSH Key + +#### Option 2: Add as a Deploy Key + +Use this option for access to a specific repository only. + +1. Navigate to the repository you want to add the key to. + +2. Click on the **Settings** tab and select **Repository**. + +3. Once you are in the **Repository Settings**, expand the **Deploy Keys** section. + +4. Click on the **Add new deploy key** button. + +5. Give your key a descriptive title. + +6. In the **Key** field, paste the SSH key you generated in ToolJet's Configure Git tab during the previous step. + +7. Enable the **Grant write permissions to this key** checkbox. We need this permission to push changes to the repository. + +8. Click **Add key** to save. + GitLab Deploy Key + +### Gitea + +1. Go to the **Settings** tab of the Gitea repository, and click on the **Deploy keys** tab. Click on the **Add deploy key** button. + GitSync + +2. Enter a title for the SSH key in the **Title** field. + +3. Paste the SSH key generated from the ToolJet. + +4. Make sure that the **Allow write access** checkbox is checked, especially when configuring the GitSync feature to [push changes to Git](/docs/development-lifecycle/gitsync/push). However, it is not mandatory to check this option when setting up the GitSync feature for [pulling changes from Git](/docs/development-lifecycle/gitsync/pull). + +5. Finally, click on the **Add Deploy key** button. + GitSync diff --git a/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/overview.md b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/overview.md new file mode 100644 index 0000000000..334eda3073 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/overview.md @@ -0,0 +1,27 @@ +--- +id: overview +title: Overview +--- + +This guide outlines the development life cycle for ToolJet deployments, explaining its importance and how ToolJet manages it efficiently. + +A development life cycle (also known as the software development life cycle or SDLC) is a structured framework that ensures software is built, deployed, and maintained efficiently. It helps teams manage changes, collaborate effectively, and maintain stability in production environments. A well-defined development life cycle enhances software quality, improves efficiency, facilitates better collaboration between teams, reduces costs by catching issues early, and ensures long-term maintainability. + +## Development Life Cycle in ToolJet + +ToolJet enables teams to manage application changes and deployments effectively through its Environment and Version Management system. Key aspects of managing the development life cycle in ToolJet include: + +### Release Management + +Using ToolJet's release management, you can create multiple **[versions](/docs/development-lifecycle/release/version-control)** of your application and easily **[release](/docs/development-lifecycle/release/release-rollback)** the latest version with new features, fixes, and enhancements. ToolJet also enables you to **[roll back](#)** to a previous stable version if needed. Additionally, ToolJet lets you **[share your application](/docs/development-lifecycle/release/share-app)** in multiple ways. + +### GitSync + +In ToolJet, you can use **[GitSync](/docs/development-lifecycle/gitsync/overview)** to maintain a history and **[backup](/docs/development-lifecycle/backup/gitsync-backup)** of your application. By integrating with Git repositories, you can ensure that your application remains secure, organized, and easily manageable over time. + +### Environment Management +ToolJet comes with three predefined environments: **development, staging, and production**. These environments apply to applications, data sources, and constants, ensuring controlled testing before deployment.For more details, refer to the [Environments Documentation](/docs/development-lifecycle/environment/self-hosted/multi-environment) + + +### Multi-Instance Environments +You can deploy multiple ToolJet instances where each acts as a different environment. This setup isolates all resources as well as users across the instances. For more details, refer to the [Multi-Instance Environments](/docs/development-lifecycle/environment/self-hosted/multi-instance/instance-as-environment) Documentation. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/release/release-rollback.md b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/release/release-rollback.md new file mode 100644 index 0000000000..02a9d61a9d --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/release/release-rollback.md @@ -0,0 +1,45 @@ +--- +id: release-rollback +title: Release and Rollback +--- + +ToolJet allows you to **[release and share](#release)** your application and **[rollback](#rollback)** to a stable version whenever needed. + +## Release + +Releasing an app in ToolJet makes the selected version available to end users, allowing them to access and use the application for their tasks. This ensures a controlled rollout of features and bug fixes while ensuring that users have access to the latest version of the app. After an application is released it can be accessed in multiple ways, refer to **[Share an Application](/docs/development-lifecycle/release/share-app)** guide for more information. + +### Steps to Release an App + +1. Promote the required version to the **[production environment](/docs/development-lifecycle/environment/self-hosted/multi-environment)**. + +2. Click on the Release button at the top-right corner. + release + +3. A confirmation dialog will popup that prompts you to decide whether to release the current version of the app. Clicking on the **Release** button will release the current version of the app. + release + +## Rollback + +The Rollback feature in ToolJet allows you to revert to a previously stable version of your app whenever needed. Whether fixing bugs, resolving errors, or addressing unexpected issues after a release, rollback ensures minimal disruption to end users. It instantly restores a prior version while keeping the application's URL the same, allowing the team to maintain application stability while debugging the faulty version offline. + +For example, after releasing a new version v1.2.0, users report failures of the form component. Using ToolJet’s version rollback, the team can quickly rollback to the stable version v1.1.0, restoring functionality within minutes. This minimizes downtime, and allows developers to debug the faulty version offline. + +### Steps to Rollback + +1. Go to the **App Version Manager** from the toolbar and click on the dropdown. It will display all the available versions of the app. The released version name will be in green color. + app version + +2. Choose the desired stable version from the dropdown. + +3. Click on the Release button at the top-right corner. + release + +4. A confirmation dialog will popup that prompts you to decide whether to release the current version of the app. Clicking on the **Release** button will release the current version of the app. + release + +## Release Application Permission + +Admin can configure the Release Application permission from the [Permissions](/docs/user-management/role-based-access/user-roles#permissions-for-user-roles) page. This disables the **Release** button for users who do not have the required permission, allowing only authorized roles, such as managers, to release the application. +release + diff --git a/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/release/share-app.md b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/release/share-app.md new file mode 100644 index 0000000000..eefc5d6c1c --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/release/share-app.md @@ -0,0 +1,30 @@ +--- +id: share-app +title: Share Application +--- + +Once the application is released, it can be shared with the end users in multiple ways, including via a direct URL, through the ToolJet dashboard, or by embedding it into another application. + +## Share Application via URL + +Once the application is released, it can be accessed via a URL, and the URL slug can be customized. ToolJet also provides an option to make the application public or private. + +- **Public Application**: Allows anyone on the internet to access the application without signing up for ToolJet. +- **Private Application**: Private applications are restricted to workspace users with the necessary **[access permissions](/docs/user-management/role-based-access/access-control)**. + +The latest released version of the application is always accessible through the same URL, ensuring a consistent access point across updates. + +Share Application Modal + +## Access Application via Dashboard + +Users can launch the released version of the application from the dashboard. The application can also be hidden from the dashboard for end users. Refer to the **[Access Control](/docs/user-management/role-based-access/access-control)** guide for more details. + +Access Application via Dashboard + +## Embed Application + +ToolJet applications can be embedded into other web applications using iframes. To embed an application, make the app public, after which ToolJet will automatically generate an iframe code snippet for integration. + +Embed application using Iframe + diff --git a/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/release/version-control.md b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/release/version-control.md new file mode 100644 index 0000000000..b5c0320ff3 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/development-lifecycle/release/version-control.md @@ -0,0 +1,38 @@ +--- +id: version-control +title: Version Control +--- + +Version Control in ToolJet helps you to maintain multiple versions of the application, do iterative development, and deploy updates systematically. It ensures stability, and allows seamless rollout of new features or fixes. + +For example, to experiment a new feature, you can create a new version of the application and try it out, without disturbing the released application. And after through testing you can release this version. This minimizes downtime, and allows developers to experiment and debug the new feature without disrupting users. + +Each version is isolated from the others and can have different environments, such as development, staging, or production. Check out the **[Multi-Environment](/docs/development-lifecycle/environment/self-hosted/multi-environment)** guide for more information. Versions can also be used to rollback to a stable version if needed, checkout **[release and rollback](/docs/development-lifecycle/release/release-rollback)** guide for more information. + +## Creating a Version + +You can create new versions from App Version Manager in the top. It displays the current version of the app and can be used to switch between the different versions of the app. To create a new version: + +1. Go to the **App Version Manager** from the toolbar and click on the dropdown. It will display all the available versions of the app. The released version name will be in green color. + app version + +2. Click on **Create new version** button at the bottom of the dropdown and a modal will pop-up. + +3. Enter a **Version Name**. + +4. Select the **Create version from** dropdown that will include all the versions of the app, choose a version from the dropdown that you want to use for your new version or ToolJet will automatically select the last created version. + +5. Click on **Create new version** button to add a new version. + modal + +## Renaming a Version + +To change the name of an app version, navigate to the version manager and select the version you wish to rename. From there, you can click on the rename icon located beside the version name. This will open a modal where you can modify the version name to your desired choice. + +version dropdown + +## Deleting a Version + +To remove an app version, go to the version manager and locate the version you wish to delete from the dropdown menu. Next to the version, you will find a delete icon. Click on it to delete the version. Released version cannot be deleted. + +version dropdown diff --git a/docs/versioned_docs/version-3.16.0-LTS/doc-home-page.mdx b/docs/versioned_docs/version-3.16.0-LTS/doc-home-page.mdx new file mode 100644 index 0000000000..3249baccd6 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/doc-home-page.mdx @@ -0,0 +1,343 @@ +--- +description: Home Page +hide_table_of_contents: true +sidebar_label: Home +title: Home +slug: / +--- + +import './homepage.css'; +import { ArrowRight } from 'lucide-react'; +import gettingStartedImage from '../../src/pages/getting-started.png'; +import { + textLabels, + featureCards, + setupCards, + deployOptions, + dataCards, + organizationCards, + releaseCards, + resourceCards, + sectionCards +} from './homePageData'; +import Link from '@docusaurus/Link'; + +{/* // Reusable components */} +export const Card = ({ className = '', href, children }) => { + const cardContent = ( +
+
+
+
+ {children} +
+
+ ); + + return href ? ( + + {cardContent} + + ) : cardContent; +}; + +export const CardHeader = ({ className = '', children }) => ( +
+ {children} +
+); + +export const CardContent = ({ className = '', children }) => ( +
+ {children} +
+); + +export const CardTitle = ({ className = '', children }) => ( +

+ {children} +

+); + +export const Button = ({ + variant = "default", + className = '', + children, +}) => { + const baseStyles = "cursor-pointer inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:opacity-50 disabled:pointer-events-none ring-offset-background"; + const variantStyles = { + default: "bg-primary text-primary-foreground hover:bg-primary/90", + outline: "border border-input hover:bg-accent hover:text-accent-foreground", + secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80", + ghost: "hover:bg-accent hover:text-accent-foreground", + link: "text-primary border-none", + }; + + return ( +
+ +
+ ); +}; + +export const IconCard = ({ icon: Icon, title, content, color, href }) => ( + +
+ +
+ +
+ {title} + + +

{content}

+ +
+ +); + +export const SmallCard = ({ icon: Icon, title, href }) => ( + +
+
+
+ +
+ {title} +
+
+ +); + +export const SectionContainer = ({ title, description, children }) => ( +
+

{title}

+

{description}

+ {children} +
+); + +{/* // Main component */} + +# +
+
+
+
+ + {/* Background shapes */} +
+ {/* Child component 1 */} +
+ {/* Child component 2 */} +
+ {/* Child component 3 */} +
+
+{/* ToolJet Documentation Section */} +
+
+

+ {textLabels.title.prefix} {textLabels.title.highlight} +

+

+ {textLabels.subtitle} +

+
+ +
+ {featureCards.map((card, index) => ( + + ))} +
+ + {/* Getting Started Section */} + +
+ {/* Hover Gradient Overlay */} +
+ + {/* Image Container */} +
+ Getting Started +
+ + {/* Text Container */} +
+

+ {sectionCards.gettingStarted.title} +

+

+ {sectionCards.gettingStarted.description} +

+
+
+ + + +
+
+ +
+ {/* Setup ToolJet Section */} + +
+ {setupCards.map((card, index) => ( + + ))} +
+ + + {/* Deploy on Section */} + +
+ {deployOptions.map((option, index) => ( + + ))} +
+ + + {/* Explore more details link */} +
+ + + +
+ + {/* Bring your data to ToolJet section */} + +
+ {dataCards.map((card, index) => ( + + ))} +
+ + + {/* Manage your organization section */} + + +
+ {organizationCards.map((card, index) => ( + + ))} +
+ + + {/* Manage releases section */} + + +
+ {releaseCards.map((card, index) => ( + + ))} +
+ + + {/* Additional resources section */} + + +
+ {resourceCards.map((card, index) => ( + + ))} +
+ +
+
+
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/getting-started/platform-overview.md b/docs/versioned_docs/version-3.16.0-LTS/getting-started/platform-overview.md new file mode 100644 index 0000000000..8613c4fbd6 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/getting-started/platform-overview.md @@ -0,0 +1,65 @@ +--- +id: platform-overview +title: Platform Overview +--- + +## What is ToolJet? + +ToolJet is a low-code platform that enables developers to rapidly build and deploy custom internal tools. It has a drag-and-drop app builder with 60+ pre-built components, so developers can create complex applications in minutes. ToolJet also connects to most popular data sources and APIs out of the box, and it has a group-based permission system for easy user access management. ToolJet also comes with a lot of other features, but for now, let’s build a basic ToolJet app. + +## How ToolJet Works: + +Platform Overview + +**With ToolJet, you can streamline app development with 4 core steps:**
+ +1. **Design Stunning Interfaces**: Drag and drop UI components like Tables, Charts, Forms, and more build custom applications in minutes. Integrate these components with data sources and incorporate business logic through JavaScript or Python. +2. **Connect Data Sources**: Leverage ToolJet's robust integration features to connect with any data source. The platform supports seamless data integration across over 50 different applications, databases, and APIs. +3. **Automate Complex Workflows**: Develop multi-step workflows in ToolJet to automate business processes. In addition to building and automating workflows, ToolJet allows for easy integration of these workflows within your applications. +4. **Secure and Manage**: Secure your internal tools with detailed permissions settings and audit logs. Maintain quality and consistency with version control, and keep track of performance with comprehensive observability tools. + +Below is a detailed overview of ToolJet's key functionalities, demonstrating how ToolJet helps teams to build more with less effort and greater efficiency. + +### Visual App Builder + +Enables the creation of visually appealing front-ends with a drag-and-drop interface and pre-built components. +App-Builder + +### Integrations + +Offers seamless integration with a wide range of data sources, including over 50 applications, databases, and APIs. +Integrations + +### ToolJet Database + +A robust, scalable database solution built atop PostgreSQL. It allows for no-code database management, enabling users to build, manage, and scale databases effortlessly. +ToolJet Database + +### Workflow Automation + +Simplifies the automation of complex manual business processes, reducing the engineering effort required. + +Workflows + +### Enterprise-Grade Security + +Designed with advanced security features and a scalable infrastructure to meet the needs of enterprise teams. + +Security + +### SSO Support + +Single Sign-On (SSO) capabilities, supporting a variety of providers including Okta, Google, Azure AD, and OpenID Connect. +SSO Support + +### Multiple Environments + +Creation and management of multiple environments for efficient application lifecycle management, allowing different stages like development, testing, and production to be handled seamlessly. +SSO Support + +### Multiplayer Editing + +Multiple users can collaboratively work on app development in real-time. Simultaneous edits and contributions from different team members streamlines the development process and fosters a more dynamic and interactive workspace +Multiplayer Editing + +Whether you're a seasoned developer or a business professional, ToolJet stands out as a comprehensive solution to fast-track your internal tool development process. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/getting-started/quickstart-guide.md b/docs/versioned_docs/version-3.16.0-LTS/getting-started/quickstart-guide.md new file mode 100644 index 0000000000..c420e7005b --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/getting-started/quickstart-guide.md @@ -0,0 +1,155 @@ +--- +id: quickstart-guide +title: Quickstart Guide +--- + + +This quickstart guide walks you through the process of creating an employee directory app using ToolJet. The application lets users track and update employee details while working with core features of the platform, all within a user-friendly interface. Here are the step-by-step instructions: + +**[1. Create Your First Application](#1-create-your-first-application)**
+**[2. Create a Database Table](#2-create-a-database-table)**
+**[3. Create a Query to Fetch Data](#3-create-a-query-to-fetch-data)**
+**[4. Bind Queried Data to the UI](#4-bind-queried-data-to-the-ui)**
+**[5. Create a Query to Add Data](#5-create-a-query-to-add-data)**
+**[6. Use Events to Trigger Queries](#6-use-events-to-trigger-queries)**
+**[7. Preview, Release and Share](#7-preview-release-and-share)**
+ +
+ +### 1. Create Your First Application + +To begin, create a free **[ToolJet](https://www.tooljet.ai/signup)** account and follow the steps below. + +
+ +
+
+ +- Click on the **Create new app** button on the dashboard. Name your application as "Employee Directory". +- Click and drag a **[Table](/docs/widgets/table)** component on the canvas. Optionally, you can also design a header by adding more components. + +
+ +
+ +### 2. Create a Database Table +Now, create a new table in **[ToolJet’s Database](/docs/tooljet-db/tooljet-database/)** to store employee records. + +
+ +
+
+ +- Name the table *employees*, then add the following columns: first_name, last_name, email, phone, department, position, joining, and status. +- Add a few employee records in the database table as placeholder data. + +
+ +
+ +### 3. Create a Query to Fetch Data + +To display employees in the application, you will first have to fetch the data from the database using a query. + +
+ +
+
+ +- Click on the **Add** button in the **[Query Panel](/docs/app-builder/query-panel/)** to create a new query. +- Select **ToolJet Database** as the data source for the query. +- Rename the query to *getEmployees*. +- Choose *employees* as the Table name, and *List rows* as the Operation. +- Click on the **Run** button to fetch data. +- To automatically run the query when the app starts, enable the toggle for *Run this query on application load* from the query setting. + +
+ +
+ +### 4. Bind Queried Data to the UI + +Now, you need to bind the data returned by the *getEmployees* query with the Table created in the first step. + +
+ +
+
+ +- Click on the Table component to open its properties panel. +- Under the Data property, enter the below code: + +```js +{{queries.getEmployees.data}} +``` + +Now the Table component is filled with the data returned by the *getEmployees* query. + +
+ +
+ +### 5. Create a Query to Add Data + +In the bottom-right corner of the Table component, there is a **+(Add new row)** button that opens an auto-generated form to add new data to the Table. Follow the steps below to create an *addEmployees* query and execute it when you click the **Save** button on the auto-generated form. + +
+ +
+
+ +- Click on the **Add** button in the query panel, and select **ToolJet Database** as the data source. +- Select *employees* as the Table name, and Create row as the Operation. +- Rename the query to *addEmployees*. +- Click on **Add Column** to add the required columns. +- Enter the code below for **first_name** and **email** column keys: + +```js +{{components.table1.newRows[0].first_name}} +{{components.table1.newRows[0].email}} +... +``` + +Frame all the remaining keys in the same format. +
+ +
+ +### 6. Use Events to Trigger Queries + +The *addEmployees* query should run when you click the **Save** button on the auto-generated form. The Table component should then reload and display the updated data whenever a new employee is added. Follow the steps below to set up this functionality using events. + +
+ +
+
+ +- Click on the Table component, and click on **New event handler** in the properties panel. +- Choose Add new rows as the Event, Run Query as the Action, and *addEmployees* as the Query. +- In the *addEmployees* query's configuration, under the settings tab, click on **New event handler** to add a new event. +- Select Query Success as the Event, Run Query as the Action, and *getEmployees* as the Query. + +Now, when you click the **+ (Add new row)** button on the Table component, enter the employee details, and click **Save**, the data will be added to the database and automatically reflected in the Table component on the UI. + +
+ +
+ +### 7. Preview, Release, and Share + +The preview, release and share buttons are at the top-right of the App-Builder. + +
+ +
+
+ +- Click on the **Preview** button on the top-right of app builder to review how your application is coming along during development. +- Once the development is done and you are ready to use the application, click on the **Release** button to deploy the app. +- Finally, share your application with your end users using the **Share** button. + +Congratulations on completing the tutorial! You've successfully built an employee directory application and, in the process, learnt the fundamentals of ToolJet. + +
+ + diff --git a/docs/versioned_docs/version-3.16.0-LTS/homePageData.js b/docs/versioned_docs/version-3.16.0-LTS/homePageData.js new file mode 100644 index 0000000000..be2deb2960 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/homePageData.js @@ -0,0 +1,219 @@ +import { + BrainCircuit, Grid3x3, Database, Workflow, Cog, Target, Scale, + Layers, FileSpreadsheet, Folder, Wand2, LayoutDashboard, Users, UserCheck, + Lock, UserPlus, ScrollText, Megaphone, Gem, Mail, GitBranch, + Box, GitMerge, ShoppingBag, Wand, Flag, ShieldCheck, Cloud, Container, Boxes, Server, Telescope, Globe +} from 'lucide-react'; + +export const featureCards = [ + { + icon: BrainCircuit, + title: "Build with AI", + color: "text-blue-500", + content: "Build applications effortlessly using natural language to generate and customize apps.", + href: "/docs/beta/build-with-ai/overview" + }, + { + icon: Grid3x3, + title: "App Builder", + color: "text-blue-500", + content: "Design and create applications with ToolJet's intuitive app builder, featuring a drag-and-drop interface and powerful pre-built components to streamline development.", + href: "/docs/beta/app-builder/overview" + }, + { + icon: Database, + title: "ToolJet Database", + color: "text-blue-500", + content: "Powered by PostgreSQL, offering a user-friendly UI editor. ToolJet Database allows you to manage, edit, and interact with your data directly within the platform.", + href: "/docs/beta/tooljet-db/tooljet-database" + }, + { + icon: Workflow, + title: "Workflows", + color: "text-blue-500", + content: "Automate processes and define workflows with precision, allowing your apps to handle tasks intelligently.", + href: "/docs/beta/workflows/overview" + } +]; + +export const setupCards = [ + { + icon: Cog, + title: "Try ToolJet", + color: "text-blue-500", + content: "Get started with ToolJet in under 2 minutes by running it with Docker. Experience a seamless setup and explore the full capabilities of ToolJet.", + href: "/docs/beta/setup/try-tooljet" + }, + { + icon: Cog, + title: "System Requirements", + color: "text-blue-500", + content: "Ensure your system meets the requirements for running ToolJet. Check hardware and software specifications to get the best performance.", + href: "/docs/beta/setup/system-requirements" + }, + { + icon: Target, + title: "Choose Your ToolJet", + color: "text-blue-500", + content: "Discover the ideal ToolJet version for your development needs. Choose between our LTS versions or explore Pre-Release versions.", + href: "/docs/beta/setup/choose-your-tooljet/" + }, + { + icon: Scale, + title: "Upgrade to LTS", + color: "text-blue-500", + content: "Upgrade to the Long Term Support (LTS) version of ToolJet for extended support, stability, and access to critical updates.", + href: "/docs/beta/setup/upgrade-to-lts" + } +]; + +export const deployOptions = [ + { icon: Cloud, title: "DigitalOcean", href: "/docs/beta/setup/digitalocean" }, + { icon: Container, title: "Docker", href: "/docs/beta/setup/docker" }, + { icon: Server, title: "AWS AMI", href: "/docs/beta/setup/ami" }, + { icon: Server, title: "AWS ECS", href: "/docs/beta/setup/ecs" }, + { icon: Server, title: "Openshift", href: "/docs/beta/setup/openshift" }, + { icon: Telescope, title: "Helm", href: "/docs/beta/setup/helm" }, + { icon: Boxes, title: "Kubernetes", href: "/docs/beta/setup/kubernetes" }, + { icon: Globe, title: "Kubernetes (GKE)", href: "/docs/beta/setup/kubernetes-gke" }, + { icon: Globe, title: "Kubernetes (AKS)", href: "/docs/beta/setup/kubernetes-aks" }, + { icon: Globe, title: "Kubernetes (EKS)", href: "/docs/beta/setup/kubernetes-eks" }, + { icon: Globe, title: "Azure Container Apps", href: "/docs/beta/setup/azure-container" }, + { icon: Globe, title: "Google Cloud Run", href: "/docs/beta/setup/google-cloud-run" }, + + +]; + +export const dataCards = [ + { + icon: Layers, + title: "Overview", + color: "text-blue-500", + content: "Gain a broad understanding on connecting various data sources to ToolJet.", + href: "/docs/beta/data-sources/overview" + }, + { + icon: FileSpreadsheet, + title: "Sample Data Source", + color: "text-blue-500", + content: "Explore sample data sources to quickly integrate with ToolJet. Test features and workflows using predefined datasets.", + href: "/docs/beta/data-sources/sample-data-sources" + }, + { + icon: Folder, + title: "Data Source Library", + color: "text-blue-500", + content: "Browse ToolJet's data source library to connect with databases, APIs, and external services seamlessly.", + href: "/docs/beta/data-sources/overview" + }, + { + icon: Wand2, + title: "Transformation", + color: "text-blue-500", + content: "Leverage ToolJet's transformation capabilities to manipulate and format data from various sources with ease.", + href: "/docs/beta/tutorial/transformations/" + } +]; + +export const organizationCards = [ + { icon: Users, title: "Workspaces", href: "/docs/beta/tj-setup/workspaces" }, + { icon: UserCheck, title: "User authentication", href: "/docs/beta/user-management/authentication/self-hosted/overview" }, + { icon: Lock, title: "Permissions", href: "/docs/beta/user-management/role-based-access/access-control" }, + { icon: UserPlus, title: "Users and groups", href: "/docs/beta/user-management/role-based-access/user-roles" }, + { icon: ScrollText, title: "Audit logs", href: "/docs/beta/security/audit-logs" }, + { icon: Megaphone, title: "White label", href: "/docs/beta/tj-setup/org-branding/white-labeling" }, + { icon: Gem, title: "Super admin", href: "/docs/beta/user-management/role-based-access/super-admin" }, + { icon: Mail, title: "Licensing", href: "/docs/beta/tj-setup/licensing/self-hosted" } +]; + +export const releaseCards = [ + { + icon: GitBranch, + title: "Git Sync", + color: "text-blue-500", + content: "Sync your ToolJet projects with Git repositories, enabling version control and collaboration across teams.", + href: "/docs/beta/development-lifecycle/gitsync/overview" + }, + { + icon: Box, + title: "Multi-Environment", + color: "text-blue-500", + content: "Easily manage and deploy applications across multiple environments, ensuring smooth transitions between development, staging, and production.", + href: "/docs/beta/development-lifecycle/environment/self-hosted/multi-environment" + }, + { + icon: GitMerge, + title: "Versioning and Release", + color: "text-blue-500", + content: "Implement version control and release management to track changes, roll back updates, and maintain stable app deployments.", + href: "/docs/beta/development-lifecycle/release/version-control" + } +]; + +export const resourceCards = [ + { + icon: ShoppingBag, + title: "Marketplace", + color: "text-blue-500", + content: "Discover a variety of plugins, extensions and integrations in ToolJet's marketplace to enhance your app-building experience.", + href: "/docs/beta/marketplace/marketplace-overview" + }, + { + icon: Flag, + title: "Tracking", + color: "text-blue-5000", + content: "ToolJet ensures privacy by acting as a proxy, never storing data, and offers anonymous tracking with feature controls.", + href: "/docs/beta/tracking" + }, + { + icon: ShieldCheck, + title: "Security", + color: "text-blue-500", + content: "ToolJet ensures data security with SOC 2 compliance, encryption, and secure credential handling, never storing your data.", + href: "/docs/beta/security/compliance" + } +]; + +export const textLabels = { + title: { + prefix: "ToolJet", + highlight: "Documentation" + }, + subtitle: "Learn how to get up and running with ToolJet", + gettingStarted: { + title: "Getting Started", + description: "Discover how to create and publish apps within minutes" + }, + setupToolJet: { + title: "Setup ToolJet", + description: "Learn about the different methods you can use to deploy ToolJet" + }, + deployOn: { + title: "Deployment" + }, + exploreMore: "Explore more", + bringData: { + title: "Bring your data to ToolJet", + description: "Learn how to connect your data sources to ToolJet" + }, + manageOrganization: { + title: "Manage your organization", + description: "Learn how to secure your apps and manage user authentication in ToolJet." + }, + manageReleases: { + title: "Manage releases", + description: "Learn how you can efficiently control the release cycle in ToolJet" + }, + additionalResources: { + title: "Additional resources", + description: "Learn more about Marketplace Plugins, ToolJet Copilot, App Performance, and Security." + } +}; + +export const sectionCards = { + gettingStarted: { + title: "Getting Started", + description: "Discover how to create and publish apps within minutes", + link: "/docs/beta/getting-started/quickstart-guide", + } +}; \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/homepage.css b/docs/versioned_docs/version-3.16.0-LTS/homepage.css new file mode 100644 index 0000000000..bd6213e1df --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/homepage.css @@ -0,0 +1,3 @@ +@tailwind base; +@tailwind components; +@tailwind utilities; \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/_category_.json b/docs/versioned_docs/version-3.16.0-LTS/how-to/_category_.json new file mode 100644 index 0000000000..cd5b99d44a --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "How To", + "position": 8, + "collapsed": true +} \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/access-cellvalue-rowdata.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/access-cellvalue-rowdata.md new file mode 100644 index 0000000000..3fa4b31a6f --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/access-cellvalue-rowdata.md @@ -0,0 +1,81 @@ +--- +id: access-cellvalue-rowdata +title: Dynamically Change Cell Colors in Table +--- +
+ +This guide shows how to change the text color and background color of certain cells in a **Table** component based on specific conditions. + +
+ +
+ +## Create a New Application and Set up the Data Source +- Create a new app and add a **[Table](/docs/widgets/table)** component to the canvas. +- Open the Query Panel at the bottom and click on the `+ Add` button. +- Select REST API as your data source - your query will be named as restapi1 by default. +- Choose GET method and enter the below URL: +``` +https://fakestoreapi.com/products +``` +- To view the data that your query will return, click on the **Preview** button. Click on the **Run** button to execute the query and retrieve the data. + +
+ +
+ +## Display Data on the Table + +- Hide the Query Panel and click on the **Table** component to open its properties panel on the right. +- Under Table Data, enter the below code: +``` +{{queries.restapi1.data}} +``` +
+ Table Component With Data +
+ +
+ +
+ +## Change Text Color Based on Cell Value + +- Select the **Table** component and go to Columns. +- For the `category` column, paste the below code under Text Color to dynamically change the text color based on the value of the cell: + +``` +{{cellValue == 'electronics' ? 'red' : 'green'}} +``` + +Now, if the cell value is `electronics`, the text color will be red; otherwise, it will be green. + +
+ Conditional Text Color +
+ +You can use also Hex color codes for more color options. + +
+ +
+ +## Change Text Color Using Row Data + +- Under Cell Background Color for the `title` column, paste the below code: + +``` +{{rowData.price < 100? 'yellow': 'white'}} +``` + +The `rowData` identifier can be utilized to reference values from any column within the **Table** component. + +Now if the value in the price column is lesser than 100, the cell background color will be yellow or else it will be white. + +
+ Conditional Background Color +
+ +You can use the above methods to change the text and background colors of a cell dynamically. + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/access-users-groups.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/access-users-groups.md new file mode 100644 index 0000000000..79e314fcc5 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/access-users-groups.md @@ -0,0 +1,44 @@ +--- +id: access-currentuser +title: Enable/Disable a Component Using Current User's Property +--- +
+ +Let's take a look at the exposed variables of the currentUser property by clicking on the **[inspector](/docs/app-builder/left-sidebar/#inspector)** icon on the left sidebar: + +- **email** : The value can accessed using `{{globals.currentUser.email}}` +- **firstName** : The value can accessed using `{{globals.currentUser.firstName}}` +- **lastName** : The value can accessed using `{{globals.currentUser.lastName}}` +- **groups**: The `groups` attribute is an array representing the groups a user belongs to. By default, every user, including admins, is part of the `all_users` group. Additionally, admins are also part of the `admin` group. To access a specific group name, you need to specify the array index, such as `[0]` for the first group, `[1]` for the second, and so on. For example, you can retrieve the name of the second group a user belongs to with `{{globals.currentUser.groups[1]}}`. +- **metadata** : The value can accessed using `{{globals.currentUser.metadata}}`. + + +
+ +
+ +### Example: Disable a Button if a User is Not Admin + +- Click on the **Button** handle to open its properties. On the **Styles** tab, go to the **Disable** property. + +
+ Properties of button +
+ +- Configure the Disable field with a condition that checks the user's group membership. If the user is not an admin, as determined by the absence of the admin value in the first position (index [1]) of the groups array, the field should be disabled. Use the following JavaScript condition for this purpose: + +```javascript +{{globals.currentUser.groups[1] !== "admin" ? true : false}} +``` + +
+ Disable Property of button +
+ +- Now, when you **release** the app, if the user is not a part of the **admin** group, the button will be disabled. + +
+ Released button disabled when user is not admin +
+ +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/access-users-location.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/access-users-location.md new file mode 100644 index 0000000000..1341dea5ef --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/access-users-location.md @@ -0,0 +1,65 @@ +--- +id: access-users-location +title: Accessing User Location with RunJS Query +--- +
+ +In this step-by-step guide we will build a ToolJet application that harnesses the power of the **JavaScript Geolocation API** to retrieve the user's location. The Geolocation API offers access to various geographical data associated with a user's device, utilizing methods such as GPS, WIFI, IP Geolocation, and more. + +:::info +To uphold user privacy, the Geolocation API requests permission before locating the device. Upon permission, you gain access to data like latitude, longitude, altitude, and speed. +::: + +
+ +1. Begin by creating a new application: +
+ How to: Access User's Location +
+ +2. In the app editor, navigate to the query panel at the bottom and create a **[RunJS query](/docs/data-sources/run-js/#runjs-example-queries)** by selecting **Run JavaScript Code** as the datasource: +
+ How to: Access User's Location +
+ +3. Utilize the following JavaScript code to employ the Geolocation API and retrieve the location: + ```js + function getCoordinates() { // Function to get coordinates + return new Promise(function (resolve, reject) { // Promise to get coordinates + navigator.geolocation.getCurrentPosition(resolve, reject); // Get current position + }); + } + + async function getAddress() { // Function to get address + const position = await getCoordinates(); // Await the coordinates + let latitude = position.coords.latitude; // Get latitude + let longitude = position.coords.longitude; // Get longitude + + return [latitude, longitude]; // Return the coordinates + } + + return await getAddress(); // Return the address + ``` + +4. Scroll down the query editor and from **Settings** enable the `Run this query on application load?` option. This ensures that the JavaScript query runs each time the app is opened, providing the user's location. + +5. Upon clicking **Run**, your browser prompts you to grant permission for the ToolJet app to access your location. Allow this permission to receive location data. +
+ How to: Access User's Location +
+ +7. Once the query is succesfully run, the coordinates will be returned and displayed in the **Preview** section of query editor. To inspect the data returned by the query, go to the **Inspector** on the left sidebar, expand queries -> `runjs1` (query name), and then examine the **data**. You'll find the coordinates. +
+ How to: Access User's Location +
+ +8. Utilize these coordinates in the **map component** to display the location. Add a map component to the canvas and edit its properties. In the **Initial location** property, enter: + ```js + {{ {"lat": queries.runjs1.data[0], "lng": queries.runjs1.data[1]} }} + ``` + +
+ How to: Access User's Location +
+ +9. Once the Map component properties are updated, you'll see the location displayed on the **map component**. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/build-dynamic-forms.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/build-dynamic-forms.md new file mode 100644 index 0000000000..51910866b8 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/build-dynamic-forms.md @@ -0,0 +1,70 @@ +--- +id: build-dynamic-forms +title: Build Dynamic Forms +--- + +This guide walks you through the process of building dynamic, interactive forms in ToolJet through validations. + +
+ +## 1. Creating the UI +Let’s get started by setting up your form’s interface. + +Drag and drop a **Form** component on the canvas and place the following input components inside it. + +| Component | Component Name | Label | +|:------------------|:---------------|:---------------------------------------------------| +| Star Rating | *starrating1* | How satisfied are you with our service? | +| Text Input | *textinput1* | What specific issues did you encounter? | +| Text Input | *textinput2* | Email | +| Number Input | *numberinput1* | Contact | +| Button | *button1* | Submit | + +Dynamic Form UI + +
+ +
+ +## 2. Add Validations and Conditions +Now, let’s add some magic with validations and conditions to make your form smart and responsive. + +a. Select the *textinput1* component and navigate to its Visibility condition. Click on **fx** next to the Visibility condition and enter the below code in the input: + +```javascript +{{components.form1.children.starrating1.value<4}} +``` +*This code will ensure that the *textinput1* component is only visible when the start rating is below 4.* + +b. Select the *textinput2* component and navigate to its Custom Validation property. Click on **fx** and enter the following code to test the email format using regex: +```javascript +{{/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(components.form1.children.textinput2.value) +? '' : 'Invalid email'}} +``` + +c. Select the *numberinput1* component and enable the toggle for Make this field mandatory. This setting will display an error when the *numberinput1* component is left blank. + +d. Finally, the *button1* component has to be disabled if the rating, email, and contact fields are not valid. Use the following code in the component's Visibility condition to achieve that: + +```javascript +{{components.form1.isValid}} +``` +
+ +
+ +## 3. Test the Functionality + +It’s time to put your form to the test! Check that everything functions smoothly and as expected. + +1. Check whether the textinput1 component's visibility is changed based on the rating selected in the Star Rating component. + Dynamic Form UI - Test Star Rating + Dynamic Form UI - Test Star Rating 2 +2. Enter incorrect email and contact details to see whether the related components throw an error while disabling the button. + Dynamic Form UI - Incorrect Email and Contact Test + +
+ +This short guide covers the main validation options that you can use while creating a dynamic form. To explore further, use the Tabs component to create multi-page forms while using the same logic to make it dynamic. + + diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/build-plugin-for-marketplace.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/build-plugin-for-marketplace.md new file mode 100644 index 0000000000..c6e5a7399a --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/build-plugin-for-marketplace.md @@ -0,0 +1,381 @@ +--- +id: build-plugin-for-marketplace +title: Build a new plugin for marketplace +--- + +## Introduction + +ToolJet marketplace is a place where you can find custom plugins and install them in your ToolJet instance. This document will help you to build a new plugin for ToolJet marketplace. + +## Prerequisites +- [Node.js](https://nodejs.org/en/download/) (v18.18.2) +- [npm](https://www.npmjs.com/get-npm) (v9.8.1) + +## Getting started +### 1. Enabling the marketplace for your instance +To enable the marketplace for your instance, you need to set the `ENABLE_MARKETPLACE` environment variable to `true` in your `.env` file. +Marketplace is disabled by default. +Once you set the environment variable, restart your ToolJet instance. You can find the instructions to run ToolJet locally [here](/docs/setup/). +Marketplace can be accessed from '/integrations' route. + +### 2. Installing tooljet-cli +ToolJet marketplace uses [tooljet-cli](https://www.npmjs.com/package/@tooljet/cli) to build and publish plugins. You can install it using npm. +```bash +npm install -g tooljet-cli + +# verify the installation +tooljet --version +``` + +### 3. Creating a new plugin - Github plugin +Let's create a new Github plugin for ToolJet marketplace, which will authenticate a user using Github Personal Access Token and will include basic operations like fetching user details, fetching repositories, fetching issues and fetching pull requests. + +```bash +# create a new plugin +tooljet plugin create github +``` +Provide the plugin name and select the plugin type, which is a `api` in this case. +Select `yes` when asked to create a new plugin for marketplace. + +Provide the repository URL if hosted on GitHub, otherwise leave it blank. + +When you create a plugin using the ToolJet CLI, an object is automatically added to the plugins.json file, which is located in the `ToolJet/server/src/assets/marketplace/` directory. This object contains metadata about the plugin, such as its name, description, version, author, and other details. +This plugins.json file serves as a registry of all the plugins that are available for use in ToolJet. When ToolJet server starts up, it reads this file and loads all the plugins that are listed in it. + +:::note +It's important to note that the plugins.json file should not be manually edited as it is automatically generated by the ToolJet CLI. Any changes made to this file may cause issues with the proper functioning of the plugins in the system. +::: + +All marketplace plugins are stored in the `/marketplace` directory of the ToolJet repository. You can find the Github plugin [here](https://github.com/ToolJet/ToolJet/tree/develop/marketplace/plugins/github). + +The directory structure of a typical ToolJet plugin looks like this: + +```bash +github/ + package.json + lib/ + icon.svg + index.ts + operations.json + manifest.json +``` + +- manifest.json should include information such as the name of plugin, description, etc. +- operations.json should include the metadata of all the operations supported by the plugin. +- index.ts is the main file. It defines a QueryService for the plugin. The QueryService handles running of queries, testing connections, caching connections, etc. +- icon.svg is the icon for the plugin. +- package.json is auto generated by the cli. + + +:::info +**Why do we need a manifest.json file or a operations.json file?** + +The manifest.json files are consumed by a React component to create dynamic UI for connection forms by defining the schema of an API or data source. The schema includes information about the source, such as its name, type, and any exposed variables. It also includes options for authentication and other properties that can be customized by the user. The properties section defines the specific fields and their types that are required for connecting to the API or data source. The React component reads the manifest.json file and generates the necessary UI components based on the schema, allowing users to enter the required information for connecting to the source. This can include text inputs, dropdowns, checkboxes, and other UI elements, depending on the schema defined in the manifest.json file. + +The operations.json file contains a schema definition for a particular data source, for example, Github. It describes the available operations and their parameters that can be used to query the data source. + +A React component uses this schema to create queries in ToolJet applications to generate a UI that allows users to select the desired operation and provide the required parameters. + +The component would use the properties defined in the operations.json file to create various UI elements, such as dropdowns, and input fields, and handle user interactions to create the final query. Once the user has filled in the required parameters, the component would use them to generate a query that can be executed against the data source, and return the results to the user. + +In conclusion, *manifest.json* and *operations.json* files play an important role in creating dynamic UI components in ToolJet applications. These files define the schema for data sources and available operations, which is then consumed by React components to generate the necessary UI elements for users to interact with. By using these files, ToolJet enables users to easily connect to various APIs and data sources, perform queries and retrieve data in a user-friendly way. +::: + + +### 4. Defining the manifest.json file +We need to include the necessary options to construct the connection form. +```json + "properties": { + "credentials": { + "label": "Authentication", + "key": "auth_type", + "type": "dropdown-component-flip", + "description": "Single select dropdown for choosing credentials", + "list": [ + { + "value": "personal_access_token", + "name": "Use Personal Access Token" + } + ] + + }, + "personal_access_token": { + "token": { + "label": "Token", + "key": "personal_token", + "type": "password", + "description": "Enter personal access token", + "hint": "You can generate a personal access token from your Github account settings." + } + } + } +``` +It includes information about authentication options, specifically a dropdown to choose a type of credentials and a field to enter a personal access token. The label, key, type, description, and hint properties are used to define the specific fields and their types required for connecting to the API or data source. + +### 5. Defining the operations.json file +```json + "properties": { + "operation": { + "label": "Operation", + "key": "operation", + "type": "dropdown-component-flip", + "description": "Single select dropdown for operation", + "list": [ + { + "value": "get_user_info", + "name": "Get user info" + }, + { + "value": "get_repo", + "name": "Get repository" + }, + { + "value": "get_repo_issues", + "name": "Get repository issues" + }, + { + "value": "get_repo_pull_requests", + "name": "Get repository pull requests" + } + ] + }, + "get_user_info": { + "username": { + "label": "Username", + "key": "username", + "type": "codehinter", + "lineNumbers": false, + "description": "Enter username", + "width": "320px", + "height": "36px", + "className": "codehinter-plugins", + "placeholder": "Enter username" + } + }, + "get_repo": { + "owner": { + "label": "Owner", + "key": "owner", + "type": "codehinter", + "lineNumbers": false, + "description": "Enter owner name", + "width": "320px", + "height": "36px", + "className": "codehinter-plugins", + "placeholder": "developer" + }, + "repo": { + "label": "Repository", + "key": "repo", + "type": "codehinter", + "lineNumbers": false, + "description": "Enter repository name", + "width": "320px", + "height": "36px", + "className": "codehinter-plugins", + "placeholder": "tooljet" + } + }, + "get_repo_issues": { + "owner": { + "label": "Owner", + "key": "owner", + "type": "codehinter", + "lineNumbers": false, + "description": "Enter owner name", + "width": "320px", + "height": "36px", + "className": "codehinter-plugins", + "placeholder": "developer" + }, + "repo": { + "label": "Repository", + "key": "repo", + "type": "codehinter", + "lineNumbers": false, + "description": "Enter repository name", + "width": "320px", + "height": "36px", + "className": "codehinter-plugins", + "placeholder": "tooljet" + }, + "state": { + "label": "State", + "key": "state", + "className": "codehinter-plugins col-4", + "type": "dropdown", + "description": "Single select dropdown for choosing state", + "list": [ + { + "value": "open", + "name": "Open" + }, + { + "value": "closed", + "name": "Closed" + }, + { + "value": "all", + "name": "All" + } + ] + } + }, + "get_repo_pull_requests": { + "owner": { + "label": "Owner", + "key": "owner", + "type": "codehinter", + "lineNumbers": false, + "description": "Enter owner name", + "width": "320px", + "height": "36px", + "className": "codehinter-plugins", + "placeholder": "developer" + }, + "repo": { + "label": "Repository", + "key": "repo", + "type": "codehinter", + "lineNumbers": false, + "description": "Enter repository name", + "width": "320px", + "height": "36px", + "className": "codehinter-plugins", + "placeholder": "tooljet" + }, + "state": { + "label": "State", + "key": "state", + "type": "dropdown", + "className": "codehinter-plugins col-4", + "description": "Single select dropdown for choosing state", + "list": [ + { + "value": "open", + "name": "Open" + }, + { + "value": "closed", + "name": "Closed" + }, + { + "value": "all", + "name": "All" + } + ] + } + } + } +``` +The operations.json file defines the operations that can be performed on the data source. It includes information about the operation type, the fields required to perform the operation, and the type of each field. The label, key, type, description, and hint properties are used to define the specific fields and their types required for connecting to the API or data source. + +### 6. Add the npm package of GitHub to the plugin dependencies + +```bash +# change directory to the plugin directory and install the npm package +cd plugins/github +npm i octokit --workspace=@tooljet-marketplace/github +``` + +:::info +Steps to install npm package to a plugin + +```bash +npm i --workspace= +``` + +The command `npm i --workspace=` is used to install a specific npm package into a particular workspace of a multi-package repository. + +The *--workspace* flag is used to specify the workspace where the package should be installed. In this case, we are installing the package in the *@tooljet-marketplace/github* workspace. +::: + +### 7. Implement the query execution logic in index.ts +The QueryService for the Github plugin handles the logic for running queries in index.ts. The QueryService receives the metadata of the data source, including the credentials and configurations for connecting and parameters for the query that was run. + +For the Github datasource, the sourceOptions will include the credentials required for authentication, such as the personal access token. The queryOptions will have the configurations and parameters for the specific query, including the operation to be performed, such as getting the list of repositories for a specific user. + +The QueryService will use this information to create and execute the necessary API requests against the Github API. The resulting data will be returned to the caller, which can then be further processed as required. + + +Create a new file query_operations.ts in the plugins/github/src directory and add the following code to it. +```typescript +import { Octokit } from 'octokit' +import { QueryOptions } from './types' + + +export async function getUserInfo(octokit: Octokit, options: QueryOptions): Promise { + const { data } = await octokit.request( + 'GET /users/{username}', + { + username: options.username + } + ); + return data; +} + +export async function getRepo(octokit: Octokit, options: QueryOptions): Promise { + const { data } = await octokit.request( + 'GET /repos/{owner}/{repo}', + { + owner: options.owner, + repo: options.repo + } + ); + return data; +} + +export async function getRepoIssues(octokit: Octokit, options: QueryOptions): Promise { + const { data } = await octokit.request( + 'GET /repos/{owner}/{repo}/issues', + { + owner: options.owner, + repo: options.repo, + state: options.state || 'all' + + } + ); + return data; +} + +export async function getRepoPullRequests(octokit: Octokit, options: QueryOptions): Promise { + const { data } = await octokit.request( + 'GET /repos/{owner}/{repo}/pulls', + { + owner: options.owner, + repo: options.repo, + state: options.state || 'all' + } + ); + return data; +} + +``` + +The query_operations.ts file contains the functions that will be used to execute the queries. The functions will be called by the QueryService in index.ts. + +The Github class has three methods: +- run: This method is called when a query needs to be executed. It takes in *sourceOptions* and *queryOptions* as input, which represent the source metadata and the query configuration, respectively. The run method uses the octokit library to make API requests to the GitHub API and returns the result of the query in a QueryResult object. + +- testConnection: When a new data source is being added to a ToolJet application, the connection can be tested. +This method is called when a connection needs to be tested. It takes in sourceOptions as input, which represents the source metadata. The testConnection method tests the connection by attempting to get the authenticated user and returns a ConnectionTestResult object that indicates whether the connection was successful or not. + +:::note +Every data source might not have a way to test connection. If not applicable for your data source, you can disable the test connection feature by adding "customTesting": true, to the manifest.json of your plugin. +:: + +- getConnection: This method is a helper method that returns an authenticated octokit client that is used to make requests to the GitHub API. It takes in sourceOptions as input, which represents the source metadata, and returns an authenticated octokit client. + + + + + + + + + + + + + + diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/bulk-update-multiple-rows-in-table.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/bulk-update-multiple-rows-in-table.md new file mode 100644 index 0000000000..53df502a00 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/bulk-update-multiple-rows-in-table.md @@ -0,0 +1,150 @@ +--- +id: bulk-update-multiple-rows +title: Bulk Update Multiple Rows in Table +--- +
+For the purpose of this guide, it's presumed that you've already established a successful connection to your data source. We'll use PostgreSQL for this example, but you can adjust the queries based on the SQL database that you are using. + +
+ +
+ +## 1. Create a Query to Get the Data + +- Create a PostgreSQL query in SQL mode, rename it to *users* and enter the below code. + +```sql +SELECT * FROM // *replace
with your table name* +``` +- Enable the `Run the query on application load?` option to execute the query automatically when the application starts. +- Click on the **Run** button to fetch the data from the database. + +
+ Fetch the Data +
+ + + +
+ +## 2. Display the Data on the Table + +- Drag and drop a **Table** component onto the canvas from the components library on the right. +- Click on the Table component to open its properties on the right sidebar. +- To populate the Table with the data returned by the query, add the below code under the `Data` field of the Table: +```js +{{queries.users.data}} +``` + +
+ Display Data on the Table +
+ +
+ +
+ +## 3. Make the Columns Editable + +- Under the Columns accordion, click on the column name that you want to make editable. +- On clicking the column name, a new section will open. Enable the toggle for `Make editable` to make the column editable. + +
+ Make Column Editable +
+ +
+ +
+ +## 4. Enable Multiple Row Selection + +- Under the Row Selection accordion, enable the `Allow Selection`, `Highlight Selected Row`, and `Bulk Selection` option. + +
+ Multiple Row Selection +
+ +
+ +
+ +## 5. Create a Custom JS query + +- Create a new Run Javascript query and use the code below to generate the SQL query for updating multiple rows. The query will be named as *runjs1* by default. + +```js +const uniqueIdentifier = "id" +const cols = Object.values(components.table1.changeSet).map((col, index) => { + return { + col: Object.keys(col), + [uniqueIdentifier]: Object.values(components.table1.dataUpdates)[index][uniqueIdentifier], + values: Object.values(col), + }; +}); + +const sql = cols.map((column) => { + const { col, id, values } = column; + const cols = col.map((col, index) => `${col} = '${values[index]}'`); + return `UPDATE users SET ${cols.join(", ")} WHERE id = '${id}';`; +}); + +return sql +``` + +Here the unique identifier is **id** and Table component's name is **table1**. You can update the unique identifier if you are using a different column as a unique identifier. You can also update the Table name if you have renamed it, the default name is *table1*. + +
+ RunJS code to later the data +
+ +
+ +
+ +## 6. Create an Update Query + +- Create a PostgreSQL query in SQL mode and rename it to *update*: + +```sql +{{queries.runjs1.data.join(' ')}} +``` + +- This query will run the SQL query generated by the *runjs1* query. + +
+ Bulk Update Rows +
+ +
+ +
+ +## 7. Adding Event Handlers to Execute Queries in Sequence + +- Edit the Table component and add an event handler for `Save Changes` event so that whenever a user will edit the Table and hit the Save Changes button the *runjs1* query will run. +- Optionally, add loading state to the Table by clicking on `fx` next to the `Loading state` property. +- Use the below code to show the loading state whenever a query is getting executed. +```js +{{queries.users.isLoading || queries.update.isLoading}} +``` + +
+ Adding Events +
+ +- Now, go to the *runjs1* query and add an event to run the *update* query for Query Success event. This will run the *update* query after the *runjs1* query is successfully executed. + +
+ Query Success +
+ +The data needs to reload once the *update* query runs since we want the Table component to be populated with the updated data. + +- Add a new event handler in the *update* query. +- Select Query Success as the Event and Run Query as the Action. +- Select *users* as Query. + +This will refresh the table whenever the *update* query will be run. + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/conditionally-display-components.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/conditionally-display-components.md new file mode 100644 index 0000000000..3067fa9b25 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/conditionally-display-components.md @@ -0,0 +1,44 @@ +--- +id: conditionally-display-components +title: Conditionally Display Components Using fx and Groups +--- + + +In this guide, you'll see how you can utilize groups to conditionally display components. This can be handy when two or more groups have access to the same app and you want to conditionally display components based on the group. + +Here's a basic application with some components. + +
+ Initial UI without any conditions +
+ +In this app, the `Approve Selected` button should only display if someone from the **Manager** group is accessing the application. + +- To implement this, select the button component and navigate to its `Visibility` property. +- Click on the **fx** button next to `Visibility` and enter the below code in the input: + +```js +{{globals.currentUser.groups.includes('Manager')}} +``` +
+ Visibility Code on Button Component +
+ +- Now if you check the UI, you won't see the **Button** component unless you are a part of the `Managers` group. + +- Here's what the users who are not in the `Managers` group can see: + +
+ Non Manager View +
+ +- Here's what the users in the `Managers` group can see: + +
+ Manager View +
+ +This was a basic implementation of how you can control the visibility of components using **fx** and **Groups** in ToolJet. + +Feel free to implement the same logic for more advanced use cases. For instance, for conditionally displaying a section or a group of components, you can place all the relevant components inside a **Container** component and apply the same logic. + diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/conditionally-format-table.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/conditionally-format-table.md new file mode 100644 index 0000000000..77e2603c7c --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/conditionally-format-table.md @@ -0,0 +1,160 @@ +--- +id: conditionally-format-table +title: Conditional Formatting in Table +--- +
+ +Conditional formatting enhances the visual representation of data by allowing you to dynamically adjust the appearance of cells in **Table** component based on specific conditions. This how-to guide will guide you through the process of implementing advanced conditional formatting for text color and background color in a Table component. + +
+ +
+ +## Create a New Application and Set Up Data Source + +- Create a new application and add a Table component to the canvas. + +- Open the Query Panel at the bottom and click on the **+ Add** button. + +- Choose **REST API** as your data source and set the method to GET. + +- Enter the following URL as REST API endpoint: +```bash title="REST API Endpoint" +https://fakestoreapi.com/products +``` + +- Click on the **Preview** button to view the data. Execute the query by clicking on the **Run** button. + +
+ Table Component With Data +
+ +
+ +
+ +## Display Data on the Table + +- Hide the Query Panel and click on the Table component to open its properties panel. + +- Under the `Data` property, enter the following code: +```js title="Data" +{{queries.restapi1.data}} +``` + +
+ Table Component With Data +
+ +
+ +
+ +## Enabling Conditional Formatting + +- Go to the `Columns` property of the Table component. + +- Select the column for which you want to enable conditional formatting (e.g., category). + +- If the column type is set to `Default` or `String`, you can set the conditional formatting for `Text color` and `Cell background color`. + +**Note**: Only `cellValue` and `rowData` can be used as identifiers for conditional formatting. + +
+ Table Component With Data +
+ +
+ +
+ +## Conditional Formatting using Cell Value + +
+ +### Example 1: Changing Text Color Based on Cell Value + +- Select the `Rate` column which has a column type of `Default`/`String`. This column contains the rating of each product on a scale of 1 to 5. + +- Under the `Text color` property, enter the following condition: + +```js +{{cellValue < 2 ? 'red' : cellValue > 2 && cellValue < 3 ? 'Orange' : 'green'}} +``` + +The above condition will change the text color to red if the cell value is less than 2, orange if the cell value is greater than 2 and less than 3, and green if the cell value is greater than 3. + +
+ Table Component With Data +
+ +
+ +
+ +### Example 2: Changing Cell Background Color Based on Cell Value + +- Select the `Rate` column, enter the following condition under the `Cell background color` property: + +```js +{{cellValue >= 4 ? 'lightgreen' : cellValue >= 3 ? 'lightyellow' : 'lightcoral'}} +``` + +The above condition will change the cell background color to lightgreen if the cell value is greater than or equal to 4, lightyellow if the cell value is greater than or equal to 3, and lightcoral if the cell value is less than 3. + +
+ Table Component With Data +
+ +
+ +
+ +
+ +## Conditional Formatting using Row Data + +
+ +### Example 1: Changing Text Color Based on Row Data + +- Select the `Title` column, enter the following condition under the `Text color` property: + +```js +{{rowData.price > 50 ? '#D9534F' : (rowData.rating.rate >= 4 ? '#5CB85C' : rowData.rating.rate >= 3 ? '#F0AD4E' : '#D9534F' )}} +``` + +The above condition will change the text color of the `Title` based on the value of the `price` and `rating` columns. If the value in the `price` column is greater than 50, the text color will be red. If the value in the `rating` column is greater than or equal to 4, the text color will be green. If the value in the `rating` column is greater than or equal to 3, the text color will be yellow. Otherwise, the text color will be red. + +
+ Table Component With Data +
+ +
+ +
+ +### Example 2: Changing Cell Background Color based on Row Data + +- In this example, we will change the cell background color of the `Title` column based on the category of the product. + +- Select the `Title` column, enter the following condition under the `Cell background color` property: + +```js +{{rowData.category === "electronics" ? 'cyan' : rowData.category === "jewelery" ? 'pink' : 'lightgray'}} +``` + +The above condition will change the cell background color of the `Title` column based on the value of the `category` column. If the value in the `category` column is `electronics`, the cell background color will be cyan. If the value in the `category` column is `jewelery`, the cell background color will be pink. Otherwise, the cell background color will be lightgray. + +
+ Table Component With Data +
+ +
+ +
+ +--- + +By following these steps, you can implement advanced conditional formatting for `Text color` and `Cell background color` in your Table component. Experiment with different conditions and color combinations to create visually appealing and informative tables in your applications. + diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/delete-multiple-rows-table.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/delete-multiple-rows-table.md new file mode 100644 index 0000000000..035c13aa8d --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/delete-multiple-rows-table.md @@ -0,0 +1,148 @@ +--- +id: delete-multiple-rows +title: Delete Multiple Rows in a Table +--- +
+ +This guide explains how to delete multiple rows from a table, assuming you've already connected to a data source. We'll use PostgreSQL for this example, but you can adjust the queries based on the SQL database that you are using. + +
+ +
+ +## 1. Create a Query to Fetch the Data from the Database + +- Create a new query and name it *getRecords*. +- Select SQL mode and enter the following query: + +```sql +SELECT * FROM tooljet // replace tooljet with your table name +``` + +- Enable the `Run the query on application load?` option to execute the query automatically when the application starts. + +
+ How-to: Delete Multiple Rows in Table +
+ +
+ +
+ +## 2. Populating the Table with Data + +- Drag and drop a **Table** component on the canvas. +- In Table properties, go to the `Data` property and set the value to `{{queries.getRecords.data}}`. +- Now if you run the *getRecords* query, the returned data will be loaded in the Table component. + +
+ How-to: Delete multiple rows in table +
+ +
+ +
+ +## 3. Enable Bulk Row Selection on Table + +- Go to the Table properties and enable the `Bulk selection` option. +- Enabling this option will allow you to select multiple rows on the table. + +
+ How-to: Delete multiple rows in table +
+ +
+ +
+ +## 4. Create a Custom JavaScript Query + +- Create a new Run Javascript code query. It will be named *runjs1* by default. +- Enter the following code: + +```js +const uniqueIdentifier = "id"; + +const idsToDelete = Object.values(components.table1.selectedRows).map(dataUpdate => dataUpdate[uniqueIdentifier]); + +const idsString = idsToDelete.map(id => `'${id}'`).join(', '); + +const SQL = `DELETE FROM tooljet WHERE ${uniqueIdentifier} IN (${idsString});`; + +return SQL; +``` + +The above code generates a SQL query that deletes rows from the database table where the `id` field matches the selected IDs in ToolJet's Table component. + +- Click on the **Preview** button to see the SQL statement generated by the query. + +
+ How-to: Delete multiple rows in table +
+ +*If you're using a different column as the unique identifier, feel free to update the code accordingly. You can also update the Table name if you have renamed it, the default name is *table1*.* + +- Select a few rows on the Table component and then Preview the SQL query generated by the *runjs1* query. + +
+ How-to: Delete multiple rows in table +
+ +
+ +
+ +## 5. Create a New Query to Delete the Rows + +- Create a new query, name it `delete`, and select SQL mode. +- Enter the following code: +```sql +{{queries.runjs1.data}} +``` + +In this query, we are dynamically loading the SQL statement generated by the JavaScript query. + +
+ How-to: Delete multiple rows in table +
+ +
+ +
+ +## 6. Add a Button to Delete the Selected Rows + +- Drag and drop a **Button** component on the canvas. +- Edit its properties and set the `Button text` property to "Delete selected". +- Add a new **Event** to the button. +- Select On click as the Event, Run Query as the Action, and *runjs1* as the Query. + +
+ How-to: Delete multiple rows in table +
+ +- Optionally, we can add a loading state to the Button whenever the *delete* or *getRecords* query is running: +```js +{{queries.delete.isLoading || queries.getRecords.isLoading}} +``` + +- Add a new **Event** to the *runjs1* query. +- Select Query Success as the Event, Run Query as the Action and *delete* as the Query. + +
+ How-to: Delete multiple rows in table +
+ +Now, whenever you click on the Button component, the *runjs1* query will run and generate a delete SQL statement with selected rows on the table. Once the *runjs1* query executes, the *delete* query will execute and delete the rows from the database. + +- Add a new **Event** to the *delete* query. +- Select Query Success as the Event, Run Query as the Action and *getRecords* as the Query. + +
+ How-to: Delete multiple rows in table +
+ +By implementing this, we are ensuring that every time rows are deleted, the Table component will automatically refresh to display the most recent data fetched from the database. + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/display-listview-record-new-page.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/display-listview-record-new-page.md new file mode 100644 index 0000000000..55f9b3a656 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/display-listview-record-new-page.md @@ -0,0 +1,61 @@ +--- +id: display-listview-record-on-new-page +title: Display Listview Record Details on a New Page +--- + +This guide explains how to display details of a selected record from a **Listview** component on a different page in ToolJet. + +
+ +## Build the App + +1. Drag a **Listview** component and setup other required components. +Build the app +2. Add another page in the application. +Add a new page +3. Setup the second page with required fields and components. +Setup the second page + +
+ +
+ +## Setting up Event Handlers + +Add a new event handler to the **Listview** component with the following configurations: +- Event: **Record Clicked** +- Action: **Set variable** +- Key: **selectedEmp** *(Enter your desired variable name.)* +- Value: + ```json + {{[{ + name: components.listview1.selectedRecord.text17.text, + designation: components.listview1.selectedRecord.text15.text, + department: components.listview1.selectedRecord.text14.text + }]}} + ``` + +This event will save the record value in the specified variable, which can be accessed on another page. + +Add event handler to set variables + +Create one more event and configure it with the following settings to switch the page when a record is clicked: + - Event: **Record Clicked** + - Action: **Switch page** + - Page: **Employee Details** *(Select your desired page from the dropdown.)* + +This event will switch the page whenever a record is clicked. + +Add event handler to switch page + +
+ +
+ +## Displaying Info on Another Page + +Now, you can reference the values stored in the variables from the previous page. For instance, you can set the default value of the **Text input** component using `{{variables.selectedEmp[0].name}}`. + +Display data on the new page + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/intentionally-fail-js-query.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/intentionally-fail-js-query.md new file mode 100644 index 0000000000..3111d09689 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/intentionally-fail-js-query.md @@ -0,0 +1,40 @@ +--- +id: intentionally-fail-js-query +title: Intentionally Throwing an Error in RunJS for Debugging +--- +
+ +In this step-by-step guide, we'll walk you through the process of creating a RunJS query that intentionally throws an error for debugging purposes. + +
+ +
+ +### Creating the Error-Throwing RunJS Query + +1. Create a new RunJS query by clicking the `+ Add` button on the query panel. + +2. Paste the following code into the RunJS query editor. This code utilizes the `ReferenceError` constructor to intentionally generate an error. + ```js + throw new ReferenceError('This is a reference error.'); + ``` + +
+ +
+ +### Adding an Event Handler for Failure + +3. Now, enhance the query by adding an event handler that will display an alert when the query fails. + +4. Click the "Run" button to execute the query and observe the intentional error being thrown. + +Refer to the screencast below: + +
+ reate a new RunJS query +
+ +
+ +By following these steps, you can effectively simulate errors in your RunJS queries, aiding in the debugging process and improving the overall robustness of your code. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/loading-image-pdf-from-db.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/loading-image-pdf-from-db.md new file mode 100644 index 0000000000..abca94f56b --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/loading-image-pdf-from-db.md @@ -0,0 +1,128 @@ +--- +id: loading-image-pdf-from-db +title: Upload And View Images and PDFs Using Base64 String +--- +
+ +This guide shows how to upload and view images and PDFs using the base64 string format. + +
+ +
+ +## 1. Start by Creating a New Table In ToolJet Database + +- Create a new table named *testDB*. +- The `id` field will be present by default to create a unique identifier for each record in our database table. +- Click on **Add more columns** button and add two more columns: `pdf` and `image`. +- Select `varchar` as datatype for the pdf and image columns. + +While we are using the ToolJet Database for this guide; feel free to use other databases while applying the same principles. + +
+New Table +
+ +
+ +
+ +## 2. Upload Files To The Database + +- Create a new application and name it *Load PDF And Images Example*. +- Drag and drop two **[Filepicker](/docs/widgets/file-picker)** components on the canvas from the components library on the right. +- Rename the first Filepicker component to *imagePicker* and second Filepicker to *pdfPicker*. + +
+ Rename Filepickers +
+ +- For *pdfPicker*, change the **Accept file types** property to `{{"pdf/*"}}` - this ensures that the Filepicker only accepts PDF files. + +
+ Accepted File Type Settings +
+ +- Retain the default `{{"image/*"}}` setting for the Accept file types property in the *imagePicker* component, as it's intended for image uploads. +- Click on the *imagePicker* component and select an image to upload. Similarly, upload a PDF using the *pdfPicker* component. + +
+ Uploaded Files +
+ +- After uploading, you will see the filenames displayed on their respective Filepicker components. +- Click on the **+ Add** button in the query panel to create a new query, choose ToolJet Database as the data source, select `testDB` as Table name, and `Create Row` as Operations. Name this query *uploadFiles*. +- Under the Columns section, add two columns - `pdf` and `image`. +- Set the below value for the `pdf` column: +```js +{{components.pdfPicker.file[0].base64Data}} +``` +- Similarly, for the `image` column: +```js +{{components.imagePicker.file[0].base64Data}} +``` + +In the above query, we are using the exposed variables of both Filepicker components to get the base64 strings of the files we had uploaded earlier. + +
+ Add Files Query +
+ +- Add a **[Button](/docs/widgets/button)** component below the Filepickers and rename it to *upload*. +- Set the Button's text to *Upload* and create a **New event handler** with the following settings: Event - `On click`, Action - `Run Query` and Query - `uploadFiles`. +- Click on the *upload* button to upload the files that we had selected in the Filepicker components earlier. + +
+ Upload Button Properties +
+ +The upload process is now complete. Whenever files are selected in the Filepicker components and the *upload* button is clicked, the base64 strings of these files will be automatically written to the database. + +
+ +
+ +## 3. View Image and PDF Files + +- Create a query named *getFiles* to retrieve base64 strings from testDB: Click on **+ Add** button in the query panel, select ToolJet as Database, `testDB` as Table name, and `List rows` as Operations. +- Enable **Run this query on application load?** and click on the **Run** button to run the getFiles query. + +
+ Fetch Files Query +
+ +- Drag an **[Image](/docs/widgets/image)** and a **[PDF](/docs/widgets/pdf)** component on the canvas from the components library. Rename the **Image** component to *displayImage* and the **PDF** component to *displayPDF*. +- In the **URL** property of the **displayImage** component, enter: +```js +{{'data:image;base64,' + queries.getFiles.data[0].image}} +``` + +- Let's apply the same logic for the **displayPDF** component and enter the below value in the **File URL** property: + +```js +{{'data:pdf;base64,' + queries.getFiles.data[0].pdf}} +``` +
+ PDF Component With File URL +
+ +The provided code constructs a Data URL to display the base64-encoded data as an image or PDF. + +
+
+ +Here's what our final interface will look like: + +
+ Final Preview +
+ + +You can also use transformations in the query response and concat `data:image/jpeg;base64,` to the base64 data. + +
+
+ +Using the above logic, you can upload and view files in ToolJet using the base64 data. + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/pass-query-params-in-custom-components.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/pass-query-params-in-custom-components.md new file mode 100644 index 0000000000..049830eca8 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/pass-query-params-in-custom-components.md @@ -0,0 +1,97 @@ +--- +id: pass-query-params-in-custom-components +title: Pass Query Parameters in Custom Components +--- + +In this guide, you'll learn how to trigger a query with parameters inside a Custom Component. + +- To begin, create a **REST API** query with an `id` parameter, and rename it to *getIndividualTodo*. + +- Select `GET` as the operation and enter the URL below under the `URL` property: + +```javascript +https://jsonplaceholder.typicode.com/todos/{{parameters.id}} +``` + +
+ Table Component With Data +
+ +- Next, drag and drop a **Custom Component** on the canvas. Enter the code below under its `Data` property: + +```javascript +{{ + { title: 'Todos', buttonText: 'Get Todo', queryData: queries.getIndividualTodo.data} +}} +``` + +Here, the title for the component, button text, and query data are being passed inside the Custom Component. + +- Enter the code below under the `Code` property: + +```javascript +import React, { useState, useEffect } from 'https://cdn.skypack.dev/react'; +import ReactDOM from 'https://cdn.skypack.dev/react-dom'; +import { Button, Container, TextField, Typography } from 'https://cdn.skypack.dev/@material-ui/core'; + +const MyCustomComponent = ({ data, updateData, runQuery }) => { + const [todoId, setTodoId] = useState(1); + + const fetchTodo = async () => { + try { + const { data: todo } = await runQuery('getIndividualTodo', { id: todoId }); + if (todo) updateData({ ...data, queryData: todo }); + } catch (error) { + console.error("Error fetching todo:", error); + } + }; + + return ( + + {data.title} + setTodoId(e.target.value)} + variant="outlined" + margin="normal" + fullWidth + /> + + {data.queryData?.title && ( +
+

ID: {data.queryData.id}

+

Title: {data.queryData.title}

+

Completed: {data.queryData.completed ? "Yes" : "No"}

+
+ )} + + ); +}; + +const ConnectedComponent = Tooljet.connectComponent(MyCustomComponent); + +ReactDOM.render(, document.body); +``` + +In the `runQuery('getIndividualTodo', { id: todoId })` function, the parameter is passed by including `id: todoId` as an argument in the query call, which specifies the unique identifier for the todo item being requested. + +
+ Custom Component +
+ + +- Now, when you click the **Fetch Todo** button, the *getIndividualTodo* query will run with the Todo ID passed as a parameter and return the details of the Todo + +
+ Custom Component With Todos Fetched +
+ + +Note: In a typical JavaScript query, parameters are passed in a manner similar to a standard function call. For example, you can specify the parameters for the query using `queries.getIndividualTodo.run({ id: 2 })`. + + + + diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/pass-values-in-rest-api.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/pass-values-in-rest-api.md new file mode 100644 index 0000000000..a371f9b3cd --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/pass-values-in-rest-api.md @@ -0,0 +1,55 @@ +--- +id: pass-values-in-rest-api +title: Pass Values in a REST API Query +--- + +This guide gives you an overview of how you can pass values in a REST API Query using raw JSON and key-value pairs. + +
+ +## Raw JSON + +In the following JSON code, the `${}` syntax is used for JavaScript string interpolation within template literals (also called template strings). This allows dynamic values from JavaScript variables or expressions to be injected directly into the string. + +```javascript +{{ + `{ + "contents": [{ + "parts": [{ + "text": "Generate the following content for this image in markdown format: + content type: ${components.typeOfContentInput.value}, + additional info: ${components.additionalInfoInput.value}" + }, + { + "inline_data": { + "mime_type":"image/jpeg", + "data": "${components.imageUploader.file[0].base64Data}" + } + },], + },], + }` + }} +``` + +
+ Passing Values Using Raw JSON +
+ +
+ +
+ +## Entering Key Value Pairs + +In this example, simple key-value pairs are entered in the provided input fields. Here, the values can simply be passed using double curly braces as is typically done in ToolJet. Take note of the status key. A string is combined with another value that is referred using double curly braces. + +
+ Passing Values Using The Key Value Inputs +
+ +
+ +To see REST API queries in action, check out the following tutorials: + +1. **[Gemini AI Content Generator](https://blog.tooljet.ai/build-an-ai-content-generator-using-gemini-api-and-tooljet-in-10-minutes/)** +2. **[Open AI Audio Transcriber](https://blog.tooljet.ai/building-an-audio-transcriber-and-analyzer-using-tooljet-and-openai/)** \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/print-multitabs.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/print-multitabs.md new file mode 100644 index 0000000000..2c5460a252 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/print-multitabs.md @@ -0,0 +1,245 @@ +--- +id: print-multi-tabs-report +title: Print Data from Multiple Tabs +--- +
+ +In this guide, we will implement printing data from multiple tabs in ToolJet. This will be useful when printing an invoice or a report from your ToolJet application. For example, a ToolJet app that has a set of tabs for each invoice, and you want to print all the tabs in one go. + + +
+ +
+ +## UI of the App + +On the ToolJet homepage, click on the ellipses on the `Create new app` button. Choose an app with a set of tabs for each record. Each tab will have a set of fields to display. For this guide, we will be using the **Lead Management System** app. + +In the example below, we have the **Tabs** component and each tab has a set of fields to display the record details. + +- **Tabs**: Each tab represents different type of lead record. For this app, we have 4 tabs. Each tab has an id starting from 0 to 4. + +- **Button**: The **Create Lead** button is the deafult button. For this guide, we will also add another button named **Download PDF**, that will print the data from all the tabs. The button will have two events, the details for which we will share later in this guide. + +
+ Print data from multiple tabs +
+ +
+ +
+ +## Load Data from Database + +- To load the data from the database, we will use the **lead_management_system** table. +- In the *fetchLeads* query, choose `lead_management_system` in `Table name` parameter. +- Choose `List rows` in the `Operations` parameter. +- Click on the **Run** button in the query panel to load the data. + +
+ Print data from multiple tabs +
+ +Once the data is successfully loaded on the tabs and the app is working as expected, we can move to the next step. + +
+ +
+ +## Printing Data from Multiple Tabs + +To print data from multiple tabs, we will create few JavaScript queries. Using event handlers, we will run these JavaScript queries in a sequence to print data from all the tabs. + +Before we start creating the JavaScript queries, we need to add a few events to the **Download PDF** button: + +|
Event
|
Action
|
Description
| +|:--- |:--- |:--- | +| On click | Set variable | Set a variable with key `lastSelectedTab` and value to `{{components.tabs1.currentTab}}`. This will store the id of the currently selected tab in the variable. | +| On click | Run query | Select the query named *viewTabs* to run when the button is clicked. | + +**Note**: We will create the *viewTabs* query later in this guide, so you will need to add the event to the button after you've created the query. + +
+ Print data from multiple tabs +
+ +
+ +
+ +## Creating Queries + +
+ +### viewTabs Query + +The *viewTabs* query is a JavaScript query that will run a loop to print data from all the tabs. The query will set a variable `tabIndex` that will store the id of the tab to print data from. The query for this app will loop and increment the tabsIndex variable by 1, using the setVariable action, till the value is less than 4. + +```js title="viewTabs" +if ((variables?.tabIndex ?? undefined) == undefined) { + await actions.setVariable("tabIndex", "0"); // set tabIndex to 0 if it is not set +} else if (parseInt(variables.tabIndex) < 4){ + await actions.setVariable("tabIndex", (parseInt(variables.tabIndex) + 1).toString()); // increment tabIndex by 1 +} +``` + +**This query will have 3 events:** + +#### Event 1: + +- In the *viewTabs* query, click on the **New event handler** button, for the event type, choose `Query Success` from the dropdown. +- Choose `Control component` as the **Action** for the event. +- In the **Run only if** parameter of the event, copy the code: `{{parseInt(variables.tabIndex) < 4}}`. This will run only if the output of the given code is true, i.e. if the tabIndex is less than 4. +- Under the **ACTION OPTIONS** of the event, choose **Action** as `Set current tab`. +- Copy the code: `{{variables.tabIndex}}` in the Id parameter. This sets the current tab to the tab with id stored in the tabIndex variable, i.e. it sets the current tab to the tab whose id got recently stored in the `tabIndex` variable via the *viewTabs* query. + +
+ Print data from multiple tabs +
+ +#### Event 2: + +- The second event in this query will also be a `Query Success` event. +- Choose `Run Query` as the **Action** for the event. +- In the **Run Only If** parameter, copy the code: `{{parseInt(variables.tabIndex) < 4}}`. This event will run only if the condition given in the code is true. +- The query for this event handler will be `getTabsHTML`. +- Add a **Debounce** of `100` milliseconds to this event handler. + +**Note:** We will create the *getTabsHTML* query later in this guide, so you will need to add the event to the button after you've created the query. + +
+ Print data from multiple tabs +
+ +#### Event 3: + +- The third event in this query will also be a `Query Success` event. +- Choose `Run Query` as the **Action** for the event. +- In the **Run Only If** parameter, copy the code: `{{parseInt(variables.tabIndex) === 4}}`. This action runs only when the `tabIndex` is equal to 4, i.e. the last iteration of the loop and we will print the data from all the tabs in this iteration. +- The query for this event handler will be `printPDF`. + +**Note:** We will create the *printPDF* query later in this guide, so you will need to add the event to the button after you've created the query. + +
+ Print data from multiple tabs +
+ +Now that we have created the *viewTabs* query, we can go to the **[Download PDF](/docs/how-to/print-multi-tabs-report#printing-data-from-multiple-tabs)** button and add the *viewTabs* query to the `On click` event handler. + +
+ +
+ +### getTabsHTML Query + +The *getTabsHTML* is a JavaScript query that will get the HTML of the current tab and store it in a variable. The query will have a variable `tabsHtml` that will store the HTML of all the tabs in the form of an array. + +```js title="getTabsHTML" +actions.setVariable( // set tabsHtml variable + "tabsHtml", + [...(variables?.tabsHtml ?? [])].concat([ // add html of the current tab to the tabsHtml variable + ((variables?.tabIndex ?? -1) > 0 + ? `
` // this will help to print data from all the tabs in one go + : "") + + document.getElementsByClassName("widget-" + components.tabs1.id)[0] // get the html of the current tab + .innerHTML + + "
", // add the html of the current tab to the tabsHtml variable + ]) +); +``` + +**This query will have 1 event:** + +#### Event 1: + +- The event in this query will be a `Query Success` event. +- This event will have an **Action** of `Run Query`. +- In the **Query** Parameter, choose *viewTabs* as the query. This will run the *viewTabs* query after the *getTabsHTML* query is successfully executed. + +
+ Print data from multiple tabs +
+ +Now that we have created the *getTabsHTML* query, we can go to the *viewTabs* query and in the **Event 2** of that query, add the *getTabsHTML* query to the event handler. + +
+ +
+ +### printPDF Query + +The *printPDF* query is a JavaScript query that generates a printable document from the HTML content stored in the `tabsHtml` variable. This query will open a new window and write the HTML content of all the tabs. This will allow the user to download a PDF document that includes the formatted content of all the tabs. + +```js title="printPDF" +var printContents = variables.tabsHtml; // get the html of all the tabs from the tabsHtml variable + +var winPrint = window.open("", "", "width=900,height=650"); // Open a New Window for Printing + +var styles = document.querySelectorAll('link, style'); +var stylesHtml = ""; +for (var i = 0; i < styles.length; i++) { + stylesHtml += styles[i].outerHTML; +} // gather styles from the current page + +stylesHtml += ''; // add landscape orientation to the page + +winPrint.document.write( + "" + + stylesHtml + + "" +); // add styles to the page + +for (var j = 0; j < printContents.length; j++) { + winPrint.document.write(printContents[j]); +} // add html of all the tabs to the page + +winPrint.document.write(""); // Document Finalization and Printing +winPrint.document.close(); +winPrint.focus(); +winPrint.print(); +winPrint.close(); +``` + +**This query will have 3 events:** + +#### Event 1: + +- In the *printPDF* query, click on the **New event handler** button, for the event type, choose `Query Success` from the dropdown. +- Choose `Unset variable` as the **Action** for the event. +- Under the **ACTION OPTIONS** of the event, set `tabsIndex` as the **Key**. This will unset the tabsIndex variable after the *printPDF* query is successfully executed. + +
+ Print data from multiple tabs +
+ +#### Event 2: + +- The second event in this query will also be a `Query Success` event. +- Choose `Unset variable` as the **Action** for the event. +- Under the **ACTION OPTIONS** of the event, set `tabsHtml` as the **Key**. This will unset the `tabsHtml` variable after the *printPDF* query is successfully executed. + +
+ Print data from multiple tabs +
+ +#### Event 3: + +- The third event in this query will also be a `Query Success` event. +- Choose `Control component` as the **Action** for the event. +- Choose `tabs1` for the **Component** parameter. +- Choose `Set current tab` as the **Action**. +- For the Id parameter, copy the code: `{{variables.lastSelectedTab}}`. This will set the current tab to the tab that was selected before the **Download PDF** button was clicked. + +
+ Print data from multiple tabs +
+ +Now that we have created the *printPDF* query, we can go to the *viewTabs* query, and in the **Event 3** of that query, add the *printPDF* query to the **Query Success** event handler. + +Finally, we can test the app by clicking on the **Download PDF** button. This will redirect us to the new tab of the browser, and download a PDF document with the data from all the tabs. + +
+ +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/run-action-from-runjs.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/run-action-from-runjs.md new file mode 100644 index 0000000000..497c31084c --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/run-action-from-runjs.md @@ -0,0 +1,268 @@ +--- +id: run-actions-from-runjs +title: Run Actions from RunJS query +--- + +ToolJet allows you to execute various [actions](/docs/actions/show-alert) within RunJS queries. This guide outlines the syntax and examples for each action. + +
+ +### Run Query + +To trigger a query, you can use the below functions: + +```js +queries.getSalesData.run() +// replace getSalesData with your query name +``` +or +```js +await actions.runQuery('getSalesData') +// replace getSalesData with your query name +``` + +**Example:** + +In the screenshot below, we are triggering two different queries using two different syntax available for `Run Query` action. + +
+ Print data from multiple tabs +
+ +
+ +
+ +### Get Query Data + +In the previous section, we saw how we can trigger queries. Once the queries are triggered, if you want to immediately use the data returned by the query inside the RunJS query, you can use the `getData()`, `getRawData()` and `getLoadingState()` functions: + +#### Trigger a query and retrieve its data: + +```js +await queries.getSalesData.run(); +// replace getSalesData with your query name + +let value = queries.getSalesData.getData(); +// replace getSalesData with your query name +``` + +#### Trigger a query and retrieve its raw data: + +```js +await queries.getCustomerData.run(); +//replace getCustomerData with your query name + +let value = queries.getCustomerData.getRawData(); +// replace getCustomerData your with query name +``` + +#### Trigger a query and retrieve its loading state: + +```js +await queries.getTodos.run() +//replace getTodos with your query name + +let value = queries.getTodos.getLoadingState(); +//replace getTodos with your query name +``` + +
+ +
+ +### Set Variables + +To create a variable, you can use the below function: + +```javascript +actions.setVariable('', ``) +``` + +
+ +
+ +### Unset Variable + +To delete a created variable, you can use the below function: + +**Syntax:** + +```javascript +actions.unSetVariable('') +``` + +
+ +
+ +### Get Variables + +To access variables immediately after setting them in a RunJS query, you can use the `getVariable` and `getPageVariable` functions: + +#### Set and retrieve a variable: + +```js +actions.setVariable('mode','dark'); +//replace mode with your desired variable name + +return actions.getVariable('mode'); +``` + +#### Set and retrieve a page-specific variable: +```js +actions.setPageVariable('number',1); +//replace number with your desired variable name + +return actions.getPageVariable('number'); +``` + +
+ +
+ +### Logout + +To log out the current logged-in user from the ToolJet, use the below function: + +```javascript +actions.logout(); +``` + +
+ +
+ +### Show Modal + +To open a modal using RunJS query, use the below function: + +```javascript +actions.showModal('') +``` + +
+ +
+ +### Close Modal + +To close a modal using RunJS query, use the below function: + +```javascript +actions.closeModal('') +``` + +
+ +
+ +### Set Local Storage + +Set a value in local storage using the below code: + +**Syntax:** + +```javascript +actions.setLocalStorage('key', 'value'); +``` + +
+ +
+ +### Copy to Clipboard + +Use the below code to copy content to the clipboard: + +```javascript +actions.copyToClipboard('') +``` + +
+ +
+ +### Generate File + +The below action can be used to generate a file. + +```js +actions.generateFile('', '', '') +``` + +`fileName` is the name that you want to give the file(string), `fileType` can be **csv**, **plaintext**, or **pdf** and `data` is the data that you want to store in the file. + +Example for generating CSV file: + +```js +actions.generateFile('csvfile1', 'csv', '{{components.table1.currentPageData}}') // generate a csv file named csvfile1 with the data from the current page of table +``` + +Example for generating Text file: + +```js +actions.generateFile('textfile1', 'plaintext', '{{JSON.stringify(components.table1.currentPageData)}}') // generate a text file named textfile1 with the data from the current page of table (stringified) +``` + +Example for generating PDF file: + +```js +actions.generateFile('Pdffile1', 'pdf', '{{components.table1.currentPageData}}') // generate a text file named Pdffile1 with the data from the current page of table +``` + +
+ +
+ +### Go to App + +You can switch to a different application using the below action: + +```javascript +actions.goToApp('slug',queryparams) +``` + +- `slug` can be found in URL of the released app after `application/` or in the share modal that opens up when you click on the `Share` button on the top-right of the app-builder +- `queryparams` can be provided in this format - `[ ['key1','value1' ], ['key2','value2'] ]` + +
+ +
+ +### Show Alert + +To show an alert using RunJS query, use the below code: + +```js +actions.showAlert('' , '' ) +``` + +Available alert types are `info`, `success`, `warning`, and `danger`. + +Example: +```js +actions.showAlert('error' , 'This is an error' ) +``` + +
+ +
+ +### Run Multiple Actions From RunJS Query + +To run multiple actions from a RunJS query, you'll have to use **async-await** in the function. + +Here is a example code snippet for running the queries and showing alert after specific intervals. Check the complete guide on running queries at specified intervals **[here](/docs/how-to/run-query-at-specified-intervals)**. + +```js +actions.setVariable('interval',setInterval(countdown, 5000)); +async function countdown(){ + await queries.restapi1.run() + await queries.restapi2.run() + await actions.showAlert('info','This is an information') +} +``` + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/run-query-at-specified-intervals.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/run-query-at-specified-intervals.md new file mode 100644 index 0000000000..6de502e96a --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/run-query-at-specified-intervals.md @@ -0,0 +1,115 @@ +--- +id: run-query-at-specified-intervals +title: Run Query at Specified Intervals +--- +
+ +In this guide, we'll walk through the process of building a ToolJet application that automates data retrieval at specific intervals. By utilizing the RunJS queries, we can set up intervals for triggering queries, ensuring that the data is fetched dynamically and efficiently. + +
+ +
+ +## Step 1: Create a New Application + +Begin by creating a new application in the ToolJet dashboard. Once the app builder opens, Drag a table component onto the canvas. This component will display the data fetched from the REST API query. + +
+ Table Component With Data +
+ +
+ +
+ +## Step 2: Set Up a REST API Query + +From the query panel, create a new REST API query. Utilize mock REST API data by choosing the 'GET' method and specifying the endpoint (e.g., `https://jsonplaceholder.typicode.com/posts`). Name the query 'post' and `Run` the query to ensure that the data is fetched successfully. + +
+ Table Component With Data +
+ +
+ +
+ +## Step 3: Configure Table Properties + +In the Table properties, link the query data to the table by setting the 'table data' property to `{{queries.post.data}}`. This establishes the connection between the REST API query and the table component. + +
+ Table Component With Data +
+ +
+ +
+ +## Step 4: Implement the RunJS Query + +Create a RunJS query to set up intervals for triggering the REST API query. Use the following script: + +```js +actions.setVariable('interval', setInterval(countdown, 5000)); // 5000ms = 5 seconds + +function countdown(){ // Function to trigger the REST API query + queries.post.run(); // action to run the REST API query +} +``` + +Adjust the interval duration according to your needs. Optionally, utilize `async` and `await` for multiple actions within the countdown function. + +```js +actions.setVariable('interval',setInterval(countdown, 5000)); +async function countdown(){ + await queries.restapi1.run() + await queries.restapi2.run() + await actions.showAlert('info','This is an information') +} +``` + +
+ +
+ +## Step 5: Advanced Configuration + + +From the Settings section of the RunJS query, enable 'Run query on page load.' This ensures that the query is triggered when the application is loaded. Rename the query as 'setInterval' to complete the configuration. + +
+ Table Component With Data +
+ +
+ +
+ +## Step 6: Prevent Indefinite Triggering + +Create another RunJS query named 'clearInrternal' to stop the query from triggering indefinitely. Use the `clearInterval()` method to clear the interval. This method retrieves the value from the variable set in the 'setInterval' query. + +```js +clearInterval(variables.interval); +``` + +
+ +
+ +## Step 7: Add a Button + +Drag a button on the canvas to act as a user-triggered stop mechanism. Attach an event handler to execute the 'clear' query when the button is clicked. + +
+ Table Component With Data +
+ +
+ +
+ +By following these steps, your ToolJet application will dynamically fetch data at specified intervals, providing an efficient and automated user experience. + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/s3-custom-endpoint.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/s3-custom-endpoint.md new file mode 100644 index 0000000000..bcc33b30b4 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/s3-custom-endpoint.md @@ -0,0 +1,22 @@ +--- +id: s3-custom-endpoints +title: Use Custom Endpoint for S3 Hosts +--- +
+ +In this how-to guide, we will see how we can connect to different **S3 compatible object storages** using the custom endpoint. In this guide, we are using Minio since it is an S3-compatible object storage. + +- Go to the ToolJet dashboard, and create a new application +- On the left-sidebar, go to the **Sources** and add a new AWS S3 datasource +- Now the connection modal will pop-up. + +
+ + Custom Endpoint - S3 hosts + +
+- To get the **Credentials** which is **Access Key** and **Secret Key**, you'll need to go to the Minio console to generate the keys +- Enable the **Custom Endpoint** toggle switch, and enter the custom host URL i.e where your Minio server API is exposed +- Once entered the details, you can click on the **Test Connection** button to check the connection + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/serverside-pagination.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/serverside-pagination.md new file mode 100644 index 0000000000..aeece0d9a9 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/serverside-pagination.md @@ -0,0 +1,92 @@ +--- +id: use-server-side-pagination +title: Using Server Side Pagination in Tables +--- + +
+ +In this guide, we will implement server-side pagination for large datasets in a table component to enhance application performance. This guide is applicable for databases like MySQL, PostgreSQL, MSSQL, MongoDB, etc., supporting `limit` and `offset` for chunked data retrieval. + +
+ +
+ +### Loading Data from PostgreSQL in Chunks + +To fetch data in chunks from a PostgreSQL table `users`, use `limit` and `offset` in the SQL query: + +```sql title="PostgreSQL query" +SELECT * +FROM users +ORDER BY id +LIMIT 100 OFFSET {{(components.table1.pageIndex-1)*100}}; +``` + +The query will fetch 100 rows at a time from the PostgreSQL users table, and the number of rows returned is determined by the current value of `pageIndex`(exposed variable) in the Table component. + +The following is the breakdown of the above PostgreSQL query: + +- `ORDER BY id`: Orders the result set by the id column. + +- `LIMIT 100`: Limits rows returned to 100 per query. + +- `OFFSET {{(components.table1.pageIndex-1)*100}}`: Determines the starting row number based on the current page index for pagination. + + +To obtain the count of records in the users table, execute the following query: + +```sql +SELECT COUNT(*) +FROM users; +``` + +
+ +
+ +### Edit the Table Component + +**Follow the steps below to edit the properties of the Table component:** + +- Drag the table component to the canvas from the components library and set the value of the **Data** property to `{{queries..data}}` to populate the table with the relevant data. + +- Enable the **Server-side pagination** option. +- Click on the `Fx` next to **Enable previous page button** and set the value as below. This condition disables the previous page button when the current page is page `1`. + + ```js + {{components.table1.pageIndex >=2 ? true : false}} + ``` + +- Click on the `Fx` next to **Enable next page button** and set it's value as below. This condition disables the next page button when the current page is the last page. + ```js + {{components.table1.pageIndex < queries..data[0].count/100 ? true : false}} + ``` + +- Set the value of the **Total records server side** property as below. This will set the total number of records in the Table component. + ```js + {{queries..data[0].count}} + ``` + +
+ Table data +
+ + +- To add the loading indicator on the table component while executing the query, set the `Loading state` property as: + + ```js + {{queries..isLoading}} + ``` +- Select the **Page changed** event and choose the **Run Query** action, after clicking the `New event handler`. Then, select the **Query** from the dropdown that fetches data from the PostgreSQL table. + +
+Table data +
+ +Now, whenever the page is changed, the query will be executed, and the data will be fetched from the PostgreSQL table in chunks. + +
+ Table data +
+ +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/setup-syslog.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/setup-syslog.md new file mode 100644 index 0000000000..6c6cdd3993 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/setup-syslog.md @@ -0,0 +1,101 @@ +--- +id: setup-rsyslog +title: Setup Log File Generation (Rsyslog) +--- +
+ +The **log file** serves as a comprehensive record of audit logs, capturing crucial information about various activities within the ToolJet. Follow the guide below to set up and utilize the log file feature effectively. + +
+ +
+ +## Activation and Configuration + +### Environment Variable Setup + +- To **activate** the log file feature, simply set the environment variable `LOG_FILE_PATH` to specify the desired path for the log file. For instance, if you want to use `rsyslog` as the log file path, set `LOG_FILE_PATH` to `rsyslog`. + + ```bash + LOG_FILE_PATH='rsyslog' + ``` + +
+ Setup log file generation +
+ +- The log file path is relative to the home directory of the machine. For instance, if the home directory is `/home/tooljet`, the log file path will be `/home/tooljet/rsyslog`. + +### Server Restart + +- After configuring the log file environment variable, it's essential to **restart the server** to initiate the log file generation process. + +- This step ensures that the server recognizes the new configuration and begins recording audit logs. + +
+ +
+ +## Log Rotation and Organization + +### Daily Log Rotation + +- The log file is designed to rotate on a daily basis, creating a new log file each day. This configuration aids in efficient management and organization of audit data. + +### Log File Path Structure + +- The log file path is determined by the `LOG_FILE_PATH` variable. It is crucial to understand that this path is relative to the home directory of the machine. For instance, if `LOG_FILE_PATH` is set to `rsyslog`, the resulting log file path will be structured as follows: + + ```bash + homepath/rsyslog/{process_id}-{date}/audit.log + ``` + + - `{process_id}` is a placeholder for the unique process identifier. + - `{date}` represents the current date. + + This structured path ensures that audit logs are organized by both process and date, simplifying traceability and analysis. + +
+ Setup log file generation +
+ +### Example Log Data + +The log data captures essential details, such as user ID, organization ID, resource ID, resource type, action type, resource name, IP address, and additional metadata. + +
+Example Log file data + +```bash +{ + level: 'info', + message: 'PERFORM APP_CREATE OF awdasdawdwd APP', + timestamp: '2023-11-02 17:12:40', + auditLog: { + userId: '0ad48e21-e7a2-4597-9568-c4535aedf687', + organizationId: 'cf8e132f-a68a-4c81-a0d4-3617b79e7b17', + resourceId: 'eac02f79-b8e2-495a-bffe-82633416c829', + resourceType: 'APP', + actionType: 'APP_CREATE', + resourceName: 'awdasdawdwd', + ipAddress: '::1', + metadata: { + userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36', + tooljetVersion: '2.22.2-ee2.8.3' + } + }, + label: 'APP' +} +``` + +
+ +### Folder Creation + +The log file feature automatically creates a folder in the home path with the specified name (e.g., `rsyslog`). This folder serves as the root directory for the organized storage of audit logs. + +
+ Setup log file generation +
+ +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/upload-files-aws.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/upload-files-aws.md new file mode 100644 index 0000000000..e5a6670f03 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/upload-files-aws.md @@ -0,0 +1,162 @@ +--- +id: upload-files-aws +title: Upload and Download Files on AWS S3 Bucket +--- +
+ +This guide will help you in quickly building a basic UI for uploading or downloading files from AWS S3 buckets. + +Before building the UI, check out the **[docs for AWS S3 data source](/docs/data-sources/s3)** to learn about setting up AWS S3 and adding the data source. + +Once you have successfully added the AWS data source, build a basic UI using the following widgets: +- **Dropdown**: For selecting a bucket in S3 storage. +- **Table**: For listing all the objects inside the selected bucket in dropdown. +- **Text Input**: For getting a path for the file that is to be uploaded. +- **File picker**: For uploading the file. +- **Button**: This will be used to fire the upload query. + +
+ +![ToolJet - How To - Upload files on AWS S3 bucket](/img/how-to/upload-files-aws/ui.png) + +
+ +
+ +
+ +## Queries + +We'll create the following queries: + +1. **getBuckets** +2. **listObjects** +3. **uploadToS3** +4. **download** + +
+ +
+ +### getBuckets + +This query will fetch the list of all the buckets in your S3. Just create a new query, select AWS S3 data source, and choose **List buckets** operation. Name the query **getBuckets** and click **Save**. + +
+ +![ToolJet - How To - Upload files on AWS S3 bucket](/img/how-to/upload-files-aws/getBuckets.png) + +
+ +Now, let's edit the properties of **dropdown** widget. + +- **Label**: Set the label as Bucket. +- **Option values**: Set option values as `{{queries.getBuckets.data.Buckets.map(bucket => bucket['Name'])}}`. We're mapping the data returned by the query as the returned data is array of objects. +- **Option label**: Set option values as `{{queries.getBuckets.data.Buckets.map(bucket => bucket['Name'])}}`. This will display the same option label as option values. + +You can later add an event handler for running the **listObject** query whenever an option is selected from the dropdown. + +
+ +![ToolJet - How To - Upload files on AWS S3 bucket](/img/how-to/upload-files-aws/dropdown.png) + +
+ +
+ +
+ +### listObjects + +This query will list all the objects inside the selected Bucket in dropdown. Select **List objects in a bucket** operation, enter `{{components.dropdown1.value}}` in the Bucket field - this will dynamically get the field value from the selected option in dropdown. + +
+ +![ToolJet - How To - Upload files on AWS S3 bucket](/img/how-to/upload-files-aws/listObjects.png) + +
+ +Edit the properties of **table** widget: +- **Table data**: `{{queries.listObjects.data['Contents']}}` +- **Add Columns**: + - **Key**: Set the **Column Name** to `Key` and **Key** to `Key` + - **Last Modified**: Set the **Column Name** to `Last Modified` and **Key** to `LastModified` + - **Size**: Set the **Column Name** to `Size` and **Key** to `Size` +- Add a **Action button**: Set button text to **Copy signed URL**, Add a handler to this button for On Click event and Action to Copy to clipboard, in the text field enter `{{queries.download.data.url}}` - this will get the download url from the **download** query that we will create next. + +
+ +![ToolJet - How To - Upload files on AWS S3 bucket](/img/how-to/upload-files-aws/table.png) + +
+ +
+ +
+ +### download + +Create a new query and select **Signed URL for download** operation. In the Bucket field, enter `{{components.dropdown1.value}}` and in Key enter `{{components.table1.selectedRow.Key}}`. + +
+ +![ToolJet - How To - Upload files on AWS S3 bucket](/img/how-to/upload-files-aws/download.png) + +
+ +Edit the **properties** of the table, add a Event handler for running the `download` query for `Row clicked` event. This will generate a signed url for download every time a row is clicked on the table. + +
+ +
+ +### uploadToS3 + +Create a new query, select the **Upload object** operation. Enter the following values in their respective fields: +- **Bucket**: `{{components.dropdown1.value}}` +- **Key**: `{{ components.textinput1.value + '/' +components.filepicker1.file[0].name}}` +- **Content type**: `{{components.filepicker1.file[0].type}}` +- **Upload data**: `{{components.filepicker1.file[0].base64Data}}` +- **Encoding**: `base64` + +
+ +![ToolJet - How To - Upload files on AWS S3 bucket](/img/how-to/upload-files-aws/uploadToS3.png) + +
+ +
+ +
+ +#### Configure the File Picker: + +Click on the widget handle to edit the file picker properties: + +- Change the **Accept file types** to `{{"application/pdf"}}` for the picker to accept only pdf files or `{{"image/*"}}` for the picker to accept only image files . In the screenshot below, we have set the accepted file type property to `{{"application/pdf"}}` so it will allow to select only pdf files: + +
+ +![ToolJet - How To - Upload files using GCS](/img/how-to/upload-files-gcs/result-filepicker.png) + +
+ +- Change the **Max file count** to `{{1}}` as we are only going to upload 1 file at a time. + +- Select a pdf file and hold it in the file picker. + +:::info + File types must be valid **[MIME](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types)** type according to input element specification or a valid file extension. + + To accept any/all file type(s), set `Accept file types` to an empty value. +::: + +
+ +![ToolJet - How To - Upload files using GCS](/img/how-to/upload-files-gcs/config-filepicker.png) + +
+ +Final steps, go to the **Advanced** tab of the **uploadToS3** query and add a query to run **listObjects** query so that whenever a file is uploaded the tabled is refreshed. + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/upload-files-gcs.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/upload-files-gcs.md new file mode 100644 index 0000000000..b948ee575d --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/upload-files-gcs.md @@ -0,0 +1,90 @@ +--- +id: upload-files-gcs +title: Upload Files Using GCS +--- +
+ +In this guide, we are going to create an interface to upload PDFs to Google Cloud Storage. + +Before adding the new data source we will need to have a private key for our GCS bucket and make sure the key has the appropriate rights. + +
+ +
+ +## Setting up Google Cloud Storage Data Source + +1. Go to the data source manager on the left-sidebar and click on the `+` button. +2. Add a new GCS data source from the **APIs** section in modal that pops up. +3. Enter the **JSON private key for service account** and test the connection. +4. Click on **Save** to add the data source. + +
+ +![ToolJet - How To - Upload files using GCS](/img/how-to/upload-files-gcs/adding-account.png) + +
+ +
+ +
+ +## Adding a File Picker + +1. Drag and drop the **file picker** widget on the canvas +2. Configure the file picker: + - Change the **Accept file types** to `{{"application/pdf"}}` for the picker to accept only pdf files. In the screenshot below, we have set the accepted file type property to `{{"application/pdf"}}` so it will allow to select only pdf files: + +
+ +![ToolJet - How To - Upload files using GCS](/img/how-to/upload-files-gcs/result-filepicker.png) + +
+ + - Change the **Max file count** to `{{1}}` as we are only going to upload 1 file at a time. + +3. Select a pdf file and hold it in the file picker. + +:::info + File types must be valid **[MIME](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types)** type according to input element specification or a valid file extension. + + To accept any/all file type(s), set `Accept file types` to an empty value. +::: + +
+ +![ToolJet - How To - Upload files using GCS](/img/how-to/upload-files-gcs/config-filepicker.png) + +
+ +
+ +
+ +## Creating a Query + +1. Click on the `+` button of the query manager at the bottom panel of the editor and select the GCS data source +2. Select **Upload file** operation and enter the required parameters: +- Bucket: `gs://test-1` +- File Name: `{{components.file1.file[0]['name']}}` +- Content Type: `{{components.file1.file[0]['type']}}` +- Upload data: `{{components.file1.file[0]['base64Data']}}` +- Encoding: `base64` +3. Click on **Save** to create the query + +
+ +
+ +## Running the Query +1. Add a **button** that will fire the query to upload the file +2. Edit the properties of the button and add a **event handler** to **Run the query** on **On-Click** event. +3. Click on **Button** to fire the query, this will upload the pdf file that you selected earlier through the file picker and will upload it on the GCS. + +
+ +![ToolJet - How To - Upload files using GCS](/img/how-to/upload-files-gcs/final-result.png) + +
+ +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/use-axios.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/use-axios.md new file mode 100644 index 0000000000..4ac9556aae --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/use-axios.md @@ -0,0 +1,68 @@ +--- +id: use-axios-in-runjs +title: Use Axios in RunJS +--- +
+ +ToolJet supports three libraries: **Moment.js**, **Lodash**, and **Axios**. This guide focuses on using the Axios library with RunJS queries. **[Axios](https://axios-http.com/docs/intro)** is a promise-based HTTP client for making requests to your own or external servers. It supports various request types like `GET`, `POST`, `PUT/PATCH`, and `DELETE`. + +
+ +
+ +## GET Requests + +We'll use **[JSONPlaceholder](https://jsonplaceholder.typicode.com/)**, a free API, to demonstrate GET and PUT requests. + +- Create a RunJS query and paste the code below: + +```javascript +var url = "https://jsonplaceholder.typicode.com/users/1"; + +var data = (await axios.get(url)).data; + +return data +``` + +*This code sets up a URL variable, makes a GET request to the API, and returns the data. Preview the query to see the API's response.* + +
+ +Use Axios in RunJS + +
+ +
+ +
+ +## POST Requests + +- Create a RunJS query and paste the code below: + +```javascript +var url = "https://jsonplaceholder.typicode.com/users"; + +var data = axios.post(url,{ + id: 11, + name: "Shubhendra", + username: "camelcaseguy", + email: "shubhendra@tooljet.com",}) + +return data +``` + +This POST request sends user details to the server. The server's response, as shown below, includes **Status: 201** indicating successful resource creation. + + +
+ +Use Axios in RunJS + +
+ +To see Axios in action in a project, check out this tutorial: +**[Build GitHub star history tracker](https://blog.tooljet.ai/build-github-stars-history-app-in-5-minutes-using-low-code/)**. + + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/use-custom-parameters.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/use-custom-parameters.md new file mode 100644 index 0000000000..369bb32ef4 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/use-custom-parameters.md @@ -0,0 +1,100 @@ +--- +id: use-custom-parameters +title: Use Custom Parameters +--- +
+ +Custom parameters in your queries offer a flexible way to introduce variables without directly modifying query parameters. This guide will walk you through creating, utilizing, and calling queries with custom parameters. + +
+ +
+ +### Adding Custom Parameters + +1. Open the query panel and select the query you want to add custom parameters to. +2. Navigate to the **Parameters** section in the top bar. +3. Click the **+** button to add a custom parameter. +4. For each parameter, specify: + - **Name:** Identifier for the parameter. + - **Default value:** A constant string, number, or object. + +
+ How to: use custom parameters +
+ +
+ +
+ +### Syntax for Utilizing Parameters + +Use `parameters.` in your query to employ custom parameters. Note that parameters can only be used within the query where they are defined. + +
+ How to: use custom parameters +
+ +
+ +
+ +### Example: Create Row in ToolJetDB with Custom Parameters + +Let's assume we have a ToolJetDB table with the following columns: `name`, `email`, and `contact`. We will create a new row in the table using custom parameters. + +- Create a new ToolJetDB query, select a table from the dropdown and select the `Create Row` operation. + +- Add the following parameters: + 1. **name:** `name` and **value:** `Shubh` + 2. **name:** `email` and **value:** `shubh@email.com` + 3. **name:** `contact` and **value:** `4638563845` + +
+ How to: use custom parameters +
+ +- Add the columns to the query and use the custom parameters to set the values. + + | Column | Value | + | ------ | ----- | + | name | `{{parameters.name}}` | + | email | `{{parameters.email}}` | + | contact| `{{parameters.contact}}` | + +
+ How to: use custom parameters +
+ +- Finally, execute the query to create a new row in the ToolJetDB table with the values provided in the custom parameters. + +
+ +
+ +### Example: Providing Custom Parameters Using Events + +In this example, we will demonstrate how to use custom parameters in a query by providing values from an event. We will use execute a REST API query and on its success, we will execute the ToolJetDB query to create a new row with the response data. + +1. **Create a REST API Query:** + - Method: `GET` + - URL: `https://reqres.in/api/users?page=2` + +2. **Add a Success Event:** + - Name: `onSuccess` + - Action: `Run Query` + - Query: `Create Row` + - Parameters: The parameters that you have added to the query will automatically be available in the event. + 1. **name:** `{{queries.getSalesData.data.data[0].name}}` This will use the name from the first record of the response data. + 2. **email:** `{{queries.getSalesData.data.data[0].email}}` This will use the email from the first record of the response data. + 3. **contact:** `4638563845` provided as a constant value just for demonstration. + +3. **Execute the REST API query and observe the new row created in the ToolJetDB table.** + +**Note:** You can also use parameters in JavaScript queries. Learn more about [JS Query Parameter](/docs/data-sources/run-js/#parameters-in-run-javascript-code). + +
+ How to: use custom parameters +
+ +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/use-events-on-chart.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/use-events-on-chart.md new file mode 100644 index 0000000000..6d2ce87dbc --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/use-events-on-chart.md @@ -0,0 +1,258 @@ +--- +id: use-events-on-chart +title: Use Events on Chart Created Through Custom Component +--- +
+ +This guide will use the Custom Component to create a chart using a third-party library that supports events. Plotly is one of the libraries that supports events. In this tutorial, we will build a chart using Plotly and add events. + +
+ Plotly Chart +
+ +
+ +
+ +## Step 1: Add a Custom Component + +- Open the App Builder and add a Custom Component to the page. +- Click on the Custom Component to open the Properties panel. + +Note: If you are not familiar with the Custom Component, please read the [Custom Component](/docs/widgets/custom-component/)documentation. + +
+ +
+ +## Step 2: Add the Code to the Custom Component + +In the Code section of the `Custom Component` properties, add the following code: + +```js +import React from 'https://cdn.skypack.dev/react'; +import ReactDOM from 'https://cdn.skypack.dev/react-dom'; +import { Button, Container } from 'https://cdn.skypack.dev/@material-ui/core'; +import Plotly from 'https://cdn.skypack.dev/plotly.js-basic-dist-min'; +import createPlotlyComponent from 'https://cdn.skypack.dev/react-plotly.js/factory'; + +// Define the custom component +const MyCustomComponent = ({ data, updateData, runQuery }) => { + // Create Plot component using Plotly + const Plot = createPlotlyComponent(Plotly); + + // Define onClick handler for bars + const barOnClick = ({ points }) => { + alert('A bar is clicked'); + }; + + // Render the component + return ( + + + + ); +}; + +// Connect the component +const ConnectedComponent = Tooljet.connectComponent(MyCustomComponent); + +// Render the connected component to the DOM +ReactDOM.render(, document.body); +``` + +**The steps to implement the above code is as follows:** + +- Import the required libraries. + +```js +import React from 'https://cdn.skypack.dev/react'; // React library +import ReactDOM from 'https://cdn.skypack.dev/react-dom'; // React DOM library +import { Button, Container } from 'https://cdn.skypack.dev/@material-ui/core'; // Material UI library +import Plotly from 'https://cdn.skypack.dev/plotly.js-basic-dist-min'; // Plotly library +import createPlotlyComponent from 'https://cdn.skypack.dev/react-plotly.js/factory'; // Plotly React library +``` + + +- Create a function component called `MyCustomComponent`. This component will render the chart. The `createPlotlyComponent` function is used to create a Plotly component. +- A function called `barOnClick` is created that will be called when the user clicks on the bar. This function will display an alert message. + +```js +const MyCustomComponent = ({data, updateData, runQuery}) => { // function component +const Plot = createPlotlyComponent(Plotly); // create a Plotly component + + const barOnClick = ({points}) => { // function that will be called when the user clicks on the bar + alert('A bar is clicked') // display an alert message + } +``` + +- Render the chart using the `Plot` component. Pass the data and layout to the `Plot` component. Also pass the `barOnClick` function to the `onClick` prop of the `Plot` component. + +```js + return ( + + + + ); +}; +``` + +- Render the `MyCustomComponent` component using the `ReactDOM.render` function. + +```js +const ConnectedComponent = Tooljet.connectComponent(MyCustomComponent); // connect the component to the Tooljet store +ReactDOM.render(, document.body); // render the component +``` + +
+ +
+ +## Step 3: Using Events from the Custom Component + +In the code above, we created a function called `barOnClick` that will be called when the user clicks on the bar. This function holds the code that will be executed when the user clicks on the bar. + +```js +const barOnClick = ({points}) => { + alert('A bar is clicked') +} +``` + +Instead of displaying an alert message, you can use the `runQuery` function to run a query. + +```js +const barOnClick = ({points}) => { + runQuery('queryName') +} +``` + +`runQuery` is a function which accepts a query name as a string used to run the query from the custom component. Learn more about the custom component [here](/docs/widgets/custom-component/). + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/use-form-component.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/use-form-component.md new file mode 100644 index 0000000000..88d098eb31 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/use-form-component.md @@ -0,0 +1,102 @@ +--- +id: use-form-component +title: Use Form Component +--- +
+ +In this guide, we'll create a simple app that uses a **[Form](/docs/widgets/form)** component to add records to a database. We'll use **[ToolJet Database](/docs/tooljet-db/tooljet-database/)** as our data source. + +
+ +
+ +## 1. Create a Table in ToolJet Database +- Create a table named *products* in ToolJet Database. +- Create three columns - `name`, `quantity` and `price`. +- Add some sample data to the table. + +
+ Database Table +
+ +
+ +
+ +## 2. Create the UI +- Create a new app and drag and drop a **[Table](/docs/widgets/table)** component on the canvas. +- Drop a **[Form](/docs/widgets/form)** next to it. +- Since we have three columns in the database, let's update the Form with one **[Text Input](/docs/widgets/text-input)** for `name` and two **[Number Inputs](/docs/widgets/text-input)** for `quantity` and `price`. +- Name the three input fields on the form as - *nameInput*, *quantityInput* and *priceInput*. Name the button as *submitButton*. + +
+ User Interface +
+Naming the components can help in easily identifying or referring individual components when there are a large number of components in the app. + +
+ +
+ +## 3. Load the Table Component With Data + +- Click on the Add button in the **[Query Panel](/docs/app-builder/query-panel/)**, select ToolJet Database +- Rename the query to *getProducts* +- Choose *products* as Table name, List rows as Operations +- Enable `Run this query on application load?` to automatically run the query when the app starts +- Click on Run to fetch data +- Click on the Table component to open its properties panel on the right. Under the `Data` property, paste the below code: +```js +{{queries.getProducts.data}} +``` +
+ Table with Data +
+ +
+ +
+ +## 4. Write Data Using the Form Component +- Click on the Add button in the Query Panel, select ToolJet Database +- Select *products* as Table name, Create row as Operations +- Rename the query to *addProduct* +- Click on Add Column and add three columns - **name**, **quantity** and **price** +- Enter code below for **name**, **quantity** and **price** column keys: + +```js +{{components.form.data.nameInput.value}} +{{components.form.data.quantityInput.value}} +{{components.form.data.priceInput.value}} +``` + +To ensure the Table component updates with new data after adding products, trigger the *getProducts* query following each *addProduct* query execution. Here's how: + +- Click on **New event handler** in the *addProduct* query to add a new event. +- For the new event, leave the event as Query Success, set Run Query as the Action and choose *getProducts* as the Query. + +
+ Refresh Table +
+ +This process refreshes the Table component with the latest data from the database. +
+
+ +- Next, click on the Form component and set `Button To Submit Form` as *submitButton*. +- Add a **New event handler** to the Form component. Keep On submit as Event, Run Query as Action and select *addProduct* as the Query. + +
+ Table with Data +
+ +Now if you enter the product data on the form and click on Submit. The `addProduct` query will run and the entered data will be written to the `products` table in the ToolJet Database. + +
+ Final Preview +
+
+ +In this how-to guide, we have explored a practical application of the Form component in ToolJet. You can apply the same principles for a variety of use cases that requires data input from the end-user. + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/use-inspector.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/use-inspector.md new file mode 100644 index 0000000000..62aa7f43c8 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/use-inspector.md @@ -0,0 +1,92 @@ +--- +id: use-inspector +title: Use Inspector in App-Builder +--- +
+ +This guide introduces **Inspector** in the app-builder, a feature that lets you view data related to queries, components, global variables, page-related variables, user-set variables and constants. + +
+ Preview of Use Inspector +
+ +
+ +
+ +## Sections + +The Inspector panel has 6 main sections: + +- **[Queries](#queries)** +- **[Components](#components)** +- **[Globals](#globals)** +- **[Variables](#variables)** +- **[Page](#page)** +- **[Constants](#constants)** + +
+ +
+ +### Queries + +Queries allow you to inspect the specifics of your queries. However, the data related to these queries will only be visible after they have been executed or triggered. + +
+ +
+ +### Components + +Under Components, you can view and analyze the properties and values of the components you've added to the canvas, providing insights into how each component functions within your app. + +
+ +
+ +### Globals + +Globals give you access to global information related to the app. + +The globals selection consists of the following data: + +- **currentUser:** Contains details about the user who is currently logged in, like their **email**, **firstName**, and **lastName**. +- **groups:** A list of group names that the logged-in user is part of. Note: The `all_users` group is a default group for everyone. +- **theme:** Shows the name of the theme that is currently being used. +- **urlparams:** Details about the URL parameters of the app. +- **environment:** Has two parts: **id**, a unique auto-generated identifier, and **name**, the name of the current environment of the app version. +- **modes:** Indicates whether the app is in **edit**, **preview**, or **view** mode. **Edit** is for editing the app, **preview** is used when the preview button in the app builder is clicked, and **view** is for when the app is opened through a shared URL. + +:::info +All the global variables can be accessed anywhere within ToolJet applications. Here's an **[example use-case](/docs/how-to/access-currentuser)** that demonstrates the usage of these variables. +::: + +
+ +
+ +### Variables + +Variables shows user-defined variables in a key-value format. These variables, set through event handlers or queries, are accessible across the entire application. You can set variables from the [event handler](/docs/actions/set-variable) or using [JavaScript code](/docs/how-to/run-actions-from-runjs#set-variables). + +
+ +
+ +### Page +Page lets you view page-specific properties like page name, handle and variables. Page variables are restricted to their respective pages and are not accessible application-wide. + +
+ +
+ +### Constants + +Under **[Constants](/docs/security/constants/)**, you can find the predefined values (usually tokens/secret keys/API keys) that can be used across your application to maintain consistency and facilitate easy updates. + +:::info +The **environment** and **mode** variables are only available in **ToolJet Enterprise Edition v2.2.3** and above. +::: + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/use-s3-presigned-url-to-upload-docs.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/use-s3-presigned-url-to-upload-docs.md new file mode 100644 index 0000000000..a69965a7ca --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/use-s3-presigned-url-to-upload-docs.md @@ -0,0 +1,138 @@ +--- +id: use-s3-signed-url-to-upload-docs +title: Use S3 Signed URL to Upload Documents +--- +
+ +In this how-to guide, we will upload documents to S3 buckets using the **S3 signed URL** from a ToolJet application. + +For this guide, we are going to use one of the existing templates on ToolJet: **S3 File explorer** + +
+ +
+ +## Create an App Using Templates + +- On ToolJet Dashboard, click on the ellipses on the right of the **Create new app** button, from the dropdown choose the **Choose from template** option. Select **AWS S3 file explorer** and click on the **Create application from template**. + + +
+ +Use S3 pre-signed URL to upload documents: Choose template + +
+ +- Go to the **Data sources** on the left-sidebar; you'll find that the **AWS S3 data source** has already been added. All you need to do is update the data source credentials. + +:::tip +Check the [AWS S3 data source reference](/docs/data-sources/s3) to learn more about connnection and choosing your preferred authentication method. +::: + +
+ +Use S3 pre-signed URL to upload documents: add datasource + +
+ +
+ +
+ +## Get the Buckets + +- Once the data source is connected successfully, go to the query manager and **Run** the *getBuckets* query. The operation selected in the *getBuckets* query is **List buckets**, which will fetch an array of all the buckets. + +
+ + Use S3 pre-signed URL to upload documents: getBuckets query + +
+ +- Running the *getBuckets* query will load all the buckets in the app's left table. + + + +
+ + Use S3 pre-signed URL to upload documents: loading buckets + +
+ +
+ +
+ +## Get the Objects Inside the Bucket + +- To fetch the data inside a bucket, select the bucket from the buckets table, go to the query manager and choose the *getObjects* query. Choose the relevant data source in the **Data Source** section, and for the **Operation** parameter, choose `List objects in a bucket` option from the dropdown. Replace the **Bucket** parameter with, `{{components.table2.selectedRow.Name}}` and click on the **Run** to list all the files from the selected bucket on the table. + + + +
+ + Use S3 pre-signed URL to upload documents: list objects in a bucket + +
+ +
+ +
+ +## Get the Signed URL for Downlaod + +The object owner can optionally share objects with others by creating a presigned URL, using their own security credentials, to grant time-limited permission to download the objects. For creating a presigned URL, in the query panel replace the parameters with the following: + +- **Data Source**: Use the relevant data source. +- **Operation**: Choose `Signed url for download` from the dropdown. +- **Bucket**: `{{components.table2.selectedRow.Name}}` to select the buckets dynamically. +- **Key**: `{{components.table3.selectedRow.Key}}`, this will get the file name from the filepickers exposed variables. +- **Expires in**: This sets an expiration time of URL, by default its `3600` seconds (1 hour). + +After setting up the parameters, click **Run** to run the query, and the URL can be accessed as shown in the screenshot. + +
+ + Use S3 pre-signed URL to upload documents: get signed URL + +
+ +
+ +
+ +## Upload Objects to the Bucket + +The `Upload Object` operation allows users to select a bucket and then upload their chosen data into that bucket. To upload objects in a bucket, follow the steps below: + +- In the query panel navigate to *uploadObject* query. +- Choose your relevant data source in the **Data Source** section. +- In the **Operation** section, choose `Upload Object` from the dropdown. +- In the **Bucket** section, copy the code: `{{components.table2.selectedRow.Name}}`, to choose a bucket dynamically. +- In the **Key** section, copy the code: `{{components.textinput2.value}}`. +- In the **Content Type** section, copy: `{{components.filepicker1.file[0].type}}`. +- In the **Upload data** section, copy: `{{components.filepicker1.file[0].dataURL}}`. + +To make sure the image is uploaded successfully, we can create a new event from the **Events** section. +- Under the `Events` section, click on **New event handler**. +- From the `Event` dropdown, choose `Query Success`. +- From the `Action` dropdown, choose `Show Alert`. +- The `Message` can be of your choice, in this example lets write the message as: `Image uploaded successfully`. + +Once the query has been created, choose the desired bucket, click on the **Upload file** button in the app, and upload your desired file to your bucket. + +
+ +
+ +## Access the Signed URL + +After uploading the file to your bucket, in the files table, click on the **Copy signed URL** button fromΒ the **Actions**Β section of the table, which will copy the URL on the clipboard. You can go to another tab and paste the URL to open the file on the browser. + +
+ + Use S3 pre-signed URL to upload documents: access signed URL + +
+ +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/use-to-py.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/use-to-py.md new file mode 100644 index 0000000000..b1ddd1f275 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/use-to-py.md @@ -0,0 +1,75 @@ +--- +id: use-to-py-function-in-runpy +title: "Translating JavaScript Objects to Python in RunPy" +--- +
+ +This guide demonstrates the utilization of the `to_py()` function in *RunPy* queries for converting JavaScript objects into their corresponding Python representations. + +
+ +
+ +## The to_py() Function + +The **to_py()** function within the **Pyodide** library serves as the counterpart to the **to_js()** function. Its purpose is to transform JavaScript objects into their equivalent Python structures. This conversion becomes essential when handling JavaScript objects within the Pyodide environment and manipulating them using Python code. + +Similar to **to_js()**, **to_py()** facilitates the mapping and conversion of data types between JavaScript and Python. It effectively converts JavaScript objects, arrays, and other data structures into their Python counterparts. + +**Note**: Refer to the **[RunPy](/docs/data-sources/run-py)** documentation for a more in-depth understanding. + +
+ +
+ +## Using the to_py() Function + +To test the working of `to_py`function, follow the steps mentioned below: + +- From the ToolJet dashboard, create a new app by clicking **Create an app** button. +- Once the app is created, navigate to the Query Panel, click on the **+ Add** button and choose **Run Python Code** as the Data Source. +- Use the code given below, in the *runpy* query code editor: + +```python +import pyodide # Import the Pyodide library + +def to_py(js_object): # Define a function to convert JavaScript objects to Python dictionaries + return dict(js_object) # Convert the JavaScript object to a Python dictionary + +my_js_object = {"name": "John", "age": 25, "country": "USA"} # Create a JavaScript object + +my_py_dict = to_py(my_js_object) # Convert the JavaScript object to a Python dictionary + +my_py_dict # Return the Python dictionary +``` + +In this example, a JavaScript object `my_js_object` is created using the `Object.fromEntries()` method, representing a dictionary-like structure. The `to_py()` function is then employed to convert this JavaScript object into a Python dictionary, resulting in `my_py_dict`. + +The output will be: +```json +{'name': 'John', 'age': 25, 'country': 'USA'} +``` + +By leveraging to_py(), JavaScript objects can seamlessly transition into Python representations, allowing for manipulation using Python code within the Pyodide environment. + +Both **to_js()** and **to_py()** functions offer a convenient means to exchange data between Python and JavaScript in Pyodide, enabling the utilization of both languages' strengths in a unified environment. + +
+ +
+ +## Why the Use of to_py() is Essential? + +- When previewing results in a *RunPy* query, discrepancies between the JSON and Raw tabs may arise due to the conversion and display mechanisms in **Pyodide**. By default, **Python dictionaries** are converted to **JavaScript Map objects** in Pyodide, ensuring compatibility between the two languages. + +- Consequently, the **JSON** tab presents data in the format of JavaScript objects, denoted by **()** symbols, while the **Raw** tab displays the raw representation as **[{}, {}, ...],** showing Python dictionaries in their original form with **{}** symbols. + +- Both representations are correct, with the JSON tab showcasing converted data compatible with JavaScript, and the Raw tab displaying the original Python dictionaries. The choice depends on the user's use case and whether they need to work with the data in a **JavaScript context** or **Python context**. + +- To maintain consistency between JSON and Raw representations, the `to_js()` function provided by Pyodide can explicitly convert Python dictionaries to JavaScript objects. This ensures alignment between representations and guarantees that the data is in the desired format. + +
+ Print data from multiple tabs +
+ +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/how-to/use-url-params-on-load.md b/docs/versioned_docs/version-3.16.0-LTS/how-to/use-url-params-on-load.md new file mode 100644 index 0000000000..63fbcf59ba --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/how-to/use-url-params-on-load.md @@ -0,0 +1,122 @@ +--- +id: use-url-params-on-load +title: Use URL Parameters on Page Load +--- +
+ +In this guide, we will learn how to use URL parameters at the time of page load. The URL parameters are used to pass data from one page to another. Currently, we can add URL parameters in the following ways: + +- From events through the [Switch page](/docs/actions/switch-page) action +- From the [JavaScript code](/docs/actions/switch-page/#switch-page-with-query-params) queries + +If a page is opened with URL parameters, you can access them using the `{{globals.urlparams}}`. This object contains all the URL parameters as key-value pairs and specific parameters can be accessed using the key like `{{globals.urlparams.}}`. + +Let's take a look at an example below to understand how to use URL parameters on page load. + +
+ +
+ +## Using URL Parameters on Page Load to Execute REST API Queries + +Create two pages, `Home` and `Dashboard`. When a new app is created, a page named `Home` is created by default. Create a new page named `Dashboard` from the Pages menu in the left sidebar. + +
+ Use URL Parameters on page load +
+ +
+ +
+ +## Home and Dashboard Pages + +Add a form component to the `Home` page. The form component will have a text input fields and a button. The text input field will be used to enter the name and the button will be used to navigate to the `Dashboard` page. Let's name the text input field as `email` and the button as `Submit`. + +
+ Use URL Parameters on page load +
+ +Select the button and add the event `On click`, select action `Switch page`, and then select the page `Dashboard`. Here, we will also find the option to add URL parameters. Add the URL parameter `email` and set the value to `{{components.form1.data.textinput1.value}}`. This will pass the value of the email input field to the `Dashboard` page as a URL parameter. + +
+ Use URL Parameters on page load +
+ +Now, on clicking the `Submit` button, the `Dashboard` page will be opened with the URL parameter `email` containing the value of the email input field. You can open the Inspector on left sidebar and navigate to the `URL Params` under the `globals` to check the URL parameters. + +
+ Use URL Parameters on page load +
+ +
+ +
+ +## Queries and Binding Data + +In the `Dashboard` page, add two table components. We will be loading the data from two different REST API queries on these tables. + +### Query 1: Get Products + +- Create a new REST API query and name it as `products`. We will be using a mock REST API to fetch the data. The URL for the REST API is `https://fakestoreapi.com/products`. Run the query and check the preview to see the returned data. +- Go to the `table1` properties, set the value of table data to `{{queries.products.data}}`. This will bind the data returned from the REST API query to the table. + +
+ Use URL Parameters on page load +
+ +### Query 2: Get User Details + +- Create a new REST API query and name it as `users`. We will be using a mock REST API to fetch the data. The URL for the REST API is `https://jsonplaceholder.typicode.com/users`. Run the query and check the preview to see the returned data. +- Go to the `table2` properties, set the value of table data to `{{queries.users.data}}`. This will bind the data returned from the REST API query to the table. + +
+ Use URL Parameters on page load +
+ +### Query 3: JavaScript Code To Use URL Parameters + +- Create a new JavaScript code query and name it as `urlparams`. We will be using this query to access the URL parameters and to check if the email parameter is present in the URL, then trigger the REST API queries. + +```javascript +function waitForURLParams(timeout) { // Wait for URL parameters to be available + const check = resolve => { // Check if URL parameters are available + if (location.search.length > 0) resolve(); // URL parameters are available + else setTimeout(_ => check(resolve), timeout); // Check again after a timeout + } + return new Promise(check); // Return a promise that resolves when URL parameters are available +} + +async function checkAndRunQuery(timeout) { // Check if URL parameters are available and run the REST API queries + await waitForURLParams(timeout); // Wait for URL parameters to be available + const urlParams = new URLSearchParams(window.location.search); // Get URL parameters + + if (urlParams.get('email')) { // Check if email parameter is present in the URL + await actions.runQuery('products'); // Run the REST API query to get products + await actions.runQuery('users'); // Run the REST API query to get user details + } + else { + alert('URL param not found'); // Alert if email parameter is not present in the URL + } +} + +checkAndRunQuery(5000); // Check if URL parameters are available and run the REST API queries after a timeout of 5 seconds +``` + +
+ +
+ +## Dashboard Page Event Handler + +- Finally, go to the Pages menu in the left sidebar and open the menu for the `Dashboard` page. +- Select the option to add Event handler and add a new `On page load`, select the option to `Run query` and select the query `urlparams`. This will trigger the JavaScript code query to check if the email parameter is present in the URL and then run the REST API queries whenever the `Dashboard` page is loaded. + +
+ Use URL Parameters on page load +
+ +Now, whenever the user will enter the email in the `Home` page and click the `Submit` button, the `Dashboard` page will be opened with the URL parameter `email` containing the value of the email input field. The JavaScript code query will check if the email parameter is present in the URL and then run the REST API queries to fetch the data. The data will be displayed in the tables on the `Dashboard` page. + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/marketplace_overview.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/marketplace_overview.md new file mode 100644 index 0000000000..736fa4755f --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/marketplace_overview.md @@ -0,0 +1,87 @@ +--- +id: marketplace-overview +title: 'Marketplace: Overview' +--- + +# Marketplace: Overview + +ToolJet Marketplace allows users to enhance their workspaces by adding custom plugins (data sources) tailored to their unique requirements. This functionality facilitates the seamless integration of user-created plugins with ToolJet. + +
+ Marketplace Overview +
+ +
+ +## Installing a Plugin + +To navigate to the Marketplace page, click on the settings icon on the bottom left of the dashboard, and click on **Marketplace** from the selection menu. + +The Marketplace page will contain two tabs: **Installed** and **Marketplace**. + +Under the **Marketplace** tab, you will see a list of all the available plugins that can be installed on the workspace. To install a plugin, click on the **Install** button on the plugin's card. Once the installation is complete, the status will change from Install to **Installed**. + +
+ List of All Plugins +
+ +
+ +
+ +## Using Marketplace Plugins + +You can access any installed plugins by following these steps: + +- Navigate to the **Data sources** tab in the dashboard. +- Scroll down to **Plugins**. + +You can now see the list of installed marketplace plugins that you can configure as data sources. + +
+ Installed plugins +
+ +- After successfully configuring a plugin, you can access it when trying to add a new query from the Query Panel. + +## Removing a Plugin + +:::caution +If you remove a plugin, all the queries associated with it will be eliminated from the applications. +::: + +To remove a plugin, follow these steps: +- Click on the settings icon on the bottom left of the dashboard, and click on `Marketplace` from the selection menu. +- On the `Installed` page, click on the `Remove` button of the related plugin that you wish to remove. + +## Available Plugins +- **[Anthropic](/docs/marketplace/plugins/marketplace-plugin-anthropic)** +- **[AWS Redshift](/docs/marketplace/plugins/marketplace-plugin-awsredshift)** +- **[AWS Textract](/docs/marketplace/plugins/marketplace-plugin-textract)** +- **[AWS Lambda](/docs/marketplace/plugins/marketplace-plugin-aws-lambda)** +- **[Cohere](/docs/marketplace/plugins/marketplace-plugin-cohere)** +- **[Engagespot](/docs/marketplace/plugins/marketplace-plugin-engagespot)** +- **[Gemini](/docs/marketplace/plugins/marketplace-plugin-gemini)** +- **[GitHub](/docs/marketplace/plugins/marketplace-plugin-github)** +- **[Google Calendar](/docs/marketplace/plugins/marketplace-plugin-googlecalendar)** +- **[HarperDB](/docs/marketplace/plugins/marketplace-plugin-harperdb)** +- **[Hugging Face](/docs/marketplace/plugins/marketplace-plugin-hugging_face)** +- **[Jira](/docs/marketplace/plugins/marketplace-plugin-jira)** +- **[Mistral AI](/docs/marketplace/plugins/marketplace-plugin-mistral_ai)** +- **[OpenAI](/docs/marketplace/plugins/marketplace-plugin-openai)** +- **[Pinecone](/docs/marketplace/plugins/marketplace-plugin-pinecone)** +- **[Plivo](/docs/marketplace/plugins/marketplace-plugin-plivo)** +- **[Pocketbase](/docs/marketplace/plugins/marketplace-plugin-pocketbase)** +- **[Portkey](/docs/marketplace/plugins/marketplace-plugin-portkey)** +- **[PrestoDB](/docs/marketplace/plugins/marketplace-plugin-Presto)** +- **[Qdrant](/docs/marketplace/plugins/marketplace-plugin-qdrant)** +- **[Salesforce](/docs/marketplace/plugins/marketplace-plugin-salesforce)** +- **[Sharepoint](/docs/marketplace/plugins/marketplace-plugin-sharepoint)** +- **[Supabase](/docs/marketplace/plugins/marketplace-plugin-supabase)** +- **[Weaviate](/docs/marketplace/plugins/marketplace-plugin-weaviate)** + +:::info For Plugin Developers +Refer to the **[Plugin Development guide](/docs/contributing-guide/marketplace/marketplace-setup)** to learn how to create plugins for the ToolJet Marketplace. +::: + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/amazon-redshift.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/amazon-redshift.md new file mode 100644 index 0000000000..c3681fa367 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/amazon-redshift.md @@ -0,0 +1,119 @@ +--- +id: marketplace-plugin-awsredshift +title: Amazon Redshift +--- + +ToolJet can connect to Amazon Redshift, enabling your applications to query data directly from a Redshift cluster. + + +
+ Marketplace Plugin: Amazon Redshift +
+ +
+ +**NOTE:** **Before following this guide, it is assumed that you have already completed the process of [Using Marketplace plugins](/docs/marketplace/marketplace-overview#using-marketplace-plugins)**. + +
+ +## Configuration + +To connect to Amazon Redshift, you need to provide the following details: + +#### Required Parameters + +- **Region**: The region where your Redshift cluster is located. For example, `us-east-1`. +- **Database Name**: The name of the database you want to connect to. +- **Authentication Type**: The type of authentication you want to use to connect to the Redshift cluster. Currently, only **IAM** is supported. +- **Access Key**: The access key of the user you want to use to connect to the Redshift cluster. +- **Secret Key**: The secret key of the user you want to use to connect to the Redshift cluster. + +#### Optional Parameters + +- **Port**: The port number of the Redshift cluster. The default port number is `5439`. +- **Workgroup name**: The name of the workgroup you want to use to connect to the Redshift cluster. + +
+ Marketplace Plugin: Amazon Redshift +
+ +
+ +
+ +## Supported Queries + +Redshift supports a comprehensive set of SQL commands. You can use the SQL editor to run any SQL query on the connected Redshift cluster. Refer to the [Redshift documentation](https://docs.aws.amazon.com/redshift/latest/dg/c_SQL_commands.html) for more information on the supported SQL commands. + +
+ +
+ +### Read Data + +The following example demonstrates how to read data from a table in the connected Redshift cluster. The query selects all the columns from the `employee` table. + +```sql +SELECT * FROM employee +``` + +
+ +
+ +### Write Data + +The following example demonstrates how to write data to a table in the connected Redshift cluster. The query inserts a new row into the `employee` table. + +```sql +INSERT INTO employee ( + first_name, + last_name, + email, + phone_number, + hire_date, + job_title, + salary, + department_id +) VALUES ( + 'Tom', + 'Hudson', + 'tom.hudson@example.com', + '234843294323', + '2024-01-01', + 'Test Automation Engineer', + 245000.00, + 12 +); +``` + +
+ +
+ +### Update Data + +The following example demonstrates how to update data in a table in the connected Redshift cluster. The query updates the `first_name` and `last_name` columns of the `employee` table. + +```sql +UPDATE employee +SET first_name = 'Glenn', + last_name = 'Jacobs' +WHERE employee_id = 8; +``` + +
+ +
+ +### Delete Data + +The following example demonstrates how to delete data from a table in the connected Redshift cluster. The query deletes a row from the `employee` table. + +```sql +DELETE FROM employee +WHERE employee_id = 7; +``` + +
+ diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/anthropic.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/anthropic.md new file mode 100644 index 0000000000..431a0f5f69 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/anthropic.md @@ -0,0 +1,53 @@ +--- +id: marketplace-plugin-anthropic +title: Anthropic +--- + +Integrating Anthropic with ToolJet enables the creation of interactive chatbots that analyze past messages to generate context-aware responses. These bots can also be customized with defined roles, making them suitable for tasks such as customer support, serving as virtual assistants, or enabling personalized conversations. + +## Connection + +To connect with Anthropic, you will need the **API Key**, which can be generated from **[Anthropic Console](https://console.anthropic.com/)**. + +Anthropic Configuration + +## Supported Operations + +### Chat + +This operation processes the user's input and generates appropriate, context-aware responses, simulating a natural, human-like conversation. It can handle multiple interactions while maintaining the flow of dialogue, enabling dynamic and engaging conversations. + +**Required Parameters** + +- **Model**: The model to use for generating the chat response. The available models are: + - claude-3-5-sonnet-20241022 + - claude-3-5-haiku-20241022 + - claude-3-opus-20240229 + - claude-3-sonnet-20240229 + - claude-3-haiku-20240307 + +- **Message**: Messages act as input interactions between the user and the model. In the Roles parameter, you can choose either User or Assistant. + +- **Max Size**: Maximum tokens used in response. + +**Optional Parameters** + +- **System Prompt**: Defines the role and context of the model to evaluate messages and generate a response. + +- **Temperature**: Controls the randomness of the response. Accepts values between 0 and 1, with a default of 1. + +Anthropic Query + +
+**Response Example** + +```json +[ + { + "type": "text", + "text": "AI has numerous significant benefits in healthcare. Here are some key advantages:nn1. Diagnosis and Disease Detectionn- Faster and more accurate diagnosis through image analysis (X-rays, MRIs, CT scans)n- Early detection of diseases like cancern- Pattern recognition in patient symptoms and medical historynn2. Treatment Planningn- Personalized treatment recommendationsn- Drug interaction predictionsn- Treatment outcome forecastingn- Precision medicine based on patient datann3. Administrative Tasksn- Automated appointment schedulingn- Medical record managementn- Billing and insurance processingn- Reducing paperwork and administrative burdennn4. Patient Caren- Remote patient monitoringn- Virtual health assistantsn- Personalized care recommendationsn- Medication adherence trackingnn5. Research and Drug Developmentn- Accelerated drug discoveryn- Clinical trial matchingn- Analysis of medical research datan- Identification of new treatment approachesnn6. Preventive Caren- Risk prediction and assessmentn- Population health managementn- Lifestyle recommendationsn- Early intervention opportunitiesnn7. Cost Reductionn- Improved efficiencyn- Reduced medical errorsn- Better resource allocationn- Streamlined operationsnn8. Accessibilityn- 24/7 availability of basic healthcare informationn- Improved access to healthcare in remote areasn- Reduced wait timesn- Better distribution of medical expertisennThese benefits continue to expand as AI technology advances and becomes more integrated into healthcare systems." + } +] +``` + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/azurerepos.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/azurerepos.md new file mode 100644 index 0000000000..b63211d0a2 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/azurerepos.md @@ -0,0 +1,120 @@ +--- +id: marketplace-plugin-azurerepos +title: Azure Repos +--- + +ToolJet offers the capability to establish a connection with Azure Repos in order to read from and commit to Git repositories for source control and version management. + +## Connection + +To connect with Azure Repos, you will need the **Organization Name (e.g., https://dev.azure.com/your-organization)** and a **Personal Access Token (PAT)**. +Generate a Personal Access Token(PAT) by navigating to User Settings, then selecting Personal Access Tokens. Ensure the token includes the necessary scopes based on the operations you want to perform. + +get azure repository + +## Supported Operations + +1. **[Get Azure Repository](#get-azure-repository)** +2. **[Get Repository Commits](#get-repository-commits)** +3. **[Get Repository Branches](#get-repository-branches)** +4. **[Get Repository Pushes](#get-repository-pushes)** +5. **[Get Project Pull Requests](#get-project-pull-requests)** + +### Get Azure Repository + +Retrieves details of a specific repository within your Azure DevOps project. + +#### Required Parameter + +- **Project** + +get azure repository + +
+**Example Values** + +```json +Project: test +``` + +
+ +### Get Repository Commits + +Fetches a list of commits made to a selected repository. + +#### Required Parameter + +- **Project** + +get repository commits + +
+**Example Values** + +```json +Project: test +``` + +
+ +### Get Repository Branches + +Lists all branches available in a specified Azure repository. + +#### Required Parameter + +- **Project** + +get repository branches + +
+**Example Values** + +```json +Project: test +Repository commits: ToolJet +``` + +
+ +### Get Repository Pushes + +Retrieves information about recent pushes made to the repository. + +#### Required Parameter + +- **Project** + +get repository pushes + +
+**Example Values** + +```json +Project: test +Repository commits: ToolJet +``` + +
+ +### Get Project Pull Requests + +Fetches pull requests associated with the selected project and repository. + +#### Required Parameter + +- **Project** + +get project pull requests + +
+**Example Values** + +```json +Project pull requests: test +``` + +
+ + diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/cohere.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/cohere.md new file mode 100644 index 0000000000..190ee047c6 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/cohere.md @@ -0,0 +1,168 @@ +--- +id: marketplace-plugin-cohere +title: Cohere +--- + +Cohere can be integrated with ToolJet to use its advanced AI models for tasks such as text generation or building a chatbot assistant by configuring parameters to optimize results. + +## Connection + +To connect with Cohere, you will need the **Access token**, which can be generated from **[Cohere Dashboard](https://dashboard.cohere.com/api-keys)**. + +Cohere Configuration + +## Supported Operations + +### Text Generation + +Use this operation to generate creative text content by selecting the desired model and defining additional parameters. + +**Required Parameters** + +- **Model**: The model to use for generating the text. The available models are: + - command-r7b-12-2024 + - command-r-plus-08-2024 + - command-r-plus-04-2024 + - command-r-plus + - command-r-08-2024 + - command-r-03-2024 + - command-r + - command + - command-nightly + - command-light + - command-light-nightly + - c4ai-aya-expanse-8b + - c4ai-aya-expanse-32b + +- **Message**: The main user input for generating response. + +**Optional Parameter** + +- **Advanced parameters**: Additional parameters to configure the model response. Refer [Advanced Parameters](#advanced-parameters) for more information. + +Example Parameters: + +```js +{ + "response_format": {"type": "text"}, + "temperature": 0.3, + "max_tokens": 512, + "seed": 3, + "p": 0.3, + "k": 1, + "frequency_penalty": 0.3, + "presence_penalty": 0.3, + "citation_options": {"mode": "fast"}, + "safety_mode": "off", + "stop_sequences": ["spam", "fraud"] +} +``` + +Cohere Text generation + +
+**Response Example** + +ToolJet is an open-source no-code platform that allows you to build your own tools and automate your workflows in minutes. It is built on top of the powerful Airbyte open-source standard for data integration, focusing on user-friendliness and extensibility. With ToolJet, you can create custom solutions for your business without any prior coding knowledge. + +Here's a high-level overview of the features and capabilities of ToolJet: + +1. **No-Code Builder**: ToolJet offers a visual interface where you can quickly create powerful applications, workflows, and automation scripts without writing a single line of code. + +2. **Data Integration**: ToolJet leverages Airbyte to provide seamless data integration capabilities. You can sync data from various sources like databases, APIs, or SaaS applications to build custom dashboards, data pipelines, or extensions. + +3. **Visual Automation Builder**: Create automated workflows using a drag-and-drop interface. Connect various tools, apps, and APIs to automate tasks, notifications, data manipulation, and more. + +4. **Open Source**: Being open-source means you get full transparency over the platform's underlying code. Plus, you can contribute to the project and customize or extend it according to your needs. + +5. **Extensions & APIs**: ToolJet provides a marketplace for sharing and discovering extensions, APIs, and pre-built workflows. You can extend the functionality of ToolJet with community-built solutions. + +6. **Dashboard & Reports**: Create interactive dashboards and reports using the built-in charting and visualization tools. Visualize data from various sources in one place and share insights with your team. + +7. **Forms & UI**: Easily create forms and user interfaces using ToolJet's intuitive form builder. Collect data, feedback, or insights from your users or systems. + +8. **Collaboration & Security**: Control user access and permissions with robust security features. Collaborate with team members on different projects and ensure data privacy and compliance. + +9. **Integration with External Tools**: ToolJet integrates with popular productivity, collaboration, and data tools, including Slack, Google Workspace, Microsoft Office, Airbyte, and more. + +10. **Open API & Extensibility**: ToolJet has a robust application programming interface (API), which allows developers to extend its capabilities. You can customize and connect any external service or application. + +ToolJet is a versatile platform that spans several use cases, including business process automation, data management, workflow optimization + +
+ +### Chat + +Use this operation for a chat-like conversation, where the model responds based on the given prompts and instructions. It provides relevant and context-appropriate answers, maintaining a smooth conversational flow. + +**Required Parameters** + +- **Model**: Specifies the model to use for generating responses in the chat. The available models are: + - command-r7b-12-2024 + - command-r-plus-08-2024 + - command-r-plus-04-2024 + - command-r-plus + - command-r-08-2024 + - command-r-03-2024 + - command-r + - command + - command-nightly + - command-light + - command-light-nightly + - c4ai-aya-expanse-8b + - c4ai-aya-expanse-32b + +- **History**: Keeps track of previous interactions to maintain context in the conversation. + +- **Message**: The main user input for generating response in the chat. + +**Optional Parameter** + +- **Advanced parameters**: Additional parameters to configure the model response. Refer [Advanced Parameters](#advanced-parameters) for more information. + +Example Parameters: + +```js +{ + "response_format": {"type": "text"}, + "temperature": 0.3, + "max_tokens": 512, + "seed": 3, + "p": 0.3, + "k": 1, + "frequency_penalty": 0.3, + "presence_penalty": 0.3, + "citation_options": {"mode": "fast"}, + "safety_mode": "off", + "stop_sequences": ["spam", "fraud"] +} +``` + +Cohere Chat + +
+**Response Example** + +ToolJet is a no-code platform that allows you to build custom internal tools with drag and drop functionality. You can integrate Cohere with ToolJet to enable an added advantage of AI features in your apps built on ToolJet. + +To integrate Cohere AI into your ToolJet app, you should have a Cohere AI API key. If you don't have one, you can sign up for a free Cohere AI account and get your API key. + +As a next step, you can refer to our documentation to see a step-by-step guide to integrate Cohere AI with ToolJet. If you have any further questions, please let me know! + +
+ +## Advanced Parameters + +| Parameter| Description | +|----------|-------------| +| Response Format | Configure the model to give output in specified format. | +| Temperature | Controls the degree of randomness of the output. | +| Max Tokens | The maximum number of tokens the model will generate as part of the response. | +| Seed | Set to ensure consistent results by initializing the generator. | +| P | Use to limit randomness by setting a probability threshold. | +| K | Defines the use of the top k most likely tokens for generation at each step. | +| Frequency Penalty | Use to discourage frequent word usage for more varied responses. | +| Presence Penalty | Use to reduce repetition of words or phrases. | +| Citation Options | Options for controlling citation generation. | +| Safety Mode | Use to select the safety instruction inserted into the prompt. Allowed values: CONTEXTUAL, STRICT, OFF | +| Stop Sequences | Defines a list of up to 5 strings that, when matched, will stop the generation and return the text generated so far. | \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/engagespot.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/engagespot.md new file mode 100644 index 0000000000..b3f873caf0 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/engagespot.md @@ -0,0 +1,126 @@ +--- +id: marketplace-plugin-engagespot +title: Engagespot +--- + +# Engagespot + +ToolJet connects to your Engagespot account, allowing you to send notifications, create or update users from within your ToolJet application. + +:::info +**NOTE:** **Before following this guide, it is assumed that you have already completed the process of [Using Marketplace plugins](/docs/marketplace/marketplace-overview#using-marketplace-plugins)**. +::: + +
+ +## Connection + +- Establish a connection to Engagespot by either clicking `+Add new Data source` on the query panel or navigating to the [Data Sources](/docs/data-sources/overview/) page from the ToolJet dashboard. + +- Enter your Engagespot API key and API secret into their designated fields. To generate user tokens directly from ToolJet, you can optionally provide a signing key. + +- Click **Test Connection** to validate your credentials. Click **Save** to store the data source. + +
+ Engagespot API Key +
+ +:::info +You can change your Engagespot BaseURL by enable custom endpoint. +::: + +
+ +
+ +## Querying Engagespot + +Click on `+Add` button of the [query manager](/docs/app-builder/query-panel/#query-manager) and select the data source added in the previous step as the data source. Select the operation that you want to perform, fill in the required parameters and click on **Run** button to run the query. + +
+ +engagespot query + +
+ +
+ +:::info +Query results can be transformed using transformations. Read our [transformations documentation](/docs/beta/app-builder/custom-code/transform-data). +::: + +
+ +
+ +## Query Operations + +You can create query for Engagespot data source to perform several actions such as: + +1. **[Create or Update User](#create-or-update-user)** +2. **[Send Notification](#send-notification)** +3. **[Generate User Token](#generate-user-token)** + +
+ +
+ +### Create OR Update User + +#### Required Parameters: + +- **User Identifier** - Unique user identifier. + +
+engagespot create user +
+
+ +:::info +The user profile column accepts any key-value pairs in valid JSON object format. +::: + +
+ +
+ +### Send Notification + +#### Required Parameters: + +- **Reciepient** - Unique user identifier. +- **Notification Title** - The title for your notification. + +
+engagespot send notitication +
+
+ +
+ +
+ +### Generate User Token + +#### Required Parameters: + +- **User Identifier** - Unique user identifier. + +
+engagespot generate token +
+
+ +:::info +To generate user tokens, ensure you provide a Signing Key when establishing a connection to your Engagespot data source. +::: + +
+ +
+ +### Adding the In-App Inbox element to your ToolJet app + +To set up an In-App Inbox element in your ToolJet application, refer to the [Adding In-App](https://docs.engagespot.co/docs/plugins/tooljet/adding-the-inbox-component) guide. + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/gemini.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/gemini.md new file mode 100644 index 0000000000..55866d8a1a --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/gemini.md @@ -0,0 +1,115 @@ +--- +id: marketplace-plugin-gemini +title: Gemini +--- + +Google Gemini can be integrated with ToolJet to build context-aware, intelligent chatbots or generate creative text content. + +## Connection + +To connect with Gemini, you will need the **API Key**, which can be generated from **[Google AI Studio](https://aistudio.google.com/apikey)**. + +Gemini Configuration + +## Supported Operations + +### Text Generation + +Use this operation to generate text based on the prompt, system instructions, and model settings. It provides information or explanations tailored to the given context. + +**Required Parameters** + +- **Model**: Specifies the Gemini model to use for generating responses. + - Gemini 1.5 Flash + - Gemini 1.5 Flash-8B + - Gemini 1.5 Pro + - Gemini 2.0 Flash + +- **Prompt**: The main user input for generating responses. + +**Optional Parameter** + +- **System Prompt**: A predefined instruction guiding the model's tone and behavior. + +- **Max Tokens**: Limits the maximum number of tokens (words and characters) in the response. + +- **Temperature**: Defines the randomness of the response. It takes a value between 0 and 1, with a default of 1. + +Gemini Query + +
+**Response Example** + +Connecting ToolJet to a database involves several steps, and the specific method depends on the type of database you're using. ToolJet primarily uses database connections through its built-in features, avoiding the need for complex configuration files or external tools. Here's a general guide, focusing on common scenarios: + +**1. Choose Your Database and Connection Method:** + +ToolJet supports various database systems, including: + +* **PostgreSQL:** A powerful, open-source relational database management system. +* **MySQL:** Another popular open-source relational database system. +* **SQLite:** A lightweight, file-based database system, often suitable for smaller projects. +* **MongoDB:** A NoSQL database system, ideal for handling unstructured or semi-structured data. + +**2. Setting Up the Database:** + +* **Ensure the database server is running and accessible.** This includes having the database software installed and configured. +* **Create a database:** Within the database server, you'll need to create a new database. +* **Create a user account with appropriate privileges:** This user account needs permissions to connect to the database and perform read/write operations. Crucially, ensure the user has the necessary permissions for your application's needs. For example, you will need `SELECT`, `INSERT`, `UPDATE`, and `DELETE` permissions if you're performing CRUD operations. +* **Determine the database credentials:** You'll need the database server's hostname/IP address, the database name, the username, and the password for the user account. + +**3. Connecting in ToolJet:** + +* **Navigate to the relevant ToolJet app/page where database interaction is needed.** +* **Utilize ToolJet's database connectors:** Look for sections or widgets in ToolJet that allow you to interact with databases. This is typically integrated into the data sources, data manipulation features, or custom functions. +* **Provide the database connection details:** Input the database server details (hostname/IP, port, database name, username, password). ToolJet will validate the connection. +* **Choose the database type:** Select the correct database type (e.g., PostgreSQL, MySQL, SQLite, MongoDB). +* **Test the connection:** ToolJet will attempt to connect to the database. Verify the success of the connection. If successful, you should be able to query the database within ToolJet's + +
+ +### Chat + +Use this operation for a chat-like conversation, where the model responds based on the given prompts and instructions. It provides relevant and context-appropriate answers, maintaining a smooth conversational flow. + +**Required Parameters** + +- **Model**: Specifies the Gemini model to use for generating responses in the chat. + - Gemini 1.5 Flash + - Gemini 1.5 Flash-8B + - Gemini 1.5 Pro + - Gemini 2.0 Flash + +- **User Prompt**: The user's question or request that the model will respond to. + +**Optional Parameter** + +- **System Prompt**: Provides the model with guidance on the style and type of responses expected. + +- **History**: Keeps track of previous interactions to maintain context in the conversation. + +- **Max Tokens**: Limits the maximum number of tokens (words and characters) in the response. + +- **Temperature**: Defines the randomness of the response. It takes a value between 0 and 1, with a default of 1. + +Gemini Query + +
+**Response Example** + +Integrating an API into ToolJet involves several steps, depending on the API's specifics (REST, GraphQL, etc.) and the desired functionality within your ToolJet application. Here's a breakdown of the process: + +**1. Understanding Your API:** + +* **Authentication:** How does the API authenticate requests? (API Key, OAuth 2.0, Basic Auth, etc.) This is crucial and will directly impact your ToolJet configuration. +* **Endpoints:** Identify the specific API endpoints you need to interact with. Note the HTTP methods (GET, POST, PUT, DELETE) for each endpoint. +* **Request Parameters:** Understand what parameters (query parameters, request body) each endpoint expects. Data types are important (string, integer, JSON, etc.). +* **Response Format:** Determine the format of the API's response (usually JSON or XML). ToolJet primarily works with JSON. + +
+ + + + + + diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/github.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/github.md new file mode 100644 index 0000000000..02e80198da --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/github.md @@ -0,0 +1,77 @@ +--- +id: marketplace-plugin-github +title: GitHub +--- + +ToolJet offers seamless integration with GitHub. This connection allows you to directly interact with GitHub repositories and data. + +## Connection + +To connect to GitHub, you need the following credential: +- **Personal Access Token**: You can generate this token through your **[GitHub Account Settings](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)**. + +You'll need a Personal Access Token to access data from private repositories. Public repository data remains accessible without a Personal Access Token. + +Marketplace: GitHub + +## Supported Queries + +- **[Get user info](#get-user-info)** +- **[Get repository](#get-repository)** +- **[Get repository issues](#get-repository-issues)** +- **[Get repository pull requests](#get-repository-pull-requests)** + +### Get User Info + +This operation fetches details for a specified user. + +#### Required Parameter + +- **Username**: Specify the GitHub username or organization to retrieve their details. + +Marketplace: GitHub + +### Get Repository + +Fetches detailed information about a specific repository. + +#### Required Parameters + +- **Owner**: Name of the repository's owner, which can be either a GitHub user or an organization. +- **Repository**: The exact name of the repository. + +Marketplace: GitHub + +### Get Repository Issues + +Generates a list of issues associated with a repository, with options to filter them by their status. + +#### Required Parameters + +- **Owner**: The name of the repository's owner. The owner can either be a GitHub organization or a user. +- **Repository**: The repository name for which the issues are to be retrieved. +- **State**: Filter the issues by their status: All, Open, or Closed. + +#### Optional Parameters + +- **Page size**: Desired number of issues per page. Default is 30. +- **Page number**: Desired page number to fetch issues from. Default is 1. + +Marketplace: GitHub + +### Get Repository Pull Requests + +Generates a list of pull requests from a repository, with options to filter them by their status. + +#### Required Parameters + +- **Owner**: The name of the repository's owner. The owner can either be a GitHub organization or a user. +- **Repository**: The repository name for which the pull requests are to be retrieved. +- **State**: Filter the pull requests by their status: All, Open, or Closed. + +#### Optional Parameters + +- **Page size**: Desired number of issues per page. Default is 30. +- **Page number**: Desired page number to fetch pull requests from. Default is 1. + +Marketplace: GitHub diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/google-calendar.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/google-calendar.md new file mode 100644 index 0000000000..360d7c40fa --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/google-calendar.md @@ -0,0 +1,75 @@ +--- +id: marketplace-plugin-googlecalendar +title: Google Calendar +--- + +ToolJet can connect to Google Calendar to fetch, create, update, and delete calendar events directly from your ToolJet application. + +## Connection + +You will need the following credential to connect with Google Calendar: + - **Client ID** + - **Client Secret** + +These credentials are used to authenticate via OAuth2 and access calendar data securely. You can review all available permission scopes [here](https://developers.google.com/workspace/calendar/api/auth). + +You can toggle on **Authentication required for all users** in the configuration. When enabled, users will be redirected to the OAuth consent screen the first time a query from this data source is triggered in the application. This ensures each user connects their own Google Calendar account securely. + +Note: After completing the OAuth flow, the query must be triggered again to load the data. + +Hugging Face Configuration + +### Generating Client ID and Client Secret + + +1. Go to **[Google Cloud console](https://console.cloud.google.com/)** and create a project. + Create New Project +2. Go to the **[Google Cloud console credentials page](https://console.cloud.google.com/apis/credentials)**, and create an OAuth client ID. + General Settings: SSO +3. You'll be asked to select user type in consent screen. To allow only users within your workspace, select 'Internal', otherwise, +select 'External'. + General Settings: SSO +4. After configuring the consent screen you will be redirected to OAuth overview page, click on **Create OAuth client**. +5. Then on the Clients page, select the Application type as **Web application**, and give it a name, under Authorised JavaScript origins, set the domain on which ToolJet is hosted and under Authorized redirect URIs, enter the Redirect URL which was generated in ToolJet's data source configuration page. + General Settings: SSO +6. Click on **Create** and copy the **Client ID** and **Client Secret**. + General Settings: SSO + +## Supported Operations + +### Calendars + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/calendars/{calendarID}` | Get calendar details. | +| PUT | `/calendars/{calendarID}` | Update a calendar. | +| DELETE | `/calendars/{calendarID}` | Delete a calendar. | +| POST | `/calendars` | Create a calendar. | +| GET | `/users/me/calendarList` | List calendars accessible to the user. | + +### Events + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/calendars/{calendarID}/events` | List events. | +| POST | `/calendars/{calendarID}/events` | Create an event. | +| GET | `/calendars/{calendarID}/events/{eventID}` | Get event details. | +| PUT | `/calendars/{calendarID}/events/{eventID}` | Update an event. | +| DELETE | `/calendars/{calendarID}/events/{eventID}` | Delete an event. | +| POST | `/calendars/{calendarID}/events/quickAdd` | Quick add event. | + +### Access Control (ACL) + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/calendars/{calendarID}/acl` | List access control rules. | +| POST | `/calendars/{calendarID}/acl` | Create an access control rule. | +| GET | `/calendars/{calendarID}/acl/{ruleID}` | Get an access control rule. | +| PUT | `/calendars/{calendarID}/acl/{ruleID}` | Update an access control rule. | +| DELETE | `/calendars/{calendarID}/acl/{ruleID}` | Delete an access control rule. | + +### Free/Busy + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/freeBusy` | Query free/busy information. | \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/harperdb.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/harperdb.md new file mode 100644 index 0000000000..eb6162d6b9 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/harperdb.md @@ -0,0 +1,288 @@ +--- +id: marketplace-plugin-harperdb +title: HarperDB +--- + +HarperDB is a database and application development platform that is focused on performance and ease of use. With flexible user-defined APIs, simple HTTP/S interface, and a high-performance single-model data store that accommodates both NoSQL and SQL workloads, HarperDB scales with your application from proof of concept to production. ToolJet integrates with HarperDB, providing a streamlined interface for reading and writing data. + +
+ +Marketplace: HarperDB + +
+ +:::note +Before following this guide, it is recommended to check the following doc: **[Using Marketplace plugins](/docs/marketplace/marketplace-overview#using-marketplace-plugins)**. +::: + +
+ +## Connection + +To establish a connection with HarperDB, you need the following credentials: +1. **Host**: The hostname or IP address of your HarperDB instance (e.g., `162.156.250.74` or `myinstance.harperdbcloud.com`). +2. **Port**: The port number configured for your server (default is `9925`). If you are using HarperDB Studio(cloud), leave the field empty or set it to `443`. +3. **SSL**: Indicates whether the connection requires SSL encryption. +4. **Username**: Your authentication username for HarperDB instance. +5. **Password**: Your password for authentication (hidden for security purposes). + +
+ +Marketplace: HarperDB + +
+ +
+ +
+ +## Querying HarperDB +To perform queries on HarperDB, click the `+Add` button in the query manager located at the bottom panel of the app builder. Select the HarperDB from the Global Datasource section in the query editor. + +
+ +Marketplace: HarperDB + +
+ +
+ +
+ +### SQL Mode + +SQL mode enables you to perform various operations on the database using SQL statements. + +- **[Select](#select)** +- **[Insert](#insert)** +- **[Update](#update)** +- **[Delete](#delete)** + +#### Select +The SELECT statement is used to query data from the database. + +Syntax: +```sql +SELECT * FROM sampleorg.people WHERE id = 1 +``` + +
+ +Marketplace: HarperDB + +
+ +#### Insert +The INSERT statement is used to add one or more rows to a database table. + +Syntax: +```sql +INSERT INTO sampleorg.people (id, name, age, country, hobby) VALUE (5, 'Shubh', 26, 'India', 'Football') +``` + +
+ +Marketplace: HarperDB + +
+ +#### Update +The UPDATE statement is used to change the values of specified attributes in one or more rows in a database table. + +Syntax: +```sql +UPDATE sampleorg.people SET hobby = 'chess' WHERE id = 5 +``` + +
+ +Marketplace: HarperDB + +
+ +#### Delete +The DELETE statement is used to remove one or more rows of data from a database table. + +Syntax: +```sql +DELETE FROM sampleorg.people WHERE id = 5 +``` + +
+ +Marketplace: HarperDB + +
+ +
+ +
+ +### NoSQL Mode + +NoSQL mode enables you to perform schema-less storage and retrieval of JSON documents. + +- **[Insert](#insert-nosql)** +- **[Update](#update-nosql)** +- **[Delete](#delete-nosql)** +- **[Search by hash](#search-by-hash)** +- **[Search by value](#search-by-value)** +- **[SeleSearch by conditions](#search-by-conditions)** + +#### Insert (NoSQL) + +Insert operation allows to add one or more rows of data to a database table. + +|
Parameters
|
Description
| +| ---------- | ----------- | +| Schema (required) | schema where the table you are inserting records into lives | +| Table (required) | table name where you want to insert records | +| Records (required) | array of one or more records for insert | + +**Example Records:** +```js +[{id: 22, name: "James Scott", age: 26, country:"Italy", hobby: "football"},...] +``` + +
+ +Marketplace: HarperDB + +
+ +#### Update (NoSQL) + +The Update operation modifies the values of specified attributes in one or more rows of a database table based on the hash attribute(primary key) that identifies the rows. + +|
Parameters
|
Description
| +| ---------- | ----------- | +| Schema (required) | schema where the table you are updating records into lives | +| Table (required) | table name where you want to update records | +| Records (required) | array of one or more records for update | + +**Example Records:** +```js +[{id:12, name:"Jeff Hannistor"},...] // Record having 12 as Primary key value will be updated +``` + +
+ +Marketplace: HarperDB + +
+ +#### Delete (NoSQL) + +Removes one or more rows of data from a specified table. + +|
Parameters
|
Description
| +| ---------- | ----------- | +| Schema (required) | schema where the table you are deleting records into lives | +| Table (required) | table name where you want to delete records | +| Hash Values (required) | array of one or more hash attribute (primary key) values, which identifies records to delete | + +**Example Hash Values:** +```js +[6, 15] // Records having 6 and 15 as Primary key value will be deleted +``` + +
+ +Marketplace: HarperDB + +
+ +#### Search by hash + +Returns data from a table for one or more hash values. + +|
Parameters
|
Description
| +| ---------- | ----------- | +| Schema (required) | schema where the table you are searching lives | +| Table (required) | table you wish to search | +| Hash Values (required) | array of hashes to retrieve | +| Table Attributes (required) | define which attributes you want returned. | + +**Example Hash Values:** +```js +[124, 66] // Records having 6 and 15 as Primary key value will be retrieved +``` + +**Example Table Attributes:** +```js +['id', 'name', 'age', 'hobby', 'country'] // Only the provided columns will be retrieved from the table +``` + +
+ +Marketplace: HarperDB + +
+ +#### Search by value + +Returns data from a table for a matching value. + +|
Parameters
|
Description
| +| ---------- | ----------- | +| Schema (required) | schema where the table you are searching lives | +| Table (required) | table you wish to search | +| Hash Values (required) | array of hashes to retrieve | +| Search Attribute (required) | attribute you wish to search can be any attribute | +| Search Value (required) | value you wish to search - wild cards are allowed. | +| Table Attributes (required) | define which attributes you want returned. | + +**Example Search Attribute:** +```bash +name +``` + +**Example Search Value:** +```bash +John Doe +or +Joh* // using wild card +``` + +**Example Table Attributes:** +```js +['id', 'name', 'age', 'hobby', 'country'] // Only the provided columns will be retrieved from the table +``` + +
+ +Marketplace: HarperDB + +
+ +#### Search by conditions + +Returns data from a table for one or more matching conditions. + +|
Parameters
|
Description
| +| ---------- | ----------- | +| Schema (required) | schema where the table you are searching lives | +| Table (required) | table you wish to search | +| Operator in-between each condition (optional) | the operator used between each condition - 'And', 'Or'. The default is 'And'. | +| Offset (optional) | the number of records that the query results will skip. The default is 0. | +| Limit (optional) | the number of records that the query results will include. The default is null, resulting in no limit. | +| Table Attributes (required) | define which attributes you want returned. | +| Conditions to filter (required) | the array of conditions objects, to filter by. Must include one or more object in the array. **search_attribute** (required) - the attribute you wish to search, can be any attribute. **search_type** (required) - the type of search to perform - 'equals', 'contains', 'starts_with', 'ends_with', 'greater_than', 'greater_than_equal', 'less_than', 'less_than_equal', 'between'. **search_value** (required) - case-sensitive value you wish to search. If the search_type is 'between' then use an array of two values to search between. Check the example below. | + +**Example Table Attributes:** +```js +['id', 'name', 'age', 'hobby', 'country'] // Only the provided columns will be retrieved from the table +``` + +**Example Conditions to filter:** +```js +[{'search_attribute': 'age', 'search_type': 'between', 'search_value': [20, 28]}, {'search_attribute': 'name', 'search_type': 'contains', 'search_value': 'Ray'}] +``` + +
+ +Marketplace: HarperDB + +
+ +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/huggingface.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/huggingface.md new file mode 100644 index 0000000000..a478ffa909 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/huggingface.md @@ -0,0 +1,112 @@ +--- +id: marketplace-plugin-hugging_face +title: Hugging Face +--- + +Hugging Face integration with ToolJet enables you to use advanced natural language processing capabilities. With Hugging Face's state-of-the-art models, you can generate high-quality content and summarize text seamlessly. + +This plugin leverages the Inference API from Hugging Face to ensure seamless integration with supported models. To confirm if a model is supported, refer to the Inference API section on its page on the **[Hugging Face](https://huggingface.co/models)**. + +Hugging Face Configuration + + +## Connection + +To connect with Hugging Face, you will need the **Personal access token**, which can be generated from **[Hugging Face Platform](https://huggingface.co/settings/tokens)**. + +You can use the following toggles: +- **Use Cache**: Use this to enable the cache layer on the inference API to accelerate response times for repeated requests. By default it is enabled. +- **Wait for Model**: Use this to wait for the model to load if it is not ready, avoiding any errors. By default it is off. + +Hugging Face Configuration + +## Supported Operations + +### Text Generation + +Use this operation to generate text based on the input and model settings. It provides information or explanations tailored to the given context. Check out all the available text generation models on [Hugging Face](https://huggingface.co/models?pipeline_tag=text-generation&sort=trending). + +**Required Parameters** + +- **Model**: Specifies the model to use for generating responses. + + Example Models - + - [google/gemma-2-2b-it](https://huggingface.co/google/gemma-2-2b-it) + - [tiiuae/falcon-7b-instruct](https://huggingface.co/tiiuae/falcon-7b-instruct) + - [HuggingFaceH4/zephyr-7b-beta](https://huggingface.co/HuggingFaceH4/zephyr-7b-beta) + - [mistralai/Mistral-7B-Instruct-v0.2](https://huggingface.co/mistralai/Mistral-7B-Instruct-v0.2) + +- **Input**: The user input for generating responses. + +**Optional Parameter** + +- **Operation Parameters**: Additional parameters to configure the model response. These parameters might change based on model being used. + +Gemini Query + +
+**Response Example** + +AI integration with ToolJet: + +**Benefits of ToolJet Integration:** + +* **Faster Development:** Streamline the development process with pre-built integrations and templates for common workflows. +* **Reduced Costs:** Automate tasks and reduce the need for custom coding, saving development time and money. +* **Increased Productivity:** Empower your team to build and deploy tools faster, allowing them to focus on more strategic tasks. +* **Improved Collaboration:** Enable seamless collaboration between developers and business users by providing a unified platform for tool creation. + +**ToolJet Integration with Existing Tooling:** + +* **Integration with Popular Tools:** ToolJet can integrate with various tools, including Slack, Jira, Google Drive, and more. +* **Customizability:** Customize the integration to fit your specific workflows and requirements. + +**How ToolJet Integrates with Existing Tooling:** + +* **APIs:** Leverage open APIs to connect ToolJet to other tools and services. +* **Webhook Integration:** Integrate ToolJet with external services via webhooks to trigger actions based on events. +* **ToolJet Plugins:** Explore a library of plugins that expand ToolJet's functionality and facilitate integrations. + +**Example Use Cases:** + +* **Automated Data Pipeline:** Connect ToolJet to a data warehousing platform like Snowflake to automate data extraction and transformation. +* **Workflow Management:** Integrate ToolJet with a project management tool like Jira to create automated workflows for tasks and approvals. +* **Customizable Reporting:** Connect ToolJet to a reporting tool like Google Analytics to generate custom reports based on data analytics. +* **Automatic Notifications:** Integrate ToolJet with a communication platform like Slack to trigger notifications for completed tasks or system updates. + +**Conclusion:** + +ToolJet's integration capabilities significantly enhance the power and flexibility of your development workflows, enabling you to build custom tools faster and more effectively. By leveraging pre-built integrations, customizability, and APIs, ToolJet empowers your team to achieve greater productivity and streamline their processes across various stages of the development lifecycle. + +
+ +### Summarisation + +Use this operation to create a summary of the input text based on the model settings. Check out all the available summarisation models on [Hugging Face](https://huggingface.co/models?pipeline_tag=summarization&sort=trending). + +**Required Parameters** + +- **Model**: Specifies the model to use for generating summary. + + Example Models - + - [facebook/bart-large-cnn](https://huggingface.co/facebook/bart-large-cnn) + - [philschmid/bart-large-cnn-samsum](https://huggingface.co/philschmid/bart-large-cnn-samsum) + - [google/pegasus-xsum](https://huggingface.co/google/pegasus-xsum) + - [ainize/bart-base-cnn](https://huggingface.co/ainize/bart-base-cnn) + - [Falconsai/text_summarization](https://huggingface.co/Falconsai/text_summarization) + + +- **Input**: Input text that needs to be summarized. + +**Optional Parameter** + +- **Operation Parameters**: Additional parameters to configure the model response. These parameters might change based on model being used. + +Gemini Query + +
+**Response Example** + +ToolJet can integrate with various tools, including Slack, Jira, Google Drive, and more. AI integration with ToolJet: capabilities significantly enhance the power and flexibility of your development workflows. By leveraging pre-built integrations, customizability, and APIs, ToolJet empowers your team to achieve greater productivity. + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/jira.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/jira.md new file mode 100644 index 0000000000..be56fc8b7f --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/jira.md @@ -0,0 +1,446 @@ +--- +id: marketplace-plugin-jira +title: Jira +--- + +# Jira + +ToolJet allows you to connect to your Jira instance to perform various operations such as managing issues, users, worklogs, and boards. + +
+ Jira Homepage +
+ +## Connection + +To connect to a Jira data source in ToolJet, you can either click the **+Add new data source** button on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page in the ToolJet dashboard. + +To connect to your Jira instance, the following details are required: + +- **URL**: Your Jira instance URL +- **Email**: Your Jira account email +- **Token**: Your Jira API token + +
+ Jira Connect +
+ +:::tip +You can generate a personal access token from your Jira account **Manage account > Security > API Tokens** section. +::: + +## Querying Jira + +1. Click the **+** button in the query manager at the bottom of the editor and select the Jira data source added earlier. +2. Choose the resource and operation you want to perform on your Jira instance. + +:::tip +Query results can be transformed using transformations. Refer to our transformations documentation for more details: **[link](/docs/beta/app-builder/custom-code/transform-data)** +::: + +## Supported Resources and Operations + +ToolJet supports the following Jira resources and operations: + +#### Issue + +- **[Get Issue](#get-issue)** +- **[Create Issue](#create-issue)** +- **[Delete Issue](#delete-issue)** +- **[Assign Issue](#assign-issue)** +- **[Edit Issue](#edit-issue)** + +#### User + +- **[Get User](#get-user)** +- **[Find Users by Query](#find-users-by-query)** +- **[Find Assignable Users](#find-assignable-users)** + +#### Worklog + +- **[Get Issue Worklogs](#get-issue-worklogs)** +- **[Add Worklog](#add-worklog)** +- **[Delete Worklog](#delete-worklog)** + +#### Board + +- **[Get Issues for Backlog](#get-issues-for-backlog)** +- **[Get All Boards](#get-all-boards)** +- **[Get Issues for Board](#get-issues-for-board)** + +## Issue + +### Get Issue + +This operation retrieves details of a specific Jira issue. + +
+ Jira Get Issue +
+ +#### Parameters: + +- **Issue key**: The key or id of the issue to retrieve. +- **Params/Body**: Additional parameters such as fields to retrieve, expand options, etc. + +#### Example: + +```yaml +Issue Key: 10001 +Params/Body: +{ + "fields": "summary,description,created", + "expand": "renderedFields,names" +} +``` + +### Create Issue + +This operation creates a new Jira issue. + +
+ Jira Create Issue +
+ +#### Parameters: + +- **Params/Body**: The details of the issue to be created. + +#### Example: + +```yaml +Params/Body: +{ + "fields": { + "project": { + "key": "SCRUM" + }, + "summary": "A particular bug needs to be fixed.", + "description": "The XYZ feature is not working as expected.", + "issuetype": { + "name": "Bug" + }, + "assignee": { + "accountId": "712020:4581444c-054e-41d8-90ed-6d1d849557f7" + }, + "labels": [ + "bug", + "urgent" + ] + } +} +``` + +### Delete Issue + +This operation deletes a specific Jira issue. + +
+ Jira Delete Issue +
+ +#### Parameters: + +- **Issue key**: The key or id of the issue to delete. +- **Delete subtasks**: Whether to delete the issue's subtasks. + +#### Example: + +```yaml +Issue Key: 10001 +Delete Subtasks: Yes // Can be Yes or No +``` + +### Assign Issue + +This operation assigns a Jira issue to a specific user. + +
+ Jira Assign Issue +
+ +#### Parameters: + +- **Issue key**: The key or id of the issue to assign. +- **Account id**: The account ID of the user to assign the issue to. + +#### Example: + +```yaml +Issue Key: 10001 +Account id: 712020:4581444c-054e-41d8-90ed-6d1d849557f7 +``` + +### Edit Issue + +This operation modifies an existing Jira issue. + +
+ Jira Edit Issue +
+ +#### Parameters: + +- **Issue key**: The key or id of the issue to edit. +- **Params/Body**: The fields to update and their new values. + +#### Example: + +```yaml +Issue Key: 10007 +Params/Body: +{ + "fields": { + "summary": "Updated issue summary", + "description": "Updated issue description" + } +} +``` + +## User + +### Get User + +This operation retrieves details of a specific Jira user. + +
+ Jira Get User +
+ +#### Parameters: + +- **Account id**: The account ID of the user to retrieve. +- **Expand**: Additional user details to include in the response. + +#### Example: + +```yaml +Account id: 5b10a2844c20165700ede21g +Expand: groups,applicationRoles +``` + +### Find Users by Query + +This operation searches for users based on a query. + +
+ Jira Find Users +
+ +#### Parameters: + +- **Query**: The search query in Jira Query Language (JQL) format. +- **Start at**: The index of the first user to return. +- **Max results**: The maximum number of users to return. + +#### Example: + +```yaml +Query: is assignee of PROJ +Start at: 1 +Max results: 10 +``` + +### Find Assignable Users + +This operation finds users that can be assigned to issues. + +
+ Jira Assignable Users +
+ +#### Parameters: + +- **Query**: The search query in Jira Query Language (JQL) format. +- **Account id**: The account ID of the user to find assignable users for. +- **Project key**: The key or id of the project to find assignable users for. +- **Issue key**: The key or id of the issue to find assignable users for. +- **Start at**: The index of the first user to return. +- **Max results**: The maximum number of users to return. +- **Action descriptor id**: The action descriptor ID to find assignable users for. +- **Recommended**: Whether to return recommended users. + +:::info +Note: Query and Account id are mutually exclusive parameters. You can only use one of them. +::: + +#### Example: + +```yaml +Query: Mark // Search for users with "Mark" in their name, username, or email +Account id: 5b10a2844c20165700ede21g +Project key: PROJ +Issue key: SCRUM-1 +Start at: 1 +Max results: 10 +Action descriptor id: 12345 +Recommended: Yes +``` + +## Worklog + +### Get Issue Worklogs + +This operation retrieves the worklogs for a specific issue. + +
+ Jira Get Issue Worklogs +
+ +#### Parameters: + +- **Issue key**: The key or id of the issue to get worklogs for. +- **Start at**: The index of the first worklog to return. +- **Max results**: The maximum number of worklogs to return. +- **Started after**: The date and time to start retrieving worklogs from. +- **Started before**: The date and time to stop retrieving worklogs. + +#### Example: + +```yaml +Issue Key: SCRUM-1 +Start at: 1 +Max results: 10 +Started after: 1626228754515 +Started before: 1726228754515 +``` + +### Add Worklog + +This operation adds a new worklog entry to an issue. + +
+ Jira Add Worklog +
+ +#### Parameters: + +- **Issue key**: The key or id of the issue to add the worklog to. +- **Params/Body**: The details of the worklog entry. + +#### Example: + +```yaml +Issue Key: SCRUM-1 +Params/Body: +{ + "comment": "I did some work here.", + "created": "2017-03-14T10:35:37.097+0000", + "id": "100028", + "issueId": "SCRUM-1", + "started": "2017-03-14T10:35:37.097+0000", + "timeSpent": "3h 20m" +} +``` + +### Delete Worklog + +This operation deletes a specific worklog entry from an issue. + +
+ Jira Delete Worklog +
+ +#### Parameters: + +- **Issue key**: The key or id of the issue containing the worklog +- **Worklog id**: The ID of the worklog to delete +- **Params/Body**: Additional parameters such as notify users, adjust estimate, etc. + +#### Example: + +```yaml +Issue Key: SCRUM-1 +Worklog id: 100010 +Params/Body: +{ + "notifyUsers": "true", + "adjustEstimate": "auto" +} +``` + +## Board + +### Get Issues for Backlog + +This operation retrieves issues from a board's backlog. + +
+ Jira Backlog Issues +
+ +#### Parameters: + +- **Board id**: The ID of the board to get backlog issues from. +- **Start at**: The index of the first issue to return. +- **Max results**: The maximum number of issues to return. +- **Expand**: Additional issue details to include in the response. +- **Params/Body**: Additional parameters such as fields to retrieve, expand options, etc. + +#### Example: + +```yaml +Board id: 1 +Start at: 1 +Max results: 10 +Expand: changelog +Params/Body: +{ + "fields": ["summary", "description", "created"], +} +``` + +### Get All Boards + +This operation retrieves all boards visible to the user. + +
+ Jira All Boards +
+ +#### Parameters: + +- **Project key**: Limit the boards to a specific project. +- **Start at**: The index of the first board to return. +- **Name**: The name of the board to search for. +- **Max results**: The maximum number of boards to return. +- **Expand**: Additional board details to include in the response. + +#### Example: + +```yaml +Project key: PROJ +Start at: 1 +Name: SCRUM +Max results: 10 +Expand: projects +``` + +### Get Issues for Board + +This operation retrieves all issues from a specific board. + +
+ Jira Board Issues +
+ +#### Parameters: + +- **Board id**: The ID of the board to get issues from. +- **Start at**: The index of the first issue to return. +- **Max results**: The maximum number of issues to return. +- **Expand**: Additional issue details to include in the response. +- **Params/Body**: Additional parameters such as fields to retrieve, expand options, etc. + +#### Example: + +```yaml +Board id: 1 +Start at: 1 +Max results: 10 +Expand: changelog +Params/Body: +{ + "fields": ["summary", "description", "created"], +} +``` diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/lambda.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/lambda.md new file mode 100644 index 0000000000..411aaa306b --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/lambda.md @@ -0,0 +1,39 @@ +--- +id: marketplace-plugin-aws-lambda +title: AWS Lambda +--- + +ToolJet can connect to AWS Lambda to run serverless functions. + +
+ +## Connection + +To connect to AWS Lambda plugin, you need to provide the following details: + +- **Access Key ID**: The access key ID of the IAM user that has the required permissions to access AWS Lambda. +- **Secret Access Key**: The secret access key of the IAM user that has the required permissions to access AWS Lambda. +- **Region**: The region where the AWS Lambda is hosted. + +
+ ToolJet database +
+ +
+ +
+ +## Supported Queries + +### Invoke Lambda Function + +This query is used to invoke a Lambda function. The following parameters are required: + +- **Function Name**: The name of the Lambda function to be invoked. +- **Payload**: The JSON payload to be sent to the Lambda function. + +
+ ToolJet database +
+ +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/mistral.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/mistral.md new file mode 100644 index 0000000000..b9cb0869cc --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/mistral.md @@ -0,0 +1,100 @@ +--- +id: marketplace-plugin-mistral_ai +title: Mistral AI +--- + +Mistral AI can be integrated with ToolJet to generate high-quality text content. By defining various roles, it enables the creation of contextually relevant and dynamic content. + +## Connection + +To connect with Mistral AI, you will need an **API Key**, which can be generated from **[Mistral AI Console](https://console.mistral.ai/api-keys/)**. + +Mistral Configuration + +## Supported Operations + +### Text Generation + +Use this operation to generate text content by controlling various parameters to achieve precise results. + +**Required Parameters** + +- **Model**: Use to specify the AI model for generating content. The available models are: + + - mistral-large-latest + - ministral-3b-latest + - ministral-8b-latest + - open-mistral-nemo + - mistral-small-latest + +- **Messages**: Provide structured input to define the context or conversation.
+ +:::info + +1. A message object with the role **assistant** should always have both a prefix and suffix message object in the messages array. +2. If a message object with the role **assistant** is the last in the array then set `prefix: true` in that object. +::: + +**Optional Parameters** + +- **Max size**: Set the maximum length for the generated content. +- **Temperature**: Adjust to control the creativity and diversity of the output. +- **Top P**: Use to limit randomness by setting a probability threshold. +- **Stop token(s)**: Specify tokens or phrases to end the content generation. +- **Random seed**: Set to ensure consistent results by initializing the generator. +- **Response format**: Choose between plain text or structured JSON output. +- **Presence penalty**: Apply to reduce repetition of words or phrases. +- **Frequency penalty**: Use to discourage frequent word usage for more varied responses. +- **Completions (N)**: Set the number of response variations to generate. +- **Safe prompt**: Ensure the prompt is free of inappropriate or sensitive content. + +Mistral Query + +
+**Response Example** + +"While I can't provide personalized financial advice, I can certainly help you understand some common investment options that may offer tax benefits. Here are some strategies to consider: + +#### 1. **Retirement Accounts** +- **401(k) or 403(b):** These are employer-sponsored retirement plans. Contributions are made with pre-tax dollars, reducing your taxable income. Employer matching contributions can also boost your savings. +- **Traditional IRA:** Contributions may be tax-deductible, depending on your income and whether you have access to a workplace retirement plan. Withdrawals are taxed as ordinary income. +- **Roth IRA:** Contributions are made with after-tax dollars, but qualified withdrawals are tax-free. This can be beneficial for those who expect to be in a higher tax bracket in retirement. + +#### 2. **Health Savings Accounts (HSAs)** +- **HSAs:** These are available to individuals with high-deductible health plans. Contributions are tax-deductible, earnings grow tax-free, and withdrawals for qualified medical expenses are tax-free. + +#### 3. **Tax-Loss Harvesting** +- **Selling Losing Investments:** You can sell investments that have lost value to offset gains from other investments, reducing your capital gains tax liability. + +#### 4. **Municipal Bonds** +- **Muni Bonds:** These are issued by state and local governments and are often exempt from federal taxes and sometimes state taxes as well. + +#### 5. **Education Savings Accounts** +- **529 Plans:** Contributions grow tax-free, and withdrawals are tax-free if used for qualified education expenses. Some states offer tax deductions or credits for contributions. +- **Coverdell ESAs:** Similar to 529 plans but with more restrictions on contributions and uses. + +#### 6. **Real Estate Investments** +- **Rental Income:** Income from rental properties can be offset by depreciation, reducing your taxable income. +- **1031 Exchanges:** Allows you to defer capital gains taxes by reinvesting the proceeds from the sale of an investment property into a similar property. + +#### 7. **Tax-Efficient Investments** +- **Index Funds and ETFs:** These often have lower turnover rates, which can reduce capital gains distributions and therefore tax liabilities. +- **Dividend-Paying Stocks:** Qualified dividends are taxed at lower rates than ordinary income. + +#### 8. **Charitable Contributions** +- **Donations:** Contributions to qualified charities can be tax-deductible, reducing your taxable income. +- **Donor-Advised Funds:** Allow you to make a charitable contribution and receive an immediate tax deduction, while deciding later where to allocate the funds. + +#### 9. **Energy-Efficient Home Improvements** +- **Tax Credits:** Certain energy-efficient home improvements may qualify for tax credits. + +#### 10. **Business Ownership** +- **Sole Proprietorships, LLCs, S-Corps:** Different business structures offer various tax benefits, such as pass-through income and deductions for business expenses. + +#### Steps to Create a Plan: +1. **Assess Your Financial Goals:** Determine what you want to achieve with your investments (e.g., retirement savings, education funding). +2. **Evaluate Your Tax Situation:** Understand your current and future tax brackets to choose the right investment vehicles. +3. **Diversify Your Portfolio:** Spread your investments across different asset classes to manage risk. +4. **Consult a Professional:** Consider working with a financial advisor or tax professional to tailor a plan to your specific needs." + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/openai.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/openai.md new file mode 100644 index 0000000000..9869b09560 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/openai.md @@ -0,0 +1,219 @@ +--- +id: marketplace-plugin-openai +title: OpenAI +--- + +ToolJet integrates with OpenAI to utilize its AI capabilities. This integration enables ToolJet to generate text based on user prompts, facilitate chat interactions, create images tailored to specific inputs, and generate vector embeddings. + +:::note +Before following this guide, it is assumed that you have already completed the process of **[Using Marketplace plugins](/docs/marketplace/marketplace-overview#using-marketplace-plugins)**. +::: + +## Connection + +For connecting to OpenAI, the following credentials are required: + +- **API key**: API key for OpenAI can be generated [here](https://platform.openai.com/account/api-keys). +- **Organization ID**: Find the Organization ID [here](https://platform.openai.com/account/org-settings). + +
+ Configuring OpenAI in ToolJet +
+ +## Supported Operations + +- **[Chat](#chat)** +- **[Completions](#completions)** +- **[Generate AI Image(s)](#generate-ai-images)** +- **[Generate embedding](#generate-embedding)** + +### Chat + +The function of this operation is to examine the user's input and generate a suitable response that simulates human-like conversation. + +#### Required Parameters + +- **Model**: The model to use for generating the chat response. The available models are: + - GPT-4.0 + - GPT-4.0 mini + - GPT-4 Turbo + - GPT-3.5 Turbo +- **Prompt**: A prompt is the initial message or question that is provided as input to the chatbot model to start a conversation. + +#### Optional Parameters + +- **Max Tokens**: This parameter specifies the maximum number of tokens to generate in the text completion output. For example, if you set it to 50, then it will generate a text completion that contains up to 50 tokens. +- **Temperature**: Temperature is used to control the creativity and randomness of the generated text. It ranges from 0 to 2, a higher value such as 0.8 will increase the randomness of the output, whereas a lower value such as 0.2 will make it more focused and deterministic. +- **Stop sequence**: This Stop sequence/parameter is used to specify when the API should stop generating text completions. This parameter is optional and can be used to customize the length and quality of the generated text. +- **Suffix**: The suffix that follows the inserted text completion. + +
+ Chat Operation +
+ +
+**Example Values** + +```yaml +Model: GPT-4 Turbo +Prompt: What are the key principles of machine learning? +Max Tokens: 100 +Temperature: 0.7 +Stop sequence: END +Suffix: \n +``` + +
+ +
+**Response Example** + +```json +"Machine learning, a subset of artificial intelligence, is fundamentally about designing and implementing algorithms that can learn from and make predictions or decisions based on data. The key principles of machine learning can be outlined as follows:nn1. **Learning from Data**: At its core, machine learning involves developing algorithms that can learn from and make predictions or inferences from data. Models are trained using a large set of data known as training data, which helps them make decisions or predictions without being explicitly programmed for the task.nn2" +``` + +
+ +### Completions + +The purpose of this operation is to generate text completions based on a given prompt. + +#### Required Parameters + +- **Model**: The model to use for generating the text completion. The available models are: + - GPT-3.5 Turbo +- **Prompt**: OpenAI uses the prompt as a starting point to generate a continuation or completion of the text, which can be in the form of a sentence, paragraph, or even an entire article. The quality and relevance of the generated text output can depend on the quality and specificity of the prompt provided. + +#### Optional Parameters + +- **Max Tokens**: This parameter specifies the maximum number of tokens to generate in the text completion output. For example, if you set it to 50, then it will generate a text completion that contains up to 50 tokens. +- **Temperature**: Temperature is used to control the creativity and randomness of the generated text. It ranges from 0 to 1, a higher value such as 0.8 will increase the randomness of the output, whereas a lower value such as 0.2 will make it more focused and deterministic. +- **Stop sequence**: Stop sequence is used to specify when the API should stop generating text completions. This parameter is optional and can be used to customize the length and quality of the generated text. +- **Suffix**: The suffix that follows the inserted text completion. + +
+ Completions Operation +
+ +
+**Example Values** + +```yaml +Model: GPT-3.5 Turbo +Prompt: The benefits of using low code platforms for software development include +Max Tokens: 100 +Temperature: 0.6 +Stop sequence: END +Suffix: \n +``` + +
+ +
+**Response Example** + +``` json +":1. Increased Speed and Efficiency: Low code platforms allow developers to quickly build and deploy applications without having to write extensive lines of code. This significantly reduces development time and increases efficiency.nn2. Cost Savings: With low code platforms, businesses can save on development costs by reducing the need for a large team of developers. This also leads to lower maintenance costs as the applications are easier to maintain and update.nn3. User-Friendly Interface: Low code platforms are designed to be user-friendly and require minimal" +``` + +
+ +### Generate AI Image(s) + +This operation generates AI images based on the given prompt. + +#### Required Parameters + +- **Model**: The model to use for generating the image. The available models are: + - DALL-E 3 + - DALL-E 2 +- **Prompt**: The prompt is the initial message or question that is provided as input to the AI model to generate an image. + +#### Optional Parameters + +- **Size (in pixels)**: The size of the image to be generated in pixels. The default value is 1024x1024. The allowed sizes depend on the model: + - **DALL-E 2**: Must be one of `256x256`, `512x512`, or `1024x1024`. + - **DALL-E 3**: Must be one of `1024x1024`, `1792x1024`, or `1024x1792`. + +
+ Generate AI Images Operation +
+ +
+**Example Values** + +```yaml +Model: DALL-E 3 +Prompt: A futuristic cityscape with flying cars and holographic billboards at sunset +Size(in pixels): 1024x1024 +``` + +
+ +
+**Response Example** + +```json +{ + "status": "success", + "message": "Image generated successfully", + "data": { + "url": "https://oaidalleapiprodscus.blob.core.windows.net/private/org-CpkCwFjT48kGZ33uOV2L4QxH/user-3QrXKnZO1PJUBeNP6xiQV9Rs/img-XXIds2QvTdcUfcJ2qmNWLwsC.png?st=2024-10-09T10%3A24%3A34Z&se=2024-10-09T12%3A24%3A34Z&sp=r&sv=2024-08-04&sr=b&rscd=inline&rsct=image/png&skoid=d505667d-d6c1-4a0a-bac7-5c84a87759f8&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skt=2024-10-09T03%3A29%3A32Z&ske=2024-10-10T03%3A29%3A32Z&sks=b&skv=2024-08-04&sig=qPBYkPdQjLwBWJAS8fWmhs3B5TNSYbxhuMe15NcmgM4%3D" + } +} +``` + +
+ +### Generate Embedding + +This operation is used to generate vector embeddings from the given text, which can be used to build AI applications. + +#### Required Parameters + +- **Model**: The model to use for generating the vector embedding. The available models are: + - text-embedding-3-small + - text-embedding-3-large + - text-embedding-ada-002 + +- **Input**: The text input used for generating the vector embedding. + +#### Optional Parameters + +- **Encoding format**: Specifies the output format of the vector embedding from the dropdown, float or base64. +- **Dimensions**: Defines the number of values in the generated embedding vector, affecting its size and level of detail. + +Generate Vector Embedding + +
+**Example Values** + +```yaml +Model: text-embedding-3-large +Input: ToolJet is a low code platform used to build internal tools +Encoding format: Float +Dimensions: 10 +``` + +
+ +
+**Response Example** + +```json +{ + "embedding": [ + -0.49750686, + -0.7019393, + -0.23043627, + -0.12421317, + -0.076866604, + 0.2191516, + 0.2548046, + 0.1453106, + -0.20050736, + 0.10516006 + ] +} +``` +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/pinecone.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/pinecone.md new file mode 100644 index 0000000000..12d9b2cb29 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/pinecone.md @@ -0,0 +1,224 @@ +--- +id: marketplace-plugin-pinecone +title: Pinecone +--- + +ToolJet integrates with Pinecone to utilize its vector database capabilities. This integration enables ToolJet to perform vector operations such as updating, querying, and managing vector embeddings in Pinecone indexes. + +:::note +Before following this guide, it is assumed that you have already completed the process of **[Using Marketplace plugins](/docs/marketplace/marketplace-overview#using-marketplace-plugins)**. +::: + +## Connection + +For connecting to Pinecone, the following credential is required: + +- **API Key**: API key for Pinecone can be generated from the [Pinecone Console](https://app.pinecone.io/organizations/-/projects/-/keys). + +Configuring Pinecone in ToolJet + + +## Supported Operations + +- **[Get Index Stats](#get-index-stats)** +- **[List Vector IDs](#list-vector-ids)** +- **[Fetch Vectors](#fetch-vectors)** +- **[Upsert Vectors](#upsert-vectors)** +- **[Update Vector](#update-a-vector)** +- **[Delete Vectors](#delete-vectors)** +- **[Query Vectors](#query-vectors)** + +### Get Index Stats + +This operation retrieves statistics about a specific index in your Pinecone database. + +#### Required Parameter + +- **Index**: The name of the index to get statistics for. + +Get Index Stats Operation + +
+**Example Response** + +```json +{ + "namespaces":{ + "":{ + "recordCount":100 + } + }, + "dimension":1024, + "indexFullness":0, + "totalRecordCount":100 +} +``` +
+ +### List Vector IDs + +This operation retrieves a list of vector IDs from a specified index. + +#### Required Parameter + +- **Index**: The name of the index to list vector IDs from. + +#### Optional Parameters + +- **Prefix**: Filter vector IDs by prefix. +- **Limit**: Maximum number of vector IDs to return. +- **Pagination Token**: Token for retrieving the next page of results. +- **Namespace**: Specific namespace to query within the index. + +List Vector IDs Operation + +
+**Example Response** + +```yaml +{ + "vectors":[ + {"id":"0"}, + {"id":"1"}, + {"id":"10"}, + {"id":"11"}, + {"id":"12"}, + {"id":"13"}, + {"id":"14"}, + {"id":"15"}, + {"id":"16"}, + {"id":"17"} + ], + "pagination":{ + "next":"eyJza2lwX3Bhc3QiOiIxNyIsInByZWZpeCI6bnVsbH0=" + }, + "namespace":"", + "usage":{ + "readUnits":1 + } +} +``` +
+ +### Fetch Vectors + +This operation retrieves specific vectors by their IDs from an index. + +#### Required Parameters + +- **Index**: The name of the index to fetch vectors from. +- **IDs**: Array of vector IDs to fetch. + +#### Optional Parameters + +- **Namespace**: Specific namespace to fetch vectors from. + +Fetch Vectors Operation + +
+**Example Response** + +```yaml +{ + "records":{}, + "namespace":"", + "usage":{ + "readUnits":1 + } +} +``` +
+ +### Upsert Vectors + +This operation inserts or updates vectors in an index. + +#### Required Parameters + +- **Index**: The name of the index to upsert vectors into. +- **Vectors**: Array of vectors to upsert, including IDs and values. + +#### Optional Parameters + +- **Namespace**: Specific namespace to upsert vectors into + +Upsert Vectors Operation + +
+**Example Response** + +```yaml +Upsert Successful +``` +
+ +### Update a Vector + +This operation updates a single vector's values or metadata. + +#### Required Parameters + +- **Index**: The name of the index containing the vector. +- **ID**: ID of the vector to update. + +#### Optional Parameters + +- **Values**: Updated vector values as an array. +- **Sparse Vector**: Sparse vector representation. +- **Metadata**: Additional metadata for the vector. +- **Namespace**: Specific namespace containing the vector. + +Update Vector Operation + +
+**Example Response** + +```yaml +Update Successful +``` +
+ +### Delete Vectors + +This operation deletes vectors from an index. + +#### Required Parameters + +- **Index**: The name of the index to delete vectors from. + +#### Optional Parameters + +- **IDs**: Array of vector IDs to delete. +- **Delete All**: Boolean flag to delete all vectors. +- **Namespace**: Specific namespace to delete vectors from. +- **Filter**: Filter condition for selective deletion. + +Delete Vectors Operation + +
+**Example Response** + +```yaml +Delete Successful +``` +
+ +### Query Vectors + +This operation queries vectors in an index based on similarity. + +#### Required Parameters + +- **Index**: The name of the index to query. +- **Vectors**: Query vector values. +- **Top K**: Number of most similar vectors to return. + +#### Optional Parameters + +- **Namespace**: Specific namespace to query. +- **Filter**: Filter condition for the query. +- **Include Values**: Boolean to include vector values in results. +- **Include Metadata**: Boolean to include metadata in results. +- **Sparse Vector**: Sparse vector for hybrid search. + +Query Vectors Operation diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/plivo.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/plivo.md new file mode 100644 index 0000000000..973ed5ac95 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/plivo.md @@ -0,0 +1,46 @@ +--- +id: marketplace-plugin-plivo +title: Plivo +--- + +You can integrate your ToolJet application with Plivo for SMS functionality. + +:::note +Before following this guide, it is assumed that you have already completed the process of **[Using Marketplace plugins](/docs/marketplace/marketplace-overview#using-marketplace-plugins)**. +::: + +## Connection + +To use the Plivo plugin, you need the following credentials: +- **Auth Token** +- **Auth ID** + +:::info Generating Auth Token/ID +- Navigate to the Plivo Console (https://www.plivo.com/) +- In the console, you will see your auth ID and auth token listed under the "API" section. +- If you don't see your auth ID and auth token, you can generate new ones by clicking on the "Generate New Auth ID/Token" button. +::: + +
+ +Configuring Plivo In ToolJet + +
+ +## Supported Queries + +### Send SMS + +You can use the Send SMS operation to send an SMS to a specified mobile number. + +#### Required Parameters: + +- **To Number** +- **From Number** +- **Body** + +
+ +Send SMS Using plivo + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/pocketbase.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/pocketbase.md new file mode 100644 index 0000000000..2ade30996b --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/pocketbase.md @@ -0,0 +1,88 @@ +--- +id: marketplace-plugin-pocketbase +title: PocketBase +--- + +# PocketBase + +ToolJet connects to your PocketBase database, allowing you to directly interact with your PocketBase backend from the convenience of your ToolJet application. + +:::info +**NOTE:** **Before following this guide, it is assumed that you have already completed the process of [Using Marketplace plugins](/docs/marketplace/marketplace-overview#using-marketplace-plugins)**. +::: + +## Connection + +- To connect to PocketBase, you need the Host URL, email, and password. The Host URL is the URL of your PocketBase instance. Email and password are the credentials of the user who has access to the PocketBase instance. +- Establish a connection to PocketBase by either clicking `+Add new Data source` on the query panel or navigating to the [Data Sources](/docs/data-sources/overview/) page from the ToolJet dashboard. +- Enter your Host URL, email and password into their designated fields. +- Click **Test Connection** to validate your credentials. Click **Save** to store the data source. + PocketBase Install + +## Querying PocketBase + +- To perform queries on PocketBase in ToolJet, click the **+Add** button in the [query manager](/docs/app-builder/query-panel/#query-manager) located at the bottom panel of the editor. +- Select the previously configured PocketBase datasource. +- In the Operation dropdown, select the desired operation type. ToolJet currently [supports](#supported-operations) five query types for PocketBase interactions. +- Enter the collection name and other required parameters for the selected operation and click on **Run** button to run the query. + PocketBase query + +:::info +Query results can be transformed using transformations. Read our [transformations documentation](/docs/beta/app-builder/custom-code/transform-data). +::: + +## Supported Operations + +You can create query for PocketBase data source to perform several operations such as: + +1. **[List Records](#list-records)** +2. **[Get Record](#get-record)** +3. **[Add Record to Collection](#add-record-to-collection)** +4. **[Update Record to Collection](#update-record-to-collection)** +5. **[Delete Record](#delete-record)** + +### List Records + +#### Required parameters: + +- **Collection Name** - Collection name in the database. + +#### Optional Parameters: + +- **Limit** - Number of records to be fetched. +- **Sort** - Sort the records based on a sort rule. Add `-` / `+`(default) in front of the attribute for DESC / ASC order. +- **Where** - Filter the records based on a filter conditions. + List Records + +### Get Record + +#### Required parameters: + +- **Collection Name** - Collection name in the database. +- **Record ID** - ID of the record to be fetched. + Get Record + +### Add Record to Collection + +#### Required parameters: + +- **Collection Name** - Collection name in the database. +- **Body** - Data to be added to the collection. It should be in valid JSON format. + Add Record + +### Update Record to Collection + +#### Required parameters: + +- **Collection Name** - Collection name in the database. +- **Record ID** - ID of the record to be updated. +- **Body** - Data to be updated in the collection. It should be in valid JSON format. + Update Record + +### Delete Record + +#### Required parameters: + +- **Collection Name** - Collection name in the database. +- **Record ID** - ID of the record to be deleted. + Delete Record diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/portkey.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/portkey.md new file mode 100644 index 0000000000..5f2624c0cd --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/portkey.md @@ -0,0 +1,232 @@ +--- +id: marketplace-plugin-portkey +title: Portkey +--- + +ToolJet can integrate with Portkey to access AI services such as text completion, chat completion, prompt completion, and embedding creation. This integration enables ToolJet to leverage Portkey's LMOps platform to develop, launch, maintain, and iterate on generative AI features. + +
+ Portkey Dashboard Overview +
+ +:::note +Before following this guide, it is assumed that you have already completed the process of **[Using Marketplace plugins](/docs/marketplace/marketplace-overview#using-marketplace-plugins)**. +::: + +## Connection + +To connect to Portkey, the following credentials are required: + +- **API Key**: Your Portkey API Key. Refer to the **[Portkey API Authentication Documentation](https://docs.portkey.ai/docs/api-reference/authentication#obtaining-your-api-key)** for instructions on obtaining your API Key. +- **Default Virtual Key** (Optional): Your default Portkey Virtual Key. Visit the **[Portkey Virtual Keys Documentation](https://docs.portkey.ai/docs/product/ai-gateway-streamline-llm-integrations/virtual-keys#creating-virtual-keys)** to learn how to create and retrieve your Virtual Key. +- **Config** (Optional): Your default Portkey configuration. +- **Gateway URL** (Optional): Your default Portkey Gateway URL. See the **[Portkey API Authentication Documentation](https://docs.portkey.ai/docs/api-reference/authentication#obtaining-your-api-key)** for details on how to obtain your Gateway URL. + +
+ Configuring Portkey in ToolJet +
+ +## Supported Operations + +Portkey in ToolJet supports the following operations: + +- **[Completion](#completion)** +- **[Chat](#chat)** +- **[Prompt Completion](#prompt-completion)** +- **[Create Embedding](#create-embedding)** + +### Completion + +This operation generates text completions based on a given prompt. + +#### Parameters: + +- **Prompt**: The input text to generate completions for. +- **Model**: The AI model to use. +- **Max Tokens**: Maximum number of tokens to generate. +- **Temperature**: Controls randomness. +- **Stop Sequences**: Sequences where the API will stop generating further tokens. +- **Metadata**: Additional metadata for the request. +- **Other Parameters**: Any other parameters to include in the request. + +
+ Completion Operation for Portkey +
+ +
+ **Response Example** + ```json +{ + "id": "cmpl-9vNUfM8OP0SwSqXcnPwkqzR7ep8Sy", + "object": "text_completion", + "created": 1723462033, + "model": "gpt-3.5-turbo-instruct", + "choices": [ + { + "text": "nn"Experience the perfect brew at Bean There."", + "index": 0, + "logprobs": null, + "finish_reason": "stop" + } + ], + "usage": { + "prompt_tokens": 13, + "completion_tokens": 10, + "total_tokens": 23 + } +} + ``` +
+ +### Chat + +This operation generates chat completions based on a series of messages. + +#### Parameters: + +- **Messages**: An array of message objects representing the conversation. +- **Model**: The AI model to use. +- **Max Tokens**: Maximum number of tokens to generate. +- **Temperature**: Controls randomness. +- **Stop Sequence**: Sequences where the API will stop generating further tokens. +- **Metadata**: Additional metadata for the request. +- **Other Parameters**: Any other parameters to include in the request. + +
+ Chat Operation for Portkey +
+ +
+ **Response Example** +```json +{ + "id": "chatcmpl-9vNIlfllXOPEmroKFajK2nlJHzhXA", + "object": "chat.completion", + "created": 1723461295, + "model": "gpt-3.5-turbo-0125", + "choices": [ + { + "index": 0, + "message": { + "role": "assistant", + "content": "The capital of France is Paris.", + "refusal": null + }, + "logprobs": null, + "finish_reason": "stop" + } + ], + "usage": { + "prompt_tokens": 24, + "completion_tokens": 7, + "total_tokens": 31 + }, + "system_fingerprint": null +} +``` +
+ +### Prompt Completion + +This operation generates completions based on a pre-defined prompt. + +#### Parameters: + +- **Prompt ID**: The ID of the pre-defined prompt to use. +- **Variables**: Variables to be used in the prompt. +- **Parameters**: Additional parameters for the prompt completion. +- **Metadata**: Additional metadata for the request. + +
+ Prompt Completion Operation for Portkey +
+ +
+ **Response Example** +```json +{ + "id": "chatcmpl-9w6D8jZciWVf1DzkgqNZK14KUvA4d", + "object": "chat.completion", + "created": 1723633926, + "model": "gpt-4o-mini-2024-07-18", + "choices": [ + { + "index": 0, + "message": { + "role": "assistant", + "content": "The Industrial Revolution, starting in the late 18th century, transformed production from hand methods to machine-based processes, introducing new manufacturing techniques, steam power, and machine tools. It marked a shift from bio-fuels to coal, with the textile industry leading the way. This period resulted in significant population growth, increased average income, and improved living standards.", + "refusal": null + }, + "logprobs": null, + "finish_reason": "stop" + } + ], + "usage": { + "prompt_tokens": 145, + "completion_tokens": 71, + "total_tokens": 216 + }, + "system_fingerprint": "fp_48196bc67a" +} +``` +
+ +### Create Embedding + +This operation creates embeddings for given input text. + +#### Parameters: + +- **Input**: The input text to create embeddings for. +- **Model**: The AI model to use for creating embeddings. +- **Metadata**: Additional metadata for the request. + +
+ Create Embedding Operation for Portkey +
+ +
+ **Response Example** +```json +{ + "object": "list", + "data": [ + { + "object": "embedding", + "index": 0, + "embedding": [ + -0.02083237, + -0.016892163, + -0.0045676464, + -0.05084554, + -0.025968939, + 0.029597048, + 0.029987168, + 0.02907689, + 0.0105982395, + -0.024356445, + -0.00935636, + 0.0066352785, + 0.034018397, + -0.042002838, + 0.03856979, + -0.014681488, + ..., + 0.024707552 + ] + } + ], + "model": "text-embedding-3-small", + "usage": { + "prompt_tokens": 9, + "total_tokens": 9 + } +} +``` +
+ +For all operations, you can optionally specify: +- **Config**: Configuration options for the request. +- **Virtual Key**: A specific virtual key to use for the request, overriding the default. + +--- \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/prestodb.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/prestodb.md new file mode 100644 index 0000000000..d4cbfe2eb1 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/prestodb.md @@ -0,0 +1,59 @@ +--- +id: marketplace-plugin-Presto +title: PrestoDB +--- + +# PrestoDB + +ToolJet allows you to connect to your PrestoDB database to perform SQL queries and retrieve data. + +## Connection + +To connect to a PrestoDB data source in ToolJet, you can either click the **+Add new data source** button on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page in the ToolJet dashboard. + +To connect to your PrestoDB database, the following details are required: + +- **Username** +- **Password** +- **Catalog** +- **Host** +- **Port** +- **Schema** +- **User** +- **Timezone** (optional) +- **Extra Headers** (optional) + +
+ PrestoDB Connect +
+ +## Querying PrestoDB + +1. Click the **+** button in the query manager at the bottom of the editor and select the PrestoDB data source added earlier. +2. Write your SQL query in the query editor. + +:::tip +Query results can be transformed using transformations. Refer to our transformations documentation for more details: **[link](/docs/beta/app-builder/custom-code/transform-data)** +::: + +## Supported Operations + +ToolJet supports executing SQL queries on PrestoDB databases. + +### SQL Query + +This operation allows you to execute SQL queries on your PrestoDB database. + +
+ PrestoDB Query +
+ +#### Parameters: + +- **SQL Query**: The SQL query to execute. + +#### Example: + +```sql +SELECT * FROM my_table WHERE column_name = 'value' LIMIT 10 +``` diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/qdrant.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/qdrant.md new file mode 100644 index 0000000000..4cf73ee5de --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/qdrant.md @@ -0,0 +1,169 @@ +--- +id: marketplace-plugin-qdrant +title: Qdrant +--- + +Qdrant is a vector database which can be integrated with ToolJet to enable efficient vector search at scale. It supports AI applications with advanced technology for finding similar vectors. + +At its core, Qdrant operates with points, which are records consisting of a vector and an optional payload which allows you to store additional context or metadata alongside the vectors for more meaningful searches. + +## Connection + +To connect with Qdrant, you will need Qdrant URL and an API key, which can be generated from [Qdrant Cloud Dashboard](https://qdrant.to/cloud). + +Qdrant Configuration + +## Supported Operations + +### Get Collection Info + +Use this operation to retrieve metadata and configuration details about a specific collection in Qdrant. + +**Required Parameter** + +- **Collection Name:** Refers to the specific dataset stored in Qdrant. + +Get Collection Info + +
+**Example Response** +```yaml +{ + "status": "green", + "optimizer_status": "ok", + "indexed_vectors_count": 5417, + "points_count": 5412, + "segments_count": 2, + "config": { + "params": { + "vectors": { + "size": 512, + "distance": "Cosine" + }, + "shard_number": 1, + "replication_factor": 1, + "write_consistency_factor": 1, + "on_disk_payload": true + }, + "hnsw_config": { + "m": 16, + "ef_construct": 100, + "full_scan_threshold": 10000, + "max_indexing_threads": 0, + "on_disk": false + }, + "optimizer_config": { + "deleted_threshold": 0.2, + "vacuum_min_vector_number": 1000, + "default_segment_number": 2, + "max_segment_size": null, + "memmap_threshold": null, + "indexing_threshold": 1000, + "flush_interval_sec": 5, + "max_optimization_threads": null + }, + "wal_config": { + "wal_capacity_mb": 1, + "wal_segments_ahead": 0 + }, + "quantization_config": null, + "strict_mode_config": { + "enabled": false + } + }, + "payload_schema": {} +} +``` +
+ +### Get Points + +Use this operation to retrieve specific data points from a collection using their unique identifiers. + +**Required Parameters** + +- **Collection Name:** Refers to the specific dataset stored in Qdrant. +- **IDs:** Unique identifiers for individual data points within the collection. They are used to locate and retrieve specific entries from the collection. + +Get Points + +
+**Example Response** + +```yaml +[{ + "id": 1, + "payload": { + "file_name": "text.jpeg", + "image_url": "https://storage.googleapis.com/demo-midjourney/.jpeg", + "name": "Catherine Hyde", + "url": "/styles/catherine-hyde" + }, + "vector": [0.043383807, -0.06374442, -0.013710048, -0.0332631, 0.013115806, -0.018017521, -0.01306308, -0.030214038, 0.009868348, 0.02169504, -0.009813371, -0.033448037, 0.004893773, -0.009090395...] +}] +``` +
+ +### Delete Points + +Use this operation to remove specific data points from a collection using their unique identifiers. + +**Required Parameters** + +- **Collection Name:** Refers to the specific dataset stored in Qdrant. +- **IDs:** Unique identifiers for individual data points within the collection. They are used to locate and retrieve specific entries from the collection. + +**Optional Parameter** + +- **Filter:** Used to set conditions when searching or retrieving points. + +Delete Points + +### Query Points + +Use this operation to search data points in a collection using a query, typically based on vector similarity or filtering conditions. + +**Required Parameters** + +- **Collection Name:** Identifies the dataset where the query will be executed. +- **Limit:** Specifies the maximum number of results to return. +- **Query:** A vector representing the query input used for similarity-based search. + +**Optional Parameters** + +- **With Vectors:** Indicates whether the vector data for the retrieved points should be included in the response (true or false). +- **Include Metadata:** Specifies if metadata associated with the points should be returned (true or false). +- **Filter:** Defines conditions to narrow down the search. + +Query Points + +
+**Example Response** + +```yaml +[{ + "id": 2589, + "version": 124, + "score": 0.1293197 +}, { + "id": 2274, + "version": 111, + "score": 0.12669206 +}, { + "id": 2612, + "version": 124, + "score": 0.12196793 +}] +``` +
+ +### Upsert Points + +Use this operation to add new data points or update existing ones in a collection based on their unique identifiers. + +**Required Parameters** + +- **Collection Name:** Represents the group of data points where the new or updated points will be stored. +- **Points:** The actual data being added or updated. Each point contains a unique identifier and optional attributes. + +Upsert Points diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/salesforce.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/salesforce.md new file mode 100644 index 0000000000..ea43f8b9df --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/salesforce.md @@ -0,0 +1,83 @@ +--- +id: marketplace-plugin-salesforce +title: Salesforce +--- + +ToolJet connects to your Salesforce account, allowing you to directly interact with your Salesforce connected app from within your ToolJet application. + +:::info +**NOTE:** **Before following this guide, it is assumed that you have already completed the process of [Using Marketplace plugins](/docs/marketplace/marketplace-overview#using-marketplace-plugins)**. +::: + +## Connection + +- To connect to Salesforce, you need to have the following credentials: + - **Client ID** - The consumer key of your Salesforce connected app. + - **Client Secret** - The consumer secret of your Salesforce connected app. + Salesforce Connected App API Settings +- Establish a connection to Salesforce by either clicking `+Add new Data source` on the query panel or navigating to the [Data Sources](/docs/data-sources/overview/) page from the ToolJet dashboard. +- Select the API version from the dropdown, enter your Client ID and Client Secret into their designated fields. +- Copy the **Redirect URL** and paste it into the OAuth **Callback URL** field in your Salesforce connected app settings. +- Click the **Connect to salesforce** button to authenticate your Salesforce account. +- Once authenticated, click **Save data source** to store the data source. + +You can toggle on **Authentication required for all users** in the configuration. When enabled, users will be redirected to the OAuth consent screen the first time a query from this data source is triggered in the application. This ensures each user connects their own Google Calendar account securely. + +Note: After completing the OAuth flow, the query must be triggered again to load the data. + +Salesforece Install + +## Querying Salesforce + +- To perform queries on Salesforce in ToolJet, click the **+Add** button in the [query manager](/docs/app-builder/query-panel/#query-manager) located at the bottom panel of the editor. +- Select the previously configured Salesforce datasource from the **Data Source** dropdown. +- In the Operation dropdown, select the desired operation type. ToolJet supports two operation types for Salesforce interactions: + - **[SOQL Query](#soql-query)** - SOQL (Salesforce Object Query Language) is used to search your organization’s Salesforce data for specific information. + - **[CRUD Action](#crud-actions)** - CRUD (Create, Retrieve/Read, Update, Delete) actions are used to interact with Salesforce objects. + +## SOQL Query + +- To perform a SOQL query, select the **SOQL Query** operation from the dropdown. +- Enter the SOQL query in the **Query** field. +- Click **Run** to execute the query. + SOQL Query + +:::info +Query results can be transformed using transformations. Read our [transformations documentation](/docs/beta/app-builder/custom-code/transform-data). +::: + +## CRUD Actions + +To perform CRUD actions on Salesforce, select the **CRUD Action** operation from the dropdown. The following CRUD actions are supported: + +### Create + +#### Required parameters: + +- **Resource Name** - The name of the Salesforce object you want to create. By default, Account is selected. +- **Resource Body** - The data you want to insert into the Salesforce object. + Create + +### Retrieve(Read) + +#### Required parameters: + +- **Resource Name** - The name of the Salesforce object you want to create. By default, Account is selected. +- **Resource ID** - The ID of the Salesforce object you want to retrieve. + Read + +### Update + +#### Required parameters: + +- **Resource Name** - The name of the Salesforce object you want to create. By default, Account is selected. +- **Resource Body** - The data you want to update in the Salesforce object. The resource body should contain the ID of the Salesforce object you want to update. + Update + +### Delete + +#### Required parameters: + +- **Resource Name** - The name of the Salesforce object you want to create. By default, Account is selected. +- **Resource ID** - The ID of the Salesforce object you want to delete. + Delete diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/sharepoint.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/sharepoint.md new file mode 100644 index 0000000000..b1910f1eb4 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/sharepoint.md @@ -0,0 +1,806 @@ +--- +id: marketplace-plugin-sharepoint +title: Sharepoint +--- + +ToolJet allows you to connect to Microsoft Sharepoint to perform various operations like managing sites, lists, and items using Microsoft Graph API. + +:::info +**NOTE:** **Before following this guide, it is assumed that you have already completed the process of [Using Marketplace plugins](/docs/marketplace/marketplace-overview#using-marketplace-plugins)**. +::: + +## Connection + +To connect to a Sharepoint data source in ToolJet, you can either click the **+ Add new data source** button on the query panel or navigate to the **[Data Sources](/docs/data-sources/overview)** page in the ToolJet dashboard. + +:::info +You'll need to register your application in Azure Active Directory to get the required credentials. The application needs appropriate Microsoft Graph API permissions. +::: + +To connect to Sharepoint, you need the following details: + +- **Client ID** +- **Client Secret** +- **Tenant ID** + +
+ Sharepoint Connect +
+ +## Querying Sharepoint + +1. Click the **+ Add** button in the query manager at the bottom of the editor and select the Sharepoint data source added earlier. +2. Choose the operation you want to perform on your Sharepoint instance. + +:::tip +Query results can be transformed using transformations. Refer to our transformations documentation for more details: **[link](/docs/beta/app-builder/custom-code/transform-data)** +::: + +## Supported Operations + +ToolJet supports the following Sharepoint operations: + +- **[Get All Sites](#get-all-sites)** +- **[Get Site](#get-site)** +- **[Get Analytics](#get-analytics)** +- **[Get Pages Of a Site](#get-pages-of-a-site)** +- **[Get All Lists](#get-all-lists)** +- **[Get Metadata Of a List](#get-metadata-of-a-list)** +- **[Create a List](#create-a-list)** +- **[Get Items Of a List](#get-items-of-a-list)** +- **[Update Item Of a List](#update-item-of-a-list)** +- **[Delete Item Of a List](#delete-item-of-a-list)** +- **[Add Item To a List](#add-item-to-a-list)** + +### Get All Sites + +This operation retrieves all available Sharepoint sites. For more details, see the Microsoft Graph API documentation **[here](https://learn.microsoft.com/en-us/graph/api/site-search)**. + +#### Optional Parameters + +- **Top**: The number of sites to retrieve +- **Page**: The page number to retrieve + +
+ Get All Sites +
+ +
+**Response Example** + +```json +{ + "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites", + "value": [ + { + "createdDateTime": "2024-09-08T15:54:30Z", + "id": "tooljetxxxx.sharepoint.com,bcxxxx-4b3a-xxxxxx-dfe229c34311,2a4ac5da-xxx-xxxx-b047-18dece61fb95", + "lastModifiedDateTime": "2024-08-17T18:50:05Z", + "name": "appcatalog", + "webUrl": "https://tooljetxxxx.sharepoint.com/sites/appcatalog", + "displayName": "Apps", + "root": {}, + "siteCollection": { + "hostname": "tooljetxxxx.sharepoint.com" + } + } + ] +} +``` + +
+ +### Get Site + +This operation retrieves information about a specific site. + +#### Required Parameters + +- **Site ID**: The ID of the site to retrieve + +
+ Get Site +
+ +#### Example: + +```yaml +Site ID: tooljetxxxx.sharepoint.com,887cb371-e930-4e5b-a726-8d5769e6b946,6d653d09-1613-4663-99ab-1bb72ff6ceeb +``` + +
+**Response Example** + +```json +{ + "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites/$entity", + "createdDateTime": "2024-10-22T13:21:10.623Z", + "description": "Internal DIA Guidelines", + "id": "tooljetxxxx.sharepoint.com,887cb371-e930-4e5b-a726-8d5769e6b946,6d653d09-1613-4663-99ab-1bb72ff6ceeb", + "lastModifiedDateTime": "2024-10-24T13:35:39Z", + "name": "NewStyle", + "webUrl": "https://tooljetxxxx.sharepoint.com/sites/NewStyle", + "displayName": "NewStyle", + "root": {}, + "siteCollection": { + "hostname": "tooljetxxxx.sharepoint.com" + } +} +``` + +
+ +### Get Analytics + +This operation retrieves analytics for a specific site. + +#### Required Parameters + +- **Site ID**: The ID of the site +- **Time Interval**: + - **Last 7 Days** + - **All Time** + +
+ Get Analytics +
+ +#### Example: + +```yaml +Site ID: tooljetxxxx.sharepoint.com,887cb371-e930-4e5b-a726-8d5769e6b946,6d653d09-1613-4663-99ab-1bb72ff6ceeb +Time Interval: Last 7 Days +``` + +
+**Response Example** + +```json +{ + "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.itemActivityStat", + "aggregationInterval": "None", + "startDateTime": "2024-10-30T00:00:00Z", + "endDateTime": "2024-11-05T00:00:00Z", + "isTrending": false, + "access": { + "actionCount": 0, + "actorCount": 0, + "timeSpentInSeconds": 0 + }, + "incompleteData": { + "wasThrottled": false, + "resultsPending": false, + "notSupported": false + } +} +``` + +
+ +### Get Pages Of a Site + +This operation retrieves all pages from a specific site. + +#### Required Parameters + +- **Site ID**: The ID of the site + +#### Optional Parameters + +- **Top**: The number of sites to retrieve +- **Page**: The page number to retrieve + +
+ Get Pages +
+ +#### Example: + +```yaml +Site ID: tooljetxxxx.sharepoint.com,887cb371-e930-4e5b-a726-8d5769e6b946,6d653d09-1613-4663-99ab-1bb72ff6ceeb +``` + +
+**Response Example** + +```json +{ + "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites('tooljetxxxx.sharepoint.com%2C887cb371-e930-4e5b-a726-8d5769e6b946%2C6d653d09-1613-4663-99ab-1bb72ff6ceeb')/pages", + "@odata.nextLink": "https://graph.microsoft.com/v1.0/sites/tooljetxxxx.sharepoint.com,887cb371-e930-4e5b-a726-8d5769e6b946,6d653d09-1613-4663-99ab-1bb72ff6ceeb/pages?$top=1&$skiptoken=UGFnZWQ9VFJVRSZwX0ZpbGVMZWFmUmVmPUV2ZW50UGxhbkhvbWUuYXNweCZwX0lEPTc", + "value": [ + { + "@odata.type": "#microsoft.graph.sitePage", + "@odata.etag": ""{2095ED1D-AC76-4480-BBDC-8D63EBAAE2AF},6"", + "createdDateTime": "2024-10-22T13:21:33Z", + "eTag": ""{2095ED1D-AC76-4480-BBDC-8D63EBAAE2AF},6"", + "id": "2095ed1d-ac76-4480-bbdc-8d63ebaae2af", + "lastModifiedDateTime": "2024-10-22T13:21:35Z", + "name": "EventPlanHome.aspx", + "webUrl": "https://tooljetxxxx.sharepoint.com/sites/NewStyle/SitePages/EventPlanHome.aspx", + "title": "Home", + "pageLayout": "home", + "thumbnailWebUrl": "https://tooljetxxxx.sharepoint.com/_layouts/15/getpreview.ashx?guidSite=887cb371-e930-4e5b-a726-8d5769e6b946&guidWeb=6d653d09-1613-4663-99ab-1bb72ff6ceeb&guidFile=bb423735-7402-47df-ab2e-729bddfe6f23", + "promotionKind": "page", + "showComments": false, + "showRecommendedPages": false, + "contentType": { + "id": "0x0101009D1CB255DA76424F860D91F20E6C4118004CC245E37669F3438CDDEB01FCEAE890", + "name": "Site Page" + }, + "createdBy": { + "user": { + "displayName": "Oliver Smith", + "email": "oliver@tooljetxxxx.onmicrosoft.com" + } + }, + "lastModifiedBy": { + "user": { + "displayName": "Oliver Smith", + "email": "oliver@tooljetxxxx.onmicrosoft.com" + } + }, + "parentReference": { + "siteId": "887cb371-e930-4e5b-a726-8d5769e6b946" + }, + "publishingState": { + "level": "published", + "versionId": "1.0" + }, + "reactions": {} + } + ] +} +``` + +
+ +### Get All Lists + +This operation retrieves all lists from a specific site. + +#### Required Parameters + +- **Site ID**: The ID of the site + +#### Optional Parameters + +- **Page**: The page number to retrieve + +
+ Get All Lists +
+ +#### Example: + +```yaml +Site ID: tooljetxxxx.sharepoint.com,887cb371-e930-4e5b-a726-8d5769e6b946,6d653d09-1613-4663-99ab-1bb72ff6ceeb +Page: 1 +``` + +
+**Response Example** + +```json +{ + "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites('tooljetxxxx.sharepoint.com%2C887cb371-e930-4e5b-a726-8d5769e6b946%2C6d653d09-1613-4663-99ab-1bb72ff6ceeb')/lists", + "value": [ + { + "@odata.etag": ""1a64ae23-9cb6-4521-b489-61d558dde9f7,11"", + "createdDateTime": "2024-10-24T11:11:10Z", + "description": "", + "eTag": ""1a64ae23-9cb6-4521-b489-61d558dde9f7,11"", + "id": "1a64ae23-9cb6-4521-b489-61d558dde9f7", + "lastModifiedDateTime": "2024-10-24T11:11:17Z", + "name": "Test_table_query", + "webUrl": "https://tooljetxxxx.sharepoint.com/sites/NewStyle/Lists/Test_table_query", + "displayName": "Test_table_query", + "createdBy": { + "user": { + "email": "oliver@tooljetxxxx.onmicrosoft.com", + "id": "90ccfd6b-17ea-402b-aa21-1a1799a547d6", + "displayName": "Oliver Smith" + } + }, + "lastModifiedBy": { + "user": { + "email": "oliver@tooljetxxxx.onmicrosoft.com", + "id": "90ccfd6b-17ea-402b-aa21-1a1799a547d6", + "displayName": "Oliver Smith" + } + }, + "parentReference": { + "siteId": "tooljetxxxx.sharepoint.com,887cb371-e930-4e5b-a726-8d5769e6b946,6d653d09-1613-4663-99ab-1bb72ff6ceeb" + }, + "list": { + "contentTypesEnabled": false, + "hidden": false, + "template": "genericList" + } + } + ] +} +``` + +
+ +### Get Metadata Of a List + +This operation retrieves metadata for a specific list. + +#### Required Parameters + +- **Site ID**: The ID of the site +- **List Name**: The name of the list, only used if List ID is not provided +- **List ID**: The ID of the list, required if List Name is not provided + +
+ Get List Metadata +
+ +#### Example: + +```yaml +Site ID: tooljetxxxx.sharepoint.com,887cb371-e930-4e5b-a726-8d5769e6b946,6d653d09-1613-4663-99ab-1bb72ff6ceeb +List ID: 22f69173-0c1d-4c76-a721-5a31f0bd5af3 +``` + +
+**Response Example** + +```json +{ + "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites('tooljetxxxx.sharepoint.com%2C887cb371-e930-4e5b-a726-8d5769e6b946%2C6d653d09-1613-4663-99ab-1bb72ff6ceeb')/lists/$entity", + "@odata.etag": ""1a64ae23-9cb6-4521-b489-61d558dde9f7,11"", + "createdDateTime": "2024-10-24T11:11:10Z", + "description": "", + "eTag": ""1a64ae23-9cb6-4521-b489-61d558dde9f7,11"", + "id": "1a64ae23-9cb6-4521-b489-61d558dde9f7", + "lastModifiedDateTime": "2024-11-05T10:27:04Z", + "name": "Test_table_query", + "webUrl": "https://tooljetxxxx.sharepoint.com/sites/NewStyle/Lists/Test_table_query", + "displayName": "Test_table_query", + "createdBy": { + "user": { + "email": "oliver@tooljetxxxx.onmicrosoft.com", + "id": "90ccfd6b-17ea-402b-aa21-1a1799a547d6", + "displayName": "Oliver Smith" + } + }, + "lastModifiedBy": { + "user": { + "email": "oliver@tooljetxxxx.onmicrosoft.com", + "id": "90ccfd6b-17ea-402b-aa21-1a1799a547d6", + "displayName": "Oliver Smith" + } + }, + "parentReference": { + "siteId": "tooljetxxxx.sharepoint.com,887cb371-e930-4e5b-a726-8d5769e6b946,6d653d09-1613-4663-99ab-1bb72ff6ceeb" + }, + "list": { + "contentTypesEnabled": false, + "hidden": false, + "template": "genericList" + }, + "columns@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites('tooljetxxxx.sharepoint.com%2C887cb371-e930-4e5b-a726-8d5769e6b946%2C6d653d09-1613-4663-99ab-1bb72ff6ceeb')/lists('1a64ae23-9cb6-4521-b489-61d558dde9f7')/columns", + "columns": [ + { + "columnGroup": "Custom Columns", + "description": "", + "displayName": "USER_NAME", + "enforceUniqueValues": false, + "hidden": false, + "id": "fa564e0f-0c70-4ab9-b863-0177e6ddd247", + "indexed": false, + "name": "Title", + "readOnly": false, + "required": false, + "text": { + "allowMultipleLines": false, + "appendChangesToExistingText": false, + "linesForEditing": 0, + "maxLength": 255 + } + } + ], + "items@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites('tooljetxxxx.sharepoint.com%2C887cb371-e930-4e5b-a726-8d5769e6b946%2C6d653d09-1613-4663-99ab-1bb72ff6ceeb')/lists('1a64ae23-9cb6-4521-b489-61d558dde9f7')/items", + "items": [ + { + "@odata.etag": ""12b493eb-2452-451b-84e5-ecba8ec898c8,1"", + "createdDateTime": "2024-10-24T11:11:11Z", + "eTag": ""12b493eb-2452-451b-84e5-ecba8ec898c8,1"", + "id": "1", + "lastModifiedDateTime": "2024-10-24T11:11:11Z", + "webUrl": "https://tooljetxxxx.sharepoint.com/sites/NewStyle/Lists/Test_table_query/1_.000", + "createdBy": { + "user": { + "email": "oliver@tooljetxxxx.onmicrosoft.com", + "id": "90ccfd6b-17ea-402b-aa21-1a1799a547d6", + "displayName": "Oliver Smith" + } + }, + "lastModifiedBy": { + "user": { + "email": "oliver@tooljetxxxx.onmicrosoft.com", + "id": "90ccfd6b-17ea-402b-aa21-1a1799a547d6", + "displayName": "Oliver Smith" + } + }, + "parentReference": { + "id": "036d657d-ed69-4dcc-a669-483ce9788655", + "siteId": "tooljetxxxx.sharepoint.com,887cb371-e930-4e5b-a726-8d5769e6b946,6d653d09-1613-4663-99ab-1bb72ff6ceeb" + }, + "contentType": { + "id": "0x0100A3D887BE30452F4A9CBA7E684C523E2100098058C6B440D14786561D28914A3EDB", + "name": "Item" + }, + "fields@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites('tooljetxxxx.sharepoint.com%2C887cb371-e930-4e5b-a726-8d5769e6b946%2C6d653d09-1613-4663-99ab-1bb72ff6ceeb')/lists('1a64ae23-9cb6-4521-b489-61d558dde9f7')/items('1')/fields/$entity", + "fields": { + "@odata.etag": ""12b493eb-2452-451b-84e5-ecba8ec898c8,1"", + "Title": "Null_test", + "id": "1", + "AuthorLookupId": "7", + "EditorLookupId": "7", + "_UIVersionString": "1.0", + "Attachments": false, + "Edit": "", + "LinkTitleNoMenu": "Null_test", + "LinkTitle": "Null_test", + "ItemChildCount": "0", + "FolderChildCount": "0", + "_ComplianceFlags": "", + "_ComplianceTag": "", + "_ComplianceTagWrittenTime": "", + "_ComplianceTagUserId": "" + } + } + ] +} +``` + +
+ +### Create a List + +This operation creates a new list in a Sharepoint site. + +#### Required Parameters + +- **Site ID**: The ID of the site +- **Body**: The list configuration in JSON format + +
+ Create List +
+ +#### Example: + +```yaml +Site ID: tooljetxxxx.sharepoint.com,887cb371-e930-4e5b-a726-8d5769e6b946,6d653d09-1613-4663-99ab-1bb72ff6ceeb +Body: +{ + "displayName": "Project Tasks", + "columns": [ + { + "name": "TaskName", + "text": { } + }, + { + "name": "DueDate", + "dateTime": { } + }, + { + "name": "Priority", + "choice": { + "choices": ["High", "Medium", "Low"] + } + } + ], + "list": { + "template": "genericList" + } +} +``` + +
+**Response Example** + +```json +{ + "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites('tooljetxxxx.sharepoint.com%2C887cb371-e930-4e5b-a726-8d5769e6b946%2C6d653d09-1613-4663-99ab-1bb72ff6ceeb')/lists/$entity", + "@odata.etag": "f7497bc1-a8e6-49d0-a11c-05b3df1d8d2b,10", + "createdDateTime": "2024-11-05T10:48:51Z", + "description": "", + "eTag": "f7497bc1-a8e6-49d0-a11c-05b3df1d8d2b,10", + "id": "f7497bc1-a8e6-49d0-a11c-05b3df1d8d2b", + "lastModifiedDateTime": "2024-11-05T10:48:52Z", + "name": "Project Tasks", + "webUrl": "https://tooljetxxxx.sharepoint.com/sites/NewStyle/Lists/Project%20Tasks", + "displayName": "Project Tasks", + "createdBy": { + "user": { + "displayName": "Oliver Smith", + "email": "oliver@tooljetxxxx.onmicrosoft.com" + } + }, + "parentReference": { + "siteId": "tooljetxxxx.sharepoint.com,887cb371-e930-4e5b-a726-8d5769e6b946,6d653d09-1613-4663-99ab-1bb72ff6ceeb" + }, + "list": { + "contentTypesEnabled": false, + "hidden": false, + "template": "genericList" + } +} +``` + +
+ +### Get Items Of a List + +This operation retrieves items from a specific list. + +#### Required Parameters + +- **Site ID**: The ID of the site +- **List ID**: The ID of the list + +#### Optional Parameters + +- **Top**: The number of sites to retrieve +- **Page**: The page number to retrieve + +
+ Get List Items +
+ +#### Example: + +```yaml +Site ID: tooljetxxxx.sharepoint.com,887cb371-e930-4e5b-a726-8d5769e6b946,6d653d09-1613-4663-99ab-1bb72ff6ceeb +List ID: 22f69173-0c1d-4c76-a721-5a31f0bd5af3 +Top: 1 +Page: 1 +``` + +
+**Response Example** + +```json +{ + "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites('tooljetxxxx.sharepoint.com%2C887cb371-e930-4e5b-a726-8d5769e6b946%2C6d653d09-1613-4663-99ab-1bb72ff6ceeb')/lists('1a64ae23-9cb6-4521-b489-61d558dde9f7')/items(fields())", + "@odata.nextLink": "https://graph.microsoft.com/v1.0/sites/tooljetxxxx.sharepoint.com,887cb371-e930-4e5b-a726-8d5769e6b946,6d653d09-1613-4663-99ab-1bb72ff6ceeb/lists/1a64ae23-9cb6-4521-b489-61d558dde9f7/items?$expand=fields&$top=1&$skiptoken=UGFnZWQ9VFJVRSZwX0lEPTE", + "value": [ + { + "@odata.etag": ""12b493eb-2452-451b-84e5-ecba8ec898c8,1"", + "createdDateTime": "2024-10-24T11:11:11Z", + "eTag": ""12b493eb-2452-451b-84e5-ecba8ec898c8,1"", + "id": "1", + "lastModifiedDateTime": "2024-10-24T11:11:11Z", + "webUrl": "https://tooljetxxxx.sharepoint.com/sites/NewStyle/Lists/Test_table_query/1_.000", + "createdBy": { + "user": { + "email": "oliver@tooljetxxxx.onmicrosoft.com", + "id": "90ccfd6b-17ea-402b-aa21-1a1799a547d6", + "displayName": "Oliver Smith" + } + }, + "lastModifiedBy": { + "user": { + "email": "oliver@tooljetxxxx.onmicrosoft.com", + "id": "90ccfd6b-17ea-402b-aa21-1a1799a547d6", + "displayName": "Oliver Smith" + } + }, + "parentReference": { + "id": "036d657d-ed69-4dcc-a669-483ce9788655", + "siteId": "tooljetxxxx.sharepoint.com,887cb371-e930-4e5b-a726-8d5769e6b946,6d653d09-1613-4663-99ab-1bb72ff6ceeb" + }, + "contentType": { + "id": "0x0100A3D887BE30452F4A9CBA7E684C523E2100098058C6B440D14786561D28914A3EDB", + "name": "Item" + }, + "fields@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites('tooljetxxxx.sharepoint.com%2C887cb371-e930-4e5b-a726-8d5769e6b946%2C6d653d09-1613-4663-99ab-1bb72ff6ceeb')/lists('1a64ae23-9cb6-4521-b489-61d558dde9f7')/items('1')/fields/$entity", + "fields": { + "@odata.etag": ""12b493eb-2452-451b-84e5-ecba8ec898c8,1"", + "Title": "Null_test", + "field_2": 10, + "field_3": 123.32, + "field_4": 1, + "id": "1", + "ContentType": "Item", + "Modified": "2024-10-24T11:11:11Z", + "Created": "2024-10-24T11:11:11Z", + "AuthorLookupId": "7", + "EditorLookupId": "7", + "_UIVersionString": "1.0", + "Attachments": false, + "Edit": "", + "LinkTitleNoMenu": "Null_test", + "LinkTitle": "Null_test", + "ItemChildCount": "0", + "FolderChildCount": "0", + "_ComplianceFlags": "", + "_ComplianceTag": "", + "_ComplianceTagWrittenTime": "", + "_ComplianceTagUserId": "" + } + } + ] +} +``` + +
+ +### Update Item Of a List + +This operation updates an existing item in a list. + +#### Required Parameters + +- **Site ID**: The ID of the site +- **List ID**: The ID of the list +- **Item ID**: The ID of the item to update +- **Body**: The updated values in JSON format + +
+ Update Item +
+ +#### Example: + +```yaml +Site ID: tooljetxxxx.sharepoint.com,887cb371-e930-4e5b-a726-8d5769e6b946,6d653d09-1613-4663-99ab-1bb72ff6ceeb +List ID: 1a64ae23-9cb6-4521-b489-61d558dde9f7 +Item ID: 1 +Body: +{ + "TaskName": "Update Documentation", + "Priority": "Medium", + "DueDate": "2023-11-15T00:00:00Z" +} +``` + +
+**Response Example** + +```json +{ + "id": "1", + "fields": { + "TaskName": "Update Documentation", + "Priority": "Medium", + "DueDate": "2023-11-15T00:00:00Z" + } +} +``` + +
+ +### Delete Item Of a List + +This operation removes an item from a list. + +#### Required Parameters + +- **Site ID**: The ID of the site +- **List ID**: The ID of the list +- **Item ID**: The ID of the item to delete + +
+ Delete Item +
+ +#### Example: + +```yaml +Site ID: tooljetxxxx.sharepoint.com,da60e844-ba1d-49bc-b4d4-d5e36bae9019 +List ID: 22f69173-0c1d-4c76-a721-5a31f0bd5af3 +Item ID: 1 +``` + +
+**Response Example** + +```json +{ + "code": 204, + "status": "No Content", + "message": "Item having id '1' in List '1a64ae23-9cb6-4521-b489-61d558dde9f7' has been deleted." +} +``` + +
+ +### Add Item To a List + +This operation adds a new item to a list. + +#### Required Parameters + +- **Site ID**: The ID of the site +- **List ID**: The ID of the list +- **Body**: The new item's data in JSON format + +
+ Add Item +
+ +#### Example: + +```yaml +Site ID: tooljetxxxx.sharepoint.com,da60e844-ba1d-49bc-b4d4-d5e36bae9019 +List ID: 22f69173-0c1d-4c76-a721-5a31f0bd5af3 +Body: +{ + "fields": { + "Title": "Prepare Presentation" + } +} +``` + +
+**Response Example** + +```json +{ + "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites('tooljetxxxx.sharepoint.com%2C887cb371-e930-4e5b-a726-8d5769e6b946%2C6d653d09-1613-4663-99ab-1bb72ff6ceeb')/lists('1a64ae23-9cb6-4521-b489-61d558dde9f7')/items/$entity", + "@odata.etag": ""95d95442-f155-45be-ae85-ef9acf1d35f9,1"", + "createdDateTime": "2024-11-05T11:40:52Z", + "eTag": ""95d95442-f155-45be-ae85-ef9acf1d35f9,1"", + "id": "69", + "lastModifiedDateTime": "2024-11-05T11:40:52Z", + "webUrl": "https://tooljetxxxx.sharepoint.com/sites/NewStyle/Lists/Test_table_query/69_.000", + "createdBy": { + "user": { + "email": "oliver@tooljetxxxx.onmicrosoft.com", + "id": "90ccfd6b-17ea-402b-aa21-1a1799a547d6", + "displayName": "Oliver Smith" + } + }, + "lastModifiedBy": { + "application": { + "id": "0dc94ee2-9788-443c-8e67-ce714f0fe579", + "displayName": "Microsoft Graph" + }, + "user": { + "email": "oliver@tooljetxxxx.onmicrosoft.com", + "id": "90ccfd6b-17ea-402b-aa21-1a1799a547d6", + "displayName": "Oliver Smith" + } + }, + "parentReference": { + "id": "036d657d-ed69-4dcc-a669-483ce9788655", + "siteId": "tooljetxxxx.sharepoint.com,887cb371-e930-4e5b-a726-8d5769e6b946,6d653d09-1613-4663-99ab-1bb72ff6ceeb" + }, + "contentType": { + "id": "0x0100A3D887BE30452F4A9CBA7E684C523E2100098058C6B440D14786561D28914A3EDB", + "name": "Item" + }, + "fields@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites('tooljetxxxx.sharepoint.com%2C887cb371-e930-4e5b-a726-8d5769e6b946%2C6d653d09-1613-4663-99ab-1bb72ff6ceeb')/lists('1a64ae23-9cb6-4521-b489-61d558dde9f7')/items('69')/fields/$entity", + "fields": { + "@odata.etag": ""95d95442-f155-45be-ae85-ef9acf1d35f9,1"", + "Title": "Prepare Presentation", + "id": "69", + "ContentType": "Item", + "Modified": "2024-11-05T11:40:52Z", + "Created": "2024-11-05T11:40:52Z", + "AuthorLookupId": "7", + "EditorLookupId": "7", + "_UIVersionString": "1.0", + "Attachments": false, + "Edit": "", + "LinkTitleNoMenu": "Prepare Presentation", + "LinkTitle": "Prepare Presentation", + "ItemChildCount": "0", + "FolderChildCount": "0", + "_ComplianceFlags": "", + "_ComplianceTag": "", + "_ComplianceTagWrittenTime": "", + "_ComplianceTagUserId": "", + "AppAuthorLookupId": "3", + "AppEditorLookupId": "3" + } +} +``` + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/supabase.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/supabase.md new file mode 100644 index 0000000000..6fefbb22b2 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/supabase.md @@ -0,0 +1,160 @@ +--- +id: marketplace-plugin-supabase +title: Supabase +--- + +# Supabase + +ToolJet connects to your Supabase database, allowing you to directly interact with your Supabase back-end from within your ToolJet application. + +:::info +**NOTE:** **Before following this guide, it is assumed that you have already completed the process of [Using Marketplace plugins](/docs/marketplace/marketplace-overview#using-marketplace-plugins)**. +::: + +## Connection + +- To connect to Supabase you need to have the Project URL and Service Role Secret. You can find these credentials in your API Settings on the Supabase dashboard. Make sure to copy the Service Role Secret key. This key has the ability to bypass Row Level Security. + Supabase API Settings +- Establish a connection to Supabase by either clicking `+Add new Data source` on the query panel or navigating to the [Data Sources](/docs/data-sources/overview/) page from the ToolJet dashboard. +- Enter your Project URL and Service Role Secret into their designated fields. +- Click **Test Connection** to validate your credentials. Click **Save** to store the data source. + Supabase Install +## Querying Supabase + +- To perform queries on Supabase in ToolJet, click the **+Add** button in the [query manager](/docs/app-builder/query-panel/#query-manager) located at the bottom panel of the editor. +- Select the previously configured Supabase datasource. +- In the Operation dropdown, select the desired operation type. ToolJet currently [supports](#supported-operations) five query types for Supabase interactions. +- Enter the table name and other required parameters for the selected operation and click on **Run** button to run the query. + Supabase query + +:::info +Query results can be transformed using transformations. Read our [transformations documentation](/docs/beta/app-builder/custom-code/transform-data). +::: + +## Supported Operations + +You can create query for Supabase data source to perform several operations such as: + +1. **[Get Rows](#get-rows)** +2. **[Create Row(s)](#create-rows)** +3. **[Update Row(s)](#update-rows)** +4. **[Delete Row(s)](#delete-rows)** +5. **[Count Rows](#count-rows)** + +### Get Rows + +#### Required parameters: + +- **Table** - Database table name. + +#### Optional Parameters: + +- **Where** - Filter rows based on a condition. +- **Sort** - Sort rows based on a column. +- **Limit** - Limit the number of rows returned. + Get Rows + +
+**Example Response** + +```yaml +[ + { + "id": 1, + "created_at": "2025-02-12T08:50:25.780412+00:00", + "likes": 99, + "content": "CFBR!", + }, + { + "id": 4, + "created_at": "2025-02-12T11:34:26.624735+00:00", + "likes": 108, + "content": "Saved!", + }, +] +``` + +
+ +### Create Row(s) + +#### Required parameters: + +- **Table** - Database table name. +- **Body** - Data to be inserted into the table. It should be an array of object(s). + Create Rows + +
+**Example Response** + +```yaml +created: true +``` + +
+ +### Update Row(s) + +#### Required parameters: + +- **Table** - Database table name. +- **Columns** - Column name and value to be updated. + +#### Optional Parameters: + +- **Where** - Update rows based on a condition. If not provided, all rows will be updated. + Update Rows + +
+**Example Response** + +```yaml +[ + { + "id": 4, + "created_at": "2025-02-12T11:34:26.624735+00:00", + "likes": 50, + "content": "Saved!", + }, +] +``` + +
+ +### Delete Row(s) + +#### Required parameters: + +- **Table** - Database table name. +- **Where** - Delete rows based on a condition. + Delete Rows + + +
+**Example Response** + +```yaml +deleted: true +``` + +
+ +### Count Rows + +#### Required parameters: + +- **Table** - Database table name. + +#### Optional Parameters: + +- **Where** - Filter rows based on a condition. + Count Rows + +
+**Example Response** + +```yaml +count: 2 +``` + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/textract.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/textract.md new file mode 100644 index 0000000000..32494d4141 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/textract.md @@ -0,0 +1,60 @@ +--- +id: marketplace-plugin-textract +title: Amazon Textract +--- + +ToolJet integrates with Amazon Textract to facilitate the extraction of text and data from various document types, such as scanned documents, forms, and tables. Supported document formats include PDF, JPEG/JPG, and PNG. + +## Connection + +To connect ToolJet with Amazon Textract, you will need the following credentials: +- **Access key** +- **Secret key** +- **Region** + +:::caution +- Access to the S3 bucket is dependent on the permissions granted to the IAM role added for the connection. +- Only single page documents are supported. For multi-page PDFs, consider converting them to single-page formats with online tools. +::: + +
+ +Amazon Textract Configuration + +
+ +## Supported Queries + +- **[Analyze Document](#analyze-document)** +- **[Analyze document stored in AWS S3](#analyze-document-stored-in-aws-s3)** + +:::info +The data returned by the queries is in **JSON** format and may include additional information such as confidence scores and the location of the extracted content within the original document. +::: + +### Analyze Document + +This operation lets you analyze the document using the document data in **base64** format. + +#### Required Parameters: + +- **Document**: Supply the document data in base64 format. File Picker component can be used here to pick the document from the local system and retrieve the base64 data dynamically using exposed variables. Example: `{{components.filepicker1.file[0].base64Data}}`. +- **Data Output**: Choose the desired data output types for the document analysis. Options include: + 1. **Forms**: Extract key and value pairs from forms. + 2. **Tables**: Extract data from tables, including headers and cell content. + 3. **Queries**: Extract data from databases and other structured sources. + 4. **Signature Detection**: Identify and extract signatures. + +### Analyze Document Stored in AWS S3 + +This operation let's you analyze the document stored in your AWS S3 buckets by providing the **bucket** and **object** name. + +#### Required Parameters: + +- **Bucket**: Specify the S3 bucket containing the document. +- **Key**: Provide the name of the document (object) to be analyzed. +- **Data Output**: Select one or more type of data output of the document. Options include: + 1. **Forms**: Extract key and value pairs from forms. + 2. **Tables**: Extract data from tables, including headers and cell content. + 3. **Queries**: Extract data from databases and other structured sources. + 4. **Signature Detection**: Identify and extract signatures. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/weaviate.md b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/weaviate.md new file mode 100644 index 0000000000..893515a551 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/marketplace/plugins/weaviate.md @@ -0,0 +1,523 @@ +--- +id: marketplace-plugin-weaviate +title: Weaviate +--- + +Weaviate is a vector database, integrating Weaviate with ToolJet enables efficient vector search and semantic querying, allowing applications to retrieve relevant information based on meaning rather than exact keywords. This integration is ideal for building AI-powered search engines, recommendation systems, and knowledge retrieval applications that enhance user experience with context-aware results. + +## Connections + +### Cloud + +To connect with Weaviate Cloud, you will need the **Instance URL** and the **API Key**, which can be generated from **[Weaviate Console](https://weaviate.io/developers/wcs/connect)**. + +Weaviate Configuration + +### Local + +To connect ToolJet with Weaviate Local, you will need the **Host** and the **Port**. + +Run the following Docker command to start the container locally. This will set the host to `localhost` and port to `8080`. + +```yaml +docker run -p 8080:8080 -p 50051:50051 cr.weaviate.io/semitechnologies/weaviate:1.28.4 +``` + +Weaviate Configuration + +## Supported Operations + +## Data Type - Schema + +### Get Database Schema + +Run this opetation to get the database schema. + +**Optional Patameter** + +- **Consistency**: Ensures the request is handled by the leader node to maintain accuracy. + +Weaviate Configuration + +
+**Response Example** + +```json +{ + "classes": [ + { + "class": "Createcollection", + "description": "Test collection create", + "invertedIndexConfig": { + "bm25": { + "b": 0.75, + "k1": 1.2 + }, + "cleanupIntervalSeconds": 300, + "indexNullState": true, + "indexPropertyLength": true, + "indexTimestamps": true, + "stopwords": { + "additions": [ + "custom1" + ], + "preset": "en", + "removals": [ + "the" + ] + } + }, + "moduleConfig": { + "text2vec-contextionary": { + "vectorizeClassName": true + } + }, + "multiTenancyConfig": { + "autoTenantActivation": false, + "autoTenantCreation": false, + "enabled": false + }, + "properties": [ + { + "dataType": [ + "text" + ], + "description": "Main text field", + "indexFilterable": true, + "indexRangeFilters": false, + "indexSearchable": true, + "name": "content", + "tokenization": "word" + } + ], + "replicationConfig": { + "asyncEnabled": true, + "deletionStrategy": "NoAutomatedResolution", + "factor": 1 + }, + "shardingConfig": { + "virtualPerPhysical": 128, + "desiredCount": 1, + "actualCount": 1, + "desiredVirtualCount": 128, + "actualVirtualCount": 128, + "key": "_id", + "strategy": "hash", + "function": "murmur3" + }, + "vectorIndexConfig": { + "skip": false, + "cleanupIntervalSeconds": 300, + "maxConnections": 64, + "efConstruction": 128, + "ef": -1, + "dynamicEfMin": 100, + "dynamicEfMax": 500, + "dynamicEfFactor": 8, + "vectorCacheMaxObjects": 1000000000000, + "flatSearchCutoff": 40000, + "distance": "cosine", + "pq": { + "enabled": false, + "bitCompression": false, + "segments": 0, + "centroids": 256, + "trainingLimit": 100000, + "encoder": { + "type": "kmeans", + "distribution": "log-normal" + } + }, + "bq": { + "enabled": false + }, + "sq": { + "enabled": false, + "trainingLimit": 100000, + "rescoreLimit": 20 + }, + "filterStrategy": "sweeping" + }, + "vectorIndexType": "hnsw", + "vectorizer": "none" + } + ] +} +``` + +
+ +## Data Type - Collection + +### Get Collection + +**Required Parameter** + +- **Collection Name**: Name of the desired collection to fetch details. + +**Optional Parameter** + +- **Consistency**: Ensures the request is handled by the leader node to maintain accuracy. + +Weaviate Configuration + +
+**Response Example** + +```json +{ +[ + { + "dataType":["text"], + "description":"Main text field", + "indexFilterable":true, + "indexRangeFilters":false, + "indexSearchable":true, + "name":"content", + "tokenization":"word" + } +], +"replicationConfig":{ + "asyncEnabled":true, + "deletionStrategy":"NoAutomatedResolution", + "factor":1 +}, +"shardingConfig":{ + "virtualPerPhysical":128, + "desiredCount":1, + "actualCount":1, + "desiredVirtualCount":128, + "actualVirtualCount":128, + "key":"_id", + "strategy":"hash", + "function":"murmur3" +}, +"vectorIndexConfig":{ + "skip":false, + "cleanupIntervalSeconds":300, + "maxConnections":64, + "efConstruction":128, + "ef":-1, + "dynamicEfMin":100, + "dynamicEfMax":500, + "dynamicEfFactor":8, + "vectorCacheMaxObjects":1000000000000, + "flatSearchCutoff":40000, + "distance":"cosine", + "pq":{ + "enabled":false, + "bitCompression":false, + "segments":0, + "centroids":256, + "trainingLimit":100000, + "encoder":{ + "type":"kmeans", + "distribution":"log-normal" + } + }, + "bq":{ + "enabled":false + }, + "sq":{ + "enabled":false, + "trainingLimit":100000, + "rescoreLimit":20 + }, + "filterStrategy":"sweeping" +}, +"vectorIndexType":"hnsw", +"vectorizer":"none" +} +``` + +
+ +### Create Collection + +Use this operation to create a new collection. + +**Required Parameters** + +- **Collection Name**: The name of the collection. +- **Vectorizer**: Vectorizer to use for data objects added to this collection. +- **Vector index config**: Vector index type specific settings, including distance metric. +- **Module config**: Module-specific settings. +- **Description**: A description for your reference. +- **Properties**: An array of the properties you are adding, same as a Property Object. + +**Required Parameters** + +- **Consistency**: Ensures the request is handled by the leader node to maintain accuracy. +- **Sharding config**: Controls behavior of the collection in a multi-node setting. +- **Stop words**: Controls which words should be ignored in the inverted index. +- **Index time stamps**: Maintains inverted indexes for each object by its internal timestamps. +- **Index null state**: Maintains inverted indexes for each property regarding its null state. +- **Index property length**: Maintains inverted indexes for each property by its length. +- **Bm 25**: Search ranking method that boosts result accuracy using adjustable k1 and b values. By default, k1 = 1.2 and b = 0.75. +- **Factor**: Controls replication or sharding behavior for scaling. +- **Async enabled**: Runs operations in the background for better performance. +- **Deletion strategy**: Defines how deleted data is handled (e.g., immediate or delayed). +- **Cleanup interval seconds**: Sets how often old or deleted data is removed. + +Refer to **[weaviate documentation](https://weaviate.io/developers/weaviate/config-refs/schema)** for more information. + +Weaviate Configuration + +
+**Response Example** + +```json + +{ + "class":"Newcollection", + "description":"Test collection create", + "invertedIndexConfig":{ + "bm25":{ + "b":0.75, + "k1":1.2 + }, + "cleanupIntervalSeconds":300, + "indexNullState":true, + "indexPropertyLength":true, + "indexTimestamps":true, + "stopwords":{ + "additions":[ + "custom1" + ], + "preset":"en", + "removals":[ + "the" + ] + } + }, + "moduleConfig":{ + "text2vec-contextionary":{ + "vectorizeClassName":true + } + }, + "multiTenancyConfig":{ + "autoTenantActivation":false, + "autoTenantCreation":false, + "enabled":false + }, + "properties":[ + { + "dataType":[ + "text" + ], + "description":"Main text field", + "indexFilterable":true, + "indexRangeFilters":false, + "indexSearchable":true, + "name":"content", + "tokenization":"word" + } + ], + "replicationConfig":{ + "asyncEnabled":true, + "deletionStrategy":"NoAutomatedResolution", + "factor":1 + }, + "shardingConfig":{ + "virtualPerPhysical":128, + "desiredCount":1, + "actualCount":1, + "desiredVirtualCount":128, + "actualVirtualCount":128, + "key":"_id", + "strategy":"hash", + "function":"murmur3" + }, + "vectorIndexConfig":{ + "skip":false, + "cleanupIntervalSeconds":300, + "maxConnections":64, + "efConstruction":128, + "ef":-1, + "dynamicEfMin":100, + "dynamicEfMax":500, + "dynamicEfFactor":8, + "vectorCacheMaxObjects":1000000000000, + "flatSearchCutoff":40000, + "distance":"cosine", + "pq":{ + "enabled":false, + "bitCompression":false, + "segments":0, + "centroids":256, + "trainingLimit":100000, + "encoder":{ + "type":"kmeans", + "distribution":"log-normal" + } + }, + "bq":{ + "enabled":false + }, + "sq":{ + "enabled":false, + "trainingLimit":100000, + "rescoreLimit":20 + }, + "filterStrategy":"sweeping" + }, + "vectorIndexType":"hnsw", + "vectorizer":"none" +} +``` + +
+ +### Delete Collection + +Use this operation to delete a collection. + +**Required Parameters** + +- **Collection Name**: Collection name that needs to be deleted. + +Weaviate Configuration + +## Data Type - Objects + +### List Objects + +Use this operation to list all the objects of a collection. + +**Required Parameter** + +- **Collection Name**: Collection name to list its objects. + +**Optional Parameter** + +- **Include vectors**: Specify names of the vectors to include. +- **After**: A threshold UUID of the objects to retrieve after. +- **Offset**: The starting index of the result window. +- **Limit**: The maximum number of items to be returned per page. +- **Include**: Include additional information, such as classification infos. Allowed values include: classification, vector, interpretation. +- **Sort**: Name(s) of the property to sort by. +- **Order**: Determines sorting direction (asc or desc). +- **Tenant**: Specifies the tenant in a request targeting a multi-tenant class. + +Weaviate Configuration + +
+**Response Example** + +```json +{ + "deprecations":[], + "objects":[{ + "class":"Testcollection", + "creationTimeUnix":1739009190787, + "id":"296f9f17-628a-463a-b273-6ae369a3bb59", + "lastUpdateTimeUnix":1739009190787, + "properties":{ + "content":"This is a test document stored in Weaviate.", + "title":"New Sample Document" + }, + "vectorWeights":null + }, + { + "class":"Testcollection", + "creationTimeUnix":1738941448311, + "id":"550e8400-e29b-41d4-a716-446655440000", + "lastUpdateTimeUnix":1738941448311, + "properties":{ + "content":"This is a test document stored in Weaviate.", + "title":"Sample Document" + }, + "vectorWeights":null + }, + { + "class":"Testcollection", + "creationTimeUnix":1739008896994, + "id":"98a6628d-f07d-4f56-b64b-1b818201095c", + "lastUpdateTimeUnix":1739008896994, + "properties":{ + "content":"This is a test document stored in Weaviate.", + "title":"Sample Document" + }, + "vectorWeights":null + }], + "totalResults":3 +} +``` + +
+ +### Create Object + +Use this operation to create a new object within the selected collection. + +**Required Parameters** + +- **Collection Name**: Collection name to create an object inside it. +- **Properties**: An array of the properties you are adding, same as a Property Object. +- **Vector**: Enter the vector for the object. + +**Optional Parameter** + +- **Object uuid**: The UUID of the object. + +Weaviate Configuration + +
+**Response Example** + +```json +{ + "class":"Testcollection", + "creationTimeUnix":1739009190787, + "id":"296f9f17-628a-463a-b273-6ae369a3bb59", + "lastUpdateTimeUnix":1739009190787, + "properties":{ + "content":"This is a test document stored in Weaviate.", + "title":"New Sample Document" + }, + "vector":[0.12345,0.12345,.......,0.12345,0.12345] +} +``` + +
+ +### Get Object By Id + +Use this operation to fetch an object using it's ID. + +**Required Parameters** + +- **Collection Name**: Collection Name of the object. +- **Object ID**: Object ID to fetch the object details. + +Weaviate Configuration + +
+**Response Example** + +```json +{ + "class":"Testcollection", + "creationTimeUnix":1738941448311, + "id":"550e8400-e29b-41d4-a716-446655440000", + "lastUpdateTimeUnix":1738941448311, + "properties":{ + "content":"This is a test document stored in Weaviate.", + "title":"Sample Document" + }, + "vectorWeights":null +} +``` + +
+ +### Delete Object By Id + +Use this operation to delete the object using it's ID. + +**Required Parameters** + +- **Collection Name**: Collection Name of the object. +- **Object ID**: Object ID of the object to be deleted. + +Weaviate Configuration diff --git a/docs/versioned_docs/version-3.16.0-LTS/project-overview/release-notes.md b/docs/versioned_docs/version-3.16.0-LTS/project-overview/release-notes.md new file mode 100644 index 0000000000..35ed093e79 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/project-overview/release-notes.md @@ -0,0 +1,72 @@ +--- +id: release-notes +title: Release Notes +--- + +# ToolJet 3.0 Release Notes + +This document outlines the key improvements introduced in ToolJet 3.0, a major upgrade focused on performance, scalability, and developer experience. + +## App Builder + +1. Up to 10 times faster app loading speeds +2. Smooth app development even with 1000s of components and 100s of queries +2. More intuitive experience in designing applications on the canvas with the new grid system +4. Highly configurable **[page management system](/docs/tutorial/pages)** +5. Revamped **[components](/docs/widgets/table/)** with more styling and functionality customizations +6. Enhanced developer experience in managing queries with the **[new query manager UI](/docs/app-builder/query-panel)** +7. Improved coding experience with better code suggestions, linting, and type-casting +8. Better debugging with easy-to-understand error messages +9. Theme settings: Light/dark/auto mode at the application level + +## Platform Enhancements + +1. **[Group Sync OIDC](/docs/user-management/sso/oidc/setup)**: Easily manage user access to ToolJet applications from your Identity Provider (IDP) directly +2. **[Secrets constants](/docs/security/constants/#using-secrets)**: Ability to store encrypted credentials +3. **[User metadata](/docs/user-management/onboard-users/user-metadata)**: Store custom metadata with user details & access them while building applications +4. User roles: Revamped user groups with granular access control +5. **[User APIs](/docs/tooljet-api#get-all-users)**: External API for creating and managing users +6. Security fixes: Various improvements to enhance platform security + +## ToolJet Database (TJ DB) + +1. **[Custom primary key](/docs/tooljet-db/constraints/primary-key)** and **[foreign key support](/docs/tooljet-db/constraints/foreign-key)** +2. Support for more data types for advanced use cases +3. **[SQL mode](/docs/tooljet-db/querying-tooljet-db#sql-editor)** for complex querying +4. Bulk upload using CSV +5. GUI for **[complex SQL queries](/docs/tooljet-db/querying-tooljet-db#gui-mode)** like joins, aggregates, and group by + +## Integrations + +1. 15+ new integrations, including: + - AWS services (Textract, Lambda, Redshift) + - OpenAI + - Databricks + - Salesforce + - Jira + - Sharepoint + - Supabase +2. Client Credentials Grant Type + +## AI Apps + +Build AI apps using **[OpenAI](/docs/marketplace/plugins/marketplace-plugin-openai)**, and **[Portkey](/docs/marketplace/plugins/marketplace-plugin-portkey)** integrations + +## Workflows + +1. Introduction of **[loop node](/docs/workflows/nodes#loop-node)** to implement iterative processes +2. Improved error handling and debugger: Improved troubleshooting +3. Support for multiple deployment environments +4. **[Webhook triggers](/docs/workflows/workflow-triggers#webhooks)** to trigger workflows from external apps and services +5. **[Multiple result nodes](/docs/workflows/results)** for greater flexibility in defining the output + +## Migration Steps + +Ready to upgrade to ToolJet 3.0? Follow our migration guides: +- **[For Self-Hosted Users](/docs/setup/upgrade-to-v3)** +- **[For Cloud Users](/docs/setup/cloud-v3-migration)** + +This release significantly enhances ToolJet's capabilities across its platform, focusing on improved performance, expanded integrations, and smoother development experience for building complex applications. The addition of AI-powered features and the release of Workflows provide users with advanced tools for creating sophisticated, automated solutions. + + + diff --git a/docs/versioned_docs/version-3.16.0-LTS/security/audit-logs.md b/docs/versioned_docs/version-3.16.0-LTS/security/audit-logs.md new file mode 100644 index 0000000000..4bf7b95368 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/security/audit-logs.md @@ -0,0 +1,225 @@ +--- +id: audit-logs +title: Audit Logs +--- + +
+ Icon + Paid feature +
+ +The audit log is the report of all the activities done in your ToolJet account. It will capture and display events automatically by recording who performed an activity, what when, and where the activity was performed, along with other information such as IP address. + +Audit logs + +### Date Range + +Retrieve the log of events that occurred within the specified date and time range using the range picker. By default, the system loads 24-hour logs for the initial view. The maximum duration that can be specified for the "from" and "to" dates is 30 days. + +:::info +Pagination at the bottom allows navigation through the pages, with each page displaying a maximum of 7 logs. +::: + +Audit logs + +## Audit Log Retention Period + +By default, audit logs are retained for 90 days. However, admins can customize this retention period by setting the following environment variable: + +```js +AUDIT_LOGS_RETENTION_PERIOD +``` + +To retain audit logs indefinitely, set the variable to 0. + +## Filter Audit Logs + +You can apply filters to the audited events based on the following criteria. + +## Select Users + +Choose a specific user from the dropdown list to view all their activities. + +## Select Apps + +The dropdown will display all the apps associated with your account. Select an app to filter the logs related to that particular app. + +## Select Resources + +|
Resources
|
Description
| +| ----------- | ----------- | +| User | Filter all the User events like `USER_LOGIN`, `USER_SIGNUP`, `USER_INVITE`, AND `USER_INVITE_REDEEM`. | +| App | Filter all the App events like `APP_CREATE`, `APP_UPDATE`,`APP_DELETE`,`APP_IMPORT`,`APP_EXPORT`,`APP_CLONE`. | +| Data Query | Filters the events associated with Data Query like `DATA_QUERY_RUN`. | +| Group Permission | All the events associated with Group Permissions will be filtered. Group Permissions include `GROUP_CREATE`, `GROUP_UPDATE`, `GROUP_DELETE`. | +| App Group Permission | Within each group, you can set apps for read or edit privileges. These events get recorded as App Group Permissions. | + +## Select Actions + +### User + +|
Actions
|
Description
| +| ----------- | ----------- | +| USER_LOGIN | This event is recorded everytime a user logins. | +| USER_SIGNUP | This event is recorded everytime a new signup is made. | +| USER_INVITE | You can invite users to your account from `Manage Users` section and an event is audited everytime an invite is sent. | +| USER_INVITE_REDEEM | This event is recorded whenever an invite is redeemed. | +| USER_LOGOUT | This event is recorded whenever a user logs out. | +| USER_ARCHIVE | This event is recorded whenever a user is archived. | +| USER_UNARCHIVE | This event is recorded whenever a user is unarchived. | +| USER_PROFILE_UPDATE | This event is recorded whenever a user's name or avatar is updated. | +| USER_PASSWORD_FORGOT | This event is recorded whenever a user requests forgot password link from the login screen. | +| USER_PASSWORD_RESET | This event is recorded whenever a super admin resets a user password at the instance level. | +| USER_PASSWORD_UPDATE | This event is recorded whenever a user update the password from profile settings. | +| USER_DETAILS_UPDATE | This event is recorded whenever a super admin updates the user details. | + +### User Groups and Permissions + +|
Actions
|
Description
| +| ----------- | ----------- | +| SET_AS_SUPERADMIN | This event is recorded whenever a user is promoted to super admin. | +| GROUP_PERMISSION_CREATE | This event is recorded whenever a group is created. | +| GROUP_PERMISSION_UPDATE | This event is recorded whenever an app or user is added to or removed from a group, or the permissions for a group are updated. | +| GROUP_PERMISSION_DELETE | This event is recorded whenever a user group is deleted from an account. | +| GROUP_PERMISSION_DUPLICATE | This event is recorded whenever a group and permission is duplicated. | +| USER_ADD_TO_GROUP | This event is recorded whenever a user is added to a group. | +| USER_REMOVE_FROM_GROUP | This event is recorded whenever a user is removed from a group. | +| GRANULAR_PERMISSION_APP_CREATE | This event is recorded whenever an app level granular permission is created. | +| GRANULAR_PERMISSION_APP_UPDATE | This event is recorded whenever an app level granular permission is updated. | +| GRANULAR_PERMISSION_APP_DELETE | This event is recorded whenever an app level granular permission is deleted. | +| GRANULAR_PERMISSION_DATA_SOURCE_CREATE | This event is recorded whenever a data source level permission is created. | +| GRANULAR_PERMISSION_DATA_SOURCE_UPDATE | This event is recorded whenever a data source level permission is updated. | +| GRANULAR_PERMISSION_DATA_SOURCE_DELETE | This event is recorded whenever a data source level permission is deleted. | + +### Workspace + +|
Actions
|
Description
| +| ----------- | ----------- | +| WORKSPACE_CREATE | This event is recorded whenever a new workspace is created. | +| WORKSPACE_UPDATE | This event is recorded whenever a workspace name or slug is updated. | +| WORKSPACE_ARCHIVE | This event is recorded whenever a workspace is archived. | +| WORKSPACE_UNARCHIVE | This event is recorded whenever a workspace is unarchived. | +| WORKSPACE_LOGIN_SETTINGS_UPDATE | This event is recorded whenever workspace login settings is updated. | + + +### App + +|
Actions
|
Description
| +| ----------- | ----------- | +| APP_CREATE | This event is recorded when a user creates a new app. | +| APP_UPDATE | This event is recorded whenever actions like renaming the app, making the app public, editing shareable link, or deploying the app are made. | +| APP_PROMOTE | This event is recorded whenever an application's environment is promoted. | +| APP_RELEASE | This event is recorded whenever an application is released. | +| APP_SHARE | This event is recorded whenever an application is shared. | +| APP_PUBLIC_UPDATE | This event is recorded whenever an application is made public. | +| APP_DELETE | This event is recorded whenever a user deletes an app from the dashboard. | +| APP_IMPORT | This event is recorded whenever a user imports an app. | +| APP_EXPORT | This event is recorded whenever an app is exported. | +| APP_CLONE | This event is recorded whenever a clone of the existing app is created. | +| APP_VERSION_CREATE | This event is recorded whenever a new version of an application is created. | +| APP_VERSION_UPDATE | This event is recorded whenever a version of an application is updated. | +| APP_VERSION_DELETE | This event is recorded whenever a version of an application is deleted. | + +### Data Source + +|
Actions
|
Description
| +| ----------- | ----------- | +| DATA_SOURCE_CREATE | This event is recorded whenever a new data source is created. | +| DATA_SOURCE_UPDATE | This event is recorded whenever a data source is updated. | +| DATA_SOURCE_DELETE | This event is recorded whenever a data source is deleted. | +| DATA_QUERY_RUN | This event is logged whenever a query run either from the query editor or from the launched app. | + +## Understanding Log Information + +Audit logs + +|
Property
|
Description
| +| ----------- | ----------- | +| action_type | This indicates the type of action that was logged in the event. Refer to [this](#select-actions) for more information on actions. | +| created_at | Shows the date and time when the event was logged. | +| id | Each logged event is assigned a unique event ID. | +| ip_address | Displays the IP address from which the event was logged. | +| metadata | The metadata includes two sub-properties: `tooljet_version` and `user_agent`. `tooljet_version` shows the version of ToolJet used for the event, while `user_agent` contains information about the device and browser used. | +| organization_id | Every organization in ToolJet has a unique ID associated with it, which is recorded when an event occurs. | +| resource_id | Different [resources](#select-resources) have their respective IDs associated with them. These IDs are assigned when the resources are created. | +| resource_name | Shows the name of the [resources](#select-resources) that were involved in the logged event. For example, if an app was created or deleted, it will display the name of that app. | +| resource_type | Indicates the type of the [resources](#select-resources) involved in the logged event. | +| user_id | Each user account in ToolJet has a unique ID associated with it, which is recorded when an event occurs. | + +### Log File + +The file will contain all the data from audit logs. The log file can be created by specifying the path in the [environment variables](/docs/setup/env-vars). The log file is rotated on a daily basis and is updated dynamically every time a new audit log is generated. + +Learn more about **setting up the log file generation** [here](/docs/how-to/setup-rsyslog). + +### Log Rotation + +The log file is configured to rotate on a daily basis. This means that a new log file will be created every day, ensuring efficient management and organization of audit data. + +### Log Redaction + +ToolJet implements log redaction to protect sensitive information. By default, the following headers are masked in the logs: + +- authorization +- cookie +- set-cookie +- x-api-key +- proxy-authorization +- www-authenticate +- authentication-info +- x-forwarded-for + +Additionally, you can specify custom fields to be masked using the `LOGGER_REDACT` environment variable. + +|
Variable
|
Description
| +| -------- | --------------------------------------------------------------------------- | +| LOGGER_REDACT | Comma-separated list of additional fields to be masked in logs (e.g., req.headers["x-session-id"],req.headers["x-device-fingerprint"]) | + +For example: +```bash +LOGGER_REDACT=res.headers["x-rate-limit-remaining"],res.headers["x-request-id"] +``` + +### Log File Path + +The path for the log file is defined using the `LOG_FILE_PATH` variable in the environment. It's important to understand that this path is relative to the home directory of the machine. For instance, if `LOG_FILE_PATH` is set to `hsbc/dashboard/log`, the resulting log file path will be structured as follows: +``` +homepath/hsbc/dashboard/log/tooljet_log/{process_id}-{date}/audit.log +``` +Here, `{process_id}` is a placeholder for the unique process identifier, and `{date}` represents the current date. This structured path ensures that audit logs are organized by both process and date, facilitating easy traceability and analysis. + +|
Variable
|
Description
| +| -------- | --------------------------------------------------------------------------- | +| LOG_FILE_PATH | the path where the log file will be created ( eg: tooljet/log/tooljet-audit.log) | + +
+Example Log file data + +```bash +{ + level: 'info', + message: 'PERFORM APP_CREATE OF awdasdawdwd APP', + timestamp: '2023-11-02 17:12:40', + auditLog: { + userId: '0ad48e21-e7a2-4597-9568-c4535aedf687', + organizationId: 'cf8e132f-a68a-4c81-a0d4-3617b79e7b17', + resourceId: 'eac02f79-b8e2-495a-bffe-82633416c829', + resourceType: 'APP', + actionType: 'APP_CREATE', + resourceName: 'awdasdawdwd', + ipAddress: '::1', + metadata: { + userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36', + tooljetVersion: '2.22.2-ee2.8.3' + } + }, + label: 'APP' +} +``` + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/security/compliance.md b/docs/versioned_docs/version-3.16.0-LTS/security/compliance.md new file mode 100644 index 0000000000..0745efb75a --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/security/compliance.md @@ -0,0 +1,55 @@ +--- +id: compliance +title: Compliance +--- + +## Uncompromised Data Security with SOC 2 Type II Compliance + +With SOC 2 Type II compliance, ToolJet ensures the highest level of data security. The adherence to SOC 2 Type II standards mirrors the rigorous data protection measures in place, covering everything from encryption to robust access controls. It also guarantees a consistent level of service availability and process integrity, instilling confidence in our customers and stakeholders about the safe handling of their sensitive information. + +## Data Protection +We take extensive measures to protect your data. All data transmitted between users and our servers is encrypted using TLS to prevent unauthorized access during transit. Sensitive data stored on our servers is encrypted at rest, following industry-standard protocols. Access to this data is tightly controlled through role-based permissions, ensuring only authorized personnel can access sensitive information. + +We also adhere to a **GDPR-compliant data deletion policy**, ensuring that personal data is permanently removed from our servers upon user request or at the end of the data retention period. Furthermore, we maintain comprehensive audit logs to track data access and modifications for monitoring and compliance purposes. + +## Compliance and Certifications +We adhere to globally recognized standards for data security and compliance. ToolJet meets the requirements of the following certifications: + +**GDPR**: ToolJet fully complies with the General Data Protection Regulation (GDPR), ensuring your personal data is processed and stored securely. + +**SOC 2**: We undergo regular SOC 2 Type II audits to validate our commitment to maintaining high security, availability, and confidentiality standards. + +**ISO 27001**: ToolJet follows the ISO 27001 standard for information security management, ensuring a systematic approach to managing sensitive information. + +## Incident Response +We continuously monitor our systems for suspicious activities or security incidents. In the event of a security breach, we have a detailed incident response plan in place. This plan ensures immediate action is taken to contain the breach, communicate with affected parties, and implement remediation steps to prevent future incidents. + +## Secure Development Practices +We adhere to globally recognized standards for data security and compliance. ToolJet meets the requirements of the certifications below. + +We undergo regular **SOC 2 Type II audits** to validate our commitment to maintaining high standards in security, availability, and confidentiality. + +## User Responsibility +We encourage all our users to practice good security habits to enhance security further. This includes creating strong, unique passwords for ToolJet accounts and enabling two-factor authentication for added protection. Users should also keep their devices and applications updated to guard against vulnerabilities. + + +## Data Storage + +ToolJet does not store data returned from your data sources. ToolJet server acts as a proxy and passes the data as it is to the ToolJet client. The credentials for the data sources are handled by the server and never exposed to the client. For example, if you are making an API request, the query is run from the server and not from the frontend. + + +## Datasource Credentials +All the datasource credentials are securely encrypted using `aes-256-gcm`. The credentials are never exposed to the frontend ( ToolJet client ). + +## Privacy Policy +ToolJet takes privacy seriously. Our transparent privacy policies ensure customers understand how their data is collected, stored, and processed. We adhere to privacy regulations in all regions in which we operate. + +## Other Security Features +- **TLS**: If you are using ToolJet cloud, all connections are encrypted using TLS. We also have documentation for setting up TLS for self-hosted installations of ToolJet. +- **Audit logs**: Audit logs are available on the enterprise edition of ToolJet. Every user action is logged along with the IP addresses and user information. +- **Request logging**: All the requests to server are logged. If self-hosted, you can easily extend ToolJet to use your preferred logging service. ToolJet comes with built-in Sentry integration. +- **Whitelisted IPs**: If you are using ToolJet cloud, you can whitelist our IP address (130.131.224.28) so that your datasources are not exposed to the public. +- **Backups**: ToolJet cloud is hosted on AWS using EKS with autoscaling and regular backups. + +If you notice a security vulnerability, please let the team know by sending an email to [security@tooljet.com](mailto:security@tooljet.com). + diff --git a/docs/versioned_docs/version-3.16.0-LTS/security/constants/constants.md b/docs/versioned_docs/version-3.16.0-LTS/security/constants/constants.md new file mode 100644 index 0000000000..6fa105f4cf --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/security/constants/constants.md @@ -0,0 +1,133 @@ +--- +id: constants +title: Workspace Constants +--- + +ToolJet allows you to set workspace constants to store pre-defined values that can be used across your application to maintain consistency, facilitate easy updates, and securely store sensitive information. Workspace constants are specific to the workspace where they are created and cannot be accessed in other workspaces. To enhance security, all constants and secrets are encrypted before being stored in the database, providing an additional layer of protection for sensitive data. + +There are two types of constants: +1. **Global Constants:** These are predefined values that can be used across your applications within a workspace. They allow you to store frequently used values, such as API URLs, configuration settings, etc. and access them within the workspace. Global Constants are resolved on the client side. +2. **Secret Constants:** These are a specific type of workspace constants designed for securely storing sensitive information like API keys and database credentials. Secrets are masked and stored in encrypted format to prevent exposure to unauthorized users. Secret Constants are resolved on the server side, preventing exposure to the client.
+ **Note**: Secret Constants cannot be used in RunJS or RunPy queries. + +## Characteristics and Usage + +| Characteristic | Global Constants | Secrets | +|-------------------------|:-----------------------------:|:-------------------------:| +| Components | βœ… | ❌ | +| Data Queries | βœ… | βœ… | +| Data Sources | βœ… | βœ… | +| Workflows | βœ… | Coming Soon | +| Encrypted in DB | βœ… | βœ… | +| Masked in Frontend | ❌ | βœ… | +| Resolved on Client Side | βœ… | ❌ | +| Resolved on Server Side | ❌ | βœ… | +| Naming Convention | `{{constants.constant_name}}` | `{{secrets.secret_name}}` | + +**Note**: +1. Secret Constants cannot be used in RunJS or RunPy queries. +2. Secret Constants can only be used as a singular key and can't be used in a composite key manner. + +## Environment Specific Configurations + +ToolJet allows users to define environment-specific configurations by assigning different values to constants and secrets across various environments. This approach is essential for managing sensitive information, such as API keys, database credentials, and external service endpoints, which may differ between development, staging, and production environments. + +For example, you can configure unique API keys for each environment to ensure seamless integration and security. + +Environment-Specific Constants + +## Creating Workspace Constants + +Workspace constants/variables permissions is needed to Create, Update or Delete workspace constants, refer to **[Access Control](/docs/user-management/role-based-access/access-control)** guide for more information. After having the required permission, follow these steps to create a workspace constant: + +1. Navigate to the Workspace Constants tab from the left sidebar in ToolJet dashboard.
+ (Example URL - `https://app.corp.com/nexus/workspace-constants`) + Environment-Specific Constants + +2. Click on **Create new constant** button to open the configuration drawer. + Create New Constant + +3. Enter a name and value for the workspace constant. + +4. Select the type of workspace constant: + - **Global constant** + - **Secret** + +5. Click the **Add constant** button to save. + +:::info +Once a constant or secret is created, its type cannot be changed. You'll need to delete it and create a new one of the desired type. +::: + +## Accessing Workspace Constants + +### Global Constants + +Global constants can be accessed using the syntax `{{constants.constant_name}}` can be used in the [app builder](#in-app-builder), data sources, data queries, and workflows. + +#### In App Builder + +Inside the App Builder, you can find all the constants inside the inspector element on the left sidebar. + +Use Global Constants Inside App Builder + +#### In Data Sources and Queries + +Global constants in ToolJet allow you to define values once and reuse them across your data sources and queries. + +- Data Source Connection Form: + Use Global Constants Data Source Connection Form + +- Inside Queries in Query Manager: + Use Global Constants Inside Queries in Query Manager + +### Using Secrets + +Secrets are designed for secure storage of sensitive information like API keys, database credentials, and can be access using the syntax `{{secrets.secret_name}}`. + +#### In Data Sources and Queries + +In Data Sources and Queries, secret values are masked in the frontend and can only be viewed in the Workspace Constants dashboard. + +- Data Source Connection Form: + Use Secrets in Data Source Connection Form + +- Inside Queries in Query Manager: + Use Secrets Inside Queries in Query Manager + +## Mapping Workspace Constants from Environment Variables + +From version **`v3.5.8-ee-lts`**, you can use environment variables to set global and secret constants. Workspace constants set using environment variables will have a `.env` tag in front of them. If there are two constants with the same name, the one set through the environment variable will be used in the app builder, while the constant set through the UI will have a `duplicate` tag in front of it. + +Users cannot edit or delete constants created from environment variables through the UI. To add, update, or delete any values from an environment variable, the container must be restarted. + +Mapping Workspace Constants from Environment Variables + +### Setting Global Constants + +**Setting Individual Global Constant** + +Syntax - `TOOLJET_GLOBAL_CONSTANTS____constant_name` + +Example - TOOLJET_GLOBAL_CONSTANTS__development__companyName = "Corp Pvt. Ltd." + +**Setting Multiple Global Constants** + +Syntax - `TOOLJET_GLOBAL_CONSTANTS__ = {β€œname1”: β€œvalue1", β€œname2”: β€œvalue2"}` + +Example - TOOLJET_GLOBAL_CONSTANTS__development = `{"company1": "corp.com", "company2": "example.com"}` + + +### Setting Secret Constants + +**Setting Individual Global Constant** + +Syntax - `TOOLJET_SECRET_CONSTANTS____constant_name` + +Example - TOOLJET_SECRET_CONSTANTS__development__apiKey = "agdagdagdg" + +**Setting Multiple Global Constants** + +Syntax - `TOOLJET_SECRET_CONSTANTS__ = {β€œname1”: β€œvalue1", β€œname2”: β€œvalue2"}` + +Example - TOOLJET_SECRET_CONSTANTS__development = `{"api_url": "https://api.example.com", "password" : "12345", "key" : "agdagdagdg"}` diff --git a/docs/versioned_docs/version-3.16.0-LTS/security/constants/variables.md b/docs/versioned_docs/version-3.16.0-LTS/security/constants/variables.md new file mode 100644 index 0000000000..478d9ec353 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/security/constants/variables.md @@ -0,0 +1,51 @@ +--- +id: variables +title: Workspace Variables Migration +--- + +
+ Icon + Deprecated +
+ + + +

+ +Workspace variables were used in ToolJet to store values such as tokens, secret keys, API keys, etc. But currently **Workspace variables are marked as deprecated, indicating that it will be removed in future releases**. In the current version, you are still able to delete existing variables and use it through out any ToolJet apps, but creating and updating variables are no longer supported. + +Please use **[Workspace Constants](/docs/security/constants/)** instead. This guide will help you migrate from **Workspace Variables** to **Workspace Constants**. + +## Workspace Constants + +Workspace Constants are predefined values that enhance consistency, simplify updates, and securely store sensitive information across applications within a workspace. Unlike other variables, they are resolved exclusively on the server side, ensuring a high level of security by preventing client-side exposure. Refer to **[Workspace Constants](/docs/security/constants/)** guide for more information. + +## Migrating from Workspace Variables to Workspace Constants + +To migrate from Workspace Variables to Workspace Constants, you need to create new constants and store each value, follow the steps in **[Creating Workspace Constants](/docs/security/constants/#creating-workspace-constants)** guide. + +Once you have migrated all the Workspace Variables to Workspace Constants, you can replace the Workspace Variables in your apps with their corresponding Workspace Constants. + +### Replacing Workspace Variables with Workspace Constants + +- Navigate to the app or data source where you want to replace the Workspace Variables. +- Replace the Workspace Variables with their corresponding Workspace Constants.
+ For example, if you have a Client Workspace Variable like `%%client.pi%%`, replace it with `{{constants.pi}}`.
+ Workspace constants + + Workspace constants + +### Deleting Workspace Variables + +After migrating all Workspace Variables to Workspace Constants and thoroughly testing your applications, you can delete the Workspace Variables. To remove a Workspace Variable, follow these steps: + +1. Navigate to the Workspace Variables tab in the Workspace Settings.
+ (Example URL - `https://app.corp.com/nexus/workspace-settings/workspace-variables`) + +2. Click on the delete icon next to the Workspace Variable you want to delete. + Workspace constants \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/_category_.json b/docs/versioned_docs/version-3.16.0-LTS/setup/_category_.json new file mode 100644 index 0000000000..1211453a23 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Setup", + "position": 2, + "collapsed": true +} diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/ami.md b/docs/versioned_docs/version-3.16.0-LTS/setup/ami.md new file mode 100644 index 0000000000..f42a70c958 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/ami.md @@ -0,0 +1,126 @@ +--- +id: ami +title: AWS AMI +--- + +# Deploying ToolJet on Amazon AMI + +:::info +You should setup a PostgreSQL database manually to be used by the ToolJet server. +::: + +You can effortlessly deploy Amazon Elastic Compute Cloud Service (EC2) by utilizing a **CloudFormation template**. This template will deploy all the services required to run ToolJet on AWS AMI instances. + +To deploy all the services at once, simply employ the following template: + +``` +curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/cloudformation/EC2-cloudfomration.yml +``` + +Follow the steps below to deploy ToolJet on AWS AMI instances. + +1. Setup a PostgreSQL database and make sure that the database is accessible from the EC2 instance. +2. Login to your AWS management console and go to the EC2 management page. +3. Under the **Images** section, click on the **AMIs** button. +4. Find the [ToolJet version](https://github.com/ToolJet/ToolJet/releases) you want to deploy. Now, from the AMI search page, select the search type as "Public Images" and input the version you'd want `AMI Name : tooljet_vX.X.X.ubuntu_bionic` in the search bar. +5. Select ToolJet's AMI and bootup an EC2 instance.
+ Creating a new security group is recommended. For example, if the installation should receive traffic from the internet, the inbound rules of the security group should look like this: + + | protocol | port | allowed_cidr | + | -------- | ---- | ------------ | + | tcp | 22 | your IP | + | tcp | 80 | 0.0.0.0/0 | + | tcp | 443 | 0.0.0.0/0 | + +6. Once the instance boots up, SSH into the instance by running `ssh -i ubuntu@`. + +7. Switch to the app directory by running `cd ~/app`.
Modify the contents of the `.env` file. ( Eg: `vim .env` ) + + The default `.env` file looks like this: + + ```bash + LOCKBOX_MASTER_KEY= + SECRET_KEY_BASE= + PG_DB= + PG_USER= + PG_HOST= + PG_PASS= + TOOLJET_DB= + TOOLJET_DB_HOST= + TOOLJET_DB_USER= + TOOLJET_DB_PASS= + ``` + + Read **[environment variables reference](/docs/setup/env-vars)** + + :::info + If there are self signed HTTPS endpoints that ToolJet needs to connect to, please make sure that `NODE_EXTRA_CA_CERTS` environment variable is set to the absolute path containing the certificates. + ::: + +8. `TOOLJET_DB_HOST` environment variable determines where you can access the ToolJet client. It can either be the public ipv4 address of your instance or a custom domain that you want to use. + + Examples: + `TOOLJET_DB_HOST=http://12.34.56.78` or + `TOOLJET_DB_HOST=https://yourdomain.com` or + `TOOLJET_DB_HOST=https://tooljet.yourdomain.com` + + :::info + We use a [lets encrypt](https://letsencrypt.org/) plugin on top of nginx to create TLS certificates on the fly. + ::: + + :::info + Please make sure that `TOOLJET_DB_HOST` starts with either `http://` or `https://` + ::: + +9. Once you've configured the `.env` file, run `./setup_app`. This script will install all the dependencies of ToolJet and then will start the required services. +10. If you've set a custom domain for `TOOLJET_HOST`, add a `A record` entry in your DNS settings to point to the IP address of the EC2 instance. +11. You're all done, ToolJet client would now be served at the value you've set in `TOOLJET_HOST`. + +#### Deploying ToolJet Database + +ToolJet AMI comes inbuilt with PostgREST. If you intend to use this feature, you'd only have to setup the environment variables in `~/app/.env` file and run `./setup_app` script. + +You can learn more about this feature [here](/docs/tooljet-db/tooljet-database). + +## Workflows + +ToolJet Workflows allows users to design and execute complex, data-centric automations using a visual, node-based interface. This feature enhances ToolJet's functionality beyond building secure internal tools, enabling developers to automate complex business processes. + +### Enabling Scheduling + +To activate workflows scheduling, set the following environment variables: + +```bash +WORKFLOW_WORKER=true +ENABLE_WORKFLOW_SCHEDULING=true +TOOLJET_WORKFLOWS_TEMPORAL_NAMESPACE=default +TEMPORAL_SERVER_ADDRESS= +``` + +**Note**: Workflows scheduling requires a Temporal server to be deployed. Restarting the server using `./setup_app`. + +### Deploying Temporal with Docker Compose + +Below is a `docker-compose` template to set up Temporal. + +``` +curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/ec2-temporal/docker-compose.yml +``` + +This setup can be deployed on a different EC2 instance. To enable seamless communication, ensure that both the application server and the Temporal server are in the same VPC. + +**Note**: Ensure that port 7233 is configured for gRPC in the security group. + +## Upgrading to the Latest LTS Version + +New LTS versions are released every 3-5 months with an end-of-life of atleast 18 months. To check the latest LTS version, visit the [ToolJet Docker Hub](https://hub.docker.com/r/tooljet/tooljet/tags) page. The LTS tags follow a naming convention with the prefix `LTS-` followed by the version number, for example `tooljet/tooljet:ee-lts-latest`. + +**Note**: If this is a new installation of the application, you may start directly with the latest version. This guide is not required for new installations. + +#### Prerequisites for Upgrading to the Latest LTS Version: + +- It is crucial to perform a **comprehensive backup of your database** before starting the upgrade process to prevent data loss. + +- Users on versions earlier than **v2.23.0-ee2.10.2** must first upgrade to this version before proceeding to the LTS version. + +_If you have any questions feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or send us an email at hello@tooljet.com._ diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/azure-container.md b/docs/versioned_docs/version-3.16.0-LTS/setup/azure-container.md new file mode 100644 index 0000000000..19280cdf53 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/azure-container.md @@ -0,0 +1,121 @@ +--- +id: azure-container +title: Azure container apps +--- + +# Deploying ToolJet on Azure container apps + +:::info +Please note that you need to set up a PostgreSQL database manually to be used by ToolJet. Additionally, you must set up a Redis service through Azure Cache for Redis. We've provided detailed configuration steps in the [Redis Setup](#redis-setup) section. +::: + +## Deploying ToolJet application + +1. Open the [Azure dashboard](https://portal.azure.com) and navigate to Container Apps, then click on **Create container app**. + Deploying ToolJet on Azure container apps + +2. Select the appropriate subscription and provide basic details such as the container name and then click on the **Create new environment** button below "Container Apps environment" to configure the networking setup. + Deploying ToolJet on Azure container apps + +3. Select "Create new environment" in `Container Apps environment` to configure the basic networking setup. +4. Configure the basic settings as shown in the screenshot below. + Deploying ToolJet on Azure container apps +5. Move to the "Networking" tab for the detailed configuration as shown in the screenshot. You can retain the default settings for Workload Profiles and Monitoring configurations. + :::tip + The Container app, the PostgreSQL server, and the Redis server all should be in the same virtual network (VNet). + ::: + Deploying ToolJet on Azure container apps + +6. Click on the **Create** button at the bottom of the page. + +7. In the container tab, uncheck the "Use quickstart image" option to select the image source manually. + Deploying ToolJet on Azure container apps + Make sure to provide the image tag, and then enter `server/entrypoint.sh, npm, run, start:prod` in the "Arguments override" field. + + Add the following ToolJet application variables under the "Environmental variable" section. You can refer to this [**documentation**](/docs/setup/env-vars) for more information on environment variables. + + **Note**: ToolJet requires: + + ``` + TOOLJET_DB + TOOLJET_DB_HOST + TOOLJET_DB_USER + TOOLJET_DB_PASS + PG_HOST + PG_DB + PG_USER + PG_PASS + SECRET_KEY_BASE + LOCKBOX_KEY + ``` + + For redis connection ensure below environment variables are added: + + ``` + REDIS_HOST + REDIS_PORT + REDIS_USER + ``` + + If using Azure Database for Postgresql-Flexible server, add: + + ``` + PGSSLMODE = require + ``` + + Deploying ToolJet on Azure container apps + +8. In the ingress tab, configure Ingress and Authentication settings as shown below. You can customize the security configurations as per your requirements. Make sure the port is set to 3000. + Deploying ToolJet on Azure container apps + +9. Move to Review + create tab and wait for the template to be verified and passed, as shown in the screenshot below. + Deploying ToolJet on Azure container apps + +10. Once the container is deployed, you can verify its status under revision management. + Deploying ToolJet on Azure container apps + + You can access ToolJet via the application URL provided in the overview tab. + +## Redis Setup + +[ToolJet](https://hub.docker.com/repository/docker/tooljet/tooljet/general) requires Redis for multiplayer editing and background jobs. + +If you already have Redis configured, you can use your existing setup. Otherwise, you can create a new Redis service by following these instructions. + +**Create a Redis Instance** + +- Create a Redis instance with the minimum required specifications. + + Step one of redis setup + + **Choose Network Settings** + +- Select your preferred network settings based on your setup. + + Step two of redis setup + +**Configure TLS Port** + +- Choose your preferred settings for the TLS port. + + Step three of redis setup + +**Review and Create** + +- Click on "Review + create" and wait for the template to be verified and passed. + + Step four of redis setup + +## Upgrading to the Latest LTS Version + +New LTS versions are released every 3-5 months with an end-of-life of atleast 18 months. To check the latest LTS version, visit the [ToolJet Docker Hub](https://hub.docker.com/r/tooljet/tooljet/tags) page. The LTS tags follow a naming convention with the prefix `LTS-` followed by the version number, for example `tooljet/tooljet:ee-lts-latest`. + +If this is a new installation of the application, you may start directly with the latest version. This guide is not required for new installations. + +#### Prerequisites for Upgrading to the Latest LTS Version: + +- It is crucial to perform a **comprehensive backup of your database** before starting the upgrade process to prevent data loss. + +- Users on versions earlier than **v2.23.0-ee2.10.2** must first upgrade to this version before proceeding to the LTS version. + +_If you have any questions feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or send us an email at hello@tooljet.com._ diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/choose-your-tooljet.md b/docs/versioned_docs/version-3.16.0-LTS/setup/choose-your-tooljet.md new file mode 100644 index 0000000000..4516a6d03e --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/choose-your-tooljet.md @@ -0,0 +1,61 @@ +--- +id: choose-your-tooljet +title: Deployment Version +--- + +ToolJet versions are categorized into three main types: **Long-Term Support (LTS)**, **Pre-Release**, and **Past versions**. Understanding these categories helps users choose the most suitable version for their needs. + +## Long-Term Support (LTS) Versions + +We highly recommend using LTS versions for most users. These versions are prioritized for bug fixes, updates, and overall stability, ensuring a reliable experience. LTS versions are ideal for production environments where stability and consistent performance are crucial. + +Please find the latest LTS version here:
+[Docker Hub - LTS Versions](https://hub.docker.com/r/tooljet/tooljet/tags?page_size=&ordering=&name=ee-lts) + +:::info +Starting from **`v3.5.0-ee-lts`** all releases are AI releases. Checkout the **[Build with AI](/docs/build-with-ai/overview)** section for more information. If you have any questions feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or send us an email at hello@tooljet.com. +::: + +| Version | Release Date | Docker Pull Command | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | -------------------------------------------- | +| Latest EE-LTS | N/A | `docker pull tooljet/tooljet:ee-lts-latest` | +| [v3.5.0-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.5.0-ee-lts/images/sha256-9580d2377d17ce0c26fca0535eca51bce899015f26bfc81769d032b4b15a5da5) | February 12, 2025 | `docker pull tooljet/tooljet:v3.5.0-ee-lts` | +| [v3.0.24-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.24-ee-lts/images/sha256-33494c8ee72c440ce0ded925cdeb15507cd87f2b7c3fe172dd1cbee790e3b96f?context=explore) | January 3, 2025 | `docker pull tooljet/tooljet:v3.0.24-ee-lts` | +| [v3.0.23-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.23-ee-lts/images/sha256-1ca2bcb5dac66b1d3d089bd8300b7077c0dcd27bb2cfe6665bf388b680294467?context=explore) | January 2, 2025 | `docker pull tooljet/tooljet:v3.0.23-ee-lts` | +| [v3.0.22-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.22-ee-lts/images/sha256-fc2bca053802e06a09858b65c2a5f47f1cb0ece2d156ca9b0dd1c37c60d5d2b8?context=explore) | December 30, 2024 | `docker pull tooljet/tooljet:v3.0.22-ee-lts` | +| [v3.0.21-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.21-ee-lts/images/sha256-88de45e3e32df48c7451a9f6ae505f985ca7a32d2b59c3a4ba9f9da992e8cafe?context=explore) | December 20, 2024 | `docker pull tooljet/tooljet:v3.0.21-ee-lts` | +| [v3.0.20-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.20-ee-lts/images/sha256-898f75a8c6a879014b890a47fa8fd6d2be41ea7f77d549bc2616e0db84788fd2?context=explore) | December 20, 2024 | `docker pull tooljet/tooljet:v3.0.20-ee-lts` | +| [v3.0.19-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.19-ee-lts/images/sha256-eb873525f3fe3a5838fcf72d38d1b9d4ffcb661f59e9af4c466f0041de882a0e?context=explore) | December 17, 2024 | `docker pull tooljet/tooljet:v3.0.19-ee-lts` | +| [v3.0.18-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.18-ee-lts/images/sha256-89e309a8a3a40c967e3bddfbb82adff9332d6b72322cf5ad40f575c03bf7dab1?context=explore) | December 12, 2024 | `docker pull tooljet/tooljet:v3.0.18-ee-lts` | +| [v3.0.17-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.17-ee-lts/images/sha256-0777d52d83a93b3729f8a9b1e6e63a66e9e7bef913adad5eda655a9a009540e0?context=explore) | December 9, 2024 | `docker pull tooljet/tooljet:v3.0.17-ee-lts` | +| [v3.0.16-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.16-ee-lts/images/sha256-9602149f5538af46288f6a33c9c239c336444781ee308c8866d3dca3a747660f?context=explore) | December 9, 2024 | `docker pull tooljet/tooljet:v3.0.16-ee-lts` | +| [v3.0.15-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.15-ee-lts/images/sha256-1fc16533d34695715debb1f3394b18a18431342c1b0d82ff168c5e936cff5d2e?context=explore) | December 5, 2024 | `docker pull tooljet/tooljet:v3.0.15-ee-lts` | +| [v3.0.14-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.14-ee-lts/images/sha256-aa12b3de3d09e4c1122050ee2dd0550152d7d7777d4f75953f4e9d55d652aa2f?context=explore) | December 3, 2024 | `docker pull tooljet/tooljet:v3.0.14-ee-lts` | +| [v3.0.13-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.13-ee-lts/images/sha256-1e469017cb03245eb1ad457219ac60a293d0f9e1b365d0dabf77cf4272cabe58?context=explore) | December 2, 2024 | `docker pull tooljet/tooljet:v3.0.13-ee-lts` | +| [v3.0.12-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.12-ee-lts/images/sha256-7c0aec97e1d630c827d42b21fb9aee853730ea72026f4c89630b6f2f6ce4bca5?context=explore) | November 29, 2024 | `docker pull tooljet/tooljet:v3.0.12-ee-lts` | +| [v3.0.11-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.11-ee-lts/images/sha256-2c102a11d7f497804586368e2e1f350ee386551c7ab5063b298aa68c9c5853dd?context=explore) | November 29, 2024 | `docker pull tooljet/tooljet:v3.0.11-ee-lts` | +| [v3.0.10-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.10-ee-lts/images/sha256-4839e8f18427b47859287c76058a0964d029eeaf8f4c4825c7d77fdb371eb857?context=explore) | November 28, 2024 | `docker pull tooljet/tooljet:v3.0.10-ee-lts` | +| [v3.0.9-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.9-ee-lts/images/sha256-bec9665a3ef51acbf8e93c5ebc47227dc4fd6cb8084d4ad811a808a46edb743d?context=explore) | November 27, 2024 | `docker pull tooljet/tooljet:v3.0.9-ee-lts` | +| [v3.0.8-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.8-ee-lts/images/sha256-8b4658e7d5c8f795b55d4187cc6acddabb9463e33bb62624d0ce3710c887ef0c?context=explore) | November 27, 2024 | `docker pull tooljet/tooljet:v3.0.8-ee-lts` | +| [v3.0.7-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.7-ee-lts/images/sha256-4e5e2b52279a127a001c1c7e93893794799fe8cdb40b15203220d030d4c415ce?context=explore) | November 26, 2024 | `docker pull tooljet/tooljet:v3.0.7-ee-lts` | +| [v3.0.6-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.6-ee-lts/images/sha256-52632c7d70f6334c84d7e3945bf118a4a627eb0081f29420eb3af7788e53f989?context=explore) | November 26, 2024 | `docker pull tooljet/tooljet:v3.0.6-ee-lts` | +| [v3.0.5-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.5-ee-lts/images/sha256-daa03ea3ef9a6a94032476fae0f57f6828869863690346fa325a5937746fe5f6?context=explore) | November 25, 2024 | `docker pull tooljet/tooljet:v3.0.5-ee-lts` | +| [v3.0.4-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.4-ee-lts/images/sha256-7dc2041bdb98674f1058381fbbc93d167ba1a66238e642c6f0cb599987a87ec1?context=explore) | November 20, 2024 | `docker pull tooljet/tooljet:v3.0.4-ee-lts` | +| [v3.0.3-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.3-ee-lts/images/sha256-ba3596677cfb885a91197c1187191afb6eabd7dd8f7f6fdb20514ce716182f8f?context=explore) | November 18, 2024 | `docker pull tooljet/tooljet:v3.0.3-ee-lts` | +| [v3.0.2-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.2-ee-lts/images/sha256-6cb558e5e3337c7fc1b9ffc830ce7096f19253ff5f2fad177afdb46fb0b0ea9d?context=explore) | November 13, 2024 | `docker pull tooljet/tooljet:v3.0.2-ee-lts` | +| [v3.0.1-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.1-ee-lts/images/sha256-b4f2e0779f76db07606ddd8a688cb7e06824837be3f507026ff91bb235efcc1d?context=explore) | November 12, 2024 | `docker pull tooljet/tooljet:v3.0.1-ee-lts` | +| [v3.0.0-ee-lts](https://hub.docker.com/layers/tooljet/tooljet/v3.0.0-ee-lts/images/sha256-989f1370c502e97555dd7e669f896ef6ba2ad1d4f317c53335105bf937b5b189?context=explore) | November 12, 2024 | `docker pull tooljet/tooljet:v3.0.0-ee-lts` | + +:::info +Users are encouraged to upgrade to the latest LTS version to ensure they benefit from the latest improvements and maintain a secure and efficient environment. +::: + +## Pre-Release Versions + +Pre-Release versions are designed for those looking to explore the latest features and advancements in ToolJet. These versions are experimental and may include new functionalities not yet available in LTS versions. However, due to their experimental nature, they may also contain bugs and lack the stability of LTS versions. Therefore, we advise against using Pre-Release versions in production environments. + +_All versions starting from **3.1.x.x** are considered Pre-Release versions._ + +## Past versions (Not maintained anymore) + +Past versions of ToolJet are those that are no longer actively maintained or supported. These versions may still be available but are not recommended, especially in production environments, as they do not receive updates, bug fixes, or security patches. diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/cloud-v3-migration.md b/docs/versioned_docs/version-3.16.0-LTS/setup/cloud-v3-migration.md new file mode 100644 index 0000000000..ec7fc7a68a --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/cloud-v3-migration.md @@ -0,0 +1,260 @@ +--- +id: cloud-v3-migration +title: ToolJet 3.0 Cloud Migration Guide +--- + +# ToolJet 3.0 Cloud Migration Guide + +ToolJet Cloud will be upgraded to 3.0 on November 11th, 2024. This update includes breaking changes that may affect your applications. Please review and update your applications before November 11th to ensure they continue working after the upgrade. + +:::warning Important + +You must make these changes before November 11th to prevent disruption to your applications. The upgrade will happen automatically and cannot be postponed. + +::: + +## Dynamic Input Restrictions + +You can no longer dynamically change references to component names. + +### Action Required + +- Review your applications for any dynamic component name references and refactor as necessary +- Replace all dynamic component references with static references +- Test all component interactions after making these changes + +### Examples and Details + +The following patterns are no longer supported: + +1. Using variables to construct component names: + + ```javascript + // This will no longer work + { + { + components[variables.componentNameVariable].value; + } + } + ``` + +2. Dynamically referencing components: + + ```javascript + // This is not supported + { + { + components["textinput" + components.tabs1.currentTab].value; + } + } + ``` + +3. Dynamically accessing nested properties: + ```javascript + // This dynamic property access is not allowed + { + { + components.table1[components.textinput1.value]; + } + } + ``` + +Instead, use static references to components: + +```javascript +{ + { + components.textinput1.value; + } +} +{ + { + components.table1.selectedRow; + } +} +{ + { + queries.query1.data; + } +} +``` + +## Component and Query Naming + +:::note +This is only an issue during the upgrade process. Once your application is running on ToolJet 3.0, you can use identical names for components and queries without any problems. +::: + +### Action Required + +- Review your applications for any instances where queries and components share the same name +- Temporarily rename either the component or the query to ensure unique names +- Document all renamed components/queries for potential post-upgrade reversion +- Test affected components and queries after renaming + +### Details and Examples + +When upgrading, if a component is referencing a query with the same name, the upgrade process may break that mapping. This occurs because ToolJet previously used a global ID-to-name map for both components and queries, which is now split in 3.0. + +Example scenario: If a table component named `userData` is referencing a query also named `userData`, this reference may break during the upgrade process. + +## Property Panel Logic + +### Action Required + +- Review all property panel variable checks +- Update any existing variable existence checks to use the new recommended format +- Remove any instances of unsupported logic patterns +- Test all components using variable checks after updates + +### New Variable Access Rules + +There are changes to how you can access and check for the existence of variables in the property panel: + +- For components, queries, and page variables, a minimum of two keys must be available after the `component/query/page` keyword +- For variables, a minimum of one key should be present after the `variables` keyword + +```javascript +// Supported formats +components.textinput1.value; +components?.textinput1?.value; +components["textinput1"].value; +queries.restapi1.data; +page.variables.name; +variables["name"]; +variables.name; + +// No longer supported +{ + { + "name" in variables; + } +} +{ + { + Object.keys(variables).includes("name"); + } +} +{ + { + variables.hasOwnProperty("name"); + } +} + +// Recommended approach for checking existence +{ + { + variables["name"] ?? false; + } +} +``` + +:::caution +These changes may affect how your application interacts with variables and components. Be sure to test thoroughly after making these updates. +::: + +## Multi-Page Component Names + +### Action Required + +- Review multi-page applications for components with identical names +- Either rename components to ensure uniqueness across pages +- Or modify queries to use query parameters instead of direct references +- Document all component name changes +- Test affected pages and their interactions after making changes + +### Current Limitations and Details + +When the same component name exists on multiple pages and is linked to queries, the query will only work correctly on the page where the component was originally associated with it. + +Example scenario: + +1. You have `page1` and `page2`, each containing a component named `textinput1` +2. You create a query in `page1` that is linked to `textinput1` +3. The query will only function properly on `page1` +4. When you switch to `page2`, the query will not work as expected, even though there's a component with the same name + +:::tip +When building multi-page applications, it's recommended to use unique component names across all pages to avoid any potential issues with query bindings. +::: + +Future resolution: We will be adding functionality to enforce unique component names across all pages in upcoming releases. + +## Removal of Deprecated Features + +### Kanban Board + +The old deprecated **Kanban Board** component will cease functioning entirely. Applications using this component will crash after the upgrade if not updated. + +
+ToolJet - Widget Reference - Kanban widget +
+ +#### Required Actions + +1. Immediately identify all instances of the old **Kanban Board** component in your applications +2. Create new boards using the new **Kanban** component. +3. Transfer your data and configuration to the new component +4. Remove the old Kanban Board components +5. Update any queries or workflows that were connected to the old boards +6. Test thoroughly to ensure all functionality is preserved + +:::caution +After November 11th, applications with the old Kanban Board component will crash and become unusable. +::: + +### Local Data Sources + +#### Action Required + +- Identify all local data sources in your applications +- Migrate them to global workspace data sources +- Update all queries and components using these data sources +- Test all affected components and queries after migration + +#### Action Required After Upgrade + +If you haven't migrated your local data sources to global data sources, you will encounter an error message indicating that local data sources are no longer supported. For detailed instructions on migrating from Local Data Sources to the new Data Sources, please refer to our [Local Data Sources Migration Guide](/docs/data-sources/local-data-sources-migration). + +### Workspace Variables + +#### Action Required + +- Identify all uses of Workspace Variables +- Replace them with Workspace Constants +- Update all components and queries using these variables +- Configure appropriate role-based access for the new constants +- Test all affected functionality after migration + +Workspace Constants are designed to be resolved on the server-side only, ensuring a high level of security. You can assign users to a specific role and provide create, update, and delete access to Workspace Constants. + +For detailed instructions on migrating from Workspace Variables to Workspace Constants, please refer to our [Workspace Variables Migration Guide](/docs/security/constants/variables). + +## Response Headers and Metadata + +#### Action Required + +- Identify all instances where response headers are being accessed +- Update the code to use the new metadata format +- Test all affected queries and components after migration + +We've introduced a capability to expose additional information through metadata for all datasources. Previously, this was only available for REST API and GraphQL data sources. + +Before, you could access response headers like this: + +```javascript +{{queries..responseHeaders}} +``` + +Now, you should use: + +```javascript +{{queries..metadata}} +``` + +The `metadata` object will contain detailed information about the request and response, including request URL, method, headers, parameters, response status code, and headers. You can read more about metadata [here](/docs/data-sources/restapi/metadata-and-cookies/#metadata). + +## Help and Support + +- Feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or you can also e-mail us at hello@tooljet.com. +- If you have found a bug, please create a [GitHub issue](https://github.com/ToolJet/ToolJet/issues) for the same. diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/digitalocean.md b/docs/versioned_docs/version-3.16.0-LTS/setup/digitalocean.md new file mode 100644 index 0000000000..b984ef770d --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/digitalocean.md @@ -0,0 +1,85 @@ +--- +id: digitalocean +title: DigitalOcean +--- + +Follow the steps below to deploy ToolJet on a DigitalOcean Droplet. + +**1. Navigate to the Droplets section in DigitalOcean.** + +
+ + create a Droplet + +
+ +**2. Configure the **Droplet** with the following options:** + +- **Image**: Ubuntu +- **Plan**: Choose a plan (e.g., Basic, 4GB RAM, 2 vCPU) + +
+ use a droplet plan +
+ + - **Auth**: For authentication, use password or ssh + - Click **Create Droplet** and note the assigned public IP + +**3. Create a Firewall for the **Droplets** to allow required ports.** + +| protocol | port | allowed_cidr | +| :------- | :--- | :----------- | +| tcp | 22 | your IP | +| tcp | 80 | 0.0.0.0/0 | +| tcp | 443 | 0.0.0.0/0 | + +**4. Connect to the **Droplets** via SSH.** + +**5. Install Docker and Docker Compose using the following commands:** + +```bash +apt update && apt upgrade -y +apt install -y docker.io +``` + +Enable and start Docker: + +```bash +systemctl enable docker +systemctl start docker +``` + +Install Docker Compose: + +```bash +apt install -y curl +curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose +chmod +x /usr/local/bin/docker-compose +``` + +Verify installation: + +```bash +docker --version +docker-compose --version +``` + +**6. Update the `TOOLJET_HOST` in the `.env` file:** + +`TOOLJET_HOST=http://:80` + +**7. Use the [Docker Documentation](https://docs.tooljet.ai/docs/setup/docker) to deploy ToolJet.** + +## Upgrading to the Latest LTS Version + +New LTS versions are released every 3-5 months with an end-of-life of atleast 18 months. To check the latest LTS version, visit the [ToolJet Docker Hub](https://hub.docker.com/r/tooljet/tooljet/tags) page. The LTS tags follow a naming convention with the prefix `LTS-` followed by the version number, for example `tooljet/tooljet:ee-lts-latest`. + +If this is a new installation of the application, you may start directly with the latest version. This guide is not required for new installations. + +#### Prerequisites for Upgrading to the Latest LTS Version: + +- It is crucial to perform a **comprehensive backup of your database** before starting the upgrade process to prevent data loss. + +- Users on versions earlier than **v2.23.0-ee2.10.2** must first upgrade to this version before proceeding to the LTS version. + +If you have any questions feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or send us an email at hello@tooljet.com. diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/docker.md b/docs/versioned_docs/version-3.16.0-LTS/setup/docker.md new file mode 100644 index 0000000000..2d3e4b777b --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/docker.md @@ -0,0 +1,168 @@ +--- +id: docker +title: Docker +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Deploying ToolJet using Docker Compose + +Follow the steps below to deploy ToolJet on a server using Docker Compose. ToolJet requires a PostgreSQL database to store applications definitions, (encrypted) credentials for datasources and user authentication data. + +:::info +If you rather want to try out ToolJet on your local machine with Docker, you can follow the steps [here](/docs/setup/try-tooljet/). +::: + +### Installing Docker and Docker Compose + +Install docker and docker-compose on the server. + +- Docs for [Docker Installation](https://docs.docker.com/engine/install/) +- Docs for [Docker Compose Installation](https://docs.docker.com/compose/install/) + +### Deployment options + +There are two options to deploy ToolJet using Docker Compose: + +1. **With in-built PostgreSQL database (recommended)**. This setup uses the official Docker image of PostgreSQL. +2. **With external PostgreSQL database**. This setup is recommended if you want to use a managed PostgreSQL service such as AWS RDS or Google Cloud SQL. + +Confused about which setup to select? Feel free to ask the community via [Slack](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA). + + + + +1. Download our production docker-compose file into the server. + +```bash +curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/docker/docker-compose-db.yaml +mv docker-compose-db.yaml docker-compose.yaml +mkdir postgres_data +``` + +2. Create `.env` file in the current directory (where the docker-compose.yaml file is downloaded as in step 1): + +```bash +curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/docker/.env.internal.example +curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/docker/internal.sh && chmod +x internal.sh +mv .env.internal.example .env && ./internal.sh +``` + +`internal.sh` helps to generate the basic .env variables such as the LOCKBOX_MASTER_KEY, SECRET_KEY_BASE, and the password for postgreSQL database. + +3. To start the docker container, use the following command: + +```bash +docker-compose up -d +``` + +4. **(Optional)** `TOOLJET_HOST` environment variable can either be the public ipv4 address of your server or a custom domain that you want to use. Which can be modified in the .env file. + +Also, for setting up additional environment variables in the .env file, please check our documentation on [environment variable](/docs/setup/env-vars) + +Examples: +`TOOLJET_HOST=http://12.34.56.78` or +`TOOLJET_HOST=https://tooljet.yourdomain.com` + +If you've set a custom domain for `TOOLJET_HOST`, add a `A record` entry in your DNS settings to point to the IP address of the server. + +:::info +i. Please make sure that `TOOLJET_HOST` starts with either `http://` or `https://` + +ii. Setup docker to run without root privileges by following the instructions written here https://docs.docker.com/engine/install/linux-postinstall/ + +iii. If you're running on a linux server, `docker` might need sudo permissions. In that case you can either run: +`sudo docker-compose up -d` +::: + +### Docker Backup (Only For In-Built PostgreSQL) + +The below bash script will help with taking back-up and as well as restoring: + +1. Download the script: + +```bash +curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/docker/backup-restore.sh && chmod +x backup-restore.sh +``` + +2. Run the script with the following command: + +```bash +./backup-restore.sh +``` + +
+ Docker - Backup and Restore +
+ + + + +1. Setup a PostgreSQL database and make sure that the database is accessible. + +2. Download our production docker-compose file into the server. + +```bash +curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/docker/docker-compose.yaml +``` + +3. Create `.env` file in the current directory (where the docker-compose.yaml file is downloaded as in step 1): + +Kindly set the postgresql database credentials according to your external database. Please enter the database details with the help of the bash as shown below. + +
+ + + +
+ +```bash +curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/docker/external.sh +curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/docker/.env.external.example && chmod +x external.sh +mv .env.external.example .env && ./external.sh +``` + +4. To start the docker container, use the following command: + +```bash +docker-compose up -d +``` + +5. **(Optional)** `TOOLJET_HOST` environment variable can either be the public ipv4 address of your server or a custom domain that you want to use. Which can be modified in the .env file. + +Also, for setting up additional environment variables in the .env file, please check our documentation on [environment variable](/docs/setup/env-vars) + +Examples: +`TOOLJET_HOST=http://12.34.56.78` or +`TOOLJET_HOST=https://tooljet.yourdomain.com` + +If you've set a custom domain for `TOOLJET_HOST`, add a `A record` entry in your DNS settings to point to the IP address of the server. + +:::info +i. Please make sure that `TOOLJET_HOST` starts with either `http://` or `https://` + +ii. If there are self signed HTTPS endpoints that ToolJet needs to connect to, please make sure that `NODE_EXTRA_CA_CERTS` environment variable is set to the absolute path containing the certificates. + +iii. If you're running a linux server, `docker` might need sudo permissions. In that case you can either run: +`sudo docker-compose up -d` + +iv. Setup docker to run without root privileges by following the instructions written here https://docs.docker.com/engine/install/linux-postinstall/ +::: + + + + +## Upgrading to the Latest LTS Version + +New LTS versions are released every 3-5 months with an end-of-life of atleast 18 months. To check the latest LTS version, visit the [ToolJet Docker Hub](https://hub.docker.com/r/tooljet/tooljet/tags) page. The LTS tags follow a naming convention with the prefix `LTS-` followed by the version number, for example `tooljet/tooljet:ee-lts-latest`. + +If this is a new installation of the application, you may start directly with the latest version. This guide is not required for new installations. + +#### Prerequisites for Upgrading to the Latest LTS Version: + +- It is crucial to perform a **comprehensive backup of your database** before starting the upgrade process to prevent data loss. + +- Users on versions earlier than **v2.23.0-ee2.10.2** must first upgrade to this version before proceeding to the LTS version. + +_If you have any questions feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or send us an email at hello@tooljet.com._ diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/ecs.md b/docs/versioned_docs/version-3.16.0-LTS/setup/ecs.md new file mode 100644 index 0000000000..5f0b156c60 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/ecs.md @@ -0,0 +1,241 @@ +--- +id: ecs +title: AWS ECS +--- + +# Deploying ToolJet on Amazon ECS + +:::info +You should setup a PostgreSQL database manually to be used by ToolJet. +::: + +You can effortlessly deploy Amazon Elastic Container Service (ECS) by utilizing a [CloudFormation template](https://aws.amazon.com/cloudformation/): + +To deploy all the services at once, simply employ the following template: + +``` +curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/cloudformation/Cloudfomation-template-one-click.yml +``` + +If you already have existing services and wish to integrate ToolJet seamlessly into your current Virtual Private Cloud (VPC) or other setups, you can opt for the following template: + +``` +curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/cloudformation/Cloudformation-deploy.yml +``` + +
+ +## Redis + +:::info +ToolJet requires configuring Redis which is used for enabling multiplayer editing and for background jobs. +::: + +To deploy Redis on an ECS cluster, please follow the steps outlined below. + +Please note that if you already have an existing Redis setup, you can continue using it. However, if you need to create a new Redis service, you can follow the steps provided below. + +- Create a new take definition + ECS Setup + +- Please add container and image tag as shown below:
+ **Make sure that you are using redis version 6.x.x** + ECS Setup + +- Ensure that when creating a service, Redis is integrated into the same cluster where your ToolJet app will be deployed.
+ **Note: Please enable public IP** + ECS Setup + +
+ +
+ +## ToolJet + +Follow the steps below to deploy ToolJet on a ECS cluster. + +1. Setup a PostgreSQL database, ToolJet uses a postgres database as the persistent storage for storing data related to users and apps. +2. Create a target group and an application load balancer to route traffic onto ToolJet containers. You can [reference](https://docs.aws.amazon.com/AmazonECS/latest/userguide/create-application-load-balancer.html) AWS docs to set it up. Please note that ToolJet server exposes `/api/health`, which you can configure for health checks. +3. Create task definition for deploying ToolJet app as a service on your preconfigured cluster. + + 1. Select Fargate as launch type compatibility + 2. Configure IAM roles and set operating system family as Linux. + 3. Select task size to have 3GB of memory and 1vCpu + ECS Setup + 4. Add container details that is shown:
+ Specify your container name ex: `ToolJet`
+ Set the image you intend to deploy. ex: `tooljet/tooljet:ee-latest`
+ Update port mappings at container port `3000` for tcp protocol. + ECS Setup + + Specify environmental values for the container. You'd want to make use of secrets to store sensitive information or credentials, kindly refer the AWS [docs](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data-secrets.html) to set it up. You can also store the env in S3 bucket, kindly refer the AWS [docs](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/taskdef-envfiles.html) . + ECS Setup + + :::info + For the setup, ToolJet requires: +
    + - **TOOLJET_DB** + - **TOOLJET_DB_HOST** + - **TOOLJET_DB_USER** + - **TOOLJET_DB_PASS** + - **PG_HOST** + - **PG_DB** + - **PG_USER** + - **PG_PASS** + - **SECRET_KEY_BASE** + - **LOCKBOX_MASTER_KEY** +
+
+ Read **[environment variables reference](/docs/setup/env-vars)** + ::: + + Additionally, include the Redis environment variables within the ToolJet container mentioned above if you have followed the previous steps to create Redis. + + ``` + REDIS_HOST= + REDIS_PORT=6379 + REDIS_USER=default + REDIS_PASSWORD= + ``` + + 5. Make sure `Use log collection checked` and `Docker configuration` with the command `npm run start:prod` + ECS Setup + +4. Create a service to run your task definition within your cluster. + +- Select the cluster which you have created +- Select launch type as Fargate + ECS Setup +- Select the cluster and set the service name +- You can set the number of tasks to start with as two +- Rest of the values can be kept as default + ECS Setup +- Click on next step to configure networking options +- Select your designated VPC, Subnets and Security groups. Kindly ensure that the security group allows for inbound traffic to http port 3000 for the task. + ECS Setup +- Since migrations are run as a part of container boot, please specify health check grace period for 900 seconds. Select the application loadbalancer option and set the target group name to the one we had created earlier. This will auto populate the health check endpoints. + +:::info +The setup above is just a template. Feel free to update the task definition and configure parameters for resources and environment variables according to your needs. +::: + +
+ +
+ +## ToolJet Database + +To use ToolJet Database, you'd have to set up and deploy PostgREST server which helps querying ToolJet Database. You can learn more about this feature [here](/docs/tooljet-db/tooljet-database). + +Deploying ToolJet Database is mandatory from ToolJet 3.0 or else the migration might break, checkout the following docs to know more about new major version, including breaking changes that require you to adjust your applications accordingly: + +- [ToolJet 3.0 Migration Guide for Self-Hosted Versions](./upgrade-to-v3.md) +- [Cloud](./cloud-v3-migration.md) + +Follow the steps below to deploy PostgREST on a ECS cluster. + +1. Create a new take definition + +
+ + ECS Setup + +
+ + Add the container details and image tag as shown below: + +
+ + ECS Setup + +
+ + Under environmental variable please add corresponding PostgREST env variables. You can also refer [env variable](/docs/setup/env-vars#postgrest). + +
+ + ECS Setup + +
+ +2. Create service and make sure the postgrest is within the same cluster as ToolJet app. + +
+ + ECS Setup + +
+ +3. Specify a service name and leave the remaining settings at their default configurations. + +
+ + ECS Setup + +
+ +4. Ensure that the PostgREST service resides within the same Virtual Private Cloud (VPC), and confirm that port 3001 is included in the security group used by the ToolJet app. **Note: Please enable public IP** + +
+ + ECS Setup + +
+ +Update ToolJet deployment with the appropriate env variables [here](/docs/setup/env-vars#tooljet-database) and apply the changes. + +
+ +## Workflows + +ToolJet Workflows allows users to design and execute complex, data-centric automations using a visual, node-based interface. This feature enhances ToolJet's functionality beyond building secure internal tools, enabling developers to automate complex business processes. + +### Enabling Workflow Scheduling + +Deploy the following containers under the same ToolJet app task definition family to enable workflow scheduling: + +**Worker Container:** +Use the `tooljet/tooljet:ee-latest`` image tag, and ensure it inherits environment variables from the ToolJet app container. + +To activate workflow scheduling, set these environment variables: + +```bash +WORKFLOW_WORKER=true +ENABLE_WORKFLOW_SCHEDULING=true +TOOLJET_WORKFLOWS_TEMPORAL_NAMESPACE=default +TEMPORAL_SERVER_ADDRESS= +``` + +Under the containers tab inside the Docker configuration, please make sure the command `npm, run, worker:prod` is added. + +
+ worker container +
+ +#### Temporal server container: + +1. Use the image tag `temporalio/auto-setup:1.25.1`. Also ensure that in the App protocol, GRPC is selected. + +
+ Temporal server container +
+ +2. Add the below env variables to the temporal container: + +
+ Temporal server container ENV's +
+ +## Upgrading to the Latest LTS Version + +New LTS versions are released every 3-5 months with an end-of-life of atleast 18 months. To check the latest LTS version, visit the [ToolJet Docker Hub](https://hub.docker.com/r/tooljet/tooljet/tags) page. The LTS tags follow a naming convention with the prefix `LTS-` followed by the version number, for example `tooljet/tooljet:ee-lts-latest`. + +If this is a new installation of the application, you may start directly with the latest version. This guide is not required for new installations. + +#### Prerequisites for Upgrading to the Latest LTS Version: + +- It is crucial to perform a **comprehensive backup of your database** before starting the upgrade process to prevent data loss. + +- Users on versions earlier than **v2.23.0-ee2.10.2** must first upgrade to this version before proceeding to the LTS version. + +_If you have any questions feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or send us an email at hello@tooljet.com._ diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/env-vars.md b/docs/versioned_docs/version-3.16.0-LTS/setup/env-vars.md new file mode 100644 index 0000000000..2c97673bb6 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/env-vars.md @@ -0,0 +1,368 @@ +--- +id: env-vars +title: Environment variables +--- + +# Environment variables + +Both the ToolJet server and client requires some environment variables to start running. + +_If you have any questions feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or send us an email at hello@tooljet.com._ + +## ToolJet server + +### ToolJet host ( required ) + +| variable | description | +| ------------ | ---------------------------------------------------------------- | +| TOOLJET_HOST | the public URL of ToolJet client ( eg: https://app.tooljet.com ) | + +### Lockbox configuration ( required ) + +ToolJet server uses lockbox to encrypt datasource credentials. You should set the environment variable `LOCKBOX_MASTER_KEY` with a 32 byte hexadecimal string. + +### Application Secret ( required ) + +ToolJet server uses a secure 64 byte hexadecimal string to encrypt session cookies. You should set the environment variable `SECRET_KEY_BASE`. + +:::tip +If you have `openssl` installed, you can run the following commands to generate the value for `LOCKBOX_MASTER_KEY` and `SECRET_KEY_BASE`. + +For `LOCKBOX_MASTER_KEY` use `openssl rand -hex 32` +For `SECRET_KEY_BASE` use `openssl rand -hex 64` +::: + +### Database configuration ( required ) + +ToolJet server uses PostgreSQL as the database. + +| variable | description | +| -------- | ---------------------- | +| PG_HOST | postgres database host | +| PG_DB | name of the database | +| PG_USER | username | +| PG_PASS | password | +| PG_PORT | port | + +:::tip +If you are using docker-compose setup, you can set PG_HOST as `postgres` which will be DNS resolved by docker +::: + +:::info +If you intent you use the DB connection url and if the connection does not support ssl. Please use the below format using the variable DATABASE_URL. +`postgres://username:password@hostname:port/database_name?sslmode=disable` +::: + +### Disable database and extension creation (optional) + +ToolJet by default tries to create database based on `PG_DB` variable set and additionally my try to create postgres extensions. This requires the postgres user to have CREATEDB permission. If this cannot be granted you can disable this behaviour by setting `PG_DB_OWNER` as `false` and will have to manually run them. + +### Check for updates ( optional ) + +Self-hosted version of ToolJet pings our server to fetch the latest product updates every 24 hours. You can disable this by setting the value of `CHECK_FOR_UPDATES` environment variable to `0`. This feature is enabled by default. + +### Comment feature enable ( optional ) + +Use this environment variable to enable/disable the feature that allows you to add comments on the canvas. To configure this environment variable, ensure that multiplayer editing is enabled in the Settings. + +| variable | value | +| ---------------------- | ----------------- | +| COMMENT_FEATURE_ENABLE | `true` or `false` | + +### Marketplace + +#### Enable Marketplace plugin developement mode ( optional ) + +Use this environment variable to enable/disable the developement mode that allows developers to build the plugin. + +| variable | value | +| --------------------------- | ----------------- | +| ENABLE_MARKETPLACE_DEV_MODE | `true` or `false` | + +### User Session Expiry Time (Optional) + +| variable | description | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| USER_SESSION_EXPIRY | This variable controls the user session expiry time. By default, the session expires after **10** days. The variable expects the value in minutes. ex: USER_SESSION_EXPIRY = 120 which is 2 hours | + +### Enable ToolJet Database (required) + +| variable | description | +| ------------------- | -------------------------------------------- | +| TOOLJET_DB | Default value is `tooljet_db` | +| TOOLJET_DB_HOST | database host | +| TOOLJET_DB_USER | database username | +| TOOLJET_DB_PASS | database password | +| TOOLJET_DB_PORT | database port | +| PGRST_JWT_SECRET | JWT token client provided for authentication | +| PGRST_HOST | postgrest database host | +| PGRST_DB_PRE_CONFIG | postgrest.pre_config | + +:::tip +The database name provided for `TOOLJET_DB` will be utilized to create a new database during server boot process in all of our production deploy setups. +Incase you want to trigger it manually, use the command `npm run db:create` on ToolJet server. +::: + +### Why ToolJet Requires Two Databases + +ToolJet requires two separate databases for optimal functionality. **TOOLJET_DB** is used to store the platform's internal metadata, including tables created within ToolJet. On the other hand, **PG_DB** acts as the primary database for application data, handling end-user data managed by the apps built on ToolJet. + +:::info +If you intent you use the DB connection url and if the connection does not support ssl. Please use the below format using the variable TOOLJET_DB_URL. +`postgres://username:password@hostname:port/database_name?sslmode=disable` +::: + +### Server Host ( optional ) + +You can specify a different server for backend if it is hosted on another server. + +| variable | value | +| ----------- | ------------------------------------------------------------------------------------------------- | +| SERVER_HOST | Configure a hostname for the server as a proxy pass. If no value is set, it defaults to `server`. | + +### Hide account setup link + +If you want to hide account setup link from admin in manage user page, set the environment variable `HIDE_ACCOUNT_SETUP_LINK` to `true`, please make sure you have configured SMTP to receive welcome mail for users. + +### Disabling signups ( optional ) + +If you want to restrict the signups and allow new users only by invitations, set the environment variable `DISABLE_SIGNUPS` to `true`. + +:::tip +You will still be able to see the signup page but won't be able to successfully submit the form. +::: + +### Serve client as a server end-point ( optional ) + +By default, the `SERVE_CLIENT` variable will be unset and the server will serve the client at its `/` end-point. +You can set `SERVE_CLIENT` to `false` to disable this behaviour. + +### Serve client at subpath + +If ToolJet is hosted on a domain subpath, you can set the environment variable `SUB_PATH` to support it. +Please note the subpath is to be set with trailing `/` and is applicable only when the server is serving the frontend client. + +### SMTP Configuration (Optional) + +ToolJet uses SMTP services to send emails (e.g., invitation emails when you add new users to your workspace). + +For Enterprise Edition, you must configure SMTP settings through the user interface (UI) in the ToolJet Settings. For more information, see [SMTP Configuration](/docs/org-setup/smtp-config). + +:::info +If you have upgraded from a version prior to v2.62.0, the SMTP variables in your .env file will automatically be mapped to the UI. +For versions v2.62.0 and later, SMTP configuration will no longer be picked up from the .env file for Enterprise Edition. You must configure SMTP through the UI. You can safely remove these variables from your .env file after ensuring that the configuration is properly set up in the UI. +::: + +For Community Edition, you can configure SMTP via environment variables using the following: + +| Variable | Description | +| ------------------ | ------------------------------------- | +| DEFAULT_FROM_EMAIL | From email for emails sent by ToolJet | +| SMTP_USERNAME | Username | +| SMTP_PASSWORD | Password | +| SMTP_DOMAIN | Domain or host | +| SMTP_PORT | Port | + +### Slack configuration ( optional ) + +If your ToolJet installation requires Slack as a data source, you need to create a Slack app and set the following environment variables: + +| variable | description | +| ------------------- | ------------------------------ | +| SLACK_CLIENT_ID | client id of the slack app | +| SLACK_CLIENT_SECRET | client secret of the slack app | + +### Google OAuth ( optional ) + +If your ToolJet installation needs access to data sources such as Google sheets, you need to create OAuth credentials from Google Cloud Console. + +| variable | description | +| -------------------- | ------------- | +| GOOGLE_CLIENT_ID | client id | +| GOOGLE_CLIENT_SECRET | client secret | + +### Google maps configuration ( optional ) + +If your ToolJet installation requires `Maps` widget, you need to create an API key for Google Maps API. + +| variable | description | +| ------------------- | ------------------- | +| GOOGLE_MAPS_API_KEY | Google maps API key | + +### APM VENDOR ( optional ) + +Specify application monitoring vendor. Currently supported values - `sentry`. + +| variable | description | +| ---------- | ----------------------------------------- | +| APM_VENDOR | Application performance monitoring vendor | + +### SENTRY DNS ( optional ) + +| variable | description | +| ---------- | ------------------------------------------------------------------------------------------------- | +| SENTRY_DNS | DSN tells a Sentry SDK where to send events so the events are associated with the correct project | + +### SENTRY DEBUG ( optional ) + +Prints logs for sentry. + +| variable | description | +| ------------ | ------------------------------------------- | +| SENTRY_DEBUG | `true` or `false`. Default value is `false` | + +### Server URL ( optional) + +This is used to set up for CSP headers and put trace info to be used with APM vendors. + +| variable | description | +| ------------------ | -------------------------------------------------------------- | +| TOOLJET_SERVER_URL | the URL of ToolJet server ( eg: `https://server.tooljet.com` ) | + +### RELEASE VERSION ( optional) + +Once set any APM provider that supports segregation with releases will track it. + +### NODE_EXTRA_CA_CERTS (optional) + +ToolJet needs to be configured for custom CA certificate to be able to trust and establish connection over https. This requires you to configure an additional env var `NODE_EXTRA_CA_CERTS` to have absolute path to your CA certificates. This file named `cert.pem` needs to be in PEM format and can have more than one certificates. + +| variable | description | +| ------------------- | ------------------------------------------------------------------ | +| NODE_EXTRA_CA_CERTS | absolute path to certificate PEM file ( eg: /ToolJet/ca/cert.pem ) | + +### Disable telemetry ( optional ) + +Pings our server to update the total user count every 24 hours. You can disable this by setting the value of `DISABLE_TOOLJET_TELEMETRY` environment variable to `true`. This feature is enabled by default. + +### Password Retry Limit (Optional) + +The maximum retry limit of login password for a user is by default set to 5, account will be locked after 5 unsuccessful login attempts. Use the variables mentioned below to control this behavior: + +| variable | description | +| ---------------------------- | ------------------------------------------------------------------------------------------------------ | +| DISABLE_PASSWORD_RETRY_LIMIT | (true/false) To disable the password retry check, if value is `true` then no limits for password retry | +| PASSWORD_RETRY_LIMIT | To change the default password retry limit (5) | + +### SSO Configurations (Optional) + +Configurations for instance level SSO. + +| variable | description | +| ---------------------------- | -------------------------------------------------------------- | +| SSO_GOOGLE_OAUTH2_CLIENT_ID | Google OAuth client id | +| SSO_GIT_OAUTH2_CLIENT_ID | GitHub OAuth client id | +| SSO_GIT_OAUTH2_CLIENT_SECRET | GitHub OAuth client secret | +| SSO_GIT_OAUTH2_HOST | GitHub OAuth host name if GitHub is self hosted | +| SSO_ACCEPTED_DOMAINS | comma separated email domains that supports SSO authentication | +| SSO_DISABLE_SIGNUPS | Disable user sign up if authenticated user does not exist | + +### Enable Cookie Forwarding to REST API (Optional) + +By default, the ToolJet server does not forward cookies along with the REST API requests. You can enable this functionality by setting the `FORWARD_RESTAPI_COOKIES` environment variable to `true`. This option is available only in the self-hosted version of ToolJet. + +| variable | description | +| ----------------------- | ----------------- | +| FORWARD_RESTAPI_COOKIES | `true` or `false` | + +## ToolJet client + +### Server URL ( optionally required ) + +This is required when client is built separately. + +| variable | description | +| ------------------ | -------------------------------------------------------------- | +| TOOLJET_SERVER_URL | the URL of ToolJet server ( eg: `https://server.tooljet.com` ) | + +### Server Port ( optional) + +This could be used to for local development, it will set the server url like so: `http://localhost:` + +| variable | description | +| ------------------- | --------------------------------------- | +| TOOLJET_SERVER_PORT | the port of ToolJet server ( eg: 3000 ) | + +### Asset path ( optionally required ) + +This is required when the assets for the client are to be loaded from elsewhere (eg: CDN). +This can be an absolute path, or relative to main HTML file. + +| variable | description | +| ---------- | ------------------------------------------------------------- | +| ASSET_PATH | the asset path for the website ( eg: https://app.tooljet.ai/) | + +### Serve client as a server end-point ( optional ) + +By default the client build will be done to be served with ToolJet server. +If you intend to use client separately then can set `SERVE_CLIENT` to `false`. + +## PostgREST server (required) + +| variable | description | +| ---------------- | ----------------------------------------------- | +| PGRST_JWT_SECRET | JWT token client provided for authentication | +| PGRST_DB_URI | database connection string for tooljet database | +| PGRST_LOG_LEVEL | `info` | + +If you intent to make changes in the above configuration. Please refer [PostgREST configuration docs](https://postgrest.org/en/stable/configuration.html#environment-variables). + +:::tip +If you have openssl installed, you can run the +command `openssl rand -hex 32` to generate the value for `PGRST_JWT_SECRET`. + +If this parameter is not specified, PostgREST will refuse authentication requests. +::: + +:::info +Please make sure that DB_URI is given in the format `postgrest://[USERNAME]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]` +::: + +## Log file path ( Optional ) + +If a log file path is specified in environment variables, a log file containing all the data from audit logs will be created at the specified path. The file will be updated every time a new audit log is created. + +| Variable | Description | +| ------------- | -------------------------------------------------------------------------------- | +| LOG_FILE_PATH | the path where the log file will be created ( eg: tooljet/log/tooljet-audit.log) | + +## ToolJet Apps + +### Enabling embedding of private apps + +By default, only embedding of public apps is permitted. By setting this variable, users will be able to embed private ToolJet Apps. + +| Variable | Description | +| ------------------------ | ----------------- | +| ENABLE_PRIVATE_APP_EMBED | `true` or `false` | + +:::caution +The option is only available starting from ToolJet Enterprise Edition `2.8.0` or higher, and `2.10.0` for the Community edition and cloud version. +::: + +## Configuring the Default Language + +To change the default language, set the LANGUAGE variable to your desired language code. + +| Variable | Description | +| -------- | --------------- | +| LANGUAGE | `LANGUAGE_CODE` | + +Available Languages with their codes and native names: + +| Language | Code | Native Name | +| ---------- | ---- | ---------------- | +| English | en | English | +| French | fr | FranΓ§ais | +| Spanish | es | EspaΓ±ol | +| Italian | it | Italiano | +| Indonesian | id | Bahasa Indonesia | +| Ukrainian | uk | Π£ΠΊΡ€Π°Ρ—Π½ΡΡŒΠΊΠ° | +| Russian | ru | Русский | +| German | de | Deutsch | + +For instance, to set the language to French, you can set the LANGUAGE variable to `fr`. + +:::info +The option to set a default language is not available on cloud version of ToolJet. +::: diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/google-cloud-run.md b/docs/versioned_docs/version-3.16.0-LTS/setup/google-cloud-run.md new file mode 100644 index 0000000000..0d810426f0 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/google-cloud-run.md @@ -0,0 +1,161 @@ +--- +id: google-cloud-run +title: Google Cloud Run +--- + +# Deploying ToolJet on Google Cloud Run + +:::info +You should setup a PostgreSQL database manually to be used by ToolJet. +::: + +Follow the steps below to deploy ToolJet on Cloud run with `gcloud` CLI. + +## Deploying ToolJet application + +1. Create a new Google Cloud Run Service: + +
+ Google Cloud Run New Setup +
+ +2. Ingress and Authentication can be set as shown below, to begin with. Feel free to change the security configurations as per you see fit. + +
+ ingress-auth +
+ +3. Under containers tab, please make sure the port is set to 3000 and command `npm, run, start:prod` is entered in container argument field with CPU capacity set to 2GiB: + +
+ port-and-capacity-tooljet +
+ +- If the command mentioned above is not compatible, please use the following command structure instead: + +
+ port-and-capacity-tooljet-alternative-command +
+ +- Should you encounter any migration issues, please execute the following command. Be aware that executing this command may cause the revision to break. However, modifying the command back to `npm, run, start:prod` will successfully reboot the instance: + +
+ port-and-capacity-tooljet-migration-fix-command +
+ +4. Under environmental variable please add the below ToolJet application variables. You can also refer env variable [**here**](/docs/setup/env-vars). + +Update `TOOLJET_HOST` environment variable if you want to use the default url assigned with Cloud run after the initial deploy. + +
+ env-variable-tooljet +
+ +:::tip +If you are using [Public IP](https://cloud.google.com/sql/docs/postgres/connect-run) for Cloud SQL, then database host connection (value for `PG_HOST`) needs to be set using unix socket format, `/cloudsql/`. +::: + +5. Please go to the connection tab. Under Cloud SQL instance please select the PostgreSQL database which you have set-up. + +
+ cloud-SQL-tooljet +
+ +Click on deploy once the above parameters are set. + +:::info +Once the Service is created and live, to make the Cloud Service URL public. Please follow the steps [**here**](https://cloud.google.com/run/docs/securing/managing-access) to make the service public. +::: + +## Deploying ToolJet Database + +To use ToolJet Database, you'd have to set up and deploy PostgREST server which helps querying ToolJet Database. Deploying ToolJet Database is mandatory from ToolJet 3.0 or else the migration might break, checkout the following docs to know more about new major version, including breaking changes that require you to adjust your applications accordingly: + +- [Self Hosted](/docs/setup/upgrade-to-v3) + +1. Cloud Run requires prebuilt image to be present within cloud registry. You can pull specific PostgREST image from docker hub and then tag with your project to push it to cloud registry. + + ```bash + docker pull postgrest/postgrest:v12.0.2 + ``` + + Please run the above command by launching googleCLI which will help to push the PostgREST image to Google container registry. + +2. Ingress and Authentication can be set as shown below, to begin with. Feel free to change the security configurations as per you see fit. + +ingress-auth + +3. Under containers tab, please make sure the port is set 3000 and CPU capacity is set to 1GiB. + +port-and-capacity-postgrest + +4. Under environmental variable please add corresponding ToolJet database env variables. You can also refer [env variable](/docs/setup/env-vars#tooljet-database). + +5. Please go to connection tab. Under Cloud SQL instance please select the PostgreSQL database which you have set-up for ToolJet application or the separate PostgreSQL database created respective to ToolJet Database from the drop-down option. + + Cloud-SQL-instance + + Click on deploy once the above parameters are set. + + :::info + Once the Service is created and live, to make the Cloud Service URL public. Please follow the steps [**here**](https://cloud.google.com/run/docs/securing/managing-access) to make the service public. + ::: + +6. Additional Environmental variable to be added to ToolJet application or ToolJet Server connect to PostgREST server. You can also refer env variable [**here**](/docs/setup/env-vars#tooljet-database) + +env-for-tooljet + +## Workflows + +ToolJet Workflows allows users to design and execute complex, data-centric automations using a visual, node-based interface. This feature enhances ToolJet's functionality beyond building secure internal tools, enabling developers to automate complex business processes. + +### Enabling Workflow Scheduling + +Please deploy the below containers to enable workflows scheduling. + +#### Worker container: + +You can use the same `tooljet/tooljet:ee-latest` image tag and ensure it has env variables from the tooljet-app container. + +To activate workflow scheduling, set the following environment variables: + +```bash +WORKFLOW_WORKER=true +ENABLE_WORKFLOW_SCHEDULING=true +TOOLJET_WORKFLOWS_TEMPORAL_NAMESPACE=default +TEMPORAL_SERVER_ADDRESS= +``` + +Under the containers tab, please make sure the command `npm, run, worker:prod` is set. + +
+ ToolJet Worker Settings +
+ +#### Temporal server container: + +1. Set the image tag as `temporalio/auto-setup:1.25.1` + +
+ Temporal Settings +
+ +2. Add the below env variables to the temporal container: + +
+ Temporal Variables and Secrets +
+ +## Upgrading to the Latest LTS Version + +New LTS versions are released every 3-5 months with an end-of-life of atleast 18 months. To check the latest LTS version, visit the [ToolJet Docker Hub](https://hub.docker.com/r/tooljet/tooljet/tags) page. The LTS tags follow a naming convention with the prefix `LTS-` followed by the version number, for example `tooljet/tooljet:ee-lts-latest`. + +If this is a new installation of the application, you may start directly with the latest version. This guide is not required for new installations. + +#### Prerequisites for Upgrading to the Latest LTS Version: + +- It is crucial to perform a **comprehensive backup of your database** before starting the upgrade process to prevent data loss. + +- Users on versions earlier than **v2.23.0-ee2.10.2** must first upgrade to this version before proceeding to the LTS version. + +_If you have any questions feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or send us an email at hello@tooljet.com._ diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/helm.md b/docs/versioned_docs/version-3.16.0-LTS/setup/helm.md new file mode 100644 index 0000000000..885da0943e --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/helm.md @@ -0,0 +1,48 @@ +--- +id: helm +title: Helm +--- + +# Deploying ToolJet with Helm Chart + +This repository contains Helm charts for deploying [ToolJet](https://github.com/ToolJet/helm-charts) on a Kubernetes Cluster using Helm v3. The charts include an integrated PostgreSQL server that is enabled by default. However, you have the option to disable it and configure a different PostgreSQL server by updating the `values.yml` file. + +## Installation + +### From Helm repo + +```bash +helm repo add tooljet https://tooljet.github.io/helm-charts +helm install tooljet tooljet/tooljet +``` + +### From the Source + +1. Clone the repository and navigate to this directory +2. Run `helm dependency update` +3. It is recommended but optional to modify the values in the `values.yaml` file, such as usernames, passwords, persistence settings, etc. +4. Run `helm install -n $NAMESPACE --create-namespace $RELEASE .` + +Remember to replace the variables with your specific configuration values. + +## ToolJet Database + +ToolJet offers a hosted database solution that allows you to build applications quickly and manage your data effortlessly. The ToolJet database requires no setup and provides a user-friendly interface for data management. + +For more information about the ToolJet database, you can visit [here](/docs/tooljet-db/tooljet-database). + +You need to set up and deploy the PostgREST server, which facilitates querying the ToolJet Database. + +## Upgrading to the Latest LTS Version + +New LTS versions are released every 3-5 months with an end-of-life of atleast 18 months. To check the latest LTS version, visit the [ToolJet Docker Hub](https://hub.docker.com/r/tooljet/tooljet/tags) page. The LTS tags follow a naming convention with the prefix `LTS-` followed by the version number, for example `tooljet/tooljet:ee-lts-latest`. + +If this is a new installation of the application, you may start directly with the latest version. This guide is not required for new installations. + +#### Prerequisites for Upgrading to the Latest LTS Version: + +- It is crucial to perform a **comprehensive backup of your database** before starting the upgrade process to prevent data loss. + +- Users on versions earlier than **v2.23.0-ee2.10.2** must first upgrade to this version before proceeding to the LTS version. + +_If you have any questions feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or send us an email at hello@tooljet.com._ diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/http-proxy.md b/docs/versioned_docs/version-3.16.0-LTS/setup/http-proxy.md new file mode 100644 index 0000000000..acc5ce51e4 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/http-proxy.md @@ -0,0 +1,34 @@ +--- +id: http-proxy +title: Connecting via HTTP proxy +--- + +The server will connect to the internet via the configured HTTP proxy when the below environment variable is set. + +| Variable | Description | +| :----------------- | :------------------------------------ | +| TOOLJET_HTTP_PROXY | Used for both HTTP and HTTPS requests | + +_If you have any questions, feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or send us an email at hello@tooljet.com._ + +
+ +## Package Information + +We use the [global-agent](https://www.npmjs.com/package/global-agent) package to manage HTTP proxies. + +This package allows you to configure global HTTP/HTTPS proxies for your Node.js application. It is particularly useful when you need to route all outgoing HTTP and HTTPS requests through a proxy server. This can be beneficial for scenarios such as bypassing network restrictions, logging, or adding an extra layer of security. + +
+ +
+ +## URL Format + +The environment variable format follows the standard host and port notation: + +``` +http://127.0.0.1:8080 +``` + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/index.md b/docs/versioned_docs/version-3.16.0-LTS/setup/index.md new file mode 100644 index 0000000000..8f2c73bd5b --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/index.md @@ -0,0 +1,10 @@ +# Deploy ToolJet + +Check out the different methods you can use to deploy ToolJet on your machine. + +```mdx-code-block +import {DocsCardList} from '../../../src/components/DocsCard'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/kubernetes-aks.md b/docs/versioned_docs/version-3.16.0-LTS/setup/kubernetes-aks.md new file mode 100644 index 0000000000..f6e5c1b951 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/kubernetes-aks.md @@ -0,0 +1,100 @@ +--- +id: kubernetes-aks +title: Kubernetes (AKS) +--- + +# Deploying ToolJet on Kubernetes (AKS) + +:::info +You should setup a PostgreSQL database manually to be used by ToolJet. We recommend using Azure Database for PostgreSQL since this guide is for deploying using AKS. +::: + +Follow the steps below to deploy ToolJet on a AKS Kubernetes cluster. + +1. Create an AKS cluster and connect to it to start with the deployment. You can follow the steps as mentioned on the [Azure's documentation](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal). + +2. Create k8s deployment + + ```bash + curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/kubernetes/AKS/deployment.yaml + ``` + +Make sure to edit the environment variables in the `deployment.yaml`. We advise to use secrets to setup sensitive information. You can check out the available options [here](/docs/setup/env-vars). + +:::info +For the setup, ToolJet requires: +
    +- **TOOLJET_DB** +- **TOOLJET_DB_HOST** +- **TOOLJET_DB_USER** +- **TOOLJET_DB_PASS** +- **PG_HOST** +- **PG_DB** +- **PG_USER** +- **PG_PASS** +- **SECRET_KEY_BASE** +- **LOCKBOX_KEY** +
+
+Read **[environment variables reference](/docs/setup/env-vars)** +::: + +:::info +If there are self signed HTTPS endpoints that Tooljet needs to connect to, please make sure that `NODE_EXTRA_CA_CERTS` environment variable is set to the absolute path containing the certificates. You can make use of kubernetes secrets to mount the certificate file onto the containers. +::: + +3. Create k8s service and reserve a static IP and expose it via a service load balancer as mentioned in the [doc](https://docs.microsoft.com/en-us/azure/aks/static-ip). You can refer `service.yaml`. + + ```bash + curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/kubernetes/AKS/service.yaml + ``` + +4. Apply YAML configs + + ```bash + kubectl apply -f deployment.yaml, service.yaml + ``` + +You will be able to access your ToolJet installation once the pods and services running. + +## ToolJet Database + +To use ToolJet Database, you'd have to set up and deploy PostgREST server which helps querying ToolJet Database. Please [follow the instructions here](/docs/setup/env-vars#tooljet-database). + +1. Setup PostgREST server + + ```bash + kubectl apply -f https://tooljet-deployments.s3.us-west-1.amazonaws.com/kubernetes/AKS/postgrest.yaml + ``` + +2. Update ToolJet deployment with the appropriate env variables [here](https://tooljet-deployments.s3.us-west-1.amazonaws.com/kubernetes/AKS/deployment.yaml) and apply the changes. + +## Workflows + +ToolJet Workflows allows users to design and execute complex, data-centric automations using a visual, node-based interface. This feature enhances ToolJet's functionality beyond building secure internal tools, enabling developers to automate complex business processes. + +Create workflow deployment: + +```bash +kubectl apply -f https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/kubernetes/workflow-deployment.yaml +``` + +**Note:** Ensure that the worker deployment uses the same image as the ToolJet application deployment to maintain compatibility. Additionally, the variables below need to be a part of tooljet-deployment. + +`ENABLE_WORKFLOW_SCHEDULING=true` +`TOOLJET_WORKFLOWS_TEMPORAL_NAMESPACE=default` +`TEMPORAL_SERVER_ADDRESS=` + +## Upgrading to the Latest LTS Version + +New LTS versions are released every 3-5 months with an end-of-life of atleast 18 months. To check the latest LTS version, visit the [ToolJet Docker Hub](https://hub.docker.com/r/tooljet/tooljet/tags) page. The LTS tags follow a naming convention with the prefix `LTS-` followed by the version number, for example `tooljet/tooljet:ee-lts-latest`. + +If this is a new installation of the application, you may start directly with the latest version. This guide is not required for new installations. + +#### Prerequisites for Upgrading to the Latest LTS Version: + +- It is crucial to perform a **comprehensive backup of your database** before starting the upgrade process to prevent data loss. + +- Users on versions earlier than **v2.23.0-ee2.10.2** must first upgrade to this version before proceeding to the LTS version. + +_If you have any questions feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or send us an email at hello@tooljet.com._ diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/kubernetes-eks.md b/docs/versioned_docs/version-3.16.0-LTS/setup/kubernetes-eks.md new file mode 100644 index 0000000000..8559d984dc --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/kubernetes-eks.md @@ -0,0 +1,88 @@ +--- +id: kubernetes-eks +title: Kubernetes (EKS) +--- + +Follow the steps below to deploy ToolJet on an EKS Kubernetes cluster. + +:::info +You should set up a PostgreSQL database manually to be used by ToolJet. We recommend using an RDS PostgreSQL database. You can find the system requirements [here](/docs/setup/system-requirements#postgresql) +::: + +1. Create an EKS cluster and connect to it to start with the deployment. You can follow the steps as mentioned in the [AWS documentation](https://docs.aws.amazon.com/eks/latest/userguide/create-cluster.html). + +2. Create a k8s Deployment: + +_The file below is just a template and might not suit production environments. You should download the file and configure parameters such as the replica count and environment variables according to your needs._ + +``` +kubectl apply -f https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/kubernetes/deployment.yaml +``` + +Make sure to edit the environment variables in the `deployment.yaml`. We advise using secrets to set up sensitive information. You can check out the available options [here](/docs/setup/env-vars). + +:::info +For the setup, ToolJet requires: +
    +- **TOOLJET_DB** +- **TOOLJET_DB_HOST** +- **TOOLJET_DB_USER** +- **TOOLJET_DB_PASS** +- **PG_HOST** +- **PG_DB** +- **PG_USER** +- **PG_PASS** +- **SECRET_KEY_BASE** +- **LOCKBOX_KEY** +
+
+Read **[environment variables reference](/docs/setup/env-vars)** +::: + +3. Create a Kubernetes service to publish the Kubernetes deployment that you have created. We have a [template](https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/kubernetes/service.yaml) for exposing the ToolJet server as a service using an AWS Load Balancer. + +**Example:** + +- [Application load balancing on Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/alb-ingress.html) + +## ToolJet Database + +To use ToolJet Database, you'd have to set up and deploy a PostgREST server, which helps in querying the ToolJet Database. Please [follow the instructions here](/docs/setup/env-vars#tooljet-database). + +1. Set up PostgREST server + +``` +kubectl apply -f https://raw.githubusercontent.com/ToolJet/ToolJet/main/deploy/kubernetes/postgrest.yaml +``` + +Update ToolJet deployment with the appropriate env variables [here](https://tooljet-deployments.s3.us-west-1.amazonaws.com/kubernetes/deployment.yaml) and apply the changes. + +## Workflows + +ToolJet Workflows allows users to design and execute complex, data-centric automations using a visual, node-based interface. This feature enhances ToolJet's functionality beyond building secure internal tools, enabling developers to automate complex business processes. + +Create workflow deployment: + +```bash +kubectl apply -f https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/kubernetes/workflow-deployment.yaml +``` + +**Note:** Ensure that the worker deployment uses the same image as the ToolJet application deployment to maintain compatibility. Additionally, the variables below need to be a part of tooljet-deployment. + +`ENABLE_WORKFLOW_SCHEDULING=true` +`TOOLJET_WORKFLOWS_TEMPORAL_NAMESPACE=default` +`TEMPORAL_SERVER_ADDRESS=` + +## Upgrading to the Latest LTS Version + +New LTS versions are released every 3-5 months with an end-of-life of at least 18 months. To check the latest LTS version, visit the [ToolJet Docker Hub](https://hub.docker.com/r/tooljet/tooljet/tags) page. The LTS tags follow a naming convention with the prefix `LTS-` followed by the version number, for example `tooljet/tooljet:ee-lts-latest`. + +If this is a new installation of the application, you may start directly with the latest version. This guide is not required for new installations. + +#### Prerequisites for Upgrading to the Latest LTS Version: + +- It is crucial to perform a **comprehensive backup of your database** before starting the upgrade process to prevent data loss. + +- Users on versions earlier than **v2.23.0-ee2.10.2** must first upgrade to this version before proceeding to the LTS version. + +_If you have any questions feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or send us an email at hello@tooljet.com._ diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/kubernetes-gke.md b/docs/versioned_docs/version-3.16.0-LTS/setup/kubernetes-gke.md new file mode 100644 index 0000000000..ed239bb376 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/kubernetes-gke.md @@ -0,0 +1,123 @@ +--- +id: kubernetes-gke +title: Kubernetes (GKE) +--- + +# Deploying ToolJet on Kubernetes (GKE) + +:::info +You should setup a PostgreSQL database manually to be used by ToolJet. We recommend using Cloud SQL since this guide is for deploying using GKE. +::: + +Follow the steps below to deploy ToolJet on a GKE Kubernetes cluster. + +1. Create an SSL certificate. + +```bash +curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/kubernetes/GKE/certificate.yaml +``` + +Change the domain name to the domain/subdomain that you wish to use for ToolJet installation. + +2. Reserve a static IP address using `gcloud` cli + +```bash +gcloud compute addresses create tj-static-ip --global +``` + +3. Create k8s deployment + +```bash +curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/kubernetes/GKE/deployment.yaml +``` + +Make sure to edit the environment variables in the `deployment.yaml`. You can check out the available options [here](/docs/setup/env-vars). + +:::info +For the setup, ToolJet requires: +
    +- **TOOLJET_DB** +- **TOOLJET_DB_HOST** +- **TOOLJET_DB_USER** +- **TOOLJET_DB_PASS** +- **PG_HOST** +- **PG_DB** +- **PG_USER** +- **PG_PASS** +- **SECRET_KEY_BASE** +- **LOCKBOX_KEY** +
+Read **[environment variables reference](/docs/setup/env-vars)** +::: + +:::info +If there are self signed HTTPS endpoints that Tooljet needs to connect to, please make sure that `NODE_EXTRA_CA_CERTS` environment variable is set to the absolute path containing the certificates. You can make use of kubernetes secrets to mount the certificate file onto the containers. +::: + +4. Create k8s service + +```bash +curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/kubernetes/GKE/service.yaml +``` + +5. Create k8s ingress + +```bash +curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/kubernetes/GKE/ingress.yaml +``` + +Change the domain name to the domain/subdomain that you wish to use for ToolJet installation. + +6. Apply YAML configs + +```bash +kubectl apply -f certificate.yaml, deployment.yaml, service.yaml, ingress.yaml +``` + +:::info +It might take a few minutes to provision the managed certificates. [Managed certificates documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/managed-certs). +::: + +You will be able to access your ToolJet installation once the pods, service and the ingress is running. + +## ToolJet Database + +To use ToolJet Database, you'd have to set up and deploy PostgREST server which helps querying ToolJet Database. Please [follow the instructions here](/docs/setup/env-vars#tooljet-database). + +1. Setup PostgREST server + + ```bash + kubectl apply -f https://tooljet-deployments.s3.us-west-1.amazonaws.com/kubernetes/GKE/postgrest.yaml + ``` + +2. Update ToolJet deployment with the appropriate env variables [here](https://tooljet-deployments.s3.us-west-1.amazonaws.com/kubernetes/GKE/deployment.yaml) and apply the changes. + +## Workflows + +ToolJet Workflows allows users to design and execute complex, data-centric automations using a visual, node-based interface. This feature enhances ToolJet's functionality beyond building secure internal tools, enabling developers to automate complex business processes. + +Create workflow deployment: + +```bash +kubectl apply -f https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/kubernetes/workflow-deployment.yaml +``` + +**Note:** Ensure that the worker deployment uses the same image as the ToolJet application deployment to maintain compatibility. Additionally, the variables below need to be a part of tooljet-deployment. + +`ENABLE_WORKFLOW_SCHEDULING=true` +`TOOLJET_WORKFLOWS_TEMPORAL_NAMESPACE=default` +`TEMPORAL_SERVER_ADDRESS=` + +## Upgrading to the Latest LTS Version + +New LTS versions are released every 3-5 months with an end-of-life of atleast 18 months. To check the latest LTS version, visit the [ToolJet Docker Hub](https://hub.docker.com/r/tooljet/tooljet/tags) page. The LTS tags follow a naming convention with the prefix `LTS-` followed by the version number, for example `tooljet/tooljet:ee-lts-latest`. + +If this is a new installation of the application, you may start directly with the latest version. This guide is not required for new installations. + +#### Prerequisites for Upgrading to the Latest LTS Version: + +- It is crucial to perform a **comprehensive backup of your database** before starting the upgrade process to prevent data loss. + +- Users on versions earlier than **v2.23.0-ee2.10.2** must first upgrade to this version before proceeding to the LTS version. + +_If you have any questions feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or send us an email at hello@tooljet.com._ diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/kubernetes.md b/docs/versioned_docs/version-3.16.0-LTS/setup/kubernetes.md new file mode 100644 index 0000000000..544a904113 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/kubernetes.md @@ -0,0 +1,91 @@ +--- +id: kubernetes +title: Kubernetes +--- + +# Deploying ToolJet on Kubernetes + +:::info +You should setup a PostgreSQL database manually to be used by ToolJet. +::: + +Follow the steps below to deploy ToolJet on a Kubernetes cluster. + +1. **Setup a PostgreSQL database**
+ ToolJet uses a postgres database as the persistent storage for storing data related to users and apps. We do not have plans to support other databases such as MySQL. +2. **Create a Kubernetes secret with name `server`.**
+ For the setup, ToolJet requires: + + - **TOOLJET_DB** + - **TOOLJET_DB_HOST** + - **TOOLJET_DB_USER** + - **TOOLJET_DB_PASS** + - **PG_HOST** + - **PG_DB** + - **PG_USER** + - **PG_PASS** + - **SECRET_KEY_BASE** + - **LOCKBOX_KEY** + + Read **[environment variables reference](/docs/setup/env-vars)** + +3. Create a Kubernetes deployment + + ```bash + kubectl apply -f https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/kubernetes/deployment.yaml + ``` + +:::info +The file given above is just a template and might not suit production environments. You should download the file and configure parameters such as the replica count and environment variables according to your needs. +::: + +:::info +If there are self signed HTTPS endpoints that ToolJet needs to connect to, please make sure that `NODE_EXTRA_CA_CERTS` environment variable is set to the absolute path containing the certificates. You can make use of kubernetes secrets to mount the certificate file onto the containers. +::: + +4. Verify if ToolJet is running + + ```bash + kubectl get pods + ``` + +5. Create a Kubernetes services to publish the Kubernetes deployment that you've created. This step varies with cloud providers. We have a [template](https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/kubernetes/service.yaml) for exposing the ToolJet server as a service using an AWS loadbalancer. + + **Examples:** + + - [Application load balancing on Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/alb-ingress.html) + - [GKE Ingress for HTTP(S) Load Balancing](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress) + +:::tip +If you want to serve ToolJet client from services such as Firebase or Netlify, please read the client Setup documentation **[here](/docs/setup/client)**. +::: + +## Workflows + +ToolJet Workflows allows users to design and execute complex, data-centric automations using a visual, node-based interface. This feature enhances ToolJet's functionality beyond building secure internal tools, enabling developers to automate complex business processes. + +Create workflow deployment: + +```bash +kubectl apply -f https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/kubernetes/workflow-deployment.yaml +``` + +**Note:** Ensure that the worker deployment uses the same image as the ToolJet application deployment to maintain compatibility. Additionally, the variables below need to be a part of tooljet-deployment. + +`ENABLE_WORKFLOW_SCHEDULING=true` +`TOOLJET_WORKFLOWS_TEMPORAL_NAMESPACE=default` +`TEMPORAL_SERVER_ADDRESS=` + +## Upgrading to the Latest LTS Version + +New LTS versions are released every 3-5 months with an end-of-life of atleast 18 months. To check the latest LTS version, visit the [ToolJet Docker Hub](https://hub.docker.com/r/tooljet/tooljet/tags) page. The LTS tags follow a naming convention with the prefix `LTS-` followed by the version number, for example `tooljet/tooljet:ee-lts-latest`. + +If this is a new installation of the application, you may start directly with the latest version. This guide is not required for new installations. + +#### Prerequisites for Upgrading to the Latest LTS Version: + +- It is crucial to perform a **comprehensive backup of your database** before starting the upgrade process to prevent data loss. + +- Users on versions earlier than **v2.23.0-ee2.10.2** must first upgrade to this version before proceeding to the LTS version. + +_If you have any questions feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or send us an email at hello@tooljet.com._ diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/openshift.md b/docs/versioned_docs/version-3.16.0-LTS/setup/openshift.md new file mode 100644 index 0000000000..7d197e350a --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/openshift.md @@ -0,0 +1,97 @@ +--- +id: openshift +title: Openshift +--- + +# Deploying ToolJet on Openshift + +:::info +You should setup a PostgreSQL database manually to be used by ToolJet. +::: + +Follow the steps below to deploy ToolJet on Openshift. + +1. Setup a PostgreSQL database ToolJet uses a postgres database as the persistent storage for storing data related to users and apps. We do not have plans to support other databases such as MySQL. + +2. Create a Kubernetes secret with name `server`. For the setup, ToolJet requires: + +- **TOOLJET_DB** +- **TOOLJET_DB_HOST** +- **TOOLJET_DB_USER** +- **TOOLJET_DB_PASS** +- **PG_HOST** +- **PG_DB** +- **PG_USER** +- **PG_PASS** +- **SECRET_KEY_BASE** +- **LOCKBOX_KEY** + +Read **[environment variables reference](/docs/setup/env-vars)** + +3. Once you have logged into the Openshift developer dashboard click on `+Add` tab. Select import YAML from the local machine. + +:::note +When entering one or more files and use --- to separate each definition +::: + +Copy paste deployment.yaml to the online editor + +``` +curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/openshift/deployment.yaml +``` + +Copy paste the service.yaml to the online editor + +``` +curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/openshift/service.yaml +``` + +
+ +online yaml editor + +
+ +Once you have added the files click on create. + +:::info +If there are self signed HTTPS endpoints that Tooljet needs to connect to, please make sure that `NODE_EXTRA_CA_CERTS` environment variable is set to the absolute path containing the certificates. You can make use of kubernetes secrets to mount the certificate file onto the containers. +::: + +4. Navigate to topology tab and use the visual connector to establish the connect between tooljet-deployment and postgresql as shown in the screenshot below. + +
+ +topology + +
+ +## Workflows + +ToolJet Workflows allows users to design and execute complex, data-centric automations using a visual, node-based interface. This feature enhances ToolJet's functionality beyond building secure internal tools, enabling developers to automate complex business processes. + +Create workflow deployment: + +```bash +kubectl apply -f https://tooljet-deployments.s3.us-west-1.amazonaws.com/pre-release/kubernetes/workflow-deployment.yaml +``` + +**Note:** Ensure that the worker deployment uses the same image as the ToolJet application deployment to maintain compatibility. Additionally, the variables below need to be a part of tooljet-deployment. + +`ENABLE_WORKFLOW_SCHEDULING=true` +`TOOLJET_WORKFLOWS_TEMPORAL_NAMESPACE=default` +`TEMPORAL_SERVER_ADDRESS=` + +## Upgrading to the Latest LTS Version + +New LTS versions are released every 3-5 months with an end-of-life of atleast 18 months. To check the latest LTS version, visit the [ToolJet Docker Hub](https://hub.docker.com/r/tooljet/tooljet/tags) page. The LTS tags follow a naming convention with the prefix `LTS-` followed by the version number, for example `tooljet/tooljet:ee-lts-latest`. + +If this is a new installation of the application, you may start directly with the latest version. This guide is not required for new installations. + +#### Prerequisites for Upgrading to the Latest LTS Version: + +- It is crucial to perform a **comprehensive backup of your database** before starting the upgrade process to prevent data loss. + +- Users on versions earlier than **v2.23.0-ee2.10.2** must first upgrade to this version before proceeding to the LTS version. + +_If you have any questions feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or send us an email at hello@tooljet.com._ diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/system-requirements.md b/docs/versioned_docs/version-3.16.0-LTS/setup/system-requirements.md new file mode 100644 index 0000000000..c1ba630189 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/system-requirements.md @@ -0,0 +1,42 @@ +--- +id: system-requirements +title: System Requirements +--- + +This document covers all the system requirements for self-hosting ToolJet. + +:::info +The official Docker tag for the Enterprise Edition is tooljet/tooljet:ee-lts-latest. +::: + +## Operating Systems + +### Supported Linux distribution + +[ToolJet images](https://hub.docker.com/r/tooljet/tooljet/tags) can run on any Linux machine with x86 architecture (64-bit). Ensure that your system meets the minimum requirements specified below before installing ToolJet. + +### Microsoft Windows + +ToolJet is developed for Linux-based operating systems. Please consider using a virtual machine or Windows Subsystem for Linux 2 (WSL2) to run ToolJet on Windows. + +## VM deployments: + +- **Operating System:** Ubuntu 22.04 or later +- **Processor Architecture:** x86 (arm64 is not supported) +- **RAM:** 2GB +- **CPU:** 1 vCPU +- **Storage:** At least 8GiB, but can increase according to your requirements. + +## Orchestrated Deployments: + +- When employing container orchestration frameworks like Kubernetes, it's imperative to ensure that your cluster hosts at least one node equipped with the above specifications for seamlessly executing ToolJet deployments. + +Note: Adjustments can be made based on specific needs and the expected load on the server. + +:::info +To enable multiplayer editing and background jobs in ToolJet, you need to configure Redis. It is recommended to use Redis version 6.x. +::: + +## Database software: + +- It is recommended that your PostgreSQL database is of version 13.x. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/tooljet-subpath.md b/docs/versioned_docs/version-3.16.0-LTS/setup/tooljet-subpath.md new file mode 100644 index 0000000000..7c2ded326f --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/tooljet-subpath.md @@ -0,0 +1,33 @@ +--- +id: tooljet-subpath +title: Deploying ToolJet on a subpath +--- + +ToolJet can now be deployed at a subpath rather than the root (`/`) of a public domain. Example subpath installation URL: **`http://www.yourcompany.com/apps/tooljet`** + +You'll need to setup the following environment variables if ToolJet installation is on a domain subpath: + +| variable | value | +| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| TOOLJET_HOST | the public URL ( eg: https://www.yourcompany.com ) | +| SUB_PATH | Set a subpath to this variable. The subpath is to be set with trailing `/` and is applicable only when the server is serving the frontend client. ( eg: `/apps/tooljet/` ) | + +:::info +See all **[Environment Variables](/docs/setup/env-vars)** here. +::: + +## Upgrading to the Latest Version + +The latest version includes architectural changes and, hence, comes with new migrations. + +If this is a new installation of the application, you may start directly with the latest version. This guide is not required for new installations. + +#### Prerequisites for Upgrading to the Latest Version: + +- It is **crucial to perform a comprehensive backup of your database** before starting the upgrade process to prevent data loss. + +- Ensure that your current version is v2.23.0-ee2.10.2 before upgrading. + +- Users on versions earlier than v2.23.0-ee2.10.2 must first upgrade to this version before proceeding to the latest version. + +_If you have any questions feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or send us an email at hello@tooljet.com._ diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/try-tooljet.md b/docs/versioned_docs/version-3.16.0-LTS/setup/try-tooljet.md new file mode 100644 index 0000000000..37e979037f --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/try-tooljet.md @@ -0,0 +1,51 @@ +--- +id: try-tooljet +title: Try ToolJet +--- + +# Try ToolJet + +## On local with Docker + +You can run the command below to have ToolJet up and running right away. + +```bash +docker run \ + --name tooljet \ + --restart unless-stopped \ + -p 80:80 \ + --platform linux/amd64 \ + -v tooljet_data:/var/lib/postgresql/13/main \ + -v temporal_sqlite:/etc/temporal \ + tooljet/try:ee-latest +``` + +#### Setup information + +- Runs the ToolJet server on the port 80 on your machine. +- Container has postgres already configured within. All the data will be available in the docker volume `tooljet_data`. +- You can make use of `--env` or `--env-file` flag to test against various env configurables mentioned [here](/docs/setup/env-vars). +- Use `docker stop tooljet` to stop the container and `docker start tooljet` to start the container thereafter. + +#### Dynamic Port Setup + +To run the ToolJet server on a different port, such as 8080 or any other port of your choice, use the following command: + +```sh +docker run \ + --name tooljet \ + --restart unless-stopped \ + -p 8080:8080 \ + -e PORT=8080 \ + --platform linux/amd64 \ + -v tooljet_data:/var/lib/postgresql/13/main \ + -v temporal_sqlite:/etc/temporal \ + tooljet/try:ee-latest +``` + +- This command will start the ToolJet server on port 8080. +- The `-e PORT=8080` flag sets the `PORT` environment variable to 8080, allowing the ToolJet server to listen on port 8080. + +By following these instructions, you can easily run the ToolJet server on the port of your choice, ensuring flexibility in your setup. + +_If you have any questions feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or send us an email at hello@tooljet.com._ diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/upgrade-to-lts.md b/docs/versioned_docs/version-3.16.0-LTS/setup/upgrade-to-lts.md new file mode 100644 index 0000000000..c6804f70a9 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/upgrade-to-lts.md @@ -0,0 +1,32 @@ +--- +id: upgrade-to-lts +title: Upgrading ToolJet to the LTS Version +--- + +ToolJet has released its first Long Term Support (LTS) version, which provides extended support and stability for your environments. Upgrading to this LTS version ensures you benefit from the latest features and security updates while maintaining a stable and supported environment. + +### Check the latest LTS Version + +ToolJet will be releasing new LTS versions every 3-5 months with an end-of-life of atleast 18 months. To check the latest LTS version, visit the [ToolJet Docker Hub](https://hub.docker.com/r/tooljet/tooljet/tags) page. The LTS tags follow a naming convention with the prefix `LTS-` followed by the version number, for example `tooljet/tooljet:ee-lts-latest`. + +### Prerequisites + +- It is crucial to perform a **comprehensive backup of your database** before starting the upgrade process to prevent data loss. + +- Users on versions earlier than **v2.23.0-ee2.10.2** must first upgrade to this version before proceeding to the LTS version. + +### Upgrade Process + +The upgrade process depends on your deployment method. You can follow the upgrade process under the respective setup guides: + +- [Upgrade ToolJet on DigitalOcean](/docs/setup/digitalocean#upgrading-to-the-latest-lts-version) +- [Upgrade ToolJet on Docker](/docs/setup/docker#upgrading-to-the-latest-lts-version) +- [Upgrade ToolJet on AWS AMI](/docs/setup/ami#upgrading-to-the-latest-lts-version) +- [Upgrade ToolJet on AWS ECS](/docs/setup/ecs#upgrading-to-the-latest-lts-version) +- [Upgrade ToolJet on OpenShift](/docs/setup/openshift#upgrading-to-the-latest-lts-version) +- [Upgrade ToolJet on Helm](/docs/setup/helm#upgrading-to-the-latest-lts-version) +- [Upgrade ToolJet on Kubernetes](/docs/setup/kubernetes#upgrading-to-the-latest-lts-version) +- [Upgrade ToolJet on Kubernetes(GKE)](/docs/setup/kubernetes-gke#upgrading-to-the-latest-lts-version) +- [Upgrade ToolJet on Kubernetes(AKS)](/docs/setup/kubernetes-aks#upgrading-to-the-latest-lts-version) +- [Upgrade ToolJet on Azure Container Apps](/docs/setup/azure-container#upgrading-to-the-latest-lts-version) +- [Upgrade ToolJet on Google Cloud Run](/docs/setup/google-cloud-run#upgrading-to-the-latest-lts-version) diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/upgrade-to-v3.16.md b/docs/versioned_docs/version-3.16.0-LTS/setup/upgrade-to-v3.16.md new file mode 100644 index 0000000000..7318707a70 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/upgrade-to-v3.16.md @@ -0,0 +1,58 @@ +--- +id: upgrade-to-v3.16 +title: ToolJet 3.16 Migration Guide +--- + +ToolJet 3.16 introduces a set of **new features and platform updates**. All changes are **non-breaking**, but there are a few that may require minor layout adjustments. This guide summarise all key updates. + +:::tip Before upgrading +We recommend reviewing this guide and testing in a staging environment to evaluate UI differences. For self-hosted users, ensure `.env` changes are applied for audit log retention. +::: + +## Suggested Updates (Medium Severity) + +### App Builder Changes + +These are layout or usability improvements that may require tweaks depending on your app setup. + +| Area |Change | +|:-----------|:----------| +| App Header | The **Hide app header** option has been deprecated and is now included under the Page & Navigation features. If you previously had the app header hidden, it will now be displayed. Ensure your layout accounts for this change. | +| Dark Mode & Header | **Toggle App Mode icon** disappears if the page menu is hidden. **Workaround**: Use a Button with the `Toggle App Mode` action. | +| Page Menu (Text and icon) | For page menus using the **Text and icon** style, icons will now stay visible when the menu is collapsed. This was not the case before and may slightly affect your layout. | +| Page Menu (Text only and Icon only) | Page menus using **Text only** or **Icon only** styles can no longer be collapsed. If your layout depended on collapsing these, adjustments may be needed. | +| Branding | The app logo and title now appear side-by-side in the top-left corner of the page menu. The separate top bar that previously held the title and logo has been removed. This change may affect layout balance and branding visibility. | + +### Platform Changes + +Audit logs are the reports of all the activities done in your ToolJet account. Below are the default retention periods that determine how long these logs are stored, depending on your deployment type. + +| Deployment | Notes | +|:--------------|:----------| +| Cloud | No change. Audit logs remain fixed to 90 days. | +| Self-Hosted | Audit logs now default to 90 days. Override via `.env`: `AUDIT_LOG_RETENTION_PERIOD=90` | + +## Minor Component Changes (Low Severity) + +These changes may cause **minor visual shifts** but require no action unless affecting your layout. + +| Component | Change Description | +|:------------------|:----------------------| +| Container | Padding updates applied. This may slightly affect alignment of tightly placed child components like headers or cards. | +| File Picker | Enhanced UI with added file size range selection, list titles, and improved visual feedback. | +| Tab | Tab headers have undergone minor visual polish, including alignment and spacing improvements. | +| List View | Padding on individual records has been slightly adjusted for consistency with other layout components. | +| Form | Internal padding revised to align with updated container spacing logic. | +| Table | A horizontal scrollbar has been added for overflow content. Scrollbar is now also wider for better accessibility. | +| Daterange Picker | Calendar popup design modernised with better visual grouping and clarity of date selection. | +| Steps | Step indicators have updated padding and width, improving alignment and usability in multi-step forms. | +| Image | Fallback UI for broken images has been improvedβ€”display is cleaner and more informative. | +| Dividers | Side padding removed on both horizontal and vertical dividers, making them appear slightly larger or more prominent. | +| Canvas | When the page menu expands, the canvas now shrinks more predictably to avoid layout clipping. | +| Page Menu (Icon) | The pin icon has been replaced with a hamburger menu icon to better reflect toggle behaviour in collapsed mode. | + +## Need Help? + +- Reach out via our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) +- Or email us at [hello@tooljet.com](mailto:hello@tooljet.com) +- Found a bug? Please report it via [GitHub Issues](https://github.com/ToolJet/ToolJet/issues) \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/upgrade-to-v3.md b/docs/versioned_docs/version-3.16.0-LTS/setup/upgrade-to-v3.md new file mode 100644 index 0000000000..baa92cc9bd --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/upgrade-to-v3.md @@ -0,0 +1,284 @@ +--- +id: upgrade-to-v3 +title: ToolJet 3.0 Migration Guide Self-Hosted +--- + +ToolJet 3.0 is a new **major version**, including **breaking changes** that require you to adjust your applications accordingly. We will guide you through this process and mention a few important changes. + +:::tip Before upgrading +Before upgrading, we recommend reviewing your existing applications for any usage of deprecated features. Addressing these ahead of time will help reduce the work needed to upgrade to ToolJet 3.0. + +For complex applications, we also recommend setting up thorough testing procedures to ensure your apps function correctly after the upgrade. +::: + +## Upgrading to ToolJet 3.0 + +### Prerequisites ⚠️ + +Before attempting to upgrade to the ToolJet 3.0: + +- **Database Backup**: Create a complete backup of your database +- **Application Review**: Check your apps for breaking and deprecated features listed in this guide. +- **Test Environment**: Only attempt upgrade in a testing environment first. + +To upgrade, checkout the latest docker image **[here](/docs/setup/choose-your-tooljet)**. + +## Breaking Changes + +The following changes are breaking and require immediate action to ensure your applications continue to function correctly after the upgrade. + +## Dynamic Input Restrictions + +You can no longer dynamically change references to component names. + +### Action Required + +- Review your applications for any dynamic component name references and refactor as necessary +- Replace all dynamic component references with static references +- Test all component interactions after making these changes + +### Examples and Details + +The following patterns are no longer supported: + +1. Using variables to construct component names: + + ```javascript + // This will no longer work + { + { + components[variables.componentNameVariable].value; + } + } + ``` + +2. Dynamically referencing components: + + ```javascript + // This is not supported + { + { + components["textinput" + components.tabs1.currentTab].value; + } + } + ``` + +3. Dynamically accessing nested properties: + ```javascript + // This dynamic property access is not allowed + { + { + components.table1[components.textinput1.value]; + } + } + ``` + +Instead, use static references to components: + +```javascript +{ + { + components.textinput1.value; + } +} +{ + { + components.table1.selectedRow; + } +} +{ + { + queries.query1.data; + } +} +``` + +## Component and Query Naming + +:::note +This is only an issue during the upgrade process. Once your application is running on ToolJet 3.0, you can use identical names for components and queries without any problems. +::: + +### Action Required + +- Review your applications for any instances where queries and components share the same name +- Temporarily rename either the component or the query to ensure unique names +- Document all renamed components/queries for potential post-upgrade reversion +- Test affected components and queries after renaming + +### Details and Examples + +When upgrading, if a component is referencing a query with the same name, the upgrade process may break that mapping. This occurs because ToolJet previously used a global ID-to-name map for both components and queries, which is now split in 3.0. + +Example scenario: If a table component named `userData` is referencing a query also named `userData`, this reference may break during the upgrade process. + +## Property Panel Logic + +### Action Required + +- Review all property panel variable checks +- Update any existing variable existence checks to use the new recommended format +- Remove any instances of unsupported logic patterns +- Test all components using variable checks after updates + +### New Variable Access Rules + +There are changes to how you can access and check for the existence of variables in the property panel: + +- For components, queries, and page variables, a minimum of two keys must be available after the `component/query/page` keyword +- For variables, a minimum of one key should be present after the `variables` keyword + +```javascript +// Supported formats +components.textinput1.value; +components?.textinput1?.value; +components["textinput1"].value; +queries.restapi1.data; +page.variables.name; +variables["name"]; +variables.name; + +// No longer supported +{ + { + "name" in variables; + } +} +{ + { + Object.keys(variables).includes("name"); + } +} +{ + { + variables.hasOwnProperty("name"); + } +} +// Recommended approach for checking existence +{ + { + variables["name"] ?? false; + } +} +``` + +:::caution +These changes may affect how your application interacts with variables and components. Be sure to test thoroughly after making these updates. +::: + +## Multi-Page Component Names + +### Action Required + +- Review multi-page applications for components with identical names +- Either rename components to ensure uniqueness across pages +- Or modify queries to use query parameters instead of direct references +- Document all component name changes +- Test affected pages and their interactions after making changes + +### Current Limitations and Details + +When the same component name exists on multiple pages and is linked to queries, the query will only work correctly on the page where the component was originally associated with it. + +Example scenario: + +1. You have `page1` and `page2`, each containing a component named `textinput1` +2. You create a query in `page1` that is linked to `textinput1` +3. The query will only function properly on `page1` +4. When you switch to `page2`, the query will not work as expected, even though there's a component with the same name + +:::tip +When building multi-page applications, it's recommended to use unique component names across all pages to avoid any potential issues with query bindings. +::: + +Future resolution: We will be adding functionality to enforce unique component names across all pages in upcoming releases. + +## Removal of Deprecated Features + +### Kanban Board + +The old deprecated **Kanban Board** component will cease functioning entirely. Applications using this component will crash after the upgrade if not updated. + +
+ToolJet - Widget Reference - Kanban widget +
+ +#### Required Actions + +1. Immediately identify all instances of the old **Kanban Board** component in your applications +2. Create new boards using the new **Kanban** component. +3. Transfer your data and configuration to the new component +4. Remove the old Kanban Board components +5. Update any queries or workflows that were connected to the old boards +6. Test thoroughly to ensure all functionality is preserved + +:::caution +After the 3.0 upgrade, applications with the old Kanban Board component will crash and become unusable. Make sure to replace all instances of the old component with the new Kanban component before upgrading. +::: + +### Local Data Sources + +#### Action Required + +- Identify all local data sources in your applications +- Migrate them to global workspace data sources +- Update all queries and components using these data sources +- Test all affected components and queries after migration + +#### Action Required After Upgrade + +If you haven't migrated your local data sources to global data sources, you will encounter an error message indicating that local data sources are no longer supported. For detailed instructions on migrating from Local Data Sources to the new Data Sources, please refer to our [Local Data Sources Migration Guide](/docs/data-sources/local-data-sources-migration). + +### Workspace Variables + +#### Action Required + +- Identify all uses of Workspace Variables +- Replace them with Workspace Constants +- Update all components and queries using these variables +- Configure appropriate role-based access for the new constants +- Test all affected functionality after migration + +Workspace Constants are designed to be resolved on the server-side only, ensuring a high level of security. You can assign users to a specific role and provide create, update, and delete access to Workspace Constants. + +For detailed instructions on migrating from Workspace Variables to Workspace Constants, please refer to our [Workspace Variables Migration Guide](/docs/security/constants/variables). + +## Response Headers and Metadata + +#### Action Required + +- Identify all instances where response headers are being accessed +- Update the code to use the new metadata format +- Test all affected queries and components after migration + +We've introduced a capability to expose additional information through metadata for all datasources. Previously, this was only available for REST API and GraphQL data sources. + +Before, you could access response headers like this: + +```javascript +{{queries..responseHeaders}} +``` + +Now, you should use: + +```javascript +{{queries..metadata}} +``` + +The `metadata` object will contain detailed information about the request and response, including request URL, method, headers, parameters, response status code, and headers. You can read more about metadata [here](/docs/data-sources/restapi/metadata-and-cookies/#metadata). + +## System Changes + +### ToolJet Database + +ToolJet Database is now a core requirement for the ToolJet 3.0. +To use ToolJet Database, you'd have to set up and deploy PostgREST server which helps querying ToolJet Database.
+Please check the environment variables that you need to configure to set up: + +- [PostgREST](/docs/setup/env-vars#postgrest) +- [ToolJet Database](/docs/setup/env-vars#tooljet-database) + +## Help and Support + +- Feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or you can also e-mail us at hello@tooljet.com. +- If you have found a bug, please create a [GitHub issue](https://github.com/ToolJet/ToolJet/issues) for the same. diff --git a/docs/versioned_docs/version-3.16.0-LTS/setup/v2-migration.md b/docs/versioned_docs/version-3.16.0-LTS/setup/v2-migration.md new file mode 100644 index 0000000000..4e0b2314b4 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/setup/v2-migration.md @@ -0,0 +1,37 @@ +--- +id: v2-migration-guide +title: V2 migration guide +--- + +# Version 2 migration guide + +ToolJet version 2 comes with a bunch of exciting features, with the major ones being: + +1. Multi page +2. Multi env +3. Forms widget +4. [Database](/docs/tooljet-db/tooljet-database) (Requires opt-in) +5. [Marketplace](/docs/marketplace/marketplace-overview) (Requires opt-in) + +Checkout the latest changelog for v2 [here](https://github.com/ToolJet/ToolJet/releases). + +## Deployment + +Based on your opted deployment method from our [setup doc](/docs/setup/), you can directly deploy v2 without any additional configuration for the default setup. + +Additional configuration are only required for the opt-in features mentioned above. You can check the respective documentation of those features for the configuration changes needed. + +:::info +Server may take some time to be ready to handle the HTTP request as v2 changes requires some data migrations for the initial deployment. This is automatically triggered as a part of the server boot. +:::: + +## Deprecations + +#### Deployments + +- Docker compose deployments with [auto SSL](/docs/1.x.x/setup/docker) is deprecated + +## Help and Support + +- Feel free to join our highly active **[Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA)** or you can also e-mail us at **hello@tooljet.com**. +- If you have found a bug, please create a **[GitHub issue](https://github.com/ToolJet/ToolJet/issues)** for the same. diff --git a/docs/versioned_docs/version-3.16.0-LTS/tj-setup/instances.md b/docs/versioned_docs/version-3.16.0-LTS/tj-setup/instances.md new file mode 100644 index 0000000000..01ad1dd147 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tj-setup/instances.md @@ -0,0 +1,40 @@ +--- +id: instances +title: Instances +--- + +Instances in ToolJet refer to self-hosted deployments of the ToolJet platform. Each instance operates independently and can have its own configurations, data, and user base. You can create multiple [workspaces](/docs/tj-setup/workspaces) inside of an instance. Workspaces are collaborative environments that enable teams to build, customize, and deploy applications, as well as manage data, workflows, and permissions. + +When it comes to roles, ToolJet offers a [Super Admin](/docs/user-management/role-based-access/super-admin) role, who can manage the instances and has full access to all the Workspaces, Users, and Groups of an instance. Within each workspace, users can be assigned one of the predefined roles (Admin, Builder, or End User) or we can add the user to a create custom group with custom permissions . For more details on managing users and roles within workspaces, refer to the [Workspace Users and Groups](/docs/user-management/role-based-access/user-roles) documentation. + + + +Marketplace Plugin: Amazon Redshift + + + + +## Why Use Instances? + +Instances help with: + +- **Data Isolation**: Keeping data separate for teams, departments, or clients. +- **Compliance**: Hosting data to meet your org regulations. +- **Data Privacy**: Ensures that your data remains private. ToolJet does not have access to your data. + +Check out the [setup guide](/docs/setup/) to explore the different options available for deploying ToolJet on your infrastructure. + +## Choosing your Instance Setup + +- **Single Instance:** Ideal for teams looking for quick setup with data compliance, privacy and minimal overhead. +- **Multiple Instances:** Suitable If your organization wants to: + - Manage applications across different departments with isolated setups. + - Host data in multiple regions to meet the compliance requirements. + - Set-up separate environments (e.g., development, staging, production) for stricter SDLC workflows. + +The diagram below illustrates the multi-instance setup. + + +Marketplace Plugin: Amazon Redshift + +If you’d like to discuss your use case or need assistance, reach out via [support](mailto:hello@tooljet.com). \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/tj-setup/licensing/cloud.md b/docs/versioned_docs/version-3.16.0-LTS/tj-setup/licensing/cloud.md new file mode 100644 index 0000000000..01bd3611ef --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tj-setup/licensing/cloud.md @@ -0,0 +1,108 @@ +--- +id: cloud +title: ToolJet Cloud +--- + +This guide explains the different types of subscriptions present and provides instructions on upgrading your subscription for ToolJet Cloud. For assistance in selecting an appropriate plan, visit the **[ToolJet Pricing](https://www.tooljet.ai/pricing)** page or **[contact the ToolJet team](mailto:hello@tooljet.com)**. + +## Types of Subscriptions + +ToolJet provides three types of subscriptions - **Basic**, **Trial**, and **Paid**. These can be further categorized in different plans based on the services and features. Visit **[ToolJet Pricing](https://www.tooljet.ai/pricing)** page for more details on different plans. + +### Basic Subscription + +This is a free subscription where a user can access basic offerings such as creating apps, limited access to the ToolJet Database, community support, etc. This is ideal for individuals or small teams who just need the essentials. + +### Trial Subscription + +ToolJet offers a trial subscription which is valid for 14 days, where users can access all premium features and evaluate ToolJet according to their needs. Once the trial period is over premium features, such as OpenID SSO login and Audit logs, will no longer be accessible. You can upgrade to a paid subscription by simply clicking on the upgrade button. + +### Paid Subscription + +ToolJet offers various plans for paid subscription. Visit the **[ToolJet Pricing](https://www.tooljet.ai/pricing)** page for more details on different plans. Once you have decided a suitable plan for your needs then you can upgrade to a paid subscription by simply clicking on the upgrade button. + +## AI Credit System + +Starting from **`v3.5.0-cloud-lts`** ToolJet supports **Build with AI** allowing you to build applications effortlessly using natural language. Refer to **[Build with AI](/docs/build-with-ai/overview)** guide for more information. + +The AI credits are consumed on every AI operation performed in ToolJet. Credits are allocated at the workspace level, varying based on the pricing plan and replenishing every month. Unused credits do not carry over to the next month, they expire at the end of each billing cycle. AI-powered operations consume credits depending on their complexity. Visit **[ToolJet Pricing](https://www.tooljet.ai/pricing)** page for more details. + +### Credit Usage + +**Standard Operations** + +AI-powered assistance for the following actions consumes **3 credits**: + +- Generating or editing single UI components +- Generating or modifying queries +- Incorporating business logic +- Debugging assistance +- Generating database tables +- Bulk modifying component styles +- Generating or modifying multi-component layouts +- Receiving guidance from documentation + +**Advanced Builds** + +The entire app UI generation consumes **10 credits**. + +### Credit Calculation + +AI credits are calculated based on the pricing plan and are assigned per builder in a workspace. These credits are then available for use by all users in the workspace. + +## Upgrading Your Subscription + +### Start Trial Subscription + +If you are not currently on a paid plan and have not yet used your free trial, you will see a **Start Trial** banner within the ToolJet dashboard. Click on the **Start free trial** button inside this banner to initiate your free trial. + +TJ Dashboard: Start free trial + +### Upgrading to Paid Subscription + +When you've identified the ideal paid plan to meet your needs, the next step is to complete the purchase process, ensuring seamless access to premium features. Follow these steps to upgrade your subscription: + +Role Required: **Admin** + +1. Click the gear icon (βš™οΈ) at the bottom of the left sidebar and select **Settings** from the dropdown. + +2. In the Settings page, choose the **Subscription** tab.
+ (Example URL - `https://app.corp.com/nexus/settings/subscription`) + +3. The subscription tab displays a subscription overview card summarizing your current plan. Locate the **Upgrade** button in the lower left corner and click on it. + +4. A modal window will appear. Enter the desired number of builder and end-user seats, then click the **Upgrade** button within the modal. + +5. You'll be directed to a payment gateway. Complete the payment process. + +6. Upon successful payment, you'll return to the ToolJet subscription tab. A success message will display, and your subscription overview card will update shortly to reflect your new plan. + Dashboard + +If you've decided to move forward with Pro or customized Enterprise plan, please schedule a call with **[ToolJet team](mailto:hello@tooljet.com)** and expect a response from the team within 24-48 hours for onboarding. + +## Updated Limits in New Pricing Plan + +Starting from version `v3.5.34-cloud-lts`, which was released on May 27th, 2025, the new pricing plan will have the following limitations and the old users will be impacted in the following ways: + +| Resource | Allowed Limit | Impact on Existing Users | +| ------------ | :-----------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Builder | 2 | All builders will be automatically archived, except for two random builders (including 1 Admin). | +| End User | 50 | All users beyond 50 will be archived automatically. | +| Applications | 2 | All the previously created apps will be accessible, but the users will not be able to create new apps if they already have two or more than two apps created. | + +### Unarchiving Desired Users Affected Due to New Pricing Plan + +If a user is automatically archived due to the new pricing plan, the Admin can [archive](/docs/user-management/onboard-users/archive-user#instance-level) an active Builder or End User to free up a slot and then [unarchive](/docs/user-management/onboard-users/archive-user#instance-level-1) the desired user. + +If you have any questions, feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or send us an email at [hello@tooljet.com](mailto:hello@tooljet.com). + +## FAQs + +
+ + **What happens if my subscription expires?** + + +If your paid or trial license key expires, your instance will revert to the Basic plan. You will lose access to premium features such as OpenID SSO login and Audit logs, but no data will be lost. You can renew anytime to regain access to premium features. + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/tj-setup/licensing/self-hosted.md b/docs/versioned_docs/version-3.16.0-LTS/tj-setup/licensing/self-hosted.md new file mode 100644 index 0000000000..3dc317330f --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tj-setup/licensing/self-hosted.md @@ -0,0 +1,104 @@ +--- +id: self-hosted +title: Self-Hosted +--- + +This guide explains the different types of licenses present and provides instructions on upgrading your license for Self-Hosted ToolJet. Self-Hosted ToolJet works on a license model and you can reach out to the **[ToolJet Team](mailto:hello@tooljet.com)** to generate the key. For assistance in selecting an appropriate plan visit the **[ToolJet Pricing](https://www.tooljet.ai/pricing)** page or contact the **[ToolJet team](mailto:hello@tooljet.com)**. + +
+ +## Types of Licenses + +ToolJet provides three types of licenses - **Basic**, **Trial**, and **Paid**. These can be further categorized into different subscription plans. Visit **[ToolJet Pricing](https://www.tooljet.ai/pricing)** page for more details on different subscription plans. + +### Basic License + +This is a free license where a user can access basic offerings such as creating apps, pre-defined user groups, community support, etc. This is ideal for individuals or small teams who just need the essentials. No license key is required for this option. + +### Trial License + +ToolJet offers a trial license which is valid for 14 days, where users can access all premium features and evaluate ToolJet according to their needs. You can contact **[ToolJet Team](mailto:hello@tooljet.com)** to generate a trial license key. + +### Paid License + +ToolJet offers various subscription plans for paid licenses. Visit the **[ToolJet Pricing](https://www.tooljet.ai/pricing)** page for more details on different subscription plans. Once you have decided on a suitable plan for your needs you can then contact the **[ToolJet Team](mailto:hello@tooljet.com)** to complete the onboarding process. + +
+ +## AI Credit System + +Starting from **`v3.5.0-ee-lts`** ToolJet supports **Build with AI** allowing you to build applications effortlessly using natural language. Refer to **[Build with AI](/docs/build-with-ai/overview)** guide for more information. + +The AI credits are consumed on every AI operation performed in ToolJet. Credits operate at an instance level and are allocated based on the pricing plan and are replenished monthly. Unused credits do not carry over to the next month, they expire at the end of each billing cycle. AI-powered operations consume credits depending on their complexity. Visit **[ToolJet Pricing](https://www.tooljet.ai/pricing)** page for more details. + +### Credit Usage + +**Standard Operations** + +AI-powered assistance for the following actions consumes **3 credits**: + +- Generating or editing single UI components +- Generating or modifying queries +- Incorporating business logic +- Debugging assistance +- Generating database tables +- Bulk modifying component styles +- Generating or modifying multi-component layouts +- Guidance from documentation + +**Advanced Builds** + +The entire app UI generation consumes **10 credits**. + +### Credit Calculation + +AI credits are calculated based on the pricing plan and are assigned per builder in an instance. These credits are then available for use by all users in the instance across all workspaces. + +## Updating License Key + +Once you have received the license key from the ToolJet Team, you can update the license key by following the steps: + +Role Required: **Super Admin** + +1. Go to the Settings page.
+ (Example URL - `https://app.corp.com/instance-settings/license`) + +2. In the license key tab, update the provided license key. + Licensing + +3. Within the license tab of the Settings page, you can access the limit tab, which provides details about available total users, builders, and end users. You can also see the expiry date of your license key. + Licensing + +## Migrating to New Pricing Plan + +Starting from the version **`v3.5.20-ee-lts`**, the basic license will have the following limitations and users on a previous version, will be impacted in the following ways: + +| Resource | Allowed Limit | Impact on Existing Users | +| ------------ | :-----------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Super Admin | 1 | No Impact | +| Builder | 2 | All builders will be automatically archived, except for two random builders (including 1 Super Admin). | +| End User | 50 | All users beyond 50 will be archived automatically. | +| Applications | 2 | All the previously created apps will be accessible, but the users will not be able to create new apps if they already have two or more than two apps created. | +| Workflows | 2 | Users can create upto two workflows. | +| Workspaces | 1 | All the previously created workspaces will be accessible, but the users will not be able to create any new workspace. | + +### Unarchiving Desired Users Affected Due to New Pricing Plan + +If a user is automatically archived due to the new pricing plan, the Super Admin can [archive](/docs/user-management/onboard-users/archive-user#instance-level) an active Builder or End User to free up a slot and then [unarchive](/docs/user-management/onboard-users/archive-user#instance-level-1) the desired user. + +If you have any questions, feel free to join our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA) or send us an email at [hello@tooljet.com](mailto:hello@tooljet.com). + +## FAQs + +
+ + **What happens if my subscription expires?** + + +If your paid or trial license key expires, your instance will revert to the Basic plan. You will lose access to premium features such as OpenID SSO login and Audit logs, but no data will be lost. You can renew anytime to regain access to premium features. + +
+ +:::caution +**Please keep in mind that your license key is private and strictly prohibited from being shared with any third parties.** +::: diff --git a/docs/versioned_docs/version-3.16.0-LTS/tj-setup/org-branding/custom-domain.md b/docs/versioned_docs/version-3.16.0-LTS/tj-setup/org-branding/custom-domain.md new file mode 100644 index 0000000000..aee2927262 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tj-setup/org-branding/custom-domain.md @@ -0,0 +1,35 @@ +--- +id: custom-domain +title: Custom Domain +--- + +In a self-hosted deployment of ToolJet, you can configure a custom domain by setting the `TOOLJET_HOST `environment variable. + +## Prerequisites + +- A running self-hosted instance of ToolJet. + +- A registered domain name. + +- A configured DNS record pointing your domain to the ToolJet server. + + +## Configuration Steps + +### 1. Set the TOOLJET_HOST Environment Variable + +The TOOLJET_HOST variable defines the public URL where ToolJet will be accessible. You need to update this variable with your desired domain. + +| variable | description | +| ------------ | ---------------------------------------------------------------- | +| TOOLJET_HOST | the public URL of ToolJet client ( eg: `https://app.corp.ai`,`https://corp.ai`,`https://corp.ai/app` ) | + + +### 2. Restart Services + +After setting the environment variable and DNS configurations, restart your ToolJet deployment to apply the changes. + + +:::info +Custom domains will soon be supported in ToolJet Cloud. +::: \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/tj-setup/org-branding/white-labeling.md b/docs/versioned_docs/version-3.16.0-LTS/tj-setup/org-branding/white-labeling.md new file mode 100644 index 0000000000..da2c44e0f4 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tj-setup/org-branding/white-labeling.md @@ -0,0 +1,57 @@ +--- +id: white-labeling +title: White Labeling +--- + +
+ Icon + Paid feature +
+ +The White Label feature in ToolJet lets you customize the look and feel of your ToolJet deployment to match your branding guidelines, including your logo, favicon, and page title, making ToolJet appear like your own product. This guide will help you understand the configuration of White labelling for your organization. For **self-hosted** instances, the white labelling is set at the [instance level](/docs/user-management/authentication/self-hosted/instance-login) and for the **cloud**, it is applied at the [workspace level](/docs/user-management/authentication/self-hosted/workspace-login). + + +whitelable your brand + + + +## Self-hosted Configuration: + +To access the White Labelling configuration, go to **Settings > White Labelling**. ( Example URL - `https://app.corp.com/instance-settings/white-labelling`) + +In this section you can configure the following branding elements: + +- **Application Logo**: This includes the logo displayed on the login screen, dashboard, and app-editor and deployed application. (Preferred dimensions: 130px by 26px). +- **Favicon**: It is an icon associated with the webpage displayed in the browser tab. (Preferred dimensions: 32px x 32px or 16px x 16px.) +- **Page Title**: This is the title associated with the webpage displayed in the browser tab. (Preferred title length: 50-60 characters.) + + +whitelabelling selfhosted + +## Cloud Configuration: + +To access the White Labelling configuration, go to **Settings > White Labelling**. ( Example URL - `https://app.corp.com//settings/white-labelling`) + +In this section you can configure the following branding elements: + +- **Application Logo**: This includes the logo displayed on the login screen, dashboard, and app-editor and deployed application. (Preferred dimensions: 130px by 26px). +- **Favicon**: It is an icon associated with the webpage displayed in the browser tab. (Preferred dimensions: 32px x 32px or 16px x 16px.) +- **Page Title**: This is the title associated with the webpage displayed in the browser tab. (Preferred title length: 50-60 characters.) + +whitelabelling selfhosted + + +## FAQ + +
+ + **What happens to white labeling if the license or subscription expires?** + +If your license or subscription expires, white labeling will automatically revert to ToolJet's default branding until the license is renewed. + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/tj-setup/overview.md b/docs/versioned_docs/version-3.16.0-LTS/tj-setup/overview.md new file mode 100644 index 0000000000..45bb932539 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tj-setup/overview.md @@ -0,0 +1,22 @@ +--- +id: overview +title: Overview +--- + +ToolJet provides a variety of configuration options to help your organization tailor the platform to your specific needs. This section outlines key setup areas for your organization, including branding, subscription plans, deployment options, and workspace management, to ensure an optimized experience for your team. + +## Deployment Options and Subscription Plans + +ToolJet provides two deployment options β€” **Self-Hosted** and **Cloud** β€” enabling users to select the model that best suits their requirements. In addition to deployment options, ToolJet provides a range of subscription plans for each deployment model, offering various features and benefits. Refer to the **[Choose Your ToolJet](/docs/tj-setup/tj-deployment)** guide for further details. + +## Instances and Workspaces + +In ToolJet, a self-hosted deployment of the platform is referred to as an **[instance](/docs/tj-setup/instances)**. Each instance operates independently, maintaining its own configuration, data, and user base. Within each instance, **[workspaces](/docs/tj-setup/workspaces)** provide isolated spaces for different teams or projects, enabling users to manage apps, resources, and access controls effectively. + +## Organization Branding + +ToolJet offers customization through **[white labeling](/docs/tj-setup/org-branding/white-labeling)** and **[custom domain](/docs/tj-setup/org-branding/custom-domain)** setup, allowing you to tailor your instance to align with your brand guidelines. White labeling ensures the platform reflects your organization’s brand identity, while a custom domain allows you to use your own web address for the ToolJet instance. + +## SMTP Server + +Additionally, ToolJet enables you to **[set up your email communication server](/docs/tj-setup/smtp-setup/configuration)** to manage tasks such as sending invitations and password reset requests, facilitating seamless communication within your team and with external stakeholders. diff --git a/docs/versioned_docs/version-3.16.0-LTS/tj-setup/smtp-setup/configuration.md b/docs/versioned_docs/version-3.16.0-LTS/tj-setup/smtp-setup/configuration.md new file mode 100644 index 0000000000..0a32632121 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tj-setup/smtp-setup/configuration.md @@ -0,0 +1,73 @@ +--- +id: configuration +title: Configuration +--- + +This feature is exclusive to self-hosted ToolJet, allowing you to configure a custom SMTP email server. This feature allows you to choose your own email server, which helps to seamlessly send emails for various purposes, including invitations, password reset requests, and notifications. + +There are two ways to setup your email server in ToolJet: +1. **[Using the GUI](#configuration-using-gui)**: This method involves directly entering SMTP settings into the ToolJet interface, which is suitable for simpler setups. +2. **[With environment variables](#configuration-with-environment-variables)**: This method utilizes environment variables for configuring the email server. It offers enhanced flexibility and security, making it particularly suitable for managing sensitive credentials in production environments. + +Both methods are designed to ensure that your ToolJet instance can send emails as needed, depending on your setup preferences and security requirements. + +
+ +## Prerequisites + +Before you begin, ensure you have: +- Super Admin access to ToolJet +- SMTP server details from your email service provider + +
+ +:::info +If you have upgraded from a version prior to v2.62.0, the SMTP variables in your .env file will automatically be mapped to the UI. +::: + +
+ +## Configuration Using GUI + +1. Navigate to the **Settings** section in ToolJet. +2. Select the **Email protocol (SMTP)** tab. +3. Toggle the switch to enable **Email protocol (SMTP)**. +4. Configure the following fields:
+ | Field | Description | Example | + |---------------|--------------------------|-----------------------------------| + | Host | SMTP server hostname | smtp.gmail.com | + | Port | SMTP server port number | 587 | + | User | SMTP account username | hello@johndoe.tech | + | Password | SMTP account password | a13d0sd344 | + | Sender's email| Email address of the sender | hello@johndoe.tech | + +5. Click **Save changes** to apply the new SMTP configuration. + SMTP Configuration Without Environment Variables + +
+ +
+ +## Configuration With Environment Variables + +ToolJet allows you to configure SMTP settings using environment variables. You can enable a toggle in the Email protocol (SMTP) settings to apply or fetch the configuration directly from your .env file. + +SMTP Configuration Without Environment Variables + +**Example Environment Variables**:
+ + ```javascript + DEFAULT_FROM_EMAIL=hello@tooljet.io + SMTP_USERNAME=your-username + SMTP_PASSWORD=your-password + SMTP_DOMAIN=smtp.mailgun.org + SMTP_PORT=587 + SMTP_SSL=false + SMTP_DISABLED=false + ``` + +- For new installations, if SMTP is configured in the .env file, the **Apply configuration from environment variables** toggle will be turned on by default. +- When the toggle is enabled, the SMTP settings fields in the UI will be populated with values from the environment variables and will be read-only. +- Disabling the toggle allows you to manually enter or edit SMTP settings directly in the UI. + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/tj-setup/smtp-setup/email-providers.md b/docs/versioned_docs/version-3.16.0-LTS/tj-setup/smtp-setup/email-providers.md new file mode 100644 index 0000000000..aab218b7e6 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tj-setup/smtp-setup/email-providers.md @@ -0,0 +1,38 @@ +--- +id: email-providers +title: Commonly Used Email Providers +--- + +Here are some general settings for the most commonly used email providers: + +| Provider | Host | Port | Username | Password | Sender's email | +|--------------------|----------------------|------------------|---------------|-----------|----------------| +| Gmail | smtp.gmail.com | 587 or 465 (SSL) | Email | Password | Email | +| Yahoo Mail | smtp.mail.yahoo.com | 465 (SSL) | Email | Password | Email | +| Outlook.com/Hotmail| smtp.office365.com | 587 or 465 (SSL) | Email | Password | Email | +| Zoho Mail | smtp.zoho.com | 587 or 465 (SSL) | Email | Password | Email | +| SendGrid | smtp.sendgrid.net | 587 or 465 (SSL) | apikey | API key | Email | +| Mailgun | smtp.mailgun.org | 587 or 465 (SSL) | SMTP username | Password | Email | + + +## SendGrid + +To configure SendGrid, use **`apikey`** as the username and the generated API key as the password. + +SMTP Configuration Without Environment Variables + +#### Steps to Generate API Key +1. Log in to your [SendGrid](https://sendgrid.com/en-us) account. + +2. Navigate to the [API Keys](https://app.sendgrid.com/settings/api_keys) page under Settings. + +3. Generate a new API key for SMTP usage. + SMTP Configuration Without Environment Variables + +## Mailgun + +Mailgun provides specific credentials for SMTP configuration. +1. Retrieve the **SMTP username** from the SMTP Credentials tab in the Domain Settings page. + +2. Use the password associated with your Mailgun account to authenticate the SMTP connection. + SMTP Configuration Without Environment Variables diff --git a/docs/versioned_docs/version-3.16.0-LTS/tj-setup/tj-deployment.md b/docs/versioned_docs/version-3.16.0-LTS/tj-setup/tj-deployment.md new file mode 100644 index 0000000000..5364c6de00 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tj-setup/tj-deployment.md @@ -0,0 +1,42 @@ +--- +id: tj-deployment +title: Choose Your ToolJet +--- + +ToolJet offers two deployment options β€” **Self-Hosted** and **Cloud** β€” enabling users to select the model that best suits their requirements. Choosing the right deployment method is crucial since it affects data control, scalability, and operational efficiency. This guide explains these options and helps you decide which one best suits your specific requirements. + +
+ +## Self-Hosted ToolJet + +With the self-hosted option, ToolJet can be deployed on your own infrastructure (on-premises or private cloud). This provides more control over data, customization, and integrations, making it an ideal choice for organizations seeking full control over their application development environment to meet compliance, security, and operational requirements. + +#### Why Choose Self-Hosted ToolJet? + +1. **Complete Data Control**: Deploying ToolJet on your infrastructure ensures your data stays within your control, meeting stringent compliance and privacy requirements. +2. **Customizability**: Self-hosted deployments allow for deeper customization to align with your organization's workflows, integrations, and unique needs. +3. **Enhanced Security**: By hosting ToolJet on-premises or in your private cloud, you can implement your own security measures, providing an added layer of protection for sensitive data. + +
+ +
+ +## ToolJet Cloud + +ToolJet Cloud is a managed service hosted by the ToolJet team. It eliminates the need for infrastructure management, providing a quick setup and seamless updates. This option is ideal for teams looking for rapid deployment, seamless scalability, and reduced operational complexity. + +#### Why Choose ToolJet Cloud? + +1. **Hassle-Free Setup**: With ToolJet Cloud, there’s no need to manage servers or infrastructure. Everything is set up and maintained by the ToolJet team, allowing you to focus solely on building applications. +2. **Seamless Updates and Maintenance**: ToolJet Cloud ensures you always have access to the latest features and updates without manual intervention. Maintenance, backups, and uptime are handled for you. +3. **Scalability**: The cloud deployment is designed to scale automatically as your team or application requirements grow, ensuring consistent performance. + +
+ +
+ +## ToolJet Subscription Plans + +ToolJet offers various subscription plans for both deployment models. Refer to the **[ToolJet Pricing](https://www.tooljet.com/pricing)** page for detailed information on features and costs. + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/tj-setup/workspaces.md b/docs/versioned_docs/version-3.16.0-LTS/tj-setup/workspaces.md new file mode 100644 index 0000000000..f599460cbc --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tj-setup/workspaces.md @@ -0,0 +1,125 @@ +--- +id: workspaces +title: Workspaces +--- +# Workspaces + +Workspaces are collaborative environments that enable teams to build, customize, and deploy applications, as well as manage data, workflows, and permissions. It helps you organize your organization's apps based on hierarchy or departments, making them easier to manage. For example, if your organization has departments, you can create separate workspaces for each to isolate apps or limit access to particular set of users or developers. + +Workspace contains applications, data sources, users (admins, developers, or builders, end users), [access and permission ](/docs/user-management/role-based-access/access-control)settings, and more. You can also set different [login configurations](/docs/user-management/authentication/self-hosted/overview) for each workspace. You can have multiple workspaces within an instance. + +## Workspace Creation + +**Role required** - Workspace Admin + +To create a new workspace, + +1. Open the workspace dropdown at the bottom left on dashboard (Example URL - `https://app.corp.com/`) +2. Select **Add a new workspace**. +3. Fill in the workspace name and slug in the modal. +4. Click **Create workspace**. + +Create workspace + +## Editing Workspaces +**Role required** - Workspace Admin + +To edit a workspace, + +1. Open the workspace dropdown at the bottom left on dashboard (Example URL - `https://app.corp.com/`) +2. Hover over the **current workspace** in the dropdown menu. +3. Click the **edit icon** to modify the workspace name or slug. +4. Save the changes, and the updates will reflect immediately across the platform. + +## Switching Workspaces + +To switch between the workspaces, + +1. Open the workspace dropdown at the bottom left on dashboard (Example URL - `https://app.corp.com/`) +2. Select the desired workspace from the list to switch instantly. +Archive workspace + +## Archiving Workspaces +**Role required** - Super Admin + +- This feature is available only for self-hosted users, and only [Super Admin](/docs/user-management/role-based-access/super-admin) can archive workspaces. A Super Admin is the user who has full access to all the Workspaces, Users, and Groups of an instance +- To archive a workspace, at least one active workspace must exist in the instance. + +- **Impact** + - The apps within the archived workspace will no longer be accessible through the URL. + - Users without access to any active workspace will be logged out. + +- To archive a workspace: + +1. Go to **Settings** > **All Workspaces**. ( Example URL - `https://app.corp.com/instance-settings/all-workspaces`) +2. A table listing all workspaces will appear. +3. Click the Archive button to open a confirmation modal. Once you confirm, the selected workspace will be archived. + + +Archive workspace + +## Unarchive Workspace + +**Role required** - Super Admin + +- To unarchive a workspace: + +1. Go to **Settings** > **All Workspaces**. ( Example URL - `https://app.corp.com/instance-settings/all-workspaces`) +2. A table displaying all workspaces will appear. Click on the Archived tab to view archived workspaces. +3. Click the Unarchive button to unarchive the selected workspace. + +## Default Workspace + +**Role required** - Super Admin + +Default workspace in ToolJet simplifies team onboarding. When configured, new users can sign up through the main company (instance) URL and get added to the default workspace. This eliminates the need to share & maintain long workspace URLs for single-workspace set ups. + +The first workspace created by the super admin will be designate as the default workspace. To update the default workspace for your instance, navigate to **Settings** > **All workspaces**. Here you'll find a dropdown labeled *Default Workspace*. From here, select the workspace you want to designate as the default. + +Set default workspace + +When configuring login settings for your instance, make sure to enable the Enable Signup option. Once enabled, you can share your instance URL (e.g., `https://app.corp.com`) for inviting users to sign up. + +Be sure to share the complete instance URL, whether it’s a subdomain, subpath, or a full custom domain. Anyone who signs up using this link will be added to the default workspace. + +:::note +The default workspace cannot be archived. Please set a different workspace as the default before proceeding with archiving this one. +::: + + +## Workspace Admin + +- A Workspace has a three predefined roles, Admins, Builders and Endusers with predefined permissions. Checkout the [users and groups](/docs/user-management/role-based-access/user-roles) docs for more details. +- The user who creates a workspace is automatically assigned as its **Admin**. +- An **Admin** can: + - Manage users, groups, data and apps within each workspace. + - Configure authentication methods for their workspaces. + +Admin user has access to all the permission at workspace level, while an end user can only view and use the released apps they are given access to and permissions can be configured for a builder. + +| Permission | Admin | Builder | End User | +|:------------------------------|:-----:|:-------:|:--------:| +| App | βœ… | Configurable | ❌ | +| Data sources | βœ… | Configurable | ❌ | +| Folder | βœ… | Configurable | ❌ | +| Workspace constants/variables | βœ… | Configurable | ❌ | + + +## FAQ + +
+ +Can applications and workspace settings be shared between workspaces? + +**No**, applications and workspace settings cannot be shared directly between workspaces. Each workspace operates independently, maintaining its own applications and configurations. However, you can **export an application** from one workspace and **import it** into another. For more details, refer to the [Import and Export Applications](/docs/app-builder/importing-exporting-applications/) documentation. + +
+ +
+ +Do users have access to all workspaces by default? + +**No**, users need to be **invited** to a specific workspace to access the apps and data within that workspace. Refer to [invite users](/docs/user-management/role-based-access/user-roles) documentation for more details + +
+ diff --git a/docs/versioned_docs/version-3.16.0-LTS/tooljet-api.md b/docs/versioned_docs/version-3.16.0-LTS/tooljet-api.md new file mode 100644 index 0000000000..712ce83eb2 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tooljet-api.md @@ -0,0 +1,1381 @@ +--- +id: tooljet-api +title: ToolJet API +--- + +
+
+ Icon + Paid feature +
+ +
+ Self Hosted +
+ +
+ + +ToolJet API allows you to interact with the ToolJet platform programmatically. You can use the APIs to manage users and their workspaces relations. The API endpoints are secured with an access token. You can perform various operations using the API such as: + +- [Get All Users](#get-all-users) +- [Get All Workspaces](#get-all-workspaces) +- [Get All App Details](#get-all-app-details) +- [Get User by ID](#get-user-by-id) +- [Create User](#create-user) +- [Update User](#update-user) +- [Update User Role](#update-user-role) +- [Replace User Workspace](#replace-user-workspace) +- [Replace User Workspaces Relations](#replace-user-workspaces-relations) +- [Export Application](#export-application) +- [Import Application](#import-application) +- [Add HTTPS Git Config for an Organization](#add-https-git-config-for-an-organization) +- [Push an App Version to GitHub](#push-an-app-version-to-github) +- [Create a New App from GitHub](#create-a-new-app-from-github) +- [Sync and Pull Changes to Existing App from Git](#sync-and-pull-changes-to-existing-app-from-git) +- [Auto Promote App](#auto-promote-app) + +## Enabling ToolJet API + +By default, the ToolJet API is disabled. To enable the API, add these variables to your `.env` file: + +| variable | description | +| :-----------------------: | :---------------------------------------------: | +| ENABLE_EXTERNAL_API | `true` or `false` | +| EXTERNAL_API_ACCESS_TOKEN | `` (To authenticate API requests) | + +## Security + +The ToolJet API is secured with an access token created by you in your `.env` file. You need to pass the access token in the `Authorization` header to authenticate your requests. The access token should be sent in the format `Basic `. + +
+ +cURL Request Example + +```bash + +curl -X GET 'https://your-tooljet-instance.com/api/ext/users' \ +-H 'Authorization: Basic ' \ +-H 'Content-Type: application/json' + +``` + +
+ +## API Endpoints + +### Get All Users + + - **Description:** Retrieves a list of all the users. + - **URL:** `/api/ext/users` + - **Method:** GET + - **Authorization:** `Basic ` + - **Content-Type:** `application/json` + - **Response:** Array of User objects. + +
+ **Response Example** +```json +[ + { + "id": "5b1608df-5e14-474b-b304-919623a9be57", + "name": "Sam Oliver", + "email": "sam@example.com", + "status": "active", + "workspaces": [ + { + "id": "a831db72-c3d2-4b36-a98e-0023ffb15e66", + "name": "demo-workspace", + "status": "active", + "groups": [ + { + "id": "b3ae95dd-b1ca-4a21-abac-b321ee76698e", + "name": "all_users" + }, + { + "id": "1830a113-24e5-4e33-8af2-e6502d477239", + "name": "admin" + } + ] + } + ] + }, + { + "id": "919623a-5e14-4v4b-63b4-3343a9be57", + "name": "David Smith", + "email": "david@example.com", + "status": "active", + "workspaces": [ + { + "id": "a831db72-c3d2-4b36-a98e-0023ffb15e66", + "name": "demo-workspace", + "status": "active", + "groups": [ + { + "id": "b3ae95dd-b1ca-4a21-abac-b321ee76698e", + "name": "all_users" + }, + { + "id": "1830a113-24e5-4e33-8af2-e6502d477239", + "name": "admin" + } + ] + }, + { + "id": "b8a0c07d-2430-46fd-ba71-2a71e48fde30", + "name": "team-spac", + "status": "active", + "groups": [ + { + "id": "7f7af977-a7e7-49e3-a08a-2dffce6f5942", + "name": "all_users" + }, + { + "id": "eda68cf3-b70d-455f-8a2a-8cd4bbff77a6", + "name": "admin" + } + ] + } + ] + } + ] +``` +
+ +### Get All Workspaces + + - **Description:** Retrieves a list of all workspaces. + - **URL:** `/api/ext/workspaces` + - **Method:** GET + - **Authorization:** `Basic ` + - **Content-Type:** `application/json` + - **Response:** Array of Workspace objects. + +
+Response Example + +```json +[ + { + "id": "a831db72-c3d2-4b36-a98e-0023ffb15e66", + "name": "demo-workspace", + "status": "active", + "groups": [ + { + "id": "b3ae95dd-b1ca-4a21-abac-b321ee76698e", + "name": "all_users" + }, + { + "id": "1830a113-24e5-4e33-8af2-e6502d477239", + "name": "admin" + } + ] + }, + { + "id": "b8a0c07d-2430-46fd-ba71-2a71e48fde30", + "name": "team-spac", + "status": "active", + "groups": [ + { + "id": "7f7af977-a7e7-49e3-a08a-2dffce6f5942", + "name": "all_users" + }, + { + "id": "eda68cf3-b70d-455f-8a2a-8cd4bbff77a6", + "name": "admin" + } + ] + } +] +``` + +
+ +### Get All App Details + + - **Description:** Get the app details for all the applications in the workspace. + - **URL:** `/api/ext/workspace/:workspace_id/apps` + - **Method:** GET + - **Authorization:** `Basic ` + - **Content-Type:** `application/json` + - **Params:** + - **workspace_id**: The ID of the workspace. + - **Response:** Array of app details for all the applications in the workspace. + +
+ **Response Example** + ```json + [ + { + "id": "ae06cc7a-2922-4fe7-9064-462741558813", + "name": "Applicant tracking system", + "slug": "ae06cc7a-2922-4fe7-9064-462741558813", + "versions": [ + { + "id": "37be6442-ca1b-4a5a-a6f4-f929e00a0ac1", + "name": "v1" + }, + { + "id": "be8a96c3-f7a4-4f82-b282-23678c52c973", + "name": "v3" + }, + { + "id": "19405d8c-be75-47ad-aa96-36f2b1728e77", + "name": "v2" + }, + { + "id": "15bd421d-54ce-44d5-8eef-39911fc2d4cb", + "name": "v4" + } + ] + }, + { + "id": "b68f87ca-6620-4cbf-83d6-becf073d8e96", + "name": "Aws Tracker", + "slug": "b68f87ca-6620-4cbf-83d6-becf073d8e96", + "versions": [ + { + "id": "466a1cc4-62cf-4b46-b71d-114af61c04ca", + "name": "v1" + }, + { + "id": "b65f1ae2-3702-4cba-91f3-3e5bddd55dbc", + "name": "v2" + } + ] + } + ] + ``` +
+ +### Get User by ID + + - **Description:** Returns a user by their ID. + - **URL:** `/api/ext/user/:id` + - **Method:** GET + - **Authorization:** `Basic ` + - **Content-Type:** `application/json` + - **Params:** + - id (string): The ID of the user. + - **Response:** User object. + +
+ **Response Example** +```json +{ + "id": "5b1608df-5e14-474b-b304-919623a9be57", + "name": "Sam Oliver", + "email": "sam@example.com", + "status": "active", + "workspaces": [ + { + "id": "a831db72-c3d2-4b36-a98e-0023ffb15e66", + "name": "demo-workspace", + "status": "active", + "groups": [ + { + "id": "b3ae95dd-b1ca-4a21-abac-b321ee76698e", + "name": "all_users" + }, + { + "id": "1830a113-24e5-4e33-8af2-e6502d477239", + "name": "admin" + } + ] + }, + { + "id": "b8a0c07d-2430-46fd-ba71-2a71e48fde30", + "name": "team-spac", + "status": "active", + "groups": [ + { + "id": "7f7af977-a7e7-49e3-a08a-2dffce6f5942", + "name": "all_users" + }, + { + "id": "eda68cf3-b70d-455f-8a2a-8cd4bbff77a6", + "name": "admin" + } + ] + } + ] +} +``` +
+ +### Create User + + - **Description:** Creates a new user. + - **URL:** `/api/ext/users` + - **Method:** POST + - **Authorization:** `Basic ` + - **Content-Type:** `application/json` + - **Body:** The body object can contain the following fields: + - `name` (string, required): The name of the user. + - `email` (string, required): The email address of the user. + - `password` (string, optional): The user's password. Must be between 5 and 100 characters. + - `status` (string, optional): The status of the user. Can be either `active` or `archived`. Defaults to `archived` if not provided. + - `workspaces` (array, required): An array of workspace objects associated with the user. Each workspace object should contain: + - `id` (string, required): The unique identifier of the workspace. + - `name` (string, required): The name of the workspace. + - `status` (string, optional): The status of the workspace. Can be either `active` or `archived`. + - `groups` (array, optional): An array of group objects associated with the workspace. Each group object can contain: + - `id` (string, optional): The unique identifier of the group. + - `name` (string, optional): The name of the group. + - `status` (string, optional): The status of the group. Can be either `active` or `archived`. + +
+ **Request Body Example** +```json +{ + "name": "Alice Johnson", + "email": "alice@example.com", + "password": "qwy@4xt123", + "status": "active", + "workspaces": [ + { + "name": "team-spac", + "status": "active", + "groups": [ + { + "name": "all_users" + } + ] + } + ] +} +``` +
+ - **Response:** `201 Created` + +### Update User + + - **Description:** Finds and updates a user by their ID. + - **URL:** `/api/ext/user/:id` + - **Method:** PATCH + - **Authorization:** `Basic ` + - **Content-Type:** `application/json` + - **Params:** + - id (string): The ID of the user. + - **Body:** The body object can contain the following fields: + - `name` (string, optional): The updated name of the user. + - `email` (string, optional): The updated email address of the user. + - `password` (string, optional): The updated password for the user. Must be between 5 and 100 characters. + - `status` (string, optional): The updated status of the user. Can be either `active` or `archived`. + + +
+ +Request Body Example + +```json +{ + "name": "Jane Doe", + "email": "jane.doe@example.com", + "password": "newsecurepassword", + "status": "active" +} +``` + +
+ + - **Response:** `200 OK` + +### Update User Role + + - **Description:** Updates the user role for a particular workspace. + - **URL:** `/api/ext/update-user-role/workspace/workspaceId` + - **Method:** PUT + - **Authorization:** `Basic ` + - **Content-Type:** `application/json` + - **Params:** + - workspaceId (string): The unique identifier of the workspace. + - **Body:** The body object can contain the following fields: + - `newRole` (string, required): The updated user role of the user. + - `userId` (string, required): The unique identifier of the user. + + +
+ +Request Body Example + +```json +{ + "newRole": "end-user", + "userId": "f2065dd1-e5ea-4793-af91-4a8831de68e6" +} +``` + +
+ + - **Response:** `200 OK` + +### Replace User Workspaces Relations + + - **Description:** Replaces all workspaces relations associated with a user. + - **URL:** `/api/ext/user/:id/workspaces` + - **Method:** PUT + - **Authorization:** `Basic ` + - **Content-Type:** `application/json` + - **Params:** + - id (string): The ID of the user. + - **Body:** Array of workspace data transfer objects. It may contain the following fields: + - `id` (string, required): The unique identifier of the workspace. + - `name` (string, required): The name of the workspace. + - `status` (string, optional): The status of the workspace. Can be either `active` or `archived`. + - `groups` (array, optional): An array of group objects associated with the workspace. Each group object can contain: + - `id` (string, optional): The unique identifier of the group. + - `name` (string, optional): The name of the group. + - `status` (string, optional): The status of the group. Can be either `active` or `archived`. + - **Note:** If the array is empty, it will remove all existing workspace relations. + - **Response:** `200 OK` + + + +### Replace User Workspace + + - **Description:** Updates a specific workspace relation associated with a user. + - **URL:** `/api/ext/user/:id/workspaces/:workspaceId` + - **Method:** PATCH + - **Authorization:** `Basic ` + - **Content-Type:** `application/json` + - **Params:** + - id (string): The ID of the user. + - workspaceId (string): The ID of the workspace. + - **Body:** The body object can contain the following fields: + - `id` (string, optional): The ID of the workspace. + - `name` (string, optional): The updated name of the workspace. + - `status` (string, optional): The updated status of the workspace. Can be either `active` or `archived`. + - `groups` (array, optional): An array of group objects associated with the workspace. Each group object can contain: + - `id` (string, optional): The ID of the group. + - `name` (string, optional): The name of the group. + +
+ +Request Body Example + +```json +{ + "status": "archived", + "groups": [ + { + "name": "all_users" + } + ] +} +``` + +
+ - **Note:** If no body is given or body is an empty object, it will not do anything. + - **Response:** `200 OK` + +### Export Application + +From version **`v3.5.7-ee-lts`**, you can use ToolJet API to export application. + + - **Description:** Export a ToolJet Application from a specified workspace. + - **URL:** `/api/ext/export/workspace/:workspace_id/apps/:app_id` + - **Method:** POST + - **Authorization:** `Basic ` + - **Content-Type:** `application/json` + - **Params:** + - **workspace_id**: The ID of the workspace. + - **app_id**: The ID of the application. + - **Query Params:** + - **exportTJDB** (boolean): Specifies whether to export TJDB data or not. By default **true**. + - **appVersion** (string): Accepts a specific version of the application that is to be exported. + - **exportAllVersions** (boolean): Defines whether to export all the available versions. By default it exports the latest version of the app. + - **Response:** Exported application json. + +
+Response Example + +```json +{ + "app": [ + { + "definition": { + "appV2": { + "type": "front-end", + "id": "ab65b201-4207-4876-a8a6-fdcbf31661b6", + "name": "ToolJet API Application", + "slug": "ab65b201-4207-4876-a8a6-fdcbf31661b6", + "isPublic": false, + "isMaintenanceOn": false, + "icon": "home", + "organizationId": "45892c81-c1f0-48c6-8875-c2e4fca516f8", + "currentVersionId": null, + "userId": "3ca0bd7a-b8e0-40d9-a2d8-2c7531dc3bee", + "workflowApiToken": null, + "workflowEnabled": false, + "createdAt": "2025-02-28T06:21:34.962Z", + "creationMode": "DEFAULT", + "updatedAt": "2025-02-28T06:21:34.961Z", + "editingVersion": { + "id": "ab40f07f-96c7-4283-afb8-8cd88df7b195", + "name": "v1", + "definition": null, + "globalSettings": { + "hideHeader": false, + "appInMaintenance": false, + "canvasMaxWidth": 100, + "canvasMaxWidthType": "%", + "canvasMaxHeight": 2400, + "canvasBackgroundColor": "#edeff5", + "backgroundFxQuery": "", + "appMode": "auto" + }, + "pageSettings": null, + "showViewerNavigation": true, + "homePageId": "c7099c38-5e2a-4e68-9e30-9005f881d75b", + "appId": "ab65b201-4207-4876-a8a6-fdcbf31661b6", + "currentEnvironmentId": "60eff059-202a-4c12-ae12-507874f9191d", + "promotedFrom": null, + "createdAt": "2025-02-28T06:21:34.974Z", + "updatedAt": "2025-02-28T06:21:34.961Z" + }, + "components": [ + { + "id": "ebe9d705-a0df-4dbb-9bf3-ab28cab12ae3", + "name": "table1", + "type": "Table", + "pageId": "c7099c38-5e2a-4e68-9e30-9005f881d75b", + "parent": null, + "properties": { + "title": { + "value": "Table" + }, + "visible": { + "value": "{{true}}" + }, + "loadingState": { + "value": "{{false}}" + }, + "data": { + "value": "{{ [ \n\t\t{ id: 1, name: 'Olivia Nguyen', email: 'olivia.nguyen@example.com', date: '15/05/2022', mobile_number: 9876543210, interest: ['Reading', 'Traveling','Photography'], photo: 'https://reqres.in/img/faces/7-image.jpg' }, \n\t\t{ id: 2, name: 'Liam Patel', email: 'liam.patel@example.com', date: '20/09/2021', mobile_number: 8765432109, interest: ['Cooking','Gardening','Hiking'], photo: 'https://reqres.in/img/faces/5-image.jpg' }\n] }}" + }, + "useDynamicColumn": { + "value": "{{false}}" + }, + "columnData": { + "value": "{{[{name: 'email', key: 'email', id: '1'}, {name: 'Full name', key: 'name', id: '2', isEditable: true}]}}" + }, + "rowsPerPage": { + "value": "{{10}}" + }, + "serverSidePagination": { + "value": "{{false}}" + }, + "enableNextButton": { + "value": "{{true}}" + }, + "enablePrevButton": { + "value": "{{true}}" + }, + "totalRecords": { + "value": "{{10}}" + }, + "enablePagination": { + "value": "{{true}}" + }, + "serverSideSort": { + "value": "{{false}}" + }, + "serverSideFilter": { + "value": "{{false}}" + }, + "displaySearchBox": { + "value": "{{true}}" + }, + "showDownloadButton": { + "value": "{{true}}" + }, + "showFilterButton": { + "value": "{{true}}" + }, + "autogenerateColumns": { + "value": true, + "generateNestedColumns": true + }, + "isAllColumnsEditable": { + "value": "{{false}}" + }, + "columns": { + "value": [ + { + "name": "id", + "id": "e3ecbf7fa52c4d7210a93edb8f43776267a489bad52bd108be9588f790126737", + "autogenerated": true, + "fxActiveFields": [], + "columnSize": 30, + "columnType": "string" + }, + { + "name": "photo", + "key": "photo", + "id": "f23b7d134b2e490ea41e3bb8eeb8c8e37472af243bf6b70d5af294482097e3a2", + "autogenerated": true, + "fxActiveFields": [], + "columnType": "image", + "objectFit": "contain", + "borderRadius": "100", + "columnSize": 70 + }, + { + "name": "name", + "id": "5d2a3744a006388aadd012fcc15cc0dbcb5f9130e0fbb64c558561c97118754a", + "autogenerated": true, + "fxActiveFields": [], + "columnSize": 130, + "columnType": "string" + }, + { + "name": "email", + "id": "afc9a5091750a1bd4760e38760de3b4be11a43452ae8ae07ce2eebc569fe9a7f", + "autogenerated": true, + "fxActiveFields": [], + "columnSize": 230, + "columnType": "string" + }, + { + "name": "date", + "id": "27b75c8af9d34d1eaa1f9bb7f8f9f7b0abf1823e799748c8bb57e74f53b2c1dc", + "autogenerated": true, + "fxActiveFields": [], + "columnType": "datepicker", + "isTimeChecked": false, + "dateFormat": "DD/MM/YYYY", + "parseDateFormat": "DD/MM/YYYY", + "isDateSelectionEnabled": true, + "columnSize": 130 + }, + { + "name": "mobile_number", + "id": "9c2e3c40572a4aefb8e179ee39a0e1ac9dc2b2e6634be56e1c05be13c3d1de56", + "autogenerated": true, + "fxActiveFields": [], + "columnType": "number", + "columnSize": 140 + }, + { + "name": "interest", + "key": "interest", + "id": "f23b7d134b2e490ea41e3bb8eeb8c8e37472af243bf6b70d5af294482097e3a1", + "autogenerated": true, + "fxActiveFields": [], + "columnType": "newMultiSelect", + "columnSize": 300, + "options": [ + { + "label": "Reading", + "value": "Reading" + }, + { + "label": "Traveling", + "value": "Traveling" + }, + { + "label": "Photography", + "value": "Photography" + }, + { + "label": "Music", + "value": "Music" + }, + { + "label": "Cooking", + "value": "Cooking" + }, + { + "label": "Crafting", + "value": "Crafting" + }, + { + "label": "Voluntering", + "value": "Voluntering" + }, + { + "label": "Garndening", + "value": "Garndening" + }, + { + "label": "Dancing", + "value": "Dancing" + }, + { + "label": "Hiking", + "value": "Hiking" + } + ] + } + ] + }, + "showBulkUpdateActions": { + "value": "{{true}}" + }, + "showBulkSelector": { + "value": "{{false}}" + }, + "highlightSelectedRow": { + "value": "{{false}}" + }, + "columnSizes": { + "value": "{{({})}}" + }, + "actions": { + "value": [] + }, + "enabledSort": { + "value": "{{true}}" + }, + "hideColumnSelectorButton": { + "value": "{{false}}" + }, + "defaultSelectedRow": { + "value": "{{{\"id\":1}}}" + }, + "showAddNewRowButton": { + "value": "{{true}}" + }, + "allowSelection": { + "value": "{{true}}" + }, + "visibility": { + "value": "{{true}}" + }, + "disabledState": { + "value": "{{false}}" + } + }, + "general": {}, + "styles": { + "textColor": { + "value": "#000" + }, + "columnHeaderWrap": { + "value": "fixed" + }, + "actionButtonRadius": { + "value": "0" + }, + "cellSize": { + "value": "regular" + }, + "borderRadius": { + "value": "8" + }, + "tableType": { + "value": "table-classic" + }, + "maxRowHeight": { + "value": "auto" + }, + "maxRowHeightValue": { + "value": "{{0}}" + }, + "contentWrap": { + "value": "{{true}}" + }, + "boxShadow": { + "value": "0px 0px 0px 0px #00000090" + }, + "padding": { + "value": "default" + } + }, + "generalStyles": { + "boxShadow": { + "value": "0px 0px 0px 0px #00000040" + } + }, + "displayPreferences": { + "showOnDesktop": { + "value": "{{true}}" + }, + "showOnMobile": { + "value": "{{false}}" + } + }, + "validation": {}, + "createdAt": "2025-02-28T06:21:45.706Z", + "updatedAt": "2025-02-28T06:23:49.872Z", + "layouts": [ + { + "id": "f72adb7f-708c-4c5f-9a3b-be9467f7dcc0", + "type": "mobile", + "top": 180, + "left": 18, + "width": 35, + "height": 456, + "componentId": "ebe9d705-a0df-4dbb-9bf3-ab28cab12ae3", + "dimensionUnit": "count", + "updatedAt": "2025-02-28T06:21:45.706Z" + }, + { + "id": "d6c8807f-dde5-4d0a-83f3-2a8036c4c147", + "type": "desktop", + "top": 30, + "left": 2, + "width": 39, + "height": 630, + "componentId": "ebe9d705-a0df-4dbb-9bf3-ab28cab12ae3", + "dimensionUnit": "count", + "updatedAt": "2025-02-28T06:23:32.534Z" + } + ] + } + ], + "pages": [ + { + "id": "c7099c38-5e2a-4e68-9e30-9005f881d75b", + "name": "Home", + "handle": "home", + "index": 1, + "disabled": null, + "hidden": null, + "icon": null, + "createdAt": "2025-02-28T06:21:34.961Z", + "updatedAt": "2025-02-28T06:21:36.766Z", + "autoComputeLayout": true, + "appVersionId": "ab40f07f-96c7-4283-afb8-8cd88df7b195", + "pageGroupIndex": 1, + "pageGroupId": null, + "isPageGroup": false + } + ], + "events": [], + "dataQueries": [], + "dataSources": [], + "appVersions": [ + { + "id": "ab40f07f-96c7-4283-afb8-8cd88df7b195", + "name": "v1", + "definition": null, + "globalSettings": { + "hideHeader": false, + "appInMaintenance": false, + "canvasMaxWidth": 100, + "canvasMaxWidthType": "%", + "canvasMaxHeight": 2400, + "canvasBackgroundColor": "#edeff5", + "backgroundFxQuery": "", + "appMode": "auto" + }, + "pageSettings": null, + "showViewerNavigation": true, + "homePageId": "c7099c38-5e2a-4e68-9e30-9005f881d75b", + "appId": "ab65b201-4207-4876-a8a6-fdcbf31661b6", + "currentEnvironmentId": "60eff059-202a-4c12-ae12-507874f9191d", + "promotedFrom": null, + "createdAt": "2025-02-28T06:21:34.974Z", + "updatedAt": "2025-02-28T06:21:34.961Z" + } + ], + "appEnvironments": [ + { + "id": "60eff059-202a-4c12-ae12-507874f9191d", + "organizationId": "45892c81-c1f0-48c6-8875-c2e4fca516f8", + "name": "development", + "isDefault": false, + "priority": 1, + "enabled": true, + "createdAt": "2024-08-22T10:34:39.181Z", + "updatedAt": "2024-08-22T10:34:39.181Z" + }, + { + "id": "48aa7f50-8709-4ae1-92cd-049b2aa22080", + "organizationId": "45892c81-c1f0-48c6-8875-c2e4fca516f8", + "name": "staging", + "isDefault": false, + "priority": 2, + "enabled": true, + "createdAt": "2024-08-22T10:34:39.181Z", + "updatedAt": "2024-08-22T10:34:39.181Z" + }, + { + "id": "8f0a5c41-cea1-452a-b27c-e93337b567bd", + "organizationId": "45892c81-c1f0-48c6-8875-c2e4fca516f8", + "name": "production", + "isDefault": true, + "priority": 3, + "enabled": true, + "createdAt": "2024-08-22T10:34:39.181Z", + "updatedAt": "2024-08-22T10:34:39.181Z" + } + ], + "dataSourceOptions": [], + "schemaDetails": { + "multiPages": true, + "multiEnv": true, + "globalDataSources": true + } + } + } + } + ], + "tooljet_version": "3.5.11-cloud-lts" +} +``` + +
+ +### Import Application + +From version **`v3.5.7-ee-lts`**, you can use ToolJet API to import application. + + - **Description:** Import a Application in ToolJet Workspace. + - **URL:** `/api/ext/import/workspace/:workspace_id/apps` + - **Method:** POST + - **Authorization:** `Basic ` + - **Content-Type:** `application/json` + - **Params:** + - **workspace_id**: The ID of the workspace. + - **Body:** The body object will contain following fields: + - Application JSON + - `appName` (string, optional): Defines the application name. If not defined then the app will be imported with the existing app name. + +:::info +By default, server accepts maximum JSON size as 50 MB. To increase this limit, use the following environment variable: +`MAX_JSON_SIZE` +::: + +
+ +Request Body Example + +```json +{ + "app": [ + { + "definition": { + "appV2": { + "type": "front-end", + "id": "ab65b201-4207-4876-a8a6-fdcbf31661b6", + "name": "ToolJet API Application", + "slug": "ab65b201-4207-4876-a8a6-fdcbf31661b6", + "isPublic": false, + "isMaintenanceOn": false, + "icon": "home", + "organizationId": "45892c81-c1f0-48c6-8875-c2e4fca516f8", + "currentVersionId": null, + "userId": "3ca0bd7a-b8e0-40d9-a2d8-2c7531dc3bee", + "workflowApiToken": null, + "workflowEnabled": false, + "createdAt": "2025-02-28T06:21:34.962Z", + "creationMode": "DEFAULT", + "updatedAt": "2025-02-28T06:21:34.961Z", + "editingVersion": { + "id": "ab40f07f-96c7-4283-afb8-8cd88df7b195", + "name": "v1", + "definition": null, + "globalSettings": { + "hideHeader": false, + "appInMaintenance": false, + "canvasMaxWidth": 100, + "canvasMaxWidthType": "%", + "canvasMaxHeight": 2400, + "canvasBackgroundColor": "#edeff5", + "backgroundFxQuery": "", + "appMode": "auto" + }, + "pageSettings": null, + "showViewerNavigation": true, + "homePageId": "c7099c38-5e2a-4e68-9e30-9005f881d75b", + "appId": "ab65b201-4207-4876-a8a6-fdcbf31661b6", + "currentEnvironmentId": "60eff059-202a-4c12-ae12-507874f9191d", + "promotedFrom": null, + "createdAt": "2025-02-28T06:21:34.974Z", + "updatedAt": "2025-02-28T06:21:34.961Z" + }, + "components": [ + { + "id": "ebe9d705-a0df-4dbb-9bf3-ab28cab12ae3", + "name": "table1", + "type": "Table", + "pageId": "c7099c38-5e2a-4e68-9e30-9005f881d75b", + "parent": null, + "properties": { + "title": { + "value": "Table" + }, + "visible": { + "value": "{{true}}" + }, + "loadingState": { + "value": "{{false}}" + }, + "data": { + "value": "{{ [ \n\t\t{ id: 1, name: 'Olivia Nguyen', email: 'olivia.nguyen@example.com', date: '15/05/2022', mobile_number: 9876543210, interest: ['Reading', 'Traveling','Photography'], photo: 'https://reqres.in/img/faces/7-image.jpg' }, \n\t\t{ id: 2, name: 'Liam Patel', email: 'liam.patel@example.com', date: '20/09/2021', mobile_number: 8765432109, interest: ['Cooking','Gardening','Hiking'], photo: 'https://reqres.in/img/faces/5-image.jpg' }\n] }}" + }, + "useDynamicColumn": { + "value": "{{false}}" + }, + "columnData": { + "value": "{{[{name: 'email', key: 'email', id: '1'}, {name: 'Full name', key: 'name', id: '2', isEditable: true}]}}" + }, + "rowsPerPage": { + "value": "{{10}}" + }, + "serverSidePagination": { + "value": "{{false}}" + }, + "enableNextButton": { + "value": "{{true}}" + }, + "enablePrevButton": { + "value": "{{true}}" + }, + "totalRecords": { + "value": "{{10}}" + }, + "enablePagination": { + "value": "{{true}}" + }, + "serverSideSort": { + "value": "{{false}}" + }, + "serverSideFilter": { + "value": "{{false}}" + }, + "displaySearchBox": { + "value": "{{true}}" + }, + "showDownloadButton": { + "value": "{{true}}" + }, + "showFilterButton": { + "value": "{{true}}" + }, + "autogenerateColumns": { + "value": true, + "generateNestedColumns": true + }, + "isAllColumnsEditable": { + "value": "{{false}}" + }, + "columns": { + "value": [ + { + "name": "id", + "id": "e3ecbf7fa52c4d7210a93edb8f43776267a489bad52bd108be9588f790126737", + "autogenerated": true, + "fxActiveFields": [], + "columnSize": 30, + "columnType": "string" + }, + { + "name": "photo", + "key": "photo", + "id": "f23b7d134b2e490ea41e3bb8eeb8c8e37472af243bf6b70d5af294482097e3a2", + "autogenerated": true, + "fxActiveFields": [], + "columnType": "image", + "objectFit": "contain", + "borderRadius": "100", + "columnSize": 70 + }, + { + "name": "name", + "id": "5d2a3744a006388aadd012fcc15cc0dbcb5f9130e0fbb64c558561c97118754a", + "autogenerated": true, + "fxActiveFields": [], + "columnSize": 130, + "columnType": "string" + }, + { + "name": "email", + "id": "afc9a5091750a1bd4760e38760de3b4be11a43452ae8ae07ce2eebc569fe9a7f", + "autogenerated": true, + "fxActiveFields": [], + "columnSize": 230, + "columnType": "string" + }, + { + "name": "date", + "id": "27b75c8af9d34d1eaa1f9bb7f8f9f7b0abf1823e799748c8bb57e74f53b2c1dc", + "autogenerated": true, + "fxActiveFields": [], + "columnType": "datepicker", + "isTimeChecked": false, + "dateFormat": "DD/MM/YYYY", + "parseDateFormat": "DD/MM/YYYY", + "isDateSelectionEnabled": true, + "columnSize": 130 + }, + { + "name": "mobile_number", + "id": "9c2e3c40572a4aefb8e179ee39a0e1ac9dc2b2e6634be56e1c05be13c3d1de56", + "autogenerated": true, + "fxActiveFields": [], + "columnType": "number", + "columnSize": 140 + }, + { + "name": "interest", + "key": "interest", + "id": "f23b7d134b2e490ea41e3bb8eeb8c8e37472af243bf6b70d5af294482097e3a1", + "autogenerated": true, + "fxActiveFields": [], + "columnType": "newMultiSelect", + "columnSize": 300, + "options": [ + { + "label": "Reading", + "value": "Reading" + }, + { + "label": "Traveling", + "value": "Traveling" + }, + { + "label": "Photography", + "value": "Photography" + }, + { + "label": "Music", + "value": "Music" + }, + { + "label": "Cooking", + "value": "Cooking" + }, + { + "label": "Crafting", + "value": "Crafting" + }, + { + "label": "Voluntering", + "value": "Voluntering" + }, + { + "label": "Garndening", + "value": "Garndening" + }, + { + "label": "Dancing", + "value": "Dancing" + }, + { + "label": "Hiking", + "value": "Hiking" + } + ] + } + ] + }, + "showBulkUpdateActions": { + "value": "{{true}}" + }, + "showBulkSelector": { + "value": "{{false}}" + }, + "highlightSelectedRow": { + "value": "{{false}}" + }, + "columnSizes": { + "value": "{{({})}}" + }, + "actions": { + "value": [] + }, + "enabledSort": { + "value": "{{true}}" + }, + "hideColumnSelectorButton": { + "value": "{{false}}" + }, + "defaultSelectedRow": { + "value": "{{{\"id\":1}}}" + }, + "showAddNewRowButton": { + "value": "{{true}}" + }, + "allowSelection": { + "value": "{{true}}" + }, + "visibility": { + "value": "{{true}}" + }, + "disabledState": { + "value": "{{false}}" + } + }, + "general": {}, + "styles": { + "textColor": { + "value": "#000" + }, + "columnHeaderWrap": { + "value": "fixed" + }, + "actionButtonRadius": { + "value": "0" + }, + "cellSize": { + "value": "regular" + }, + "borderRadius": { + "value": "8" + }, + "tableType": { + "value": "table-classic" + }, + "maxRowHeight": { + "value": "auto" + }, + "maxRowHeightValue": { + "value": "{{0}}" + }, + "contentWrap": { + "value": "{{true}}" + }, + "boxShadow": { + "value": "0px 0px 0px 0px #00000090" + }, + "padding": { + "value": "default" + } + }, + "generalStyles": { + "boxShadow": { + "value": "0px 0px 0px 0px #00000040" + } + }, + "displayPreferences": { + "showOnDesktop": { + "value": "{{true}}" + }, + "showOnMobile": { + "value": "{{false}}" + } + }, + "validation": {}, + "createdAt": "2025-02-28T06:21:45.706Z", + "updatedAt": "2025-02-28T06:23:49.872Z", + "layouts": [ + { + "id": "f72adb7f-708c-4c5f-9a3b-be9467f7dcc0", + "type": "mobile", + "top": 180, + "left": 18, + "width": 35, + "height": 456, + "componentId": "ebe9d705-a0df-4dbb-9bf3-ab28cab12ae3", + "dimensionUnit": "count", + "updatedAt": "2025-02-28T06:21:45.706Z" + }, + { + "id": "d6c8807f-dde5-4d0a-83f3-2a8036c4c147", + "type": "desktop", + "top": 30, + "left": 2, + "width": 39, + "height": 630, + "componentId": "ebe9d705-a0df-4dbb-9bf3-ab28cab12ae3", + "dimensionUnit": "count", + "updatedAt": "2025-02-28T06:23:32.534Z" + } + ] + } + ], + "pages": [ + { + "id": "c7099c38-5e2a-4e68-9e30-9005f881d75b", + "name": "Home", + "handle": "home", + "index": 1, + "disabled": null, + "hidden": null, + "icon": null, + "createdAt": "2025-02-28T06:21:34.961Z", + "updatedAt": "2025-02-28T06:21:36.766Z", + "autoComputeLayout": true, + "appVersionId": "ab40f07f-96c7-4283-afb8-8cd88df7b195", + "pageGroupIndex": 1, + "pageGroupId": null, + "isPageGroup": false + } + ], + "events": [], + "dataQueries": [], + "dataSources": [], + "appVersions": [ + { + "id": "ab40f07f-96c7-4283-afb8-8cd88df7b195", + "name": "v1", + "definition": null, + "globalSettings": { + "hideHeader": false, + "appInMaintenance": false, + "canvasMaxWidth": 100, + "canvasMaxWidthType": "%", + "canvasMaxHeight": 2400, + "canvasBackgroundColor": "#edeff5", + "backgroundFxQuery": "", + "appMode": "auto" + }, + "pageSettings": null, + "showViewerNavigation": true, + "homePageId": "c7099c38-5e2a-4e68-9e30-9005f881d75b", + "appId": "ab65b201-4207-4876-a8a6-fdcbf31661b6", + "currentEnvironmentId": "60eff059-202a-4c12-ae12-507874f9191d", + "promotedFrom": null, + "createdAt": "2025-02-28T06:21:34.974Z", + "updatedAt": "2025-02-28T06:21:34.961Z" + } + ], + "appEnvironments": [ + { + "id": "60eff059-202a-4c12-ae12-507874f9191d", + "organizationId": "45892c81-c1f0-48c6-8875-c2e4fca516f8", + "name": "development", + "isDefault": false, + "priority": 1, + "enabled": true, + "createdAt": "2024-08-22T10:34:39.181Z", + "updatedAt": "2024-08-22T10:34:39.181Z" + }, + { + "id": "48aa7f50-8709-4ae1-92cd-049b2aa22080", + "organizationId": "45892c81-c1f0-48c6-8875-c2e4fca516f8", + "name": "staging", + "isDefault": false, + "priority": 2, + "enabled": true, + "createdAt": "2024-08-22T10:34:39.181Z", + "updatedAt": "2024-08-22T10:34:39.181Z" + }, + { + "id": "8f0a5c41-cea1-452a-b27c-e93337b567bd", + "organizationId": "45892c81-c1f0-48c6-8875-c2e4fca516f8", + "name": "production", + "isDefault": true, + "priority": 3, + "enabled": true, + "createdAt": "2024-08-22T10:34:39.181Z", + "updatedAt": "2024-08-22T10:34:39.181Z" + } + ], + "dataSourceOptions": [], + "schemaDetails": { + "multiPages": true, + "multiEnv": true, + "globalDataSources": true + } + } + } + } + ], + "tooljet_version": "3.5.11-cloud-lts", + "appName": "ToolJet API Application" +} +``` + +
+ + - **Response:** `201 Created` diff --git a/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/constraints/foreign-key.md b/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/constraints/foreign-key.md new file mode 100644 index 0000000000..bb3868ea5f --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/constraints/foreign-key.md @@ -0,0 +1,124 @@ +--- +id: foreign-key +title: Foreign Key +--- + +A foreign key relation refers to linking one column or set of columns of the current table with one column or set of columns in an existing table. This relationship establishes a connection between the two tables, enabling the current source table to reference the existing target table. While creating a Foreign Key relationship, you can select the desired [action](#foreign-key-actions) to be performed on the source row when the referenced(target) row is updated or deleted. + +
+ +## Constraints +- The target table must contain a column having the same data type as the column in the source table. +- The column that has to be referenced in the target table must have Unique constraint explicitly. +- The target table must already exist before adding the Foreign Key relationship in the source table. + +## Limitations +- Self-references are not allowed i.e. Target table and Source table cannot be the same. +- No foreign key can be created with a column of serial data type in the source table. +- No foreign key can be reference a column in target table that is a part of its composite Primary key. + +## Exception +- The foreign key created with a column having integer data type in the source table can also reference a column of serial data type in the target table. + +
+ +
+ +## Creating Foreign Key + +While creating/editing a table(target), you will be able to add one or more than one Foreign Keys referencing the column(s) of other existing(source) tables. +To create a Foreign Key relationship, follow these steps: + + - Create or edit an existing table. + - Click on the `+ Add Relation` button under the Foreign key relation section. + - The table which is being created/edited is the source table. + - Under the source section, select the desired column from the dropdown menu. + - Under the target section, select the desired target table and Column from the dropdown menu. + - Under the Actions section, select the desired action to be performed when the referenced row is updated or deleted. + - Click on the `Create` button to create the Foreign Key relationship. + +ToolJet database + +When defining the foreign key column, the default value can be set to Null. This ensures that if no explicit value is provided for the foreign key during record creation or update, the database will automatically assign null to the column. + +Default value Null + +
+ +
+ +## Foreign Key Actions + +When creating a foreign key relationship, ToolJet Database lets you choose from several actions to be performed on the source row when the referenced row in the target table is updated or deleted. + +### On Update + +| Option | Description | +| --- | --- | +| Restrict (default) | Restrict any updates on target table if any referenced row is being updated. | +| Cascade | Any updates in referenced row in target table will show up in the source table as well. | +| Set NULL | Any updates in referenced row in target table will set it's instances in the source table as NULL. | +| Set to Default | Any updates referenced row in target table will set it's instances in the source table as default value of foreign key column of source table. | + +### On Delete + +| Option | Description | +| --- | --- | +| Restrict (default) | Restrict any deletion on target table if any referenced row is being updated. | +| Cascade | Any deletion of referenced row in target table will delete the row having it's instance in the source table as well. | +| Set NULL | Any deletion of referenced row in target table will set it's instances in the source table as NULL. | +| Set to Default | Any deletion of referenced row in target table will set it's instances in the source table as default value of foreign key column of source table. | + +
+ +
+ +## Referential Integrity + +The foreign key constraint ensures referential integrity between the source and target tables. This constraint enforces that the foreign key column in the source table has one of the unique values present in the foreign key column in the target table.
+- When creating a new row in the source table the column with the foreign key relation will have a dropdown with the unique values present in the target table. This ensures that the data in the source table is always consistent with the data in the target table. +- On the bottom of the dropdown, there is a button to **Open referenced table** which will take you to the target table. + +ToolJet database + +- When editing the value of a foreign key cell in an existing row of the source table, the dropdown will show the unique values present in the target table. This ensures that even when the data in the source table is being updated, it is always consistent with the data in the target table. + +ToolJet database + +### Example + +Let's consider an example where we want to create a foreign key relationship between the `Orders` and `Customers` tables in an e-commerce application. + +First, create the following two tables in the ToolJet Database: + +**Customers** + +| Column Name | Data Type | Primary Key | Not Null | Unique | +|-------------|-----------|:--------------:|:--------:|:--------:| +| customer_id | int | βœ… | βœ… | βœ… | +| name | varchar | ❌ | βœ… | ❌ | +| email | varchar | ❌ | βœ… | βœ… | + +**Orders** + +| Column Name | Data Type | Primary Key | Not Null | Unique | +|--------------|-----------|:--------------:|:--------:|:--------:| +| order_id | int | βœ… | βœ… | βœ… | +| customer_id | int | ❌ | βœ… | ❌ | +| order_date | varchar | ❌ | βœ… | ❌ | +| total_amount | float | ❌ | βœ… | ❌ | + +We want to create a foreign key relationship between the `customer_id` column in the `Orders` table and the `customer_id` column in the `Customers` table. + +1. **Define the Foreign Key Relationship** + - Edit the `Orders` table. + - Click on the **+ Add Relation** button under the Foreign Key Relation section. + - In the **Source** section, select the `customer_id` column. + - In the **Target** section, select the `Customers` table and the `customer_id` column. + - Choose the desired action, for example, **RESTRICT** to prevent deleting a customer that has associated orders. + +3. **Save Changes**: Click the **Save Changes** button to create the foreign key relationship. + +Now, whenever you try to insert or update a record in the `Orders` table, the `customer_id` value must correspond to an existing `customer_id` value in the `Customers` table. This is also prevent you from deleting a customer that has associated orders. This ensures that orders are always associated with a valid customer, maintaining data integrity and consistency. + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/constraints/primary-key.md b/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/constraints/primary-key.md new file mode 100644 index 0000000000..39c80fec9a --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/constraints/primary-key.md @@ -0,0 +1,87 @@ +--- +id: primary-key +title: Primary Key +--- + +ToolJet Database supports both single field and composite primary keys. + +
+ +## Creating Single Field Primary Key + +When creating a new table, an `id` column with the `serial` data type is automatically generated to serve as the primary key. However, you can designate any other column as the primary key if desired. The primary key column can be of any supported data type except Boolean. +The constraints for the primary key column ensure the integrity and uniqueness of the primary key, which is essential for properly identifying and referencing records within the table. To create a single field primary key, follow these steps: + + - Create or edit an existing table. + - Check the **Primary** checkbox on the column which you want to set as the primary key. + - This will automatically add the primary key constraint to the column. + - Click on the **Create** button to create the table. + +ToolJet database + +### Constraints +- The primary key column cannot contain null values. +- The primary key column must have unique values across all rows. + +### Limitations +- Every table must have at least one primary key. +- The primary key column cannot have the Boolean data type. + +
+ +
+ +## Creating Composite Primary Key + +You have the option to convert an existing primary key column into a composite primary key, consisting of two or more columns. +By utilizing a composite primary key, you can uniquely identify records based on multiple column values, providing greater flexibility and control over your data structure. To create a composite primary key, follow these steps: + + - Create or edit an existing table. + - Check the **Primary** checkbox on multiple columns to set them as the composite primary key. + - This will automatically add the primary key constraint to the selected columns. + - Click on the **Save changes/Create** button to update/create the table. + +ToolJet database + +### Constraints +- None of the composite key columns can contain null values. +- The combination of values across all composite key columns must be unique for each row in the table. + +### Limitation +- The composite key columns cannot be of the Boolean data type. + +
+ +
+ +## Modifying Primary Key + +After creating a table, you can designate any column as the primary key, provided it adheres to the required constraints. If the chosen column already contains data, the existing values must comply with the primary key constraints. However, you cannot update or modify the primary key of a target table if it is currently being referenced as a foreign key in any other source tables. To modify the primary key, follow these steps: + + - Edit an existing table. + - Check the **Primary** checkbox on the column which you want to set as the primary key. + - This will automatically add the primary key constraint to the column. + - Uncheck the **Primary** checkbox on the existing primary key column. The primary key constraints will still stay in place for this column but are no longer necessary. + - Click on the **Save changes** button to update the table. + +ToolJet database + +
+ +
+ +## Deleting Primary Key + +An existing primary key column can be deleted through the **Edit Table** panel. To delete the primary key column, follow these steps: + +- Edit an existing table. +- Select a different column to serve as the new primary key for the table. +- Once the new primary key column is designated, you can proceed to the existing primary key column. +- Uncheck the **Primary** checkbox for the existing primary key column to remove its primary key status. +- After removing the primary key constraint, you can delete this column from the table. + +You cannot delete a Primary Key of a target table if it is being used as a foreign key in any source table(s). + +ToolJet database + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/data-types.md b/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/data-types.md new file mode 100644 index 0000000000..d0f72853ea --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/data-types.md @@ -0,0 +1,36 @@ +--- +id: data-types +title: Data Types +--- + +ToolJet Database supports several data types to accommodate various kinds of information. Each data type has its own characteristics and uses. + +## Supported Data Types + +| Data Type | Description | Example | +|:--------------------|:----------- |:------- | +| **serial** | Used to generate a sequence of integers, often used as the Primary key of a table. When a new table is created in the ToolJet database, a column **id** with the serial data type is automatically created as the **primary key** of the table. | Numbers starting from 1, 2, 3, 4, 5, etc. | +| **varchar** | Used to store characters of indefinite length | Any string value | +| **int** | A numeric data type used to store whole numbers, without fractional components. | Numbers ranging from -2147483648 to 2147483647 | +| **bigint** | A numeric data type used to store larger whole numbers, without fractional components. | Numbers ranging from -9223372036854775808 to 9223372036854775807 | +| **float** | A numeric data type used to store inexact, variable-precision values. | Any floating-point number, ex: 3.14 | +| **boolean** | Can hold true, false, and null values. | `true` or `false` | +| **date with time** | Stores both date and time information in ISO 8601 format. The default timezone is set to the user's device time zone, with an option to specify a different timezone. All timestamp data is stored in UTC format and converted to the specified timezone when displayed. | '2024-07-22 15:30:00' | +| **jsonb** | Used to store JSON data, can store structured data like arrays or nested objects. | `{"name": "John Doe", "age": 30, "skills": ["JavaScript", "Python"], "address": {"city": "New York", "zip": "10001"}}` | + +ToolJet database + +## Permissible Constraints per Data Type + +The following table shows which constraints are permissible for each data type. For more detailed explanations of each constraint type, please refer to the [Column Constraints](/docs/tooljet-db/database-editor#column-constraints) section. + +| Data Type | Primary Key | Foreign Key | Unique | Not Null | +|:--------------:|:--------------:|:-------------:|:------:|:----------:| +| serial | βœ… | ❌ | βœ… | βœ… | +| varchar | βœ… | βœ… | βœ… | βœ… | +| int | βœ… | βœ… | βœ… | βœ… | +| bigint | βœ… | βœ… | βœ… | βœ… | +| float | βœ… | βœ… | βœ… | βœ… | +| boolean | ❌ | ❌ | ❌ | βœ… | +| date with time | ❌ | ❌ | ❌ | βœ… | +| jsonb | ❌ | ❌ | ❌ | βœ… | \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/database-editor.md b/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/database-editor.md new file mode 100644 index 0000000000..50139ec6ec --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/database-editor.md @@ -0,0 +1,174 @@ +--- +id: database-editor +title: Database Editor +--- + +You can manage the ToolJet Database directly from the Database Editor. ToolJet Database organizes the data into **tables** that can have different structures. All the tables will be listed lexicographically on the left. Click on any of the tables to view the table data. + +ToolJet database + +The sidebar on the left can also be collapsed to give more space to the database editor. + +ToolJet database + +
+ +## Create New Table + +To create a new table in the ToolJet Database: + - Click on the **Create New Table** button on the top left corner of the Database editor. + - A drawer will open from the right. Enter the details of your new table. + +#### To create a new table, you'll need to: +- Enter a **Table name**. +- By default, an **id** column with **serial** data type is automatically created as the **primary key** of the table. You can change the primary key to any other column. + +ToolJet database + +- Add Columns: + +| **Option** | **Description** | +| --- | --- | +| **Column name** | Enter a unique name for the column. | +| **Data type** | Select the appropriate data type for the column from the dropdown menu. For more information on available data types, see the [Supported Data Types](/docs/tooljet-db/data-types#supported-data-types) section. | +| **Default value (optional)** | Specify any default value to be assigned to the column. If left blank, the column will allow null values. | +| **Primary Key** | Check this box to designate the column as the [Primary Key](/docs/tooljet-db/constraints/primary-key). Multiple columns can be selected, creating a composite primary key. | +| **NULL/NOT NULL toggle** | Use this toggle to determine whether the column should allow null values or require a value. By default, null values are permitted. | +| **Unique toggle** | Click the kebab menu and toggle the **Unique** option to add a unique constraint to the column, ensuring all values are distinct. By default, duplicate values are allowed. | +| **Foreign Key** | Click the **+ Add Relation** button to establish a foreign key relationship, linking this column to a primary key or unique constraint column(s) in another table. | + +
+ +
+ +## Column Constraints + +ToolJet Database supports several column constraints to maintain data integrity and enforce rules on the data stored in the tables. These constraints include: + +**Primary Key**: The primary key constraint ensures that the values in the designated column(s) are unique and not null across all rows in the table. It serves as a unique identifier for each record in the table. + +**Foreign Key**: The foreign key constraint establishes a link between the data in two tables, ensuring referential integrity. It requires that the values in the foreign key column(s) of the source table match the values in the primary key or unique constraint column(s) of the target table. + - Source Table: The current table on which constraint is to be added. + - Target Table: The table that contains the column to be referenced. + +**Unique**: The unique constraint ensures that the values in the designated column(s) are unique across all rows in the table, allowing for null values. + +**Not Null**: The not null constraint ensures that the designated column(s) cannot have null values, requiring a value for every row in the table. + +For a detailed overview of which constraints are allowed for each data type, refer to the [Permissible Constraints per Data Type](/docs/tooljet-db/data-types#permissible-constraints-per-data-type) table. + +
+ +
+ +## Adding and Modifying Data + +### Add New Data + +The Add new data button on the top of the table editor allows you to add data to the table. You can either **[Add new row](#add-new-row)** or **[Bulk upload data](#bulk-upload-data)** to add the data to the table. + +ToolJet database + +### Add New Row + +To add a new row to a table, either click on the `Add new data` button on top and then select the **Add new row** option or click on the **+** button present at the bottom left.
+A drawer from the right will open up where the values for the new row can be provided. + +ToolJet database + +### Edit Row + +To edit a row, hover on the row that you want to edit and the expand icon will appear next to the checkbox of that row. Click on the Expand icon to open the drawer and edit the row. + +ToolJet database + +### Edit a Cell + +- Double-click on the cell you want to edit. +- Enter the new value. +- Click on the **Save** button or press **Enter** to save the changes. +- For boolean-type columns, use the toggle to change the value. + +ToolJet database + +### Bulk Upload Data + +You can bulk upload data to the ToolJet database by clicking the **Bulk upload data** button at the top of the database editor. On clicking the button, a drawer will open from the right from where you can upload a **CSV** file. This file is used to insert records onto the table. If data for the id column is missing, it will insert a new record with the row data; if the id is present, it will update the corresponding record with the row data. + +From the drawer, users can download the **template CSV file** in which they can enter the data to be uploaded to the ToolJet database's table or format their CSV file in the same way as the template file. + +Once the CSV file is ready, click on the file picker to select the file or drag and drop the file in the file picker. Now, click on the **Upload data** button to upload the data to the ToolJet database. + +**Requirements**: +- The data types of columns in the CSV file should match those in the ToolJet database table. +- The `id` column with a `serial` data type should not contain duplicate values. +- All the column constraints should be satisfied. For example, if a column is marked as `Unique`, it should not contain duplicate values in the CSV file. + +**Limitations**: +- There is a limit of 1000 rows per CSV file that can be uploaded to the ToolJet database. +- The CSV file should not exceed 2MB in size. + +:::info +You can overcome the above limitations in the self-hosted version by adding the following environment variables: +- `TOOLJET_DB_BULK_UPLOAD_MAX_ROWS`: Specifies the maximum number of rows that can be uploaded. The default is 1,000 rows. +- `TOOLJET_DB_BULK_UPLOAD_MAX_CSV_FILE_SIZE_MB`: Specifies the maximum CSV file size for bulk uploads. The default maximum size is 5 MB. +::: + +ToolJet database + +### Delete Records + +To delete one or many records/rows, click the checkbox to the right of the record or records you want to delete. As soon as you select a single record, the button to delete the record will appear on the top, click on the **Delete record** button to delete the selected records. + +ToolJet database + +
+ +
+ +## Filter + +### Add Filter + +You can add as many filters as you want into the table by clicking on the **Filter** button present on the top of the database editor. + +#### Adding a filter on the table data +- Select a **column** from the Columns dropdown. +- Choose an **[operation](#available-operations-are)**. +- Enter a **value** for the selected operation. + +#### Available operations are: +| **Operation** | **Description** | +| --- | --- | +| **equals** | This operation is used to check if the value of the column is equal to the value entered in the input field. | +| **greater than** | This operation is used to check if the value of the column is greater than the value entered in the input field. | +| **greater than or equal** | This operation is used to check if the value of the column is greater than or equal to the value entered in the input field. | +| **less than** | This operation is used to check if the value of the column is less than the value entered in the input field. | +| **less than or equal** | This operation is used to check if the value of the column is less than or equal to the value entered in the input field. | +| **not equal** | This operation is used to check if the value of the column is not equal to the value entered in the input field. | +| **like** | This operation is used to check if the value of the column is like the value entered in the input field. This operation is case-sensitive. ex: `ToolJet` will not match `tooljet` | +| **ilike** | This operation is used to check if the value of the column is like the value entered in the input field. This operation is case-insensitive. ex: `ToolJet` will match `tooljet` | +| **match** | This operation is used to check if the value of the column is like the value entered in the input field. This operation is case-sensitive. ex: `ToolJet` will not match `tooljet`. This operation uses regular expressions. ex: `^ToolJet$` will match `ToolJet` but not `ToolJet Inc`. | +| **imatch** | This operation is used to check if the value of the column is like the value entered in the input field. This operation is case-insensitive. This operation uses regular expressions. ex: `^ToolJet$` will match `ToolJet` but not `ToolJet Inc`. | +| **in** | This operation is used to check if the value of the column is in the list of values entered in the input field. ex: `(1,2,3)` | +| **is** | This operation is used to check if the value of the column is equal to the value entered in the input field. This operation is used for boolean data types. | + +ToolJet database + +### Clear Filter + +You can either delete filters individually or clear all the filters together. + +ToolJet database + +
+ +
+ +## Sort + +To sort the table data, click on the **Sort** button on top, select a **column** from the dropdown, and then choose an order **ascending** or **descending**. + +ToolJet database + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/querying-tooljet-db.md b/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/querying-tooljet-db.md new file mode 100644 index 0000000000..d264421385 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/querying-tooljet-db.md @@ -0,0 +1,274 @@ +--- +id: querying-tooljet-db +title: Querying Data +--- + +Querying the ToolJet database is as easy as querying any other data source on ToolJet. You can use either the GUI or the SQL editor to interact with your data. + +## GUI Mode + +1. Go to the **Query panel**, and click on the **+Add** button to add a new query, and select **ToolJet Database**. + ToolJet Database editor +2. Select the GUI mode from the toggle. +3. Select the table you want to query and the operation from the dropdown, then enter the required parameters for the selected operation. +4. Click on the **Run** button to execute the query. + +:::info +The selected operation should adhere to the column constraints of the selected table. +::: + +ToolJet Database editor + +### List Rows + +This operation returns all the records from the table. + +#### Optional Parameters + +- **Filter**: Add a condition by choosing a column, an operation, and the value for filtering the records. +- **Sort**: Sort the query response by choosing a column and the order (ascending or descending). +- **Limit**: Limit the number of records to be returned by entering a number. +- **Aggregate**: Perform calculations on a set of values and return a single result. + - Available functions: Count, Sum + - Limitations: + - Sum only for numeric columns. + - Count only for non-null values. + ToolJet Database editor +- **Group By**: Group rows with the same values in specified columns. + - Can only be used after adding at least one aggregate condition. + - Select one or more columns to group by. + - Results are grouped based on unique combinations of values in selected columns. + ToolJet Database editor + +### Create row + +This operation creates a new record in the table. You can create a single record or multiple records at once. + +#### Required Parameters + +- **Columns**: Choose the columns, add values for the new record, and enter the values. You can also add a new column by clicking on the **+Add column** button. + +### Update Row + +This operation updates a record in the table. You can update a single record or multiple records at once. + +#### Required Parameter + +- **Filter**: Add a condition by choosing a column, an operation, and the value for updating a particular record. +- **Columns**: Choose the columns, update the values for the selected record, and enter the values. + +### Delete Row + +This operation deletes a record in the table. You can delete a single record or multiple records at once. + +#### Required Parameters + +- **Filter**: Add a condition by selecting a column, an operation, and the value to delete a specific record. +- **Limit**: Limit the number of records to be deleted by entering a number. + +### Bulk Update with Primary Key + +This operation can be used to update multiple rows using the primary key. Primary key can be a singular primary key or a composite primary key. + +#### Required Parameters + +- **Primary key**: The primary key of the table is auto selected and cannot be edited. +- **Rows to upsert**: Array of objects of rows to be updated. Each object in the array need to specify primary key column(s) with their values. + +ToolJet Database editor + +### Bulk Upsert with Primary Key + +This operation can be used to upsert multiple rows using the primary key. Primary key can be a singular primary key or a composite primary key. Using the upsert operation you can update an existing row or insert a new row if it doesn't exisit. + +#### Required Parameters + +- **Primary key**: The primary key of the table is auto selected and cannot be edited. +- **Rows to upsert**: Array of objects of rows to be updated. Each object in the array need to specify primary key column(s) with their values. + +ToolJet Database editor + +## SQL Editor + +The ToolJet **SQL editor** allows you to query the ToolJet Database by writing SQL queries, specifically supporting standard SQL syntax for **Data Manipulation Language (DML)** commands. This feature is only available on the [Self-Hosted](/docs/tj-setup/tj-deployment#self-hosted-tooljet) version of ToolJet. + +### Supported SQL Commands + +- **DML Commands**: You can use the following DML commands to manipulate data: + + - **SELECT**: Retrieve data from the database. + - **INSERT**: Add new records to the database. + - **UPDATE**: Modify existing data. + - **DELETE**: Remove records from the database. + +- **Restricted Commands**: + - **Data Definition Language (DDL)** commands like **CREATE**, **ALTER**, **TRUNCATE**, **DROP**, and **RENAME** are not allowed. + - **Data Control Language (DCL)** commands like **GRANT** and **REVOKE** are also restricted. + +### SQL Editor Usage + +1. In the Query panel, click on the **+Add** button to add a new query, and select **ToolJet Database**. +2. Select the **SQL** mode tab in the query editor. +3. Write your SQL query in the editor. +4. Click on the **Run** button to execute the query. + +ToolJet Database SQL Editor + +Example: + +```sql +SELECT * FROM users WHERE age > 30 +``` + +## Modifying Tables with Foreign Key Constraints + +When you are creating, updating, or deleting records in a table that has a foreign key constraint, you need to ensure that the foreign key constraint is not violated. + +- If you are trying to create/update a new row in the source table, you need to ensure that the foreign key value exists in the target table. Otherwise, the operation will fail with an error message. + +ToolJet database + + +- Similarly, if you are trying to delete a row in the target table, you need to ensure that the foreign key value is not being referenced in the source table. + +## Join Tables + +You can join two or more tables in the ToolJet database by using the **Join** operation. + +#### Required Parameters + +- **From**: In the From section, the following parameters are available: + + - **Selected Table**: Select the table from which you want to join the other table. + - **Type of Join**: Select the type of join you want to perform. The available options are: `Inner Join`, `Left Join`, `Right Join`, and `Full Outer Join`. + - **Joining Table**: Select the table that you want to join with the selected table. If the selected table has a foreign key relationship(s) with other tables, those tables will be listed with a foreign key icon next to their name. + - **On**: Select the column from the **selected table** and the **joining table** on which you want to join the tables. Currently, only `=` operation is supported for joining tables. If the selected table and the joining table have a foreign key relationship, both the columns will be auto-populated in the **On** dropdown. + + ToolJet database + + - **AND or OR condition**: You can add multiple conditions by clicking on the **+Add more** button below each join. The conditions can be joined by `AND` or `OR` operation. + + ToolJet Database editor + +- **Filter**: Add a condition by choosing a column, an operation, and the value for filtering the records. The operations supported are same as the [filter operations](/docs/tooljet-db/database-editor#available-operations-are) for the **List rows** operation. +- **Sort**: Sort the query response by choosing a column and the order (ascending or descending). +- **Limit**: Limit the number of records to be returned by entering a number. +- **Offset**: Offset the number of records to be returned by entering a number. This parameter is used for pagination. +- **Select**: Select the columns that you want to return in the query response. By default, all the columns are selected. + +ToolJet Database editor + +## Mapping Date with Time Column to Table Component + +The date with time column stores data in the ISO 8601 format. When querying a table with a date with time column, the column is displayed in the ISO 8601 format by default. To display the date with time column in a more readable format in the Table Component, follow these steps: + +1. Connect the query to the Table Component and navigate to its properties panel. +2. In the Columns section, select the column that stores the date with time. +3. Change the column type from String to **Date Picker**. +4. Under the date format section, toggle on the **Enable date** and **Enable time** options accordingly. +5. In the transformation field, the `{{cellValue}}` variable contains the ISO 8601 formatted date. Convert it to a Date object using `{{new Date(cellValue)}}`, then format the Date object to meet your requirements. + +ToolJet Database Date + +## Querying JSON Data Type + +In ToolJet Database, a column can be set to JSON Data Type. It can be used to store structured data like arrays or nested objects, making it useful for complex data structures such as configurations or logs. To query the JSON Data Type, follow the following steps: + +### Flat JSON Object + +A flat JSON object is a JSON structure where all key-value pairs exist at a single level, without any nesting. Each key is unique within the object, and all values are direct data entries rather than other objects or arrays. + +1. Add **ToolJet DB** as the Data Source from the query panel. +2. Select **GUI mode** (else you can select SQL mode as well). +3. Select the **Table name**. +4. Select the desired operation from the dropdown. +5. Click on **+ Add Condition** button in front of Filter. +6. Choose column that consist JSON Data, choose the desired operation and enter the value. +7. In the input box below the column name, enter the desired key by adding `->>` before the key, example `->>city`. + +ToolJet Database Date + +
+**Response Example** + +```json +[ + { + "id": 1, + "json": { + "id": 101, + "age": 30, + "city": "Los Angeles", + "name": "Alice Johnson", + "email": "alice@example.com", + "country": "USA" + } + } +] +``` + +
+ +### Nested JSON Object + +A nested JSON object is a JSON structure that contains key-value pairs, where some values are themselves JSON objects or arrays. This creates a hierarchical, multi-level structure with nested layers, which can represent complex relationships between data elements. + +1. Add **ToolJet DB** as the Data Source from the query panel. +2. Select **GUI mode** (else you can select SQL mode as well). +3. Select the **Table name**. +4. Select the desired operation from the dropdown. +5. Click on **+ Add Condition** button in front of Filter. +6. Choose column that consist JSON Data, choose the desired operation and enter the value. +7. In the input box below the column name, enter the desired JSON path by adding `->` before each key, example `->user->preferences->settings->notifications->sms->alerts->appointments->cancellations`. + +ToolJet Database Date + +**Note:** You can use `->` to access nested JSON fields and use `->>` to access the text. + +
+**Response Example** + +```json +[ + { + "id": 102, + "name": "Michael Brown", + "age": 25, + "email": "michael@example.com", + "user": { + "preference": { + "settings": { + "notification": { + "sms": { + "alert": false + } + } + } + } + } + }, + { + "id": 104, + "name": "David Miller", + "age": 35, + "email": "david@example.com", + "user": { + "preference": { + "settings": { + "notification": { + "sms": { + "alert": false + } + } + } + } + } + } +] +``` + +
+ +:::info +If you have any other questions or feedback about **ToolJet Database**, please reach us out at hello@tooljet.com or join our **[Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA)** +::: diff --git a/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/table-operations.md b/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/table-operations.md new file mode 100644 index 0000000000..dd9e52b13b --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/table-operations.md @@ -0,0 +1,79 @@ +--- +id: table-operations +title: Table Operations +--- + +## Search Table + +Open the Search bar by clicking on the **Search** button and search for a table in the ToolJet database by entering the table name. + +ToolJet database + +
+ +## Rename Table + +To rename a table, click on the kebab menu icon on the right of the table name and then select the **Edit table** option. A drawer will open from the right from where you can edit the table name. + +ToolJet database + +
+ +
+ +## Add New Column + +To add a new column to a table, either click on the kebab menu icon on the right of the table name and then select the **Add new column** option or click on the **+** button present at the end of the column header. + +A drawer from the right will open up where you can enter the details for the new column: + +- **Column Name**: Enter a unique name for the new column, serving as its key identifier. +- **Data Type**: Choose the appropriate data type for the column from the [available options](/docs/tooljet-db/data-types#supported-data-types). For more information on data types and their associated constraints, see the [Supported Data Types](/docs/tooljet-db/data-types#supported-data-types) and [Permissible Constraints per Data Type](/docs/tooljet-db/data-types#permissible-constraints-per-data-type) sections. +- **Default Value**: Specify any default value that should be assigned to the column. Optionally, users can leave this field blank. When a table contains rows and NOT NULL is applied to one of its existing or new columns, specifying a default value becomes compulsory. +- **Foreign Key Relation**: Click on the toggle to add a foreign key relationship to the column. This will open a menu where you can select the target table and column to reference. + +ToolJet database + +
+ +
+ +## Export Schema + +The export schema option allows you to download the selected table schema in a JSON file. This does not export the table data or the relationships.
+While exporting the app, you can choose to export the app with or without a table schema connected to the app.
+To export the table schema, click on the three vertical dots icon on the right of the table name and then click on the **Export** option. A JSON file will be downloaded with the table schema. + +ToolJet database + +
+ +
+ +## Delete Table + +To delete a table, click on the three vertical dots icon on the right of the table name and then click on the **Delete** option. A confirmation modal will appear, click on the **Delete** button to delete the table. + +ToolJet database + +
+ +
+ +## Edit Column + +To edit a column, click on the kebab menu on the column name and select the option to **Edit column**. When you edit the column, the data type cannot be changed. + +ToolJet database + +
+ +
+ +## Delete Column + +To delete a column, click on the kebab menu on the column name and select the option to **Delete**. You cannot delete a column if it is being used as a primary key. You will have to remove the primary key constraint from the column before deleting it. + +ToolJet database + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/tooljet-database.md b/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/tooljet-database.md new file mode 100644 index 0000000000..0c7c4bbf93 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tooljet-db/tooljet-database.md @@ -0,0 +1,103 @@ +--- +id: tooljet-database +title: Overview +--- + +Use the ToolJet-hosted database to build apps faster, and manage your data with ease. ToolJet database require no setup and gives you a powerful user interface for managing your data. + +
+ ToolJet database +
+ +
+ +## Enabling the ToolJet Database for your instance + +Requires: +- PostgREST server +- Additional configuration for ToolJet server + +This feature is only enabled if [`ENABLE_TOOLJET_DB`](/docs/setup/env-vars#tooljet-database) is set to `true`. + +
+ +### PostgREST Server + +PostgREST is a standalone web server that turns your PostgreSQL database directly into queryable RESTful APIs which is utilized for Tooljet Database. This server only communicates with the ToolJet server and therefore does not need to be publicly exposed. + +:::tip +If you have openssl installed, you can run the +command `openssl rand -hex 32` to generate the value for `PGRST_JWT_SECRET`. + +If this parameter is not specified, then PostgREST refuses authentication requests. +::: + +|
Variable
|
Description
| +| ---------------------------- | ----------------------------------------------- | +| PGRST_JWT_SECRET | JWT token client provided for authentication | +| PGRST_DB_URI | database connection string for tooljet database | +| PGRST_LOG_LEVEL | `info` | +| PGRST_DB_PRE_CONFIG | postgrest.pre_config | + +:::info +Please make sure that DB_URI is given in the format `postgres://[USERNAME]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]` +::: + +
+ +#### Additional ToolJet server configuration + + +|
Variable
|
Description
| +| ------------------ | -------------------------------------------- | +| TOOLJET_DB | Default value is `tooljet_db` | +| TOOLJET_DB_HOST | database host | +| TOOLJET_DB_USER | database username | +| TOOLJET_DB_PASS | database password | +| TOOLJET_DB_PORT | database port | +| PGRST_JWT_SECRET | JWT token client provided for authentication | +| PGRST_HOST | postgrest database host | +| TOOLJET_DB_BULK_UPLOAD_MAX_ROWS | Maximum rows allowed to bulk upload. Default value is 1000 | +| TOOLJET_DB_BULK_UPLOAD_MAX_CSV_FILE_SIZE_MB | Maximum file size of CSV for bulk upload. Default value is 5 MB | + + +If you intend to make changes in the above configuration. Please refer [PostgREST configuration docs](https://postgrest.org/en/stable/configuration.html#environment-variables). + +:::tip +When this feature is enabled, the database name provided for `TOOLJET_DB` will be utilized to create a new database during server boot process in all of our production deploy setups. +In case you want to trigger it manually, use the command `npm run db:create` on ToolJet server. +::: + +
+ +
+ +## Features + +ToolJet database allows you to: + +- **Maintain tables of data** in a secure database that's only accessible within your ToolJet organization. +- **Edit, search, filter, sort, and filter** data using a spreadsheet-like interface. +- **Use the SQL editor** to write and execute complex SQL queries directly on your ToolJet database, providing more advanced data manipulation and retrieval capabilities. +- **Quickly build applications and write queries** to interact with the ToolJet Database, just like any other datasource but without any setup. +- **Export schema** from the ToolJet Database to a JSON file. +- Uniquely identify each record in a table using **Primary Keys**, ensuring data integrity and enabling efficient querying and indexing. +- Establish relationships between tables using **Foreign Keys**, allowing you to create associations based on the Primary Key of one table and maintain referential integrity. + +
+ +
+ +## Accessing ToolJet Database + +Once you log-in to your ToolJet account, from the left sidebar of the dashboard you can navigate to **ToolJet Database**. + +The ToolJet Database is available on: **[ToolJet Cloud](https://tooljet.ai)**, **[Self-Host](/docs/setup/)**, and **Enterprise Edition**. You can manage your database and its data using the **Database editor UI**. + +
+ ToolJet database +
+ +
+ + diff --git a/docs/versioned_docs/version-3.16.0-LTS/tooljetcli.md b/docs/versioned_docs/version-3.16.0-LTS/tooljetcli.md new file mode 100644 index 0000000000..295d6cbf60 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tooljetcli.md @@ -0,0 +1,93 @@ +--- +id: tooljet-cli +title: ToolJet CLI +--- + +ToolJet CLI is a powerful tool that empowers developers to effortlessly create and enhance Marketplace plugins for ToolJet workspace. + +:::info +Starting from ToolJet CLI version 0.0.14, the creation of datasource plugins has been deprecated to prioritize marketplace plugins. This change enhances the plugin development experience and aligns with ToolJet's roadmap. +::: + +## Installation + +In order to manage plugins for the ToolJet marketplace, including creating, updating, and deleting, you will need to utilize **[tooljet-cli](https://www.npmjs.com/package/@tooljet/cli)**. This can be installed via npm by entering the following command: + +```bash +npm install -g @tooljet/cli +``` + +
+ +ToolJet CLI installation + +
+ +#### Ensure the installation was successful + +```bash +tooljet --version +``` + +
+ +ToolJet CLI version check + +
+ +## Commands + +### info + +This command returns the information about where tooljet is being run + +```bash +tooljet info +``` + +
+ +ToolJet CLI info + +
+ +### create + +This command creates a new plugin. + +```bash +tooljet plugin create PLUGIN_NAME +``` +:::tip +Read the detailed guide on creating a marketplace plugin [here](/docs/contributing-guide/marketplace/creating-a-plugin). +::: + +
+ +ToolJet CLI : create plugin + +
+ +### delete + +This command deletes a plugin. + +```bash +tooljet plugin delete PLUGIN_NAME +``` + +The CLI will prompt developers to verify if the plugin to be deleted is a marketplace plugin before proceeding with the deletion. + +
+ +ToolJet CLI: delete plugin + +
+ +### install + +Installs a new npm module inside a tooljet plugin + +```bash +tooljet plugin install [NPM_MODULE] --plugin +``` \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/tracking.md b/docs/versioned_docs/version-3.16.0-LTS/tracking.md new file mode 100644 index 0000000000..695bcae677 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tracking.md @@ -0,0 +1,13 @@ +--- +id: tracking +title: Tracking +slug: /tracking +--- + +
+ +ToolJet does not store any data fetched from the data sources. ToolJet acts as a proxy and the data from data sources is sent to the client application without storing. + +ToolJet tracks anonymous usage data such as page loads and clicks. **ToolJet tracks only the events and doesn't capture data from data sources.** + +Tracking can be disabled by setting the value environment variable `ENABLE_TRACKING` to `0`. diff --git a/docs/versioned_docs/version-3.16.0-LTS/tutorial/_category_.json b/docs/versioned_docs/version-3.16.0-LTS/tutorial/_category_.json new file mode 100644 index 0000000000..1ed20f00b1 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tutorial/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Tutorial", + "position": 4, + "collapsed": false +} diff --git a/docs/versioned_docs/version-3.16.0-LTS/tutorial/actions.md b/docs/versioned_docs/version-3.16.0-LTS/tutorial/actions.md new file mode 100644 index 0000000000..92586941e0 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tutorial/actions.md @@ -0,0 +1,31 @@ +--- +id: actions +title: Adding actions +--- + +# Adding actions + +ToolJet supports several actions that can be invoked as the handler for any `event` that is triggered in an application. + +## To add actions + +To attach an action for component events, click on the component's handle, and then click on the `Add handler` button on the +inspector panel available on the right side. + +To attach an action for query events, select the query, go to the `advanced` tab and then click on the `Add handler` button. + +## Available actions + +Some of the actions that ToolJet Support are + + Action| Description| + ----| ----------- | + Show alert | Show an alert message as a bootstrap toast | + Run query | Run any of the data queries that you have created | + Open webpage | Go to another webpage in a new tab | + Goto app | Go to another ToolJet application | + Show modal | Open any modal that you've added | + Close modal | Close any modal that you've added if its already open | + Copy to clipboard | Copy any available text that you see on the application to clipboard | + Set localStorage | Set a key and corresponding value to localStorage | + Generate file | Construct file using data available in your application and let the user download it | \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/tutorial/adding-a-datasource.md b/docs/versioned_docs/version-3.16.0-LTS/tutorial/adding-a-datasource.md new file mode 100644 index 0000000000..a8e2d9fb8e --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tutorial/adding-a-datasource.md @@ -0,0 +1,36 @@ +--- +id: adding-a-datasource +title: Adding a data source +--- + +# Adding a data source + +:::tip +The data sources are created on app level and not on workspace level. +::: + +**Datasource manager** is on the left-sidebar of the app builder. To add a new data source, click on the
`Add datasource` button. + + +adding datasource + + +You will be prompted to select the data source that you wish to add. Let's select PostgreSQL for this tutorial. You will then need to provide the credentials of your PostgreSQL database. The fields that are marked as `encrypted` will be encrypted before saving to ToolJet's database. + +
+ +![ToolJet - Tutorial - Adding a data source](/img/tutorial/adding-datasource/datasources.png) + +
+ +The name of the data source must be unique (within the app) and can be changed by clicking on the data source name at the top of the prompt. Click on `Test Connection` button to verify the connection, this might take a couple of minutes. Once verified, save the data source. + +:::tip +If you are using ToolJet cloud and if your data source is not publicly accessible, please white-list our IP address ( shown while creating a new data source ). +::: + +
+ +postgre add datasource + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/tutorial/adding-widget.md b/docs/versioned_docs/version-3.16.0-LTS/tutorial/adding-widget.md new file mode 100644 index 0000000000..f1e69e62ee --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tutorial/adding-widget.md @@ -0,0 +1,66 @@ +--- +id: adding-widget +title: Adding a widget +--- + +# Adding a widget + +To add a widget, navigate to the `Widget manager` on the right sidebar. It will display the list of built-in widgets that can be added to the app. Use the search functionality to quickly find the widget that you want. + +widget + +## Drag and drop a widget + +Let's add a `table` widget to the app to show the customer data from the query that we created in the previous steps. +To add a widget, drag and drop the widget to the canvas. + +## Resize a widget + +The widgets can be resized and repositioned within the canvas. + +resize + +## Adding widgets to Modal + +To add a widget to Modal, we need to trigger [Show modal action](/docs/tutorial/actions#available-actions) + +:::info +Before triggering `Show modal action` we need to add a modal widget to the canvas. +::: + +- Add a `modal widget` to the app +- Trigger the **Show modal action** +- Click on the canvas area for the `Widget manager` sidebar +- Navigate to the Widget manager on the right sidebar and Drag and drop a widget into the Modal + +adding-widget + +## Resize table columns + +We can resize the column width using the resize handle of the column. + +resize-table-column + +## Change widget properties + +Click on the widget to open the inspect panel on right sidebar. Here you can change the properties of the widgets. Let's configure the table columns to display the customer data. The display order of columns can be changed by dragging icon near the column name. + +inspect panel + +## Connecting data with widget + +Now we will connect the `data` object of the `fetch customers` query with the table. Click on the table widget to open the inspector on the right sidebar. We can see that the data property of the table has an empty array as the value. The data field, like almost every other field on the editor supports single-line javascript code within double brackets. Variable suggestions will be shown as a dropdown while you type the code in the field. + +Let's select the `data` object of the 'postgresql' query. + +` {{queries.postgresql1.data}}` + +Since we have already run the query in the previous step, the data will be immediately displayed in the table. + +table data + +So far in this tutorial, we have connected to a PostgreSQL database and displayed the data on a table. + +:::tip +Read the widget reference of table [here](/docs/widgets/table) for more customizations such as server-side pagination, actions, editing data. +::: diff --git a/docs/versioned_docs/version-3.16.0-LTS/tutorial/building-queries.md b/docs/versioned_docs/version-3.16.0-LTS/tutorial/building-queries.md new file mode 100644 index 0000000000..9598c2f9da --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tutorial/building-queries.md @@ -0,0 +1,53 @@ +--- +id: building-queries +title: Building Queries +--- + +# Building Queries + +Query Editor lives at the bottom of the page. We will now build a query for the PostgreSQL datasource that we connected in the previous step. + +:::tip +You can click on the 'enlarge' icon to enlarge query editor pane. +::: + +- Click on the `+` icon of the query editor to create a new query. +- Select the PostgreSQL datasource created in previous step. +- Copy the query given below and paste on the query area. +- Select SQL mode + +```sql +SELECT * FROM customers; +``` + + +query + + +Query results can be previewed by clicking the `preview` button. Previewing queries will not alter the state of the app. + + +preview + + + +## Advanced options + + +advanced options + + +#### Run query on page load +If this option is enabled, the query will be run when the app is loaded for the first time. The queries can have more than one trigger, ie the same query can later be triggered again using a button's click event or table's row selected event or any other events. + +#### Request confirmation before running query +Enable this option to show a prompt to confirm the action before a query is run. The confirmation prompt will look like this: + +
+ +confirm + +
+ +#### Show notification on success +Enable this option to show a custom message on query completion. Duration of the notification can also be set. diff --git a/docs/versioned_docs/version-3.16.0-LTS/tutorial/creating-app.md b/docs/versioned_docs/version-3.16.0-LTS/tutorial/creating-app.md new file mode 100644 index 0000000000..425ef29e39 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tutorial/creating-app.md @@ -0,0 +1,32 @@ +--- +id: creating-app +title: Creating new app +--- + +# Creating new app + +:::info +Apps in ToolJet binds the widgets, data sources and queries together. +::: + +This tutorial will walk you through building a simple app to fetch customer information from a PostgreSQL database and display the data using the table widget. +To create a new ToolJet app, click on the **'Create new application'** button on the ToolJet dashboard. + + +dashboard create new app + + +You will be redirected to the visual app editor once the app has been created. Create the first version of your app to start building. The name of the app can be changed by clicking on the app name at top-left of the app builder. + +
+ +![ToolJet - Creating an app](/img/tutorial/creating-new-app/visual-app-editor.png) + +
+ +The main components of an app: +an app: + +- **[Widgets](/docs/tutorial/adding-widget)** - UI components such as tables, buttons, dropdowns. +- **[Data sources](/docs/tutorial/adding-a-datasource)** - ToolJet can connect to databases, APIs and external services to fetch and modify data. +- **[Queries](/docs/tutorial/building-queries)** - Queries are used to access the connected data sources. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/tutorial/debugger.md b/docs/versioned_docs/version-3.16.0-LTS/tutorial/debugger.md new file mode 100644 index 0000000000..bc61761ba4 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tutorial/debugger.md @@ -0,0 +1,19 @@ +--- +id: debugger +title: Debugger +--- + +# Debugger + +The debugger captures errors that happens while running the queries. For example, when a database query fails due to the unavailability of a database or when a REST API query fails due to an incorrect URL, the errors will be displayed on the debugger. The debugger also displays relevant data related to the error along with the error message. Debugger is located on the left-sidebar. + + +debugger + + + +## Pin Debugger +You can click on the `pin` icon at the top-right corner of the debugger if you do not want the debugger to close. The debugger will remain open until it is unpinned. + + +pinned debugger diff --git a/docs/versioned_docs/version-3.16.0-LTS/tutorial/keyboard-shortcuts.md b/docs/versioned_docs/version-3.16.0-LTS/tutorial/keyboard-shortcuts.md new file mode 100644 index 0000000000..27e7ba0642 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tutorial/keyboard-shortcuts.md @@ -0,0 +1,25 @@ +--- +id: keyboard-shortcuts +title: Keyboard Shortcuts +--- + +# Keyboard Shortcuts + +You can perform operations like copying and pasting components, cloning components, deleting components, undo, redo, and more using keyboard shortcuts. + + +| Action | Mac Shortcut | Linux/Windows Shortcut | +|:------------|:-------------------|:-----------------------| +| Select all components | `cmd + a` | `ctrl + a` | +| Copy component | `cmd + c` | `ctrl + c` | +| Cut component | `cmd + x` | `ctrl + x` | +| Paste component | `cmd + v` | `ctrl + v` | +| Undo | `cmd + z` | `ctrl + z` | +| Redo | `cmd + shift + z` | `ctrl + shift + z` | +| Clone component | `cmd + d` | `ctrl + d` | +| Remove component | `delete` | `backspace` | +| Deselect component | `esc` | `esc` | +| Run Query | `cmd + enter` | `ctrl + enter` | +| Preview Query | `cmd + shift + enter` | `ctrl + shift + enter` | + +To choose several components at once within the app-builder, simply hold down the shift key while clicking on each component you want to select. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/tutorial/mobile-layout.md b/docs/versioned_docs/version-3.16.0-LTS/tutorial/mobile-layout.md new file mode 100644 index 0000000000..6d53baf5fe --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tutorial/mobile-layout.md @@ -0,0 +1,26 @@ +--- +id: mobile-layout +title: Mobile layout +--- + +# Mobile layout + +Mobile layout is activated when the width of the window is less than 600px. + +:::tip +Widgets can be shown on desktop, mobile, or both. +::: + + +mobile layout + + +## Adding existing widget to mobile layout +Click on the widget to open inspector. Scroll down to the `layout` section and enable mobile layout. The width of the widget will be adjusted to fit the mobile layout. + +## Adding a new widget to mobile layout +Switch the layout to mobile by clicking the button on the top navigation bar. Drag and drop a widget to the canvas. This widget will not be shown on desktop layout unless enabled from the widget inspector via the "Show on desktop" button manually. + +:::tip +Width of the widgets will be automatically adjusted to fit the screen while viewing the application in app viewer. +::: diff --git a/docs/versioned_docs/version-3.16.0-LTS/tutorial/sharing-and-deploying.md b/docs/versioned_docs/version-3.16.0-LTS/tutorial/sharing-and-deploying.md new file mode 100644 index 0000000000..244d3ea3fb --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tutorial/sharing-and-deploying.md @@ -0,0 +1,55 @@ +--- +id: sharing-and-deploying +title: Preview and Sharing Apps +--- + +# Preview and Sharing Apps + +## Preview + +Clicking on `Preview` will open up the currently opened version of the app in the new tab. This is useful if you want to immediately check the app in production. + + +preview + +## Sharing an app + +Once you have released a version of your app, you can share the app with others using a customized url. To share an app: + +- Click on the **Share** button on the top-right corner + +
+ + +share + + +
+ +- In the dialog box, turn on the toggle switch to `Make the application public` and shareable + +
+ + +toggle + + +
+ +- Create your own `customised URL` for the app and click on `copy` to copy the URL + +
+ +url + + +
+ +- You can also `Embed` your application using the embeddable link + +
+ +embed + + +
diff --git a/docs/versioned_docs/version-3.16.0-LTS/tutorial/versioning-and-release.md b/docs/versioned_docs/version-3.16.0-LTS/tutorial/versioning-and-release.md new file mode 100644 index 0000000000..4bae42f7a6 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/tutorial/versioning-and-release.md @@ -0,0 +1,112 @@ +--- +id: versioning-and-release +title: Versioning and Release +--- + +# Versioning and Release + +Versioning and Release lets you version control your apps and release app changes to the users. + +
+ +## Versioning + +Versioning is really useful if multiple developers are working on an app, it allows them to save their own version of the app. This also prevents developers from overwriting the other developer's work. + +
+ +
+ +### Creating a Version + +You can create new versions from **App Version Manager** on the top-right corner. It displays the version of the app that you're currently working and can be used to switch between the different version of the app. To create a new version: + +- Go to the **App Version Manager** from the toolbar and click on the dropdown. It will display all the versions of the app that have been created. The released version name will be in green color. +
+ + app version + +
+ +- Click on **Create new version** button present at the bottom of the dropdown and a modal will pop-up. Enter a **Version Name** and click on **Create version from** dropdown that will include all the versions of the app, choose a version from the dropdown that you want to use for your new version or ToolJet will automatically select the last created version, and then click on `Create new Version` button to add a new version. +
+ + modal + +
+ +
+ +
+ +### Renaming a Version + +If you want to change the name of an app version, navigate to the **version manager** and select the version you wish to rename. From there, you can click on the rename button located beside the version name. This will open a modal where you can modify the version name to your desired choice. + +
+ +version dropdown + +
+ +
+ +
+ +### Deleting a Version + +If you want to remove an app version, go to the **version manager** and locate the version you wish to delete from the dropdown menu. Next to the version, you will find a delete icon. Click on it to initiate the deletion process. + +
+ +version dropdown + +
+ +
+ +
+ +## Release + +Making a release let's you publish the app and push the changes to production. + +### Releasing a Version + +To release a version: + +- Go to the **App Version Manager** and select the `version` from the dropdown that you want to release. +
+ + version dropdown + +
+ +- Click on the `Release` button on the top-right corner. +
+ + release + +
+ +- A confirmation dialog will popup that prompts you to decide whether to release the current version of the app. Clicking on the **Release** button will release the current version of the app. +
+ + release + +
+ + +:::caution +- When an app is made **Public** without being released, it functions similarly to previewing the application. This means that the version that is loaded when accessing the app through its Public app URL will be the same version of the app currently loaded in the app builder. + +- To prevent the unintended publishing of an unfinished app, ToolJet will prompt you to create a new version for making any edits to the `Released version` of an app. Editing of the `Released version` will be blocked until a new version is created. + +
+ +release + +
+::: + +
\ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/user-management/authentication/cloud-login.md b/docs/versioned_docs/version-3.16.0-LTS/user-management/authentication/cloud-login.md new file mode 100644 index 0000000000..1be8cad8d4 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/user-management/authentication/cloud-login.md @@ -0,0 +1,56 @@ +--- +id: cloud-login +title: Cloud Authentication +--- + +In cloud deployment, you can setup the authentication on your workspaces and is managed by the Admins of the respective groups. Each workspace can have different Authentication method. We will learn about the available Authentication methods in this documentation. + + +### Configuration + +To configure the authentication: + +1. Go to **Workspace Settings** > **Workspace login**. (Example URL - `https://app.corp.com/nexus/workspace-settings/workspace-login`) + +2. On this page, you can configure the following settings: + +cloud workspace level login + + +### SSO (Single Sign-On) + + * SSO makes it easier for organizations to manage user access. Users can use one login for different tools, and admins can quickly add or remove access when needed. Thus, it improves an organization's onboarding and offboarding experience. + + * You can configure SSO with Google, GitHub, OpenID Connect, LDAP, and SAML. Please check the [SSO docs](/docs/user-management/sso/overview) for a detailed guide on SSO configuration. + + +### Default SSO (Single Sign-On) + * ToolJet supports preconfigured Google and GitHub as default SSO options, which can be easily enabled from the workspace login page. + + +### Allowed Domains + + * This feature helps restrict login access to specific email domains, ensuring that only authorized users from your organization can sign up or log in. + + * You can add multiple domains for login by specifying allowed domain names, separated by commas. **Example:** `corp.com`, `corp.io`, `corp.ai` + + +### Sign-Up Without Invitations + + * This feature allows organizations to simplify onboarding by letting users sign up without needing an invitation. + + * The **Enable Signup** feature lets users create accounts without being invited. + + * When users sign up with this feature enabled, they are assigned to the end user of that workspace. Workspace admin can later change the [role](/docs/user-management/role-based-access/user-roles) of the user once the user is on-boarded to the workspace. + +### Password Login + + * Password login allows users to log in using their email and password. However, organizations can also use SSO for better security and control. + + * Toggle this setting to **enable** or **disable** password login on the login page. Make sure to disable password login only when your SSO is configured otherwise, you will get locked out. + +### Automatic SSO Login + + * This feature eliminates the need for users to interact with the login page by directly authenticating them via the configured SSO provider. + + * To Enable the Automatic SSO Login, ensure the password login is disabled and only one SSO provider is configured. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/user-management/authentication/self-hosted/instance-login.md b/docs/versioned_docs/version-3.16.0-LTS/user-management/authentication/self-hosted/instance-login.md new file mode 100644 index 0000000000..e1fedab00f --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/user-management/authentication/self-hosted/instance-login.md @@ -0,0 +1,76 @@ +--- +id: instance-login +title: Instance Login +--- + +In self-hosted deployments, it can be configured at two levels: **Instance Level**, which applies globally across all workspaces and is configurable only by the super admin, and **Workspace Level**, which overrides the instance-level settings for specific workspaces and can be configured by both super admins and workspace admins. This guide focuses on configuring instance-level authentication. + +### Configuration + +To configure the instance-level authentication configuration + +1. Go to **Settings** > **Instance login**. (Example URL - `https://app.corp.com/instance-settings/instance-login`) + +2. On this page, you can configure the following settings: + +only instance level login + +### SSO (Single Sign-On) + +- SSO makes it easier for organizations to manage user access. Users can use one login for different tools, and admins can quickly add or remove access when needed. Thus, it improves an organization's onboarding and offboarding experience. + +- At the instance level you can configure SSO with Google, GitHub, and OpenID Connect. Please check the [SSO docs](/docs/user-management/sso/overview) for a detailed guide on SSO configuration. + +- You can also configure the Google or Github with Environment Variables. To set Google as default SSO use the following environment variable. + + | Variable | Description | + | --------- |:-----:| + | SSO_GOOGLE_OAUTH2_CLIENT_ID | Google OAuth client id | + +- To set GitHub as the default SSO use the following environment variables: + + | Variable | Description | + | --------- |:-----:| + | SSO_GIT_OAUTH2_CLIENT_ID | GitHub OAuth client ID | + | SSO_GIT_OAUTH2_CLIENT_SECRET | GitHub OAuth client secret | + | SSO_GIT_OAUTH2_HOST | GitHub OAuth host name if GitHub is self-hosted | + + +### Allowed Domains + +- This feature helps restrict login access to specific email domains, ensuring that only authorized users from your organization can sign up or log in. + +- You can add multiple domains for login by specifying allowed domain names, separated by commas. **Example:** `corp.com`, `corp.io`, `corp.ai` + + +### Sign-Up Without Invitations + +- This feature allows organizations to simplify onboarding by letting users sign up without needing an invitation. + +- The **Enable Signup** feature lets users create accounts without being invited. + +- This feature is available only when the Personal Workspace option is enabled in the Manage Instance settings. When users sign up with this feature enabled, a new personal workspace is automatically created for them, and they are assigned as the admin of that workspace. Refer to [Sign-Up Documentation](/docs/user-management/onboard-users/self-signup-user#enable-sign-up-at-instance-level) to learn more. + +### Password Login + +- Password login allows users to log in using their email and password. However, organizations can also use SSO for better security and control. + +- Toggle this setting to **enable** or **disable** password login on the login page. Make sure to disable password login only when your SSO is configured otherwise, you will get locked out. + +### Enable Workspace Login Configuration + +- This feature allows workspace admins to customize login settings for their specific workspaces. It is useful when different workspaces in the same instance require distinct login configurations. + +- Once enabled, workspace-specific settings will override the instance-level configuration for those workspaces. + +### Automatic SSO Login + +- This feature eliminates the need for users to interact with the login page by directly authenticating them via the configured SSO provider. + +- To Enable the Automatic SSO Login, ensure the password login is disabled and only one SSO provider is configured. + +### Custom Logout URL + +- A Custom Logout URL allows organizations to redirect users to a specific page after they log out. This can be useful for redirecting users to a company portal or a feedback form. + +- Enter the desired logout URL in theΒ **Custom Logout URL**Β field to configure this. \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/user-management/authentication/self-hosted/overview.md b/docs/versioned_docs/version-3.16.0-LTS/user-management/authentication/self-hosted/overview.md new file mode 100644 index 0000000000..c07c2455da --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/user-management/authentication/self-hosted/overview.md @@ -0,0 +1,61 @@ +--- +id: overview +title: Overview +--- + +Authentication in ToolJet ensures secure access to your applications and data.In self-hosted deployments, authentication can be configured at two levels: + +- **Instance Level:** Applies globally across all workspaces within the instance. Only the super admin can configure this. + +- **Workspace Level:** Overrides instance-level configuration for workspaces where it is applied. Both super admins and workspace admins can configure it. + + +## Scenarios for Authentication Configuration + +ToolJet supports flexible authentication setups, allowing instance-level, workspace-level, or a mix of both configurations. You can configure [SSO](/docs/user-management/sso/overview) or email-password login at both the levels. Below are common scenarios to guide your setup. + +### 1\. Only Instance-Level Login + +Instance-level login configuration is a global setting that applies across all workspaces within a ToolJet instance. + + +**Example:** Imagine a company, Nexus Corp, that wants to build internal application with ToolJet for three departments: Marketing, Sales, and Engineering. To ensure better collaboration, they need to isolate the applications and data sources for each department. Since all these departments use the same login system as they belong to the same company, an instance-level configuration is suitable setup for this scenario. Here’s how this can be set up: + +- Create three workspacesβ€”one for each department: Marketing, Sales, and Engineering. This ensures the applications and data sources for each department remain isolated. + +- Since all workspaces belong to a single instance of the company, configure authentication at the instance level. For example, if the company uses Google Workspace, they can configure Google SSO at the instance level. + +- This allows users across all workspaces to log in using the same authentication system. + +only instance level login + + +### 2\. Only Workspace-Level Login + +Workspace-level login allows individual workspaces to define their own authentication configurations, overriding the global instance-level settings. This approach is ideal for organizations with diverse authentication needs across departments or teams. + + +**Example** Consider a service-based company, Pixel Technologies Inc., that serves three client companies: GreenTech Ltd., BlueWave Corp., and EcoBuild Enterprises. To provide customized solutions, Tech Solutions Inc. have to isolate applications, users and datasource and access control configuration for each client company. In this scenario, service-based company can do the following setup: + +- Create a workspace for each client company: GreenTech Ltd., BlueWave Corp., and EcoBuild Enterprises. This ensures the applications and data sources for each client remain isolated. + +- Configure individual workspace-level login settings for each workspace. For example, GreenTech Ltd may use Google SSO, BlueWave Corp. may prefer Azure AD, and EcoBuild Enterprises might us both SAML SSO and a custom email-password authentication system. + +only instance level login + +### 3\. Instance-Level and Workspace-Level Login (Mixed Configuration) + +In this setup, some workspaces inherit the instance-level configuration, while others override it with workspace-specific login settings. + + +**Example** Consider a large company, Global Dynamics Ltd., with three departments: Marketing, Engineering, and HR. To ensure better collaboration, they need to isolate the applications and data sources for each department. Global Dynamics Ltd. wants to maintain a separate login for the applications related to the HR department to comply with strict security and compliance requirements. For the other departments, they prefer to use a common authentication at the instance level. + +In such scenarios where company wants to implement a mixed authentication configuration, they can do the following setup. + +- Create three workspacesβ€”one for each department: Marketing, Engineering, and HR. This ensures the applications and data sources for each department remain isolated. + +- The Marketing and Engineering workspaces can inherit the instance-level configuration. For instance, they use Google OAuth configured at instance level. + +- The HR workspace, due to compliance and security policies, requires isolated login settings. Thus configures workspace-level login settings, such as SAML authentication, which will override the instance level configuration. + +only instance level login \ No newline at end of file diff --git a/docs/versioned_docs/version-3.16.0-LTS/user-management/authentication/self-hosted/pat.md b/docs/versioned_docs/version-3.16.0-LTS/user-management/authentication/self-hosted/pat.md new file mode 100644 index 0000000000..2348b619d7 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/user-management/authentication/self-hosted/pat.md @@ -0,0 +1,108 @@ +--- +id: pat +title: Personal Access Token +--- + +You can seamlessly and securely embed your ToolJet applications inside customer portals, internal dashboards, and third-party systems, without requiring full user authentication flows. + +With Personal Access Tokens (PATs), ToolJet enables secure, scoped, and session-isolated access to embedded applications. Each token is tied to a specific user and application, allowing you to control exactly who can access what, and for how long, all without interfering with your main ToolJet session. + +## Key Benefits +- **Embed without friction**: Load applications inside iframes instantly, no login prompts or redirects. +- **Scoped access**: Tokens are application and user-specific, ensuring proper scoped access. +- **Session isolation**: Embedded sessions don’t interfere with regular ToolJet usage. +- **Expiration control**: Define how long each token and session should stay valid. +- **Workspace-level compatibility**: Extend PAT usage across workspace when needed. + +## When to Use PAT + +Use Personal Access Tokens when you want to: +- Embed ToolJet apps into customer-facing portals without requiring login. +- Integrate ToolJet apps into third-party systems, CRMs, or internal dashboards. +- Deliver multi-tenant SaaS interfaces with strict access control per user. +- Build secure public dashboards with time-bound, scoped access. +- Maintain session isolation between embedded apps and primary ToolJet usage. + +## Generate PAT + +To create a Personal Access Token for a specific app-user combination, you can use the following endpoint: + +```swift +POST /api/ext/users/personal-access-token +``` +**Required Parameters** + +| Field | Type | Description | +|:--------------- |:------ |:---------------------------------------- | +| `email` | string | Email of the user | +| `appId` | string | App ID to which the PAT should be scoped | +| `sessionExpiry` | number | Session duration in minutes | +| `patExpiry` | number | Token validity in seconds | + +**cURL Request Example** + +```js +curl --location 'http://localhost:3000/api/ext/users/personal-access-token' \ +--header 'Authorization: Basic ' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "email": "a1@tooljet.com", + "appId": "8ba8bf0e-6b8f-4e07-abb9-6fd2d816fabc", + "sessionExpiry": 60, + "patExpiry": 1000000 +}' +``` + +
+Example Response +```js +{ + "personalAccessToken": "pat_469ed9...1a8b597", + "redirectUrl": "http://localhost:8082/embed-apps/8ba8bf0e...?personal-access-token=pat_469ed9..." +} +``` +
+ +## Embed the App + +Use the returned **redirectUrl** inside an `