Skip to Content
Technical Articles
Author's profile photo Matthew Shaw

SAP Analytics Cloud User and Team Provisioning 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

What are the business benefits and use-cases?

For those using the standard user interface to create or manage your users:

  • Automation. The scripts help to eliminate human errors in addition to saving considerable time performing multiple tasks. For example:
    • Creating users and adding them into multiple teams at the time of creation
    • Defining the users’ membership to multiple teams in one go (by either adding, removing or replacing those memberships)
    • Removing a user from all teams without having to first determine which teams the user is a member of. The standard interface doesn’t make this task so easy
  • Remove limitations of the User Interface, for example
    • They enable a team to have more than 4000 users
  • Eases the administration of users with team-on-team management capabilities (copy team, add or remove a team to or from another etc.)

In addition to the above, and whilst using your own Identity Provider with ‘automatic user creation’ and ‘user attribute mapping to teams’ do assist with the above tasks, these sample scripts also enable:

  • Further automation:
    • Updating a whole team of users at a time (for example updating all users of a team with a different BI license type or “active” status etc.)
    • Deleting users or a whole team of users at a time
    • Updating the users’ team membership so they receive publications sent to the team before they login (the user may miss a publication since SAML SSO only updates team membership at the time of login and not before)
  • Improved user creation:
    • Enables correct user settings at time of user creation. Users can be created with non-default settings for language, date/time/number formats, saving all your users from changes these settings
    • Enables user creation with the user id of your choice rather than one determined by SAP (a common requirement for SAML SSO based on email). This is often needed to enable easier integration with other systems, typically access control security rights based on acquired data models from BW.
  • Enables a multitude of life-cycle management use-cases. For example, transporting users and their relationship to teams and roles from one SAP Analytics Cloud Service to another (this just isn’t possible without these samples).
    • SAP Analytics Cloud can transport teams and their relationships to roles and when it does so, it ‘adds’ the relationships. For many life-cycle management use-cases you often don’t want to ‘add’, but either ‘replace’ or simply ‘keep’ the existing relationships of the target. These samples support these other use-cases easing your management of security across your landscape.
  • Service (tenant) migration use-cases when you’re moving or migrating from one SAP Analytics Cloud Service to another, for example migrating from NEO public to CF private. The samples can transport users* with their settings (of language, date/time/number formats etc.), unlike any user export/import provided by SAP Analytics Cloud.

For those that don’t need the sample scripts because you’re developing your own solution based off the SCIM API, then the best practices have everything and more you could ask for, from session and error management to sizing and performance. This article will dramatically accelerate your adoption and reduce your project risk.

 

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.

(Please also see the related blogs and videos for hands-on tutorials by HANA Academy)

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.3 – August 2021)
.pdf Download
.pdf Preview
Samples (the code)
(version 0.5.2 – October 2021)
Github (zip download) Change log

 

Best Practices

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

 

Blog posts referencing this blog post

  1. SAP Analytics Cloud – SAP SuccessFactors Import Model Security Use Case by Mohamed EZZAT
  2. Getting started with SAP Analytics Cloud, Embedded Edition (BTP service) by Alexey Dugarov
  3. SAP Analytics Cloud Embedded Edition | SAP Business Technology Platform | Hands-on Video Tutorials by Denys van Kempen
  4. SAP Analytics Cloud User and Team Provisioning API | Hands-on Video Tutorials by Denys van Kempen

Videos referencing this blog post

 

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

 

