Setup and start - Atoti Hub

This guide explains how to create a Spring Boot application with an Atoti Enterprise Risk Suite solution. The result is a running application, configurable and extensible using the Atoti Configuration API. The same API is used to customize the solution’s default database and cube behavior, and to add new cubes. Setup involves the following steps:

Generate an application from the archetype
Configure the application properties
Run the application

Prerequisites

Java 25 or later installed.
Apache Maven 3.9+ installed.
Access to the ActiveViam Maven repository (atoti-solutions-mvn).
A valid Atoti license, configured via the ATOTI_LICENSE environment variable (base64-encoded string) or file path. See Getting Started: License.

Step 1: Generate the application

Use the solution-app-archetype to generate a ready-to-run application. The archetype is published to the ActiveViam Maven repository. Run the following command:

mvn archetype:generate \
  -DarchetypeGroupId=com.activeviam.solutions \
  -DarchetypeArtifactId=solution-app-archetype \
  -DarchetypeVersion=${solutions.version} \
  -DgroupId=com.activeviam.myapp \
  -DartifactId=my-app \
  -Dpackage=com.activeviam.myapp \
  -DapplicationName=MyApp \
  -DstarterGroupId=${starter.groupId} \
  -DstarterArtifactId=${starter.artifactId} \
  -DstarterVersion=${solutions.version} \
  -DinteractiveMode=false

Replace ${solutions.version} with the target release version, and ${starter.groupId} and ${starter.artifactId} with the coordinates for the chosen solution. The following table lists the available starters:

Solution	starterGroupId	starterArtifactId
Market Risk (Enterprise Risk)	`com.activeviam.springboot`	`var-cube-starter`
Counterparty Credit Risk (Enterprise Risk), PFE	`com.activeviam.springboot`	`pfe-cube-starter`
Counterparty Credit Risk (Enterprise Risk), Ratings	`com.activeviam.springboot`	`ratings-cube-starter`

For Counterparty Credit Risk (Enterprise Risk), each cube has its own starter. See PFE setup and start and Ratings setup and start.

Note: If your artifactId contains hyphens (e.g., my-app), set package to a valid Java package name (e.g., -Dpackage=com.activeviam.myapp).

Generated project structure

The archetype generates a complete Spring Boot application:

my-app/
├── pom.xml
├── src/main/java/com/activeviam/myapp/
│   ├── MyAppApplication.java                  # Entry point; opts into as-of-date data loading
│   ├── ModelConfigurer.java                   # Hook for custom database/cube configuration
│   ├── security/                              # Authentication and security filters
│   └── ui/
│       └── CustomUiEnvJsResourceConfig.java   # UI configuration
├── src/main/resources/
│   ├── application.yml
│   ├── i18n/en-US                             # Atoti UI translations
│   └── static/atoti-ui/
│       └── extensions.json
└── src/test/
    ├── java/com/activeviam/myapp/
    │   └── MyAppApplicationIT.java            # Context-load integration test
    └── resources/
        └── application-it.yml                 # Binds a free port for the test above

Step 2: Configure the application properties

The generated application.yml provides sensible defaults that are sufficient to start the application without changes. Customize cube behavior by editing src/main/resources/application.yml. For solution-specific properties, refer to the configuration properties page for the chosen solution.

How to customize the application

The generated ModelConfigurer.java is the entry point for extending the default configuration of any solution. It implements IModelConfigurer, which exposes two methods:

configureDatabase(IDatabaseConfigurator): defines tables and joins in the database
configureCubes(ICubeManagerConfigurator): defines cubes, dimensions, and measures

The generated class is a stub with a commented-out cube field. Once wired to a cube, it has the following shape:

@RequiredArgsConstructor
public static class ModelConfigurer implements IModelConfigurer {
  // Inject your solution's cube interface, for example IVaRCube.
  private final ObjectProvider<ISolutionCube<?, ?, ?, ?>> cube;
  @Override
  public void configureDatabase(final IDatabaseConfigurator databaseConfigurator) {
    // Add tables, fields and joins here, referencing them through
    // cube.getObject().databaseModel().
  }
  @Override
  public void configureCubes(
      final ICubeManagerConfigurator cubeManagerConfigurator,
      final IDatabaseSchema databaseSchema) {
    cube.ifAvailable(
        solutionCube -> {
          final var measuresConfigurator =
              cubeManagerConfigurator.cube(solutionCube.name()).measures();
          // Build on solutionCube.measures() to add measures of your own.
          measuresConfigurator.addMeasure("Contributors Count", Copper.count());
        });
  }
}

