# Group Permissions ## **What Are Group Permissions** Group Permissions build upon Field-Based Resource access and grant users permission based on a submission against a Group Resource. Groups are saved within a Resource and assigned to different users creating a one-to-many relationship between a group and its users. Form permissions can then leverage these groups to establish permissions for the users based on the group they are associated with. ## **Why Should I Use Group Permissions?** Group Permissions create an additional layer of form access control, associating different users to specific groups, and granting those users additional permissions that would typically not be available based on their user roles. ## **How Do I Use Group Permissions?** A Resource is created to represent the Group. That Resource is then used to establish the Group database. A group can be defined as any entity that is used to coalesce different sets of users into different groups. Here are some good examples of what could be defined as a Group. * **Department** - Place employees in their own departments. * **Team** - Place athletes into their teams. * **Class** - Used to collect teachers and students together into a "class" group. Once the Group resource has been established, a Join Resource is created that will then reference the Group Resource and User-based Resource. A [**Group Assignment**](https://help.form.io/userguide/forms/form-building/actions#group-assignment) action will then be added to the Resource where the Group and User fields will be defined. Submissions can then be made against this Resource which will save the Group and User to the submission object of the Join Resource. A Select Resource field is then added to any form where Group Permissions should be established. Within the Access tab of the form, [**Field-Based Resource Access**](https://help.form.io/developers/roles-and-permissions/field-based-resource-access) will be configured to assign permissions based on the Resource reference. ## Example 1 - Joining Groups and Users In this example, we will establish a Department resource and an Employee Resource. Each employee is associated with one of the two departments, Customer Support or Sales, creating a one-to-many relationship between the Resources. A Role Resource will be A form will be created that will grant certain permissions based on the Group the user is associated with.' The **Employee** users will be created within the predefined Resource **User** ### Create Department (group) Resource This Resource will be used to establish our different Department groups. In this example, Sales and Customer Support will be the groups that are assigned to Employees in following steps. 1. Create a new **Resource** called **Department** 2. Add a **TextField** called **Department Name** ![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FAsAQPrUKqRrx7A6PIvfP%2Fdepartmentres.jpg?alt=media\&token=0db046e5-acbb-4025-8d9d-06cfc535b71e) 3. Make two **submissions** against the Resource: **Sales** and **Customer Support** \ In this example, Sales and Customer Support will be the groups that are assigned to Employees in following steps. ![Viewing the data of group to see our two "groups" called Teachers and Students.](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FEOVnH1CjZi4OvfNt7K7A%2Fdepartmentdata.jpg?alt=media\&token=cfff379b-ee0f-4fa9-97f2-2c453e45b37a) We can now create a "join" resource to bring users and groups together. ### Create Employee (users) Resource This Resource will be used to establish our different employee users. 1. **Use** the predefined **User** Resouce 2. Make 4 **submissions**. \ | abc123\ | abc123\ | abc123\ | abc123\ \ We can now create a "join" resource to bring users and groups together.
### Creating a Join Resource To create a one-to-many relationship between Users and Groups (where users can be associated with many groups, and vice-versa) we will create another Resource that will serve the sole purpose of "joining" these two resources together. This is typically called a **Join Resource** and is very powerful in establishing a one-to-many or many-tomany relationship between different resources. {% hint style="info" %} A one-to-many relationship is also possible by simply adding the "Group" field to the User resource, but for this example, we will cover the more common use case of using a join resource. {% endhint %} 1. Create a new **Resource** and call it **UserGroup** 2. Drag and drop a **Select** component called **User** * Click the **Data** tab, and then select **Resource** under **Data Source Type**. * Select **User** for the Resource setting * Add the following for the **Item Template**\ `{{ item.data.email }}` 3. Drag and drop a **Select** component called **Department** * Click the **Data** tab, and then select **Resource** under **Data Source Type**. * Select **Department** for the Resource setting * Add the following for the **Item Template**\ `{{ item.data.departmentName }}` * **CHECK** the **Save as Reference** setting 4. **Save** the field settings and Resource.
5. Click the **Action** tab and add the **Group Assignment** action * Set the **Group Resource** setting to **Department** * Set the **User Resource** setting to **User** * Leave the **Role** setting empty 6. **Save** the Action
8. Click the **Use** tab and make submissions to establish the User Groups. \ **User:** | **Group:** Support \ **User:** | **Group:** Support \ **User:** | **Group:** Sales \ **User:** | **Group:** Sales ![Adding some users to groups](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FP7wJuVrRSpxY3SrUW8K9%2Fusergroupsubmissions.jpg?alt=media\&token=f6b09ae1-4881-4a63-8df8-228f88d51945) ### Assigning Group Permissions To test the permission system, add a Group to a form by using a Select Resource field, and then provide access to that form based on the group that the user belongs to. For example, we could create a **Group Test** form, and then add the **Department** as a field to that form. The **Department** field will then be used as the Resource to determine CRUD operations for the Form's submissions. 1. **Create** a new form called **Group** **Test** 2. Add a **Select** field to the form called **Department** * Click the **Data** tab, and then select **Resource** under **Data Source Type**. * Select **Department** for the Resource setting * Add the following for the **Item Template**\ `{{ item.data.departmentName }}` * **CHECK** the **Save as Reference** setting ![Creating a form that contains the Group as a select field](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FPbICpCnR6NYYoQMEJsAA%2Fgrouptestform.jpg?alt=media\&token=66ee949f-b875-41d7-b331-98e50bdd5cb7) 3. Click the **Access** tab and navigate down to the **Field-Based Resource Access** * Set the following **permissions**\ **Permission:** Read | **Resource:** Department\ **Permission:** Create | **Resource:** Department ![Giving groups "read" and "create" access to the form submissions.](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FVlrIDCxgXjEMKtm91ifF%2Fgrouptestfieldbased.jpg?alt=media\&token=51eb9a42-cd35-4e6b-9e35-1b471a6b536e) This configuration can be interpreted as: > Any user part of the Sales department can make a submission and can read other Sales submissions, but not Customer Support submissions. Any Customer Support can make a submission and read other Customer Support submissions, but not Sales submissions. ### Test Workflow Using Postman In this example, PostMan will be used to send out [**API**](https://apidocs.form.io/) calls to authenticate the different users. Requests will be made to the Group Test form from the different users to verify the permissions are working correctly. 1. Within Postman, perform a [**POST**](https://apidocs.form.io/#03acc709-aaba-b066-c69b-fb7ab92a48d0) request to the **User Login** form to authenticate the users * Authenticate - Take note of the token * Authenticate - Take note of the token
2. Perform a **GET** Request using **Sales1** User * Create a new request and set it to [**GET**](https://apidocs.form.io/#bc4aaf65-ee01-9c85-005f-ac7b433612d8) * Add the endpoint for the **Form Testing** submission containing the **Sales** department\ `{{projectUrl}}/{{formPath}}/submission/{{submissionId}}` * Add the token for **Sales1** user within the header of the request * Executing the request should return the submission JSON
3. Perform a **GET** Request using **Support1** User * Within the Header of the same request, replace the Sales1 token with Support1 token * Execute the same GET request for the Sales submission - The response should return Unauthorized * Within the same request, Replace the submission ID with the ID for the Support submission
* Using the same request, replace the submission ID for the endpoint with the ID for the Support submission - The response should return the submission JSON ## Example 2 - Group Roles Group Roles can add a granular layer of permissions to users within a single group. For example, if you wish to have a Group defined as a **Department,** the Group Roles system allows you to assign users to a Department, but then choose if they are an Employee or Admin within that Department. The role field can then be used to grant separate permissions based on their role within the Group ### Create Role Resource This Resource will be used to create and establish the Roles that will be associated with the Employee User giving granular permission over the permissions assigned to the Users. This Role field will be used to establish granular within the Groups. 1. Create a new **Resource** called **Group Role** 2. Add a **TextField** called **Role**
3. Make two **submissions** against the Resource: \ Employee | Admin ### Add Role Field To User Group (Join Resource) The **Role** field will be added to the existing **User Group** resource (Join Resource in the example above) as a Select Resource component. 1. Drag and drop a **Select** component called **Role** * Click the **Data** tab, and then select **Resource** under **Data Source Type**. * Select **Role** for the Resource setting * Select **Role** for the **Value Property** setting (this automatically configures the item template) ![A Join Resource to bring Users and Groups together](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2Fwoo6kWGnxqGwxeqTSVyE%2Fusergroupres.jpg?alt=media\&token=ecd90f99-1603-45d9-8ff6-31ea82b30a34) 2. Click the **Action** tab * Edit the **Group Assignment** action * Click the **Role** dropdown and select **Role**
3. Click the **Data** tab * **Delete** all **entries** (the entries are recreated due to a limitation of the Group Assignment which will be resolved in the future) * Create four new users \ **Support1/Sales1** users will carry the **Employee** role\ **Support2/Sales2** users will carry the **Admin** role
### Modifying Group Test Form The Group Test form will need to be updated to support our Granular role system. 1. Click the Group Test **Access** tab and navigate down to the **Field-Based Resource Access.** * Set the following **Permissions**. \ Create - **Resources**: Department | **Role**: Employee, Admin. \ Read - **Resources**: Department | **Role**: Employee, Admin\ Delete - **Resources**: Department | **Role**: Admin

The Delete permission not shown in the image

This configuration can be interpreted as: > Any user part of the **Sales** department with the **Employee** or **Admin** role can **create** a submission and can **read** other Sales submissions. Only Sales user with the **Admin** role can **Delete** the Sales submission. Customer Support users will not have any access. > > Any user part of the **Customer Support** department with the **Employee** or **Admin** role can **create** a submission and can **read** other Customer Support submissions. Only Customer Support users with the **Admin** role can **Delete** the Customer Support submission. Sales users will not have any access. 2. Click the **Data** tab and edit all submissions to update with the new permissions
### Test Workflow Using Postman In this example, PostMan will be used to send out [**API**](https://apidocs.form.io/) calls to authenticate the different users. Requests will be made to the Group Test form from the different users to verify the permissions are working correctly. 1. Within Postman, perform a [**POST**](https://apidocs.form.io/#03acc709-aaba-b066-c69b-fb7ab92a48d0) request to the **User Login** form to authenticate the users * Authenticate - Take note of the token * Authenticate - Take note of the token * Authenticate - Take note of the token * Authenticate - Take note of the token
2. Perform a **GET** Request against the **Group** **Test** form submission using **Authorized** User * Create a new request and set it to [**GET**](https://apidocs.form.io/#bc4aaf65-ee01-9c85-005f-ac7b433612d8) * Add the endpoint for the **Form Testing** submission containing the **Sales** department\ `{{projectUrl}}/{{formPath}}/submission/{{submissionId}}` * Add the token for **Sales1** user within the header of the request * Executing the request should return the submission JSON
3. Perform a **DELETE** Request using **Unauthorized** Users * Change the request type to DELETE * Executing the request type should return Unauthorized since the Sales1 user does not carry the Admin role allowing them to delete a submission * Within the Header of the same request, replace the Sales1 token with Support2 token * Executing the request type should return Unauthorized since Support2 is not part of the Sales group
4. Perform a **DELETE** Request using **Authorized** Users * Within the Header of the same request, replace the Sales1 token with Sales2 token * Executing the request type should delete the submission since Sales2 is part of the Sales group with the Admin role allowing them to delete a submission
## How does Group Permissions work? So how does this all work? Let's start with the Group Resource. When a Resource is created, each submission carries a unique ID. This can be seen within the browser URL when viewing a submission, essentially generating a unique ID for a **Group** when utilizing the Resource as a Group Resource. This same concept applies when creating Group Assignment **Roles**.
When the Join Resource is created to join a User and Group together, a Group Assignment action is added to the Resource. This action adds a special flag within the submission object to distinguish the User, Group, and Roles field data within the submission of the Join Resource.
Group permissions work by assigning the Group ID (submission id) as a "role" that is added to the user's submission object as well as any Role value submitted with the user. This can be seen by viewing the user's submission JSON and viewing the "roles" property which will contain any group id's that the user has been assigned.

In this example, the Support1 user is part of the Support Group carrying the Employee role.

In the screenshot above, we can see 3 different role identifiers. The first role ID is the Role given to the User by the **Role Assignment** action within the **User** Resource. In this case, these Users receive the **Authenticated** role from the action. These roles are traditionally used to configure a form's Submission Data access permission. If we look at the URL endpoint when viewing the Authenticated role within our Project, we can see the IDs match. This role is not being demonstrated in the examples above.
The second role ID is the Group submission ID saved to the user object when their record was created within the Join Resource. If we navigate to the Group Resource and view the submission of the Group the user was joined to (in this case, the Customer Support group) the IDs can be matched between the submission and user object.
Lastly, the Employee role comes from the Role field within the Join Resource. The Role field is pointing towards a Role resources which contain the values Employee and Admin. The Role field is configured to display the value property which will save the Label of the value within the submission object.
When configuring the Group Permissions for a form, you must set the Group reference the form will use for access and any granular role.
Let's compare the UI above to the submission JSON of the form containing the Support group value. The form is looking for a user that contains the Support value ID from the Group Resource as well as an Employee or Admin role and will grant permissions based on how the access is configured.
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.form.io/developers/roles-and-permissions/group-permissions.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.