Updating Comment Addresses

This workflow shows how to update existing comment addresses in a Dodeca repository. Because comment updates can affect many rows, the example first exports a tenant and imports it into an in-memory repository so the changes can be tested before they are applied to the target repository.

Connect to an existing Dodeca repository:

dshell/:>connect local-dodeca-server

Validate the connection by listing the detected tenants:

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

Switch to the SAMPLE tenant:

dshell/:>use SAMPLE
dshell/SAMPLE:>

Export the tenant. The default export-tenant command includes comments:

dshell/SAMPLE:>export-tenant

This creates SAMPLE.zip in the current directory. Create a new in-memory Dodeca repository to test the comment modifications:

dshell/SAMPLE:>inmem

A new repository, including all Dodeca tables, is created in memory. It is lost when Dodeca Shell exits. This provides a simple place to test changes. Verify that the in-memory repository has no tenants:

dshell/SAMPLE:>list-tenants

The result should be empty:

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

dshell/:>

Set the active tenant to SAMPLE. Use --force because the tenant does not exist yet in the in-memory repository:

dshell/SAMPLE:>use SAMPLE --force

Import the tenant export created earlier:

dshell/SAMPLE:>import-tenant SAMPLE.zip

Use view-comments to inspect the comments in the repository. For repositories with many comments, this command can generate a large amount of output:

dshell/SAMPLE:>view-comments
+------+-------------------+-----------------------------------------------+-------------------+
|Author|Keys               |Comment                                        |Created            |
+------+-------------------+-----------------------------------------------+-------------------+
|system|Entity: Entity1    |This is a comment for Scenario2/Period4/Entity1|2021-02-04T20:02:14|
|      |Period: Period4    |                                               |                   |
|      |Scenario: Scenario2|                                               |                   |
|system|Entity: Entity2    |This is a comment for Scenario2/Period4/Entity2|2021-02-04T20:02:14|
|      |Period: Period4    |                                               |                   |
|      |Scenario: Scenario2|                                               |                   |
|system|Entity: Entity0    |This is a comment for Scenario9/Period3/Entity0|2021-02-04T20:02:14|
|      |Period: Period3    |                                               |                   |
|      |Scenario: Scenario9|                                               |                   |

... omitted for brevity ...

|system|Entity: Entity1    |This is a comment for Scenario2/Period1/Entity1|2021-02-04T20:02:14|
|      |Period: Period1    |                                               |                   |
|      |Scenario: Scenario2|                                               |                   |
+------+-------------------+-----------------------------------------------+-------------------+

Use find-comments to look for comments at a particular intersection:

dshell/SAMPLE:>find-comments "Scenario=Scenario2"
+------+----+-------+-------+
|Author|Keys|Comment|Created|
+------+----+-------+-------+

Comments: 0

No comments are found because no comment has an address that consists only of Scenario=Scenario2. To search by a partial address, add --partial-address:

dshell/SAMPLE:>find-comments "Scenario=Scenario2" --partial-address
+------+-------------------+-----------------------------------------------+-------------------+
|Author|Keys               |Comment                                        |Created            |
+------+-------------------+-----------------------------------------------+-------------------+
|system|Entity: Entity1    |This is a comment for Scenario2/Period4/Entity1|2021-02-04T20:02:14|
|      |Period: Period4    |                                               |                   |
|      |Scenario: Scenario2|                                               |                   |
|system|Entity: Entity2    |This is a comment for Scenario2/Period4/Entity2|2021-02-04T20:02:14|
|      |Period: Period4    |                                               |                   |
|      |Scenario: Scenario2|                                               |                   |

... omitted for brevity ...

|system|Entity: Entity1    |This is a comment for Scenario2/Period1/Entity1|2021-02-04T20:02:14|
|      |Period: Period1    |                                               |                   |
|      |Scenario: Scenario2|                                               |                   |
+------+-------------------+-----------------------------------------------+-------------------+

Comments: 15

After the test data is loaded and the target comments are identified, use update-comments. This command updates all comments whose address includes Scenario=Scenario2, changing the Scenario value to Budget:

dshell/SAMPLE:>update-comments --include-key-spec "Scenario=Scenario2" --partial-address --update-key-spec "Scenario=Budget"

After the update, searching for the original partial address should return no comments:

dshell/SAMPLE:>find-comments "Scenario=Scenario2" --partial-address
+------+----+-------+-------+
|Author|Keys|Comment|Created|
+------+----+-------+-------+

Comments: 0

Searching for the updated partial address should return the 15 updated comments:

dshell/SAMPLE:>find-comments "Scenario=Budget" --partial-address
+------+----------------+-----------------------------------------------+-------------------+
|Author|Keys            |Comment                                        |Created            |
+------+----------------+-----------------------------------------------+-------------------+
|system|Entity: Entity1 |This is a comment for Scenario2/Period4/Entity1|2021-02-04T20:02:14|
|      |Period: Period4 |                                               |                   |
|      |Scenario: Budget|                                               |                   |
|system|Entity: Entity2 |This is a comment for Scenario2/Period4/Entity2|2021-02-04T20:02:14|
|      |Period: Period4 |                                               |                   |
|      |Scenario: Budget|                                               |                   |

... omitted for brevity ...

|system|Entity: Entity1 |This is a comment for Scenario2/Period1/Entity1|2021-02-04T20:02:14|
|      |Period: Period1 |                                               |                   |
|      |Scenario: Budget|                                               |                   |
+------+----------------+-----------------------------------------------+-------------------+

Comments: 15

The include key specification is optional. If it is omitted, every comment in the repository is affected:

dshell/SAMPLE:>update-comments --update-key-spec "Foo=Bar"
dshell/SAMPLE:>view-comments
+------+-------------------+-----------------------------------------------+-------------------+
|Author|Keys               |Comment                                        |Created            |
+------+-------------------+-----------------------------------------------+-------------------+
|system|Entity: Entity1    |This is a comment for Scenario2/Period4/Entity1|2021-02-04T20:02:14|
|      |Foo: Bar           |                                               |                   |
|      |Period: Period4    |                                               |                   |
|      |Scenario: Scenario2|                                               |                   |
|system|Entity: Entity2    |This is a comment for Scenario2/Period4/Entity2|2021-02-04T20:02:14|
|      |Foo: Bar           |                                               |                   |
|      |Period: Period4    |                                               |                   |
|      |Scenario: Scenario2|

...

Use --remove-key-spec to remove keys from comment addresses. This variation removes the Foo key that was added to every comment in the previous example:

dshell/SAMPLE:>update-comments --remove-key-spec "Foo"
dshell/SAMPLE:>view-comments
+------+-------------------+-----------------------------------------------+-------------------+
|Author|Keys               |Comment                                        |Created            |
+------+-------------------+-----------------------------------------------+-------------------+
|system|Entity: Entity1    |This is a comment for Scenario2/Period4/Entity1|2021-02-04T20:02:14|
|      |Period: Period4    |                                               |                   |
|      |Scenario: Scenario2|                                               |                   |
|system|Entity: Entity2    |This is a comment for Scenario2/Period4/Entity2|2021-02-04T20:02:14|
|      |Period: Period4    |                                               |                   |
|      |Scenario: Scenario2|                                               |                   |
|system|Entity: Entity0    |This is a comment for Scenario9/Period3/Entity0|2021-02-04T20:02:14|
|      |Period: Period3    |                                               |                   |
|      |Scenario: Scenario9|                                               |                   |

...

Run this command carefully because address changes can create comment intersection collisions. For example, removing a key can cause a comment to have the same address as an existing comment.

After testing the commands, either run the same commands while connected to the repository that should be modified, or export the updated comments and import them into the target repository and tenant.

To export only comments from the in-memory tenant, use export-tenant --exclude-artifacts:

dshell/SAMPLE:>export-tenant --exclude-artifacts

This is the same export-tenant command used earlier, but it excludes artifacts from the export.

After connecting to the repository where the comments should be updated, select the target tenant. This example imports to a new tenant named SAMPLE2:

dshell/SAMPLE2:>use SAMPLE2 --force

Import the comments:

dshell/SAMPLE2:>import-tenant SAMPLE.zip

Validate the updated comment addresses:

dshell/SAMPLE2:>view-comments
+------+-------------------+-----------------------------------------------+-------------------+
|Author|Keys               |Comment                                        |Created            |
+------+-------------------+-----------------------------------------------+-------------------+
|system|Entity: Entity1    |This is a comment for Scenario2/Period4/Entity1|2021-02-04T20:02:14|
|      |Period: Period4    |                                               |                   |
|      |Scenario: Budget   |                                               |                   |
|system|Entity: Entity2    |This is a comment for Scenario2/Period4/Entity2|2021-02-04T20:02:14|
|      |Period: Period4    |                                               |                   |
|      |Scenario: Budget   |                                               |                   |
|system|Entity: Entity0    |This is a comment for Scenario9/Period3/Entity0|2021-02-04T20:02:14|
|      |Period: Period3    |                                               |                   |
|      |Scenario: Scenario9|                                               |                   |

...