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.


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

C3 AI VS Code Extension

Get Started

Before developing an application on the C3 AI Platform, make sure to meet the prerequisites:

A directory where your packages will live - this is your workspace
An Environment URL
The C3 AI VS Code Extension installed to VS Code
A node version $\geq$ 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)


Run `node -v`

Install the extension

To install, select the Extensions icon in VS Code and search for C3 AI Development Experience V8.

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.

Setup the local workspace

The local workspace is where you store your C3 AI application package code. Ensure that you have a workspace (a folder) in your local machine that follows the following structure, where LocalWorkspace represents the directory that contains the package(s) that you are working on.


Example workspace with multiple packages

Create an environment

Application development is done by connecting to a Dedicated Development Environment (DDE). Once connected to a DDE, you will be able to instantly start applications based on the packages in your workspace.

Environments can be created via C3 AI Studio; below is an example of DDE creation in Studio.


Create a DDE via C3 AI Studio

Connect and sync

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


Connect to an Env via the Welcome page

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

Now you are ready to start building applications!

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 initial connection and sync.

On the welcome page, there are a few advanced settings options, as shown below.


Advanced Settings

Setting	Default Option	Non-default Option
Source of Truth	Client: Server-side files will be overridden based on client-side files for files that have the same file name.	Server: Client-side files will be overridden based on the server-side files for files that have the same file name. Users might see local files being deleted or changed.
Union	On: Unique files to the server or client will be synced.	Off: Unique files to the server or client will not be synced.

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 changes and not saved.
	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 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.

C3 AI VSCE Features

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

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


(1) Package Explorer, (2) Tester, (3) Panel tabs

Package Explorer

The package explorer is first (1) 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 new files and folders
[Right click] Delete files and folders
[Right click] Start and stop UI Bundling
[Right click] Start and stop applications within your DDE
[Hover icon] Run test files / add them to the Tester queue
[Hover icon] Debug JS logic logic on the client-side via tests
Search for files, c3-specific keywords, and more across your workspace
See which applications are active (green circle icon)
See which files are unsynced, synced, or validated (check marks next to file icon)

Tester

The tester is second (2) section highlighted above. This is where you can queue up a list of test files 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:

Running all the test files
Re-running failed test files
Stopping/aborting the running test
Debugging client-side JS logic
Clearing all test files from the queue

You can also interact with individual test files in a similar fashion.

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.

Panel Tab

The panel is third (3) section highlighted in the image above. This section has multiple tabs within it that are relevant to the C3 developers. These include Output, C3 AI: Metadata Issues, and C3 AI: Test Results.

Output

This tab provides logging information to let users know what is happening when they are using the extension. During the initial connection and sync, it will provide insight into which stage of the process the user is in. Additionally, upon making metadata changes, the output tab provides instant feedback regarding the synchronization of files.


An example of the output tab as during the initial sync

Metadata 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 a metadata error for the SmartBulb 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 result information for 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.
Metadata error-check – Check the C3 AI: Metadata Issues tab for any metadata 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

JS Notebook

A new preview feature that we have enabled is the integrated JS Notebook. It will automatically connect to your remote environment and will allow you to run JS console commands and Type APIs within VS Code. You will also be able to switch context to any applications that you start within your DDE. To interact with your remote environments and applications from within VS Code open a new JS notebook by clicking on the notebook icon as shown below.


New JS notebook

Once in the notebook, you can run Type APIs as you would on the console. For example, see the screenshot below. To run commands against another application within your connected environment click on the Select App button.


Run APIs via the JS notebook across multiple apps as you would in the browser console

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/.

C3 AI Development Experience V8

C3.ai