# Import
IN THIS ARTICLE Do you have data about your implementation activities prepared in an external file or system? You can use that data to create your FieldDoc records, without to enter everything by hand! By our estimates, import can save you hours of manual data entry for new records. In this article, learn how to build your portfolio using external .csv, .GeoJSON, or Shapefiles. Get existing geospatial data into FieldDoc in a breeze. This article is intended to assist users in batch import of data. If you are looking to import a single geospatial data point, view the [Geometry](/essentials/activities/geometry.md) article. *** ## Import The Import feature helps you quickly create new FieldDoc records from data you already have—such as spreadsheets or GIS files—without entering information record by record. Import is especially helpful when you are: * Adding a large number of activities at once * Migrating data from another system * Preparing a portfolio or pact to share with a funder * Working with partners who already manage data outside of FieldDoc Rather than rebuilding work you’ve already done, import lets you bring your data into FieldDoc efficiently and consistently. {% hint style="warning" %} **Important limitations to know upfront** * Import is used to **create new records only** * Existing FieldDoc records **cannot be updated via import** If you need to batch-update existing records, email **** and we’ll help you plan the best approach. {% endhint %} ### Quick Start: How Import Works At a high level, importing into FieldDoc follows a simple pattern: 1. **You choose where to start the import** 2. **You upload a source file** 3. **You map your file’s fields to FieldDoc fields** 4. **FieldDoc creates new activity records and places them accordingly** Two things determine *where your records end up*: * **Where you start the import from** (Home, Project, or Pact) * **What information you include in your source file** (such as Project or Section names) Once imported, all activity records become part of your FieldDoc portfolio. ### Important Limitations to Know Up Front Before getting started, it’s important to understand what Import can—and cannot—do. * Import is used to **create new records only** * Existing FieldDoc records **cannot be updated via import** If you have an existing portfolio and need to make large-scale updates using an external source file, please contact us at ****. We’re happy to help you plan the best approach. ### Before You Import: A Quick Checklist Taking a few minutes to prepare will save time later. Before importing, confirm that: * You are logged into the **correct FieldDoc workspace** * You know whether your records should belong to a **Project or Pact** * Your source file includes the required fields for your activity type * Your file format and size meet FieldDoc requirements * You are intending to create **new** records (not updating existing ones) ## Text and numerical fields to import
FieldDoc NameFieldDoc Field NameImportableDescription and tips
Activity Namepractice:name✅Choose a unique name or code as a reference point. This is the label for each activity record.
Activity Typepractice_type:key❌You must choose and assign activity type from the available list within FieldDoc. We recommend appending the activity type to the description during import for a quick in-app reference.
Activity Descriptionpractice:description✅A text field where you can provide narrative about the activity record. A great place to add the activity type for quick reference.
Activity Extentpractice:extent✅Number field. An extent overrides the estimated extent generated from associated polygon or line geometries. This is an especially helpful field if you are relying on point geometries. Tip: the extent will need to be manually entered into any models to run calculations.
Activity Extent unitpractice:extent_unit🟡You can import if you follow the standard FieldDoc vocabulary for extent
Completed on datepractice:completed_on✅The completion date should represent the estimated date that the activity was installed to specification.
Project Nameproject:name🟡A new project folder will be created for all unique names in the file. If all records have the same project name listed, only one folder will be created.
Section Namesection:name🟡Sections are a sub-folder within projects. One folder will be created for all records with the same section name.
### Things to consider #1: Where you start the import matters You can start an import from different locations in FieldDoc. Each option affects where your new activity records are placed. #### Importing from Within a Project or Pact If you begin the import from inside a specific Project or Pact folder: * All activities in your file will automatically be added in that folder so that you do not need to link the records later. This approach works well when you are preparing data for a funder or building out a specific portfolio. #### Regardless of Where You Start No matter where you begin the import: * All activity records become part of your FieldDoc portfolio * You can organize and link them later if needed #### Importing from the Home Page If you begin the import from the Home Page and select Activities as the destination: * Activity records will be created without a Project or Pact association * Unless Project or Pact information is included in your source file This approach gives you more flexibility if you plan to organize records after import. ### Things to consider #2: Use Import to build your folder structure Import can do more than create activity records—it can also help you create **Projects and Sections** automatically. This is optional and considered more advanced FieldDoc usage. If you are new to FieldDoc, you can skip this and organize records later. #### Including Project and Section in Your Source File If your import file includes columns for: * **Project** * **Section** FieldDoc will automatically: * Create new Projects and Sections (if they don’t already exist) * Place your activity records inside them {% hint style="info" %} The "rule" that FieldDoc only creates new records applies to project and sections as well. That means that if you have an existing project in FieldDoc and you import a file with a project name field, regardless of if the names match, FieldDoc will create a new project. This means that if you are importing new activity records to an existing project then you need to import them directly to that project or organize them after import. {% endhint %} ## Supported File Types and Limits FieldDoc follows standard data import practices. If your file meets the requirements below, it will import successfully. #### Supported File Types * `.csv` * `.GeoJSON` * Shapefiles (zipped) #### File Size and Feature Limits * **Maximum upload size:** 10 MB * **Maximum features per upload:** 1,000 For shapefile archives, the 10 MB limit applies to the total size of all uncompressed files. If your dataset exceeds these limits, additional features will be ignored. For larger workloads, please contact **** so we can help you plan your workflow. ### File Type: .CSV #### *When to use a .csv file.* If you have all of your activity records and associated attribute data prepared in a spreadsheet, you can import that spreadsheet into FieldDoc in a .csv format. Every row in the spreadsheet will create a new activity record. Files in comma-separated value (CSV) format may contain spatial data, but it isn't required. If included, geometry values should be provided as coordinates or [well-known text](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry). When your file contains coordinates, columns for latitude and longitude **must** be present. Please refer to the following column header mappings before uploading CSV files with spatial data. If you don't include coordinates, you will be able to draw your geometries in FieldDoc or make use of the import option within each activity record's geometry tab to delineate the implementation location. | **Value** | **Supported column headers** | | --------- | ------------------------------------------- | | geometry | wkt | | latitude |

