C3 AI Documentation Home

Create Custom Types and Methods

You can use VS Code and C3 AI VS Code Extension (VSCE) features to extend your C3 AI application:

  • Create custom Types and access the Type documentation.
  • Add static or member methods to your custom Types.
  • View documentation for custom or built-in Types.
  • Create new application packages in your environment.
  • Find errors in your code.

Prerequisites

Before you begin, ensure you have the following:

  1. Access to a C3 AI Studio cluster.
  2. A running single node environment (SNE).
  3. A basic C3 AI application in your SNE.
  4. A workspace with the C3 AI VS Code extension.

To create your SNE or development application, see any of the following links:

For an overview of development requirements, see Develop a C3 AI Application. If your organization is not yet a C3 AI customer, contact us for additional information.

Create a new custom Type

In the C3 AI Type System, a Type is analogous to a class or interface in traditional software development.

Follow these steps to add a custom Type to your application:

  1. Create a src folder in your package, if one is not present.
    As a best practice, create (or ensure you have) an entity folder inside src.
  2. Create a <type name>.c3typ file in the src/entity folder.
    This is where you define the mixins, fields, methods, and annotations for the custom Type.

The following example creates a WindTurbine.c3typ file containing a WindTurbine Type definition:

The filename must be the same name as the Type it defines. Capitalization is important!

Type
/**
* WindTurbine.c3typ
* Represents a single wind turbine in a wind farm
*/
entity type WindTurbine {

    // custom fields and methods will go here

}

You can configure Type behavior using the following attributes:

  • Fields: Attributes associated with the Type.
  • Annotations: Additional attributes and configurations for a field, method, or Type.
  • Mixins: Attributes for reusing and inheriting properties from other Types.

For a deeper dive on Types, Type methods and runtimes, see any of the following:

Create a custom Type method

A Type method can take arguments, perform logic, invoke changes, and return values.

You can add a Static or Member method to a Type. The following table briefly describes each:

  • Static: Called on the Type. Inaccessible on Type instances.
  • Member: Called on the Type instance. Can return data about a specific Type without using a query.

Follow these steps to create a custom Type method:

  1. Declare a method signature as a field in the desired Type.
    The signature defines the method's input, output, implementation language, and execution location:

    TypeScript
    methodName: function(inputVariableName: inputDataType): outputDataType implementationLanguage-executionLocation
    • methodName: The name of the method. For example, getInstanceName
    • inputVariableName: inputDataType: A method parameter and corresponding data type. For example, length: int declares an int parameter called length.
    • outputDataType: The data type returned by this method. For example, int specifies that a method returns a number.
    • implementationLanguage-executionLocation: The method's runtime execution context. For example, js-client specifies a JavaScript implementation that will be run on the client.

  2. Create <TypeName>.<implementedLanguageExtension> file to implement the function.

    • This file must be saved in the same location as the Type's .c3typ definition file.
    • For example, a WindTurbine.js file would contain JavaScript method implementations for a WindTurbine.c3typ Type definition in the same directory.

The following sections demonstrate these steps in more detail using an example WindTurbine Type:

You can test method implementations in the JavaScript Notebook. To access a JavaScript notebook using C3 AI VSCE, see Overview of the C3 AI VS Code Extension.

Create a static method

Follow these steps to create a static method on the WindTurbine Type:

  1. In the WindTurbine.c3typ file, add the method signature as a field.

    • The following example declares a randNumber method that generates and returns a random number.
      It will take an integer argument called max as the maximum value it can return.
    • js-server indicates this will be a JavaScript implementation that runs in the C3 AI server runtime.
    Type
    entity type WindTurbine {
    // ...

    /**
    * A static method that generates a random number.
    */
    randNumber: function(max: int): int js-server
}

  2. In the src folder, create a WindTurbine.js file and implement the method as a function.
    The following example uses JavaScript's built-in Math.random function to return a random number:

    JavaScript
    // WindTurbine.js
function randNumber(max){
  return Math.floor(Math.random() * max);
}

    Save the implementation and ensure your package is fully synchronized. Refer to Check file synchronization for more details.

  3. In the JavaScript Notebook, test the new method to see the method output:

    JavaScript
    // Outputs a random number between 0 and 100
WindTurbine.randNumber(100);

    Press SHIFT+ENTER to execute the code cell. The output will be a random number from 0 to 99.

Repeat these steps to declare and implement more methods on the WindTurbine Type.

A Static method is not available on Type instances. Using the preceding example, the following will generate an error:

JavaScript
// Create a new instance of the "WindTurbine" Type
var myInstance = WindTurbine.make({ id: 123 })

myInstance.randNumber(); // <Returns an implementation error>

Create a member method

Member methods are only accessible on Type instances. You create them using a similar process to static methods. This section adds a member method to the WindTurbine Type example.

  1. Declare the method signature on the Type. Member method signatures must include the member keyword.
    This example declares a method that returns the ID of a WindTurbine Type instance:

    Type
    entity type WindTurbine {
    /**
    * Returns the ID of the Type instance
    */
    getInstanceId: member function(): int js-server
}

    The entity keyword gives the Type additional built-in properties including an id.

    In the example, js-server indicates the function will be implemented in JavaScript that runs on the C3 AI server.

  2. If you don't have one yet, create a WindTurbine.js file in the same directory as the WindTurbine.c3typ extension.
    Implement a getInstanceId function in the WindTurbine.js file that returns the id of the object:

    JavaScript
    // WindTurbine.js
//
// Use the "this" keyword to access data from the created WindTurbine instance
function getInstanceId(){
  return this.id;
}

    Save the implementation and ensure your package is fully synchronized.

  3. To call the member method, create an instance of the Type in your JavaScript notebook and access the method using dot notation:

    JavaScript
    // Create a WindTurbine with the ID "123"
var myInstance = WindTurbine.make({ id: 123 }); 

myInstance.getInstanceId(); // returns the instance ID

    The previous method call should return 123.

Create a new application package

A package is a way to bundle resources that can be used by other applications. To add a new package to your development environment, select Create New Package in the VS Code Extension sidebar.

Create New Package control in the C3 AI VS Code Extension sidebar

After creating the new package, you can extend it with custom Types. For more information on C3 AI application packages, see Package Management Overview.

Additional information

The following information may help you troubleshoot issues in your development environment. For more troubleshooting guidance, see C3 AI VS Code Extension Troubleshooting.

Access Type information

To access Type documentation within VS Code, enter the Type name (for example, WindTurbine) in the JavaScript Notebook and press SHIFT + ENTER. You can also use the c3ShowType function on any Type:

JavaScript
c3ShowType(WindTurbine)

If a Type is in a different package in your development environment, change your notebook application context to access it. Use Select Application in the notebook window to reveal a package menu, then select the target package from the menu.

VSCE notebook controls

Check environment mode

The C3 AI VS Code Extension can only connect to a dev (single node) environment. If you cannot connect to an environment using VS Code, or the Open in VS Code action is unavailable in C3 AI Studio, you may have created a shared environment.

To see if your environment is in development mode, view the environment name under APPLICATIONS in the C3 AI VS Code extension sidebar.

The application mode should be visible as (dev).

You can also find this information in C3 AI Studio by taking the following steps:

  1. Navigate to the application. You can use any of the following methods:
    1. Select the application card from the C3 AI Studio homepage
    2. Select the application name from the list on the Apps page
    3. Select the application name from its parent environment overview page
  2. Locate the Application mode label in the Details section of the Application Overview page.

File synchronization

The following icons indicate whether a file or directory has been synchronized with the C3 AI server:

IconStatusDescription
Un-synced iconUn-syncedThe file has not been uploaded to the server. Try making changes and saving the file again.
Synced iconSyncedThe file has been uploaded to the server.
Validated iconValidatedThe file has been sent to and validated by the server. If a validated file contains errors, the filename turns red.

If your file is saved and shows a synced status when you expect a validated status, resynchronize your local package to the server by following these steps:

  1. Open the VS Code Command menu (CMD+SHIFT+P on macOS; CTRL+SHIFT+P on Windows)
  2. Select the C3: Resync Local Packages with Server command.

A notification message will indicate when your package synchronization is completed.

If the file remains in a synced state, restart VS Code and reconnect to your environment.

View package errors

The C3 AI tab in the bottom panel of the C3 AI VS Code Extension shows the errors in your package. Keep this tab open during development to show any errors that emerge after you save your code. To go to the error in your code, select the error message.

To enable DEBUG mode, run the following in the application notebook, console, or the C3 AI VS Code Extension Read-Eval-Print Loop (REPL) feature:

JavaScript
Js.exec(`Pkg.Store.log().setLogLevel("DEBUG")`)

See the "REPL" section in C3 AI VS Code Extension Features to learn more about using the REPL feature.

See also

Was this page helpful?