Modeler IDE Reference Manual


About This Manual

This is the Reference Manual for the LogicBlox Modeler Configuration Tool which is also referred to as the Modeler IDE. This manual will lead you through the various aspects involved in configuring and building a LogicBlox Modeler IDE application.

Note

In this manual, we assume that you already are familiar with the Modeler and LogicBlox's implementation of online analytical processing (OLAP) and its three primary concepts: levels, dimensions, and measures. An overview of the basic concepts of the Measure Service can be found in the LogicBlox Core Reference Manual.

Part I. Getting Started

1. Installing LogicBlox development environment

The Modeler IDE is part of the LogicBlox platform. This section describes how to obtain and install LogicBlox, and how to start using the Modeler IDE.

1.1. Install your development environment

Download the latest version of LogicBlox for your platform (Linux or macOS).

Follow the installation instructions on the LogicBlox download page. More details on how to use the LogicBlox services can be found in the LogicBlox Core Reference Manual.

Tip

You need to have Java 8 installed. Java can be downloaded from oracle.com/java. You can check which version you have installed by running the following command:

$ java -version

java version "1.8.0_192"
Java(TM) SE Runtime Environment (build 1.8.0_192-b12)
Java HotSpot(TM) 64-Bit Server VM (build 25.192-b12, mixed mode)

You also need to have Python 3.5 or newer installed. Python can be downloaded from python.org. You can check which version you have installed by running the following command:

$ python --version

Python 3.5.8

1.2. Verify your development environment

You can verify your LogicBlox installation by checking the status of the services by typing the following command on the command-line:

$ lb services status

lb-compiler-server       : running
lb-server                : running
lb-web-server            : running

If your services are not running yet, you can start them with the following command:

$ lb services start

2. Using the Modeler IDE

The Modeler IDE is distributed together with LogicBlox as a stand-alone desktop application (Linux or macOS) called "Modeler Configuration Tool" and can be found in the ide directory of the LogicBlox installation package.

When you run the Modeler IDE for the first time you can choose between creating a new project and opening an existing project:

Select "Create Project" to create a new project or select "Open Project" to open an existing project.

Part II. Settings

1. Creating and Opening Projects

When you run the Modeler IDE for the first time you can choose between creating a new project and opening an existing project:

Select "Create Project" to create a new project or select "Open Project" to open an existing project. Previously created or opened Modeler IDE projects will be displayed under "Recent Projects". This allows you to quickly switch between projects.

The next time you start the Modeler IDE, it will automatically open the most recent project for you.

2. Modeler Application Settings

The "Settings" view of the Modeler IDE allows you to manage your Modeler application settings. Use the "Change" button to under "Current Project" to switch between Modeler IDE projects.

The Modeler application settings are stored in a JSON file called project_config.json in the root of your Modeler IDE project. To inspect the contents of this JSON, select the "Preview JSON Config" option.

2.1. General Settings

The "General" tab of the "Settings" view contains the following settings:

SettingDescription
NameThe name of your Modeler IDE project.
WorkspaceThe name of the LogicBlox workspace used by your Modeler application.
Application PrefixThe application prefix for your Modeler application.
Project FileThe LogiQL project file which contains the configuration of the LogiQL library for your Modeler application.
Deployment User The LDAP account to be used for deployment via the NixOps Dashboard. Please note, deployment of your Modeler application via the Modeler IDE is not supported yet.

Add additional dependencies to the Modeler IDE project by selecting the "Add Dependency" option. Existing additional dependencies can be removed using the "Remove" button.

Tip

You may use environment variables in the pathname of your dependencies.

2.2. Modeling Features

The "Modeling Features" tab of the "Settings" view contains the following settings:

SettingDescription
Root Prefix The root URL prefix to add to all Modeler application routes as seen by the user in their browser.
Navigation Tree ID The ID of the default navigation tree of the Modeler application. Please note, this setting should not be set if "Display Workbook List" is set.
RealmThe name of the realm with which to authenticate.
Level Members Quantity Threshold The display limit of the level members size. The default for this setting is 10.000 level members.
Is Partitioned This flag will change the /commit and /refresh services to be prefixed by the workbook ID.
Display Workbook list Whether the workbook list should be the default page. Please note, this setting should not be set if a "Navigation Tree ID" is set.
Disable Filter Query Disables the query that is used to determine if cells have failed to pass a filter. This option is typically used to analyze performance problems.
Enable JSON View Should the menu bar button to view a sheet in JSON mode be present.
Allow User Defined Sheets Allows users to create their own sheets or copy existing views.
Enable Schema Editing Allows users to create new level members and modify level mappings.
Enable Data Import Enables the data import view for all users

The following settings related to Modeler's Chart Mode can be made visible by selecting the "Show More" option under "Chart Settings".

Chart SettingDescription
Export As PNG Display the "Export As PNG" button in Chart Mode.
View Source Display the "View Source" button in Chart Mode.
Open In Vega Editor Display the "Open in Vega Editor" button in Chart Mode.
Complexity Index Threshold The default for this setting is 500.000.
Loading Cells Threshold The default for this setting is 45.000.

The following settings related to Modeler's collaboration features can be made visible by selecting the "Show More" option under "Collaboration".

Collaboration SettingDescription
Min Update Interval The minimum amount of time to wait to requery data after a collaboration message has been received (in seconds). The default for this setting is 0 seconds.
Max Update Interval The maximum amount of time to wait to requery data after a collaboration message has been received (in seconds). The default for this setting is 6 seconds.

