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.

Login

The login command obtains a token that allows you to interact with Gtmhub and is required for all commands that interact with Gtmhub except "Download an Insight", which will automatically login if not already logged in. Once you log in, the login is valid for the duration of the token which for most accounts is 10 hours.

When logging in, you will be asked which location you want to log in to. If your account domain has ".us" like "jakedemo.us.gtmhub.com", then you will select US. Otherwise, you will select EU.

This will then open a browser window where you will see a login code. 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.


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.

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.

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 Help Article

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

Did this answer your question?