Automatic Creation of User Groups

overview 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 integration flow 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 upload the manifest file upload the manifest file using the upload artifact api 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 users create new users with correct user group and designation using the ums api create a manifest file 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 solutionid gated solution usergroupsrequired \ name solutions owner description solutions owner role landingpage url /app a rank 2 roles \ role\ dispatch orders app\ dispatch get orders \ role\ dispatch orders app\ dispatch view orders \ name field executive description team manager admin role landingpage url /app b rank 1 roles \ role\ dispatch routes app\ dispatch list routes \ role\ dispatch routes app\ dispatch view routes \ role\ dispatch users app\ dispatch view users adminusergroups \ solutions admin in the yaml file, we have a solution level manifest that defines user groups and their associated roles for the "gated solution" solution let's break down what this yaml file is doing solutionid this attribute specifies the unique identifier for the solution, which is "gated solution" in this case usergroupsrequired this section defines the user groups required for the solution name specifies the name of the user group in this example, we have two user groups "solutions owner" and "field executive" description provides a brief description of the user group's purpose or role within the solution landingpage specifies the landing page details for each user group url indicates the url or path of the landing page associated with the user group rank determines the order or priority of the landing page for the user group roles lists the roles assigned to each user group using the format role \<listingid> \<rolename> for the "solutions owner" user group, two roles are assigned "dispatch get orders" and "dispatch view orders" from the "dispatch orders app" listing for the "field executive" user group, three roles are assigned "dispatch list routes" and "dispatch view routes" from the "dispatch routes app" listing, and "dispatch view users" from the "dispatch users app" listing adminusergroups this section specifies the user group(s) that should be assigned to the tenant admin users for this solution in this example, the "solutions admin" user group is assigned to the tenant admin users 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 certainly! here's an updated section for the "automatic creation of user groups and roles for apps" developer guide that covers updating permissions for a frontend app updating permissions for frontend app when developing a frontend application that interacts with a backend app, you can define the roles required by the frontend app to communicate with the backend this allows for more granular control over the permissions granted to the frontend app and helps in managing the size of access tokens to update the permissions for a frontend app, you need to create a yaml file that specifies the required roles here's an example yaml file appid "platform\ app\ example client" rolesrequired roles \ platform\ role\ platform\ app\ example\ users \ platform\ role\ platform\ app\ example\ users admin \ platform\ role\ platform\ app\ dispatch\ viewer \ platform\ role\ platform\ app\ dispatch\ editor in this yaml file the appid field follows the format platform \<appidfromdevportal> client , where \<appidfromdevportal> represents the unique identifier of the app obtained from the developer portal the rolesrequired section lists all the roles that the users of the frontend app may require to communicate with the backend of the corresponding app by specifying the required roles in the yaml file, you can control the permissions granted to the frontend app when an access token is generated for a user of the frontend app, it will contain the intersection of the user's roles and the roles specified in the rolesrequired section of the yaml file for example, let's say a user has roles a, b, c, and d if the frontend app requires only roles a and b, as specified in the yaml file, the access token generated for that user will contain only roles a and b upload the 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 curl location request post 'https //developer platform tms/developer/artifacts?appversionid=appversion 1f866da9 6205 5760 a82e 94acb79dcd1e\&artifacttype=manifest' \\ \ form 'file=@"/path/to/usergroup manifest yaml";type=text/x yaml' 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) onboard the solution 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 sb1 dlv2 prod dlv india lt1 nonprod the following request onboards a solution to a two tenants { "versionid" "solnversion\ f8594a6b 47f4 4a3b 9edf 8b2c641e38af", "tenantids" \[ "devtenant1", "devtenant2" ] } create users 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" { "usercode" "user123", "userownerid" "owner456", "userownertype" "solutionprovider", "function" "administration", "firstname" "john", "middlename" "a ", "lastname" "doe", "email" "john doe\@example com", "primarymobile" { "countrycode" "+1", "number" "5551234567" }, "secondarymobile" { "countrycode" "+1", "number" "5557654321" }, "groups" \[ "solutions admin", "business owner" ], "worklocations" \[ "hq 1" ], "teams" \[ "team 1" ], "identification" { "idtype" "passport", "idnum" "p123456789" }, "fileid" "file123456", "usertype" "admin", "department" "it", "aaaid" "aaa123456", "aaagroups" \[ "admingroup" ], "designation" "new tenant admin", "employmenttype" "full time", "callback" { "url" "https //random mock pstmn io/callback/200", "metadata" {} } }