DeepSee Implementation Guide
Packaging DeepSee Elements into Classes
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

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:
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
Where:
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:
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"
To this:
localDataSource=""
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"
To this:
owner=""
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
Where:
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:
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 Server.
  4. 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.
  5. 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.
  6. Click Export.
  7. Optionally click the Directory tab, which shows the files in the given 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. 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.
  4. 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.
  5. 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 Browser.
  4. Select the items to export.
  5. Optionally select Export Related Supporting Items.
  6. 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.
  7. 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.
  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.
  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" ...>
    To this:
    <dashboard xmlns="http://www.intersystems.com/deepsee/library" name="DashA" folderName="New Folder" ...>
    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.