Category
Data Transformation
Product Version
9.0
API flow for automating Client Orgs, User Groups, Roles, and Content Permissions
Answered
Hi Yellowfin team,
We’re in the process of integrating Yellowfin into our own application, and we need clarity on the correct API flow + endpoints for a few key automation tasks. I want to make sure we’re aligning with best practices before building it all out.
Here’s what I'm aiming to do, step by step:
1. Client Org creation
- When a new customer is created in our app, we want to automatically create a Client Organization for them in Yellowfin.
- Currently working on /api/orgs for v9.13+.
- Each org should have a clientReferenceId matching our internal Customer ID.
2. Super users across orgs
- We have a few “super users” (global admins in our app) that should always exist in all Client Orgs in Yellowfin.
- Question: is the correct API to add them /api/admin/client-orgs/{uuid}/memberships with roleCode = SYSTEM_ADMINISTRATOR?
3. Automating user groups (roles & depts)
- In our app, every user belongs to a role and group (department).
- We want to replicate these as User Groups in Yellowfin inside each Client Org.
- Plan: use /api/admin/user-groups to create user groups, then assign users to them via /api/admin/users (with group membership).
4. CRUD Users with role + group assignment
- Whenever a user is created/edited/deleted in our app, we want this reflected in Yellowfin.
- Tentative API flow: Create: POST /api/admin/users with role + group IDs. Update: PUT /api/admin/users/{id} for changes to email/name/role/group. Delete: DELETE /api/admin/users/{id}.
- Question: is role editing done purely through roleCode on the user, or do we also need a membership update?
5. Import dashboards/reports into each org
- We’re building all of our dashboards, views, and reports in the default Client Org of the instance.
- For each new client org, we’ll need to import this content (dashboards + reports).
- Question: which API should we use to copy/export/import content from the default org into a client org? Is this handled by /api/admin/content/export-import?
6. Restricting content by use case (via folders)
- Our app has ~7 different use cases, and each user group only has access to certain ones.
- Plan: Put dashboards/reports into Content Folders, one per use case. Control access via folder-level permissions.
- Question: is this the correct approach- create folders per use case and then use group-to-folder permissions via the API?
The big picture flow we’re targeting
- Customer created in our app → Create Client Org in YF.
- Add global super users to that org.
- Create user groups in the org (based on our app’s roles/groups).
- Create users in the org and assign them to groups + roles.
- Import default dashboards/reports into the org.
- Assign content folder permissions to groups, so users see only what they should.
Ask: Could someone confirm the correct sequence of API calls and endpoints for this potential flow? Especially:
- Which endpoint to use for client org creation
- The right APIs for creating/assigning user groups and roles.
- Best practice for importing content from the default org into client orgs.
- How to handle folder-level security for user groups.
- Any other useful details for the calls to incorporate in the set up
Thanks in advance- I know this is a lot, but I think this is a very common integration scenario and getting the flow right upfront will save a ton of rework.
The same question
Hi Brian,
Thanks for contacting Yellowfin with your questions and I hope you're doing well.
I've taken a stab already at answering your client org question in your other ticket, so do let me know over there if you were successful with that.
For your other questions, I'll go through them and hope to give you an answer shortly.
Kind regards,
Chris
Hi Brian,
Thanks for contacting Yellowfin with your questions and I hope you're doing well.
I've taken a stab already at answering your client org question in your other ticket, so do let me know over there if you were successful with that.
For your other questions, I'll go through them and hope to give you an answer shortly.
Kind regards,
Chris
Hi Brian,
I hope you're doing well.
In answer to your questions:
Question: is the correct API to add them /api/admin/client-orgs/{uuid}/memberships with roleCode = SYSTEM_ADMINISTRATOR?
- You'll want to add these to the default org, with ID 1. If you want to grant them full access, SYSTEM_ADMINISTRATOR is fine. You could also set up a new super user role, that's similar to SYSTEM_ADMINISTRATOR but with a few less permissions, if that's more appropriate.
Question: is role editing done purely through roleCode on the user, or do we also need a membership update?
- PATCH is the correct verb to use to update a user. For roleCode vs. group membership, that depends on how you have organised your user administration. Groups allow for a more organised setup where every user that is part of a group can be included with a role membership. But you can also have users assigned to roles separately from a group. So if you are using groups, add a user to a group and they'll get all the privileges of that group's role assigned to them.
Question: which API should we use to copy/export/import content from the default org into a client org? Is this handled by /api/admin/content/export-import?
- Content created in the default org is already accessible by client orgs. If you do want to move specific content between orgs, you can use api/rpc/import-export/export-content
See here for more: https://developers.yellowfinbi.com/dev/api-docs/current/#tag/import-export
Question: is this the correct approach- create folders per use case and then use group-to-folder permissions via the API?
- Yes that's correct. You can also divide up content between 'use cases' if these qualify as separate orgs, so content created in one org is separate from all the other orgs. The only exception is that content created in the default org is accessible to all, as previously mentioned.
Have a look at our developer documentation for the REST API. If you like, I can ask your account manager to look at setting up a session with one of our consulting partners to get you some tailored assistance for your API use. Support can handle situations where things go wrong or answer general questions, but assistance with specific workflows and best practice are best handled by an integration expert.
Kind regards,
Chris
Hi Brian,
I hope you're doing well.
In answer to your questions:
Question: is the correct API to add them /api/admin/client-orgs/{uuid}/memberships with roleCode = SYSTEM_ADMINISTRATOR?
- You'll want to add these to the default org, with ID 1. If you want to grant them full access, SYSTEM_ADMINISTRATOR is fine. You could also set up a new super user role, that's similar to SYSTEM_ADMINISTRATOR but with a few less permissions, if that's more appropriate.
Question: is role editing done purely through roleCode on the user, or do we also need a membership update?
- PATCH is the correct verb to use to update a user. For roleCode vs. group membership, that depends on how you have organised your user administration. Groups allow for a more organised setup where every user that is part of a group can be included with a role membership. But you can also have users assigned to roles separately from a group. So if you are using groups, add a user to a group and they'll get all the privileges of that group's role assigned to them.
Question: which API should we use to copy/export/import content from the default org into a client org? Is this handled by /api/admin/content/export-import?
- Content created in the default org is already accessible by client orgs. If you do want to move specific content between orgs, you can use api/rpc/import-export/export-content
See here for more: https://developers.yellowfinbi.com/dev/api-docs/current/#tag/import-export
Question: is this the correct approach- create folders per use case and then use group-to-folder permissions via the API?
- Yes that's correct. You can also divide up content between 'use cases' if these qualify as separate orgs, so content created in one org is separate from all the other orgs. The only exception is that content created in the default org is accessible to all, as previously mentioned.
Have a look at our developer documentation for the REST API. If you like, I can ask your account manager to look at setting up a session with one of our consulting partners to get you some tailored assistance for your API use. Support can handle situations where things go wrong or answer general questions, but assistance with specific workflows and best practice are best handled by an integration expert.
Kind regards,
Chris
This is extremely helpful, thank you!
This is extremely helpful, thank you!
Hi Brian,
No worries. Let me know if you have any other questions on this topic.
Kind regards,
Chris
Hi Brian,
No worries. Let me know if you have any other questions on this topic.
Kind regards,
Chris
Hi Brian V,
Hope you're having a good week.
Just wanted to check-in and see how it's all going. Are there any other questions on this one you'd like some assistance with? Let me know, otherwise I think we can mark this one as answered!
Kind regards,
Chris
Hi Brian V,
Hope you're having a good week.
Just wanted to check-in and see how it's all going. Are there any other questions on this one you'd like some assistance with? Let me know, otherwise I think we can mark this one as answered!
Kind regards,
Chris
Hi Brian V,
I hope things are going well with you.
Just wanted to let you know I'll be closing this request due to inactivity. However, if you ever wanted to re-visit this or have anything else I can help you with, please let me know.
Kind regards,
Chris
Hi Brian V,
I hope things are going well with you.
Just wanted to let you know I'll be closing this request due to inactivity. However, if you ever wanted to re-visit this or have anything else I can help you with, please let me know.
Kind regards,
Chris
Replies have been locked on this page!