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 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 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

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.

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. [e-mail] | abc123 [e-mail] | abc123 [e-mail] | abc123 [e-mail] | 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.

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.

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 <span>{{ item.data.email }}</span>

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 <span>{{ item.data.departmentName }}</span>

   • 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: [e-mail] | Group: Support User: [e-mail] | Group: Support User: [e-mail] | Group: Sales User: [e-mail] | Group: Sales

Adding some users to groups

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 <span>{{ item.data.departmentName }}</span>

   • CHECK the Save as Reference setting

Creating a form that contains the Group as a select field

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.

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 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 request to the User Login form to authenticate the users

   • Authenticate [e-mail] - Take note of the token

   • Authenticate [e-mail] - Take note of the token

2. Perform a GET Request using Sales1 User

   • Create a new request and set it to GET

   • 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

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 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 request to the User Login form to authenticate the users

   • Authenticate [e-mail] - Take note of the token

   • Authenticate [e-mail] - Take note of the token

   • Authenticate [e-mail] - Take note of the token

   • Authenticate [e-mail] - 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

   • 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.