Getting Started

Dodeca Shell (Dshell) is a command-line utility that helps you work with a Dodeca repository. It connects directly to the repository database (without going through the Dodeca server itself). Various actions can be performed on a repository, including viewing, exporting, importing, and searching for data.

Dshell is packaged as a self-contained runnable JAR file. In order to run it, you need to have Java 1.8+ installed on your system. It is much more convenient to run when you have java available on your system path, so that you only need to type java to run it, as opposed to a fully qualified path.

You can quickly test if Java is available on the current path as well as of a new enough version by trying to run the Java version command from a commmand-line:

java -version

If Java is installed and available on the path, you may see output like the following:

java version "1.8.0_25"
Java(TM) SE Runtime Environment (build 1.8.0_25-b17)
Java HotSpot(TM) 64-Bit Server VM (build 25.25-b02, mixed mode)

You can run dshell by executing the following command:

java -Dloader.path=lib/ -jar dodeca-shell.jar

This command defines a variable named loader.path and sets it to the lib subfolder of the current working directory. This setting sets the folder that Dshell should look in for additional JDBC drivers that may be needed to connect to your Dodeca repository. You will likely need additional JAR files for your repository, based on its database technology (such as Oracle, Microsoft SQL Server, DB2, MySQL, and others).

If everything works correctly, you will see Dshell start up similar to the following:

       __     __         ____
  ____/ /____/ /_  ___  / / /
 / __  / ___/ __ \/ _ \/ / /
/ /_/ (__  ) / / /  __/ / /
\__,_/____/_/ /_/\___/_/_/
You are connected to an internal repository. Use the connect command to connect to a Dodeca repository
Type 'help connect' for information on how to use the connect command
dshell/:>

By default, dshell starts up and is connected to an internal repository that does not have any objects in it. You can use this workspace to facilitate certain types of testing, but most likely you will need and want to connect it to your own repository.

Connecting To Your Dodeca Repository

The easiest way to connect to a repository is to create a properties file with the connection settings in it. This can be as simple as a file with the following contents:

dodeca.datasource.url = jdbc:mysql://server/dodeca?noDatetimeStringSync=true
dodeca.datasource.username = dodeca
dodeca.datasource.password = password

The preceding example is for a repository inside a MySQL database, therefore the JDBC URL is formatted specifically for MySQL. The URL format for other database types typically varies. You can use the same setting from your existing hibernate.properties file configured for your Dodeca server or attempt to create the URL yourself. The username and password fields are defined with the plaintext version of the password.

For convenience, you can use the suffix .dodeca.properties on your connection file, for a total file name such as mysql-dev.dodeca.properties. This allows you to use the list-connections command in the shell, which will list all of the files in the current directory that have this suffix. You may then use the connect command to refer to this short version of the file, such as:

connect mysql-dev

You may use the fully-qualified name of the file as well. You can switch between different repository connections during a single shell session, even if those connections are different database technologies (so long as the appropriate JDBC drivers are available, of course).

Most shell commands require having specified a tenant to work with by using the use command. For example, to set the tenant to SAMPLE, you would type:

use SAMPLE

Assuming that a tenant named SAMPLE exists, the shell prompt will update to indicate the current tenant:

dshell/SAMPLE:>

Using Tab-based Auto-completion

Many commands in the shell support tab-based auto-completion. This can make entering artfiact IDs, tenants, commands, and file names much more quick and less error prone.

For example, consider when there are a number of tenants available, such as by using the list-tenants command:

dshell/SAMPLE:>list-tenants
+---------------------------+
|Tenant                     |
+---------------------------+
|DEMOWARE                   |
|SAMPLE                     |
+---------------------------+

You may then wish to switch to the DEMOWARE tenant. You can have the shell provide you a list of items to select from, or a list of items based on what you have already typed in. For example, upon typing use DE followed by pressing the tab key, the shell will finish off the text by using the matching tenant (in this case, DEMOWARE), and you can then press enter to execute the command.

If you have not started typing the text for an item, the shell may prompt your for the parameter name first, which you can select and press tab again in order to get the list of all available options.

Scripting

The shell offers limited scripting/automation capabilities by way of running the shell with an additional parameter that specifies a list of commands to run sequentially. For instance, you may wish to automate a process that connects to your repository and exports all of the comments for a certain Dodeca tenant named SAMPLE. The sequence of commands for accomplishing this would be the following:

connect mysql-dev
use SAMPLE
export-comments --file comment_export.xml

You can then put these lines into a file named export_comments.dshell and then run it with the following command:

java -Dloader.path=lib/ -jar dodeca-shell.jar @export_comments.dshell

Note that @ symbol in front of the scripting filename (@export_comments.dshell).

Getting Help With Commands

You can get a list of all available commands by typing help. You can get help and parameter information by typing help followed by the command name. For instance, to get help on the export-comments command, type:

help export-comments

You will then be presented with help like the following:

NAME
	export-comments - Export comments

SYNOPSYS
	export-comments [--file] file  [[--author] string]  [[--include-key-spec]
	comment-key-spec]  [[--exclude-key-spec] comment-key-spec]

OPTIONS
	--file or -F  file

		[Mandatory]

	--author  string

		[Optional, default = <none>]

	--include-key-spec  comment-key-spec

		[Optional, default = <none>]

	--exclude-key-spec  comment-key-spec

		[Optional, default = <none>]

Data Source Commands

Data Source commands are used to manage the actual connection between Dodeca Shell and the Dodeca repository database.

List Data Sources

Use the list-connections command to view the available connections. Connections are created by placing database connection details in a local file that ends with .dodeca.properties. For example, if your development Dodeca repository is in a MySQL database, you can create a local file named dev.dodeca.properties. The contents of the list-connections command would then list this as an available connection:

dshell/:>list-connections
dev.dodeca.properties

