Skip to main content
Previous sectionNext section

Packaging DeepSee Elements into Classes

In most cases, you develop your application elements on a test system and then copy them to a production system. This chapter describes how to package the DeepSee elements and copy them to another system. It discusses the following topics:

Note:

This chapter assumes that you are familiar with the process of exporting from and importing into Studio. If not, see Using Studio.

Also see the appendix “Other Export/Import Options.”

Overview

Your DeepSee implementation may include some or all of the following elements:

  • Cube class definitions

  • Subject area class definitions

  • KPI class definitions

  • DeepSee folder items, which include all the items that are not defined as classes. These include pivot tables, dashboards, pivot variables, and so on.

To move all these items to another system (here called the target system), do the following:

  1. Export all the folder items to one or more DeepSee container classes, as described in the next section.

    A DeepSee container class contains an XML representation of any number of DeepSee folder items.

  2. Export the cube, subject area, and KPI class definitions.

    You can create a project that contains all your DeepSee class definitions and folder items. Then you can export this project from Caché and import it into another Caché instance, where needed. You can use the Studio export/import options or you can use the usual class methods in %SYSTEM.OBJ.

  3. Examine the exported folder item definitions to make edits for portability.

  4. Import all the class definitions to the target system.

    When you compile the container classes, DeepSee iterates over all the folder items contained in those classes and creates or overwrites each of those items in the target system.

Exporting Folder Items to a Container Class

To export DeepSee folder items to container classes, you use a method that generates a file that defines a container class that includes the items. The method is %ExportContainer(), which is in the class %DeepSee.UserLibrary.Utils. This method is as follows:

classmethod %ExportContainer(ByRef pItemList As %String, 
                             pFileName As %String, 
                             pContainerClassName As %String = "") as %Status
Copy code to clipboard

Where:

  • pItemList is a multidimensional array that has nodes of the following form:

    Node Node Value
    pItemList(itemidentifier) ""

    For each itemidentifier, use one of the following strings:

    • dashboardname.dashboard where dashboardname is the name of a dashboard. You can use the wildcard * to represent all dashboards; you can use the wildcard with the other types of items as well.

    • pivotname.pivot where pivotname is the name of a pivot table (or use *).

      Note that the %ExportContainer() method identifies all the pivot tables used by any dashboard you export. The only pivot tables you need to export explicitly are the pivot tables that are not used by any dashboard.

    • namedfiltername.namedFilter where namedfiltername is the name of a named filter (or use *).

    • sharedcalcmembername.sharedCalcMember where sharedcalcmembername is the name of a shared calculated member (or use *).

    • listinggroupname.listingGroup where listinggroupname is the name of a listing group (or use *).

    • pivotvarname.pivotVariable where pivotvarname is the name of a pivot variable (or use *).

    • settingname.userSetting where settingname is the name of a user setting (or use *).

    • termlistname.termList where termlistname is the name of a term list (or use *).

    • themename.theme where themename is the name of a dashboard theme (or use *).

    • widgettemplatename.widgetTemplate where widgettemplatename is the name of a widget template (or use *).

    • linkname.link where linkname is the name of a dashboard link (or use *).

    • reportname.report where reportname is the name of a dashboard report (or use *).

  • pFileName is the name of the file to generate.

  • pContainerClassName is the full name of the container class to generate, including package.

Editing the DeepSee Folder Items for Portability

If you intend to copy a DeepSee folder item to another system, it is worthwhile to examine the exported XML and make any necessary edits, discussed in the following subsections.

Also note the following points:

  • When you export a dashboard, DeepSee does not automatically export any pivot tables that it uses. It is your responsibility to identify and export the pivot tables as well.

  • References between DeepSee elements (such as from a dashboard to any pivot tables) are made by name.

Removing <filterState> Elements

If it was saved in a previous release, a folder item definition might contain <filterState> elements, which are no longer supported. If so, you should remove these — that is, remove both the starting tag <filterState> and the matching ending tag </filterState>.

Stripping Out Local Data

A folder item definition might also contain information that is local to your system and not available on another system (depending on what elements you package and share between systems). Check the XML for the following items:

localDataSource attribute

Where found: <widget> elements in exported dashboards.

This attribute contains any local overrides performed in the Mini Analyzer. You should always clear this when you use the exported XML in another system. For example, change this:

localDataSource="$LOCAL/Basic Dashboard Demo/SamSmith/590125613.pivot"
Copy code to clipboard

To this:

localDataSource=""
Copy code to clipboard

Or remove the localDataSource attribute.

owner attribute

Where found: All folder items.

This element contains the name of the user who owns this item. If the given user does not exist on the target system, edit this attribute. You can set the attribute to null. For example, change this:

owner="DevUser"
Copy code to clipboard

To this:

owner=""
Copy code to clipboard

Or you can remove the attribute.

resource attribute

Where found: All folder items.

This element contains the name of the resource used to secure this item, if any. If this resource does not exist on the target system, edit this attribute. You can set the attribute to null or even remove the attribute.

createdBy attribute

Where found: All folder items.

This element contains the name of the user who created this item. You can set the attribute to null or even remove the attribute. If you do so, when the XML is imported (or the container class is compiled), createdBy is set to the current user.

timeCreated attribute

Where found: All folder items.

