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>]

Artifact Commands

delete-all-artifacts

Command Format

delete-all-artifacts

Deletes all binary artifacts in the current tenant. Other objects (comments, audit logs, users, roles) are not affected. For deleting all objects in a given tenant, consider the delete-tenant command.

delete-artifact

Command Format

delete-artifact [--artifact string] --category string --version integer

Parameters

  --artifact string

      [Mandatory]

  --category string

      [Optional, default = <none>]

  --version integer

      [Optional, default = 1]

Deletes a single artifact from the current tenant. Only the artifact ID is required but this command will only work when an artifact has been uniquely specified. If there are multiple artifacts with the same ID then the category and/or version will be necessary to disambiguate.

Examples

Delete view artifact named IncStmt

delete-artifact IncStmt VIEW

import-starter-kit

Command Format

import-starter-kit

Imports the standard Dodeca repository starter kit to the current tenant. This is an embedded copy of the starter kit that is contained inside of Dodeca Shell so that no external file needs to be referenced.

Examples

Basic Example

use TEST
import-starter-kit

list-artifacts

Command Format

list-artifacts --category string --id string [--latest-only ]

Parameters

  --category string

      [Optional, default = <none>]

  --id string

      [Optional, default = <none>]

  --latest-only

      [Optional]

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

Examples

List all artifacts in current tenant

list-artifacts

Output

ID                                                 CATEGORY                       TYPE                 VERSION
-------------------------------------------------- ------------------------------ -------------------- -------
DodecaTeal_OfficeWhite_Style                       GENERAL                        StyleLibrary         1
HyperionStyle                                      GENERAL                        StyleLibrary         1
Office2010Style_Blue                               GENERAL                        StyleLibrary         1
Standard                                           HIERARCHY                      Hierarchy            1
CustomToolControllers                              MODULE                         Module               1
ADMIN                                              SMART_CLIENT_APPLICATION       WindowsApplication   1
USER                                               SMART_CLIENT_APPLICATION       WindowsApplication   1
Essbase Admin Console                              TOOLBARS_CONFIGURATION         ToolbarConfig        1
Essbase View Main All                              TOOLBARS_CONFIGURATION         ToolbarsConfig       1
Essbase View Main Limited                          TOOLBARS_CONFIGURATION         ToolbarsConfig       1
Essbase View Standard All                          TOOLBARS_CONFIGURATION         ToolbarsConfig       1
Essbase View Standard All Excel AddIn              TOOLBARS_CONFIGURATION         ToolbarsConfig       1
Essbase View Standard Limited                      TOOLBARS_CONFIGURATION         ToolbarsConfig       1
Excel View Main                                    TOOLBARS_CONFIGURATION         ToolbarsConfig       1
Excel View Standard                                TOOLBARS_CONFIGURATION         ToolbarsConfig       1
Excel View Standard with Edit Tools                TOOLBARS_CONFIGURATION         ToolbarsConfig       1
PDF View Standard                                  TOOLBARS_CONFIGURATION         ToolbarsConfig       1
PDF View Standard All                              TOOLBARS_CONFIGURATION         ToolbarsConfig       1
SQL View Standard                                  TOOLBARS_CONFIGURATION         ToolbarsConfig       1
SQL View Standard with Save Only                   TOOLBARS_CONFIGURATION         ToolbarsConfig       1
View Console                                       TOOLBARS_CONFIGURATION         ToolbarConfig        1
View Standard                                      TOOLBARS_CONFIGURATION         ToolbarsConfig       1
Web Browser IE                                     TOOLBARS_CONFIGURATION         ToolbarsConfig       1
Web Browser IE Extended                            TOOLBARS_CONFIGURATION         ToolbarsConfig       1
Web Browser Report                                 TOOLBARS_CONFIGURATION         ToolbarsConfig       1
Web Browser Report Extended                        TOOLBARS_CONFIGURATION         ToolbarsConfig       1
Adhoc_ExcelAddInMode                               VIEW                           AdhocEssbase         1

print-artifact

Command Format

print-artifact [--artifact string] --category string --version integer [--bytes ] --output-file string