The contents of the file should can include the following values:

dodeca.datasource.url = jdbc:mysql://localhost/dodeca?noDatetimeStringSync=true&useSSL=false
dodeca.datasource.username = root
dodeca.datasource.password = password

The dodeca.datasource.url value should be a valid JDBC database URL for your database environment. You may omit the password from connection file for security purposes, in which case you will be prompted in the shell for the password to the database for the specified user.

Connect to Data Source

Use the connect commmand to connect to a data source using the specified connection file. You may omit the .dodeca.properties suffix.

Encrypt Password in Data Source Connection File

You may want to encrypt the value of dodeca.datasource.password in your connection file. You can use the encrypt command for this. Encrypt takes a single parameter and will output an encrypted version of the password. For example:

dshell/:>encrypt mypassword

You will receive output similar to the following:

ENC(CjzrGUAl14fEcR9Y2zo06lvlTg8fjkTd)

This entire line of text represents the value to place in your connection file. For instance:

dodeca.datasource.url = jdbc:mysql://localhost/dodeca?noDatetimeStringSync=true&useSSL=false
dodeca.datasource.username = root
dodeca.datasource.password = ENC(CjzrGUAl14fEcR9Y2zo06lvlTg8fjkTd)

You may now connect to the data source and Dodeca Shell will use the decrypted password to connect to the Dodeca repository.

General Commands

Decode Encoded Contents

You may be working with the encoded contents of an artifact such as in the ENCODED_ARTIFACT column of the BINARY_ARTIFACTS table or inside of the exported artifact XML. The decode command takes a single parameter and will decode and print the conents for you.

For example, when the standard Income Statement view is exported to a zip file, the contents of the inner SAMPLE.VIEW.IncStmt.1.xml file as similar to the following:

<?xml version='1.0' encoding='UTF-8'?>
<BinaryArtifact exported="2019-03-22T18:27:32" info="NS8xMDAuMC8xMDAuMS8xLzIwMjA=">
  <Tenant>SAMPLE</Tenant>
  <Category>VIEW</Category>
  <ID>IncStmt</ID>
  <Version>1</Version>
  <UserID />
  <Type>ExcelEssbase</Type>
  <Name>Income Statement</Name>
  <Description />
  <Filename />
  <FileCreatedDateTime />
  <FileModifiedDateTime />
  <Checksum>00f41daf7c7a1e5bb632a5f66bfce0155188253c</Checksum>
  <CacheType>0</CacheType>
  <CacheTimeout>0</CacheTimeout>
  <EncodedArtifact>H4sIAAAAAAAEAO29B2AcSZYlJi9tynt/SvVK1+B0oQiAYBMk2JBAEOzBiM3mkuwdaUcjKasqgcplVmVdZhZAzO2dvPfee++999577733ujudTif33/8/XGZkAWz2zkrayZ4hgKrIHz9+fB8/Iv7Hv/cffPyTRX519Bsnacq/nS3Pq3qRtUW1TN8tymXz6F1TfPbRvG1Xj+7evbq6Gl/dG1f1xd29nZ3du7/3F89fT+f5Itsulk2bLaf5R/at2c1vfcT9Us9nT4/OltPX7aJ9fJd+109fZIscn1eLPH3dZm2+yJfUgD/WJkD5zfUqp5dO303z8rRpJlmTP77rfeFBm72sq1Vet9ev87ZJ78qw73bGLZ9qyyJvfoh0OC7L6up1dpkftfWaRuH+DhrMs7pYXgRt9CPTbN1WT9ZFOfty+eUqX5qWnU+18Um2wrCPz9u85q97NE+JNun33oy/yOq3efv9dBt/EIFm66n56/U0XxIK1fcf3+3D046+yOuLPJuU+ZuqKidZ3ZxUy/PiYl0z2WmmMBHpF1mxJJivP39898YXfC6o3uZLM6f2s/hryiUp90ejXM6yepY+LxZFm8+0703vaxffLZaz6qpBy6/Ovpz8dD5tleW+W9VvJ1X1Fl89vjvczp/VfPb81Zf4vDna01n1PtKWijkhtCQogs3rbLEq8/GTrCmmj+/GWoQvP68uiuXrvL4spnmAjf/90yIrqwsLbvAdB9oJjH5IH7/Ol7OfyuuqOW6+KJrGMW3kC/vSV01+XBbUaaONvQ9sI33rTf6ufd0y6+8Qv/Q+tO1fVMfTad40rnHnEx3I3dhIHn9eFzOiaEuAv8iXaxr3m5yITuLhffr4br+Zvv86L4lkVR0wkkNOiWxaQRfZL+nr51nTEg1mZySNCv7oaX6erUvShrEvN7/7PJvkpRWUAD/CeP/3FynHHNkPI02fF01L30jj3/9Nnee/P/QLFIt7VRtFXg9Zzr0RsJW8UdXtl/Usr492qZn9w2vRIZ8Q2QmAp8ndoC1nR4n+/6oZuff7q6q95ZRo6x/OnOz9/JyT+7+/MXi3nBTT/Pc/qRYT76Vvdjbu/ZBmw2ET02h2CE+r6ducNWJdlZ/X1Xr1ur0u8yMyufjCQRlqqPA6xvDL5dO6KMt2Tg0v5q/ned4e7e73bGasmQI8yZppNstfV+t66g368Qm5Ue2rnCxCfpm/ypYXOQbtfV8t4A/xN95rT7M2O8nL8mm1JmflpCymb19W9O/10fFsxh0/ozF6yDy+O/zKMMwv8sUkr58VJTlWsd69DqTpm4q9IqLrJb1BE/RqXXbx7tGI3Wv/05Q/FpTjrT1w5Fh3qRNY1A4hGIbXFD68Ma1PCpKY62N67TybOnGNBwv0+U/KGGEmzK+GW2+G2zfxMUwDumw2/dHXtS/iMHJyv1wqp2WlOjr9z90LzJLKIgGHNvye/7V5qbo6XhJS5Xqx/HZO7F6TC9oUxE1Hz7ISKmVDC4XxJpt0X/I/QqvHdwN/STzno/8Htu+7wloOAAA=</EncodedArtifact>
  <CreatedBy>Dodeca Sample 7.0.0</CreatedBy>
  <CreatedDate>2019-02-14T19:10:50</CreatedDate>
  <UpdatedBy />
  <UpdatedDate />