This element contains the name of the user who created this item. You can set the attribute to null or even remove the attribute. If you do so, when the XML is imported (or the container class is compiled), timeCreated is set to the current time stamp.

Importing an Exported Container Class

To import an exported container class, use the %ImportContainer() method, which is in the class %DeepSee.UserLibrary.Utils. This method is as follows:

ClassMethod %ImportContainer(pFileName As %String = "", pReplace As %Boolean = 1) As %Status
Copy code to clipboard

Where:

  • pFileName is the name of the file to generate.

  • pReplace specifies whether to replace the existing class.

Note that %ImportContainer() automatically calls the %OnLoad() method if it is defined in the container class.

Using the Folder Manager

This section describes how to use the Folder Manager to see the dependencies of an item, export items, and import items. You can also export and import in Studio, as described later in this chapter.

Seeing the Dependencies of a Folder Item

If you click the check box for a single item, the left area of the Folder Manager displays details for that item, including a list of the items that it depends on:

generated description: folder manager item details

Exporting DeepSee Folder Items to the Server

To export DeepSee folder items to files on the server:

  1. Click the InterSystems Launcher and then click Management Portal.

    Depending on your security, you may be prompted to log in with a Caché username and password.

  2. Switch to the appropriate namespace as follows:

    1. Click Switch.

    2. Click the namespace.

    3. Click OK.

  3. Select DeepSee > Admin > Folder Manager.

  4. Select Server.

  5. For Server Directory, type the full path of the directory in which to export the items. Or type the name of a directory relative to the directory that contains the default database for this namespace. Or use the Browse button.

    The directory must already exist.

  6. Click the check box next to each item that you want to export.

    Or to select all items, click the check box at the top of the column of check boxes.

  7. Click Export.

  8. Optionally click the Directory tab, which shows the files in the given directory.

    generated description: export directory

Variation: Exporting a Container Class

To instead export a single file that consists of a container class that contains the given folder items, do the following:

  1. Specify Server and Server Directory as in the preceding steps.

  2. Select the items to export.

  3. Select the option Create Container Class For Export.

  4. Optionally select Export Related Supporting Items to export all supporting items that might be needed to deploy the selected folder items. Examples of supporting items include pivot variables, named filters, and shared calculated members.

  5. For Container Class Name, optionally specify a fully qualified class name (package and class). If no Container Class Name is specified, both the container class and the export file will use generated names.

  6. Click Export.

For information on container classes, see “Packaging DeepSee Folder Items into Classes.”

Exporting DeepSee Folder Items to the Browser

To export DeepSee folder items to the browser’s download directory:

  1. Click the InterSystems Launcher and then click Management Portal.

    Depending on your security, you may be prompted to log in with a Caché username and password.

  2. Switch to the appropriate namespace as follows:

    1. Click Switch.

    2. Click the namespace.

    3. Click OK.

  3. Select DeepSee > Admin > Folder Manager.

  4. Select Browser.

  5. Select the items to export.

  6. Optionally select Export Related Supporting Items.

  7. For Container Class Name, optionally specify a fully qualified class name (package and class). If no Container Class Name is specified, both the container class and the export file will use generated names.

  8. Click Export.

Importing DeepSee Folder Items

To import a folder item that has previously been exported:

  1. Click DeepSee, Admin, and then click Folder Manager.

  2. For Server Directory, type the full path of the directory that contains the exported items. Or type the name of a directory relative to the directory that contains the default database for this namespace.

  3. Click the Directory tab, which shows the filenames for items in the given directory.

    generated description: export directory

  4. Click the check box next to each file that you want to import.

    Or to select all items, click the check box at the top of the column of check boxes.

  5. Click Import.

  6. Click OK at the prompt to continue. Or click Cancel.

Note:

For the items created when you import the files, the owner is the username under which the Caché service runs, for example _SYSTEM.

Variation: Importing Local Files to the Server

To import a local file to the server:

  1. Click DeepSee, Admin, and then click Folder Manager.

  2. Select Browser.

  3. Click the Directory tab, and then click Choose File.

  4. Select the file that you want to import.

  5. Click Import.

  6. Click Ok at the prompt to continue. Or click Cancel.

Restoring Deleted Folder Items

When you delete a pivot table or dashboard via the web-based interfaces, DeepSee moves it into a folder named $TRASH. Or, if the item is already in a folder, then $TRASH/ is prepended to the folder name. In either case, the item is no longer visible in the web-based interfaces. To restore the item, if needed, do the following in Studio:

  1. In the Workspace window, expand the Other folder.

    generated description: studio folder items

  2. Find the item that corresponds to the folder item table definition. Here its displayed name starts with $TRASH-, followed by the complete original name.

  3. Right-click the item, and then click Export.

  4. Specify the name of the file and click OK.

  5. Open the exported file with a text editor and modify the folderName attribute of the exported item. For example, change this:

    <dashboard xmlns="http://www.intersystems.com/deepsee/library" name="DashA" folderName="$TRASH" ...>
    Copy code to clipboard

    To this:

    <dashboard xmlns="http://www.intersystems.com/deepsee/library" name="DashA" folderName="New Folder" ...>
    Copy code to clipboard

    For folderName, specify any string that does not start with a dollar sign ($). This can be the name of an existing folder or a new one.