Skip to main content

Atoti Runtime Plugin reference page

Introduction​

note

This feature was developed to be used in association with Atoti Python SDK, it helps user define complex components that cannot be defined using Python alone.

Atoti Runtime Plugin allows you to create an extension to the basic Atoti Runtime application, where you to define new components and functionalities that can be used in your Atoti applications such as custom measures, post-processors and REST endpoints with custom security.

Configuration​

To use Atoti Runtime Plugin, the first step is to create a new Maven project with the atoti-runtime-plugin-parent as the parent POM. This can be done by using the Atoti Maven Archetype:

<parent>
    <groupId>io.atoti</groupId>
    <artifactId>atoti-runtime-plugin-parent</artifactId>
</parent>

You can use 6.1.9-SNAPSHOT to specify the version of Atoti Runtime Plugin you want to use.

Child POMs using atoti-runtime-plugin-parent as their parent inherit:

  • Standard Atoti plugin dependencies with managed versions and provided scope, ready for plugin development.
  • Java 21 compiler settings for consistent builds.
  • Maven Compiler Plugin configuration, including annotation processors (Lombok, Spring Boot).
  • Assembly profile for packaging plugins using the Atoti assembly descriptor.
  • Distribution management setup for publishing artifacts.
  • Best practices for plugin structure and build, reducing boilerplate and ensuring compatibility with Atoti Runtime.

Features​

In this section, you can find the features that are available through Atoti Runtime Plugin.

Beans provided by Atoti Runtime Plugin​

When using Atoti Runtime Plugin, you are guaranteed to have access to the following beans:

  • IActivePivotManager
  • IDatabase
  • IDatastore
  • IContentService
  • IPluginSetup which is used to register custom measures and post-processors see.

Those Beans can prove useful when you want to create post-processors or want to interact with the Atoti application in a more advanced way in a custom REST controller.

Custom Measures and Post-processors​

Atoti Runtime Plugin allows you to create custom measures and post-processors that can be used in your Atoti applications.

A detailed guide on how to create custom measures and post-processors can be found in the custom measures and post-processors page.

note

Something not mentioned in the how-to is that you can specify a formatter when creating your custom measure formula by overriding IFormulaFactory.computeFormatter()

Example

/** Arguments class for multiply by two measure. */
public record MultiplyByTwoArguments(String underlyingMeasureName, LevelIdentifier perLevel)
    implements IMeasureDefinition {
  public static final String PLUGIN_KEY = "INCREMENT_BY_ONE";
}
private MeasureRegistration<MultiplyByTwoArguments> createMultiplyByTwoRegistration() {
  return MeasureRegistration.<MultiplyByTwoArguments>builder()
      .measureKey(MultiplyByTwoArguments.PLUGIN_KEY)
      .definitionClass(MultiplyByTwoArguments.class)
      .factory(
          new IFormulaFactory<>() {
            @Override
            public CopperMeasure buildFormula(
                final MultiplyByTwoArguments definition,
                final IFormulaFactoryEnvironment environment) {
              return environment
                  .getMeasure(definition.underlyingMeasureName())
                  .getFormula()
                  .multiply(Copper.constant(2))
                  .per(Copper.level(definition.perLevel()))
                  .sum();
            }
            @Override
            public Optional<String> computeFormatter(
                final MultiplyByTwoArguments definition, final IFieldType outputType) {
              if (outputType.isPrimitive() && outputType.getContentType() == ContentType.DOUBLE) {
                return Optional.of("DOUBLE[#,###.###]");
              } else {
                throw new IllegalStateException(
                    "Underlying value should be of type double, but got " + outputType);
              }
            }
          })
      .build();
}

The arguments passed to the custom measures inside a IMeasureDefinition from Python are of the following types:

  • Any Java primitive type (e.g. int, double, boolean, etc.)
  • LevelIdentifier
  • HierarchyIdentifier
  • StoreField
  • Measure name as a String
  • Column name as a String
  • Dimension name as a String
  • Any array/tuple and map of the above types

Custom REST Endpoints​

Atoti Runtime Plugin allows you to create custom REST endpoints that can be used in your Atoti applications.
A detailed guide on how to apply your custom security with DSLs provided by Atoti Runtime to your REST endpoints can be found in the custom REST security page.

About Python SDK​

This feature is supposed to be used in association with the Atoti Python SDK, once the jar for your plugin is created on build, you can provide it to the Python session config as an extra_jars.