# 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\
   <admin@example.com> | abc123
2. **Use** the **User** Resource to create a record - These users will carry the Authenticated Role\
   <user@example.com> | abc123

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FaffHblyvcSxxJKiAa9Cr%2Fadmin.jpg?alt=media&#x26;token=f705e8f3-02e9-4195-b4ec-36551c8ab4bc" alt=""><figcaption></figcaption></figure>

### Creating Test Form

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

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FwTIqGoabh2RQRhAvfmTO%2Ftestaccessform.jpg?alt=media&#x26;token=c788a36e-679c-45fb-9e71-d21a08ab579b" alt=""><figcaption></figcaption></figure>

1. Create a new Form called **Test Access**
2. Add a Radio component called Privacy - ensure the API Property Name is **privacy**&#x20;
   * 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

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FEq4I5dSACN2fzv5Yu7Di%2Ffieldbased.jpg?alt=media&#x26;token=d91280b1-beb7-46ae-9b71-24f8e5879f77" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FpC81aO0Fs2GumUsdOtIo%2Floginform.jpg?alt=media&#x26;token=9a09d624-9c7c-4720-9113-8f7d6ec66d12" alt=""><figcaption></figcaption></figure>

### 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.&#x20;

#### **Authentication**&#x20;

Utilize the Login form within the project to authenticate a Physician and receive a JWT token.&#x20;

1. Perform a [**Post**](https://apidocs.form.io/#03acc709-aaba-b066-c69b-fb7ab92a48d0) request against the Login form using the **Admin** credentials
2. Take note of the x-jwt-token from the response header&#x20;
3. Perform a [**Post**](https://apidocs.form.io/#03acc709-aaba-b066-c69b-fb7ab92a48d0) request against the Login form using the **Authenticated** credentials
4. Take note of the x-jwt-token from the response header&#x20;

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FYumlFn8KhCODrYonMwkm%2Fadminlogin.jpg?alt=media&#x26;token=d0a48441-fe6e-4f75-aaa3-c3c81512a031" alt=""><figcaption></figcaption></figure>

#### **GET All Form Submission Request**

A [**GET**](https://apidocs.form.io/#1f207caa-9d04-3e81-2973-e4bf82ee5190) request will be made against the Test form to retrieve all submissions made against the Form.&#x20;

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** &#x20;
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**](https://apidocs.form.io/#1f207caa-9d04-3e81-2973-e4bf82ee5190) 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**

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FZcNJpnMwJVwxXN9rDGJG%2Fpostmangetsubmission.jpg?alt=media&#x26;token=ece2247a-4d03-47cf-88f1-8eb53499817d" alt=""><figcaption></figcaption></figure>