The following settings related to Modeler's session timeouts can be made visible by selecting the "Show More" option under "Idle Time Values".

Idle Time Values SettingDescription
Idle Notification Time The number of seconds of inactivity before the Modeler application shows the inactivity message. The default for this setting is 1.800 seconds.
Idle Logout Time The number of seconds after the inactivity notification window has been displayed that the user has to resume their sesion before they are logged out. The default for this setting is 60 seconds.
Ignore Broadcasting Time The number of seconds of inactivity before the user's session stops responding to collaboration messages. The default for this setting is 300 seconds.

2.3. Branding

The "Branding" tab of the "Settings" view contains the following settings:

SettingDescription
Image URL Path to the image which should be used as the application logo.
Image Alt Text Alternative text for the image.
Redirect URLThe URL to redirect to when clicking on the logo of the Modeler application.

2.4. Header Action Buttons

Add a new action button to the menu bar of your Modeler application by selecting the "+ Add Action Button" option. Each configured action button has the following settings:

Action Button SettingDescription
Action ID The ID of the action to call for this action button.
Action Label The label for the action button.

Remove an existing action button configuration by clicking on the trash can icon.

2.5. Internationalization

The "Internationalization" tab of the "Settings" view contains the following settings:

SettingDescription
Translations Debug A flag to enable i18n debug messages like missing keys.

Add a new languages as an available language to the Language Selector of your Modeler application by selecting the "+ Add Language" option. Each configured language has the following settings:

Language SettingDescription
Language A dropdown list with all languages that can be configured.
Value The locale identifier of the configured language (e.g. en-US for US English).
Name How the language name should be shown in the Language Selector of your Modeler application.

Remove a language configuration by clicking on the trash can icon.

2.6. URLs

The "URLs" tab of the "Settings" view contains the following settings:

SettingDescription
Login URL Custom URL of the login service.
Add Block Service URL Custom relative URL for the addblock service.
Exec Block Service URLCustom relative URL for the exec service.
Measure Service URL Custom relative URL for the measure service.
Measure Config URL Custom relative URL for querying measure formatting configuration.
Navigation Tree URL Custom relative URL for the navigation tree service.
User Broadcast URL Custom URL for the websocket service.
Current User URL Custom URL for the current user service that allows the "Current Users" widget of the Modeler application to correctly determine and display the other users looking at the same workbook.
LB Web Admin URL Custom relative URL the lb web admin service. This setting is typically used for testing purposes only.

Part III. Model

1. Measure Components

The "Measure Components" view of the Modeler IDE allows you to manage the measure components of your Modeler application. This view contains a table which gives you an overview of all configured measure components with a summary of their settings:

The following user actions are supported in this view:

  • Manage the configuration of an existing measure component by clicking on its row in the table.
  • Change the order in which measure component will be applied in measure variants by dragging and dropping it to another position in the table.
  • Add a new measure component to your Modeler application by selecting the "+ New" option.
  • Remove an existing measure component by clicking on the trash can icon.

Use Cases

Measure components are commonly used in planning applications to automate the creation of Measure Variants. For example, a retail planning application will typically contain measures that hold Sales and Returns data. This data can be measured in various units of measurements (UOM) such as in units and dollar amounts. Furthermore, the dollar amount could be cost or retail.

Similarly, we can keep track of different versions of our measures. Versions are used to indicate whether measure values are actuals, planned, or approved. Common actual versions are This Year (TY), Last Year (LY), and Last Last Year (LLY) where TY data typically originates from an upstream system, and LY and LLY are time-shifted TY values. A common planned version is the Working Plan (WP) and a common approved version is the Approved Plan (AP).

In planning applications, you will usually also find users who have different roles within the planning process. For instance, a manager could set targets for Sales and Returns at the Class,Region,Week intersection. And on its turn, a planner could work on a plan at the Sku,Store,Week intersection to achieve these targets.

Each measure component can be used to define Override Settings for certain aspects of a measure variant such as its value type, base intersection, and default aggregation method. Some examples:

  • Unit of measure (UOM) implies the value type and formatting of the measure variant. For instance, we probably want to use Decimal as the value type and Currency as the formatting for a measure variant that holds a retail dollar amount.
  • Role implies the base intersection of the measure variant. For instance, the Sales measure variant for a planner could have Sku,Store,Week as its intersection while the measure variant for the manager has Class,Region,Week as its base intersection.

1.1. Managing Measure Component Configuration

The following example shows how the measure component Unit of Measure (UOM) of an example application is configured in the Modeler IDE.

This view shows the list of measure component items that have been defined for this measure component: Retail dollar (R), Units (U), and Average Unit Retail (AUR).

The following user actions are supported in this view:

  • Manage the settings of the selected measure component by clicking on the pencil icon next to the measure component name.
  • Manage the configuration of an existing measure component item by clicking on its row in the table.
  • Add a new item to the measure component by selecting the "+ New" option.
  • Remove an existing item from the measure component by clicking on the trash can icon.

1.2. Measure Component Settings

When managing the settings of a measure component, the "Measure Components" view allows you to configure the following settings:

SettingDescription
NameThe name of the measure component.
LabelThe label of the measure component.

1.3. Measure Component Item Settings

When managing the settings of an item of a measure component, the "Measure Components" view allows you to configure the following settings:

SettingDescription
NameThe name of the item.
LabelThe label of the item.

Add a new override to this measure component item by selecting the "+ Add Override" option. The following overrides are supported:

  • Intersection
  • Value Type
  • Default Value
  • Aggregation Method
  • Spread Method
  • Empty Value
  • Horizontal Alignment
  • Base Ambiguous
  • Read Only
  • Cell Type

Every override has its own set of Override Settings.

Remove an override by clicking on the trash can icon.

1.4. Override Settings

1.4.1. Intersection

SettingDescription
Intersection The base intersection for measure variants that use this measure component item.

1.4.2. Value Type

SettingDescription
Value Type The value type for measure variants that use this measure component item.

1.4.3. Default Value

SettingDescription
Default Value The default value for measure variants that use this measure component item.

1.4.4. Aggregation Method

SettingDescription
Aggregation Method The default aggregation method for measure variants that use this measure component item.

1.4.5. Spread Method

SettingDescription
Spread Method The default spread method for measure variants that use this measure component item.

1.4.6. Empty Value

SettingDescription
Empty Value The empty value for measure variants that use this measure component item.

1.4.7. Format

SettingDescription
What Kind Of Format? The type of formatting to apply on data for measure variants that use this measure component item. The Modeler IDE shows a preview of the configured formatting.
Currency Symbol The currency symbol to use for this value (e.g. $ or ). This option is only visible when the formatting is of type "Currency".
Symbol Position The position of the currency or percent symbol in relation to the value (prefix or postfix). This option is only visible when the formatting is of type "Currency" or "Percent".
Space Separated Should Modeler add a space between the value and the currency or percent symbol? This option is only visible when the formatting is of type "Currency" or "Percent".
Precision Number of decimals to display.
Scale Factor Check this option when Modeler should apply a scale factor on the value. This option is only visible when the formatting is of type "Currency" or "Neither".
Thousands Separated? Check this option when Modeler should add a thousands separator to the formatted value. This option is only visible when the formatting is of type "Currency" or "Neither".

1.4.8. Horizontal Alignment

SettingDescription
Horizontal Alignment Specify the horizontal alignment of data (left, right, or center) for measure variants that use this measure component item.

1.4.9. Base Ambiguous

SettingDescription
Base Ambiguous Should measure variants that use this measure component item be considered base ambiguous.

1.4.10. Read Only

SettingDescription
Read Only Should measure variants that use this measure component item be considered read only.

1.4.11. Cell Type

SettingDescription
Cell Type The cell type to use for measure variants that use this measure component item. This option is only relevant when the "Value Type" has been set to "Boolean" (Boolean Dropdown) or "String" (Address, Image, Link, Mouse Over Image, and Wrapped Text).

2. Dimensions

The "Dimensions" view of the Modeler IDE allows you to manage the dimensions, levels, and hierarchies of your Modeler application. This view contains a table which gives you an overview of all configured dimensions with a summary of their settings:

The following user actions are supported in this view:

  • Manage the configuration of an existing dimension by clicking on its row in the table.
  • Add a new dimension to your Modeler application by selecting the "+ New" option. After providing the basic dimension settings such as the name of the dimension, you can start configuring the levels and hierarchies of your dimension.
  • Remove an existing dimension by clicking on the trash can icon.

Global Validation

If there are errors in the dimension configuration, such as a missing default hierarchy, the Modeler IDE will report this via Global Validation. Validation errors will also be reported in the "Status" column of the table in "Dimensions" view.

2.1. Managing Dimension Configuration

The following example shows how the Location dimension of an example application is configured in the Modeler IDE.

On the left-hand side of the view, the Modeler IDE shows the list levels which have been defined for this dimension: Store, City, and Country.

On the right-hand side of the view, the Modeler IDE shows the list of hierarchies and their hierarchy mappings which have been defined for this dimension. A hierarchy is a named sequence of levels from the same dimension along which a measure can be aggregated. A hierarchy mapping is a many-to-one relation. For instance, in the Default hierarchy, each Store can only map to one City, and each City can only map to one Country.

Besides a default hierarchy, dimensions can be configured to have alternate hierarchies which describe an alternative sequence of levels along which a measure can be aggregated.

The Modeler includes an implicit top level (e.g. All Location) in the data model of the application. This level allows measures to be viewed by aggregating away the Location dimension entirely. For instance, a Sales measure (typically keyed by Sku, Store, Week) could be viewed regardless of their Store, City, or Country, by viewing this measure at the All Location level.

The following user actions are supported in this view:

  • Manage the settings of the selected dimension by clicking on the pencil icon next to the dimension name.
  • Manage the settings of a configured level by right-clicking on the level field and selecting "Edit".
  • Add a new level to your dimension by selecting the "+ New" option under "Levels".
  • Remove an existing level by right-clicking on the level field and selecting "Delete".
  • Manage the settings of a configured hierarchy by clicking on the pencil icon in the hierarchy panel.
  • Change the order of the sequence of levels within a hierarchy by dragging and dropping level fields within the hierarchy panel. When the hierarchy panel contains more level fields than can be displayed on a single row, you can expand the hierarchy panel by clicking on the expand icon.
  • Remove a level from a hierarchy by dragging and dropping the level field out of the hierarchy panel.
  • Add a new level to a hierarchy by dragging and dropping its level field from the left-hand side of the view onto the hierarchy panel.
  • Add a new hierarchy to your dimension by selecting the "+ New" option under "Hierarchies".
  • Remove an existing hierarchy by clicking on the trash can icon in the hierarchy panel.

2.2. Dimension Settings

When managing the settings of a dimension, the "Dimensions" view allows you to configure the following settings:

SettingDescription
NameThe name of the dimension.
LabelThe label of the dimension.

2.3. Level Settings

