Field Match-Based Access
What Are Field-Based Resource Access
Field Match Access is useful if you want to configure submission access based on specific field values saved within the submission.
Why Should I Use Field-Based Resource Access?
Field-based access grants submission permissions to certain users based on the value of certain fields within the form. For example, a 'privacy' field on the form has "public" and "private" values. Access can be granted to specific role-based user groups depending on what privacy value was selected with the submission
How Do I Use Field-Based Resource Access?
For each permission that can be granted the following criteria can be used to perform the "match" for access.
Roles - A selection of roles that can be applied to that match
Field Path - The path for the field to determine if the value conditionally applies this permission.
Operator - The operator to use for comparison of the field value and the value criteria.
Type - The data type of the value.
Value - The value to use in the comparison to determine if this is a match and the permission should apply.
To use Field Match Access, specify a form's or a submission's field's path (e.g. "data.privacy" for the "privacy" field within the form, "state" for the "state" field of the submission) and also a value which it should be compared with. You can select one of the available operators for comparison and specify a type of value. If you add multiple conditions for a single role, access will be given if at least one of them passes.
Values of arrays should be separated by "," without spaces. Strings should NOT be wrapped in the brackets.
The permissions that can be granted are as follows and pertain to all records saved to the Form.
Workflow Example
In this example, the Admin and User resources will be used to create records. A form will be created with Public and Private records. Field Match-Based access settings will be configured to allow the Authenticated Users to Read Public records while Administrators will have permission to Update, Create, and Read Public and Private records. Postman will be utilized to handle the requests and responses to the server.
Establishing Resources
Use the Admin Resource to create a record - These users will carry the Administrator Role admin@example.com | abc123
Use the User Resource to create a record - These users will carry the Authenticated Role user@example.com | abc123
Creating Test Form
This form will be used to test the access settings using role-based field values.
Create a new Form called Test Access
Add a Radio component called Privacy - ensure the API Property Name is privacy
Add two values Public and Private
Add a Text Field called Information
Click the Access setting tab, navigate to the Field Match-Based Access section, and add the following permissions.
Role: Authenticated | Field Path: data.privacy | Operator: equal | Type: string | Value: public
Role: Administrator | Field Path: data.privacy | Operator: equal | Type: string | Value: public
Role: Administrator | Field Path: data.privacy | Operator: equal | Type: string | Value: private
Make 4 submissions Privacy: Public | Information: Public Record #1 Privacy: Public | Information: Public Record #2 Privacy: Private | Information: Private Record #1 Privacy: Private | Information: Private Record #2
Modify Login Form
The User Login form will be used to log in both the Admin and Authenticated users. To ensure the Admins can log in using the same form, modify the Login action saved to the User Login form and ensure it references the Admin resource.
Edit the User Login form within the project
Click the Action tab and edit the Login action
Click the Resource dropdown and select the Admin Resource
Save the Action
Test Workflow Using Postman
To test this workflow, Postman will be utilized to authenticate the users and to send the API requests to read and update submissions.
Authentication
Utilize the Login form within the project to authenticate a Physician and receive a JWT token.
Perform a Post request against the Login form using the Admin credentials
Take note of the x-jwt-token from the response header
Perform a Post request against the Login form using the Authenticated credentials
Take note of the x-jwt-token from the response header
GET All Form Submission Request
A GET request will be made against the Test form to retrieve all submissions made against the Form.
Within your Project, click the Embed tab of the Test Access form.
Copy the Embed URL of the form
Within Postman, create a new request tab and set the request type to GET
Click Headers and add the Authenticated users JWT token noted in the Authentication steps and add to the request Header.
Key: x-jwt-token | Value: abcd1234 (Your token ID from the previous step)
Apply the GET All Form Submission request endpoint and perform the request
{{projectUrl}}/{{formPath}}/submission
As the User, you should receive the submission JSON within the body of the response for all Public Records but not the Private RecordsUsing the same request tab, click Headers and replace the User token with the Admin token copied from the Authentication step.
Execute the endpoint again As the Admin, you should receive the submission JSON within the body of the response for all Public and Private Records
Last updated