Gtmhub provides an extension for Microsoft's Visual Studio Code that allows you to easily edit insights within the powerful VS Code environment. With the extension installed, you will be able to download insights to your computer, make edits to the SQL and HTML, execute the SQL with filters and see the resulting JSON, and publish the changes back to Gtmhub.

You can view the extension's listing on the VS Code Marketplace.

Keep reading to learn how to use the offline insight editor, or watch the videos below.

Video Walkthroughs

Watch an overview of how to use the extension

Learn how to use the advanced features

Installing the Extension

Before installing, if you had a beta version of the offline insight editor that was provided by Gtmhub, uninstall it.

  • In VS Code, open the Extensions pane (View > Extensions)

  • In the search bar, search for "Gtmhub"

  • Find the "Gtmhub Insight Editor"

  • Click "Install"

  • You will likely be prompted to reload VS Code after installation (and if you are not prompted, we still recommend re-loading VS Code)

Extension Commands

After installing the extension, you will see several new commands in the VS Code Command Palette, all prefixed with "Gtmhub:". The commands are detailed below.

Download an Insight

This command downloads an insight from Gtmhub to your computer. If you are not already logged in, you will first go through the login process. Once logged in, if you have access to multiple accounts you will be asked which account you want to download from. You will then be asked which insight to download. If you have multiple insights with the same name, the system name will also be shown (this can also be seen in the URL when using the online editor).

When you have selected the insight you want to download, you will be asked where to save it on your computer. Once you've selected a location, a folder will be created with a VS Code workspace file, the SQL file, and the HTML file. The name you specify on the download will be the name of the folder, this defaults to the insight's name with special characters removed.

Once downloaded, the new workspace will automatically be opened and you can now use all of the other commands.

A screenshot of the opened workspace

In each workspace, you will see three files:

  • insightHtml.html - this contains the HTML for the insight

  • insightSql.sql - this contains the SQL for the insight

  • <insight name>.code-workspace - this contains the workspace configuration information for the insight that allows the plugin to link to the correct account and insight in Gtmhub. In most cases, this file should not be edited.

Download an Insightboard

This command downloads an insightboard and all of its insights into a folder with a board-level workspace. Each insight goes into its own subfolder that is identical to if the insight were downloaded on its own without the rest of the board. There is also a board manifest file that contains information about the structure of the insightboard.

In the future, we will add additional support for board-level updates like publishing, but for now the board-level manifest is just for reference.

Refresh this Insight

This command will retrieve the latest SQL and HTML for the insight from the server, overwriting what you have locally. It will not save the files, so you can undo the change if you accidentally overwrite without intending to.

Use this command when you know changes have been made in the online editor or when you first open an insight on your machine that was not downloaded recently and you're not sure if there have been changes on the online editor since then.

Insert Snippet

This command allows you to select from a list of snippets maintained by the Gtmhub Technical Success team to insert into your code. The list of snippets is loaded on open of VS Code and may not be available for a few seconds after initially opening.

The snippets are categorized as HTML/CSS or SQL and the list of snippets displayed will vary depending on which file you have open (SQL vs. HTML).

Insert SQL Entity

This command will allow you to insert the name of a table or column into your code. The list of tables and columns is populated based on the Data Sources that are available for use through Gtmhub.

The table or column name will be inserted where the cursor is at the time that the command is executed. The list of entities will be refreshed any time that the “Get Entity Column List” command is run, so if you add a new data source into Gtmhub while your window is open, you will need to re-run that command in order to ensure that all tables and columns are up to date.

Publish this Insight

This command will publish the SQL and HTML code from the insight you have open back to the server, overwriting what is on the server. Each time you publish, a new version is created that can be accessed from the version history in the online editor if you need to revert.

Save this Insight as a New Insight

This command allows you to save the insight you’re working on as a new insight. You will be asked whether you want to save in the same account or a different account and be given the opportunity to change the name and description. You will also be asked whether to place it on an existing insightboard, new insightboard (in which case you’ll provide the board name), or not placed on a board at all.

Execute this Insight

This command will execute the SQL in the SQL file for the insight and open the results as a new JSON file within the workspace. If there is an error in the SQL, the error will be displayed in the bottom right corner of VS Code.

By default, the execution will time out after 5 seconds. If you have a complex query that takes longer than this, you can run "Execute this Insight w/ Custom Timeout".

Execute this Insight w/ Custom Timeout

This command is the same as "Execute this Insight", but allows you to specify a timeout in seconds between 1 and 60 seconds. Should be used if you know your SQL may take a while to execute.

Create Filter Settings File

This command will create a file called "filters.txt" in the workspace where you can set the value to be used for the Insightboard parameters in your SQL when executing within the offline editor.

The generated file contains more detailed instructions on how to fill out the value.

A screenshot of a filters.txt file

Get Valid Filter Options

This command will create a file called "availableFilters.txt" in the workspace that shows the list of available Insightboard parameters present on the account. For list and multi-select list type Insightboard parameters that are used in your SQL, it will also load the list of valid list values that you can use (maximum of 100) for the filter.

For some Insightboard parameters, the inserted value in SQL is different from the displayed value for the user. When the availableFilters file is generated, the SQL inserted value is displayed first, followed by the display value in parenthesis.

A screenshot of an availableFilters.txt file

Get Entity Column List

This command will create a file called availableEntities.txt that contains the list of available entities (tables) and fields (columns) for all data sources connected to the Gtmhub account. For each field, it will also give you the display name and data type.

A screenshot of part of an availableEntities.txt file

Convert Json Result to Excel

This command when run on a file generated by the "Execute this Insight" command will take the JSON result and convert it into an Excel file to allow easier working with the data for those more familiar with working in Excel.

If this command is executed on any file other than a JSON file generated by the Execute command, it will result in an error.

JSON

Converted to Excel

Open Insight with Online Editor

This command will open the insight you are currently working on in the Gtmhub Online Editor which uses SQL to retrieve data from within your account, and display it with HTML, CSS, and JavaScript. This command can be used once you have finished writing the logic in SQL and are working on the visual aspect of insights.

Open Insightboard this Insight is used on

This command will open the insightboard that the insight you are editing is used on. If the insight is used on more than one board, then a list of boards that it is used on will be shown so you can pick which one you want to use.

Note that only boards that you have access to are displayed. If the insight is not available on any boards (or boards you have access to) you will see a message indicating that.

Open Help Article

This command will open this Gtmhub Help Article page, detailing the commands, how to use them, and video walkthroughs.

Logging in to Gtmhub

Any command that requires communication with Gtmhub will automatically trigger the login flow if no valid token is available. The

When logging in, you will be asked which location you want to log in to if you are not in a VS Code workspace that is tied to an insight. If you are in a workspace, the location will be automatically selected based on that workspace. You can find your location by looking at the URL of your gtmhub account.

  • .us before gtmhub.com means US

  • .sa before gtmhub.com in the URL means South America

  • .as before gtmhub.com in the URL means

  • No prefix before gtmhub.com means EU

  • Staging will only be used by Gtmhub employees

After selecting a location or if a location is selected based on the insight you are in, your browser will open with a login screen. The login code should match the code displayed in the bottom right corner of VS Code.

After verifying the code and clicking "Confirm" you will be redirected to Gtmhub's login page. Log in with your regular credentials. If your account has SSO set up, you will be re-directed to your SSO login once you enter your e-mail address. Note that if you are already logged to your SSO provider in the browser, this step may be skipped.


Once the browser confirms the login is complete, you will see a success message in VS Code's status bar for a few seconds. You can now proceed to execute any other commands that require a connection to the server.

Did this answer your question?