Using the Cube Manager

Introduction to the Cube Manager

The Cube Manager enables you to define the cube registry, which contains information about the cubes in the current namespace. In particular, it contains information about how they are to be built, synchronized, or both.

The cube registry defines a set of cube groups. A cube group is a collection of cubes that need to be updated together, either because they are related or because you have chosen to update them together. When you first access the Cube Manager, it displays an initial set of cube groups. Each initial cube group is either a single cube or a set of cubes that are related to each other (and thus must be updated as a group). You can merge these initial cube groups together as wanted. You cannot, however, break up any of the initial cube groups.

Each cube group is initially unregistered, which means that it is not included in the cube registry. After you register a cube group (thus placing it into the registry), you define an update plan for it. The Cube Manager creates automatic tasks that use these update plans. See the next section for details.

Introduction to Update Plans

The update plan for a cube group specifies how and when the cubes are to be updated. Each group has a default plan, which you can modify. You can also specify different update plans for specific cubes in the group. In both cases, the plan choices are as follows:

• Build and Synch — Rebuild periodically, once a week by default. Also synchronize periodically, once a day by default.

  This option is not supported for a given cube unless that cube supports synchronization (as described earlier in this page).

• Build Only — Rebuild periodically, once a week by default.

• Synch Only — Synchronize the cubes periodically, once a day by default.

  This option is not supported for a given cube unless that cube supports synchronization (as described earlier in this page).

  Important:

  Before you synchronize cubes from the Cube Manager, it is necessary to build the cubes at least once from the Cube Manager.

• Manual — Do not rebuild or synchronize from the Cube Manager.

  Instead, use any suitable combination of other tools: the Build option in the Architect and the %BuildCube(), %SynchronizeCube(), %ProcessFact(), and %DeleteFact() methods; the latter three methods are described later in this page.

  Alternatively, you may manually rebuild the cube with a call to %DeepSee.CubeManager.Utils.BuildCube()Opens in a new tab. You may also manually synchronize the cube with a call to %DeepSee.CubeManager.Utils.SynchronizeCube()Opens in a new tab.

For each plan (other than Manual), you can customize the schedule details.

For any namespace, the Cube Manager defines two tasks: one performs all requested cube build activity in this namespace, and one performs all requested cube synchronization activity in this namespace. Both of these tasks follow the instructions provided in the cube registry. Both tasks also automatically process cubes in the correct order required by any relationships.

The Cube Manager provides an Exclude check box for each registered group and cube, which you can use to exclude that group or cube from any activity by the Cube Manager. Specifically, the Cube Manager tasks ignore any excluded groups and cubes. Initially these check boxes are selected, because it is generally best to not to perform updates until you are ready to do so.

Accessing the Cube Manager

To access the Cube Manager, do the following in the Management Portal:

1. Switch to the appropriate namespace as follows:

   1. Click the name of the current namespace to open the list of available namespaces.

   2. From the list, click the appropriate namespace.

2. Click Analytics > Admin > Cube Manager.

3. If you have not used the Cube Manager in this namespace, it prompts you for information about the cube registry. In this case, specify the following information:

   • Cube Registry Class Name — Specify a complete class name, including package. This class definition will be the cube registry for this namespace.

   • Disable — Optionally click this to disable the registry. If the registry is disabled, the Cube Manager tasks are suspended. (Because there are no Cube Manager tasks yet, it would be redundant to disable the registry at this point.)

   • Update Groups — Specify how to update groups with respect to each other. If you select Serially, the tasks update one group at a time. If you select In Parallel, the tasks update the groups in parallel.

   • Allow build to start after this time — Specify the earliest possible build time.

   You can change all these details later, apart from the class name.

   Then click OK.

The system displays the Cube Registry page. You can view this page in two modes (via the View buttons). Click the left View button for tree view or click the right View button for table view.

Tree View

In tree view, the left area of the Cube Manager displays a tree of unregistered cube groups. For example:

The middle area displays a table (initially empty) with information for the registered groups. The following example shows what this table looks like after you have registered a group:

This area is color-coded as follows:

• White background — The group or cube is included, which means that the Cube Manager tasks update it. See the Exclude option in Specifying an Update Plan, later in this page.

• Gray background — The group or cube is excluded, which means that the Cube Manager tasks ignore it.

This area also lists (in italics) any subject areas based on a given cube, for example:

Note that you cannot specify update plans for the subject areas, because updates in a cube are automatically available in any subject area based on that cube. (So there is no need and no way to update a subject area independently from the cube on which it is based.)

In the right area, the Details tab (not shown) displays details for the current selection. You can make edits in this tab. The Tools tab provides links to other tools.

Note:

When the Cube Manager is in tree view, you can expand or collapse the display of all registered groups, which are shown in the middle area. To do so, use the Expand All or Collapse All button, as applicable, at the top of the middle area. These buttons do not affect the left area of the page, which displays the unregistered groups.

Table View

In table view, the Cube Manager lists all cubes in the current namespace, with their update plans. For example:

This table is color-coded as follows:

• White background — The cube is included, which means that the Cube Manager tasks update it. See the Exclude option in Specifying an Update Plan, later in this page.

• Gray background — The cube is excluded, which means that the Cube Manager tasks ignore it.

• Pink background — The cube is not registered and therefore has no update plan.

The Group Name field indicates the group to which each cube belongs, and the Group Build Order field indicates the order in which each cube is to be built or synchronized within its group. The Cube Manager computes this order only for cubes in registered groups.

In the right area, the Details tab (not shown) displays details for the current selection. You can make edits in this tab. The Tools tab provides links to other tools.

Modifying the Registry Details

When you first access the Cube Manager, it prompts you for initial information. To modify these details later (other than the registry class name, which cannot be changed):

1. Display the Cube Manager in tree view.

2. In the middle area, click the heading that starts Registered Groups.

3. Edit the details on the right.

   For information on the options, see the previous section.

4. Click Save.

Registering a Cube Group

To register a cube group:

1. Display the Cube Manager in tree view.

2. Expand the list of unregistered cubes on the left.

3. Drag the group from that area and drop it onto the Registered Groups heading in the middle area.

Or display the Cube Manager in table view, click the row for any cube in the group, and click Register Group in the right area.

In either case, the change is automatically saved.

Specifying an Update Plan

To specify the update plan for a cube group and its cubes:

1. Display the Cube Manager in tree view.

2. Click the group in the middle area.

3. In the Details pane on the right, specify the following information:

   • Name — Unique name of this group.

   • Exclude — Controls whether the generated tasks perform update activities for cubes in this group. Initially this option is selected, and the group is excluded.

     The Cube Manager displays any excluded groups or cubes with a gray background.

   • Update Plan — Select an update plan.

     Note that the Cube Manager does not permit you to use synchronization unless that cube supports it (as described earlier in this page). For example, you can choose the Build and Synch plan for the group, but the Cube Manager automatically sets the update plan to Build for any cube that does not support synchronization.

     Important:

     Before you synchronize cubes from the Cube Manager, it is necessary to build the cubes at least once from the Cube Manager.

   • Build every — Use these fields to specify the schedule for the build task (if applicable).

   • Synch every — Use these fields to specify the schedule for the synchronization task (if applicable).

   • Build Cubes Synchronously — Select this to cause the system to build these cubes synchronously (if applicable). If this option is clear, the system builds them asynchronously.

   Initially, these details apply to all cubes in the group. If you edit details for a specific cube and then later want to reapply the group defaults, click Apply to All Cubes in Group.

4. Optionally click a cube within this group (in the middle area) and edit information for that cube in the Details pane on the right.

   The options are similar to those for the entire group, but include the following additional options, depending on whether the cube supports synchronization:

   • Post-Build Code — Specify a single line of ObjectScript to be executed immediately after building this cube. For example:

     do ##class(MyApp.Utils).MyPostBuildMethod("transactionscube")
     

     

   • Pre-Synchronize Code — Specify a single line of ObjectScript to be executed immediately before synchronizing this cube. For example:

     do ##class(MyApp.Utils).MyPresynchMethod("transactionscube")
     

     

     If needed, to abort the synchronization, do the following in your code:

     set $$$ABORTSYNCH=1
     

     

   • Post-Synchronize Code — Specify a single line of ObjectScript to be executed immediately after synchronizing this cube. For example:

     do ##class(MyApp.Utils).MyPostsynchMethod("transactionscube")
     

     

   In all cases, your code can perform any processing required.

   Modify each cube as needed.

5. Click Save.

   When you do so, the Cube Manager creates or updates the cube registry in this namespace. If the Task Manager does not yet include the necessary tasks, the Cube Manager creates them.

