C3 AI VS Code Extension

This is the official VS Code extension for development on the C3 AI Platform. The extension enhances the application development experience on the C3 AI Platform by providing C3 Type System-specific aid across type files and implementation files. These include code completion, in-text documentation, testing and debugging capabilities, and other developing utilities. For more information on C3 AI, visit our website.

Important Note: The extension only supports Version 8 and above and requires a VS Code version of 1.81.2 or greater.


C3 Type System specific IntelliSense, Live Error-checking, and Instant Deployment

C3 AI VS Code Extension

Prerequisites

Before developing an application on the C3 AI Platform, you must:

Setup the local workspace. The local workspace is a directory that contain your packages.
Uninstall C3.ai Development Experience and restart VS Code.
Install C3 AI VS Code extension.
A node version >= 16.

Our extension requires that you be on a node version greater than or equal to 16. You can check the node version by running node -v in your terminal or VS Code terminal. Make sure to run this command in the correct workspace.

If you have no node installed please install a version (there are multiple ways to do this: How to Install NPM and Node.js on Windows and Mac Devices). For the first time installation of the node, you need to restart VS Code to start a new fresh session that will recognize the newly installed node.


Run `node -v`

Setup the local workspace

A local workspace is a folder or directory on the local file system of your client device. This is where you can store your C3 AI application package code.

Ensure that you have a workspace (a directory) that contains your packages like the following example:


Example workspace with multiple packages

Install the extension

In VS Code, select the Extensions tab on the Activity Bar and search for C3 AI.

It is best practice to have the latest version of the extension. If the server version is incompatible with the newest version of the extension, you can install an older version of the extension on this page.

Set up the developers environment

Create an environment

For application development, connect to a Single Node Environment. Once connected to a single node environment, you will be able to start applications based on the packages in your workspace.

Use C3 AI Studio to create environments. Refer to the example below for creating a single node environment in Studio:


Create a single node environment through C3 AI Studio

Connect and synchronize the workspace

Once the extension is installed, a pop-up welcome page launches allowing you to select or confirm your workspace and enter your environment URL.

To manually access the welcome page, go to the C3: EXPLORER panel and choose one of the following options:

Select the Connect link.
Select the spaceship icon.


Connect to an Env via the Welcome page

On the welcome page, you can confirm your workspace and connect to the environment URL.

Workspace: Select the folder that contains the packages you want to begin development on.

Environment URL: Enter the Environment URL that you have created in the previous section. The URL can be obtained from C3 AI Studio by going to the desired environment and selecting Open in VS Code from the ellipsis menu.

The initial sync may take several minutes. During the sync process, C3 Type files from dependencies are downloaded to your workspace and local files are uploaded. You can pay attention to the output tab which should open automatically to see what is going on.

Upon successful connection and sync, you should see the following message in the notification box as well as within the output tab. Additionally, you will also see the package explorer in the C3 AI tab populate with your local and external (dependency) packages.


Successful Connection Notification

Advanced Settings

This section is for custom setups and we advise that most users do not change these specifications. Additionally, these settings only apply during connection and synchronization.

On the welcome page, there are options for advanced settings:


Advanced Settings

Setting	Default Option	Non-default Option
Source of Truth	Select Client to override the server-side files with the client-side files.	Select Server to override the client-side files with the server-side files. Local files can be modified or removed.
Union	Toggle off to have to have the Source Of Truth files completely override the other.	Toggle on to merge the client-side and server-side files.

Note about the Union setting:

The option you select for the Source of Truth takes precedence over overlapping files.
When connecting to a new package, make sure the Union toggle is turned off.


Example image of different outcomes based on advance settings

Scenario 1:

Source of Truth: Client & Union: Off
The client-side files override the server-side completely.

Scenario 2:

Source of Truth: Client & Union: On
The client-side files override the server-side files. The server-side files that have not been overwritten by the client-side files remain unchanged.

Scenario 3:

Source of Truth: Server & Union: Off
The server-side files override the client-side completely.

Scenario 4:

Source of Truth: Server & Union: On
The server-side files override the client-side files. The client-side files that have not been overwritten by the client-side files remain unchanged.

