# Field-Based Resource Access
## **What Are Field-Based Resource Access**
Field-Based Resource Access assigns user permission(s) to a specific data submission based on a Resource referenced within the Form.
## **Why Should I Use Field-Based Resource Access?**
Let's imagine you are building a Clinic application, and wish to assign patients to physicians within the clinic. One of your requirements might be to ensure that only patient data is available to physicians who have been specifically assigned that Patient. Field-Based Resource Access can accomplish that by granting granular permissions to control what patient data the physicians have access to based on a reference to a given Resource.
## **How Do I use Field-Based Resource Access?**
Field-Based Resource Access is utilized by establishing Resources and referencing the Resource data as a means to grant form submission permission to a user group. When a Select Resource field is saved to a form, you can allocate that field to a Field-Based Resource Permission in the form's access settings. This is done by choosing the field within the Resource setting of the permission. When a user logs in and views the form, the user will be granted permission depending on what Group value (resource field) is saved within their user object. The following permissions can be defined for any resource field within the form.
| **Permission** | **Description** |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Read | The Read permission will allow a resource, defined in the submission, to read all of the submission data. |
| Create | The Create permission will allow a resource, defined in the submission to create or submit all of the submission data. |
| Update | The Update permission will allow a resource, defined in the submission to edit all of the submission data except for the Submission Resource Access and Owner information. |
| Delete | The Admin permission will allow a resource, defined in the submission, to delete all of the submission data. |
## **Workflow Example**
The following example will build off the use case described above. Physicians will be created using a Resource. A Patient Resource will be used to create Patients and assign Physicians within the submission using a Select Resource. That Select Resource field will be configured within the Patient Resource access settings to grant granular permissions based on which Physician is accessing the submission.
### Create Physician Resource
This Resource will serve as the Physician database that will be used to assign Physicians to Patients.
1. Create a new **Resource** titled **Physician**
2. Add a **Text Field** called **Physician Name**, **Email,** and **Password** field to the Resource
3. Add a **Role Assignment** action to the Resource
* Set the **Resource Association** to **Existing Resource**
* Set the **Action Type** to **Add Role**
* Set the **Role** to **Authenticated**
4. **Use** the Resource and make two submissions
* Joe Smith | | abc123
* Sally Fields | | abc123
### Create Patient Resource
This Resource is where Patients will be created and assigned their Physician
1. Create a new **Resource** titled **Patient**
2. Add a **Text Field** called **Patient Name**
3. Add a **Select** component called **Physician** that will reference the Physician Resource
* Within the **Data** tab, set the **Data Source Type** to **Resource**
* Set the **Resource** to **Physician**
* Set the **Item Template** to `{{ item.data.`[`physicianName`](#user-content-fn-1)[^1] `}}`
* Check the **Save as Reference** setting
4. **Save** the Resource
5. Click the **Access** tab. Within the Field-Based Resource Access section, set the following permissions
* **Read** | **Resource:** Physician
* **Update** | **Resource:** Physician
* **Save** the settings
| Permission | Description |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Read | The Read permission will allow a resource, defined in the submission, to read all of the submission data. |
| Create | The Create permission will allow a resource, defined in the submission to create or submit all of the submission data. |
| Update | The Update permission will allow a resource, defined in the submission to edit all of the submission data except for the Submission Resource Access and Owner information. |
| Delete | The Admin permission will allow a resource, defined in the submission, to delete all of the submission data. |
In the following example, Physicians mapped by the Select Resource field will have permission to **Read** and **Create** submission data for this Form.
6. **Use** the **Resource** and make four submissions
* **Physician**: Joe Smith | **Patient Name:** A
* **Physician**: Joe Smith | **Patient Name:** B
* **Physician**: Sally Fields | **Patient Name:** C
* **Physician**: Sally Fields | **Patient Name:** D
### Modify Login Form
Modify the Login form action so it references the Physician resource when authenticating login credentials
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 **Physician** 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**](https://apidocs.form.io/#03acc709-aaba-b066-c69b-fb7ab92a48d0) request against the Login form using Joe Smith Physician credentials
2. Copy the x-jwt-token from the response header to use in our GET request
#### **GET Submission Request**
Using the JWT token from the previous step, a [**GET**](https://apidocs.form.io/#bc4aaf65-ee01-9c85-005f-ac7b433612d8) request will be made to retrieve a Patient Resource submission
1. Within your Project, click the **Data** tab of the **Patient** Resource. We will take note of two different submission IDs
* **View** a submission for **Physician** Joe Smith
* Take note of the **Submission** **ID** appended at the end of the URL
* **View** a submission for **Physician** Sally Fields
* Take note of the **Submission** **ID** appended at the end of the URL
2. Within Postman, create a new request tab and set the request type to **GET**
3. Click **Headers** and add your JWT token to authenticate the request
* **Key**: x-jwt-token | Value: abcd1234 (Your token ID from the previous step)
4. Within the Postman, apply the correct [**GET Submission API**](https://apidocs.form.io/#bc4aaf65-ee01-9c85-005f-ac7b433612d8) endpoint and perform the request\
`{{projectUrl}}/{{formPath}}/submission/{{submissionId}}`\
You should receive the submission JSON within the body of the response
5. Within the same request, **change** the **Submission** **ID** to a different Physician and perform the request\
You should receive an Unauthorized error within the response
These concepts will be applied to the **Group Permissions** workflow which is discussed in the next section.
[^1]: The API Property Name of the Physician Name field within the Physician Resource
