Dodeca Shell

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:

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:

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:

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

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:

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.

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:

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

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

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:

You will then be presented with help like the following:

Command Format

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.

Command Format

Parameters

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.

Command Format

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.

Command Format

Parameters

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

Command Format

Parameters

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.

Command Format

Parameters

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.

Command Format

Parameters

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

Command Format

Parameters

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

Command Format

Parameters

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.

Command Format

Parameters

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

Command Format

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

Command Format

Parameters

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:

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:

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:

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

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:

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:

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:

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

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

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:

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

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

Command Format

Parameters

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.

Command Format

Parameters

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.

Command Format

Parameters

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:

With output such as the following:

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:

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:

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

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:

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:

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.

Command Format

Parameters

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

Command Format

Parameters

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

Command Format

Parameters

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

Command Format

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

Command Format

Parameters

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:

Command Format

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.

Command Format

Parameters

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

Command Format

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:

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

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.

Command Format

Parameters

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.

Command Format

Parameters

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.

Command Format

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

Command Format

Parameters

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.

Command Format

Parameters

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.

Command Format

Parameters

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

Command Format

Parameters

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.

Command Format

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.

Command Format

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.

Command Format

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.

Command Format

Parameters

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.

Command Format

Parameters

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:

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):

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:

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.

Command Format

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

Command Format

Deletes clients that are stored in the repository.

Command Format

Parameters

Imports a client zip file to the repository.

Command Format

Parameters

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

Command Format

Parameters

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

Command Format

Parameters

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

Command Format

Parameters

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.

Command Format

Parameters

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.

Command Format

Parameters

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

Command Format

Lists available tenant option names.

Command Format

Parameters

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.