When managing the settings of a level within a dimension, the "Dimensions" view allows you to configure the following settings:

SettingDescription
NameThe name of the level.
LabelThe label of the level.
Order By The ordering of the level members. The level can be ordered by the name, the label, or by configuring custom ordering logic.
Custom Order Type This option becomes visible when you select "Custom" in the "Order By" setting. The setting determines what value type is expected by the Order Attribute.
Generate Order Attribute When this option is checked, Modeler will generate an order attribute (e.g. Location:City_index) for this level. This option is automatically checked when you select "Custom" in the "Order By" setting.
Generate Order Predicates When this option is checked, Modeler will generate order predicates (e.g. Location:City_first, Location:City_last, Location:City_next, and Location:City_prev) for this level. This option is automatically checked when you select "Custom" in the "Order By" setting.

The following settings can be made visible by selecting the "Show More" option under "Existing Predicates".

SettingDescription
Existing Id Predicate The existing Id predicate.
Existing Label Predicate The existing label predicate.

2.4. Hierarchy Settings

When managing the settings of a hierarchy within a dimension, the "Dimensions" view allows you to configure the following settings:

SettingDescription
NameThe name of the hierarchy.
LabelThe label of the hierarchy.
Order By The ordering of the level members. The level can be ordered by the name, the label, or by configuring custom ordering logic.
Is Default? Specifies whether this hierarchy is the default hierarchy when the Measure Service is choosing paths through the dimension. Note that a dimension can only have one primary (default) hierarchy.

The following settings can be made visible by selecting the "Show More" option under "First/Last".

SettingDescription
Has First? Should this hierarchy have an alternate hierarchy that creates a mapping from one child to its parent, if that child is the "first" child of its parent.
Has Last? Should this hierarchy have an alternate hierarchy that creates a mapping from one child to its parent, if that child is the "last" child of its parent.

Tip

The Modeler IDE requires you to mark one hierarchy as the default hierarchy. By convention, we always name the default hierarchy of a dimension Default.

3. Intersections

The "Intersections" view of the Modeler IDE allows you to manage the intersections of your Modeler application. This view contains a table which gives you an overview of all configured intersections with a summary of their settings:

The following user actions are supported in this view:

  • Manage the configuration of an existing intersection by clicking on its row in the table.
  • Add a new intersection to your Modeler application by selecting the "+ New" option.
  • Remove an existing intersection by clicking on the trash can icon.

Global Validation

If there are errors in the intersection configuration, such as the existence of an intersection referring to a deleted level, the Modeler IDE will report this via Global Validation. Validation errors will also be reported in the "Status" column of the table in "Intersections" view.

3.1. Managing Intersection Configuration

The following example shows how the SkuStoreWeek intersection of an example application is configured in the Modeler IDE.

On the left-hand side of the view, the Modeler IDE shows a list of all dimensions and their levels which can be added to the intersection.

On the right-hand side of the view, the Modeler IDE shows the levels which are selected to be part of this intersection.

The following user actions are supported in this view:

  • Restrict the number of visible levels in the left-hand side of the view by searching for specific levels using the "Search" box.
  • Add a new level to the intersection by dragging the level field from the list of levels to the list of selected levels.
  • Change the position a the level in the intersection by dragging and dropping it to another position in the list of selected levels.
  • Remove a new level from the intersection by dragging the level field out of the list of selected levels.

3.2. Intersection Settings

When managing the configuration of an intersection, the "Intersections" view allows you to configure the following settings:

SettingDescription
Intersection Label The label of the intersection. This setting is optional, intersections are typically represented in the Modeler IDE by showing a pill for each selected level.

4. Composite Aggregations

The "Composite Aggregations" view of the Modeler IDE allows you to manage composite aggregation methods for your Modeler application. This view contains a table which gives you an overview of all configured composite aggregation methods with a summary of their settings:

The following user actions are supported in this view:

  • Manage the configuration of an existing composite aggregation method by clicking on its row in the table.
  • Add a new composite aggregation method to your Modeler application by selecting the "+ New" option under "Aggregations".
  • Remove an existing composite aggregation method by clicking on the trash can icon.

4.1. Composite Aggregation Settings

When managing the settings of a composite aggregation method, the "Composite Aggs & Spreads" view allows you to configure the following settings:

SettingDescription
Name The name of the composite aggregation method.
Label The label of the composite aggregation method.

Add a new dimension along which you want a measure to be aggregated with the "+ Add Item" option. Each configured dimension has the following settings:

SettingDescription
Dimension The dimension along which you want to aggregate.
Method The aggregation method you want to use for this dimension.

Remove a dimension configuration by clicking on the trash can icon.

Use Cases

In planning applications, commonly-used composite aggregation methods for inventory calculations are BOP (Beginning of period) and EOP (End of period).

  • This composite aggregation method BOP (shown in the screenshot above) sums up all values along the non-Calendar hierarchies. The value at aggregate Calendar is the same value as the first child period's value belonging to the aggregate parent (e.g. inventory at the beginning of the Calendar:Year, Calendar:Month, or Calendar:Week).
  • This composite aggregation method EOP also sums up all values along the non-Calendar hierarchies. In this case, the value at aggregate Calendar is the same value as the last child period's value belonging to the aggregate parent (e.g. inventory at the end of the Calendar:Year, Calendar:Month, or Calendar:Week).

5. Composite Spreads

The "Composite Spreads" view of the Modeler IDE allows you to manage composite spread methods for your Modeler application. This view contains a table which gives you an overview of all configured composite spread methods with a summary of their settings:

The following user actions are supported in this view:

  • Manage the configuration of an existing composite spread method by clicking on its row in the table.
  • Add a new composite spread method to your Modeler application by selecting the "+ New" option under "Spreads".
  • Remove an existing composite spread method by clicking on the trash can icon.

5.1. Composite Spread Settings

When managing the settings of a composite spread method, the "Composite Aggs & Spreads" view allows you to configure the following settings:

SettingDescription
Name The name of the composite spread method.
Label The label of the composite spread method.

Add a new dimension along which you want a measure to be spread with the "+ Add Item" option. Each configured dimension has the following settings:

SettingDescription
Dimension The dimension along which you want to spread.
Method The spread method you want to use for this dimension.

Remove a dimension configuration by clicking on the trash can icon.

Use Cases

In planning applications, the aggregation methods BOP (Beginning of period) and EOP (End of period) are typically configured together with composite spread methods.

  • This composite spread method BOP (shown in the screenshot above) places an edited value into the first logical child dimension beneath the level of the edit (e.g. if the user updates a measure on the Calendar:Month level, the value is spread down to the first day in that Calendar:Month).
  • This composite spread method EOP places an edited value into the last logical child dimension beneath the level of the edit. (e.g. if the user updates a measure on the Calendar:Month level, the value is spread down to the last day in that Calendar:Month).

6. Measures

The "Measures" view of the Modeler IDE allows you to manage the measures of your Modeler application. This view contains a table which gives you an overview of all configured measures with a summary of their settings:

The following user actions are supported in this view:

  • Manage the configuration of an existing measure by clicking on its row in the table.
  • Add a new measure to your Modeler application by selecting the "+ New" option.
  • Remove an existing measure by clicking on the trash can icon.

6.1. Managing Measure Configuration

The following example shows how the Sales measure of an example application is configured in the Modeler IDE.

The "Measures" view allows you to configure the following settings:

SettingDescription
NameThe name of the measure.
LabelThe label of the measure.
Do you want to create Variants of this measure? Determines whether the Modeler IDE should generate derived measures using measure variants for this measure. When a measure doesn't use measure variants, we call the measure a concrete measure.

The "Measures" view supports the following additional user actions for concrete measures:

  • Manage the settings of the concrete measure.

The view supports the following additional user actions when the measure uses measure variants:

  • Manage the configuration of an existing measure variant by clicking on its row in the table.
  • Add a new measure variant for this measure to your Modeler application by selecting the "+ New" option.
  • Remove an existing measure variant by clicking on the trash can icon.
  • Open a preview of all derived measures that will be generated for all measure variants of this measure by selecting the "Preview All" option.

6.2. Concrete Measure Settings

When managing the settings of a concrete measure, the "Measures" view allows you to configure the measure definition:

SettingDescription
IntersectionThe base intersection of the measure.
Value TypeThe value type of the measure.
Default ValueThe default value of the measure.
Percent Parent? Should Modeler compute percent-parent values for this measure? A percent-parent measure contains percentage values, computed using the value of a measure at one intersection, divided by the value of that same measure, at a "parent" intersection. For example, we may want to measure the percentage of Sales for one product, over Sales of all products, or the percentage of Sales for one Subclass, over the Sales of its parent Class.
Base Metric The measure which should be used as the percent base for the percent-parent calculation. This is the measure we are interested in computing percentages of. This option is only visible when the "Percent Parent?" setting is set to "Yes".
Dimension The dimension along which to compute the percent-parent. For instance, specifying Product for this dimension would mean the resulting percent-parent measure is defined to compute the percentages of Sales of one level in the Product dimension, over a "parent" level in the Product dimension (e.g. Sku sales over sales of its parent Class). This option is only visible when the "Percent Parent?" setting is set to "Yes".
Aggregation Method The default aggregation method for the measure. This option is only visible when the "Percent Parent?" setting is set to "No".
Spread Method The default spread method for the measure. This option is only visible when the "Percent Parent?" setting is set to "No".
Spread By Metric Indicates which measure is to be used by the default spread method. This setting allows you to use the values of another measure when spreading data. For instance, whenever the value of Sales is edited, we may want to spread the value proportionally based on the value of a measure Gross Margin %, rather than using the values of existing Sales. This option is only visible when the "Percent Parent?" setting is set to "No".

The following settings related to Cell Formatting can be made visible by selecting the "Show More" option under "Cell Formatting".

SettingDescription
AlignmentSpecify the horizontal alignment of data (left, right, or center) for this measure.
Cell Type The cell type to use for this measure. Note that some cell types require special formatting (JSON) of the data to render data correctly. This option is only visible when the "Value Type" setting is set to "Boolean" (Boolean Dropdown) or "String" (Address, Image, Link, Mouse Over Image, and Wrapped Text).
Empty ValueThe empty value for this measure.
Read Only?Should this measure be considered read only.
Base AmbiguousShould this measure be considered base ambiguous.

The "Measures" view allows the configuration of business logic which is used to calculate the values for the measure. This business logic is configured as CubiQL expressions. For more details, see the section about Measure Rules And Inverses.

6.3. Configuring Measure Variants

The following example shows how the measure variant AUR_<TY,WP,LY>_PL of the Sales measure of an example application is configured in the Modeler IDE.

On the left-hand side of the view, the Modeler IDE shows a searchable list with a history of all measure variants which have been opened in the past. The following user actions are supported in the left-hand side of the view:

  • Filter the list of measure variants using the Search box.
  • Manage the configuration of another measure variant by clicking on its row in the list.
  • Remove a measure variant from the list by clicking on the "X" in its row. The measure variant will only be removed from the history, the actual measure variant will not be removed.