</BinaryArtifact>

The contents of the <EncodedArtifact> element can be used with the decode command as follows:

dshell/:>decode H4sIAAAAAAAEAO29B2AcSZYlJi9tynt/SvVK1+B0oQiAYBMk2JBAEOzBiM3mkuwdaUcjKasqgcplVmVdZhZAzO2dvPfee++999577733ujudTif33/8/XGZkAWz2zkrayZ4hgKrIHz9+fB8/Iv7Hv/cffPyTRX519Bsnacq/nS3Pq3qRtUW1TN8tymXz6F1TfPbRvG1Xj+7evbq6Gl/dG1f1xd29nZ3du7/3F89fT+f5Itsulk2bLaf5R/at2c1vfcT9Us9nT4/OltPX7aJ9fJd+109fZIscn1eLPH3dZm2+yJfUgD/WJkD5zfUqp5dO303z8rRpJlmTP77rfeFBm72sq1Vet9ev87ZJ78qw73bGLZ9qyyJvfoh0OC7L6up1dpkftfWaRuH+DhrMs7pYXgRt9CPTbN1WT9ZFOfty+eUqX5qWnU+18Um2wrCPz9u85q97NE+JNun33oy/yOq3efv9dBt/EIFm66n56/U0XxIK1fcf3+3D046+yOuLPJuU+ZuqKidZ3ZxUy/PiYl0z2WmmMBHpF1mxJJivP39898YXfC6o3uZLM6f2s/hryiUp90ejXM6yepY+LxZFm8+0703vaxffLZaz6qpBy6/Ovpz8dD5tleW+W9VvJ1X1Fl89vjvczp/VfPb81Zf4vDna01n1PtKWijkhtCQogs3rbLEq8/GTrCmmj+/GWoQvP68uiuXrvL4spnmAjf/90yIrqwsLbvAdB9oJjH5IH7/Ol7OfyuuqOW6+KJrGMW3kC/vSV01+XBbUaaONvQ9sI33rTf6ufd0y6+8Qv/Q+tO1fVMfTad40rnHnEx3I3dhIHn9eFzOiaEuAv8iXaxr3m5yITuLhffr4br+Zvv86L4lkVR0wkkNOiWxaQRfZL+nr51nTEg1mZySNCv7oaX6erUvShrEvN7/7PJvkpRWUAD/CeP/3FynHHNkPI02fF01L30jj3/9Nnee/P/QLFIt7VRtFXg9Zzr0RsJW8UdXtl/Usr492qZn9w2vRIZ8Q2QmAp8ndoC1nR4n+/6oZuff7q6q95ZRo6x/OnOz9/JyT+7+/MXi3nBTT/Pc/qRYT76Vvdjbu/ZBmw2ET02h2CE+r6ducNWJdlZ/X1Xr1ur0u8yMyufjCQRlqqPA6xvDL5dO6KMt2Tg0v5q/ned4e7e73bGasmQI8yZppNstfV+t66g368Qm5Ue2rnCxCfpm/ypYXOQbtfV8t4A/xN95rT7M2O8nL8mm1JmflpCymb19W9O/10fFsxh0/ozF6yDy+O/zKMMwv8sUkr58VJTlWsd69DqTpm4q9IqLrJb1BE/RqXXbx7tGI3Wv/05Q/FpTjrT1w5Fh3qRNY1A4hGIbXFD68Ma1PCpKY62N67TybOnGNBwv0+U/KGGEmzK+GW2+G2zfxMUwDumw2/dHXtS/iMHJyv1wqp2WlOjr9z90LzJLKIgGHNvye/7V5qbo6XhJS5Xqx/HZO7F6TC9oUxE1Hz7ISKmVDC4XxJpt0X/I/QqvHdwN/STzno/8Htu+7wloOAAA=

Generating the following output:

<View>
  <ViewInformation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <ID>IncStmt</ID>
    <Name>Income Statement</Name>
    <ViewTypeID>ExcelEssbase</ViewTypeID>
    <NamedPropertySets />
  </ViewInformation>
  <Properties xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <AllowSave>true</AllowSave>
    <AllowSharing>true</AllowSharing>
    <AutoBuildOnOpen>true</AutoBuildOnOpen>
    <CaptionAfterBuild>Income Statement for [T.Market] - [T.Product] - [T.Scenario]</CaptionAfterBuild>
    <MergeableToolbarsConfigurationID>View Main - SG</MergeableToolbarsConfigurationID>
    <ViewTokens />
    <ViewToolbarsConfigurationID>Essbase View Standard Limited - SG</ViewToolbarsConfigurationID>
    <WindowsViewUIObjectTypeID>WorkbookView</WindowsViewUIObjectTypeID>
    <AllowedLROTypes>2</AllowedLROTypes>
    <EssbaseConnectionID>Sample.Basic</EssbaseConnectionID>
    <EssbaseLoginServiceObjectTypeID>EssbaseLoginDialog</EssbaseLoginServiceObjectTypeID>
    <EssProperties>
      <SendZerosAsMissing>true</SendZerosAsMissing>
      <UseAliases>true</UseAliases>
      <MissingTextString>0</MissingTextString>
      <NoAccessString>0</NoAccessString>
    </EssProperties>
    <GridContextMenuID>TemplateContextMenu</GridContextMenuID>
    <SelectorConfiguration>
      <EssbaseSelectorInfo>
        <LastUsedItemContext>Default</LastUsedItemContext>
        <LastUsedItemContextLabel />
        <SelectorID>4_Market</SelectorID>
        <SelectorListID>Market_Tree_AutoOpen</SelectorListID>
        <SelectorTypeID>Essbase</SelectorTypeID>
        <SortOrder>1</SortOrder>
        <EssbaseSelectorConfigConnectionProperties />
      </EssbaseSelectorInfo>
      <EssbaseSelectorInfo>
        <LastUsedItemContext>Default</LastUsedItemContext>
        <LastUsedItemContextLabel />
        <SelectorID>3_Product</SelectorID>
        <SelectorListID>Product_Tree_AutoOpen</SelectorListID>
        <SelectorTypeID>Essbase</SelectorTypeID>
        <SortOrder>2</SortOrder>
        <EssbaseSelectorConfigConnectionProperties />
      </EssbaseSelectorInfo>
      <EssbaseSelectorInfo>
        <LastUsedItemContext>Default</LastUsedItemContext>
        <LastUsedItemContextLabel />
        <SelectorID>5_Scenario</SelectorID>
        <SelectorListID>Scenario_Combo</SelectorListID>
        <SelectorTypeID>Essbase</SelectorTypeID>
        <SortOrder>3</SortOrder>
        <EssbaseSelectorConfigConnectionProperties />
      </EssbaseSelectorInfo>
    </SelectorConfiguration>
    <SelectorDockedControlGroupStyle>Stacked</SelectorDockedControlGroupStyle>
    <AllowedLROTypesOnDrillthroughSheet>14</AllowedLROTypesOnDrillthroughSheet>
    <CascadeSources />
    <ChartRetrieveRangeInfo />
    <CommentRanges />
    <DataCellDoubleClickPolicy>AddSheetForDrillthrough</DataCellDoubleClickPolicy>
    <DataCellDoubleClickMemberFilters />
    <DataCellDrillthroughMemberToTokenConversionRules />
    <DataDrillthroughSheetName>Drillthrough Sheet</DataDrillthroughSheetName>
    <DataSetRanges />
    <EssPropertiesForDrillthroughSheet />
    <ExcelTemplateBinaryArtifact>
      <ID>IncStmt</ID>
      <Version>1</Version>
    </ExcelTemplateBinaryArtifact>
    <GridContextMenuIDForDrillthroughSheet>DrillthroughContextMenu</GridContextMenuIDForDrillthroughSheet>
    <RetainOnRetrieval>true</RetainOnRetrieval>
    <RetrievePolicy>RetrieveRanges</RetrievePolicy>
    <RowAndColumnHeadersVisible>False</RowAndColumnHeadersVisible>
    <TabsVisible>False</TabsVisible>
  </Properties>
</View>

Artifact Commands

Display Artifact Contents

Many Dodeca objects are stored as compressed XML. You can decompress and view the contents by using the print-artifact command and specifying an artifact. For example, to view the XML conents of version 1 of a certain View artifact named IncStmt, you may use the following command:

print-artifact IncStmt VIEW 1

The contents are then displayed:

<View>
  <ViewInformation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <ID>IncStmt</ID>
    <Name>Income Statement</Name>
    <ViewTypeID>ExcelEssbase</ViewTypeID>
    <NamedPropertySets />
  </ViewInformation>
  <Properties xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <AllowSave>true</AllowSave>
    <AllowSharing>true</AllowSharing>
    <AutoBuildOnOpen>true</AutoBuildOnOpen>
    <CaptionAfterBuild>Income Statement for [T.Market] - [T.Product] - [T.Scenario]</CaptionAfterBuild>
    <MergeableToolbarsConfigurationID>View Main </MergeableToolbarsConfigurationID>
    <ViewTokens />
    <ViewToolbarsConfigurationID>Essbase View Standard Limited</ViewToolbarsConfigurationID>
    <WindowsViewUIObjectTypeID>WorkbookView</WindowsViewUIObjectTypeID>
    <AllowedLROTypes>2</AllowedLROTypes>
    <EssbaseConnectionID>Sample.Basic</EssbaseConnectionID>
    <EssbaseLoginServiceObjectTypeID>EssbaseLoginDialogWithGenericCaption</EssbaseLoginServiceObjectTypeID>
    <EssProperties>
      <SendZerosAsMissing>true</SendZerosAsMissing>
      <UseAliases>true</UseAliases>
      <MissingTextString>0</MissingTextString>
      ...

Note that all artifacts in a Dodeca repository are uniquely identified by a unique combination of four pieces of information: tenant, artifact ID, category, and version. In the previous example, the tenant is already set (by way of the use command), and then then three other properties are specified. You do not have to always fully qualify an exact artifact, but if the artifact specification is otherwise ambiguous, the shell will report an error and tell you that you need to be more specific.

For instance, in the demo tenant that we have been working with, there are multiple artifacts with the name IncStmt, so attempts to print the artifact contents with the following command:

dshell/SAMPLE:>print-artifact IncStmt

Will result in the following error message:

Ambiguous artifact specification 'IncStmt' as there are 2 artifacts that match (GENERAL/1, VIEW/1)

Helpfully enough, the error tells us that the ambiguous name is due to there being an artifact with the same ID but with categories of GENERAL and VIEW. We can then narrow our artifact specification:

dshell/SAMPLE:>print-artifact IncStmt VIEW

(Notice that we did not have to specify the version).

Delete All Artifacts

The delete-all-artifacts command deletes all of the binary artifacts in the current tenant.

Delete Artifact

The delete-artifact command deletes a single artifact.

Delete All Artifacts on Stack

The delete-all-artifacts command can optionally take a --use-stack flag that specifies that the artifacts to be deleted are the ones that are on the current artifact stack.

