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.

Permission	Description
Read	If the field value matches the criteria, then the user of the specified role will be able to read all submission.
Create	If the field value matches the criteria, then the user of the specified role will be able to create a submission.
Update	If the field value matches the criteria, then the user of the specified role will be able to update and read the submission.
Delete	If the field value matches the criteria, then the user of the specified role will be able to Delete the submission.

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

1. Use the Admin Resource to create a record - These users will carry the Administrator Role [e-mail] | abc123

2. Use the User Resource to create a record - These users will carry the Authenticated Role [e-mail] | abc123

Creating Test Form

This form will be used to test the access settings using role-based field values.

1. Create a new Form called Test Access

2. Add a Radio component called Privacy - ensure the API Property Name is privacy

   • Add two values Public and Private

3. Add a Text Field called Information

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

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

1. Edit the User Login form within the project

2. Click the Action tab and edit the Login action

3. Click the Resource dropdown and select the Admin Resource

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

1. Perform a Post request against the Login form using the Admin credentials

2. Take note of the x-jwt-token from the response header

3. Perform a Post request against the Login form using the Authenticated credentials

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

1. Within your Project, click the Embed tab of the Test Access form.

   1. Copy the Embed URL of the form

2. Within Postman, create a new request tab and set the request type to GET

3. 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)

4. 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 Records

5. Using the same request tab, click Headers and replace the User token with the Admin token copied from the Authentication step.

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