Skip to main content
Previous sectionNext section

Other Export/Import Options

This appendix describes additional options for exporting and importing DeepSee elements, as a supplement to the chapter “Packaging DeepSee Elements into Classes.” It discusses the following topics:

Note:

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

Creating a DeepSee Container Class

As noted in the chapter “Packaging DeepSee Elements into Classes,”you can package pivot tables and other folder items into Caché classes. You can package as many elements as needed into a single class, which is easier to export and import than many separate files.

To create such a class:

  • The class must extend %DeepSee.UserLibrary.Container.

  • The class must include an XData block named Contents. For this XData block, you must specify the XML namespace as follows:

    [ XMLNamespace = "http://www.intersystems.com/deepsee/library" ]
    Copy code to clipboard
  • The top-level element within the XData block must be <items>.

Include as many XML definitions as needed within <items>. You can copy the definitions in Studio or from exported XML files. Also see the next section, which describes edits you should make.

Also be sure to copy and paste only the definition, not the XML declarations at the top of the file. That is, do not copy the following line into the XData block:

<?xml version="1.0" encoding="UTF-8"?>
Copy code to clipboard

For example:

Class DeepSee.Model.DashboardItems Extends %DeepSee.UserLibrary.Container
{

XData Contents [ XMLNamespace = "http://www.intersystems.com/deepsee/library" ]
{
<items>
<dashboard dashboard definition here ...
</dashboard>
<dashboard another dashboard definition here ...
</dashboard>
<pivot pivot definition here ...
</pivot>
<pivot another pivot definition here ...
</pivot>
<pivot yet another pivot definition here ...
</pivot>
</items>
}

}
Copy code to clipboard

When you compile this class or when you call its %Process() instance method, DeepSee creates the items defined in the XData block. Specifically, it imports these definitions into the internal global that the User Portal uses.

The same class can also define the %OnLoad() callback, which can execute any additional code needed when these items are set up.

For samples of pivot tables and dashboards that are packaged into class definitions, see the classes DeepSee.DashboardsEtc and HoleFoods.DashboardsEtc in the SAMPLES namespace.

If you delete a container class, that has no effect on the pivots and dashboards that currently exist.

Exporting and Importing Folder Items

This section describes the older API for exporting and importing folder items.

Exporting Folder Items Programmatically

To export folder items programmatically, use the following command:

Do ##class(%DeepSee.UserLibrary.Utils).%Export(itemname,filename)
Copy code to clipboard

Where:

  • itemname is the full name of the item, including the folder in which it belongs.

    • For a pivot table, append the extension .pivot

    • For a dashboard, append the extension .dashboard

    • For a widget, append the extension .widget

    • For a theme, append the extension .theme

  • filename is the full path and file name of the file to create. InterSystems suggests that you end the file name with .xml, because the file is an XML file.

For example:

 set DFIname="Chart Demos/Area Chart.pivot"
 set filename="c:/test/Chart-Demos-Area-Chart-pivot.xml"
 do ##class(%DeepSee.UserLibrary.Utils).%Export(DFIname,filename)

 set DFIname="KPIs & Plugins/KPI with Listing.dashboard"
 set filename="c:/test/KPIs-Plugins-KPI-with-Listing-dashboard.xml"
 do ##class(%DeepSee.UserLibrary.Utils).%Export(DFIname,filename)
Copy code to clipboard

Alternative Technique (for Exporting Multiple Items)

To export multiple items programmatically into a single XML file, use the $system.OBJ.Export() method. The first and second arguments for this method are as follows:

  • items is a multidimensional array as follows:

    Array Node Node Value
    items("full-folder-item-name.DFI") where items is the name of the array and full-folder-item-name.DFI is the full name of the folder item, exactly as seen in Studio, including case. ""

    Note that because this argument is a multidimensional array, you must precede it with a period when you use the $system.OBJ.Export() method.

  • filename is the full path and file name of the file to create. InterSystems suggests that you end the file name with .xml, because the file is an XML file.

For example:

 set items("Chart Demos-Area Chart.pivot.DFI")=""
 set items("Chart Demos-Bar Chart.pivot.DFI")=""
 set items("Chart Demos-Bubble Chart.pivot.DFI")=""
 set filename="c:/test/Chart-Samples.xml"
 do $system.OBJ.Export(.items,filename)
Copy code to clipboard

You can also use this method to export other items such as classes; for details, see the Class Reference for %SYSTEM.OBJ.

Importing Folder Items Programmatically

To import folder items programmatically:

 Do ##class(%DeepSee.UserLibrary.Utils).%Import(pFile, pReplace, pVerbose)
Copy code to clipboard

Where:

  • pFile is the full path and file name of the file to import.

  • If pReplace is true, replace an existing item with the same name. The default is false.

  • If pVerbose is true, write status to the console. The default is true.

For example:

 set filename="c:/test/Chart-Demos-Area-Chart-pivot.xml"
 do ##class(%DeepSee.UserLibrary.Utils).%Import(filename,1,1) 
Copy code to clipboard