Merging Groups

You can merge one group (group A) into another (group B). Specifically this moves all the cubes from group A into the group B and then removes the now-empty group A.

To merge one group into another, use the following procedure. In this procedure, group A must not yet be registered, and group B must be registered.

1. Display the Cube Manager in tree view.

2. Drag group A (the group that contains the cubes that you want to move) from the left area and drop it into the group heading of group B (the target group) in the middle area.

   The system prompts you to confirm the action.

3. Click OK.

   If group B currently has an update plan that cannot be used for some of the newly moved cubes, the system displays a dialog box to indicate this. Click OK. For any such cubes, the Cube Manager selects an update plan that can be used.

4. Review the update plan for each newly moved cube and modify it as needed.

5. Click Save.

Or use the following alternative procedure. In this procedure, both groups must already be registered.

1. Display the Cube Manager in table view.

2. In the middle area, click the row for any cube in group A (the group that contains the cubes that you want to move).

3. On the right, click Merge to another group and then select group B (the target group) from the drop-down list.

4. Click Merge.

   The system prompts you to confirm the action.

5. Click OK.

   If group B currently has an update plan that cannot be used for some of the newly moved cubes, the system displays a dialog box to indicate this. Click OK. For any such cubes, the Cube Manager selects an update plan that can be used.

6. Review the update plan for each newly moved cube and modify it as needed.

7. Click Save.

Building All the Registered Cubes

The system provides a utility method that you can use to build all the registered cubes, in the correct order. The method is BuildAllRegisteredGroups() in the class %DeepSee.CubeManager.UtilsOpens in a new tab. This method ignores the schedule specified in the registry but uses the build order specified in the registry.

Performing On-Demand Builds

The Cube Manager also provides options to build cubes on demand (that is, ignoring the schedule). In this kind of build, the Cube Manager rebuilds the requested cube as well as any cubes that depend on it.

To perform an on-demand build:

1. Save any changes to the cube registry.

   Important:

   The build options are disabled if there are any unsaved changes.

2. Select a registered cube. To do so, either:

   • Display the Cube Manager in tree view and then click a cube in the middle area.

   • Display the Cube Manager in table view and click a cube that shows Yes in the Registered column.

3. On the right, clear the Exclude option.

4. Click Build Dependency List.

   The Cube Manager then displays the build dialog box.

5. Click Build List.

   The dialog box displays progress of the build.

6. When the build is done, click OK.

There are other ways to perform on-demand builds:

• Display the Cube Manager in tree view. Click the header of the table in the middle area. Then click Build All Registered Groups. Continue as described previously.

• Display the Cube Manager in tree view. Click a cube group in the middle area. Then click Build This Group. Continue as described previously.

Unregistering a Cube Group

To unregister a cube group:

1. Display the Cube Manager in tree view.

2. In the middle area, click the X in the row for the cube group.

3. Click OK.

Viewing Cube Manager Events

For certain events, the Cube Manager writes log entries to a table, which you can query via SQL. The table name is %DeepSee_CubeManager.CubeEvent. The CubeEvent field indicates the type of cube event. Possible logical values for this field include the following:

For information on other fields in this table, see the class reference for %DeepSee.CubeManager.CubeEventOpens in a new tab.

Restricting Access to the Cube Manager

You may want to manage the cube update schedule without allowing users to change that schedule through the Cube Registry page. To restrict access to the Cube Registry page, set the UserUpdatesLocked attribute to "true" in either the RegistryMap or RegistryMapGroup objects within your saved cube registry. For example:

<RegistryMap Disabled="false" IndependentSync="false" SerialUpdates="false" UserUpdatesLocked="true">

When UserUpdatesLocked is set to "true" for a RegistryMap:

• The registry’s Disable setting cannot be changed through the Details tab. For information on accessing this tab, see Modifying the Registry Details.

When UserUpdatesLocked is set to "true" for a RegistryMapGroup:

• Each registered group’s Exclude check box is displayed but disabled.

• Each registered cube’s Exclude check box is hidden.

• Each registered group’s Update Plan is hidden.

• Each registered cube’s Update Plan is hidden.

• The red X button for removing registered groups is removed.

• The Build Frequency and Synch Frequency columns are left blank.

• The Build Dependency List is available for cubes, but the Build This Group button is disabled.

See Also

• Keeping the Cubes Current

• Using the Task Manager

• Using Cube Synchronization