On the right-hand side of the view, the Modeler IDE shows the configuration of the selected measure variant. The following user actions are supported in the right-hand side of the view:

  • Create a copy of the measure variant by selecting the duplication icon next to the measure name.
  • Edit the measure component configuration for this measure variant by selecting the "Edit Components" option.
  • Edit the measure rule configuration for this measure variant by selecting the "Formula" tab.
  • Manage the override configuration for this measure variant by selecting the "Override" tab.
  • Preview the derived measures that will be generated for this measure by selecting the "Preview" tab.

6.3.1. Editing Measure Component Configuration

This view allows you to select along which measure components this measure variant should be exploded. The Modeler IDE will generate a derived measure for every combination of the selected items per measure components.

The following user actions are supported in this view:

  • Check a measure component item to add it to the measure variant configuration.
  • Uncheck a measure component item o remove it from the measure variant configuration.
  • Save changes by selecting the "Save' option.
  • Discard changes by selecting the "Cancel' option.

Use Cases

In planning applications, the average unit retail (AUR) is typically calculated for every version of the measure Sales. The following example shows the measure component configuration of the AUR_<TY,WP,LY>_PL variant of the Sales measure of an example application.

For this measure variant, the Modeler IDE will generate the following derived measures of Sales:

Sales_AUR_TY_PL
Sales_AUR_WP_PL
Sales_AUR_LY_PL

Both the Unit of Measure (UOM) and Role component are fixed to only one single measure component item (respectively AUR and PL). For the Version component, the Modeler IDE should create a derived measure for each of the selected component items (TY, WP, and LY).

6.3.2. Editing Measure Rule and Inverses

The "Formula" tab of the measure variant configuration allows the configuration of business logic which is used to calculate the values for this measure variant. This business logic is configured as CubiQL expressions. For more details, see the section about Measure Rules And Inverses.

6.3.3. Managing Override Configuration

The "Override" tab of the measure variant configuration allows you to inspect and change the overrides of a measure variant. The following example shows the override configuration of the AUR_<TY,WP,LY>_PL variant of the Sales measure of an example application in the Modeler IDE.

At the top of the "Override" tab, you find a summary of the overrides originating from the selected measure component items.

Add a new override to this measure variant selecting the "+ Add Override" option. You can also use this configuration to override one or more configurations originating from the selected measure component items. The following overrides are supported:

  • Intersection
  • Value Type
  • Default Value
  • Aggregation Method
  • Spread Method
  • Empty Value
  • Horizontal Alignment
  • Base Ambiguous
  • Read Only
  • Cell Type
  • Percent Parent
  • Spread By Metric

Every override has its own set of Override Settings. The Percent Parent and Spread By Metric overrides are configured in the same way as with Concrete Measures. Note that configuring a percent-parent override will automatically override the aggregation and spread methods set at the measure component level.

Remove an override by clicking on the trash can icon.

6.3.4. Previewing Derived Measures

The "Preview" tab of the measure variant configuration allows you to inspect the overrides (Override Configuration) and business logic (Measure Rules And Inverses) per derived measure that will be generated for this measure variant.

7. Expressions

The "Expressions" view of the Modeler IDE allows you to manage reusable CubiQL expressions for your Modeler application. Expressions are typically used for:

This view contains a table which gives you an overview of all configured CubiQL expressions:

The following user actions are supported in this view:

  • Manage the configuration of an existing expression by clicking on its row in the table.
  • Add a new expression to your Modeler application by selecting the "+ New" option.
  • Remove an existing expression by clicking on the trash can icon.

7.1. Expression Settings

When managing the settings of an expression, the "Expression" view allows you to configure the following settings:

SettingDescription
Name The name of the expression.
Expression The CubiQL expression configured for this expression.

Part IV. Services

1. Actions

The "Actions" view of the Modeler IDE allows you to manage the actions of your Modeler application. This view contains a table which gives you an overview of all configured actions with a summary of their settings:

The following user actions are supported in this view:

  • Manage the configuration of an existing action by clicking on its row in the table.
  • Add a new action to your Modeler application by selecting the "+ New" option.
  • Remove an existing action by clicking on the trash can icon.

1.1. Action Settings

The following example shows how an action of an example application is configured in the Modeler IDE. This example action will return an informational response message (with HTML markup) that will be displayed in the Modeler application after successful execution.

When managing the settings of an action, the "Actions" view allows you to configure the following settings:

SettingDescription
NameThe name of the action.
Action TypeThe type of the action: Service, or workbook commit/refresh.
Commit Group The name of the Commit Group used by this action. This setting is only visible for action type "Commit".
Refresh Group The name of the Refresh Group used by this action. This setting is only visible for action type "Refresh".
Action The inactive block of LogiQL which should be executed by this action. This setting is only visible for action type "Service".
Is Disabled?This setting specifies whether the action button should be disabled by default.
Allow HTML?This setting determines whether a response message (set via predicate modeler:actions:ActionResponseStatus_message) may contain HTML markup.
Has Confirmation?Should the Modeler application present a confirmation modal to the user before executing the action.
Title Title of the confirmation modal. This setting is only visible when the setting "Has Confirmation" is checked.
Text Text of the confirmation modal. This setting is only visible when the setting "Has Confirmation" is checked.

Part V. Build

1. Global Validation

All views in the Modeler IDE contain standard input validation. These form validations make sure that required fields are filled out by the user and the input is correctly formatted.

