My SAP Analytics Cloud User and Team Provisioning SCIM API Sample Scripts recently received an update to version 0.6. This blog post is for those that already use the samples and would like to understand what's new and a few tips on how to update to this version from 0.5.
If you're new to the samples, then there's no need to read this as the main introductory blog post and the user guide have already been updated. The 'Sample Scripts Presentation' will soon be updated. It means everything is in one place for you, rather than having to read lots of different blog posts. Nevertheless you might find it interesting.
Here's a little more details on each of the above (except the Transferring a Hidden team, as that's detailed in the blog post mentioned above):
Before this update you had to edit the scripts to ensure the 'userName' property had the correct value. You don't need to do this anymore. All you need to do is define a Postman environment called 'SAMLSSO' and set its value to:
It's as simple as that!
And it even works for the 9xx transport samples, only the variable is called 'Source-SAMLSSO' and 'Target-SAMLSSO'.
The 9xx transport samples will even transport between SAP Analytics Cloud services using different authentication and SAML SSO setups!
To 'update' your existing environments, all you need to do is run the updated samples 001 (and 011 if applicable) and the new environment variable will be added for you, setting its value to 'default' (by default! ). You can then change it if you need to and you don't need to worry about making any code changes any more just because your using SAML SSO.
You no longer need to use the 1xx, or 2xx samples to update the role a user has directly assigned to them. You can now use a single sample script to update just that aspect.
408 is 'by user' and 458 is 'by user, but updates a whole team of users at a time'
They both have the usual 'add', 'remove' and 'replace' actions. As like the other sample actions, a 'replace' action with an empty array [] will remove all roles from the user, even when you don't know what roles they currently have. (i.e. works in the same way that 403 will remove all teams from a user, when you don't necessarily know which teams the user is a member of)
If you are using your own custom Identity Provider and configured SAML SSO, then these samples are handy to update the user property, called userName, that is the thing you're mapping the user on. Both samples, 409 and 429, will update both the email or the 'custom' (external id) for the user, whichever you're using. (remember the samples are now SAML SSO aware, so they will make sure the update is right for which ever SAML SSO mapping you're using)
Sample 409 is when you want to identify and update the user by the 'SAC userid'. An example data file when using 'custom':
and you can update the email, still identifying the user by the 'SAC userid':
Sample 429 is when you identify and update the user by their 'email' and so the sample data files now have email as the 'id' allowing you to update the 'custom':
and updating the email (identified by the old email!):
The sample script creates teams and adds users into the team that meet a certain criteria. It scans all the users that are defined in SAP Analytics Cloud enabling each user to be checked against the criteria.
For those users that match the criteria, the user is added or removed. It means you can easily identify certain users, by adding them to a team, to then update or process them by another sample script!
In turn, it should help resolve issues with your users' configuration and I suspect it will become a script of choice for many administrators.
There are some 18 different types of ‘tests’ and include things like:
The script enables both ‘and’ and ‘or’ operators between the different tests allowing for complex logic, such as ‘users not in a team AND created in the last week’.
And because the target is a team, we have the usual 'actions', like with the other 'team-on-team' samples. But because we're scanning all the users registered we have a few more!:
Actions include ‘replace’, which removes all users not fulfilling the defined test (just like the other samples), and ‘invert’ that is simply the opposite of the matching users. This 'invert' is only possible because we're scanning all the registered users.
You really need to see the details of what all the 'tests' are but to cut to the chase, these are the types of teams that can be created (the sample data files provided creates these and a few more):
It might be this script fulfils your need entirely, like 'Users without a team' or 'Users without a role'. But the power of this AdminToolKit is further demonstrated by 'Scenarios' which is explained below.
I hopefully thought of everything and tried my best to keep the script as versatile as possible. It includes a few extra's bits to polish things off:
To get going, just use the sample data files provided, and search and replace the following in all the data files:
Additionally:
The AdminToolKit enables a great deal of additional use-cases because it creates teams of users that help other sample scripts process users. To save you the time and effort, I've preconfigured a bunch of sample data files so you can start to understand the power of the 'Admin Tool Kit'.
All you need to do is tweak the data files for your own needs, such as the team names, roles names, manager ids. You'll find these data files in a new folder called 'Example data files\Scenarios'.
Each scenario just consists of sample data files, that if ran in the given order, will fulfil the task at-hand. They are documented in the User Guide with suggestions to further tailor them to suit your needs.
I can imagine other scenarios will be added over time and please do make suggestions here.
Its easy-peasy!
You should have changed the code on the scripts that create users (1xx and 2xx), to only define the correct date/time/number formations and language. You'll still need to re-apply these changes to the latest version. So consider creating a new Postman workspace and importing the new samples into the new workspace allowing you to then copy the lines of code you made from your old workspace. The changes you made, should be very simple and easy to copy/paste!
If you made code changes because you have SAML SSO enabled, then you can ignore any changes you made, you'll not need to make them again. The scripts are now SAML SSO aware.
Once you imported all the new sample scripts into your new Postman workspace:
Don't forget to download a fresh copy of all the sample data files. Many more have been added.
A few extra bits and bobs:
Many thanks
Matthew Shaw @MattShaw_on_BI
matthew.shaw/#content:blogposts
If you're new to the samples, then there's no need to read this as the main introductory blog post and the user guide have already been updated. The 'Sample Scripts Presentation' will soon be updated. It means everything is in one place for you, rather than having to read lots of different blog posts. Nevertheless you might find it interesting.
Summary of what's new:
- All sample scripts are now SAML SSO 'aware'. It means you no longer need to edit any scripts if you're using SAML SSO thanks to my code making use of a new Postman environment variable called 'SAMLSSO'. Set this to 'default', 'userid', 'email' or 'custom' as appropriate.
- New sample scripts 408 and 458 that update the users' direct Role assignment
- 408 is 'by user' and 458 is 'by user, but updates a whole team of users at a time'
- And they have the usual 'add', 'remove' and 'replace' actions.
- New sample scripts 409 and 429 that updates the 'userName' property of a user (which is their SAML mapping😞
- This is handy when using 'custom' or 'email' SAML SSO
- sample 409 is when you want to identify and update the user by the 'SAC userid'
- sample 429 is when you identify and update the user by their 'email'.
- New sample script '654-All_T-Uc-Uur-Oark-Transfer API Hidden Team To API Created Team'.
- This reads a team, that can't be managed by the API, and transfers users+roles to a team that can be managed by the API. Handy when you've created teams manually, or, you've previously created teams via the API and then enabled IMPLEMENT_WORKAROUND_FOR_SCIM_GROUPS. This blog about making manually created teams readable by the API has the next level of detail.
- New sample script 665-All_U-Uc-Uu-Oarrieei-Fj-Es-AdminToolKit
- A very versatile script that creates teams and adds users into the team that meet certain criteria. It scans all the users that are defined in SAP Analytics Cloud enabling all users to be checked against the criteria. For those users that match the criteria, then the user is added or removed. It means you can easily identify certain users, by adding them to a team, to then update or process them by another sample script! In turn, then enables further use-cases which are then elaborated in 'Scenarios' (see next!)
- The most common use-case it supports is to add users into a team, that aren't already in a team, but there are plenty of others! (explained below)
- Scenarios
- Scenarios is a very simple concept which comprises of nothing more than sets of pre-configured sample data files. Each scenario addresses a single use-case by combining different sample scripts together in a particular order.
- It means most of the thinking has been done for you. All you need to do is tweak the data files for your own needs, such as the team names, roles names, manager ids etc.
The scenarios provided are:
- D01 - Delete users then delete managers
- L01 - Managers with BIconcurrent to BInamed license
- L02 - Disabled users to BIconcurrent license
- L03 - Convert all BIconcurrent to BInamed license
- M01 - Reassign users of given manager to another
- R01- Swap directly assigned role for a team role
- S01 - Assign settings for recently created with default settings
- S02 - Assign settings concurrent lic for recently created w default settings
- T01 - Transport Managers then Users
Here's a little more details on each of the above (except the Transferring a Hidden team, as that's detailed in the blog post mentioned above):
SAML SSO 'aware'
Before this update you had to edit the scripts to ensure the 'userName' property had the correct value. You don't need to do this anymore. All you need to do is define a Postman environment called 'SAMLSSO' and set its value to:
- 'default', if you're using the default authentication method that comes with SAP Analytics Cloud
- 'userid', 'email', or 'custom' is your using your own Identity Provider and configured SAML SSO. Set the value to whichever property you're mapping on.
It's as simple as that!
And it even works for the 9xx transport samples, only the variable is called 'Source-SAMLSSO' and 'Target-SAMLSSO'.
The 9xx transport samples will even transport between SAP Analytics Cloud services using different authentication and SAML SSO setups!
To 'update' your existing environments, all you need to do is run the updated samples 001 (and 011 if applicable) and the new environment variable will be added for you, setting its value to 'default' (by default! ). You can then change it if you need to and you don't need to worry about making any code changes any more just because your using SAML SSO.
Direct Role assignment
You no longer need to use the 1xx, or 2xx samples to update the role a user has directly assigned to them. You can now use a single sample script to update just that aspect.
408 is 'by user' and 458 is 'by user, but updates a whole team of users at a time'
They both have the usual 'add', 'remove' and 'replace' actions. As like the other sample actions, a 'replace' action with an empty array [] will remove all roles from the user, even when you don't know what roles they currently have. (i.e. works in the same way that 403 will remove all teams from a user, when you don't necessarily know which teams the user is a member of)
SAML Mapping
If you are using your own custom Identity Provider and configured SAML SSO, then these samples are handy to update the user property, called userName, that is the thing you're mapping the user on. Both samples, 409 and 429, will update both the email or the 'custom' (external id) for the user, whichever you're using. (remember the samples are now SAML SSO aware, so they will make sure the update is right for which ever SAML SSO mapping you're using)
Sample 409 is when you want to identify and update the user by the 'SAC userid'. An example data file when using 'custom':
file_userid,file_samlmapping
MSHAW,MATTHEWSHAWand you can update the email, still identifying the user by the 'SAC userid':
file_userid,file_samlmapping
MSHAW,matthew.new.email@sap.comSample 429 is when you identify and update the user by their 'email' and so the sample data files now have email as the 'id' allowing you to update the 'custom':
file_email,file_samlmapping
matthew@sap.com,MATTHEWSHAWand updating the email (identified by the old email!):
file_email,file_samlmapping
matthew@sap.com,matthew.new.email@sap.comAdminToolKit
The sample script creates teams and adds users into the team that meet a certain criteria. It scans all the users that are defined in SAP Analytics Cloud enabling each user to be checked against the criteria.
For those users that match the criteria, the user is added or removed. It means you can easily identify certain users, by adding them to a team, to then update or process them by another sample script!
In turn, it should help resolve issues with your users' configuration and I suspect it will become a script of choice for many administrators.
There are some 18 different types of ‘tests’ and include things like:
- Users with Business Intelligence license
- Users that are managers
- Users without a role
- Users without a team
- Users with an email domain @Sap.com
- Etc. etc.
The script enables both ‘and’ and ‘or’ operators between the different tests allowing for complex logic, such as ‘users not in a team AND created in the last week’.
And because the target is a team, we have the usual 'actions', like with the other 'team-on-team' samples. But because we're scanning all the users registered we have a few more!:
Additional actions when scanning all users
Actions include ‘replace’, which removes all users not fulfilling the defined test (just like the other samples), and ‘invert’ that is simply the opposite of the matching users. This 'invert' is only possible because we're scanning all the registered users.
You really need to see the details of what all the 'tests' are but to cut to the chase, these are the types of teams that can be created (the sample data files provided creates these and a few more):
- AdminToolKit_All_Users
- AdminToolKit_Users_Created_Recently
- AdminToolKit_Users_With_BI_Concurrent_License
- AdminToolKit_Users_With_BI_Named_User_License
- AdminToolKit_Users_With_A_Manager.
- AdminToolKit_Users_With_Manager_MANAGERID
- AdminToolKit_Users_Without_A_Manager
- AdminToolKit_Users_That_Are_Managers
- AdminToolKit_Users_That_Are_Enabled
- AdminToolKit_Users_That_Are_Disabled
- AdminToolKit_Users_With_UserID_Ending__1
- AdminToolKit_Users_With_SAP_email
- AdminToolKit_Users_Without_SAP_email
- AdminToolKit_Users_Without_a_Role_and_Without_a_Team
- AdminToolKit_Users_Without_a_Team
- AdminToolKit_Users_Without_a_Role
- AdminToolKit_Users_With_Directly_Assigned_BIAdmin_Role
- AdminToolKit_Users_With_Default_Settings
- AdminToolKit_Users_Created_Over_A_Year_Ago
- AdminToolKit_Users_That_Are_Managers_With_BI_Concurrent_License
- AdminToolKit_Users_That_Are_Disabled_With_BI_Named_User_License
- AdminToolKit_Users_In_Managment_Structure
- AdminToolKit_Users_Not_In_Managment_Structure
- AdminToolKit_Users_Without_Default_Settings
It might be this script fulfils your need entirely, like 'Users without a team' or 'Users without a role'. But the power of this AdminToolKit is further demonstrated by 'Scenarios' which is explained below.
I hopefully thought of everything and tried my best to keep the script as versatile as possible. It includes a few extra's bits to polish things off:
- It has an 'exclude an array of users': this enables you to exclude some users from all the 'scans' such as the 'SAP_SUPPORT' user. You're most likely need to exclude this user from almost all your teams.
- Because the nature of the teams it creates, is a 'moment in time', the team membership may need to change overtime. So its important any user of SAP Analytics Cloud understands the teams are not 'dynamic', they do require the script to run for it to be corrected. To help with this, I enabled the 'display name' of the team to be updated and if it contains the word 'TIMESTAMP' then TIMESTAMP is replaced by the current date and time. I even made this timestamp time zone aware. It uses 3 environment variables: TimeZoneHours, TimeZoneMinutes and TimeZoneDescription. If you run the updated sample script 001, it will create these variables for you allowing you to easily update them as you see fit.
- The script creates teams, but of course one of the tests is for 'users not in any teams'. So there are additional 'exclude' lists to exclude either a given team name, or teams that start with a particular name. You'll find all my sample data files create teams that start with 'AdminToolKit' and they also include this text in the 'teams to ignore' list! The same applies for Roles.
To get going, just use the sample data files provided, and search and replace the following in all the data files:
- Replace SAP_SUPPORTXXXXXXXXX with the SAP SUPPORT User in your service
- Replace sap.com with your organisation email domain name
Additionally:
- Change the 'file_team' name for sample data files that have the word 'SAP' in them to match your organisation name, unless you work for SAP!
Scenarios
The AdminToolKit enables a great deal of additional use-cases because it creates teams of users that help other sample scripts process users. To save you the time and effort, I've preconfigured a bunch of sample data files so you can start to understand the power of the 'Admin Tool Kit'.
All you need to do is tweak the data files for your own needs, such as the team names, roles names, manager ids. You'll find these data files in a new folder called 'Example data files\Scenarios'.
| Scenario | Description / use-case |
| D01 - Delete users then delete managers | Given a team of users to be deleted, it will delete the users first before then deleting the managers so to avoid the problem of not being able to delete a user that is a manager of another user |
| L01 - Managers with BIconcurrent to BInamed license | Identifies which users have a ‘Business Intelligence’ concurrent session license AND that are also managers. It then updates their license type to ‘named user’ ensuring all managers are always able to login and don’t need to wait for a spare concurrent session to be available |
| L02 - Disabled users to BIconcurrent license | Identifies all disabled users (with a BI named license) and sets their ‘Business Intelligence’ license to ‘concurrent session’ avoiding an unnecessarily consumption of a ‘named user’ license that could be allocated to someone else |
| L03 - Convert all BIconcurrent to BInamed license | Updates all users that have a Business Intelligence ‘concurrent session’ license to a Business Intelligence ‘named user’ license. Ideal if your SAP Analytics Cloud Service is to be, or has been, migrated from NEO to CF when the CF instance has no concurrent licenses. Can be used as an alterative workaround prior to a contract change where concurrent licenses are removed from the SAP Analytics Cloud Service that occurs when a change of contract is effective. Without a workaround the concurrent session license remains enforced. An alterative workaround is after the licenses have been removed as described in KBA 3126413. |
| M01 - Reassign users of given manager to another | Re-assigns all users of the given manager(s) to another manager which is helpful when the manager is unavailable or needs to be deleted. |
| R01- Swap directly assigned role for a team role | Re-assigns all users which have the ‘BI_Admin’ role directly assigned to them, adds these users into a team, adds the team to be a member of the ‘BI_Admin’ role before then removing the directly assigned role from all the users. This enables you to adopt the best practice for assigning roles to users, which is with the help of inheritance and teams |
| S01 - Assign settings for recently created with default settings | Assigns the right date/time/number and language settings for those users created in last week with the default settings. It means your users will then be set correctly avoiding each user to update their own settings which is an unnecessary task |
| S02 - Assign settings concurrent lic for recently created w default settings | Same as S01, only it also assigns the user with a ‘Business Intelligence’ ‘concurrent session’ license. |
| T01 - Transport Managers then Users | Given a team of users to be transported, it transports the managers first, and then all the users avoiding the problem that you can’t create a user with a manager, if the manager doesn’t already exist |
Each scenario just consists of sample data files, that if ran in the given order, will fulfil the task at-hand. They are documented in the User Guide with suggestions to further tailor them to suit your needs.
I can imagine other scenarios will be added over time and please do make suggestions here.
How to update to version 0.6
Its easy-peasy!
You should have changed the code on the scripts that create users (1xx and 2xx), to only define the correct date/time/number formations and language. You'll still need to re-apply these changes to the latest version. So consider creating a new Postman workspace and importing the new samples into the new workspace allowing you to then copy the lines of code you made from your old workspace. The changes you made, should be very simple and easy to copy/paste!
If you made code changes because you have SAML SSO enabled, then you can ignore any changes you made, you'll not need to make them again. The scripts are now SAML SSO aware.
Once you imported all the new sample scripts into your new Postman workspace:
- Go back to your original workspace, duplicate your Postman 'Environments' to then 'Move' the duplicated one to your new workspace. It will just save you having to define the environments again:
- Then make the copy/paste the code changes you made from your old workspace to your new one (remember ignore any SAML SSO changes)
- Run the new sample script 001 (and 011 if applicable). This will add new environment variables:
- SAMLSSO (and it will be set to 'default'. If you've enabled SAML SSO set it to 'userid', 'email', or 'custom')
- TimeZoneHours, TimeZoneMinutes and TimeZoneDescription. Update these as you see fit. Hours and Minutes needs to be a number, -23 to 23, and -30, 0 or 30 respectively. Set the description to be whatever suits 'GMT' 'CET' 'CTT' 'IST' 'PST' etc.
Don't forget to download a fresh copy of all the sample data files. Many more have been added.
A few extra bits and bobs:
- a few of the samples changed their name very slightly (all sample script 'IDs', the number part remain unchanged)
- I fixed a few bugs in the 9xx samples
- If you downloaded an early copy of the '665 Admin Tool Kit' (when it didn't have any documentation) please delete it and the sample data files, since the data file syntax is now different.
Feedback
- Feedback is very welcome.
- I'd love to hear if you like the new updates
- However, in general, please only comment on the main blog post so others can find it all in one place.
Many thanks
Matthew Shaw @MattShaw_on_BI
matthew.shaw/#content:blogposts
- SAP Managed Tags:
