Import Links
Updated over a week ago

IMPORTANT NOTE: When importing into Dynamic Fields you need to perform both a data import and a linking import. The data import uploads the front end value (what appears in the field,) and the linking import establishes the linking relationship. If both of these are not done then complications may arise. Here's a link to our Import table of contents.


Linking records is a way to create a connection between two records that would otherwise not have a relationship to each other. For more information on linking and how to set up a form that allows for linking, please see the Help Center section on Linking.

When records are created or updated with the Import tool, any links that might need to be created for these records - or between an imported record and a record that already exists in the database - are not created at the time of import. Links can be added manually, by opening each record that needs to be linked and individually adding the link where appropriate. Instructions on this page will show you how to import links with the Import tool.

The Import tool will guide you through a preparation page where you will decide which forms to connect with imported links. Then you will download a pre-configured template in .csv format where you will paste or enter information to be imported. Once this has been uploaded to the Import tool, you will be guided through the process of validating and verifying the data and, finally, adding it to your Apricot.

Before you can import links that will connect records, all the records that need to be connected must be entered into the database.

This can be done manually, by individually creating the necessary records. Or it can be done with the Import tool. For more information on creating records with the Import tool, see our article "Create and Update Tier 1 Records".

Note: It is best practice to upload no more than 20,000 records at a time with the Import Tool. Whether creating new records or updating existing records in Apricot, it is expected that the Import Tool may experience issues when processing more than 20,000 records with each upload.

Prepare Your Data for Import

Before working with the Import tool, prepare the data that you plan to import into Apricot. Your data should be in a format - like an Excel spreadsheet - that will allow you to select columns or rows of data to paste into the Import tool template.

Because you will be importing links between records, you should assemble information on the records that need to be connected and which records you would like to connect them to. In the example above, we created an Apricot report to find Record IDs for each of the records we want to connect. Then we exported the report and matched up the rows from each form, leaving us with an Excel spreadsheet we can use to match each record to the one it should connect to.

For more information on creating a Record ID report to use with the Import tool, please see our article "Building a Record ID-Based Report for Importing Date."

 

Access the Import Tool

  1. To access the Import tool, click the Administrator tab at the top of the page.

  2. In the left hand menu, select Imports.

  3. Under "Form List," all previous files that had been imported will be listed by the form.This list will only contain information about imports that have been completed with the new Import tool. For instructions on how to access the information you imported with the legacy import tool (available prior to September 2015), please click here.

  4. To start an import of new information into the system, select Prepare for Import from the right hand palette.

 

Choose Form

  1. Expand the black arrow under Form.

  2. Select the form you would like to connect with links.

 

Choose Import Type

  1. Select import type. Data: A data import will add information to the fields on the selected form. For instructions on how to complete a data import, please click here. Linking: A linking import will add connections between the selected form and a second form. The instructions that follow on this page will describe how to import links.

  2. Field selection. The Import tool will ask you to import links using the base form as a template to prepare for the import process. If you have chosen a form that is the target form of a link relationship, the tool will automatically switch to the base form. If there is more than one link field on the base form you are connecting, you will have the opportunity to choose which link field and therefore which connection you would like to use.

  3. Reconcile. The Import tool will need to match the information you enter with information that already exists in the database to correctly identify which records should be connected. You can choose to reconcile this information using: Record IDs: Each record is assigned a unique record ID at the time it is created. Record IDs for the records you would like to connect can be found using a report. More information on how to build a Record ID report can be found here. Duplicate Check Fields: Each record has a unique combination of information in its Duplicate Check fields. You may know the information contained in Duplicate Check fields for the records you would like to connect; this information can also be found in a report.

 

Column Selection

  1. Under the Column Selection header, you can see the fields the system will use to reconcile or match information you wish to enter. These are the fields that we will find on the .csv template the Import tool creates for us.

Because we are using Record IDs to find the records we need to connect, there will only be two columns in our .csv file - the Record IDs for the records we want to connect.

 

.CSV Preview