Adjust reconnect attempts

If you happen to lose your internet connection temporarily (e.g., your VPN crashes), the extension attempts to reconnect five times, with each attempt lasting for 30 seconds.

When VSCE detects the loss of connection, it will provide a notification as shown below.


Notification provided during auto-reconnect attempts

You can change the number of attempts:

Open the VS Code extension settings. For MAC, you can use the keyboard shortcut (⌘,). Go to VS Code documentation for more information.
Enter c3: reconnect attempts in the search bar or select Extensions > C3 AI
Under C3: Reconnect Attempts, enter the number of attempts you would like to have


The extension setting to change the number of reconnect attempts

Start application

Once your package is synced and validated with the server, right-click on the package and select Start App to initiate your application. A green circle next to the application name indicates that it is running.

For detailed setup instructions, refer to Set up the C3 AI VS Code extension.

Now you are ready to start building applications!

Review validation

After the synchronization process, the remote environment will begin to validate all the new files that it has received. During this process, you will see the icons on the files in the Package Explorer transition across a few states outlined below.

Icon	Status	Description
	Unsynced	An unfilled gray checkmark next to your file icon indicates an unsynced state, meaning that the local file has not yet been upserted to the server. Generally, this is when you have made unsaved changes.
	Synced	An unfilled green checkmark next to your file icon indicates a synced state, meaning that the local file has been upserted to the server.
	Validated	A green filled checkmark next to your file icon in the Package Explorer indicates that the file has been successfully synced to and validated by the remote environment. Note that files can be validated and have errors; in this case, the file name will turn red.

Environment health metrics

Upon connection, the extension provides two health metrics for the environment: CPU and Memory. These can be found on the bottom status bar next to the environment URL.


Environment CPU and Memory usage

When these values exceed certain thresholds (where the default thresholds are set to be 90% for CPU and 75% for memory), you will get a notification.

Note: The threshold values for triggering a notification can be changed in the extension settings at the user or workspace level.

C3 AI VSCE Features

Upon successful connection, you should be able to test out the following features. There are 4 main areas that are useful within the C3 AI tab:

The Package Explorer (1), the Application Explorer (2), the Tester (3), and the Bottom C3 AI Panel (4) tabs (which contain C3 AI: Package Issues , C3 AI: Test Results).


(1) Package Explorer, (2) Application Explorer, (3) Tester, (4) Bottom C3 AI Panel Tabs

Package Explorer

The package explorer is the first section highlighted above. Once you have an established connection, you should see a list of your local packages as well as any dependencies from the server (for example, the platform package).

This is also the recommended interface for interacting with your packages (over the native file explorer). From here you should be able to do the following:

[Top level icons] Create new packages (with or without UI utilities)
[Right click] Create/Delete/Rename files, folders, types
[Right click] Open file, folder in file manager
[Right click] Copy and paste file
[Right click] Copy path and copy package path
[Right click] Start application of package
[Right click] Reysnc package
[Hover icon] Run tests, debug tests, and add tests to the Tester queue
[Hover icon] Queue all tests in the package
See which files are unsynced, synced, or validated (check marks next to the file icon)

Application Explorer

The application explorer is the second section highlighted above. It serves as a management hub for your current applications. || |:--:| | Application Explorer View| From this interface, you can view applications running under various packages along with their respective application modes. Additionally, it provides the following functionalities:

[Top level icons] Initiate a new application

[Button] Launch a new application

[Right click] Terminate an application

[Right click] Start and stop UI bundling

[Right click] Create a new notebook

[Right click] Navigate to the static console

When you initiate an application, the C3 AI | Start Application tab will appear. This tab includes a dropdown menu for selecting from the packages in your current workspace, an input box for specifying the application name, and an option to select the application mode.

Start Application Form

Tester

The tester is the third section highlighted above. This is where you can queue up a list of test files under a package to run, execute test files and view the history of the last 10 test runs. There are 2 tabs: Queue and History.

Via the test queue, you can interact with a set of test files by:

Select an application to run your tests against

Running all the test files

Re-running failed test files

Stopping/aborting the running test