Export Artifacts to CSV

The export-csv command exports artifacts to a CSV file. The columns will correspond to the fields in the internal Dodeca binary artifacts table. This export format is not used anywhere else in Dodeca but may be helpful to load artifact metadata into other tools that expect a flat file format.

Export Artifacts to ZIP

Use export-zip to export artifacts to a ZIP file that is compatible with Dodeca client import/export operations. By default, all artifacts in the tenant will be exported or you can use the --use-stack parameter to specify to use the list of artifacts currently on the stack.

Import Artifacts

List Artifacts

Use list-artifacts to view a list of binary artifacts. This command supports various filtering options for the artifact type, category, and other attributes.

Refresh Artifact List

The refresh-artifact-list command can be used alone or with a --category CATEGORY parameter in order to refresh the internal Dodeca list of artifacts. Internally, Dodeca keeps a cache of available artifacts. You may need to manually refresh an artifact list after performing actions in Dodeca that add/remove artifacts.

Artifact Dependency Commands

View Artifact Dependencies

You can view the dependencies (artifacts that a given artifact depends on) with by using the view-dependencies command and specifying the artifact:

dshell/SAMPLE:>view-dependencies IncStmt VIEW 1

Example output:

dshell/SAMPLE:>view-dependencies IncStmt VIEW 1
has root (VIEW/1) IncStmt
	has Essbase connection (ESSBASE_CONNECTION/1) Sample.Basic
	has selector (SELECTOR/1) 4_Market
	has selector (SELECTOR/1) 3_Product
	has selector (SELECTOR/1) 5_Scenario
	has selector list (SELECTOR_LIST/1) Market_Tree_AutoOpen
	has selector list (SELECTOR_LIST/1) Product_Tree_AutoOpen
	has selector list (SELECTOR_LIST/1) Scenario_Combo
	has mergeable toolbar (TOOLBARS_CONFIGURATION/1) View Main
	has view toolbar (TOOLBARS_CONFIGURATION/1) Essbase View Standard Limited
	has Excel template (GENERAL/1) IncStmt

You may run a reverse dependency search to determine what depends on a given artifact. For example, in the previous example we can see that the IncStmt view has a dependency on an Excel binary artifact of the same name (with type GENERAL). Therefore, in this case we would expect that if we search for what depends on this Excel template, we will at least see our view.

We can use the depends-on command to perform this search, such as the following:

dshell/SAMPLE:>depends-on IncStmt GENERAL 1

We may see something like the following output:

(GENERAL/1) IncStmt
	has Excel template (VIEW/1) IncStmt

Artifact Stack Commands

Dodeca Shell supports the notion of an "artifact stack". The artifact stack is a list of artifact keys (a combination of the artifact ID, category, and version) in a given tenant. The list can be modified by various commands. It is used to build up a list of particular artifacts and then perform some action on them.

For example, you may want to use Dodeca Shell to help facilitate the migration of certain views and their dependencies from one environemnt to another. You could use the view-dependencies command to generate a list of dependencies:

dshell/SAMPLE:>view-dependencies IncStmt VIEW

By default, the view-dependencies command will just output the hierarchy of dependencies that it detects:

IncStmt/VIEW/1
has Essbase connection Sample.Basic/ESSBASE_CONNECTION/1
has selector 4_Market/SELECTOR/1
has selector 3_Product/SELECTOR/1
has selector 5_Scenario/SELECTOR/1
has selector list Market_Tree_AutoOpen/SELECTOR_LIST/1
	has The selector that a selector list depends on 4_Market/SELECTOR/1
has selector list Product_Tree_AutoOpen/SELECTOR_LIST/1
	has The selector that a selector list depends on 3_Product/SELECTOR/1
has selector list Scenario_Combo/SELECTOR_LIST/1
	has The selector that a selector list depends on 5_Scenario/SELECTOR/1
has mergeable toolbar View Main /TOOLBARS_CONFIGURATION/1
has view toolbar Essbase View Standard Limited/TOOLBARS_CONFIGURATION/1
has Excel template IncStmt/GENERAL/1

However, the view-dependencies command accepts a --stack parameter that tells it to add the found dependencies to the artifact stack that is kept in memory during the Dodeca Shell session.

Notice that the stack is empty at first:

dshell/SAMPLE:>view-stack
dshell/SAMPLE:>

Then run the dependency command again, but adding the new stack parameter:

dshell/SAMPLE:>view-dependencies IncStmt VIEW --stack

Now when we view the stack, we’ll see all of the dependencies of the view added:

dshell/SAMPLE:>view-stack
Sample.Basic/ESSBASE_CONNECTION/1
IncStmt/GENERAL/1
3_Product/SELECTOR/1
4_Market/SELECTOR/1
5_Scenario/SELECTOR/1
Market_Tree_AutoOpen/SELECTOR_LIST/1
Product_Tree_AutoOpen/SELECTOR_LIST/1
Scenario_Combo/SELECTOR_LIST/1
Essbase View Standard Limited/TOOLBARS_CONFIGURATION/1
View Main /TOOLBARS_CONFIGURATION/1
IncStmt/VIEW/1

Remove an item from the artifact stack

You may want to remove certain items from the stack. You can use the stack-remove command. For example, perhaps you want to get all of the dependencies of the Income Statement view in order to export to another environment, but you may want to omit the Essbase connection that it’s dependent on. You can use the stack-remove command to specify an item to remove:

dshell/SAMPLE:>stack-remove Sample.Basic ESSBASE_CONNECTION 1

The stack after:

dshell/SAMPLE:>view-stack
IncStmt/GENERAL/1
3_Product/SELECTOR/1
4_Market/SELECTOR/1
5_Scenario/SELECTOR/1
Market_Tree_AutoOpen/SELECTOR_LIST/1
Product_Tree_AutoOpen/SELECTOR_LIST/1
Scenario_Combo/SELECTOR_LIST/1
Essbase View Standard Limited/TOOLBARS_CONFIGURATION/1
View Main /TOOLBARS_CONFIGURATION/1
IncStmt/VIEW/1

