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 or on ‘custom’). This is often needed to enable easier integration with other systems, typically access control security rights based on acquired data models from BW.
  • Enables user creation with a different user id compared to the SAML mapping property (userName). For example, creating a user with userid M_SHAW, but with a saml property M-SHAW.
• Automated Administration tasks such as:
  • Updating users’ SAML mapping property (’email’ or ‘custom’). This can also be helpful for a project changing the SAMLSSO mapping from ’email’ to ‘custom’
  • Adding users not in a team, into a team
  • Adding users not in a team or a role, into a team
  • Delete users then delete managers avoiding the problem of not being able to delete a user that is a manager of another user
  • Assigning Managers that currently have a BI concurrent session licence to BI named license
  • Assigning a BI concurrent session license to any user that is disabled avoiding an unnecessarily consumption of a ‘named user’ license
  • Changing the BI concurrent session license for all users, to a named user license. Ideal if you’re moving away from concurrent licenses.
  • Reassign users of given manager to another
  • Swap a directly assigned role for a team role, so adopting best practice
  • Assign the correct settings for recently created users that currently have default settings
• 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 51 sample scripts in Postman (called ‘Collections’ in Postman) that fulfil a whole range of functions related to the Analytics Cloud SCIM API:

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 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 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 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

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 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:

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

Best Practices

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
5. Making manually created SAP Analytics Cloud Teams readable by the SCIM API by Matthew Shaw
6. Sample Scripts Update v0.6 – what’s new by Matthew Shaw
7. Removing Concurrent Session licenses and other updates around managing licenses with roles and teams by Matthew Shaw
8. SAP Analytics Cloud Embedded Edition Best Practices & Sample Scripts for Administration by Matthew Shaw
9. Sample Scripts Update v0.7 – what’s new by Matthew Shaw

Videos referencing this blog post

• SAP HANA Academy – SAP Analytics Cloud Security Playlist

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