Remove tests under a package

Run/debug individual test files

|| |:--:| | Tests Queued in Tester| In tester, you are able to run your test(s) against a currently running application or a "single-run application". A "single-run application" creates new isolated and temporary applications to run tests. Once the test is done running, the application is terminated. This option does not impact the current set of running applications.

Via the test history tab, you review the results of the last 10 test files that you’ve run. Clicking on a specific test file result will open the output tab with the detailed results.

JavaScript (JS) Debugger

In addition to running tests, users can also debug individual test files.

Currently, only JavaScript test files using Jasmine are supported.

To start the debug session:

Place breakpoints in the test file and Javascript files you are trying to debug.

Hover over a related test file and select the Debug test file button

For repeated debugging of the same file, hover over the file and select Add test to test queue. Then click the Debug test file button from the test queue

Once the debugging session has started, you will see a toolbar located near the top of the screen that has the icons. Restart and Disconnect icons affect the debug session while the other icons affect the line-by-line execution of the program. For more information on these icons, see Debug Actions.

Go to the left side navigation, Run and Debug tab, to use the debugging functionality and view information like:

Variables: Inspect and set variables at each scope, ordered by innermost to outermost scope. See Data Inspection.

Watch: Watch both variables and expressions as the program is run.

Call stack: Show the program's function call stack and hide unnecessary stack frames using skipFiles.

Loaded Scripts: View the scripts loaded during the debug session.

Breakpoints: View/edit/remove breakpoints placed. Conditional breakpoints are also supported.

In the panel tabs, go to the Debug Console tab to inspect complex objects with nested fields and evaluate expressions using REPL (Read-Eval-Print Loop) feature. The C3 AI debugger adds custom logs with information on tests starting, passing, and failing.

A debugging session in progress

(Preview Feature) Debugging server-side methods: The C3 AI debugger provides an experimental feature that allows debugging of server-side methods and executes them in Node instead of on the server. To enable this behavior, breakpoints must be set on the JavaScript implementation file. All server-side methods on the file will be debuggable. This is supported for multiple files.

If you want to switch breakpoints within a set of files during a debug session, you must pause the debugger and resume after the breakpoints are updated.

Additionally, this may cause unintended errors during execution since not all server-side code is valid in Node. Remove the breakpoints on these files if errors occur.

Bottom C3 AI Panel

The panel is the fourth section highlighted in the image above. This section has multiple tabs within it that are relevant to the C3 developers. These include C3 AI: Package Issues, and C3 AI: Test Results.

Package Issues

This tab regularly updates with any syntax or deployment errors that your code has. This is a good one to keep open as you make changes within your application.

An example of an error captured on the WindTurbine Type

Test Results

This tab provides two views, one for the test results and the other for server logs. The first view provides the status and results of any tests that you run. If there is an error the line where the error is located is presented. The second view outputs a server log snapshot of the test run.

An example of a test result output tab

Developer Utilities

The extension provides several C3 Type specific IntelliSense features including the following:

Hover documentation – When mousing over any reference C3 type file or keyword, you will see in-context documentation.

Autocompletion – When typing in type files or implementation files, receive type-ahead or autocomplete suggestions that include the set of types in your local workspace and remote environment.

Jump to Definition/Implementation – Right-click to navigate to another type file or implementation file from the type file you are within (you can cmd + click as well).

Peek Definition/Implementation – Right-click and open a preview to the type file or implementation file within your existing file without opening a new tab.

Package error-check – Check the C3 AI: Package Issues tab for any package errors as you type and save (see the image in the Panel’s section).

Before you jump into editing methods, ensure that your TS/JS Server is initialized. This will show up in the bottom status bar when you first open a JavaScript file after the completed initial sync. See the following image.

Initialization of the TS/JS Server

Notebook

The extension offers a C3 notebook, which is an implementation of a VS Code notebook. A notebook contains cells that you can run your code in. The supported languages in the C3 notebook are JavaScript and Markdown. You can connect to an application in your remote environment with a notebook and run actions in the context of this application. To create a new notebook, click the notebook icon in the package explorer as shown below.

