Skip to Content
Technical Articles
Author's profile photo Jascha Kanngiesser

New Command-Line Interface for SAP Data Warehouse Cloud – code your way to the cloud!

Update: I released another blog “Automatically Add Members to Spaces in SAP Data Warehouse Cloud Using @sap/dwc-cli” describing how to automatically retrieve passcodes and do mass-member assignment to spaces in SAP Data Warehouse Cloud.


Although nice-looking and easy-to-use user interfaces are more important than ever for a software product to be willingly accepted by the market, enabling good automation and programmatic access to the solution is equally important. With good APIs at hand repetitive tasks can be easily automated and developers embed the solution in the company’s CI/CD automated setups and external applications.

Introduction

The SAP Data Warehouse Cloud Command-Line Interface (CLI) is available on npmjs.com as a standalone Node.js module. Starting with a small functional scope in the domain of space management, the CLI enables you as a user of SAP Data Warehouse Cloud to access your tenants programmatically, allowing you to automate and speed up recurring tasks which otherwise require lots of manual, repetitive work (and we, the digital natives of today, don’t like repetitive, manual work, eh?)

Using%20the%20command-line%20interface

Using the command-line interface

A little story to tell …

To provide you with some hands-on experience while reading this blog, I’m using the example of mass user assignment to spaces for demonstrating the power of the CLI.

Imagine the following situation: You’re the administrator of your company’s SAP Data Warehouse Cloud tenant and are asked to prepare the tenant for a new project that’s about to start soon. The project requires you to set up three spaces with slightly different settings regarding the space’s storage resources, and 1000 users assigned to each of the spaces. The list of users is available in an excel sheet.

Now, you start navigating to your tenant and create the first space. It takes a few seconds to load the UI and navigate to the space management, because, well, rendering the UI and loading the required resources isn’t done as quickly as that (do I really get the promised 100Mbit/s?). You configure the available resources, and start adding the first user. Then the second user, third user, fourth user, … you know the drill. A quick look at the clock tells you that you already spent 5 minutes to only create one space and assign 10 users. You quickly do the math and check your calendar whether there’s something up for the rest of the week. Luckily it’s friday and it seem you’ll enjoy a quiet afternoon and not much planned for the weekend, so enough time to continue the fun task at hand! 🙂

You stop assigning users as you start thinking that this task probably starts boring you within the next minute, open google.com and start typing “dwc automate space creation user assignment”. There’s one interesting hit which talks about the SAP Data Warehouse Cloud CLI. As you start making yourself familiar with the topic, you are keen to learn all about the new tool and how it will save you a tremendous amount of time when working with your SAP Data Warehouse Cloud tenant in the future.

Installation

The CLI is available on npmjs.com as a node module named @sap/dwc-cli. To install the tool, you require a node environment on the machine where you install the module. To figure out whether node is already installed in your environment, just run the following command:

$ node -v
v12.21.0

If installed, you should receive a response like v12.21.0 as above, returning the currently installed version. Otherwise, you can download the current node version from the node.js website and follow the installation instructions according to your environment.

Node modules are installed through the node package manager (npm). To install the @sap/dwc-cli module, run

$ npm install -g @sap/dwc-cli

The -g option is optional and installs the module globally in your environment, so you can call it from any place. If you want to install it locally into the current directory, omit the -g option.

To check whether the CLI is correctly installed, run

$ dwc -v
2021.20.0

Same as when checking the installed Node.js version, this command returns the currently installed CLI version. Don’t worry if a different version number is displayed. To get help on any available command, you can always add the -h or –help option to any command, and it will return more human-friendly information.

$ dwc -h
Usage: dwc [options] [command]

Command-Line Interface for SAP Data Warehouse Cloud.

Options:
  -v, --version   output the version number
  -h, --help      display help for command

Commands:
  spaces          manage and orchestrate spaces
  help [command]  display help for command

If you receive a similar output, you’re good to go!

Versioning

