How to use Atoti Server Extension to create your own measures

In this guide, we show the steps required to take full advantage of Atoti Server Extension to define and use your own measures and post-processors.

Prerequisites

This guide assumes you have already created a Maven project with atoti-server-extension-parent as described in the Atoti Server Extension reference.

1. Add atoti-server-extension-parent to your pom.xml

For a correct use of Atoti Server Extension, you need to add the atoti-server-extension-parent as a parent in the pom.xml file of your server extension project.

<parent>
    <groupId>io.atoti</groupId>
    <artifactId>atoti-server-extension-parent</artifactId>
</parent>

You can use {@mavenVersion: -} to specify the version of Atoti Server Extension you want to use.

2. Create a basic custom measure and register it

In this section, we show you how to create a custom measure and register it in the Atoti application. The steps are the same for every custom measure not requiring an underlying post-processor.

2.1 Create an argument class for your measure

Create a class that implements the empty interface com.activeviam.atoti.application.api.measures.IMeasureDefinition, this class should contain the arguments needed to compute the measure and optionally, the measure’s plugin key.
Arguments can be of any Java primitive type, or any types of identifier defined in Atoti (e.g. com.activeviam.activepivot.core.intf.api.cube.metadata.LevelIdentifier, com.activeviam.activepivot.core.intf.api.cube.metadata.HierarchyIdentifier, etc.).

/** Arguments for a measure increment its underlying measure. */
public record IncrementArguments(
    String underlyingMeasureName, LevelIdentifier perLevel, long increment)
    implements IMeasureDefinition {
  public static final String PLUGIN_KEY = "MY_INCREMENT";
  @Override
  public String getPluginKey() {
    return PLUGIN_KEY;
  }
}

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

2.2 Create your measure’s registration class

Once an argument class is defined, you are now able to create a com.activeviam.atoti.server.common.api.plugins.MeasureRegistration object specific to your measure, that will then be used to register the measure in the Atoti application.

private static MeasureRegistration<IncrementArguments> createIncrementRegistration() {
  return MeasureRegistration.<IncrementArguments>builder()
      .measureKey(IncrementArguments.PLUGIN_KEY)
      .definitionClass(IncrementArguments.class)
      .factory(
          (definition, environment) ->
              environment
                  .getMeasure(definition.underlyingMeasureName())
                  .getFormula()
                  .plus(Copper.constant(definition.increment()))
                  .per(Copper.level(definition.perLevel()))
                  .sum())
      .build();
}

You can also 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";
  @Override
  public String getPluginKey() {
    return PLUGIN_KEY;
  }
}
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();
}

2.3 Register your measure in the Atoti application

Once the measure registration class is ready, you can register your measure in the Atoti application using the com.activeviam.atoti.server.common.api.plugins.IPluginSetup bean.
You can do this in a Spring configuration class by defining a bean that returns a com.activeviam.atoti.server.common.api.plugins.PluginMeasureRegistrations object.

@Bean
@Lazy(false)
public PluginMeasureRegistrations pluginMeasureRegistrations(final IPluginSetup pluginInit) {
  return pluginInit.contributeMeasures().addMeasure(createIncrementRegistration()).build();
}

If you need to register multiple measures, they can all be added to the PluginMeasureRegistrations object returned by the contributeMeasures() method of the IPluginSetup bean.Example:

return pluginInit
    .contributeMeasures()
    .addMeasure(createAddOneRegistration())
    .addMeasure(createEverythingRegistration())
    .addMeasure(createEverythingMapRegistration())
    .build();

Once this is done, the measure is available on the start of your application. To know how to use it with Atoti Python SDK, head to the Atoti Python SDK documentation.

Don’t forget to import your measures configuration class (the class containing the @Bean method from step 2.3) in your @AutoConfiguration class using the @Import annotation. See section 4 for details.

3. Create a custom measure relying on a custom post-processor

In this section, we show you how to create a custom measure whose calculations rely on a custom post-processor.

3.1 Create a custom post-processor

You can create a custom post-processor by extending any class which already extends AAdvancedPostProcessor.
For example:

Creation of a basic post-processor

/** A post processor that adds one to the aggregated value. */
@AtotiExtendedPluginValue(intf = IPostProcessor.class, key = AddOnePostProcessor.PLUGIN_KEY)
public class AddOnePostProcessor extends ABasicPostProcessor {
  public static final String PLUGIN_KEY = "ADD_ONE";
  public AddOnePostProcessor(
      final String name, final IPostProcessorCreationContext creationContext) {
    super(name, creationContext);
  }
  @Override
  public void init(final Properties properties) throws ActiveViamException {
    properties.setProperty(OUTPUT_TYPE_PROPERTY, ILiteralType.DOUBLE);
    super.init(properties);
  }
  @Override
  public void evaluate(
      final ILocation location,
      final IRecordReader aggregatedMeasures,
      final IWritableCell resultCell) {
    resultCell.writeDouble(aggregatedMeasures.readDouble(0) + 1);
  }
  @Override
  public String getType() {
    return PLUGIN_KEY;
  }
}