Creating a notebook from package explorer

Alternatively, you can right click on an application in the Application Explorer and select "Open Notebook".

Creating a notebook from app explorer

Once in the notebook, you can write Markdown and JavaScript code in the notebook cells. Below is a notebook with some example cells.

Notebook example

Toolbar Overview

Option Description

+ Code Adds a new code cell which can run JavaScript and has C3 Type System initialized.

+ Markdown Adds a new markdown cell.

Scripts Allows for running a custom JavaScript script that is run before running any notebook cells. See Scripts for more details.

REPL Opens a new REPL. See REPL for more details.

Select Application Selects the application context used to run notebook cells. Changing the context clears all defined variables, similar to restarting the notebook.

Run All Sequentially runs every cell in the context of the connected application.

Debug Enables the ability to pause on breakpoints set within the notebook. This only applies for the Node.js notebook.

Restart Restarts the notebook and clears all defined variables. Creates a new connection to the selected application and runs all custom scripts.

Clear All Outputs Clears the cell output for each cell in the notebook.

... Opens advanced notebook settings such as toggling line numbers or modifying extension notebook settings.

C3 Server Rhino The currently selected notebook kernel. Click this to change the current kernel. See Supported Kernels for more details.

Supported Kernels

A notebook kernel is responsible for running code that is written in a code cell. The C3 notebook currently supports two JavaScript kernels:

C3 Server Rhino: Code is ran in C3 Server directly in a session that lasts for a few hours. If the session expires with the error message Error invoking Java method Js.TurboJsSession#execute, please restart your notebook.

C3 Client Node.js: Code is run using the version of Node.js on your computer. The C3 Type system ensures that C3 actions are run in the correct action engine.

The default kernel is C3 Server Rhino. To change the currently selected kernel, click on the button in the top right and select the desired kernel in the dropdown.

Changing notebook kernels

If the option for C3 Client Node.js is not visible, click on Select Another Kernel and C3 AI and select the Node.js kernel. Only notebook kernels that were used recently will show up in the list of notebook kernels.

REPL

In addition to the C3 notebook, the extension also offers an alternative way to run code called REPL. The C3 REPL is useful for running commands quickly and uses the same notebook kernels as the C3 notebook. It also supports accessing the previous command using the up arrow key.

Opening REPL

Similar to the notebook, you can open a REPL from the package explorer or from the application explorer. To run commands in a REPL, write your code in the dedicated code cell at the bottom of the page. Note that REPL only supports code cells.

Example REPL

Visualizations

In addition to basic outputs, the C3 notebook supports interactive visualizations. To visualize documentation for a C3 type, run a cell with the name of the type. You can navigate to links for other C3 Types in the documentation view.

C3 Type Documentation

C3 notebooks support automatically visualizing objects. Objects can be rendered in tree, grid, and chart views. Views are only rendered if possible with the given data. For example, data that is a FetchResult can be visualized in all three views:

Tree Visualization

Grid Visualization

Chart Visualization

To change the currently selected view, click on the icons in the top left of the cell output. Interactive visualizations are also supported in the C3 REPL.

Scripts

Both the C3 notebook and C3 REPL have support for running custom scripts before any notebook cells. This is useful for defining constants and functions that will be available in any notebook or REPL. To access this, click on the Scripts button in the notebook toolbar.

Notebook Scripts

Notebook scripts can be defined in two locations, either Global or Workspace. The global script applies to all notebooks for every workspace, whereas the workspace script applies only to notebooks in that workspace. Note that the global script runs before the workspace script.

Using a custom function in scripts

In the example above, the notebook has access to a custom function called wf that was defined in the script. Since the scripts are only run once before any cell is run, make sure to restart the notebook after making any changes to the scripts.

Lodash

Lodash is automatically included in notebooks and REPL for both Rhino and Node.js kernels. For examples, see Lodash.

Advanced Features

In the Node.js notebook and REPL, you can use $_ to refer to the output of the previous cell. This is identical to the usage of $_ in the Chrome developer console.

Private methods and fields on a C3 Type in the documentation view are hidden by default. You can change this in the advanced notebook settings in Toolbar Overview.