lat
latitude
y

| | longitude |

lng
lon
long
longitude
x

| #### Sample template: .csv {% file src="/files/4K7Z3rHdzd0B2Rj9k3vO" %} ### **File Type: Shapefile** When importing shapefiles you can quickly configure d You can import a multi-feature shapefile to create many records at once, or import a single shapefile into the geometry tab of a single activity record. The following instructions are provided as general guidance for all shapefile imports; however, the demo template includes multiple features. **Files to include in your archive.** In addition to the mandatory .shp, .shx, and .dbf files, shapefile archives must include a .prj file that describes the coordinate system and projection. The files should be projected in WG84. All files must be compressed into a .zip file before uploading. To ensure that FieldDoc reads the archive correctly, the archive itself and the files it contains should share the same name.

All of the file types to include in your compressed file.

#### Tips and tricks for preparing your shape file for import: * File names must not contain spaces. * FieldDoc will interpret each feature as a unique record. If you are attempting to import multiple polygons into a single record, they must be configured as multi-polygons before import. * Nested ZIP folders are not supported (e.g. example.zip > example > example.shp). All required files must be stored in the top level of the ZIP folder (e.g. example.zip > example.shp, example.shx, …). #### Sample Shapefile {% file src="/files/rWlDK3SjY6y4KsQ3klpD" %} ### **File Type: GeoJSON** GeoJSON files must use the .json or .geojson file extensions and follow the format described in [this specification](https://tools.ietf.org/html/rfc7946). We recommend testing GeoJSON data with [geojson.io](https://geojson.io/) before uploading it to FieldDoc. See [here](https://www.mapbox.com/help/define-geojson/) for more help with the GeoJSON format. ## Step 2. Import your source file 1. Prepare your source file. Review our [source file requirements](#prepare-your-source-file) to make sure that your file will be successfully imported. 2. You can find the **Import File** button in several places across FieldDoc. Before you begin, we recommend reviewing [**How FieldDoc Organizes Your Data**](#how-fielddoc-organizes-your-imported-data) to choose the best place to start your import—whether that’s from the **Home Page**, a **Project**, or a **Pact**. Your starting point helps determine how your data will be grouped and displayed. > **Tip:** Starting your import from the right place saves time and helps keep your activities organized automatically. 3. Open the Import File button. Drop in your source file and click **upload**. 4. Map your source file fields to the FieldDoc fields. 5. Click save. 6. FieldDoc may take a few moments to generate all of the new records. Once it has completed the task the button will turn green and indicate how many records were imported. 7. Some fields cannot be imported. Once you have imported your source file, you must complete the configuration for each activity record. For example, you may need to assign `activity types`, run [models](/essentials/activities/models.md), and attach [programmatic metrics](/essentials/metrics/metrics-programmatic.md) in the FieldDoc system. ### Dig in! Interactive Training Tutorial {% @arcade/embed flowId="JOLCfjh94voD5JpBwRX0" url="" %} ### Complete data entry within FieldDoc for the imported activity records FieldDoc's importer cannot import the following fields: * `Activity Typef` * `Model Input` These are critical fields in the FieldDoc system, so users will need to manually input this information. Both Activity Type and Extent fields can be quickly inputted using the [Tables (Grid View)](/essentials/tables-grid-view.md). Alternatively, you can open the **Edit Activity** modal and enter this information in manually. {% tabs %} {% tab title="Single Activity" %} ### Single Activity: Step-by-Step Instructions For more detailed instructions, visit the [Activities](/essentials/activities.md) pages. #### Assign Activity Type 1. Open the **Edit Activity** modal. 2. Navigate to **Activity type** view. 3. Select **Choose Activity** type to open the universal list. 4. Search for the appropriate `activity type`. Select it. Save. Close modal. 5. **Save** on the overview page. #### Activate Model(s) 1. Open the **Edit Activity** modal. 2. Navigate to the **Models** view. 3. Follow the instructions to input all required fields and run the model. 4. Click **save**. #### Metrics 1. Open the **Edit Activity** modal. 2. Navigate to the **Metrics** tab. 3. Select the associated Pact to access the relevant Programmatic Metrics list. > **Tips:** > > * Link your activity record to a Pact in order to access the Programmatic metrics. > * Activity records can be assigned to multiple Pacts. ### Dig in! Interactive Tutorial {% @arcade/embed flowId="n1iv1gciMCZHUPUmOgKB" url="" %} {% endtab %} {% tab title="Table View" %} ### Table View: Step-by-Step Instructions Table View is a simple way to see and update many of your activity records at once—kind of like working in a spreadsheet. Instead of opening each activity one by one, you can scroll through a table and edit key details directly from the page. This is especially helpful when you need to review or enter data for multiple records at the same time. Below, we’ll walk you through what you can do in Table View and how to use it effectively. #### Activity types 1. Navigate to the activity types field. 2. Click the drop down arrow. A list of all activity types in FieldDoc pops up. 3. Search, scroll, and select the `activity_type` that matches your work. 4. Close the modal. 5. You can repeat these steps within individual rows/records, or, you can copy (CTRL+C) and paste (CTRL+V) the same activity type and activity type key into other rows/records. #### Extent 1. Navigate to the `extent` field. 2. Enter in a numerical value. 3. Navigate to the `extent_unit` field. 4. Select the unit from the available list. #### Completed date 1. Navigate to the `completed_on` field. 2. Open the calendar tool. 3. Select a date in the past. {% hint style="info" %} At this time, models cannot be activated from the table view. To [turn on a model](/essentials/activities/models.md) to calculate environmental benefits, you must open the [Edit Activity](/essentials/activities/models.md) modal within each activity record. {% endhint %} {% endtab %} {% endtabs %} ## Common Import Mistakes (*and How to Avoid Them*) Import is designed to be flexible, but a few common missteps can create extra work. Reviewing these ahead of time can save you from needing to re-import data or reorganize records later.
Importing into the wrong workspace **What happens**\ Activities are created successfully—but they’re in the wrong organization’s workspace and cannot be moved. **Why it matters**\ Records cannot be shared or transferred between workspaces after they’re created. **How to avoid it** * Double-check the workspace name before importing * Confirm that you are working in the **lead applicant’s workspace** when importing for a pact **Tip:**\ If you’re helping a partner or client, pause here and confirm you’ve been invited to the correct workspace before continuing.
Expecting import to update existing records **What happens**\ Duplicate activities are created instead of updating existing records. **Why it matters**\ Import only creates new records; it cannot modify records that already exist. **How to avoid it** * Use import only for **new** activities * If you need to batch-update existing records, contact **** for guidance.
Starting the Import in the wrong location **What happens**\ Activities are created but aren’t linked to the Project or Pact you expected. **Why it matters**\ You may need to manually organize or relink records afterward. **How to avoid it** * Start the import from inside a **Project or Pact** if records should live there * Start from the **Home Page** only if you want unassigned records **Quick check:**\ Ask yourself—*“Where should these records land immediately after import?”*
Missing Project or Section fields in the source file **What happens**\ Activities import correctly, but folders and sections aren’t created because they were not included in the source file fields. **Why it matters**\ You can manually organize records after import from the table views. **How to avoid it** * Include **Project** and **Section** columns in your source file if you want FieldDoc to create them automatically * Ensure values are spelled consistently across rows **Note:**\ This is optional—manual organization is always possible later.
The import "hangs" when you click save. **What happens** When you click save to import all of your data, the save button hangs on saving and the records are not created. **Why it matters** This means that something is interuppting the import process, either in the source file or in FieldDoc. **How to avoid it** * Make sure to follow all of the configuration guidelines based on the file type that you are utlizing. * If everything looks good in your source file, try refreshing your browser and clearing your browser cache, then try again. * If you still cannot import the file, send the file to for assistance.
Skipping field mapping step. **What happens** You import a file and skip the field mapping step, you just click save. FieldDoc will create activity records for all of the rows of data and map the geometries data to individual activity records. All all FieldDoc fields will remain empty. **Why it matters** FieldDoc import will "work" even if you don't map any fields from the source data to the FieldDoc schema; it will simply follow the instructions that you give it. Importing the geospatial data is automated, so the points, lines, or polygons will be imported regardless. If you need to remove these records because you do have field data to map, please delete the records first. Reach out to if you need assistance deleting a failed import.
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.fielddoc.org/essentials/import.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.