The Import tool will prepare a spreadsheet in .csv format to hold the data you will be importing. This is a preview of what will be provided in that .csv template. These columns should match the fields under the Column Selection section above.

The first two rows of the .csv will be dedicated to "Column ID" and "Column Name" as shown in the example above. These two rows contain information that will ensure the Import tool places your links in the right place in your Apricot.

 

Import Instructions

Import Instructions will display details for the kinds of data that will be accepted for import.

  1. If you are importing Record IDs, these must match a record that already exists in the system.

  2. It can be useful to print these instructions or open them in a new browser window for reference.

  3. When you are ready, select Download .CSV File.

  4. This is the template where you will enter information to be imported into the Apricot database. It will be downloaded according to your Internet browser protocols.

 

Open CSV and Paste In Data

Begin by opening both the .csv template as downloaded from the Import tool as well as the spreadsheet containing the information you would like add to the database.

  1. This is the .csv template as downloaded from the Import tool.

  2. It has been configured with two header rows describing where the data will be added once it has been imported into Apricot. Do not change anything in these top two rows.

  3. Each column in this .csv template represents a field on a form. Each row (after the two header rows) represents one link.

  4. Open the file that contains the data you would like to import. Select information from the old file and paste it into the appropriate spot in the new .csv template.

 

Save the .CSV Template

Once the data has been added to the .csv template, save it to your desktop or to another location on your computer where you will be able to find it later.

 

Return to Apricot

  1. Once you have finished adding information to the .csv template and have saved the file to your computer, return to Apricot and select the Administrator tab at the top of the page.

  2. Select Imports from the left hand menu.

  3. Select Upload file from the right hand palette.

 

Upload

  1. Click the "Choose File" button.

  2. Find the .csv template that contains the information you want to import.

  3. Open.

  4. Upload.

 

Import Overview and Progress

Once you have uploaded your .csv file, the Import Overview page will open.

  1. Under Name, you can adjust the name of your import if necessary,

  2. And see details about the file that has been uploaded into the system.

  3. Before the information can be added to the Apricot database, it will need to go through each of the steps in the Import Progress palette.

  4. You will guide the process by selecting options under the Import Actions palette. You can choose to "Run All,"

  5. Or select each step one at a time.

  6. Your progress will be recorded by green check marks next to each step in the import process.

 

Run All

  1. If you select "Run All," the Import tool automatically runs each of the steps in the Import Progress palette (with the exception of the "Revert" which should only be used if you want to undo the changes an import has made in your Apricot).

  2. Section headers show details for each step in the Import Progress palette.

  3. A message tells you how many rows were imported. When importing links, this tells you how many records are now connected with links.

  4. Revert will "undo" an import that *has been fully imported*. If you have completed an Import in error and need to either remove it completely or re-do it, click the Revert button.

 

Import Actions

Instead of choosing "Run All," you may instead manually select each Import Progress step.

  1. Your progress will appear under the Import Progress palette. The first step, "Uploaded" will already be completed when this page opens.

  2. The next step will appear as a button under the Import Actions palette. To move to the next step, click the "Verify" button.

 

Verify

During the verify step, the Import tool checks the structure of the .csv file to make sure it is suitable for importing.

  1. When a file passes the verify step, you will see a green check box here.

  2. Details about the columns will be listed here.

 

Verify Errors

  1. If your file is found to contain errors during the verify step, you will see a red x in the Import Progress palette.

  2. Details about the error will be found under the "Verified" section of the Imports page. In the example above, there was a problem with the column related to "Service Recipients - Record ID."

 

  1. At the bottom of the page, an error message will give you instructions for fixing the error or will tell you, "This file cannot be used for import." To move beyond this step with a successful import, a new .csv file with the appropriate columns and headers will have to be uploaded and pass the verify step.

  2. If you attempt to continue the import by selecting the next step, Prepare,

  3. You will get another error message: "This import has failed and cannot continue."

 

Prepare

During the prepare step, the Import tool loads your information and tells you how many rows are going to be imported. Because two of the rows on the spreadsheet are devoted to the header columns, this number should be two less than the total number of rows on your spreadsheet. When importing links, each row will be one link or one connection between records.

  1. If your file passes the Prepare step, it will be shown with a green check mark.

  2. Details about your rows can be found here.

  3. If you need details about the rows that will be imported, you may also download a new .csv file by selecting "Get CSV" or you may view the rows by selecting view.

 

Prepare Errors

  1. If your file is found to contain errors during the prepare step, you will see a red x in the Import Progress palette.

  2. Details about the error will be found under the "Prepared" section of the Imports page. In the example above, the .csv file contained the proper header rows but no rows of data.

 

  1. At the bottom of the page, an error message will give you instructions for fixing the error; in this case: "Please verify that your file contains data." To move beyond this step with a successful import, a new .csv file with at least one row of data will have to be uploaded and pass the prepare step.

  2. If you attempt to continue the import by selecting the next step, Validate,

  3. You will get another error message: "This import has failed and cannot continue."

 

Validate

During the validate step, the Import tool checks the quality of each of your rows of data to ensure they can be imported.

  1. If your file passes the validate step, it will be shown with a green check mark.

  2. Details about your rows can be found here.

 

Validate Errors

Unlike other Import progress steps, if errors are found during the validate step, you do not have to stop your import and re-start after the files have been corrected. Instead, you can import only the records that can be validated with good data and download a .csv file of the rows containing errors. These error rows can be fixed and uploaded as a second import.

  1. If your file contains errors, you will see a yellow alert icon in the Import Progress palette.

  2. Details about the errors will be found under the "Validated" section of the Imports page. In the example above, the .csv file contains 1 row of invalid data.

  3. If you would like to download a .csv file containing only the error rows, click the "Get CSV For All Errors" button. This would be useful if you have a large file to import and would like to be able to fix the errors and upload a separate file for a separate import.

  4. The View button will display the error rows so you can see which pieces of data did not pass validation.

  5. If you would like to move forward with your import and fix the errors later, you may continue with the import process by clicking Reconcile.

 

Reconcile

During the reconcile step, the Import tool checks the identifying information you entered about the records you want to connect.

  1. When a file passes the reconcile step, you will see a green check box here.

  2. Details about the rows will be listed here.

 

Reconcile Errors

  1. If your file is found to contain errors during the reconcile step, you will see a yellow alert icon in the Import Progress palette.

  2. Details about the error will be found under the "Reconciled" section of the Imports page. In the example above, one row matches an existing link.

 

  1. You may choose to go ahead with your import even if you have reconcile errors. The error rows will be skipped if you select to continue.

 

Import and Post Processing

 

You made it! You have imported rows!

  1. A message will tell you how many rows you imported.

  2. Under the "Imported" section, you can see details.

  3. And download a .csv file of the links that were imported. This can be useful if, in the future, you need to check what was imported.

  4. Revert will "undo" an import that *has been fully imported*. If you have completed an Import in error and need to either remove it completely or re-do it, click the Revert button. 

Other Important Information

  • We recommend limiting CSV files used for imports to no more than 20,000 rows for maximum efficiency and to reduce the potential for your import to time out. With imports that contain numerous columns, a lower row count may be necessary to ensure optimal performance.

  • Auto populate fields will not populate automatically when links are imported, an additional data import or manual data entry will be needed to update the values. 

  • Dynamic Dropdown values can not be import updated if the fields already contain a link. These types of values can only be adjusted manually, at the record level.

  • Dynamic Dropdown fields which were previously empty can be imported onto, but require two imports. Both a data import and link import will be necessary

  • Dynamic Checkbox values can be imported whether or not the fields already contain a value, but require two imports. Both a data import and link import will be necessary. Options selected prior to the import will remain selected after the import.

  • Reverting an import will only revert records that have not yet been modified. The import tool will provide you a CSV of the records that were not reverted.

  • Linking imports do not show in Record Audits or in the Record History of a record.

Did this answer your question?