(Check out the SAP Developer Challenge - APIs blog post for everything you need to know about the challenge to which this task relates!)
In this task, you're going to create an instance of the SAP Cloud Management Service, with a specific plan. To find out why, read on.
Background
This task follows on from and is in a group with the previous task (Task 7 - Create a new directory in an SAP BTP account). Having created a directory in your SAP Business Technology Platform (SAP BTP) account, you're going to eventually retrieve that directory's details programmatically, through an API endpoint.
In making such a call to the appropriate endpoint, you need to supply authentication details in the HTTP header.
What do the authentication details look like, and how do you obtain them? Well, in this and subsequent tasks, you'll find out, by reading, and by doing!
The details of the API endpoint
On the reading part, you should start out by jumping back to the Core Services for SAP BTP API package landing page on the SAP Business Accelerator Hub that you viewed in the previous task. You'll see a range of APIs, like this:
The Accounts Service API is described thus: "Manage the directories and subaccounts in your global account's structure". This is the API containing the endpoint that you'll eventually use to look at the details of the directory you created in the previous task.
Selecting this API, and navigating to its API Reference section, specifically to the Directory Operations group, you'll see quite a list of endpoints, some of which you can see in this screenshot:
One of them is the one you'll eventually be calling:
Note that the final part of the endpoint's path, {directoryGUID}, is what we need to specify when making a call to this endpoint. Remind you of anything? Yes, it's the GUID value of your newly created directory that you determined in the previous task.
While you're staring at the details of this endpoint, make a mental note of this part:
Required scope: $XSAPPNAME.global-account.account-directory.read
This will become relevant shortly.
The documentation on this API
While you're still in reading mode, jump back to the Accounts Service API Overview and follow the link to the SAP Help Portal documentation Account Administration Using APIs of the SAP Cloud Management Service. It's here that you'll find information on setting up for calls to this API and its endpoints. Take some time to read through the linked section and the subsections within.
Here's a very brief summary of what it says, so you have something concise to which you can refer in this and subsequent tasks in this group.
In order to make calls to API endpoints in this API (and indeed the other APIs in the package), you'll need to follow these steps:
- create an instance of the SAP Cloud Management Service, with a plan that contains the appropriate scope(s) that you need
- create a service key based on that instance
- use the details in the service key to request an access token
- use the access token thus obtained to authenticate a call to the API endpoint
The documentation mentions different environments in which you might create an instance of the service; for the purposes of this Developer Challenge as a whole, please use a Cloud Foundry environment. This is for a couple of reasons:
- everyone can get a Cloud Foundry environment on SAP BTP; for example, if you're using a trial account you will most likely have a Cloud Foundry environment automatically set up for you in your subaccount, and if you don't have one, you can create one
- it makes running this task and the related tasks simpler and we can all take part in the same collective and shared conversation about what we're doing
OK, let's look at precisely what your task is. That list of steps above looks quite a lot of work ... but don't worry. Your task today relates only to step 1 in the list.
Your task
There are two parts to your task here. In both parts, you should use the cf command line tool for Cloud Foundry (also known as the "cf CLI").
There are different ways you could go about creating a service instance on Cloud Foundry, but here the cf CLI is prescribed because it can be used for not only creating the instance, but also for retrieving detailed information afterwards. And of course, also because #TheFutureIsTerminal 🙂
For part one, you must complete step 1 in the list above, i.e. create an instance of the SAP Cloud Management Service (short name: cis). Do this in your SAP BTP account that you used in the previous task. Make sure you choose the appropriate plan when doing this, and create the instance in your Cloud Foundry environment.
Information on where to find the service plan details, and tips on how to create the instance itself, are detailed in the "Hints and tips" section.
For part two, you must use the Cloud Foundry API to retrieve information about your newly created service instance. Specifically, you should use the List all Service Instances endpoint (GET /v2/service_instances). And as you'll have already been using the cf CLI for part one of this task, you are strongly encouraged to use it for this part as well. Did you know that you can use the cf CLI to make calls to the CF API as well? Find out more in the "Hints and tips section below".
From the information you retrieve via the GET /v2/service_instances endpoint, you should identify the appropriate object in the resources property in the JSON returned, and pick out the value of the entity type.
Here's an example (with some properties removed for brevity):
{ "total_results": 1, "resources": [ { "metadata": { "guid": "58314563-ab6d-48db-b40c-ae4abf0e0355", "url": "/v2/service_instances/58314563-ab6d-48db-b40c-ae4abf0e0355", "created_at": "2023-08-15T10:31:13Z", "updated_at": "2023-08-15T10:31:15Z" }, "entity": { "name": "cis-central", "credentials": {}, "service_plan_guid": "7cc70093-3c5f-47f2-acf6-8de4185ba63c", "space_guid": "52311e40-efaa-4176-bef1-505f3a9889bd", "gateway_data": null, "dashboard_url": null, "type": "<instance-type>", "last_operation": { "type": "create", "state": "succeeded", "updated_at": "2023-08-15T10:31:15Z", "created_at": "2023-08-15T10:31:15Z" }, "tags": [], "maintenance_info": {}, "service_guid": "4eacd0ef-9a9d-4cb3-8fb1-60fb685d8f82" } } ] }
As you can see in this example, there's only one service instance in the Cloud Foundry environment org / space used to set up this example. This is reflected in the fact that there's only a single object contained in the resources array. That object represents and contains the details of that service instance.
The type of the service instance is given in the entity.type property within the object. In the example above, the value is deliberately hidden, and has been replaced by the string <instance-type>.
For those of you who are curious and have also tried to use cf service to list details of the service, note that the entity type shown in the output to cf service is not quite the same, and not what is required here. You have been warned!
It's the actual value of this entity.type property that you must determine and send to be hashed and shared in a reply to this discussion thread as described in Task 0. So whatever that value is, in the JSON that's returned, that's what you need to send to be hashed (don't include the double quotes, because they're just part of the JSON syntax of course).
Hints and tips
Here are some pointers to help you with this task.
Creation of the service instance
If you read through the Account Administration Using APIs of the SAP Cloud Management Service documentation, you will have come across the SAP Cloud Management Service - Service Plans section. In this section, the details of each service plan offered are available, including a list of scopes provided by each.
When creating the service instance, make sure you specify the appropriate plan, the plan that contains the scope that you need to make a GET request to the /accounts/v1/directories/{directoryGUID} API endpoint.
Using the cf CLI
You are required to use the cf CLI for both parts of this task. Some of you may already have the cf CLI installed. Others may not.
For those of you who have it installed, or are willing and able to install it in their own system, we recommend you use the latest major version, i.e. version 8. The reason for this is twofold:
- the major version of the cf CLI available in all Dev Spaces in the SAP Business Application Studio is 8 (specifically, at the time of writing, version 8.5.0+73aa161.2022-09-12)
- there are some breaking changes introduced between major versions 7 and 8, including in the area of the output of service binding details, so it's best that we're all on the same version and we also recommend you move to 8 now anyway
See Upgrading to cf CLI v8 for details of what's new and different with version 8.
For those who don't already have the cf CLI installed, and don't want to install it right now, we recommend you make use of a Dev Space in the SAP Business Application Studio. Just like the Cloud Foundry environment itself, a subscription to the SAP Business Application Studio is available to anyone and everyone, not least within a trial SAP BTP account context. You can follow the tutorial Set Up SAP Business Application Studio for Development if you need some guidance on getting access.
Once you have a subscription to the SAP Business Application Studio, create yourself a Dev Space. It doesn't have to be anything special - even a Basic Dev Space contains the cf CLI, as you can see:
Once you have a Dev Space up and running, and you have of course opened up a terminal session therein (use menu path "Terminal -> New Terminal"), you have the cf CLI at your disposal.
At this point you should log in, and specify the API endpoint that relates to your specific Cloud Foundry environment instance.
There are different ways to find out what the API endpoint is (including programmatically, see Determining your CF API endpoint), but a simple way for the purposes of this task is to head over to the SAP BTP Cockpit and check in the subaccount overview:
Once you've logged in, you'll need to familiarize yourself with the cf CLI commands related to this task.
For the first part of the task, look into the "Services integration" commands (get to this list using the command cf help):
Services integration: marketplace,m create-user-provided-service,cups services,s update-user-provided-service,uups create-service,cs create-service-key,csk update-service delete-service-key,dsk delete-service,ds service-keys,sk service service-key bind-service,bs bind-route-service,brs unbind-service,us unbind-route-service,urs
In particular:
- cf marketplace will give you a list of service offerings; specifying a particular service offering with the -e option is also worth looking into
- cf create-service will allow you to create a new service instance, specifying the plan as well as the service
- cf services will allow you to list services instances that already exist, allowing you to check that your service instance creation was successful
When using cf marketplace, note that the service offerings will be listed using their technical name. The technical name for the SAP Cloud Management Service is cis, as noted in the Account Administration Using APIs of the SAP Cloud Management Service section on the SAP Help Portal.
For the second part of the task, you'll want to look at:
- cf curl
Interestingly, if you want to find this command in the list of possible commands in the cf CLI, you must use:
cf help -a
(i.e. include the -a option) otherwise it's not shown.
Good luck and have fun!
For discussion
How else might one create an instance of a service? Is this your first encounter with the cf CLI? How did you find it? What is your favorite place to run command line tools?
yes. I have the following setup, an old (feature set a) global account (SAP Mentors ABAP Cloud System) and a new Free Tier account.
When I log in using the UI I allways see this:
I allready specified the other global account as the default. However, this doesn't seem to have the desired effect.
When I login with the CF CLI i get this:
❯ cf l
API endpoint: https://api.cf.eu10.hana.ondemand.com
Email: christian.drumm@gmail.com
Password:
Authenticating...
OK
Targeted org abapcp-mentors-eu10.
Targeted space Trial.
API endpoint: https://api.cf.eu10.hana.ondemand.com
API version: 3.140.0
user: christian.drumm@gmail.com
org: abapcp-mentors-eu10
space: TrialIf I then try to get the orgs I only see this:
❯ cf o
Getting orgs as christian.drumm@gmail.com...
name
abapcp-mentors-eu10
Hi, Could you please help me to understand what I might be missing. I am using central plan; but receiving the following 403 error while trying out from business accelerator hub. I am trying to get the directory information, authorization is enabled already for the directory.
-Anupam
Hi DJ,
I tried with postman too to get the directory information; it gives me same 403 error:
I Created cloud management service instance with central plan. Tried with both password and client credential tokens. Every time I am getting this error. Not sure what I am missing.
-Anupam
