Tutorial 9: Shell project management

This tutorial describes advanced project management techniques in CleverMaps Shell.

In the first tutorial, you've learned how to create a project, dump it, import a dimension and add some data & metadata. Now the project has been handed over and your clients are using it. So what about extensions? What about data updates? We sure don't want our clients to use an incomplete/broken project. We'll create a clone, perform our work there, and then elegantly put our changes back to the live project. Here's how.

Creating a project clone

The process of creating a project clone is very similar to the process of importing a data dimension. Data dimension is a project like any other, so by importing it to your own project, you're actually creating a clone of it.

If we want to create a fresh, clean clone, we have to create a new project for it first. Log in to CleverMaps Shell and create a new project using the createProject command.

Then we use the import command. We specify the --project parameter with the project's ID, and the --server parameter to import the project from the server.

Let's skip some of the import command output...

After the import finishes successfully, use the addMetadata command to upload the metadata, and pushProject to upload the data.

This creates an identical clone of the original project. A clone might serve multiple purposes. It can be used as:

  • a working copy of the original project (where updates are made, and which later replaces the original project)
  • a base for a branched out, similar project (in order not to start from scratch)
  • a backup of older version of the project (to be archived)

Restoring a backup dump

Each dump is an image of a project in a specific time. So, a local dump can be used as a backup of a project. It is useful to periodically dump the project you're working on, to save your previous work. This way, in case you break the live project, you can always revert to a previous version of the project.

The first step is to truncate the live project of all data and metadata. Open the project again to close the curent dump, and use the truncateProject command.

Then use listDumps to list previous dumps of the project.

We've decided that we want to roll the project back to the previous dump with id 2019-01-30_14-08-31. This is possible by specifying the --dump parameter. 

Import with --dump parameter will first check if the project is empty. It is, because we've truncated it earlier. This behaviour can be overriden by specifying the --force parameter. 

Let's skip some of the import command output again...

The final step to restore the backup dump is to upload the data and metadata to the project. As usually, use addMetadata and pushProject to do that.

Updating a live project

Now that we've done some work on the project clone, we want to transfer the changes to the live project.

So with the premise that we don't want our clients to use use an incomplete/broken project still in mind, what can we do? Before we update the data and metadata, we will set the project's status to disabled, using the editProject command.

Setting the project's status to disabled displays a maintenance notification to the user. This notification varies for different user roles:

  • Admin role sees a popup window (which can be dismissed) and a warning bar at the bottom and can still access all project's views 
  • Editor, Load data and Viewer roles can access the Project page, but cannot access any of the project's views

So you, as an Admin can still review the changes you've made, but other users are informed about the maintenance and are told to come back later.

Project page for Admin roleProject page for Editor, Load data and Viewer roles

With the live project being disabled, we can truncate it of all data and metadata. Open the project again to close the curent dump, and use the truncateProject command.

Now, we will import the latest dump of the clone project, where we've done all the work. Use import command with both --dump and --project parameters.

Let's skip some of the import command output again...

And as the finish message tells us, use the usual addMetadata and pushProject commands to upload the updated dump to the live project.

After that, you as an Admin can open the project in the application. Dismiss the "Maintenance is under way" popup window, enter the Transactions view, and check out if everything works, and the changes you've done in the clone project are there.

Finally, we can switch the project's status back to enabled, and let all our users in.