Hi, I am Denys van Kempen, SAP Partner Innovation Lab and the SAP HANA Academy.
In this video tutorial series we are going to cover the user and team provisioning API
of SAP Analytics Cloud. This video was recorded in September 2021;
for the latest video tutorials on the topic, please check the playlist.
In the previous video we showed how we can automate user provisioning using a single
Node.js command with Nfewman, which you can download, forgot to show you, if you go to
Postman settings, Add-ons tab, and then select Download Newman from npm. which will guide
you to the NPM website, to the newman entry and here you can read all about it.
OK As promised, in this video we are going to take an in-depth look at the code executed,
the API calls, and the scripts used to manage the processing flow.
Short recap, we imported our environment from the sample scripts, we covered this in a previous
video, where we showed where to get the URLs, the OAuth client id (username) and secret
(password), and how to configure content namespace and platform.
The current values are now blurred, I have recreated an OAuth client for the rest of
this series. To see a real-life example, you can watch
the video about the OAuth client. OK
Make sure that the environment is loaded. Then we are going to import our first collection.
Starting with number 101. There is some logic to the name, U for Users,
C for Create, F for file, c for CSV, j for JSON and so on
these sample script were created by Matthew Shaw from SAP who did a great job.
Select to open, and Import
The collection contains three statements; two POST, one GET
POST Create user is the API call doing all the work
The other two, as we will see, are just need for authorisation.
OK A POST API call, as mentioned
To our Analytics Cloud tenant service URL, resolved as variable
with API v1 SCIM in the path and Users as endpoint
no parameters as authorisation we pass an access token
Let me clear them out from the environment so we start from scratch.
The token will be passed in the header the authorisation tab here in Postman is just
to make the configuration a bit easier 10 headers are hidden
amongst which authorization as these are all set by Postman, being an
API client, which we can ignore them. We do need to set an x-csrf-token in the header,
as documented in the SAP Analytics Cloud user and team provisioning API developer guide,
we covered this in the video about OAuth, and here you can also read that you need to
set another header x-sap-sac-custom-auth plus one for the content type
our token is empty now if we then take a look at the body we can
see that indeed the content is JSON, we need to define the schema
and then we are going to pass a list of parameters, which for the most part will come as variable
but not defined anywhere yet email is an array, with work as primary, these
are hardcoded as using multiple e-mail address is rarely used, to my knowledge,
then the next section sets a number of custom parameters, which as a reminder, if we briefly
switch to the Users interface of Analytics Cloud
here we have the main settings user id, last name and email are required
as a minimum, and then when we select our user, profile settings, here we have the other
parameters as user preferences: language, date formatting, time formatting, currency
position, email notifications, and so on Now, if we export the User table, and open
the CSV file, we can see that there are even more variables to be set, offine phone, office
address, agile BI enabled, is user deactived, and so on.
OK back to our body,
here we see a selection, roles is also a JSON array, we will look into
roles in the next video prerequest script, this JavaScript code snippet
gets executed before the POST call is made some debug information to the console; we
saw this when we executed newman in the previous video;
particularly when creating many users, you can save the console output as log file for
auditing or validation purposes. there is a suggestion: why not do things right,
first time around? Making an update call to several hundred or
thousands of users just to change the date format will take some time, so take a look
these settings before you hit Send. here we are setting a number of variables
as constant with commentary about possible values; most of this will be documented but
there some relevant suggestions, like for example to set the booleans in lowercase.
then user name, first name, last name, email, we are going to read from file, we will see
this in a minute, roles and teams we will cover later, we are
just create users here and then with postman.variable.set we are
going to set these variables in the environment, like we did for the service URL and access
token previously, same thing OK
The script on the test tab is executed after the call,
so we are first checking for the response: expecting a 200, 201, 401 or 403
when we get 401 unauthorised we are going to do some processing and set next request
to the GET access token request plus two additional parameters: needgettoebauthorised and recovery,
we will get to this in a minute when we cover the GET access token request.
403 is less common, you can read the text for possible occurences,
409 indicates a conflict: user already exists 200 or 201 means we are good.
the unique identifier is email. We can have multiple John Smiths or Jean Martins
in which case the number one will be appended to the user name; and this will be logged
to the console as a warning. For all other responses we log the error or
warning OK
So in the first iteration, we expect a 401 and trigger Postman to call GET access token
This is the same call as covered in the previous video about the Oauth client
so with parameter grant_type = client-credentials the SAC token FQDN variable should be resolved
but oauth path will be red; unresolved, this is fine
as prerequest we are going to parse the SAC Platform variable and for CF set the path
to / oauth / The authorization for this call is basic auth
with username and password, well it will be the client ID from the OAuth Client
created for this purpose, with the secret as value for the token,
the variables are called username and password so they correspond to the Postman UI,
agian, we covered this in the video about Oauth
nothing in the body under test, we expect a 200
if so, we setting two variables: access token and x-csrf token, with value fetch, as documented
next request we get from the recovery setting, which as you may recall when we discussed
the tests for the POST Create user call was set th READ users for authorisation,
should we get an error here than there is something wrong with our Oauth client settings,
so we set next request to null and quit. very well,
Read users for authorisation this is a GET to the SAC service URL agian
with the parameters we are just requesting information about the system owner, there
is always one, to limit the amount of data sent
authorisation for the service is always using an access token
there are three custom headers as documented in the API guide, these need to be set
prerequest script just outputs a line for our log file so we know where we are, we saw
this with newman and as return code, expecting 200 OK or 401
(less likely) when we get 200 we check the environment for
the presence of the csrfokenvariable and if this contains the value fetch, we get the
token from the response header and set to the environment.
OK Let’s run the collection.
There is nothing defined at the collection level
What I do want to point out is the documentation here
provided as-is with a link to the user guide
and when we open this up and scroll down a bit
you can see that this collection is extensively documented.
when to use and when not to use there is also a link to a blog post from Matthew
Shaw, and this is the place to add your comments or ask any questions,
very well Run
we need to provide a file with users in either CSV or JSON format.
Let’s take a CSV I am using a slightly different sample here
with Dutch painters but that makes no difference, if we cat the file, you can see that it is
just a simple flat text file, comma separated You can preview the file also in the Postman
client, make sure all is well and then click run
the output looks pretty much the same as when using newman on the command line,
we call POST create user returns 403 forbidden
this sets next request to POST GET access token
200 OK we now have an access token
As test we read the recovery variable for next the request and find
GET READ users for authorisation 200 OK
we now also have an x-csrf token, so we can start processing the CSV file
Create user 201 created iteration 2
201 created iteration 3
201 created and we are done
each call takes about 2 seconds, gradually speeding up
Here is a summary the first create user required 4 calls, the
other two only a single call this should all make sense now
of course, when we refresh the security users view, we can see that our users have been
created should we run the collection again, we expect
an error, and we are getting one
409 assertion error: not expected,
although we do capture this and log some information to the console
here is the code, as a reminder so much for collection 101
in the next video we are going to take a look at how we can create a user with a role and
with a team, and also how we can delete users. See the description below for more information.
Don’t forget to subscribe. Denys van Kempen, SAP HANA Academy / Partner
Innovation Lab Thanks for watching.