Replace ISolutionCube<?, ?, ?, ?> with the cube interface of the solution. The table below lists them.

Solution	Cube interface	Registered by	Public API
Market Risk (Enterprise Risk)	`IVaRCube`	`var-cube-starter`	Public API
Counterparty Credit Risk (Enterprise Risk), PFE	`IPfeCube`	`pfe-cube-starter`	PFE public API
Counterparty Credit Risk (Enterprise Risk), Ratings	`IRatingsCube`	`ratings-cube-starter`	Ratings public API

Inject the cube through ObjectProvider when the cube can be disabled. The configurer then still loads when the cube is off, and ifAvailable runs only when the cube is present. A cube that is always on can be injected directly. An application that runs several cubes injects one ObjectProvider per cube. The generated class is a top-level class annotated with @Configuration, which registers it as a Spring bean. For examples of how to use each method, see Customizing the data model, Dimensions, and Measures.

Data loading

Each solution ships the channels and CSV topics that describe how its cube is fed, and an alias grouping them that it publishes through its topics bean (I[Cube name]CubeTopics). Point them at your files with atoti.solution.data-load.csv.base-path, and set topic-type to read from a cloud bucket or the local filesystem. Requesting a load is the application’s part, and the generated application already opts in. @Import(AsOfDateDataLoadConfiguration.class) on the application class gives it the startup load, the /activeviam/as-of-date/rest/v1 endpoints, and the load and unload events. What is left to fill in is what to load and when:

atoti:
  solution:
    data-load:
      csv:
        base-path: ./data/#{AS_OF_DATE}
      as-of-date:
        # One alias per starter this application depends on.
        topics:
          - PFE_LOAD
        unload-topics:
          - PFE_UNLOAD
        initial-dates:
          enabled: true
          dates:
            - 2024-03-04

Until topics names something, the application starts and serves its cube but loads nothing. To go further than the properties (repoint a topic at your own files, or attach a table of your own to one the solution already reads), publish an IDataLoadConfigurer bean. Inject the solution’s channel and topic name beans alongside it (e.g. IPfeCubeChannels and IPfeCubeTopics) and take every channel and topic name from them rather than writing the name out. Data loading covers the full property set and shows both overrides.

Step 3: Run the application

Start the Spring Boot application. The default server port is 9090, configured in src/main/resources/application.yml. To confirm the cube is available, query the cube discovery endpoint. The generated application includes a default admin user (password: admin):

http://localhost:9090/activeviam/pivot/rest/v10/cube/discovery

To explore the cube in a browser, see How to access Atoti UI and Atoti Admin UI.

Optional: How to enable the health endpoint

The Spring Boot Actuator health endpoint is not exposed by default. To enable it, add the following to your application.yml:

management:
  endpoints:
    web:
      exposure:
        include: health

Verify the application status at:

http://localhost:9090/actuator/health

Expected output:

{"status": "UP"}

How to access Atoti UI and Atoti Admin UI

The application serves two web interfaces next to the cube:

Atoti UI is where users build dashboards and explore the data of the cube.
Atoti Admin UI is where administrators monitor the server, manage users, inspect the datastore, and perform other administrative tasks.

On the default port, they are available at:

Interface	URL
Atoti UI	`http://localhost:9090/ui`
Atoti Admin UI	`http://localhost:9090/admin/ui`

For an application that listens elsewhere, use http://<host>:<port>/ui and http://<host>:<port>/admin/ui. Every solution starter and cube starter brings atoti-ui-starter and atoti-admin-ui-starter, so no additional server-side configuration is needed to expose a cube to either interface. An application generated from the archetype already contains the environment configuration both interfaces read (CustomUiEnvJsResourceConfig). Sign in with a user the application defines, such as the default admin user of the generated application. For the use of Atoti UI, see the Atoti UI documentation.

​Prerequisites

​Step 1: Generate the application

​Generated project structure

​Step 2: Configure the application properties

​How to customize the application

​Data loading

​Step 3: Run the application

​Optional: How to enable the health endpoint

​How to access Atoti UI and Atoti Admin UI

​Related pages