Assigned tags

      23 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Abhimanyu Sharma
      Abhimanyu Sharma

      How to connect SAC with SCIM ?

      Author's profile photo Sissy Haegele
      Sissy Haegele

      You can use the SCIM Connector: https://help.sap.com/viewer/97ae2202f05940a19211f9c5174a971c/8.0/en-US/84015e848b904e1aad1dad4a92887293.html

      Author's profile photo Thomas Jentsch
      Thomas Jentsch

      You can also use SAP Intelligent RPA: SAP RPA 2.0: Use SAP Analytics Cloud REST API with SAP Intelligent RPA – Automations

      Author's profile photo Shailendar Anugu
      Shailendar Anugu

      Hi Matthew,

      Excellent, thank you very much for sharing the scripts and a demo!!

       

      Thanks,

      Shailu.

      Author's profile photo Aleksey Zvyagin
      Aleksey Zvyagin

      Awsome article!

      Author's profile photo Nilesh Salpe
      Nilesh Salpe

      When API used to delete a user from SAC do we need to provide a surrogate user for to be deleted user's resources ? or is there admin as default surrogate user?

      From UI you cannot delete without mentioning the user to which resources will be transferred. Does API enforce the same?

      Author's profile photo Shailendar Anugu
      Shailendar Anugu

      Hi Nilesh Salpe ,

      By default it's Admin as default surrogate user.

       

      Thanks,

      Shailu.

      Author's profile photo Narendra Kumar Nulu
      Narendra Kumar Nulu

      Is there any API for downloading / deleting the Activity logs (Security - Activities). This will be very helpful to cleanup the logs by automating with the help of API.

      Author's profile photo Matthew Shaw
      Matthew Shaw
      Blog Post Author

      Hello Narendra

      There's currently no API for that, but what a great idea. Please submit the idea at https://influence.sap.com/sap/ino/#/campaign/884 or like an existing one. Regards, Matthew

      Author's profile photo Matthew Shaw
      Matthew Shaw
      Blog Post Author

      Ooo! I got a mention: https://blogs.sap.com/2021/07/01/quarterly-code-sample-roundup-summer-edition/  😉

      Author's profile photo Peter Siglreitmeier
      Peter Siglreitmeier

      Matthew Shaw  Many thanks for your awesome blog post. But unfortunately I cannot access the Sample Scripts User guide. I do not have access to the dam.sap. com. Even not as a partner. Perhaps you can set it to public. I struggled setting up the Postman without a guide. Many tanks

      Author's profile photo Matthew Shaw
      Matthew Shaw
      Blog Post Author

      Hi Peter

      The user guide is already a public asset (always has been). Perhaps if you could try with a different browser? Many thanks Matthew

      Author's profile photo Jef Baeyens
      Jef Baeyens

      Absolutely great piece of work and very extensive!
      Thank you Matthew!

      Now that we learned SCIM for User Provisioning, are there perhaps also some examples for the other API's that are listed in SAP Analytics Cloud OAuth Access types like 'Modelling', 'Resource Permissions', etc.? Resource (Folder) permissions would be a nice one to complement SCIM.

       

      Author's profile photo Matthew Shaw
      Matthew Shaw
      Blog Post Author

      Hello Jef,

      Many thanks for your feedback.

      Great minds think alike! I agree! 😉 Which would you vote for first?  Many thanks, Matthew

      Author's profile photo Jef Baeyens
      Jef Baeyens

      I'd vote for the Resource Permissions, such that we can learn how to manage all permissions using API's, for example Team/Folder assignments, Sharing to Teams into the catalog, etc. Today it's too much manual work.
      On second place: Content Network.
      Wondering if that is the way to setup some kind of CI/CD pipeline.

      Author's profile photo Jef Baeyens
      Jef Baeyens

      Also wondering if there is any documentation, examples & support for other endpoints like
      /sap/fpa/services/rest/fpa/dataintegration as described in this blog

      Author's profile photo SAP Security Team
      SAP Security Team

      Hello Mathew ,

      We had a set of Team that were created Manually. ( not using the API). I had tried using the API to delete the Teams. However the API doe not allow teams to be deleted if there were created Manually too. I had created Teams through the API which now has 2 records as shown in picture.

      The issue we are facing is how do we delete 500 teams that were created manually without affecting the Teams that were created from API through postman. as both teams have identical names as show in picture. The Record that was created manually has the user id under "created and "last changed" by attribute tab -.

      Wondering if there is anything in cloud that can toggle

       

      Author's profile photo Matthew Shaw
      Matthew Shaw
      Blog Post Author

      Hello customer,

      Its expected that teams created manually can not be managed via the API.  The User Guide (around page 27) and the presentation cover this in 'Prerequisites for using Teams'.

      So you have to delete those teams via the user interface. I don't think its too much effort, just sort by 'created date' or 'last changed by' making it easier to select the teams you want to delete, and then just press the delete button. Should only take a few minutes.

      For next time, please consider posting your question to the community site. Only the search and question/answer feature doesn't work in blog post comments. It will then help others find the answer without having to look in blog post comments. You can always @tag me in a question. Many thanks 😉

      All the best, Matthew

       

      Author's profile photo Oliver Pellaton
      Oliver Pellaton

      Hi Matthew,

      unfortunately, I do not have access to the User Guide PDF (It looks that you do not have access to the requested resource.).

      Can I get it from somewhere else?

      Best regards.

      Oliver

      Author's profile photo Matthew Shaw
      Matthew Shaw
      Blog Post Author

      Hello Oliver

      Please try again using an incognito window and/or a different browser. That should resolve your problem. Regards Matthew

      Author's profile photo Oliver Pellaton
      Oliver Pellaton

      Hi Matthew,

      also incognito/different browser did not work. I'm asked to loggin via Universal ID, and there I got the message from above.

      Doesn't matter, meanwhile I got another link from the support which works ... 🙂

      Best Regards.

      Oliver

      Author's profile photo Matthew Shaw
      Matthew Shaw
      Blog Post Author

      Hi Oliver

      Many thanks for posting back. I'm pleased you got it to work and I'm sorry you've had problems. I've checked with the support team that support the digital library and somehow I published the wrong URL (a URL that would only work for SAP employees!). We have no clue how I managed to get this link, because it seems impossible to generate it again. So, I've updated the direct download link here, in the wiki and in PPT. Hopefully that will resolve the problem completely! (famous last words!) Sorry again for this.

      All the best Matthew

      Author's profile photo Matthew Shaw
      Matthew Shaw
      Blog Post Author

      I've just published a new 'AdminToolKit' sample to GitHub!

      The AdminToolKit (sample 665) is a very versatile script that creates teams for different types of users (e.g. users without a team)

      Thought I'd share the news here for you to play before I update the documentation next week. But it should be easy enough to use with all the sample data files I've shared:

      Stay tuned for the documentation!

      Matthew