Automatic Creation of User Groups
Developers can now streamline creating and updating solution level user groups using the solution service-level manifest file. This manifest file allows developers to define the user groups with corresponding role mappings. The solution service in turn will create the user groups in AAA based on the uploaded manifest file. Once a customer subscribes to a solution, the user groups defined in the manifest are automatically created within the tenant with the mapped roles assigned. After subscription, developers can update the user groups and role mappings by uploading a new manifest file, which in turn will be used by the solution service to update the AAA user groups.
This capability allows developers to configure the necessary user groups and permissions for their solution while having the flexibility to modify as needed by updating the central manifest file.
Additionally, we introduced schema validation in the UploadArtifact API for App and Solution manifest file types so developers can catch any potential schema level issues while uploading the YAML files.
- Create a manifest file: Define user groups and role mappings in a YAML manifest file for a solution. Please refer here for a sample solution level manifest file.
- Onboard to tenants: Use the Onboarding API to onboard the solution. When a customer subscribes the solution service will create user groups with role mappings in AAA. There is also
Create a solution-level manifest file in YAML format that includes user groups and their corresponding roles.
The following example manifest provides a pre-defined set of user groups for both administrators and business users. It also maps the relevant application roles to each group. Additionally, when a solution is subscribed, it automatically assigns the "Solutions-Admin" group to the tenant administrator.
The manifest file does the following:
- Defines the solution ID as "gated-solution"
- Two user groups are defined in userGroupsRequired section:
- Solutions-Owner group with two roles
- Dispatch-get-orders
- Dispatch-view-orders
- The Field-Executive group with four roles
- dispatch-list-routes
- dispatch-view-routes
- dispatch-get-users
- dispatch-view-users
- The adminUserGroups lists the "Solutions-Admin" group that will be assigned to the tenant admin users for this solution during subscription or onboarding.
Please note that if an app developer includes an existing user group (a group that already exists in a solution manifest) within their App manifest /permissions file, then the developer can only assign new roles to the existing group but will not be able to remove the roles added to such a user group. The vice versa is also true i.e. roles defined by the App manifest file cannot be removed from the solution manifest by the solution developers.
Also, in such cases, the resultant user group will be a union of user groups (and roles assigned) in the solution manifest and user groups (and roles assigned) in the app manifest.
Use the UploadArtifact API to upload your manifest file to the registered solution. By default, the user groups from manifest are created during tenant subscription to the solution.
If you want to create user groups at solution onboarding, you need to specify it using the forceCreateUserGroup parameter in Onboarding API request.
- File: The manifest file to be uploaded. In Postman, select File from the Key dropdown menu to upload your file.
- artifactType: Set the artifactType to MANIFEST
- solutionVersionID: Include the versionId of the solution to upload the file to.
Example:
On success, the response provides the fileID and the URL where the artifact has been uploaded.
Please note that only the Solution owner/s will be able to update their solution-level manifest file, the same is true for app-level manifest as well (only the app developers will be able to update).
Proceed to use the Onboarding API to onboard the solution to the desired tenants. Upon initial subscription, the solution service will automatically create or update user groups in AAA based on the uploaded manifest. Whenever the manifest file is updated and onboarded, the user groups will be updated accordingly.
There are two flows:
- First time user group creating during the initial subscription
- Ongoing updates to existing groups based on the updated manifest yaml file as and when the updated file is onboarded through platform
Upon subscription or when there is any change to the manifest, the solution service ensures the user groups and role mappings in AAA match the latest manifest.
You can use the following parameters when onboarding a solution:
Path Parameters
Parameter | Description |
stackCredentialOverwrite | Forces the use of production credentials even when onboarding to developer/staging tenants. The acceptable value is production. |
forceCreateUserGroup | Set to true in order to force the user group creation during onboarding. |
Body Parameters
Parameters | Description |
versionId* | The unique ID for the app or solution version. Example: solutionversion:0f77dbcd-56vtb-5e12-90d8-6990e3a82b |
tenantIdx | Unique Id for the tenant to onboard. |
stackId | Onboard app or solution version to all tenants for a stackId. Acceptable Values:
|
The following request onboards a solution to a two tenants:
Use the CreateUsers API to add users, passing the group names from the manifest file and setting designation per the solution’s requirements for proper group mapping. This step allows for flexible mapping between designations and user groups, supporting both one-to-one and one-to-many relationships.
The following example request creates a new user, setting the designation field parameter as "New-Tenant-Admin" and the groups object as "solutions-admin" and "business-owner":