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 API works, behaves and performs
I introduce two new articles:
- Sample Scripts
- 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:
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:
- be easily consumable (simple .csv files or .json files are needed)
- provide very maximum throughput possible (of not only the Analytics Cloud API, but also of Postman)
- 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)
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’:
Transporting user 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.
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 what ever 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.
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:
Errors from the API are handled and automatic re-attempts will be made
This includes errors that are exceptionally rare
And the very maximum performance is provided. They are highly intelligent scripts, for example they will:
- only perform an update if one is actually needed
- determine the ‘net’ change to a team, and only make the necessary changes
- batch requests together so to optimise team updates
- 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.
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:
