Navigation :

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

JDK21 +
Maven 3.8+

Artifactory Access

Please ensure you have access to our private Maven repositories in your Maven settings.xml file before installation. You will need access to the following repositories:

Atoti Server repository

This repository contains all the dependencies required to run Atoti Server. Atoti Limits is itself an Atoti Server product, which is why this repository is required.

<repository>
    <id>ActiveViamInternalRepository</id>
    <name>ActiveViam Internal Repository</name>
    <url>https://activeviam.jfrog.io/activeviam/mvn-internal/</url>
    <layout>default</layout>
    <snapshots>
        <enabled>false</enabled>
    </snapshots>
</repository>

Business Solutions server repository

This repository contains all the dependencies required to run ActiveViam Business Solutions.


<repository>
    <id>ActiveViamBusinessSolutionsRepository</id>
    <name>ActiveViam Business Solutions Repository</name>
    <url>https://activeviam.jfrog.io/activeviam/activeviam-mvn-accelerators/</url>
    <layout>default</layout>
    <snapshots>
        <enabled>false</enabled>
    </snapshots>
</repository>

Business Solutions UI repository

To download the dependencies for the UI, you need to set up access to Artifactory via npm:

npm login --scope @activeviam --registry https://activeviam.jfrog.io/artifactory/api/npm/activeviam-npm-accelerators/

The result is the following message: Logged in as username to scope @activeviam on https://activeviam.jfrog.io/artifactory/api/npm/activeviam-npm-accelerators/.

If the scope isn’t mentioned in the message, change the command to the following:

npm login --scope=@activeviam --registry=https://activeviam.jfrog.io/artifactory/api/npm/activeviam-npm-accelerators/

License

To use Atoti Server, you will need a valid license. Atoti Limits is itself an Atoti Server product, which is why this license is required. For details on how to install the license, see the Atoti Server documentation.

Installing the Starter Project

The starter project is a reference Spring Boot application that demonstrates how to use Atoti Limits. It contains the default configurations and workflows. It can be configured, customized, or extended for your specific use cases using Spring.

To install the starter project:

Download the Atoti Limits source code. This contains the starter project and the parent pom file.
Extract the source code folder into your workspace.
Open the project in your IDE.
Run mvn clean install.

This will compile the source code, run tests, and package the application. You may exclude test execution by running mvn clean install -DskipTests.

Running the Starter

Start the application with:

Windows:

    java 
    --add-opens=java.base/java.util=ALL-UNNAMED
    --add-opens=java.base/java.util.concurrent=ALL-UNNAMED
    -Dlimits.dlc.root-dir=<path\to\data-samples> 
    -jar <path to>/limits-starter-<version>-exec.jar

MacOS/Linux:

   java
   --add-opens=java.base/java.util=ALL-UNNAMED
   --add-opens=java.base/java.util.concurrent=ALL-UNNAMED
   -Dlimits.dlc.root-dir=<path\to\data-samples> 
   -Dactiveviam.chunkAllocatorKey=mmap 
   -jar <path to>/limits-starter-<version>-exec.jar

By default, the application starts on http://localhost:3090.

Alternatively, if using your IDE, run the com.activeviam.solutions.limits.starter.Limits class.

Atoti Limits UI

For details on activating the UI features, see UI Activation.

Connecting Atoti Limits to your Atoti server

In order to start loading data and evaluating limits, Atoti Limits must be connected to your Atoti server. Atoti Limits utilizes Spring Auto-configuration to create the connection to your Atoti server, minimizing the amount of manual configuration required. Atoti Limits also supports connections to multiple Atoti servers to allow for managing limits across multiple applications in one place.

See How to Integrate Limits to an Atoti Server for details on how to set up the connection between Atoti Limits and your Atoti server(s).

Customizing the Starter

The following section outlines how to modify the starter project to suit your needs. We recommend that you make changes in the following order:

Configurations: these are usually non-code related changes and are the easiest to migrate.
Customizations: these are usually code additions that can be easily “swapped in” to the existing codebase to either safely override or augment existing functionality.
Overrides: these are usually code changes that require a more in-depth understanding of the codebase and may require changes to existing code. These are the hardest to migrate, and if you need to do them we recommend you raise a Jira for us to see if there is a better alternative or if there is a gap in our product that needs to be addressed.

1. Configurations

We recommend that you configure the application as much as possible before customizing existing code. The following configurations are commonly used:

Configuring Application Properties

Application properties are used to configure functionality of Atoti Limits and most of its dependencies. These can be found in the properties section and updated by modifying the src/main/resources/application.yml file, or by using environment variables.

Database Configuration with Spring JPA

By default, the application uses an in-memory H2 database and expects any initial data to be loaded from CSV files.

info

Using the H2 database in production is not recommended. Instead, please use a production-grade database. There is none in particular that we recommend, but popular choices include:

If you wish to persist Atoti Limits data to an external database, you’ll need to configure the database connection in the application.yml file. You will need to create and deploy your own database server, but once the connection is configured, Atoti Limits will automatically create the required tables and schemas for you. See Persistence for more information on how to set up the database connection.

Performance

Depending on a multitude of factors, such as the number of limits you have, the cardinality of the scopes for your limits, and/or the volume/schema of the data in the connected Atoti server, the performance of your Atoti Limits implementation may vary. See Performance for information on options to improve performance.