Parameters

  --artifact string

      [Mandatory]

  --category string

      [Optional, default = <none>]

  --version integer

      [Optional, default = 1]

  --bytes

      [Optional]

  --output-file string

      [Optional, default = <none>]

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. 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. 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.

Examples

Print IncStmt View

print-artifact IncStmt VIEW 1

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 </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>
      ...

Trying to print an artifact that is ambiguously specified

print-artifact IncStmt

Output

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

recovery-app

Command Format

recovery-app --recovery-app-id string

Parameters

  --recovery-app-id string

      [Optional, default = RECOVERY]: The artifact ID for the recovery application

Creates a new application in the current tenant that does not have any configuration authentication provider. By default, the app will have ID RECOVERY. This app can be used to login to the Dodeca tenant and update authentcation settings for a different app that may not be working properly (for example, due to misconfiguring its authentication settings). This app should be deleted after the main app has been fixed.

Artifact Dependency Commands

depends-on

Command Format

depends-on [--artifact string] --category string --version integer

Parameters

  --artifact string

      [Mandatory]

  --category string

      [Optional, default = <none>]

  --version integer

      [Optional, default = 1]

You may run a reverse dependency search to determine what depends on a given artifact.

Examples

Find artifacts that depend on IncStmt template

depends-on IncStmt GENERAL 1

Output

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

view-dependencies

Command Format

view-dependencies [--artifact string] --category string --version integer --scanner-config string [--stack ] [--table ]

Parameters

  --artifact string

      [Mandatory]

  --category string

      [Optional, default = <none>]

  --version integer

      [Optional, default = 1]

  --scanner-config string

      [Optional, default = <none>]

  --stack

      [Optional]: Add the artifacts to the artifact stack

  --table

      [Optional]: print dependencies in table format

View the dependencies (artifacts that a given artifact depends on) of a given aritfact.

Examples

View Dependencies of Income Statement VIEW

dshell/SAMPLE:>view-dependencies IncStmt VIEW 1

Output

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

Audit Log Commands

delete-data-audit-log-records

Command Format

delete-data-audit-log-records [--all ] --days integer

Parameters

  --all

      [Optional]: Delete all data audit log records

  --days integer

      [Optional, default = <none>]: Delete all data audit log records older than the given number of days

Deletes records from the data audit log. The data audit log tables are populated, for example, when data is submitted in a view and updates a cube.

Examples

Delete all data audit log records in current tenant

delete-data-audit-log-records --all

Delete data audit log records in the current tenant that are older than 30 days

delete-data-audit-log-records --days 30

delete-metadata-audit-log-records

Command Format

delete-metadata-audit-log-records [--all ] --days integer

Parameters

  --all

      [Optional]: Delete all metadata audit log records

  --days integer

      [Optional, default = <none>]: Delete all metadata audit log records older than the given number of days

Deletes records from the metadata audit log (a log of artifact contents as they’ve been updated).

Examples

Delete all metadata audit log records in current tenant

delete-metadata-audit-log-records --all

Delete metadata audit log records in the current tenant that are older than 30 days

delete-metadata-audit-log-records --days 30

Comment Commands

comment-summary

Command Format

comment-summary

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

copy-comments

Command Format

copy-comments --author string --include-key-spec string --exclude-key-spec string --remove-key-spec string --add-key-spec string --new-author string --tenant string

Parameters

  --author string

      [Optional, default = <none>]

  --include-key-spec string

      [Optional, default = <none>]

  --exclude-key-spec string

      [Optional, default = <none>]

  --remove-key-spec string

      [Optional, default = ]

  --add-key-spec string

      [Optional, default = ]

  --new-author string

      [Optional, default = <none>]: Update the created by property

  --tenant string

      [Optional, default = <none>]: Set different tenant for the 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"

delete-comments

Command Format

delete-comments [--all ] --author string --include-key-spec string --exclude-key-spec string

Parameters

  --all

      [Optional]: Delete all comments

  --author string

      [Optional, default = <none>]

  --include-key-spec string

      [Optional, default = <none>]

  --exclude-key-spec string

      [Optional, default = <none>]

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.

