mirror of
https://github.com/ToolJet/ToolJet
synced 2026-05-06 06:48:21 +00:00
Merge branch 'ToolJet:develop' into develop
This commit is contained in:
Hisham Akmal
GitHub
commit
34b2852a6f
15 changed files with 551 additions and 447 deletions
|
|
@ -11,563 +11,354 @@ import TabItem from '@theme/TabItem';
|
|||
|
||||
The GitSync feature enables synchronization of workspace applications with a git repository, streamlining application management and version control on ToolJet.
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
<div style={{paddingTop:'24px'}}>
|
||||
|
||||
## Overview
|
||||
|
||||
ToolJet applications can be synchronized with a Git repository, offering the flexibility to tailor your application development and deployment processes across various environments while aligning with best practices for the application development lifecycle.
|
||||
|
||||
</div>
|
||||
#### Key Use-Cases
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
|
||||
### Key Use-Cases:
|
||||
|
||||
#### Backup of Apps
|
||||
**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.
|
||||
|
||||
#### Environment Migration
|
||||
**Environment Migration**
|
||||
|
||||
Facilitating the movement of applications across different ToolJet deployments (e.g., from development to staging to production), GitSync acts as a pivotal tool for environment migration. Users can effortlessly transfer their applications across environments by pushing changes to a Git repository.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/envmigration.png" alt="GitSync" />
|
||||
</div>
|
||||
|
||||
<br/>
|
||||
<img className="screenshot-full" src="/img/gitsync/envmigration.png" alt="GitSync" />
|
||||
|
||||
</div>
|
||||
|
||||
<div style={{paddingTop:'24px'}}>
|
||||
|
||||
## Setting up GitSync
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="GitHub" label="Setting up GitSyncing with GitHub">
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
|
||||
## Setting up GitSyncing with GitHub
|
||||
|
||||
:::caution
|
||||
:::info
|
||||
- ToolJet support git repo managers like GitHub, GitLab, Bitbucket, AWS CodeCommit, and Azure Repos.
|
||||
- Only Admins have the permission to configure the GitSync feature on workspace level.
|
||||
- The default branch name for the git repository should be `master`.
|
||||
- The default branch name for the git repository should be **master**.
|
||||
:::
|
||||
|
||||
### Step 1: Create a new repository on GitHub
|
||||
### 1. Create a New Repository
|
||||
|
||||
Create a new repository on GitHub. The repository can be public or private. You can also use an existing repository. Make sure that the repository is empty.
|
||||
Create a new repository on your git repo manager. The repository can be public or private. You can also use an existing repository. **Make sure that the repository is empty.**
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/github1.png" alt="GitSync" />
|
||||
</div>
|
||||
<Tabs>
|
||||
|
||||
### Step 2: Obtain the repository URL
|
||||
<TabItem value="GitHub" label="GitHub">
|
||||
|
||||
Obtain the **SSH URL** of the repository. When a repository is created, GitHub shows a screen with the repository URL. If the repository is already created, you can obtain the URL by clicking on the **Clone or download** button.
|
||||
<img className="screenshot-full" src="/img/gitsync/github1.png" alt="GitSync" />
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/github2.png" alt="GitSync" />
|
||||
</div>
|
||||
</TabItem>
|
||||
|
||||
### Step 3: Configure the GitSync feature on ToolJet
|
||||
<TabItem value="GitLab" label="GitLab">
|
||||
|
||||
Go to the **Workspace settings**, and click on the **Configure git** tab.
|
||||
Enter the **SSH URL** of the repository (obtained in Step 2) in the **Git repository URL** field. 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.
|
||||
<img className="screenshot-full" src="/img/gitsync/gitlab/repo.png" alt="GitSync" />
|
||||
|
||||
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. Older VCS providers like Bitbucket recommend using this key type.
|
||||
</TabItem>
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/ssh2-v2.png" alt="GitSync" />
|
||||
</div>
|
||||
</Tabs>
|
||||
|
||||
### Step 4: Deploy the SSH key to GitHub repository
|
||||
### 2. Obtain the Repository URL
|
||||
|
||||
Go to the **Settings** tab of the GitHub repository that you created in Step 1, and click on the **Deploy keys** tab. Click on the **Add deploy key** button.
|
||||
Obtain the **SSH URL** of your repository.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/github3.png" alt="GitSync" />
|
||||
</div>
|
||||
<Tabs>
|
||||
|
||||
Enter a title for the SSH key in the **Title** field. Paste the SSH key that you copied in Step 3 in the **Key** field. Make sure that the **Allow write access** checkbox is checked, especially when configuring the GitSync feature to [push changes to Git](#pushing-changes-to-git-repo). However, it is not mandatory to check this option when setting up the GitSync feature for [pulling changes from Git](#pulling-changes-from-git-repo). Finally, click on the **Add key** button.
|
||||
<TabItem value="GitHub" label="GitHub">
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/github4.png" alt="GitSync" />
|
||||
</div>
|
||||
When a repository is created, GitHub shows a screen with the repository URL. If the repository is already created, you can obtain the URL by clicking on the **Clone or download** button.
|
||||
<img className="screenshot-full" src="/img/gitsync/github2.png" alt="GitSync" />
|
||||
|
||||
### Step 5: Finish the GitSync configuration on ToolJet
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="GitLab" label="GitLab">
|
||||
|
||||
On GitLab, you can obtain the URL by clicking on the **Clone** button and selecting the **SSH** option.
|
||||
<img className="screenshot-full" src="/img/gitsync/gitlab/gitlabssh.png" alt="GitSync" />
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
### 3. Configure the GitSync Feature on ToolJet
|
||||
|
||||
1. Go to the **Workspace settings**, and click on the **Configure git** tab.
|
||||
|
||||
<img className="screenshot-full" src="/img/gitsync/gitsync.png" alt="GitLab Repo" />
|
||||
|
||||
2. Enter the **SSH URL** of the repository (obtained in [Step 2](#2-obtain-the-repository-url)) in the **Git repo URL** field.
|
||||
3. 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.
|
||||
|
||||
<img className="screenshot-full" src="/img/gitsync/ssh2-v2.png" alt="GitSync" />
|
||||
|
||||
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. Older VCS providers like Bitbucket recommend using this key type.
|
||||
|
||||
<img style={{marginBottom:'15px'}} className="screenshot-full" src="/img/gitsync/ssh2.png" alt="GitSync" />
|
||||
|
||||
### 4. Deploy the SSH Key
|
||||
|
||||
<Tabs>
|
||||
|
||||
<TabItem value="GitHub" label="GitHub">
|
||||
|
||||
Follow the following steps to deploy the SSH key to GitHub Repository:
|
||||
|
||||
1. Go to the **Settings** tab of the GitHub repository that you created in [Step 1](#1-create-a-new-repository), and click on the **Deploy keys** tab. Click on the **Add deploy key** button.
|
||||
|
||||
<img className="screenshot-full" src="/img/gitsync/github3.png" alt="GitSync" />
|
||||
|
||||
2. Enter a title for the SSH key in the **Title** field.
|
||||
3. Paste the SSH key that you copied in [Step 3](#3-configure-the-gitsync-feature-on-tooljet) in the **Key** field.
|
||||
4. Make sure that the **Allow write access** checkbox is checked, especially when configuring the GitSync feature to [push changes to Git](#pushing-changes-to-git-repo). However, it is not mandatory to check this option when setting up the GitSync feature for [pulling changes from Git](#pulling-changes-from-git-repo).
|
||||
5. Finally, click on the **Add key** button.
|
||||
|
||||
<img className="screenshot-full" src="/img/gitsync/github4.png" alt="GitSync" />
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="GitLab" label="GitLab">
|
||||
|
||||
You have two options to add the SSH key to GitLab, depending on your needs:
|
||||
|
||||
#### 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.
|
||||
|
||||
<img className="screenshot-full" src="/img/gitsync/gitlab/addingssh.png" alt="GitLab SSH Key" />
|
||||
|
||||
3. In the **Key** field, paste the SSH key you generated in [Step 3](#3-configure-the-gitsync-feature-on-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.
|
||||
|
||||
<img style={{marginBottom:'15px'}} className="screenshot-full" src="/img/gitsync/gitlab/activessh.png" alt="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.
|
||||
|
||||
<img className="screenshot-full" src="/img/gitsync/gitlab/deploy-keys.png" alt="GitLab Deploy Key" />
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
### 5. Finish the GitSync Configuration on ToolJet
|
||||
|
||||
Go back 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.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/finalize-ssh2-configuration-v2.png" alt="GitSync" />
|
||||
</div>
|
||||
<br/>
|
||||
<img className="screenshot-full" src="/img/gitsync/finalize-ssh2-configuration-v2.png" alt="GitSync" />
|
||||
|
||||
</div>
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
<div style={{paddingTop:'24px'}}>
|
||||
|
||||
## Auto-commit on Promoting Environment
|
||||
|
||||
When you promote an environment, from **Developement to Staging**, the changes will be automatically committed to the git repository. The commit message will be `<version_number> Version of <app_name> promoted from <source_environment> to <destination_environment>`. 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.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/promoted.png" alt="GitSync" />
|
||||
</div>
|
||||
<br/>
|
||||
<img className="screenshot-full" src="/img/gitsync/promoted.png" alt="GitSync" />
|
||||
|
||||
This option can be enabled or disabled from the **Configure git** tab on the **Workspace settings** page. By default, this option is disabled.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/autocommit-v2.png" alt="GitSync" />
|
||||
</div>
|
||||
<br/>
|
||||
<img className="screenshot-full" src="/img/gitsync/autocommit-v2.png" alt="GitSync" />
|
||||
|
||||
</div>
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
<div style={{paddingTop:'24px'}}>
|
||||
|
||||
## 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.
|
||||
|
||||
**When enabled**
|
||||
#### When Enabled
|
||||
|
||||
On clicking the GitSync button, the users will be able to commit changes to the git repository.
|
||||
|
||||
**When disabled**
|
||||
1. For 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.
|
||||
2. For admin users: The users will see a dialogue box with a link to configure the GitSync feature.
|
||||
#### When Disabled
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/connect-v2.png" alt="GitSync" />
|
||||
</div>
|
||||
<br/>
|
||||
1. **For 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.
|
||||
2. **For admin users**: The users will see a dialogue box with a link to configure the GitSync feature.
|
||||
|
||||
<img className="screenshot-full" src="/img/gitsync/connect-v2.png" alt="GitSync" />
|
||||
|
||||
</div>
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
<div style={{paddingTop:'24px'}}>
|
||||
|
||||
## 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.
|
||||
|
||||
**Note:**
|
||||
- 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.
|
||||
**Note:** 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.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/deleteconfig-v2.png" alt="GitSync" />
|
||||
</div>
|
||||
<br/>
|
||||
<img className="screenshot-full" src="/img/gitsync/deleteconfig-v2.png" alt="GitSync" />
|
||||
|
||||
</div>
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
<div style={{paddingTop:'24px'}}>
|
||||
|
||||
## Git Repo
|
||||
|
||||
Once the initial commit is made, you can see the app files in the git repository. The repository will have the individual app folders and a **.meta** folder. The app folders will be named as the app name and will have the respective **JSON** file of the application. The **.meta** folder will have the `meta.json` file that contains the meta information of each application synced to git repo.
|
||||
Once the initial commit is made, you can see the app files in the git repository. The repository will have the individual app folders and a **.meta** folder. The app folders will be named as the app name and will have the respective **JSON** file of the application. The **.meta** folder will have the **meta.json** file that contains the meta information of each application synced to git repo.
|
||||
|
||||
The **meta.json** file holds information about apps such as the **App name**, **last commit message**, **last commit user**, **last commit date**, **version name**, and **version id**.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/gitcommit.png" alt="GitSync" />
|
||||
</div>
|
||||
<br/>
|
||||
<Tabs>
|
||||
|
||||
<TabItem value="GitHub" label="GitHub">
|
||||
|
||||
<img className="screenshot-full" src="/img/gitsync/gitcommit.png" alt="GitSync" />
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="GitLab" label="GitLab">
|
||||
|
||||
<img className="screenshot-full" src="/img/gitsync/gitlab/firstcommit.png" alt="GitSync" />
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
</div>
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
<div style={{paddingTop:'24px'}}>
|
||||
|
||||
## Pushing Changes to Git Repo
|
||||
|
||||
Once the GitSync feature is configured, you can start pushing changes to the git repository.
|
||||
|
||||
### App Creation
|
||||
#### App Creation
|
||||
|
||||
When 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.
|
||||
When 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.
|
||||
|
||||
:::info
|
||||
If the app name is same as the name of the existing app in the git repo, it will overwrite the existing app in the git repo.
|
||||
:::
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/commitchanges-v2.png" alt="GitSync" />
|
||||
</div>
|
||||
<br/>
|
||||
<img className="screenshot-full" src="/img/gitsync/commitchanges.png" alt="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.
|
||||
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.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/firstcommit.png" alt="GitSync" />
|
||||
</div>
|
||||
<br/>
|
||||
<Tabs>
|
||||
|
||||
### App Rename
|
||||
<TabItem value="GitHub" label="GitHub">
|
||||
|
||||
<img className="screenshot-full" src="/img/gitsync/firstcommit.png" alt="GitSync" />
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="GitLab" label="GitLab">
|
||||
|
||||
<img className="screenshot-full" src="/img/gitsync/gitlab/author.png" alt="GitSync" />
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
#### 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.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/rename.png" alt="GitSync" />
|
||||
</div>
|
||||
<br/>
|
||||
<Tabs>
|
||||
|
||||
### App Updates
|
||||
<TabItem value="GitHub" label="GitHub">
|
||||
|
||||
<img className="screenshot-full" src="/img/gitsync/rename.png" alt="GitSync" />
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="GitLab" label="GitLab">
|
||||
|
||||
<img className="screenshot-full" src="/img/gitsync/gitlab/apprename.png" alt="GitSync" />
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
#### App Updates
|
||||
|
||||
Whenever a user makes a change in an app, they can make a commit to the git repository by clicking on the **GitSync** button on the topbar. On clicking the **GitSync** button, a modal will open with the option to enter the commit message. The user can 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 connnected **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.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/modalgit.png" alt="GitSync" />
|
||||
</div>
|
||||
<br/>
|
||||
<img className="screenshot-full" src="/img/gitsync/gitlab/message.png" alt="GitLab SSH Key" />
|
||||
|
||||
Once the changes are committed, the user can see the commit message, author, and date in the git repository.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/commitgitsync.png" alt="GitSync" />
|
||||
</div>
|
||||
<br/>
|
||||
<Tabs>
|
||||
|
||||
### App Deletion
|
||||
<TabItem value="GitHub" label="GitHub">
|
||||
|
||||
<img className="screenshot-full" src="/img/gitsync/commitgitsync.png" alt="GitSync" />
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="GitLab" label="GitLab">
|
||||
|
||||
<img className="screenshot-full" src="/img/gitsync/gitlab/lastcommitmsg.png" alt="GitSync" />
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
#### App Deletion
|
||||
|
||||
Whenever a user deleted 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.
|
||||
|
||||
### App Version Update
|
||||
#### App Version Update
|
||||
|
||||
Whenever a user creates a new app version and creates a commit to git repository, the **JSON** file in the app folder will be replaced with the new version of the app that was created. The **meta.json** file in the **.meta** folder will also be updated with the new version id and version name.
|
||||
When a user creates a new version of an app, there will be an option to select the **Commit changes**. If you select the **commit changes** option, the new version of the app will be committed to the git repository.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/replace.png" alt="GitSync" />
|
||||
</div>
|
||||
<br/>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
## Pulling Changes from Git Repo
|
||||
|
||||
You can configure the GitSync feature on another workspace to pull the changes from the git repository. To configure the GitSync feature on another workspace, follow the steps mentioned in the [Setting up GitSyncing with GitHub](#setting-up-gitsyncing-with-github) section.
|
||||
|
||||
Once the GitSync feature is configured, go to the ToolJet dashboard and click on the three dots on the right side of the **Create new app** button. Click on the **Import from git repository** option.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/importgit-v2.png" alt="GitSync" />
|
||||
</div>
|
||||
<br/>
|
||||
|
||||
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.
|
||||
|
||||
:::caution
|
||||
- The app imported from the git repository cannot be edited.
|
||||
- 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.
|
||||
:::
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/importmodal-v2.png" alt="GitSync" />
|
||||
</div>
|
||||
<br/>
|
||||
|
||||
### Checking for Updates
|
||||
|
||||
You can check for updates in the git repository by clicking on the **GitSync** button on the topbar. On clicking the **GitSync** button, a modal will open with the option to **Check for updates**. 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. Click on the **Pull changes** button to pull the changes from the git repository.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/updatecheck.png" alt="GitSync" />
|
||||
</div>
|
||||
<br/>
|
||||
|
||||
</TabItem>
|
||||
|
||||
|
||||
<TabItem value="GitLab" label="Setting up GitSyncing with GitLab">
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
|
||||
## Setting up GitSyncing with GitLab
|
||||
|
||||
:::caution
|
||||
- ToolJet support git repo managers like GitHub, GitLab, Bitbucket, AWS CodeCommit, and Azure Repos.
|
||||
- Only Admins have the permission to configure the GitSync feature on workspace level.
|
||||
- The default branch name for the git repository should be `master`.
|
||||
:::
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
|
||||
### Step 1: Create a new repository
|
||||
|
||||
Create a new repository on GitLab. The repository can be public or private. You can also use an existing repository. **Make sure that the repository is empty**.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/gitlab/repo.png" alt="GitLab Repo" />
|
||||
</div>
|
||||
<br/>
|
||||
|
||||
</div>
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
|
||||
### Step 2: Obtain the repository URL
|
||||
|
||||
Obtain the **SSH URL** of the repository. On GitLab, you can obtain the URL by clicking on the **Clone** button and selecting the **SSH** option.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/gitlab/gitlabssh.png" alt="GitLab Repo" />
|
||||
</div>
|
||||
<br/>
|
||||
|
||||
</div>
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
|
||||
### Step 3: Configure the GitSync feature on ToolJet
|
||||
|
||||
Go to the **Workspace settings**, and click on the **Configure git** tab.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/gitsync.png" alt="GitLab Repo" />
|
||||
</div>
|
||||
<br/>
|
||||
|
||||
Enter the **SSH URL** of the repository (obtained in Step 2) in the **Git repository URL** field. 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 gitlab repository.
|
||||
|
||||
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. Older VCS providers like Bitbucket recommend using this key type.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/ssh2.png" alt="GitLab Repo" />
|
||||
</div>
|
||||
<br/>
|
||||
|
||||
</div>
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
|
||||
### Step 4: Deploy the SSH key to GitLab
|
||||
|
||||
Now, let's add the SSH key to GitLab. You have two options, depending on your needs:
|
||||
|
||||
Option 1: Add as a user-wide SSH key (for access to all your repositories)
|
||||
|
||||
- Click on your avatar in the top-left corner and select **Edit Profile**.
|
||||
- Navigate to the **SSH Keys** tab and click the **Add new key** button.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/gitlab/addingssh.png" alt="GitLab SSH Key" />
|
||||
</div>
|
||||
<br/>
|
||||
|
||||
- In the **Key** field, paste the SSH key you generated in ToolJet's Configure Git tab during the previous step..
|
||||
- Give your key a descriptive title.
|
||||
- Set **Usage type** to **Authentication & signing**.
|
||||
- Optionally, set an expiration date.
|
||||
- Click **Add key** to save.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/gitlab/activessh.png" alt="GitLab SSH Key" />
|
||||
</div>
|
||||
<br/>
|
||||
|
||||
Option 2: Add as a deploy key (for access to a specific repository only)
|
||||
|
||||
- Navigate to the repository you want to add the key to.
|
||||
- Click on the **Settings** tab and select **Repository**.
|
||||
- Once you are in the **Repository Settings**, expand the **Deploy Keys** section.
|
||||
- Click on the **Add new deploy key** button.
|
||||
- Give your key a descriptive title.
|
||||
- In the **Key** field, paste the SSH key you generated in ToolJet's Configure Git tab during the previous step.
|
||||
- Enable the **Grant write permissions to this key** checkbox. We need this permission to push changes to the repository.
|
||||
- Click **Add key** to save.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/gitlab/deploy-keys.png" alt="GitLab Deploy Key" />
|
||||
</div>
|
||||
<br/>
|
||||
|
||||
</div>
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
|
||||
### Step 5: Finish the GitSync configuration on ToolJet
|
||||
|
||||
Go back 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.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/gitlab/configfin.png" alt="GitLab SSH Key" />
|
||||
</div>
|
||||
<br/>
|
||||
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
## Auto-commit on promoting environment
|
||||
|
||||
When you promote an environment, from **Developement to Staging**, the changes will be automatically committed to the git repository. The commit message will be `<version_number> Version of <app_name> promoted from <source_environment> to <destination_environment>`. 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.
|
||||
|
||||
This option can be enabled or disabled from the **Configure git** tab on the **Workspace settings** page. By default, this option is disabled.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{ border:'0', marginBottom:'15px', borderRadius:'5px', boxShadow: '0px 1px 3px rgba(0, 0, 0, 0.2)' }} className="screenshot-full" src="/img/gitsync/autocommit.png" alt="GitSync" />
|
||||
</div>
|
||||
<br/>
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
|
||||
## 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.
|
||||
|
||||
**When enabled**
|
||||
|
||||
On clicking the GitSync button, the users will be able to commit changes to the git repository.
|
||||
|
||||
**When disabled**
|
||||
1. For 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.
|
||||
2. For admin users: The users will see a dialogue box with a link to configure the GitSync feature.
|
||||
|
||||
<br/>
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{padding: '10px', marginBottom:'15px', borderRadius: '6px' }} className="screenshot-full" src="/img/gitsync/connect.png" alt="GitLab SSH Key" />
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
|
||||
## 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.
|
||||
|
||||
**Note:** 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.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{padding: '10px', marginBottom:'15px', borderRadius: '6px' }} className="screenshot-full" src="/img/gitsync/deleteconfig.png" alt="GitLab SSH Key" />
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
|
||||
## Git repo
|
||||
|
||||
Once the initial commit is made, you can see the app files in the git repository. The repository will have the individual app folders and a **.meta** folder. The app folders will be named as the app name and will have the respective **JSON** file of the application. The **.meta** folder will have the `meta.json` file that contains the meta information of each application synced to git repo.
|
||||
|
||||
The **meta.json** file holds information about apps such as the **App name**, **last commit message**, **last commit user**, **last commit date**, **version name**, and **version id**.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{padding: '10px', marginBottom:'15px', borderRadius: '6px' }} className="screenshot-full" src="/img/gitsync/gitlab/firstcommit.png" alt="GitLab SSH Key" />
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
|
||||
## Pushing changes to git repo
|
||||
|
||||
Once the GitSync feature is configured, you can start pushing changes to the git repository.
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
|
||||
### App creation
|
||||
|
||||
When 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.
|
||||
|
||||
:::info
|
||||
If the app name is same as the name of the existing app in the git repo, it will overwrite the existing app in the git repo.
|
||||
:::
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{padding: '10px', marginBottom:'15px', borderRadius: '6px' }} className="screenshot-full" src="/img/gitsync/commitchanges.png" alt="GitLab SSH Key" />
|
||||
</div>
|
||||
|
||||
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.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{padding: '10px', marginBottom:'15px', borderRadius: '6px' }} className="screenshot-full" src="/img/gitsync/gitlab/author.png" alt="GitLab SSH Key" />
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
|
||||
### 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.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{padding: '10px', marginBottom:'15px', borderRadius: '6px' }} className="screenshot-full" src="/img/gitsync/gitlab/apprename.png" alt="GitLab SSH Key" />
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
|
||||
### App updates
|
||||
|
||||
Whenever a user makes a change in an app, they can make a commit to the git repository by clicking on the **GitSync** button on the topbar. On clicking the **GitSync** button, a modal will open with the option to enter the commit message. The user can 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 connnected **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.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{padding: '10px', marginBottom:'15px', borderRadius: '6px' }} className="screenshot-full" src="/img/gitsync/gitlab/message.png" alt="GitLab SSH Key" />
|
||||
</div>
|
||||
|
||||
Once the changes are committed, the user can see the commit message, author, and date in the git repository.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{padding: '10px', marginBottom:'15px', borderRadius: '6px' }} className="screenshot-full" src="/img/gitsync/gitlab/lastcommitmsg.png" alt="GitLab SSH Key" />
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
|
||||
### App deletion
|
||||
|
||||
Whenever a user deleted 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.
|
||||
|
||||
</div>
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
|
||||
### App version update
|
||||
|
||||
When a user creates a new version of an app, there will be an option to select the `Commit changes`. If you select the `commit changes` option, the new version of the app will be committed to the git repository.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{padding: '10px', marginBottom:'15px', borderRadius: '6px' }} className="screenshot-full" src="/img/gitsync/gitlab/newversion.png" alt="GitLab SSH Key" />
|
||||
</div>
|
||||
<img className="screenshot-full" src="/img/gitsync/gitlab/newversion.png" alt="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.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{padding: '10px', marginBottom:'15px', borderRadius: '6px' }} className="screenshot-full" src="/img/gitsync/gitlab/newversion1.png" alt="GitLab SSH Key" />
|
||||
</div>
|
||||
<Tabs>
|
||||
|
||||
<TabItem value="GitHub" label="GitHub">
|
||||
|
||||
<img className="screenshot-full" src="/img/gitsync/replace.png" alt="GitSync" />
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="GitLab" label="GitLab">
|
||||
|
||||
<img className="screenshot-full" src="/img/gitsync/gitlab/newversion1.png" alt="GitSync" />
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
</div>
|
||||
|
||||
</div>
|
||||
<div style={{paddingTop:'24px'}}>
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
## Pulling Changes from Git Repo
|
||||
|
||||
## Pulling changes from git repo
|
||||
|
||||
You can configure the GitSync feature on another workspace to pull the changes from the git repository. To configure the GitSync feature on another workspace, follow the steps mentioned in the [Setting up GitSyncing with GitLab](#setting-up-gitsyncing-with-gitlab) section.
|
||||
You can configure the GitSync feature on another workspace to pull the changes from the git repository. To configure the GitSync feature on another workspace, follow the steps mentioned in the [Setting up GitSync](#setting-up-gitsync) section.
|
||||
|
||||
Once the GitSync feature is configured, go to the ToolJet dashboard and click on the three dots on the right side of the **Create new app** button. Click on the **Import from git repository** option.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{padding: '10px', marginBottom:'15px', borderRadius: '6px' }} className="screenshot-full" src="/img/gitsync/importgit.png" alt="GitLab SSH Key" />
|
||||
</div>
|
||||
<img className="screenshot-full" src="/img/gitsync/importgit-v2.png" alt="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.
|
||||
|
||||
|
|
@ -577,24 +368,12 @@ On clicking the **Import from git repository** option, a modal will open with th
|
|||
- 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.
|
||||
:::
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{padding: '10px', marginBottom:'15px', borderRadius: '6px' }} className="screenshot-full" src="/img/gitsync/importmodal.png" alt="GitLab SSH Key" />
|
||||
</div>
|
||||
<img style={{marginBottom:'15px'}} className="screenshot-full" src="/img/gitsync/importmodal-v2.png" alt="GitSync" />
|
||||
|
||||
<div style={{paddingTop:'24px', paddingBottom:'24px'}}>
|
||||
|
||||
### Checking for updates
|
||||
#### Checking for Updates
|
||||
|
||||
You can check for updates in the git repository by clicking on the **GitSync** button on the topbar. On clicking the **GitSync** button, a modal will open with the option to **Check for updates**. 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. Click on the **Pull changes** button to pull the changes from the git repository.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img style={{padding: '10px', marginBottom:'15px', borderRadius: '6px' }} className="screenshot-full" src="/img/gitsync/updatecheck.png" alt="GitLab SSH Key" />
|
||||
</div>
|
||||
<img className="screenshot-full" src="/img/gitsync/updatecheck.png" alt="GitSync" />
|
||||
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
|
|
|
|||
324
docs/docs/widgets/chart/transforming-data-for-charts.md
Normal file
324
docs/docs/widgets/chart/transforming-data-for-charts.md
Normal file
|
|
@ -0,0 +1,324 @@
|
|||
---
|
||||
id: transforming-data-for-charts
|
||||
title: Transforming Data for Charts
|
||||
---
|
||||
|
||||
This guide explains how to transform data using RunJS and RunPy in ToolJet and visualize it using the chart component. The chart component in ToolJet enables the creation of various types of charts, with the option to integrate with Plotly for enhanced customization and advanced visualizations. While ToolJet provides the ability to connect to multiple databases, APIs, and data sources for integration, this guide will focus on using ToolJet DB to fetch the required data.
|
||||
|
||||
<div style={{paddingTop:'24px'}}>
|
||||
|
||||
## Plotting a Simple Pie Chart
|
||||
|
||||
To create a simple pie chart, the data has been stored in the table with the following structure in ToolJet DB:
|
||||
|
||||
| <div style={{ width:"100px"}}> id </div> | <div style={{ width:"550px"}}> course </div> |
|
||||
|:-- | :---- |
|
||||
| 1 | Maths |
|
||||
| 2 | Full Stack Web Development |
|
||||
| 3 | Digital Marketing Strategy |
|
||||
| 4 | Business Ethics |
|
||||
| 5 | Maths |
|
||||
| 6 | Full Stack Web Development |
|
||||
| 7 | Digital Marketing Strategy |
|
||||
| 8 | Financial Accounting |
|
||||
| 9 | Maths |
|
||||
| 10 | Chemistry |
|
||||
| 11 | Financial Accounting |
|
||||
| 12 | Physics |
|
||||
| 13 | Full Stack Web Development |
|
||||
| 14 | Maths |
|
||||
|
||||
### Query to Fetch Data
|
||||
|
||||
1. Click on **+ Add** button of the query manager at the bottom panel of the editor.
|
||||
2. Select the ToolJet Database as the data source.
|
||||
3. Select your table from the dropdown.
|
||||
4. Select the **List rows** operation.
|
||||
5. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query.
|
||||
|
||||
<img className="screenshot-full" src="/img/widgets/chart/transforming-data/pie-fetch-data.png" alt="Fetch Data Query" />
|
||||
|
||||
This query will fetch the data from the ToolJet DB.
|
||||
|
||||
### Transform the Data
|
||||
|
||||
To restructure the data into a format compatible with the chart component, we will be using RunJS transformation.
|
||||
|
||||
Create a new **RunJS** Query and add the following code:
|
||||
|
||||
```js
|
||||
await queries.getRevenueDetails.run();
|
||||
|
||||
let data = queries.getRevenueDetails.getData();
|
||||
|
||||
const courseCounts = data.reduce((counts, obj) => {
|
||||
if (obj.course) {
|
||||
counts[obj.course] = (counts[obj.course] || 0) + 1;
|
||||
}
|
||||
return counts;
|
||||
}, {});
|
||||
|
||||
const courseData = Object.keys(courseCounts).map(course => ({
|
||||
x: course,
|
||||
y: courseCounts[course]
|
||||
}));
|
||||
|
||||
return {courseData};
|
||||
```
|
||||
|
||||
<img className="screenshot-full" src="/img/widgets/chart/transforming-data/pie-js-query.png" alt="Transform JS Query" />
|
||||
|
||||
This query will calculate the number of each course and return an array of objects that can be utilized to plot the pie chart.
|
||||
|
||||
### Plotting Pie Chart
|
||||
|
||||
1. Add a chart component from the component library available on right to the canvas.
|
||||
2. Under Properties section select **Pie** as the chart type from the dropdown.
|
||||
3. Under chart data section input `{{queries.<Your RunJS Query Name>.data.courseData}}` to input the data from the query.
|
||||
|
||||
<img className="screenshot-full" src="/img/widgets/chart/transforming-data/pie-chart.png" alt="Pie Chart" />
|
||||
|
||||
</div>
|
||||
|
||||
<div style={{paddingTop:'24px'}}>
|
||||
|
||||
## Plotting a Line Chart with RunJS Transformation
|
||||
|
||||
To create the line chart, the data has been stored in the table with the following structure in ToolJet DB:
|
||||
|
||||
| <div style={{ width:"20px"}}> id </div> | <div style={{ width:"300px"}}> x </div> | <div style={{ width:"80px"}}> y </div> | <div style={{ width:"150px"}}> region </div> | <div style={{ width:"100px"}}> rdate </div>|
|
||||
|:---|:--|:--|:-------|:-----|
|
||||
| 1 | Social Media Engagement | 15 | North America | 15-01-2024 |
|
||||
| 2 | Email Marketing | 10 | Europe | 10-02-2024 |
|
||||
| 3 | SEO Optimization | 20 | Asia | 05-03-2024 |
|
||||
| 4 | Content Creation | 25 | North America | 20-04-2024 |
|
||||
| 5 | Paid Advertising | 30 | Europe | 12-05-2024 |
|
||||
| 6 | Analytics and Reporting | 18 | Asia | 18-06-2024 |
|
||||
| 7 | Influencer Marketing | 12 | North America | 30-07-2024 |
|
||||
| 8 | Market Research | 22 | Europe | 25-08-2024 |
|
||||
| 9 | Web Development | 17 | Asia | 15-09-2024 |
|
||||
| 10 | Customer Relationship Management | 28 | North America | 02-10-2024 |
|
||||
|
||||
### Query to Fetch Data
|
||||
|
||||
1. Click on **+ Add** button of the query manager at the bottom panel of the editor.
|
||||
2. Select the ToolJet Database as the data source.
|
||||
3. Select your table from the dropdown.
|
||||
4. Select the **List rows** operation.
|
||||
5. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query.
|
||||
|
||||
<img className="screenshot-full" src="/img/widgets/chart/transforming-data/line-fetch-data.png" alt="Fetch Data Query" />
|
||||
|
||||
This query will fetch the data from the ToolJet DB.
|
||||
|
||||
### Transform the Data
|
||||
|
||||
Create a new **RunJS** Query and add the following code:
|
||||
|
||||
```js
|
||||
const data = queries.getLinechartData.data;
|
||||
|
||||
const calculateAverage = (arr) => arr.reduce((sum, item) => sum + item.y, 0) / arr.length;
|
||||
|
||||
const regionData = data.filter(item => item.region !== "Asia");
|
||||
|
||||
const transformedData = regionData.map(item => {
|
||||
if (item.rdate && typeof item.rdate === 'string') {
|
||||
const dateParts = item.rdate.split('-');
|
||||
|
||||
if (dateParts.length === 3) {
|
||||
const year = dateParts[2];
|
||||
const month = dateParts[1];
|
||||
return {
|
||||
x: `${year}-${month}`,
|
||||
y: item.y && !isNaN(item.y) ? item.y : 0
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
return { x: 'Invalid Date', y: 0 };
|
||||
});
|
||||
|
||||
const validData = transformedData.filter(item => item.x !== 'Invalid Date');
|
||||
const averageY = calculateAverage(validData);
|
||||
|
||||
const finalData = transformedData.map(item => ({
|
||||
x: item.x,
|
||||
y: item.y - averageY
|
||||
}));
|
||||
|
||||
return finalData;
|
||||
```
|
||||
|
||||
<img className="screenshot-full" src="/img/widgets/chart/transforming-data/line-js-query.png" alt="Transform JS Query" style={{marginBottom:'15px'}}/>
|
||||
|
||||
### Plotting Line Chart
|
||||
|
||||
1. Add a chart component from the component library available on right to the canvas.
|
||||
2. Under Properties section select **Line** as the chart type from the dropdown.
|
||||
3. Under chart data section input `{{queries.<Your RunJS Query Name>.data}}` to input the data from the query.
|
||||
|
||||
<img className="screenshot-full" src="/img/widgets/chart/transforming-data/line-chart.png" alt="Line Chart" />
|
||||
|
||||
</div>
|
||||
|
||||
<div style={{paddingTop:'24px'}}>
|
||||
|
||||
## Plotting Candle Stick Chart Using Plotly
|
||||
|
||||
To create a candlestick chart, the data has been stored in the table with the following structure in ToolJet DB:
|
||||
|
||||
| <div style={{ width:"60px"}}> id </div> | <div style={{ width:"150px"}}> sdate </div> | <div style={{ width:"100px"}}> open </div> | <div style={{ width:"100px"}}> high </div> | <div style={{ width:"100px"}}> low </div> | <div style={{ width:"100px"}}> sclose </div> |
|
||||
|:---|:------|:-----|:-----|:----|:-------|
|
||||
| 1 | 2024-04-02 | 115 | 125 | 115 | 120 |
|
||||
| 2 | 2024-04-03 | 120 | 130 | 120 | 125 |
|
||||
| 3 | 2024-04-04 | 125 | 135 | 125 | 130 |
|
||||
|
||||
### Query to Fetch Data
|
||||
|
||||
1. Click on **+ Add** button of the query manager at the bottom panel of the editor.
|
||||
2. Select the ToolJet Database as the data source.
|
||||
3. Select your table from the dropdown.
|
||||
4. Select the **List rows** operation.
|
||||
5. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query.
|
||||
|
||||
<img className="screenshot-full" src="/img/widgets/chart/transforming-data/cs-fetch-data.png" alt="Fetch Data Query" />
|
||||
|
||||
This query will fetch the data from the ToolJet DB.
|
||||
|
||||
### Transform the Data
|
||||
|
||||
To restructure the data into a format compatible with the chart component, we will be using RunJS transformation.
|
||||
|
||||
Create a new **RunJS** Query and add the following code:
|
||||
|
||||
```js
|
||||
const dbData = queries.getCandlestickData.data;
|
||||
|
||||
if (!Array.isArray(dbData) || dbData.length === 0) {
|
||||
return { plotData: [] };
|
||||
}
|
||||
|
||||
let dates = [];
|
||||
let openPrices = [];
|
||||
let highPrices = [];
|
||||
let lowPrices = [];
|
||||
let closePrices = [];
|
||||
|
||||
dbData.forEach(row => {
|
||||
dates.push(String(row.sdate));
|
||||
openPrices.push(row.open);
|
||||
highPrices.push(row.high);
|
||||
lowPrices.push(row.low);
|
||||
closePrices.push(row.sclose);
|
||||
});
|
||||
|
||||
const transformedData = [
|
||||
{
|
||||
x: dates,
|
||||
open: openPrices,
|
||||
high: highPrices,
|
||||
low: lowPrices,
|
||||
close: closePrices,
|
||||
type: 'candlestick'
|
||||
}
|
||||
];
|
||||
|
||||
let result = {
|
||||
data: transformedData
|
||||
};
|
||||
|
||||
return JSON.stringify(result)
|
||||
```
|
||||
|
||||
<img className="screenshot-full" src="/img/widgets/chart/transforming-data/cs-js-query.png" alt="Transform JS Query" style={{marginBottom:'15px'}}/>
|
||||
|
||||
### Plotting Candlestick Chart
|
||||
|
||||
1. Add a chart component from the component library available on right to the canvas.
|
||||
2. Enable use plotly JSON schema under Plotly JSON Chart Schema section.
|
||||
3. Under JSON Description section input `{{queries.<Your RunJS Query Name>.data}}` to input the data from the query.
|
||||
|
||||
<img className="screenshot-full" src="/img/widgets/chart/transforming-data/cs-chart.png" alt="Candlestick Chart" />
|
||||
|
||||
</div>
|
||||
|
||||
<div style={{paddingTop:'24px'}}>
|
||||
|
||||
## Plotting heatmap Chart Using Plotly
|
||||
|
||||
To create a heatmap chart, the data has been stored in the table with the following structure in ToolJet DB:
|
||||
|
||||
| <div style={{ width:"60px"}}> id </div> | <div style={{ width:"150px"}}> x </div> | <div style={{ width:"100px"}}> y </div> | <div style={{ width:"100px"}}> value </div> |
|
||||
|:---|:------|:-----|:-----|
|
||||
| 1 | 0 | 0 | 0.32 |
|
||||
| 2 | 0 | 1 | 0.95 |
|
||||
| 3 | 0 | 2 | 0.57 |
|
||||
| 4 | 0 | 3 | 0.08 |
|
||||
| 5 | 0 | 4 | 0.82 |
|
||||
| 6 | 0 | 5 | 0.33 |
|
||||
| 7 | 0 | 6 | 0.9 |
|
||||
| 8 | 0 | 7 | 0.11 |
|
||||
| 9 | 0 | 8 | 0.73 |
|
||||
| 10 | 0 | 9 | 0.39 |
|
||||
|
||||
### Query to Fetch Data
|
||||
|
||||
1. Click on **+ Add** button of the query manager at the bottom panel of the editor.
|
||||
2. Select the ToolJet Database as the data source.
|
||||
3. Select your table from the dropdown.
|
||||
4. Select the **List rows** operation.
|
||||
5. Click on the **Preview** button to preview the output or Click on the **Run** button to trigger the query.
|
||||
|
||||
<img className="screenshot-full" src="/img/widgets/chart/transforming-data/hm-fetch-data.png" alt="Fetch Data Query" />
|
||||
|
||||
This query will fetch the data from the ToolJet DB.
|
||||
|
||||
### Transform the Data
|
||||
|
||||
To restructure the data into a format compatible with the chart component, we will be using RunPy transformation.
|
||||
|
||||
Create a new **RunPy** Query and add the following code:
|
||||
|
||||
```py
|
||||
import pandas as pd
|
||||
import json
|
||||
|
||||
data_raw = queries.fetchHeatmapData.getData()
|
||||
|
||||
data = data_raw.to_py() if hasattr(data_raw, 'to_py') else list(data_raw)
|
||||
|
||||
df = pd.DataFrame(data)
|
||||
heatmap_data = df.pivot(index='y', columns='x', values='value')
|
||||
|
||||
x_labels = [f"Column {i}" for i in heatmap_data.columns.tolist()]
|
||||
y_labels = [f"Row {i}" for i in heatmap_data.index.tolist()]
|
||||
|
||||
output = {
|
||||
"data": [
|
||||
{
|
||||
"z": heatmap_data.values.tolist(),
|
||||
"x": x_labels,
|
||||
"y": y_labels,
|
||||
"type": "heatmap"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
output_str = json.dumps(output)
|
||||
|
||||
output_str
|
||||
```
|
||||
|
||||
<img className="screenshot-full" src="/img/widgets/chart/transforming-data/hm-py-query.png" alt="Transform JS Query" style={{marginBottom:'15px'}}/>
|
||||
|
||||
### Plotting Heatmap Chart
|
||||
|
||||
1. Add a chart component from the component library available on right to the canvas.
|
||||
2. Enable use plotly JSON schema under Plotly JSON Chart Schema section.
|
||||
3. Under JSON Description section input `{{queries.<Your RunJS Query Name>.data}}` to input the data from the query.
|
||||
|
||||
<img className="screenshot-full" src="/img/widgets/chart/transforming-data/hm-chart.png" alt="Heatmap Chart" />
|
||||
|
||||
|
||||
</div>
|
||||
|
|
@ -115,7 +115,8 @@ const sidebars = {
|
|||
'label': 'Chart',
|
||||
'items': [
|
||||
'widgets/chart/chart-properties',
|
||||
'widgets/chart/chart-examples'
|
||||
'widgets/chart/chart-examples',
|
||||
'widgets/chart/transforming-data-for-charts'
|
||||
]
|
||||
},
|
||||
'widgets/checkbox',
|
||||
|
|
|
|||
BIN
docs/static/img/widgets/chart/transforming-data/cs-chart.png
vendored
Normal file
BIN
docs/static/img/widgets/chart/transforming-data/cs-chart.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 33 KiB |
BIN
docs/static/img/widgets/chart/transforming-data/cs-fetch-data.png
vendored
Normal file
BIN
docs/static/img/widgets/chart/transforming-data/cs-fetch-data.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 9.6 KiB |
BIN
docs/static/img/widgets/chart/transforming-data/cs-js-query.png
vendored
Normal file
BIN
docs/static/img/widgets/chart/transforming-data/cs-js-query.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 38 KiB |
BIN
docs/static/img/widgets/chart/transforming-data/hm-chart.png
vendored
Normal file
BIN
docs/static/img/widgets/chart/transforming-data/hm-chart.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 46 KiB |
BIN
docs/static/img/widgets/chart/transforming-data/hm-fetch-data.png
vendored
Normal file
BIN
docs/static/img/widgets/chart/transforming-data/hm-fetch-data.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 9.5 KiB |
BIN
docs/static/img/widgets/chart/transforming-data/hm-py-query.png
vendored
Normal file
BIN
docs/static/img/widgets/chart/transforming-data/hm-py-query.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 56 KiB |
BIN
docs/static/img/widgets/chart/transforming-data/line-chart.png
vendored
Normal file
BIN
docs/static/img/widgets/chart/transforming-data/line-chart.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 59 KiB |
BIN
docs/static/img/widgets/chart/transforming-data/line-fetch-data.png
vendored
Normal file
BIN
docs/static/img/widgets/chart/transforming-data/line-fetch-data.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 9.5 KiB |
BIN
docs/static/img/widgets/chart/transforming-data/line-js-query.png
vendored
Normal file
BIN
docs/static/img/widgets/chart/transforming-data/line-js-query.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 80 KiB |
BIN
docs/static/img/widgets/chart/transforming-data/pie-chart.png
vendored
Normal file
BIN
docs/static/img/widgets/chart/transforming-data/pie-chart.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 75 KiB |
BIN
docs/static/img/widgets/chart/transforming-data/pie-fetch-data.png
vendored
Normal file
BIN
docs/static/img/widgets/chart/transforming-data/pie-fetch-data.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 10 KiB |
BIN
docs/static/img/widgets/chart/transforming-data/pie-js-query.png
vendored
Normal file
BIN
docs/static/img/widgets/chart/transforming-data/pie-js-query.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
Loading…
Reference in a new issue