Technical Articles
Making manually created SAP Analytics Cloud teams readable by the SCIM API
Why can’t the API read a team that I created manually? Why does the API return a ‘http 404 not found’ error? And how do you resolve this problem?
These are common questions asked by those customers running SAP Analytics Cloud on the ‘Cloud Foundry’ platform (which applies to almost everyone! This issue isn’t applicable for those on ‘NEO’, which is the platform run within SAP Data Centres)
When the SCIM API was first released the API ‘missed’ the requirement that a team, created by any of the following, can’t then be managed by it:
- Manually
- or via the Content Network
- or via the Export/Import mechanism
The API endpoint /api/v1/scim/Groups/TeamID will return a ‘HTTP 404 not found’.
This creates a problem! How do you fix this and allow the API to manage the team?
IMPLEMENT_WORKAROUND_FOR_SCIM_GROUPS
The fix is quite straightforward, simply log a Support Incident with SAP Product Support and ask for the business toggle IMPLEMENT_WORKAROUND_FOR_SCIM_GROUPS to be turned on. Mention SAP KBA 2857395 and the SAP Analytics Cloud Service URL in the incident.
However, doing so, will mean any teams previously created via the API, then can’t be managed via the API. We’re one step forward and one step back! How do you solve this problem?
A little bit of magic!?
As part of my SAP Analytics Cloud SCIM API Sample Scripts, which comprises of over 50 scripts developed in Postman, I’ve just added a new script “654-All_T-Uc-Uur-Oark-Transfer API Hidden Team To API Created Team”.
This sample script (called a Collection in Postman) uses the API to read a team that can’t be managed by the API and copies the users and roles, of that team, and adds them to another team that the API can manage.
How does it perform this magic!? How can a script, using the API, read a team that can’t be read by the API?
The answer isn’t magic. Sorry! Although the API endpoint /api/v1/scim/Groups/TeamID returns a ‘404 not found’, the API endpoint /api/v1/scim/Groups returns all the teams, albeit a page of 200 teams at a time.
What this means is we can still read the users and roles of any team, regardless of whether the other endpoint doesn’t work. It just means we can’t perform a GET, PUT or DELETE to the /api/v1/scim/Groups/TeamID endpoint to read, update or even delete it.
My new sample script uses the /api/v1/scim/Groups endpoint to read the team that can’t be read via /api/v1/scim/Groups/TeamID and simply copies the users and/or roles to another team.
Script in action
Configuring the script is a piece of cake. All you do is edit the sample data file provided with the code. The data file ‘drives’ the script. In this example the data file I used was:
[ { "file_source_team": "HiddenTeam", "file_target_team": "NewTeam", "file_user_action": "add", "file_role_action": "add" } ]
The team that can’t be read, in my example, is called ‘HiddenTeam’ and I had already added 23 users into the team and added the team into 3 roles.
Now, although this blog post is talking about the time when the business toggle IMPLEMENT_WORKAROUND_FOR_SCIM_GROUPS is turned on, the script will also read a team that was manually created but still the IMPLEMENT_WORKAROUND_FOR_SCIM_GROUPS is off.
In other words
- When business toggle IMPLEMENT_WORKAROUND_FOR_SCIM_GROUPS=off the hidden teams are manually created teams
- When business toggle IMPLEMENT_WORKAROUND_FOR_SCIM_GROUPS=on the hidden teams are teams previously created via the API
Either way, I have a team that is ‘hidden’ and this script will work for both cases.
The Postman console log shows what the script is doing:
Step 1: It first attempts to read the team (that can’t be read!)
The 404 is shown and so the script knows this team can’t be read by the endpoint /api/v1/scim/Groups/HiddenTeam
Step 2: Reads the target team (and creates it if it doesn’t already exist):
When reading the target team, in this case, the script also receives a ‘404 not found’, but as this is the target team and the team doesn’t already exist, it creates a new one. If the target team already existed (and can be managed by the API) then it would recognise it and add the users into it, rather than creating another.
Step 3: The script then reads all the teams registered in SAP Analytics Cloud (using the /api/v1/scim/Groups endpoint) in pages of 200 at a time until it finds the ‘hidden’ team that it’s looking for:
Once it finds the team it reads all the users and roles of that team, ready for the final step.
Step 4: Update target team:
Finally, the target team is updated, first by adding the team into roles, then by adding the users.
The result is two teams, in this case one called ‘HiddenTeam’ and another ‘NewTeam’, both with the same number of users and roles. The script copied the users and roles from HiddenTeam to NewTeam. So, the script doesn’t solve the problem, but it certainly helps reduce the amount of re-work.
Although access right permissions on folders/objects in the file repository and elsewhere are NOT currently updated, as part of this script, it has saved you the effort of creating a new team and transferring all the users and roles into it. This means all you need to do is worry about is updating the access rights where the source team (HiddenTeam in my example) is used and add the new team (NewTeam in my example) as another entry. Then when you’ve finished, you’ll be safe to delete HiddenTeam . If you think you might have missed an access right somewhere, empty the HiddenTeam first and wait to see if you get any complaints!
Where to start?
You’ll find step-by-step instructions on how to install and run my sample scripts via the main blog post I mentioned earlier. Download the user guide and follow the instructions. There are about 40 steps, most are a single mouse click! It shouldn’t take a complete novice much more than 40 minutes to complete this task.
Its good to know, that once a team has been created by the API, then you can continue to manage that team both via the API as well as manually via the standard user interface of SAP Analytics Cloud. The problem is only related to the creation of the team. In fact, the problem is related to the ‘namespace’ of the team and the namespace of any object can’t be edited after it’s been created.
My user guide provides comprehensive instructions and further details on how to download, install, run, and configure the scripts as well as more details on how the script works. Please take care to read the guide carefully.
Other things I need to know about IMPLEMENT_WORKAROUND_FOR_SCIM_GROUPS?
Before requesting Product Support to enable this toggle for you, please also consider setting the ‘Content namespace’ to be the same and consistent value. Once this toggle is enabled/on you’ll no longer be able to change the ‘Content namespace’. Its not essential the namespace is the same across your landscape, but there are a few benefits. For more details, please refer to this blog that introduces this topic and in particular this section in the related article.
Feedback
Please comment if you use these resources in anyway (or if you’re shy, just hit the like button!)
Please do provide feedback, but please only post comments here that related directly to this topic. Kindly keep all other ‘Sample Script’ comments in the main blog post so others can find them in one location rather than multiple. Please take time to read the User Guide carefully! It is very detailed and could well answer your question.
Many thanks
Matthew Shaw @MattShaw_on_BI
https://people.sap.com/matthew.shaw/#content:blogposts
Thanks Matthew,
For the interested reader who, like some of us, finds reading documentation a little challenging, here is a link to the video tutorial series covering the concepts of the SCIM API in easily digestible episodes and which may serve as a warming up exercise to the script mentioned in this blog post.
Your videos are wonderful Denys, they really help explain how the sample scripts work in practice. I thoroughly recommend them to anyone new to the API or these sample scripts.
Next round is on me, Matthew. 😉
Thank you, Matthew Shaw for detailed explanation. Have a question on this topic. We've recently migrated from one external IdP to another (ADFS to AAD specifically).
Since the switch to new IdP, groups created by SCIM API at the time old IdP was used are no longer readable by SCIM API (error 404). I was wondering if you heard of this issue before? It seems like the list of scenarios you quoted when describing conditions where the problem occurs, can to be extended with
Has this been raised by other customers? Are you aware of any plans by SAP to provide a long-term fix, so that all groups can be managed by SCIM API irrespective of how they were originally created?
Thank you!
Hello Mikhail,
Many thanks for your feedback.
When using an IdP to provision users and/or teams it will be using the SCIM API. Thus, any team it happens to create, will be an API created team. However, I very much doubt your previous IdP actually created the team. In almost all cases, the team is manually created before the IdP configuration is performed.
Hope this helps!?
Kind regards, Matthew
Thank you for quick response, let me clarify - I think my original description is confusing.
We've created groups via SCIM API while IdP1 was configured. Once we removed IdP1 and moved to IdP2, groups created while IdP1 was configured are no longer accessible via SCIM API. So yes, IDP did not create the groups, they were created via SCIM API.
Hope this clarifies the problem we're having.
Mikhail
Hello Mikhail,
Ok, so regardless of what 'client' (IdP is this case) is using the SCIM API, then it will be readable by it. However your current thinking is not the case. This isn't expected and I think something has changed.
Either the SAC namespace and/or the IMPLEMENT_WORKAROUND_FOR_SCIM_GROUPS has been enabled that is now preventing the SCIM API from reading the team (group in SCIM language).
Or you have enabled this new setting Ignore Content Namespace For Teams and you have 2 teams of the same name (but this isn't applicable for your case because this setting is a new one and you've not yet have the chance to use it!)
Sorry, I can't identify the source of the issue for you. Still, I hope this script (or this new setting) resolves your problem. Let us know
Many thanks, Matthew
Thank you - setting Ignore Content Namespace For Teams actually has resolved the issue!
I wish SAP KBA 2857395 included reference to the setting, it would've helped us to resolve this much quicker.
Thanks again,
Mikhail
Hello Mikhail,
Sorry I forgot to answer this question:
Q
Are you aware of any plans by SAP to provide a long-term fix, so that all groups can be managed by SCIM API irrespective of how they were originally created?
A
The next version of the SAP Analytics Cloud SCIM API (version 2) will resolve this problem. The current version of the SAP Analytics Cloud SCIM API is already SCIM v2 complaint.
I also need to update my blog article and user guide as a new administration configuration setting (menu-administration-system configuration) has just been made available called "Ignore Content Namespace For Teams". Just enable this and it will mean the SAC SCIM v1 API will ignore the team namespace, meaning that regardless of how the team was created, it will be readable via the SAC SCIM v1 API.
Stay tuned for an update to this blog and user guide for more details, but in short the only known downside is when you have 2 teams of the same name (but different namespace). With this setting enabled, the SAC SCIM v1 API will return a 404 in the case when you have 2 teams of the same name (just different namespace). The advantage of this setting is you can still change the namespace of your SAC service and, of course, you can perform the setting change yourself without the need to log an incident with SAP Product Support.
All the best
Matthew
Thank you, definitely looking forward to these enhancements!
Hi Matthew,
I might be missing something, but is there an API which will import security settings into the read and write properties of secured dimensions?
If not is it something that is planned?
Without this it seems to me that the API's are doing half of the job on managing security.
Regards,
Mark