Skip to Content
Technical Articles

SAP Analytics Cloud SCIM API Best Practices and Sample Scripts

Your one-stop shop for everything related to SAP Analytics Cloud SCIM API is here!

An essential blog for those:

  • that have no interest in how the API works, you just want to use it to fulfil a function
  • system administrators, system integrators or developers that need to understand how the API works, behaves and performs

I introduce two new articles:

  1. Sample Scripts
  2. Best Practices

Sample Scripts

I’ve created 45 sample scripts in Postman (called ‘Collections’ in Postman) that fulfil a whole range of functions related to the Analytics Cloud SCIM API:

SAP%20Analytics%20Cloud%20SCIM%20API%20Sample%20Scripts

SAP Analytics Cloud SCIM API Sample Scripts

These scripts allow you to perform a great number of user management operations and cover everything from creating users, updating users, performing team-on-team operations and even transporting users and teams from one SAP Analytics Cloud service to another!

I’ve designed these scripts to:

  1. be easily consumable (simple .csv files or .json files are needed)
  2. provide very maximum throughput possible (of not only the Analytics Cloud API, but also of Postman)
  3. return a known result

Creating and updating users

There are some 18 scripts to create and update users! Why so many? Some just read a .csv file so that its super easy for you to use. Others need to read a .json file as they need to read an array (of teams for example). There’s different ones depending upon what you’re doing, for example some are designed for greatest throughput for creating users, others for updating.

I designed these scripts to cover as many use-cases as possible. For example when updating users, the scripts read an ‘action’ so you can ‘add’, ‘remove’, ‘replace’ or just ‘keep’ the existing team and role assignment. (the scripts are versatile allowing you to use different actions for teams and roles)

creating%20or%20updating%20a%20user%20actions%20on%20teams%20and%20roles

creating or updating a user – actions on roles (left) and teams (right)

Updating users by team

Updating user properties requires an update to each user, but I often hear customers wishing to update a whole team of users. So, I provide scripts that reads a team, and then update all members of that team. For example, script 451 will update the ‘Business Intelligence licence type’ for all users of a team. You’ll find a script for almost every purpose including updating: active status, manager, datatime/number format, language and many more.

Team-on-team

I frequently hear of customers wishing to add a team to another team. Whilst this isn’t technically possible, it hasn’t stopped me using the API to read a team and add all the users of one team to another. Thus, I have scripts that perform this ‘team-on-team’ operations. With the ‘actions’ idea taken to act across teams, it means you can even do things like remove a team from another, as well as perform ‘set’ operations on teams including ‘intersect’ and ‘exclude’:Team-on-team%20actions

Team-on-team actions (shown is for users, but roles are also possible)

Transporting users and teams

You can’t really transport a user from one SAP Analytics Cloud service to another. However that hasn’t stopped me using the API to read all the properties of a user and either create or update the same user in another Service! It means I have created scripts that basically transport a user, albeit without their personal folder.

Relationships%20transported%20between%20SAP%20Analytics%20Cloud%20Services

Relationships transported between SAP Analytics Cloud Services

Not only do I transport the user, but I also transport all the relationships to roles and teams. My transport scripts are highly versatile allowing you to transport whatever relationship you’d like to or not. I’ve extended the ‘actions’ concept from earlier allowing you to perform ‘add’, ‘remove’, ‘replace’ or just ‘keep’ either the existing teams or roles as you please! This in turn means there are now more life-cycle use-cases supported (as the Service only performs an ‘add’ operation when it comes to transporting relationships)

And because I’m using the API, you can use my scripts to transport between NEO and Cloud Foundry (or any combination)

For all my sample scripts, if the team doesn’t exist, it will create one for you!

Getting started

Getting%20started

These samples, provided ‘as is’, are available to download from today. Getting started couldn’t be easier! It will take novice no more than 40 minutes.

I provide a comprehensive User Guide, an article and a webinar to introduce it all.

Best Practices built-in

The scripts are designed with all the best practices and means you don’t need to worry about sessions or error management. That’s all taken care for you:

  1. Errors from the API are handled and automatic re-attempts will be made
  2. This includes errors that are exceptionally rare

And the very maximum performance is provided. They are highly intelligent scripts, for example they will:

  1. only perform an update if one is actually needed
  2. determine the ‘net’ change to a team, and only make the necessary changes
  3. batch requests together so to optimise team updates
  4. they even include automatic and dynamic self-tuning for updating teams by batching and chunking updates!

Demo

If you’d like to cut to the chase and see the scripts in action – preview or download

Best Practices

For those that need to understand more about the API then my article on the Best Practices covers everything!

My article is almost a training course on the API and provides practice examples covering things like session management and the basic things like creating or updating users and teams.

Managing%20errors%20on%20a%20create%20update%20workflow

Managing errors on a create update workflow

I dive into the detail of combining the ‘create’ and ‘update’ workflow to help illustrate where care is needed around the API. For example, how to recover from a 409 or a 502 response. I answer the questions like “is it safe to resubmit a POST /Users (create user)”?

I’ve done all the thinking for you, so you don’t need to necessarily work it out for yourself or learn from your mistakes. I’ve covered the lot including helping you to identify when there might be a error, even very rare errors, and how to resolve them to a known result.

I take a very close look at the different workflows to achieve a particular task and share with you how to get the very maximum throughput possible. For example:

Activity or action: Workflow (not optimised) Optimised workflow
Creating 500 users and adding each user into 3 teams 1 hour 15 mins 20 mins
Updating 500 users 25 mins 4 seconds 10 mins 13 secs
Updating 500 users and removing each user from 3 teams, and adding each user into 3 different teams 3 hours 37 mins 27 mins
Adding 500 users into a team 13 minutes 13 seconds

Updating teams can be particularly challenging when the membership is over 5000 and the total number of users registered is over 10,000. I share with you how to achieve the maximum throughput and reliability for adding 32767 users into a team on a service with 80000 users registered in it:

No one wants a surprise and so even if you’ve already implemented a solution using the API, you should find my article useful especially as user volumes increase

Performance

Both my articles provide comprehensive information.

Best Practices article provides, for every endpoint the performance of the API for both an empty service and one with 80000 users registered in it. Here’s one example:

 

And the samples article provides information on the throughput of the script, including its overhead expressed as a percentage and shown in (brackets). Here’s one example:

Articles & downloads

Your complete list of resources is summarised here:

Sample Scripts

Sample Scripts Presentation
(version 1.0.1 – May 2021)
Wiki
Preview PPT
Download PPT
Webinar 1h 38 mins
.mp4 Preview
.mp4 Download
Sample Scripts Demo .mp4 Preview
.mp4 Download
Sample Scripts User Guide
(version 0.5.1 – June 2021)
.pdf Download
Samples (the code)
(version 0.5 – May 2021)
Github (zip download) Change log

 

Best Practices

Best Practices Presentation
(version 1.0.1 – June 2021)
Wiki
Preview PPT
Download PPT
Webinar 1h 50mins
.mp4 Preview
.mp4 Download

 

Feedback

I’ve invested a great deal of time and effort into these materials and so your feedback is very welcome and will help judge if I should continue to create these kind of resources

Please do:

  • Comment if you use these resources in anyway (or if you’re shy, just hit the like button!)
  • Share which sample scripts you’ve used. Other customers would love to hear if you’ve used the scripts. It will give them a sense of how reliable they are! 😉
  • Share your experience of adopting the best practices, for example by how much did you improve your scripts’ performance, or did you resolve a rare error?
  • Share how much time you saved because of these resources, would you had been as successfully without them?

Before posting any questions please:

  • Do read the contents of both articles (or watch the videos). There’s a massive amount of content in each. I appreciate you may not have the time to read or watch them all. If you’re looking for a quick answer and don’t have the time, feel free to post a question to the community rather than here, it will help keep the number of questions here reduced and it will help others find answers easier (than searching this blogs’ Q and A). You can always ‘@tag’ me in your post so I get a notification, and you can always post a link to your question from a comment to this blog if you think that might help others.
  • If you’ve got a question about the sample scripts, make sure you’ve read the User Guide! Some of the sample scripts are highly versatile and support a great number of use-cases, so I can imagine a few good discussions here about that.

Feel free to follow this blog post for updates and also follow the wiki pages for updates there too. I’ll update the version numbers in this blog post when there’s one.

Many thanks

Matthew Shaw @MattShaw_on_BI

https://people.sap.com/matthew.shaw/#content:blogposts

 

9 Comments
You must be Logged on to comment or reply to a post.