Add an item to the stack

Generally you will use other commands that support the artifact stack in order to add their output to the stack, but you can also simply add an item manually using the stack-add command, such as the following:

dshell/SAMPLE:>stack-add Sample.Basic ESSBASE_CONNECTION 1

After:

dshell/SAMPLE:>view-stack
Sample.Basic/ESSBASE_CONNECTION/1
IncStmt/GENERAL/1
3_Product/SELECTOR/1
4_Market/SELECTOR/1
5_Scenario/SELECTOR/1
Market_Tree_AutoOpen/SELECTOR_LIST/1
Product_Tree_AutoOpen/SELECTOR_LIST/1
Scenario_Combo/SELECTOR_LIST/1
Essbase View Standard Limited/TOOLBARS_CONFIGURATION/1
View Main /TOOLBARS_CONFIGURATION/1
IncStmt/VIEW/1

Repository/Tenant Commands

List Tenants

You can list available tenants using the list-tenants command. At present this is determined simply by considering the unique list of tenants present across all binary artifacts.

dshell/SAMPLE:>list-tenants
+---------------------------+
|Tenant                     |
+---------------------------+
|DEMOWARE                   |
|H2                         |
|SAMPLE                     |
|___DODECA_SERVER_LICENSE___|
+---------------------------+

Set (Use) Current Tenant

Most commands in Dodeca Shell work against a tenant that is set to be active. You can choose this tenant by using the use command. Your shell prompt will be updated to reflect the current active tenant:

dshell/SAMPLE:>use DEMOWARE
dshell/DEMOWARE:>

If the tenant does not seem to exist (based on the tenants that seem to exist based on binary artifacts, the shell will give you a warning and not change):

dshell/DEMOWARE:>use BAD
Warning: No such tenant
dshell/DEMOWARE:>

For automation or other purposes you may need to simply force the tenant (such as creating a new tenant). The --force flag can be used:

dshell/DEMOWARE:>use BAD --force
Warning: No such tenant
Forcing use of tenant even though it doesn't exist
dshell/BAD:>

You may want to skip the tenant validation check because it takes too long against your repository. You can use the --skip-tenant-check flag to do so.

Unset (Unuse) Tenant

You can go back to not having a tenant set by using the unuse command.

dshell/SAMPLE:>unuse
dshell/:>

Delete Tenant

You can delete a tenant by deleting all of its binary artifacts, comments, and other items. The delete-tenant command can be used.

Warning
Before deleting a tenant you are strongly encouraged to create a backup of the contents using the various export commands or creating a backup of the database itself.

You can check out the current list of tenants using the list-tenants command. It may show the following:

dshell/:>list-tenants
+---------------------------+
|Tenant                     |
+---------------------------+
|SAMPLE                     |
|___DODECA_SERVER_LICENSE___|
+---------------------------+

Note that the automatic tenant list is based on contents of the binary artifacts table only. Therefore, it may be the case that you don’t see a tenant listed but there are other database entries for that tenant that exist, such as comments, metadata, and other items.

The delete-tenant command will delete all traces of the specified tenant from every Dodeca repository table:

dshell/:>delete-tenant SAMPLE
Warning: Deleting all objects for tenant SAMPLE

And afterward:

dshell/:>list-tenants
+---------------------------+
|Tenant                     |
+---------------------------+
|___DODECA_SERVER_LICENSE___|
+---------------------------+

To take a deeper look, you can force a context switch to the deleted tenant and run the stats command to view the count of objects:

dshell/:>use SAMPLE --force
Warning: No such tenant
Forcing use of tenant even though it doesn't exist
dshell/SAMPLE:>stats
Artifacts: 0
Comments: 0
Data audit log records: 0

Import Tenant

You can import a tenant from a previously created tenant export. The parameters are the target tenant name and the export file:

dshell/SAMPLE:>import-tenant SAMPLE ../../SAMPLE.zip

Or you can use full syntax:

dshell/SAMPLE:>import-tenant --tenant SAMPLE --file ../../SAMPLE.zip

The tenant import process will then kick off. Depending on the number of artifacts, their size, and latency to you database, the import process can take seconds or minutes.

At present, the tenant export and import feature supports binary artifacts and comments.

Warning
All of the comments in the tenant you are importing to will be CLEARED before the comments are imported from the import file.

Export Tenant

You can export a tenant to a tenant export file. The tenant export file is a zip file containing the binary artifacts for the tenant and the comments. The import file can then be used with the import-tenant command. The export file is also compatible with the Dodeca client and can be used to import artifacts from (but not comments).

At its simplest, you can export a specified tenant:

shell/SAMPLE:>export-tenant SAMPLE

This will generate a file named tenant.zip (in this case, SAMPLE.zip) in the current folder. Alternatively, you may specify the exact file to export to:

dshell/SAMPLE:>export-tenant SAMPLE SAMPLE_backup.zip

Copying a Tenant

There is no direct command to copy a tenant. You can achieve it by exporting a tenant file, deleting any data that may exist in the target tenant, then importing the file.

Comment Commands

Comment Summary

The comment-summary command provides a high-level overview of how many comments have been written and by whom.

View Comments

You can view the comments in the current tenant:

dshell/SAMPLE:>view-comments
+-----------+-------------------------+-----------------------------------------------+
|Author     |Keys                     |Comment                                        |
+-----------+-------------------------+-----------------------------------------------+
|Jason Jones|Day: 2                   |Yeah                                           |
|           |Month: December          |                                               |
|           |Row: 1                   |                                               |
|           |Year: 2016               |                                               |
|Jason Jones|Market: New York         |Test comment                                   |
|           |Measures: COGS           |                                               |
|           |Product: Root Beer       |                                               |
|           |Scenario: Variance       |                                               |
|           |Year: Jan                |                                               |
|Jason Jones|Key: 1                   |foo                                            |
|           |Year: 2016               |                                               |
...

