# Using Site Candidate Loader

You can use the _Load Candidate Sites_ action, available on the _Study_ lifecycle, to load _Candidate Sites_ using a properly formatted CSV file. Using the information in the CSV, Vault creates new _Candidate Site_ records and automatically enters the _Organization_, _Location_, and _Person_ records for the new site records based on text matching.

## How to Run the Load Candidate Sites Action

If you have a <a class="download-link " href="https://platform.veevavault.help/assets/downloads/clinops-site-candidate-loader-sample-file.csv" target="_blank" rel="noopener">properly formatted CSV<i class="fa fa-download" aria-hidden="true"></i></a> that includes _Candidate Sites_ for a _Study_, you can use this CSV to automatically create the _Candidate Sites_ in Vault. Here's how:

1. Locate the _Study_ to which you want to add _Candidate Sites_.
2. From the **All Actions** menu, select **Load Candidate Sites**.
3. Click **Upload Candidate Sites** and select the properly formatted CSV file you wish to use to upload _Candidate Sites_.
4. Click **Submit**.
5. Vault verifies the information, processes the records, and creates the new _Candidate Sites_.

For more detailed information about Vault's validation and processing of the records, see below.

## Site Candidate CSV Validation

When you select a CSV for upload, Vault performs a series of validation checks.  First, it checks the format and size of the CSV to ensure that the data is not corrupted, the file is not too large (greater than 2000 rows), and that the file is, indeed, a CSV. Next, Vault checks the headers present in the file. The following are mandatory:

* _Study Country_
* _Site Name_

If these are not present, Vault issues an error and does not proceed. Vault also checks the CSV to see if the following optional fields are present:

* _Principal Investigator_
* _Organization_
* _Location_

If any of these fields is not present, you must confirm that you wish to continue. Additionally, if the _Location_ field is populated, the _Organization_ field must also be populated.

## Site Candidate Loader Processing

Once successfully performing the validation checks, Vault enables the _Submit_ button in the dialog window. When you click the _Submit_ button, Vault begins the _Process Site Candidate Loader_ job to process the file. Vault uses text matching to process the CSV. To this end, Vault treats all values as if they are lowercase and without any spaces. Further, it ignores any special characters and leading/trailing whitespace.

Vault first attempts to match the _Study Country_ value from the CSV to an existing study country _Name_ (`name__v`), _Country Name_ (`country__v`), and _External ID_ (`external_ID__v`).

Vault sets the `name__v` field on the _Study Site_ object to the value of the "Site Name" column on the CSV.

To determine the newly-created site record's _Organization_ value, Vault attempts to match the CSV value to `organization__v` records already in Vault based on following fields on the organization__v object:

* _Name_ (`name__v`)
* _External ID_ (`external_id__v`)

If there are multiple matches for the _Organization_ field, Vault does not populate the _Organization_ field on the newly created Site record. If Vault locates a single match, it sets the `organization__clin` field on the new `site__v` record to the matching _Organization_ value.

To determine the newly-created site record's _Location_ value, Vault attempts to match the CSV value to the CSV value to `location __v` records based on the following fields on the on the `location__v` object:

* _Name_ (`name__v`)
* _External ID_ (`external_id__v`)

Vault only searches the `location__v` records whose parent `organization__v` is the record identified in the previous step. If it locates a single match, Vault sets the `location__v` field of the new `site__v` record as the matching _Organization_ record. Further, if only one location exists for the parent _Organization_ record, Vault defaults that location for the new `site__v` record.

Vault attempts to match the CSV Principal Investigator heading value to the following _Person_ (`person__sys`) object fields:

* _Name_ (`name__v`)
* _Email_ (`email__sys`)
* _External ID_ (`external_id__v`)

If Vault locates a single match, it populates the `principal_investigator__v` field of the new `site__v` record with the matching value. If there are multiple matching _Person_ records, Vault does not populate the `principal_investigator__v` field on the new `site__v` object at all.

Vault creates a new `site__v` record for each record it processes in the CSV. See the table below for a recap of how Vault populates the `site__v` fields:

<table>
  <tr>
   <td><strong>CSV Header</strong>
   </td>
   <td><strong>Matches in Vault</strong>
   </td>
  </tr>
  <tr>
   <td><em>Site Name</em>
   </td>
   <td><code>name__v</code>
   </td>
  </tr>
  <tr>
   <td><em>Study Country</em>
   </td>
   <td><code>study_country__v</code>
   </td>
  </tr>
  <tr>
   <td><em>Organization</em>
   </td>
   <td><code>organization__v</code>
   </td>
  </tr>
  <tr>
   <td><em>Location</em>
   </td>
   <td><code>location__v</code>
   </td>
  </tr>
  <tr>
   <td><em>Principal Investigator</em>
   </td>
   <td><code>primary_investigator</code>
   </td>
  </tr>
</table>

When the _Process Site Candidate Loader_ job is complete, Vault sends a message to the user who initiated the job. This message contains the number of records Vault created subsequent to running the job and a CSV containing individual successes and failures.