3.2 Create a custom measure relying on the created post-processor

Once the post-processor is created, you can create a measure that relies on it by using very similar code to the one used in the Basic Custom Measure section:

You need to create an argument class that implementing IMeasureDefinition.

/** Arguments */
public class AddOneAndMultiplyArguments implements IMeasureDefinition {
  @Getter private final String underlyingMeasureName;
  @Getter private final double multiplier;
  public static final String PLUGIN_KEY = "ADD_ONE_AND_MULTIPLY";
  /** Creates a new instance of the arguments. */
  public AddOneAndMultiplyArguments(final String underlyingMeasureName, final double multiplier) {
    this.underlyingMeasureName = underlyingMeasureName;
    this.multiplier = multiplier;
  }
  @Override
  public String getPluginKey() {
    return PLUGIN_KEY;
  }
}

You need to create a MeasureRegistration object specifying the new post-processor that will be used to register the measure in the Atoti application, for example:

private static MeasureRegistration<AddOneAndMultiplyArguments> createAddOneRegistration() {
  return MeasureRegistration.<AddOneAndMultiplyArguments>builder()
      .measureKey(AddOneAndMultiplyArguments.PLUGIN_KEY)
      .definitionClass(AddOneAndMultiplyArguments.class)
      .factory(
          (definition, environment) ->
              Copper.newPostProcessor(AddOnePostProcessor.PLUGIN_KEY)
                  .withUnderlyingMeasures(
                      environment.getMeasure(definition.getUnderlyingMeasureName()).getFormula())
                  .withType(Types.TYPE_DOUBLE)
                  .multiply(Copper.constant(definition.getMultiplier())))
      .build();
}

3.3 Register the post-processor

One the post-processor and the measure are created, you need to manually register the created post-processor in the Atoti application registry:

/** Registers the percentage post processor. */
public void registerAddOnePostProcessor() {
  Registry.getExtendedPlugin(IPostProcessor.class)
      .add(AddOnePostProcessor.PLUGIN_KEY, "Add one post processor", AddOnePostProcessor.class);
}

3.4 Register the measure

Finally, you can register the measure in the Atoti application using the IPluginSetup bean as shown in the Basic Custom Measure section. The post-processor must also be registered in the PluginMeasureRegistrations bean definition.

4. Import your measures configuration in your project’s AutoConfiguration

Once you have created your measures configuration class (e.g., ServerExtensionMeasuresConfig), you must import it in your extension’s @AutoConfiguration class to make it available to the Atoti application see.

@AutoConfiguration
@Import({
  ServerExtensionMeasuresConfig.class,  // Import your measures configuration
  // Add other configuration classes as needed
})
public class ExtensionAutoConfiguration {}

Without this import, Spring Boot will not register your measures even if they are correctly configured. Once this is done, the measure will be available on the start of your application, to know how to use it with Atoti Python SDK, head to the Atoti Python SDK plugin_measure documentation.

Releases and upgrades

Getting started

Concepts

Step 1: Bring your data into Atoti

Step 2: Design your Cube

Step 3: Build an Atoti application

Step 4: Query an Atoti application

Configure Atoti

Secure Atoti

Operate Atoti

Reference

How to use Atoti Server Extension to create your own measures

Prerequisites

1. Add atoti-server-extension-parent to your pom.xml

2. Create a basic custom measure and register it

2.1 Create an argument class for your measure

2.2 Create your measure’s registration class

2.3 Register your measure in the Atoti application

3. Create a custom measure relying on a custom post-processor

3.1 Create a custom post-processor

3.2 Create a custom measure relying on the created post-processor

3.3 Register the post-processor

3.4 Register the measure

4. Import your measures configuration in your project’s AutoConfiguration

​Prerequisites

​1. Add atoti-server-extension-parent to your pom.xml

​2. Create a basic custom measure and register it

​2.1 Create an argument class for your measure

​2.2 Create your measure’s registration class

​2.3 Register your measure in the Atoti application

​3. Create a custom measure relying on a custom post-processor

​3.1 Create a custom post-processor

​3.2 Create a custom measure relying on the created post-processor

​3.3 Register the post-processor

​3.4 Register the measure

​4. Import your measures configuration in your project’s AutoConfiguration

Prerequisites

1. Add atoti-server-extension-parent to your pom.xml

2. Create a basic custom measure and register it

2.1 Create an argument class for your measure

2.2 Create your measure’s registration class

2.3 Register your measure in the Atoti application

3. Create a custom measure relying on a custom post-processor

3.1 Create a custom post-processor

3.2 Create a custom measure relying on the created post-processor

3.3 Register the post-processor

3.4 Register the measure

4. Import your measures configuration in your project’s AutoConfiguration