export-comments

Command Format

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

Parameters

  --file string

      [Mandatory]

  --author string

      [Optional, default = <none>]

  --include-key-spec string

      [Optional, default = <none>]

  --exclude-key-spec string

      [Optional, default = <none>]

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.

find-comments

Command Format

find-comments [--include-key-spec string] [--partial-address ]

Parameters

  --include-key-spec string

      [Mandatory]: Key spec of comments to update, such as Period=Jan,Scenario=Actual

  --partial-address

      [Optional]: Set if key spec address only needs to be partial match

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.

import-comments

Command Format

import-comments [--comment-file string]

Parameters

  --comment-file string

      [Mandatory]

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

update-comments

Command Format

update-comments --include-key-spec string --update-key-spec string [--partial-address ] --remove-key-spec string

Parameters

  --include-key-spec string

      [Optional, default = <none>]: Key spec of comments to update, such as Period=Jan,Scenario=Actual

  --update-key-spec string

      [Optional, default = <none>]: Key spec to update/add, such as Year=FY20

  --partial-address

      [Optional]: Set if key spec address only needs to be partial match

  --remove-key-spec string

      [Optional, default = <none>]: Comma separated list of keys to remove from address

Used to create copies of comments by modifying their POV somehow.

Data Source Commands

connect

Command Format

connect --connection-file string

Parameters

  --connection-file string

      [Optional, default = <none>]

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

drivers

Command Format

drivers

Lists the available JDBC drivers that are currently available to the running instance of the shell.

Examples

Example

drivers

Output

oracle.jdbc.OracleDriver
com.ibm.db2.jcc.DB2Driver
com.mysql.jdbc.Driver
com.mysql.fabric.jdbc.FabricMySQLDriver
org.postgresql.Driver
com.microsoft.sqlserver.jdbc.SQLServerDriver
org.h2.Driver

encrypt

Command Format

encrypt [--text string]

Parameters

  --text string

      [Mandatory]

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. The encrypted password can then be used in your connection file:

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

Examples

Example

encrypt mypassword

Output

ENC(CjzrGUAl14fEcR9Y2zo06lvlTg8fjkTd)

inmem

Command Format

inmem

Sets the current connection as a completely in-memory relational database. This can be useful for testing commands and operations without needing to setup an entire database. Upon creation, the in-memory database will have the Dodeca schema deployed to it. The in-memory database will be lost after exiting Dodeca Shell.

jdbc-test

Command Format

jdbc-test --file string

Parameters

  --file string

      [Optional, default = <none>]

Provides a simple wizard for helping define and test the JDBC connection settings for the Dodeca repository.

Examples

Create and test a connection to SQL Server database

Output

dshell/:>jdbc-test
0 - oracle.jdbc.OracleDriver
1 - com.ibm.db2.jcc.DB2Driver
2 - com.mysql.jdbc.Driver
3 - com.mysql.fabric.jdbc.FabricMySQLDriver
4 - org.postgresql.Driver
5 - com.microsoft.sqlserver.jdbc.SQLServerDriver
6 - org.h2.Driver
JDBC Driver Class (hibernate.connection.driver_class) [0]:
5
Hibernate Dialect (hibernate.dialect) [com.appliedolap.dodeca.hibernate.dialect.SQLServerUnicodeDialect]:

Connection Username (hibernate.connection.username) []:
sa
Connection Password (hibernate.connection.password) []:
password1
Database Server (include colon and port if needed) (server) []:
db1:1400
Schema (Database name for SQL Server) (schema) []:
DODECA
JDBC URL (hibernate.connection.url) [jdbc:sqlserver://db1:1400;DatabaseName=DODECA;SelectMethod=cursor]:

hibernate.connection.driver_class: com.microsoft.sqlserver.jdbc.SQLServerDriver
                hibernate.dialect: com.appliedolap.dodeca.hibernate.dialect.SQLServerUnicodeDialect
    hibernate.connection.username: sa
    hibernate.connection.password: password1
                           server: db1:1400
                           schema: DODECA
         hibernate.connection.url: jdbc:sqlserver://db1:1400;DatabaseName=DODECA;SelectMethod=cursor
Parameters correct? [y]
Test connection? [y]
Connected!
Update an existing dodeca.properties file? [y]n
Write settings to a connection file? [y]
Wrote settings to /Users/dodeca/dodeca-hibernate.properties

list-connections

Command Format

list-connections

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.

set-checksum-function

Command Format

set-checksum-function --checksum-function string

Parameters

  --checksum-function string

      [Optional, default = <none>]

Used to force the checksum function being used by the shell. Dodeca Shell will attempt to use the proper checksum function for your version of Dodeca (e.g. Dodeca 7.x uses SHA-1, Dodeca 8.x+ uses SHA-256). You may need to manually set this when working with an older version of a Dodeca repository.

License Commands

import-license

Command Format

import-license [--file string] [--validate-only ]

Parameters

  --file string

      [Mandatory]

  --validate-only

      [Optional]

Imports a Dodeca license file to the server. The license can be specified as a file relative to where Dodeca Shell was executed or by using a fully-qualified path. It may be useful/easier to specify the license by double-quoting the path and using forwardslashes instead of backslashes on Windows, in order to avoid any potential backslash issues.

Examples

Example

import-license "C:/Dodeca/license1.txt"

Output

The Dodeca license has been correctly verified.

Company Name:      Applied OLAP
Project Name:      n/a
Tenant Code:       n/a
Perpetual License: True
License Scope:     Server

Dodeca Spreadsheet Management System:
  Enabled:         True
  Expiration:      12/30/2020 11:59:59 PM
  Users:           100
  Trial License:   False

Dodeca Excel Add-In for Essbase:
  Enabled:         True
  Expiration:      12/30/2020 11:59:59 PM
  Users:           100
  Trial License:   False

Drillbridge:
  Enabled:         True
  Expiration:      12/30/2020 11:59:59 PM
  Users:           100
  Trial License:   False

validate-current-license

Command Format

validate-current-license

Validates the current license loaded to the server and displays it:

Examples

Example

validate-current-license

Output

The Dodeca license has been correctly verified.

Company Name:      Applied OLAP
Project Name:      n/a
Tenant Code:       n/a
Perpetual License: True
License Scope:     Server

Dodeca Spreadsheet Management System:
  Enabled:         True
  Expiration:      12/30/2020 11:59:59 PM
  Users:           100
  Trial License:   False

Dodeca Excel Add-In for Essbase:
  Enabled:         True
  Expiration:      12/30/2020 11:59:59 PM
  Users:           100
  Trial License:   False

Drillbridge:
  Enabled:         True
  Expiration:      12/30/2020 11:59:59 PM
  Users:           100
  Trial License:   False

Misc Commands

decode

Command Format

decode [--encoded-contents string]

Parameters

  --encoded-contents string

      [Mandatory]

Decodes an encoded text value. The general use case for this is when you want to verify the contents of an artifact in your Dodeca repository and copy its value from your SQL tool.

Examples

Decode the encoded contents of the IncStmt view

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=

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>

Repository Commands

create-tenant

Command Format

create-tenant [--tenant string] [--import-starter-kit ] [--delete-existing ] --file string

Parameters

  --tenant string

      [Mandatory]

  --import-starter-kit

      [Optional]

  --delete-existing

      [Optional]

  --file string

      [Optional, default = <none>]

Creates a new tenant. This command is roughly equivalent to deleting an entire tenant, optionally importing the standard starter kit, then optionally importing a specified export file to load. Before loading, the entire Dodeca repository will be searched any existing objects associated with that tenant. If any exist then the creation process will stop. The --delete-existing parameter can be used to automatically delete everything, although you are encouraged to make a backup/export of the tenant before doing so.

Examples

Create a new tenant named DEMO, load the standard starter kit, then load an existing export file

create-tenant DEMO --import-starter-kit --file SAMPLE.zip

export-all-tenants

Command Format

export-all-tenants --base-dir string [--include-system-tenants ] [--append-date ] [--all ] [--exclude-artifacts ] [--include-artifacts ] [--exclude-artifact-usages ] [--include-artifact-usages ] [--exclude-comments ] [--include-comments ] [--exclude-comment-audit-log ] [--include-comment-audit-log ] [--exclude-data-audit-log ] [--include-data-audit-log ] [--exclude-metadata-audit-log ] [--include-metadata-audit-log ] [--exclude-users ] [--include-users ] [--exclude-user-roles ] [--include-user-roles ] [--exclude-roles ] [--include-roles ] [--exclude-saved-views ] [--include-saved-views ] [--exclude-saved-view-accesses ] [--include-saved-view-accesses ] [--exclude-view-usages ] [--include-view-usages ]

Parameters

  --base-dir string

      [Optional, default = <none>]

  --include-system-tenants

      [Optional]: Includes system tenants in the export (license, system config, etc.)

  --append-date

      [Optional]: Append a datestamp to the file

  --all

      [Optional]: Turn on exporting all metadata (individual types can still be excluded)

  --exclude-artifacts

      [Optional]: Exclude artifacts

  --include-artifacts

      [Optional]: Include artifacts

  --exclude-artifact-usages

      [Optional]: Exclude artifact usages

  --include-artifact-usages

      [Optional]: Include artifact usages

  --exclude-comments

      [Optional]: Exclude comments

  --include-comments

      [Optional]: Include comments

  --exclude-comment-audit-log

      [Optional]: Exclude comment audit log

  --include-comment-audit-log

      [Optional]: Include comment audit log

  --exclude-data-audit-log

      [Optional]: Exclude data audit log

  --include-data-audit-log

      [Optional]: Include data audit log

  --exclude-metadata-audit-log

      [Optional]: Exclude metadata audit log

  --include-metadata-audit-log

      [Optional]: Include metadata audit log

  --exclude-users

      [Optional]: Exclude users

  --include-users

      [Optional]: Include users

  --exclude-user-roles

      [Optional]: Exclude user roles

  --include-user-roles

      [Optional]: Include user roles

  --exclude-roles

      [Optional]: Exclude roles

  --include-roles

      [Optional]: Include roles

  --exclude-saved-views

      [Optional]: Exclude saved views

  --include-saved-views

      [Optional]: Include saved views

  --exclude-saved-view-accesses

      [Optional]: Exclude saved view accesses

  --include-saved-view-accesses

      [Optional]: Include saved view accesses

  --exclude-view-usages

      [Optional]: Exclude view usages

  --include-view-usages

      [Optional]: Include view usages

Exports all tenants to export files, one file per tenant.

Examples

Export all normal tenants

export-all-tenants

Output

Exporting ./SAMPLE.zip
Exporting ./STARTER_KIT.zip
Exporting ./DEMO.zip

Export all tenants including reserved/system tenants

export-all-tenants --include-system-tenants

Output

Exporting ./SAMPLE.zip
Exporting ./STARTER_KIT.zip
Exporting ./DEMO.zip
Exporting ./___DODECA_EXCEL_ADDIN___.zip
Exporting ./___DODECA_SERVER_LICENSE___.zip

Export all tenants including reserved/system tenants and append date

export-all-tenants --include-system-tenants --append-date

Output

Exporting ./SAMPLE_20210518T204610.zip
Exporting ./STARTER_KIT_20210518T204610.zip
Exporting ./DEMO_20210518T204610.zip
Exporting ./___DODECA_EXCEL_ADDIN____20210518T204610.zip
Exporting ./___DODECA_SERVER_LICENSE____20210518T204610.zip

list-tenants

Command Format

list-tenants [--deep ]

Parameters

  --deep

      [Optional]: Check for tenant presence based on all tables, not just binary artifacts

Lists the available tenants, based on the presence of objects in the repository. In general, tenants will be determined based on the presence of objects in the artifacts table.

Examples

Example

list-tenants

Output

+---------------------------+
|Tenant                     |
+---------------------------+
|DEMOWARE                   |
|SAMPLE                     |
|___DODECA_SERVER_LICENSE___|
+---------------------------+

Example

list-tenants --deep

Output

+---------------------------+
|Tenant                     |
+---------------------------+
|DEMOWARE                   |
|SAMPLE                     |
|SAMPLE2                    |
|___DODECA_SERVER_LICENSE___|
+---------------------------+

recompute-checksums

Command Format

recompute-checksums

Recomputes checksums for all artifacts and comments in the database. This shouldn’t normally need to be used but may be necessary if the checksums are out of sync.

tables

Command Format

tables

Lists the database tables in the current repository. Useful to quickly gauge if you’re connected to a new schema or one that needs to be upgraded.

Examples

Example

tables

Output

BINARY_ARTIFACTS
BINARY_ARTIFACT_USAGES
COMMENTS
COMMENT_ATTACHMENTS
COMMENT_AUDIT_LOG
COMMENT_KEY_ITEMS
DATABASECHANGELOG
DATABASECHANGELOGLOCK
DATA_AUDIT_LOG
DATA_AUDIT_LOG_DATAPOINTS
DATA_AUDIT_LOG_ITEMS
METADATA_AUDIT_LOG
METADATA_AUDIT_LOG_ITEMS
SSO_TOKENS
SSO_TOKEN_ATTRIBUTES
USERS
USER_ROLES
USER_ROLE_MAPPINGS
VIEW_ACCESS
VIEW_USAGE_LOG

unuse

Command Format

unuse

Unsets the current tenant. Normally this does not need to be performed explicitly, but may be useful in automation scenarios where you want to make sure that a certain tenant will not be operated on.

Examples

Example

- unuse

upgrade

Command Format

upgrade --target-version string [--dry-run ]

Parameters

  --target-version string

      [Optional, default = <none>]: Migrate schema to a particular version (advanced use only)

  --dry-run

      [Optional]

Deploys or upgrades the Dodeca schema to the current connected repository. All data in the database will be preserved. If used with a blank repository, then all tables and related objects will be created. When used against a version 7 repository, it will be upgraded to the version associated with this version of Dodeca shell.

use

Command Format

use [--tenant string] [--force ] [--skip-tenant-check ]

Parameters

  --tenant string

      [Mandatory]

  --force

      [Optional]: Force use of the tenant, even if it doesn't exist

  --skip-tenant-check

      [Optional]: Skip tenant check, has no effect if force is used

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.

Smart Client Commands

Text: Traditional Dodeca deployments have Smart Client files stored inside of the metadata servlet (.war) file or in the /smartclient folder (when using the standalone distribution). As an advanced deployment scenario, the Smart Client may be stored in the Dodeca repository itself. The Smart Client commands are used to import, manage, and deploy Smart Clients in this configuration scenario, but are not needed at all for normal deployments. Repository clients must be enabled by configuring the dodeca.client-deployment-type configuration setting.

client-versions

Command Format

client-versions

Lists all versions of the Smart Client that are stored in the repository, if any.

delete-clients

Command Format

delete-clients

Deletes clients that are stored in the repository.

import-client

Command Format

import-client [--client-zip string]

Parameters

  --client-zip string

      [Mandatory]

Imports a client zip file to the repository.

upgrade-client

Command Format

upgrade-client --version string

Parameters

  --version string

      [Optional, default = <none>]

Switches the current client version to the latest available in the repository.

Tenant Commands

delete-tenant

Command Format

delete-tenant [--confirm ]

Parameters

  --confirm

      [Optional]: This flag must be set in order to confirm deletion

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

export-certificate

Command Format

export-certificate [--filename string] [--days integer]

Parameters

  --filename string

      [Mandatory]: File to export certificate to

  --days integer

      [Mandatory]: Number of days that the exported certificate is valid for

Exports a certificate that can be imported to a Dodeca Essbase servlet for use in setting up authentication using impersonation via SAML.

export-tenant

Command Format

export-tenant --output-directory string --filename string [--append-date ] [--all ] [--exclude-artifacts ] [--include-artifacts ] [--exclude-artifact-usages ] [--include-artifact-usages ] [--exclude-comments ] [--include-comments ] [--exclude-comment-audit-log ] [--include-comment-audit-log ] [--exclude-data-audit-log ] [--include-data-audit-log ] [--exclude-metadata-audit-log ] [--include-metadata-audit-log ] [--exclude-users ] [--include-users ] [--exclude-user-roles ] [--include-user-roles ] [--exclude-roles ] [--include-roles ] [--exclude-saved-views ] [--include-saved-views ] [--exclude-saved-view-accesses ] [--include-saved-view-accesses ] [--exclude-view-usages ] [--include-view-usages ]

Parameters

  --output-directory string

      [Optional, default = <none>]

  --filename string

      [Optional, default = <none>]

  --append-date

      [Optional]: Append a datestamp to the file

  --all

      [Optional]: Turn on exporting all metadata (individual types can still be excluded)

  --exclude-artifacts

      [Optional]: Exclude artifacts

  --include-artifacts

      [Optional]: Include artifacts

  --exclude-artifact-usages

      [Optional]: Exclude artifact usages

  --include-artifact-usages

      [Optional]: Include artifact usages

  --exclude-comments

      [Optional]: Exclude comments

  --include-comments

      [Optional]: Include comments

  --exclude-comment-audit-log

      [Optional]: Exclude comment audit log

  --include-comment-audit-log

      [Optional]: Include comment audit log

  --exclude-data-audit-log

      [Optional]: Exclude data audit log

  --include-data-audit-log

      [Optional]: Include data audit log

  --exclude-metadata-audit-log

      [Optional]: Exclude metadata audit log

  --include-metadata-audit-log

      [Optional]: Include metadata audit log

  --exclude-users

      [Optional]: Exclude users

  --include-users

      [Optional]: Include users

  --exclude-user-roles

      [Optional]: Exclude user roles

  --include-user-roles

      [Optional]: Include user roles

  --exclude-roles

      [Optional]: Exclude roles

  --include-roles

      [Optional]: Include roles

  --exclude-saved-views

      [Optional]: Exclude saved views

  --include-saved-views

      [Optional]: Include saved views

  --exclude-saved-view-accesses

      [Optional]: Exclude saved view accesses

  --include-saved-view-accesses

      [Optional]: Include saved view accesses

  --exclude-view-usages

      [Optional]: Exclude view usages

  --include-view-usages

      [Optional]: Include view usages

Exports the current tenant to a zip file that can be imported with import-tenant. The default export includes the binary artifacts in the tenant, but various options allow for specifying exporting other tenant data, such as comments, data audit log, metadata audit log, users, and roles.

Examples

Export all data for the current tenant

export-tenant --all

Output

Exporting to SAMPLE.zip
Finished export

Export all data for the current tenant and automatically include a timestamp on export file

export-tenant --all --append-date

Output

Exporting to SAMPLE_20210518T203553.zip
Finished export

Export all data excluding the data audit log for the current tenant

export-tenant --all --exclude-data-audit-log

Output

Exporting to SAMPLE.zip
Finished export

generate-encryption-keys

Command Format

generate-encryption-keys [--regenerate ] --logical-id string --token-duration-seconds string --certificate-duration-days string

Parameters

  --regenerate

      [Optional]: Specify to regenerate the public/private keys if they already exist

  --logical-id string

      [Optional, default = <none>]: The logical ID of the Dodeca server (typically the Dodeca server name, or load balancer)

  --token-duration-seconds string

      [Optional, default = 86400]: Token duration seconds

  --certificate-duration-days string

      [Optional, default = 3650]: Number of days crypto certificate will be valid for

Generates encryption keys for the current tenant. Generally only used when setting up impersonation via SAML for an Essbase connection. If the keys are already set, they will not be regenerated unless it is forced with the regenerate option.

This functionality is generally used to a establish a trust relationship between the Dodeca server and a Dodeca Essbase connector. The logical ID must match the alias used when importing the certificate to the Java key store on the Dodeca Essbase Connector. As a best practice, the logical ID will generally be the fully-qualified domain name of your Dodeca server, such as mustang.appliedolap.com. The corresponding certificate file that is generated may be mustang.appliedolap.com.cer. The exact filename isn’t important, but when the certificate is imported to the Java key store on the Dodeca Essbase Connector, the alias for the imported certificate should match the logical ID.

Examples

Simple usage

generate-encryption-keys

Usage when encryption keys are already set

generate-encryption-keys

Output

Public/private keys are already set, use --regenerate to force regeneration. Existing connectors with corresponding keys will stop working

Force key regeneration

generate-encryption-keys --regenerate

Generate keys, set related tenant options, and export a certificate for input into the Java keystore of a Dodeca Essbase Connector. The default certificate duration of 3,650 days (10 years) will be used.

generate-encryption-keys --regenerate --logical-id mustang.appliedolap.com

Output

Exported certificate to mustang.appliedolap.com.cer

import-tenant

Command Format

import-tenant [--file string] --imported-by string [--all ] [--exclude-artifacts ] [--include-artifacts ] [--exclude-artifact-usages ] [--include-artifact-usages ] [--exclude-comments ] [--include-comments ] [--exclude-comment-audit-log ] [--include-comment-audit-log ] [--exclude-data-audit-log ] [--include-data-audit-log ] [--exclude-metadata-audit-log ] [--include-metadata-audit-log ] [--exclude-users ] [--include-users ] [--exclude-user-roles ] [--include-user-roles ] [--exclude-roles ] [--include-roles ] [--exclude-saved-views ] [--include-saved-views ] [--exclude-saved-view-accesses ] [--include-saved-view-accesses ] [--exclude-view-usages ] [--include-view-usages ]

Parameters

  --file string

      [Mandatory]

  --imported-by string

      [Optional, default = system]: Use a specified name on the import instead of the default

  --all

      [Optional]: Turn on exporting all metadata (individual types can still be excluded)

  --exclude-artifacts

      [Optional]: Exclude artifacts

  --include-artifacts

      [Optional]: Include artifacts

  --exclude-artifact-usages

      [Optional]: Exclude artifact usages

  --include-artifact-usages

      [Optional]: Include artifact usages

  --exclude-comments

      [Optional]: Exclude comments

  --include-comments

      [Optional]: Include comments

  --exclude-comment-audit-log

      [Optional]: Exclude comment audit log

  --include-comment-audit-log

      [Optional]: Include comment audit log

  --exclude-data-audit-log

      [Optional]: Exclude data audit log

  --include-data-audit-log

      [Optional]: Include data audit log

  --exclude-metadata-audit-log

      [Optional]: Exclude metadata audit log

  --include-metadata-audit-log

      [Optional]: Include metadata audit log

  --exclude-users

      [Optional]: Exclude users

  --include-users

      [Optional]: Include users

  --exclude-user-roles

      [Optional]: Exclude user roles

  --include-user-roles

      [Optional]: Include user roles

  --exclude-roles

      [Optional]: Exclude roles

  --include-roles

      [Optional]: Include roles

  --exclude-saved-views

      [Optional]: Exclude saved views

  --include-saved-views

      [Optional]: Include saved views

  --exclude-saved-view-accesses

      [Optional]: Exclude saved view accesses

  --include-saved-view-accesses

      [Optional]: Include saved view accesses

  --exclude-view-usages

      [Optional]: Exclude view usages

  --include-view-usages

      [Optional]: Include view usages

Imports a tenant from an export zip created either from the Dodeca client or from the export-tenant command.

list-tenant-option-names

Command Format

list-tenant-option-names

Lists available tenant option names.

Examples

Example

list-tenant-option-names

Output

Available options: [logical-id, token-duration-seconds]

set-tenant-option

Command Format

set-tenant-option [--option-name string] [--option-value string]

Parameters

  --option-name string

      [Mandatory]

  --option-value string

      [Mandatory]

Sets a tenant option. For a list of valid option names, use the list-tenant-option-names command. Generally only needs to be used when configuring impersonation via SAML for Essbase authentication.