The view-comments command also takes --author, --include-key-spec and --exclude-key-spec parameters to specify that the comments displayed should have the given author or key spec, using standard comment key-specification syntax.

Delete Comments

Comments can be deleted using delete-comments. Without any parameters, all comments are deleted. The delete-comments command also accepts the standard --author, --include-key-spec and --exclude-key-spec parameters.

Copy Comments

The comment copy functionality can be used to copy comments within the same tenant. This command allows for specifying comments based on key value pairs to include or exclude, to adjust the POV of the comments, the author, and more. Consider a Dodeca tenant that contains the following comments:

dshell/SAMPLE:>view-comments
+-----------+-------------------------+----------------------------------------------------------------------------------+
|Author     |Keys                     |Comment                                                                           |
+-----------+-------------------------+----------------------------------------------------------------------------------+
|Jason Jones|Market: West Seattle     |Lower sales due to planned road work during the month                             |
|           |Measure: Sales           |                                                                                  |
|           |Scenario: Budget         |                                                                                  |
|           |Time: Jan                |                                                                                  |
|           |Year: FY2020             |                                                                                  |
|Jason Jones|Market: Northgate        |Closure of competing store in same neighborhood to provide significant sales boost|
|           |Measure: Sales           |                                                                                  |
|           |Scenario: Budget         |                                                                                  |
|           |Time: Feb                |                                                                                  |
|           |Year: FY2020             |                                                                                  |
|Jason Jones|Market: Downtown Flagship|Higher sales from customers avoiding West Seattle location                        |
|           |Measure: Sales           |                                                                                  |
|           |Scenario: Budget         |                                                                                  |
|           |Time: Jan                |                                                                                  |
|           |Year: FY2020             |                                                                                  |
+-----------+-------------------------+----------------------------------------------------------------------------------+

In this example, there are three comments for three different locations and a total of two different time periods (Jan and Feb). The comment copy command allows us to do several things with the comments. For example, we may wish to copy the comments and specify a new time period:

dshell/SAMPLE:>copy-comments --add-key-spec Time=Mar
+-----------+-------------------------+----------------------------------------------------------------------------------+
|Author     |Keys                     |Comment                                                                           |
+-----------+-------------------------+----------------------------------------------------------------------------------+
|Jason Jones|Measure: Sales           |Lower sales due to planned road work during the month                             |
|           |Time: Mar                |                                                                                  |
|           |Year: FY2020             |                                                                                  |
|           |Market: West Seattle     |                                                                                  |
|           |Scenario: Budget         |                                                                                  |
|Jason Jones|Measure: Sales           |Closure of competing store in same neighborhood to provide significant sales boost|
|           |Time: Mar                |                                                                                  |
|           |Year: FY2020             |                                                                                  |
|           |Market: Northgate        |                                                                                  |
|           |Scenario: Budget         |                                                                                  |
|Jason Jones|Measure: Sales           |Higher sales from customers avoiding West Seattle location                        |
|           |Time: Mar                |                                                                                  |
|           |Year: FY2020             |                                                                                  |
|           |Market: Downtown Flagship|                                                                                  |
|           |Scenario: Budget         |                                                                                  |
+-----------+-------------------------+----------------------------------------------------------------------------------+

The --add-key-spec directive allows for specifying a series of key values that should be added or updated on each comment intersection. Similarly, we can copy the comments and remove a portion of the key value pairs:

dshell/SAMPLE:>copy-comments --remove-key-spec Scenario
+-----------+-------------------------+----------------------------------------------------------------------------------+
|Author     |Keys                     |Comment                                                                           |
+-----------+-------------------------+----------------------------------------------------------------------------------+
|Jason Jones|Measure: Sales           |Higher sales from customers avoiding West Seattle location                        |
|           |Time: Jan                |                                                                                  |
|           |Year: FY2020             |                                                                                  |
|           |Market: Downtown Flagship|                                                                                  |
|Jason Jones|Measure: Sales           |Closure of competing store in same neighborhood to provide significant sales boost|
|           |Time: Feb                |                                                                                  |
|           |Year: FY2020             |                                                                                  |
|           |Market: Northgate        |                                                                                  |
|Jason Jones|Measure: Sales           |Lower sales due to planned road work during the month                             |
|           |Time: Jan                |                                                                                  |
|           |Year: FY2020             |                                                                                  |
|           |Market: West Seattle     |                                                                                  |
+-----------+-------------------------+----------------------------------------------------------------------------------+

We can delete multiple keys at once by separating them with a comma:

dshell/SAMPLE:>copy-comments --remove-key-spec Scenario,Year
+-----------+-------------------------+----------------------------------------------------------------------------------+
|Author     |Keys                     |Comment                                                                           |
+-----------+-------------------------+----------------------------------------------------------------------------------+
|Jason Jones|Measure: Sales           |Closure of competing store in same neighborhood to provide significant sales boost|
|           |Time: Feb                |                                                                                  |
|           |Market: Northgate        |                                                                                  |
|Jason Jones|Measure: Sales           |Lower sales due to planned road work during the month                             |
|           |Time: Jan                |                                                                                  |
|           |Market: West Seattle     |                                                                                  |
|Jason Jones|Measure: Sales           |Higher sales from customers avoiding West Seattle location                        |
|           |Time: Jan                |                                                                                  |
|           |Market: Downtown Flagship|                                                                                  |
+-----------+-------------------------+----------------------------------------------------------------------------------+