Besides form validations, the Modeler IDE is equipped with global validation. Global validation makes sure the configuration of the entire Modeler application is complete and consistent. When the Modeler IDE detects problems in the configuration, it will show a "!" icon in the top menu bar as a notification. This "!" icon has a badge with the number of validation errors. To indicate the presence of validation errors, the menu bar will also turn orange.

Click on the "!" icon in the top menu bar to open the validation console. This sidebar contains a summary of all validation errors. The summary contains links to relevant views to help the user quickly solve the problems in the configuration.

2. Local Development

The Modeler IDE provides you with everything you need to build, run, and test your Modeler application locally.

2.1. Build

The "Build" view contains a "Build" button. When you press this button, the Modeler IDE will (re)build the entire Modeler application.

2.2. Update

You don't have to rebuild the entire Modeler application when you only made changes to the measure model. Rebuild the model using the "Update" button on the "Build" view of the Modeler IDE.

2.3. Open Modeler Application in Browser

Modeler applications built with the Modeler IDE are web applications and are typically deployed to a web server. For local development, the Modeler IDE allows you to open the application without having to install and run additional software such as a web server.

To open the Modeler application, select the "Open In Browser" option in the top menu bar. This option can be found on the right-hand side of the header of the Modeler IDE. The application will automatically open in your web browser:

After signing in using your credentials, the Modeler application will open:

Tip

As long as the Modeler IDE is running, you can also open the Modeler application by manually typing http://localhost:8000 in the address bar of your web browser.

3. Workflow Support

The Modeler IDE build process provides support for adding custom workflows in the /workflows directory of your Modeler IDE project (e.g. for loading data). When an on_build.wf file is present in this directory, it will be executed at the end of the build process.

An overview of the basic concepts of workflow can be found in the LogicBlox Core Reference Manual.

Part VI. CubiQL

1. Measure Rules And Inverses

Business logic in a Modeler application can be implemented for Concrete Measures and Measure Variants using measure rules. These measure rules can be written within the Modeler IDE as CubiQL expressions.

To simplify the configuration of measure rules and inverses, the Modeler IDE contains a CubiQL editor on all "Formula" tabs of the "Measures" view. This editor supports CubiQL syntax highlighting, code completion for measure names, and a measure explosion syntax for measure variants.

Measure Explosion Syntax ($)

As described in the section on Measure Variants, the Modeler IDE will explode measure variants along their measure components. This means the Modeler IDE will generate derived measures for every combination of the selected measure components for a measure variant.

The Modeler IDE has a measure explosion syntax which can be used in CubiQL expressions that allows you to define how the measures in CubiQL rules and inverses should be exploded along the measure components of a measure variant. To use this syntax, simply add $ in front of the measure name. The following sections explain the use of this syntax in more detail by discussing common use cases in retail planning applications.

1.1. Net Sales

In retail planning applications, the measure NetSales tracks the Sales minus Returns for a particular type of Sku:

NetSales = Sales - Returns

The following example shows the configuration of measure variant <R,U>_<TY,WP,LY>_PL of the NetSales measure in an example application that keeps track of the net sales in retail dollar amount (R) and units (U) for the following versions: TY, LY, and WP:

1.1.1. Measure Rule

On the "Formula" tab of a measure variant, you can only configure one rule per measure variant. Since we're exploding the measure NetSales along the UOM (R and U), Version (WP, TY, and LY), and Role (PLN) component, we'll need to make sure this single rule works for all our derived measures. This means our rule should cover all of the following cases:

NetSales_R_WP_PLN = Sales_R_WP_PLN - Returns_R_WP_PLN
NetSales_R_TY_PLN = Sales_R_TY_PLN - Returns_R_TY_PLN
NetSales_R_LY_PLN = Sales_R_LY_PLN - Returns_R_LY_PLN
NetSales_U_WP_PLN = Sales_U_WP_PLN - Returns_U_WP_PLN
NetSales_U_TY_PLN = Sales_U_TY_PLN - Returns_U_TY_PLN
NetSales_U_LY_PLN = Sales_U_LY_PLN - Returns_U_LY_PLN

The following rule for NetSales uses the measure explosion syntax to explode the measures Sales and Returns along all their measure components.

$Sales - $Returns

Since we're not specifying any measure components in this rule, you could also read this rule as:

Sales_<UOM>_<Version>_<Role> - Returns_<UOM>_<Version>_<Role>

In our case, this will result in the following set of rules being assigned to the derived measures of NetSales:

NetSales_R_WP_PLN = Sales_R_WP_PLN - Returns_R_WP_PLN
NetSales_R_TY_PLN = Sales_R_TY_PLN - Returns_R_TY_PLN
NetSales_R_LY_PLN = Sales_R_LY_PLN - Returns_R_LY_PLN
NetSales_U_WP_PLN = Sales_U_WP_PLN - Returns_U_WP_PLN
NetSales_U_TY_PLN = Sales_U_TY_PLN - Returns_U_TY_PLN
NetSales_U_LY_PLN = Sales_U_LY_PLN - Returns_U_LY_PLN

You can inspect how your measure rules be exploded by the Modeler IDE by opening the Preview tab of your measure variant.

1.1.2. Inverses

The measure explosion syntax can also be applied to inverse rules to calculate the new value for $Sales and $Returns when you edit the value of $NetSales. The value entered by the user is available as Input. You can use the following CubiQL rule for the inverse group of $Sales:

$Returns + Input

The Modeler IDE explodes this rule to the following set of inverses for Sales:

Sales_R_WP_PLN = Returns_R_WP_PLN + Input
Sales_R_TY_PLN = Returns_R_TY_PLN + Input
Sales_R_LY_PLN = Returns_R_LY_PLN + Input
Sales_U_WP_PLN = Returns_U_WP_PLN + Input
Sales_U_TY_PLN = Returns_U_TY_PLN + Input
Sales_U_LY_PLN = Returns_U_LY_PLN + Input

The following CubiQL rule can be used for the inverse group of $Returns:

$Sales - Input

As you might have expected, this translates to the following set of inverses for Returns:

Returns_R_WP_PLN = Sales_R_WP_PLN - Input
Returns_R_TY_PLN = Sales_R_TY_PLN - Input
Returns_R_LY_PLN = Sales_R_LY_PLN - Input
Returns_U_WP_PLN = Sales_U_WP_PLN - Input
Returns_U_TY_PLN = Sales_U_TY_PLN - Input
Returns_U_LY_PLN = Sales_U_LY_PLN - Input

Inverse Groups

When you take a look at a Modeler application with a NetSales measure configured with inverses as described in this section, you will notice that Modeler updates the value of $Sales when you edit $NetSales.

By default, the measure service will use the inverse rule in the first inverse group. An example of a situation where the second inverse group becomes relevant is when you turn on Modeler's Deferred Calc mode and edit both $Sales and $NetSales at some position. When you press "Calculate", the measure service will recalculate the value of $Returns with the rule in the second inverse group applying the new values of $Sales and $NetSales.

1.2. Average Unit Retail (AUR)

Average Unit Retail (AUR) is a Unit of Measure (UOM) of Sales which tracks the average dollar amount spent for a particular type of Sku. The values or AUR can be calculated by dividing the total sales in dollars (R) by the number of units sold (U):

Sales_AUR = Sales_R / Sales_U

The following example shows the configuration of measure variant AUR_<TY,WP,LY>_PL of the Sales measure in an example application that keeps track of the UAR for the following versions: TY, LY, and WP:

1.2.1. Measure Rule

To write the CubiQL rule for this measure variant correctly, we need a way to tell the Modeler IDE that it should fix the UOM of Sales to R for the first argument of the division and U for the second argument of the division. The measure explosion syntax gives you the ability to control which measure components should be exploded and which ones shouldn't be exploded in the CubiQL rule:

$Sales_R / $Sales_U

You could also read this rule as:

$Sales_R_<Version>_<Role> / $Sales_U_<Version>_<Role>

The complete list of rules for all derived measures after exploding this rule along Version and Role when keeping the UOM fixed using the measure explosion syntax:

Sales_AUR_WP_PLN = Sales_R_WP_PLN / Sales_U_WP_PLN
Sales_AUR_TY_PLN = Sales_R_TY_PLN / Sales_U_TY_PLN
Sales_AUR_LY_PLN = Sales_R_LY_PLN / Sales_U_LY_PLN

Because our rule contains a division it's a non-additive computation. This means we can't rely on the default aggregation (total) and spread (ratio) methods as we did for NetSales. Instead, we need to define a rule which is capable of calculating the Average Unit Retail for every possible intersection (e.g. the base intersection Sku,Store,Week, or intersections with aggregated levels such as Sku,Store,Month and Class,Country,Year).

You can achieve this by writing the rule as a CubiQL function expression which takes the intersection at which the data is being displayed:

fun [inter = {Sku, Store, Week}] in 
    $Sales_R[inter] / $Sales_U[inter]

Modeler will pass the current intersection at which the data is being displayed (e.g. Class,Country,Year) to the rule via the argument inter. We declare a default value for this argument which is the base intersection of the Sales measure: Sku,Store,Week. When the measure service evaluates this rule, it first aggregates the value of $Sales_R and $Sales_U to the provided intersection inter using the default aggregation method of these (derived) measures. Then, the result of the division is returned as the value of $Sales_AUR for the provided intersection inter.

1.2.2. Inverse Rules

For the inverse groups of $Sales_R and $Sales_U, we'll also be using CubiQL function expressions since we need to be able to calculate these inverses at the intersection at which the data is being displayed. We can use the following CubiQL rule for the inverse group of $Sales_R:

fun [inter = {Sku, Store, Week}] in 
    Input * $Sales_U[inter]

And the following inverse rule for the inverse group of $Sales_U

fun [inter = {Sku, Store, Week}] in 
    $Sales_R[inter] / Input

2. Reusable Expressions

The "Expressions" view of the Modeler IDE allows you to configure reusable CubiQL expressions for your Modeler application. For more information about this view, see Expressions.

2.1. Functions

The following example shows how a function for linearly rescaling values from one range to another range can be configured in the Modeler IDE.

After configuring this minmax expression, it can be used in all CubiQL expressions within the Modeler IDE project.

CubiQL REPL

Test your expressions while developing your application in the CubiQL REPL:

$ lb measure-service repl --uri http://localhost:55183/ide-planning-app/measure

Welcome to the
  ___     _    _  ___  _      ___ ___ ___ _
 / __|  _| |__(_)/ _ \| |    | _ \ __| _ \ |
| (_| || | '_ \ | (_) | |__  |   / _||  _/ |__
 \___\_,_|_.__/_|\__\_\____| |_|_\___|_| |____|

Enter ':help' for a list of commands.

Connecting to measure service at http://localhost:55183/ide-planning-app/measure ...
> minmax(50d, 0d, 100d, 0d, 1d)

value of decimal
┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈
          0.5d

Displayed all 1 result entries.