Remote Python Debugger

This extension provides a feature for debugging Python code ran on a remote server.

Starting the Remote Python Debugger

You can start the Python debugger in two ways:

After a successful sync, go to the launch and debug tab, select the C3 Remote Debugger configuration, and click on the run icon.

Starting Debugger from Run and Debug tab

You can also automatically start the debugger after a successful sync by enabling the C3: Auto Start Debugger in the extension settings.

Automatically Starting remote debugger after a successful sync

Once the debugger has started successfully, you will see the debug toolbar at the top of the screen.

Debugging Python Code

The debugger supports the following features:

Breakpoints: Set breakpoints in your Python code, and the debugger will stop at the breakpoint.

Step Over: Step over the current line of code.

Step Into: Step into the current line of code.

Step Out: Step out of the current line of code.

Continue: Continue execution until the next breakpoint or end of the program.

Disconnect: Disconnect the debugger from the remote server.

Debug Console: Open a debug console to run Python code on the remote server.

Watch: Watch variables and expressions as the program runs.

Here are some ways to hit breakpoints in Python code:

Running actions through notebook (Recommended way): To debug server-side Python actions through your Notebook, you can add a breakpoint in the Type implementation files, start the notebook in your application, and try running the action. The debugger stops at the breakpoint and the file is focused in the editor.

Hitting Breakpoints using notebooks

Running actions through the console: Similar to the notebook, you can add breakpoints in the Type's Python implementation files. Open the console of the your application and try running the action. The debugger will stop at the breakpoint in the Python action in VS Code.

Hitting breakpoints using static console

Running actions through Jupyter notebook: To hit breakpoints when running actions through Jupyter notebooks, you need to ensure that the actions are being ran on the remote server. For example, if you want to run an action implemented in py-a runtime, ensure that the Jupyter notebook kernel does not have the same runtime py-a or has all the dependencies of py-a. You can do this by creating a Python runtime without any dependencies and running the action in that runtime

Hitting breakpoints through Jupyter

Limitations of Remote Python Debugger.

Currently only supports the debugging of py4j actions. If you have a custom runtime, it is most likely py4j.

Can debug only one action at a time. If multiple actions are running simultaneously, the debugger will stop at the first action that hits a breakpoint.

C3 AI Code Assistant

The extension also offers an advanced coding assistant powered by generative AI. It provides a chat service that allows users to ask questions and receive AI-generated responses based on the context of your code. To access C3 AI Code Assistant, click the C3 AI Code Assistant icon on the activity bar. If you see a screen indicating that C3 AI Code Assistant is disabled, please contact your administrator.

Features

Interactive Chat Service

Use the provided chat bar to ask questions and receive fine-tuned AI-generated answers specifically trained off of C3 code.

Copy Code Responses to the Editor

The C3 AI Code Assistant provides an option to copy code responses directly to your editor. This feature allows you to easily use the code snippets provided by the AI in your project. Simply click on the 'Copy to Editor' button next to the AI's response in the chat.

Highlight and Explain Code

With the C3 AI Code Assistant, you can highlight sections of your code in the editor, right-click to open the context menu, and select 'Explain Code'. The AI will provide an explanation of the highlighted code in the chat.

Highlight and Fix Code

The C3 AI Code Assistant can also suggest fixes for your code. Highlight the section of code you want to fix, right-click to open the context menu, and select 'Fix Code'. The AI will suggest a fix in the chat, which you can then copy to your editor.

Getting Started

To access the C3 AI Code Assistant, find and click the Generative AI icon on the activity bar. If you are greeted with a screen saying it is disabled, please contact your administrator.

Giving Feedback on AI Responses

Users can provide feedback on AI responses using thumbs up/down icons. If a response is unhelpful, users can give a thumbs down and provide additional text feedback, including what they believe the correct answer should have been. This feedback is crucial for improving the AI model and enhancing the usefulness of the C3 AI Code Assistant.

Feedback

We are constantly working to improve the extension by fixing bugs and adding new features. If you have any feedback that you wish to share with the developer team, please reach out to us at https://support.c3.ai/.