We may wish to only operate on comments with a certain intersection. The --include-key-spec parameter can be used to specify a set of key value pairs to filter on. In the following example, only comments with an existing key of Time=Feb will be operated on and will have their Year set to FY2021:

copy-comments --include-key-spec Time=Feb --add-key-spec Year=FY2021
+-----------+-----------------+----------------------------------------------------------------------------------+
|Author     |Keys             |Comment                                                                           |
+-----------+-----------------+----------------------------------------------------------------------------------+
|Jason Jones|Measure: Sales   |Closure of competing store in same neighborhood to provide significant sales boost|
|           |Time: Feb        |                                                                                  |
|           |Year: FY2021     |                                                                                  |
|           |Market: Northgate|                                                                                  |
|           |Scenario: Budget |                                                                                  |
+-----------+-----------------+----------------------------------------------------------------------------------+

Multiple filters can be specified in a single --include-key-spec specification. For example, the following command specifies that comments with an intersection where Time equals Jan and Market equals West Seattle (notice the quotes since the key value contains spaces) are to be operated on:

copy-comments --include-key-spec "Time=Jan,Market=West Seattle" --add-key-spec Year=FY2021

The quotes surround the entire parameter value (i.e. everything after --include-key-spec and before --add-key-spec rather than the individual member names.

You can specify multiple include filters by separating them with a semi-colon. For example:

copy-comments --include-key-spec "Time=Jan,Market=West Seattle;Market=Northgate" --add-key-spec Year=FY2021

The preceding comment command specifies that there are multiple types of comment intersections to consider:

  • Any comments that have both Time=Jan and Market=West Seattle or

  • Any comments that have Market=Northgate

You may need to filter out some comments that match certain criteria. For example, we could extend the previous example:

copy-comments --include-key-spec "Time=Jan,Market=West Seattle;Market=Northgate" --exclude-key-spec Time=Feb --add-key-spec Year=FY2021

It can be read as follows:

Copy comments where the comment POV is Time=Jan and Market=West Seattle or where Market=Northgate (without any regard for Time), but exclude anything with a POV where Time=Feb. Lastly, add or update the comment POV so that Year=FY2021.

On any given comment update command you may also use some additional parameters such as updating the comment author, or optionally setting the comment’s "updated" date to the current time/date:

copy-comments --include-key-spec "Time=Jan,Market=West Seattle;Market=Northgate" --exclude-key-spec Time=Feb --add-key-spec Year=FY2021 --new-author "Tim Tow" --updated
+-------+--------------------+-----------------------------------------------------+
|Author |Keys                |Comment                                              |
+-------+--------------------+-----------------------------------------------------+
|Tim Tow|Measure: Sales      |Lower sales due to planned road work during the month|
|       |Time: Jan           |                                                     |
|       |Year: FY2021        |                                                     |
|       |Market: West Seattle|                                                     |
|       |Scenario: Budget    |                                                     |
+-------+--------------------+-----------------------------------------------------+

The common "comment key specification" format also allows for specifying the key/value to be matched in more advanced ways. Typically the key specification is in the form Key=Value but it can also be specified in other ways. For example, without a value specifies to filter where the comment simply has Market as a key in its intersection, but with ANY value.:

view-comments --include-key-spec "Market"

Lastly, the key can be omitted in order to filter on the value only without respect to the key:

view-comments --include-key-spec "=Budget"

View Comments

You can view, export, and import comments. Viewing is useful to get a sense of what comments exist and which intersections an export/import will target. You can export comments to an XML file to be imported to a different tenant, database, or both. You may also specify which intersections should be specifically included or excluded in the import.

To view all comments in the current tenant, you can simply use the view-comments command:

view-comments

With output such as the following:

+-----------+-------------------------+---------------------------------------------+
|Author     |Keys                     |Comment                                      |
+-----------+-------------------------+---------------------------------------------+
|Jason Jones|Day: 2                   |Comment 1                                    |
|           |Month: December          |                                             |
|           |Row: 1                   |                                             |
|           |Year: 2016               |                                             |
|Jason Jones|Market: New York         |Test comment                                 |
|           |Measures: COGS           |                                             |
|           |Product: Root Beer       |                                             |
|           |Scenario: Variance       |                                             |
|           |Year: Jan                |                                             |
+-----------+-------------------------+---------------------------------------------+

The view-comments command (as well as the export and import commands) also allow for specifying an include and exclude "key spec" or key specification. This lets you filter the comments to include/exclude such that all the comments meet all of the specified criteria. By way of a simple example, you may wish to export all comments that contain as part of their intersection the key of "Market" with a value of "New York". That can be specified as follows:

view-comments --include-key-spec "Market=New York"

Note that the whole key spec is in quotes since one of the values contains a space in it.

You may instead decide that you want to view/export all comments that simply have a key named Market, but with any value. This can be specified as follows:

view-comments --include-key-spec "Market="

You may want to specify just comments where the value is "West" but for whatever reason it doesn’t matter what the key is:

view-comments --include-key-spec "=West"

You can also specify that comments should have multiple keys and values, such as those comments that have Market set to West but also where Measures is set to Sales:

view-comments --include-key-spec "Market=West,Measures=Sales"

Again, not that the exported comments must satisfy all of the specified key specs, not just some of them.

You may want to exclude certain combinations as well. This works similarly to the include key spec in that the excluded comments must match all of the specifications. For example:

view-comments --include-key-spec "Market" --exclude-key-spec "Market=New York,Year=Jan"

The preceding example would include comments that have Market as part of their key set (with any value), while also excluding those comments that have Market set to New York AND have Year set to Jan. Comments that have Market set to New York but that have Year set to something besides Jan will not be excluded.

Export Comments

The export-comments command supports the same syntax as the view-comments command but with an additional --file parameter that the contents are exported to.

Import Comments

The import-comments command is used to specify a comment export file that has previously been created with the export-comments command.