Presentation
NOTICE : This is the documentation of the next iteration of the Copper API.
The previous version of the Copper API has been deprecated.
From now on, in this guide, any mention of Copper or Copper 2 will refer to this version.
Copper is an API that helps you add measures and hierarchies to an ActivePivot Cube.
Its main goal is to provide a simple and comprehensive API to create all the measures an ActivePivot project might need.
This document is aimed at ActivePivot developers, and therefore contains references to multidimensional concepts such as datastores, store references, dimensions, hierarchies, levels, measures, locations, context values, and the MDX query language. Newcomers should be able to use Copper with only a minimal amount of ActivePivot-specific training, but it is advised to make sure to at least be familiar with these concepts before reading this.
Copper is used to add measures to a cube whose dimensions, hierarchies and levels are already defined, on top of an already defined datastore with an already defined selection. The datastore does not need to contain data for Copper to work. Additionaly, Copper can be used to enrich the cube with special hierarchies but we'll see that later.
Why the name "Copper"? Copper was originally intended as a contraction of "Core Post-Processors". It symbolizes a shift away from complex core logic and towards a simpler API for your client projects. Its features have been expanded since its creation to also include the creation of other types of measures (native measures, aggregated measures, etc.) as well as hierarchies.
Status
This version of the Copper API is shipped with ActivePivot 5.8.3 and will replace the previous CoPPer API in 5.9.0. There is already a wide range of features everyone can use, described in examples in the next sections. You are encouraged to use them and report to us any issue you encounter while trying them out in your projects; this will help us improve the API, discover new use cases, or improve our error messages.
Although the version 2 of the Copper API is production ready, it is released as an experimental feature for ActivePivot 5.8.X versions as future releases might include some breaking changes.
The official release will be with ActivePivot 5.9.0.
Retro-compatibility
Compatibility with the Core ActivePivot APIs
Copper aims to replace other previous ways of creating measures and hierarchies in ActivePivot. Eventually, we hope that it will become the standard way to do so.
Given that there are still some use cases and optimizations not yet covered by Copper, we have made it fully retro-compatible with "legacy" post-processors. The Copper API will allow you to:
- use measures that are already defined in your cube description, it includes all types of measures: native measures, aggregated measures and postprocessors.
- create post-processors "the old way" (with the plugin key and properties)
Being able to use and create post-processors in Copper will allow you to manage your migration incrementally.
Compatibility between versions of the Copper API
The different versions of the Copper API are not compatible as major concepts in the API have been overhauled. This is also the case for testing frameworks provided along with Copper.