If you already have some experience with Node.js modules, npm and the like, you’ll probably wonder why we start with version 2021.20.0 instead of 1.0.0 like you normally do with new modules. Well, technically it doesn’t matter which version you start with. However, since Data Warehouse Cloud is also delivered in waves and you need an easy way to figure out whether the CLI version you use is compatible with the current wave deployed into your tenant, we decided to stay in sync with the wave versioning.

We will not ship a new CLI version with every new wave deployed into your tenant every other week, simply for the fact that there’s not always a change applied to the CLI only because a new wave is deployed. That approach causes the most recent CLI version available on npmjs.com to probably be lower than the currently deployed wave in your tenant. That doesn’t matter, because you simply need to ensure that you use the most recent CLI version which is equal or lower than the wave version deployed in your tenant. In case there are multiple CLI versions to which this statement applies, use the one with the highest version. Here’s a quick example:

Wave currently in the roll out process, 
but not yet available in all tenants: 2021.24

CLI versions available on nmpjs.com (in descending order, 
we didn't ship a new version for wave 2021.23 and 2021.20):
2021.24
2021.22
2021.19
2021.18

In case your tenant still uses wave 2021.23, you want to use version 2021.22 of the CLI, because the version is lower than the wave version, which also applies to versions 2021.19 and 2021.18, but from the list of these three versions we use the highest available one: 2021.22. If your tenant already received wave 2021.24, you want to use version 2021.24 of the CLI. Installing a specific version is as simple as running

$ npm install -g @sap/dwc-cli@2021.24.0

Add the version to be installed after the second @. To install the latest version, use the term latest:

$ npm install @sap/dwc-cli@latest

Usage

With the initially delivered version the CLI supports creating and updating space definitions, reading definitions of and deleting existing spaces. Following the use case described above, let’s take a close look at how the CLI enables us to set up everything within 5 minutes and less.

User Permissions

To create, read or update spaces in your SAP Data Warehouse Cloud tenant the user you use to retrieve the passcode has to have the following privileges assigned in SAP Data Warehouse Cloud:

Space: Create, Read, Update, Manage

Team: Create, Read, Update

Creating Spaces

We start by creating an empty space without connections or members assigned. We call the space MYSPACE with description “This is my space” and assign some storage and compute resources to it. The file to define the space looks like this:

// MYSPACE.json

{
    "MYSPACE": {
        "spaceDefinition": {
            "version": "1.0.4",
            "label": "This is my space",
            "assignedStorage": 10000000, // 100 MB
            "assignedRam": 10000000, // 100 MB
            "priority": 1
        }
    }
}

We save the file as MYSPACE.json. All properties except version are optional, meaning you can omit then when creating or updating a space. When omitting a property, in case it’s already defined in the tenant it is not touched. When creating a new space the default value is used. For your reference, all default values are documented in SAP Help. Thus, the least minimal file looks like this:

{
    "MYSPACE": {
        "spaceDefinition": {
            "version": "1.0.4"
        }
    }
}

We then need to know how we can supply the information to our SAP Data Warehouse Cloud tenant to create a new space. To figure out which command to run to create a space, we run dwc spaces -h to see which commands are available:

$ dwc spaces -h
Usage: dwc spaces [options] [command]

manage and orchestrate spaces

Options:
  -h, --help               display help for command

Commands:
  create [options]         creates/updates space details based on an import file
  delete [options] <name>  delete an existing space
  read [options] <name>    fetches space details for a specified space
  help [command]           display help for command

According to this output to create a space we shall run dwc spaces create:

$ dwc spaces create
error: required option -H, --host not specified

Do’h, seems like we’re missing something. What does the help say?

$ dwc spaces create -h
Usage: main spaces create [options]

creates/updates space details based on an import file

Options:
  -f, --filePath <filePath>  path to definition file
  -V, --verbose              print detailed log information to console (optional)
  -H, --host <host>          specifies the url host where the tenant is hosted
  -p, --passcode <passcode>  passcode for interactive session authentication (optional)
  -h, --help                 display help for command

Ah, we have to mention which host (tenant) we’d like to connect to and create the space in (makes sense!), and an optional passcode for authenticating our own user. We already know the tenant URL which typically follows the pattern https://<your company’s DWC prefix>.<region>.hcs.cloud.sap/, for example https://dwc-my-example-company.eu10.hcs.cloud.sap/. We don’t yet know what the passcode option is exactly, so let’s try running the CLI with the host and filePath option, pointing to our file we defined earlier, and omit the passcode option.

$ dwc spaces create -H https://dwc-my-example-company.eu10.hcs.cloud.sap/ -f MYSPACE.json
 Do you want to retrieve a passcode from https://dwc-my-example-company.authentication.eu10.hana.ondemand.com/passcode? … yes

Sweet, the CLI prompts us for a passcode because we didn’t provide one through the CLI options. When responding with Y (for Yes), it also opens the browser automatically and navigates to the mentioned URL:

Retrieving%20the%20passcode

Retrieving the passcode

Let’s copy the passcode and continue:

 Enter your temporary authentication code: … **********

Alright, the CLI didn’t return any errors. Let’s check our tenant whether the space exists. Et voilà, there we have it!

The%20newly%20created%20space

The newly created space

Reading Space Definitions

Now we’d like to check whether the definition we deployed to our tenant can be retrieved as well. We use the dwc spaces read command for this. Let’s see what the required arguments and options are by running the command using the -h, –help option.

$ dwc spaces read MYSPACE -H https://dwc-my-example-company.eu10.hcs.cloud.sap/
 Do you want to retrieve a passcode from https://dwc-my-example-company.authentication.eu10.hana.ondemand.com/passcode? … yes
 Enter your temporary authentication code: … **********
{
  "MYSPACE": {
    "spaceDefinition": {
      "version": "1.0.4",
      "label": "This is my space",
      "assignedStorage": 100000000,
      "assignedRam": 100000000,
      "priority": 1,
      "auditing": {
        "dppRead": {
          "retentionPeriod": 30,
          "isAuditPolicyActive": false
        },
        "dppChange": {
          "retentionPeriod": 30,
          "isAuditPolicyActive": false
        }
      },
      "members": [],
      "hdicontainers": {},
      "dbusers": {},
      "workloadClass": {
        "totalStatementMemoryLimit": {
          "value": 0,
          "unit": "Percent"
        },
        "totalStatementThreadLimit": {
          "value": 0,
          "unit": "Percent"
        }
      },
      "allowConsumption": false
    }
  }
}

Great, we successfully retrieved the definition of our space and can view it in the terminal. Also we can see that for those properties we didn’t supply respective default values were set. If we want to use this definition as an template to create another space, adjust it to our needs and push it back to our tenant, we can also save it in a file and continue from there. The help mentioned a -f or –filePath option, let’s try that.

$ dwc spaces read MYSPACE -H https://dwc-my-example-company.eu10.hcs.cloud.sap/ -f ./MYSPACE_NEW.json
 Do you want to retrieve a passcode from https://dwc-my-example-company.authentication.eu10.hana.ondemand.com/passcode? … yes
 Enter your temporary authentication code: … **********

The command didn’t return any errors, so let’s see whether a file named samplespace.json exists in the current directory and contains the definition we already saw in the terminal.

$ ls -la
total 20856
.
..
MYSPACE.json
MYSPACE_NEW.json

There it is, so we can use it now to update properties or as a template for another space.

Updating Spaces

Now, going back to our little story at the start of the blog. How do we continue for example if we want to add a list of users to our space? Before, when reading the space definition using the dwc spaces read command, we saw that there’s a property called members, which is an array including all users which are assigned to our space. It was empty when reading the space definition, meaning that no users are assigned to our spaces. To change this we need to send another space definition to our tenant and define the list of members to add to our space.

// MYSPACE_UPDATED.json

{
  "MYSPACE": {
    "spaceDefinition": {
      "version": "1.0.4",
      "members": [
        {
          "name": "FIRST_USER",
          "type": "user"
        },
        {
          "name": "SECOND_USER",
          "type": "user"
        },
        {
          "name": "THIRD_USER",
          "type": "user"
        },
        {
          "name": "FOURTH_USER",
          "type": "user"
        },
        {
          "name": "FITH_USER",
          "type": "user"
        }
      ]
    }
  }
}

For each user to add to our space we have to add an object to the array with properties name and type. The value for the property name equals a user ID existing in our tenant. The value for property type is always the constant value “user”. As you rightly guessed I’m using artificial user IDs here. When replacing the dummy IDs FIRST_USER, SECOND_USER, … with actual user IDs from our tenant and using the dwc spaces create command to send the updated definition to our tenant like so:

$ dwc spaces create -H https://dwc-my-example-company.eu10.hcs.cloud.sap/ -f ./MYSPACE_UPDATED.json -p somepasscode

We see that the users were added. Yay! We just saved ourselves at least a few seconds of our precious time compared to achieving the same through the UI. Image how this scales (and saves you enough time for another relaxing week off this year) when doing this for hundreds or thousands of users (assuming you find a smart way to generate the members array from a available list of users programmatically, but I trust in you, trust me).

Users%20added%20to%20a%20space

Users added to a space

Pay attention to the list of users you mention in the file sent to our tenant. The list is not merged with the previously assigned members, but any member not part of the new list is removed from the space. So, if you want to add some users and keep all previously assigned users in your space, be sure to include both lists in your space definition file.

Deleting Spaces

We can also delete spaces through the CLI using the delete command. The drill is similar to reading space definitions. We specify the space to be deleted and confirm the deletion either by passing the -f, –force flag or by answering the prompt in the terminal. Let’s try the latter by deleting our space we created earlier so that our tenant is cleaned up when we’re finished with reading this blog:

$ dwc spaces delete MYSPACE -H https://dwc-my-example-company.eu10.hcs.cloud.sap/
 Do you want to retrieve a passcode from https://dwc-my-example-company.authentication.eu10.hana.ondemand.com/passcode? … yes
 Enter your temporary authentication code: … **********
 Do you really want to delete space MYSPACE? … yes

As the command finished without any errors, the space was deleted successfully. When providing the -f or –force option, the CLI won’t prompt us to confirm the deletion, but only asks for the passcode if not provided using the -p, –passcode option.

Conclusion

The new CLI is a great addition to the existing tooling around SAP Data Warehouse Cloud for all people who spend a lot of their time working with the solution. Working on tasks which are repetitive and tedious and take a long time to accomplish when using the graphical user interface, like assigning many users to one or more spaces, can be easily automated and scaled. The mass-user assignment is only one of many examples how the CLI can improve your experience when working with SAP Data Warehouse Cloud to the next level.

I’d be happy to hear your thoughts, ideas and comments on this tool and what you think would be a nice-to-have enhancement to the CLI, making your life and work with SAP Data Warehouse Cloud easier. Let me know in the comments!

Further Reading

Blog: “Automatically Add Members to Spaces in SAP Data Warehouse Cloud Using @sap/dwc-cli”

Command-Line Interface for SAP Data Warehouse Cloud on npmjs.com

Command-Line Interface for SAP Data Warehouse Cloud on SAP Help

Get your SAP Data Warehouse Cloud 30 Days Trial Account

Assigned tags

      13 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Xavier Polo
      Xavier Polo

      Thanks Jascha, It looks promising!
      I hope that services will also be implemented to get data from the different layers, especially related to metadata, and help us for example to generate project documentation.

      Author's profile photo Jascha Kanngiesser
      Jascha Kanngiesser
      Blog Post Author

      Thank you for your reply Xavier! For example, you mean to download the definition of a view or table created in the Data Builder?

      Author's profile photo Xavier Polo
      Xavier Polo

      Yes, we need to generate documentation with fields, types, etc. I think we can get definition for tables from HANA Cloud system tables, but I don't know if this is also possible with views or business layer objects. We are using the CSN files but it has to be done one by one.

      I'm thinking also in metadata like the relation between objects, dependencies, information to get the lineage, It would be wonderful to be able to extract these dependencies and add them in project management tools.

      Or the information of "Business Purpose" section, we are working a lot with tags to to classify objects, intended use, etc. and all this information stays inside DWC, we don't know how to extract it in a general way.

      Kind regards,

      Author's profile photo Jascha Kanngiesser
      Jascha Kanngiesser
      Blog Post Author

      Thank you for your input Xavier! I added this to our CLI development backlog. Please watch out for new blog posts or Road Map Explorer updates regarding the CLI.

      Author's profile photo Xavier Polo
      Xavier Polo

      I always leave you good scores in your webinars surveys, so I don't know what else I could do to thank you 😀
      Seriously, if you need help with beta testing, I'll be happy to help.
      Thanks again.

      By the way, are there any DWC permissions or space configuration requirements to use it.
      I have done some testing but can't get the space details. I enter the password generated by the service when using the command:

      c:\> dwc spaces read DEV -H https://<TENTANT>.eu10.hcs.cloud.sap/

      but it returns "Definition of space DEV could not be retrieved". DEV is the technical and business name of the space. My user has access to the space and is a DWC administrator.

      Thanks

      Author's profile photo Jascha Kanngiesser
      Jascha Kanngiesser
      Blog Post Author

      True, I didn't mention it in the post and the official SAP Help page is not yet live. I updated the post and added a paragraph about user permissions I also quote here:

      "To create, read or update spaces in your SAP Data Warehouse Cloud tenant the user you use to retrieve the passcode has to have the following privileges assigned in SAP Data Warehouse Cloud:

      Space: Create, Read, Update, Manage

      Team: Create, Read, Update"

      Author's profile photo Jascha Kanngiesser
      Jascha Kanngiesser
      Blog Post Author

      You can also add -V, --verbose to the command to see few more details (also check dwc spaces read -h for more help on the command). What's the output if you add -V?

      Author's profile photo Xavier Polo
      Xavier Polo

      Reading definition for space DEV...
      GET https://dwaas-core-sac-saceu10.cfapps.eu10.hana.ondemand.com/api/v1/content?space=DEV&spaceDefinition=true
      Request failed with 404 Not Found
      Error: "The requested route is currently not available."
      Correlation ID f6320cb2-0a88-4ee2-64fa-75699c2a4077
      Definition of space DEV could not be retrieved

      Author's profile photo Jascha Kanngiesser
      Jascha Kanngiesser
      Blog Post Author

      There was a delay in service deployment which leads to the required endpoints not being available yet in EU10. Please try again tomorrow, they should be deployed again tonight.

      Author's profile photo Xavier Polo
      Xavier Polo

      it is now working, thank you

      Author's profile photo Jascha Kanngiesser
      Jascha Kanngiesser
      Blog Post Author

      Super! Let me know what you think about it and where we can improve. Happy to receive your feedback!

      Author's profile photo DJ Adams
      DJ Adams

      Nice post! And I'm glad to see you're resisting the urge to go for zsh 😉

      Screenshot%20showing%20standard%20macOS%20message%20suggesting%20a%20switch%20to%20zsh

      Stay strong. You could even install a modern version of bash, with brew, too, to replace the ancient one that ships with even modern versions of macOS.

       

      Author's profile photo Jascha Kanngiesser
      Jascha Kanngiesser
      Blog Post Author

      Haha, thanks for your reply DJ Adams! I'm actually using bash already 🙂

      $ echo $SHELL
      /bin/bash

      I'd be lost with zsh I guess, I'm too young for that, eben bash gives me hard times sometimes 😀