2. Customizations

info

When you add new code as a customization to the starter project, we highly recommend that you use your own package name and avoid using the com.activeviam package. This will separate your code from our code and make it much easier to migrate. All customizations should be done in the limits-starter module, or in a separate module that depends on limits-starter.

Customizing via Spring Beans

The application follows Spring best practices. To customize, you can override existing beans and components by defining them in your application. This is the safest form of overriding or augmenting existing code behavior. We aim to use @ConditionalOnMissingBean as much as possible to allow for easy customization. If we have not exposed a bean you wish to override as @ConditionalOnMissingBean, please raise a Jira with us and mark your bean as @Primary.

Activiti Workflow Customization

The application includes default Activiti workflows located in src/main/resources/processes/. See Limit Workflow for information on the default workflows. If you want to use custom workflows, you need to:

Create your BPMN file. You can either edit the existing BPMN files or use a BPMN editor, such as BPMN.io.
Import any Spring beans or services required by your workflow. This is detailed further in adding custom workflow tasks.
Add the new processes in src/main/resources/processes/.
Restart the application to ensure the changes are picked up.

Security customizations

The application comes with a default security configuration using Spring security. You need to customize this by implementing your own security configuration. This is done by implementing and exposing the following interfaces:

com.activeviam.web.spring.api.config.ICorsConfig: This interface is used to configure CORS settings.
org.springframework.security.web.SecurityFilterChain: This interface is used to configure security filters for REST requests.
org.springframework.security.core.userdetails.UserDetailsService: This interface is used to load user-specific data.

Roles and permissions

Configure the roles assigned to users to control what actions users can perform and assign permissions to custom roles to control what data they can access in Atoti Limits. See Roles and Permissions for more information on the default roles provided by Atoti Limits and how to configure custom roles and permissions.

Other customizations

The ability to customize the application is not limited to these examples. Please see the Extending the Module section for more in-depth information on the different ways you can customize the application.

3. Override

If you cannot configure or customize the application to meet your requirements, you may need to override the application. This is the most complex form of modification as it requires an in-depth knowledge of the core codebase and may result in unintended consequences. It is also the most difficult code to migrate, because it may be difficult to remember if the code was an override in the first place or is a legitimate starter class. We recommend adding a javadoc to differentiate overrides from released source code.

warning

If you need to override our code we recommend that you raise a Jira ticket with us to see if there is a better alternative or if there is a gap in our product that needs to be addressed.

Migrating Atoti Limits

When migrating to a new version of Atoti Limits, we recommend the following steps:

Ensure your code customizations are under a separate package name from the com.activeviam package.
Create a new branch in your VCS for the upgrade.
If you have overridden any of our code, move it to a tmp.com.activiam package. This should only apply to overrides, not to starter code.
Install the starter project for your new version, replacing the old starter com.activeviam packages with the new packages.
Verify if any of the tmp.com.activeviam code can be removed. If so, remove it, otherwise, please raise a Jira and merge it with the new code.
Run mvn clean install
If you have any compilation errors, consult the migration notes in the release notes for the new version.
Repeat steps 6-7 until the code compiles and is correctly installed.

Usage

Atoti Limits can be integrated with any Atoti Server instance with the same version. For more information, see How to Connect Limits to an Atoti Server.

As Of Date

The file as_of_date.csv sets the asOfDate for the limits application. This asOfDate is used for evaluating limits against connected Solutions.

Limit structures

A limit structure defines the business details for a collection of limits and serves as the parent to those limits. Due to this relationship, limit structures are required to be created before you can start creating limits. You can configure Atoti Limits to load limit structures from a CSV file or database as part of the initial load when the application is started, or manually create them at runtime via file upload or using the form in the UI.

Limits

A limit is a business rule that defines a threshold for a specific metric on a given scope. Every limit is associated with a limit structure, which defines the business details for all limits in the structure. If the parent structures are defined in a CSV file or database and loaded at startup, the associated limits can also be loaded at startup from a CSV file or database. You can also create limits manually at runtime via file upload or using the form in the UI.

EvaluationTasks and the Incidents store

EvaluationTasks are created for each limit in the Limits store, which evaluates whether a limit is in breach or warning state. The PollingFrequency field of a limit determines how often an EvaluationTask is run. When limits are in breach or warning status, the EvaluationTask writes to a file named incidents.csv. You can find this file in today’s date folder inside the directory src/test/resources/data-damples/data/{serverName}/incident. The files generated here will populate the Incidents store via a fetch topic on startup.

Limits ecosystem and architecture

In the ActiveViam ecosystem, Atoti Limits runs on its own JVM and is the one-stop shop to manage all the limits across all Atoti Server cubes. The workflow audit is automatically maintained in the persistent relational database. All users log into a combined Atoti UI to access all Atoti Server cubes.

Limits Ecosystem and Architecture

Frequently asked questions

I can’t download the starter project dependencies due to my company’s policy. What can I do?

We store Maven repositories for all of our artifacts on Artifactory. The core Atoti Server jars are available in the ActiveViam share page, as described in the Atoti Server download guide. From there you can download the Atoti Server 6.1.3 jars.

The Atoti Limits jars are available from the Business Solutions artifacts repository. From there you can download the Atoti Limits jars. Once downloaded, install these jars in your local repository and re-run the Maven build.