❗️

Premise on the use of terminals for Windows Users

We strongly recommend to use either WSL or bash terminals throughout the whole development process of your custom UI Component or Cloud Function.

The IXON CDK Simulator offers an easy way to test your code and seeing the results in real time, allowing you to review your work properly before deploying and publishing to the Cloud.

Running the Simulator

To view and test your component, follow these steps:

• Open your project folder in your IDE. This folder should at least contain a /components folder with a <component-name> folder inside of it (replace the placeholder with your component's name). For example, the path to a UI Component in the Service Logbook app will look like this: /app-service-logbook/components/service-logbook.
• Open a terminal window (preferably using bash or WSL terminals), navigate to the root folder of your project and run the following command:
  Simulate your component

  npx cdk simulate <component-name>

This will open the simulator app in a browser and build your component in watch mode, meaning that any changes to the component source files will trigger a rebuild and automatically reload the simulator.

🚧

Simulation scenarios

When simulating a project, please keep the following in mind:

• If your project is composed by both a UI Component (UI/Frontend) and a Cloud function (Backend logic), also called a Cloud app, you will need to open two terminals to run the two different environments respectively at the same time:
  1. In one terminal you will run make run to test your Cloud function. To do this successfully, please follow the instructions and tips found in the yellow note in the Initial set up section.
  2. In the other terminal, you will run the npx cdk simulate <component-name> instead to visualize the UI Component, the frontend of your Cloud app.
• If your project only consists of a Cloud function, you will only need one terminal, but in that case the best way to see the simulation result will be checking the console. As best practice, we always recommend creating a UI Component to visualize the results of your Cloud function.
• If your project only consists of a UI Component, you will only need one terminal where you will run npx cdk simulate <component-name>.

Login using the Simulator and retrieve real platform data

By default, the Simulator provides your component with a device with mocked historical data and can only use a locally running Cloud Function. Besides the default behaviour of the Simulator, it is possible to retrieve and manipulate platform resources you have access to, such as historical data, agents and production Cloud Functions.
This can be achieved by logging in with the following command:

npx cdk login

You will be prompted to fill in your email address and password (as well as the OTP number of your provider in case 2FA is active).

📘

Note about user permissions

If your component has different behaviour for different user permissions, it is possible to simulate a user with different permissions than your own.

At times, the login might expire. In these cases, you will see this window appear after launching the simulator:

As the message says, you can choose to use mock data or, alternatively, stop the terminal with CTRL + C or kill it and use npx cdk login to repeat the login process and then run the simulation command once more.

Testing with a Cloud Function

Two interfaces (respectively the BackendComponentClient and the ObjectStorageClient) orchestrate how the Simulator works based on what kind of settings are selected. You can find more information about the Object Storage in this article.

Settings (Cogwheel) > Component > Cloud Function

• None:

  • The BackendComponentClient will reject all calls.

  • The ObjectStorageClient will accept all calls.

  • All storage operations will be in the Simulator memory on the developer's computer.

  • The UI Component's URL is automatically set up when running the Simulator.

    
    
  
  

• Local Cloud Function Ingress:

  • The BackendComponentClient will call the locally running ingress;

  • The ObjectStorageClient will try to authorize all calls with the locally running ingress;

  • All storage operations will be in the Simulator memory on the developer's computer.

  • The default local Cloud Function Ingress is http://localhost:8020/.

    
    

• Production Cloud Function:

  • The BackendComponentClient will call the Cloud Function running in IXON Cloud

  • The ObjectStorageClient will authorize all calls with the Cloud Function running in IXON Cloud;

  • All storage operations will be with the IXON Cloud.

    
    

Using mock data or platform data

Data is mainly handled by the LoggingDataClient and ResourceDataClient interfaces. To know more about each one of them, please refer to the Using the Logging data client and Using the Resource data client knowledge articles.

Settings (Cogwheel) > API > General > API

• Use mock data: The simulator generates fake data for the LoggingDataClient and ResourceDataClient.

  
  

• Use platform data: The simulator calls the platform API for the LoggingDataClient and ResourceDataClient.

  
  

Testing with different permissions

Permissions can, if needed, be simulated as well.

Settings (Cogwheel) > API > Permissions

• Standard permissions: When using mock data, no permissions are given. If platform data is used, the user's actual permissions are given.

  
  

• Use fixed permissions: The selected permissions are given. This can only be used with mock data.