Importing Shapefiles into TerraFlow Data Engine

Learn how to import existing GIS data from shapefiles into your TerraFlow projects for field reference or data integration.

Time needed: 3-5 minutes depending on file size and complexity

Before you start:

  • Log in to TerraFlow Data Engine at https://app.terraflow.ca
  • Have your shapefile prepared and zipped (see requirements below)
  • Verify the shapefile is in Web Mercator projection
  • Know which project, workflow, job, and asset type to import into
  • Understand the shapefile attribute structure for mapping fields

Step 1: Understanding Shapefile Requirements

Before importing, ensure your shapefile meets TerraFlow requirements.

Required file format:

  • Shapefile must be zipped (shapefiles consist of multiple files: .shp, .shx, .dbf, .prj, etc.)
  • Include all shapefile component files in the zip archive

Required coordinate system:

  • Shapefile must be in Web Mercator projection
  • EPSG code: 3857 or EPSG: 900913
  • If your shapefile is in a different projection, reproject it before importing

If your shapefile is in another coordinate system (NAD83, WGS84, State Plane, etc.), use GIS software like QGIS or ArcGIS to reproject it to Web Mercator before zipping and uploading.

Step 2: Navigate to the Import Tool

Access the import function for your target project.

  1. Log in to TerraFlow Data Engine at https://app.terraflow.ca
  2. Navigate to the Projects page
  3. Locate the project you want to import data into
  4. Click Import on that project

Each import is project-specific. Ensure you're importing into the correct project as data cannot easily be moved between projects after import.

Step 3: Select Your Shapefile

Upload your zipped shapefile to TerraFlow.

  1. On the Import page, click Upload File
  2. Navigate to your zipped shapefile
  3. Select the file and click Open
  4. Wait for the file to upload (larger files take longer)

The system will validate your shapefile. If there are errors (wrong projection, missing files, corrupted data), you'll see an error message.

Step 4: Select Workflow, Job, and Asset Type

Define where and how the imported data should be classified.

  1. Select the Workflow that matches your imported data
  2. Select the Job where this data should be organized
  3. Select the Type (asset type) for the imported features:
    • Poles
    • Valves
    • Gas Mains
    • Manholes
    • Or other asset types available in your workflow

The Type you select determines which attributes are available and how the data appears in TerraFlow. Choose carefully as this affects field staff's view of the data.

Step 5: Map Shapefile Attributes to TerraFlow Fields

Connect your shapefile attributes to TerraFlow data fields using the drag-and-drop editor.

Using Drag and Drop Mapping

  1. View the list of shapefile attributes (left side)
  2. View the list of TerraFlow fields (right side)
  3. Drag a shapefile attribute to the corresponding TerraFlow field
  4. Drop it to create the mapping
  5. Repeat for all relevant attributes

Map the attributes you need. Unmapped attributes won't be imported.

Using Free Form Text

For fields where all imported features should have the same value:

  1. Locate the TerraFlow field you want to populate
  2. Click in the Free Form text box for that field
  3. Type the value you want
  4. This value will populate every imported feature for that field

Use Free Form for fields like "Data Source: Imported 2025-10-11" or "Status: Existing" where all features should have the same value.

Step 6: Preview the Import

Review your mapped data before committing the import.

  1. Click Preview after completing your attribute mapping
  2. The system displays a preview of your imported features on the map
  3. Click on any feature to inspect its attributes
  4. Verify that:
    • Features appear in the correct locations
    • Attributes are mapped correctly
    • Values look accurate
    • Asset type is appropriate

Take time to spot-check several features. It's much easier to fix mapping issues before import than to delete and reimport later.

Step 7: Complete the Import

Import the data into your TerraFlow project once you're satisfied with the preview.

  1. Review the preview one final time
  2. Click Import to begin the import process
  3. Wait for the system to process and load your data
  4. You'll see a confirmation message when the import is complete

Large datasets may take several minutes to import. Don't close the browser window until the process completes.

Step 8: Verify Imported Data

Confirm the import was successful and data appears correctly.

  1. Navigate to the Map view for your project
  2. Locate and zoom to your imported features
  3. Click on features to verify attributes imported correctly
  4. Check that features are in the correct job
  5. Verify the asset type is displayed correctly

If you notice issues, you may need to delete the imported data and reimport with corrected mapping.

Troubleshooting

"Invalid projection" or coordinate system error?

  • Verify your shapefile is in Web Mercator (EPSG:3857)
  • Check the .prj file is included in your zip archive
  • Use GIS software to reproject the shapefile before importing
  • Ensure all shapefile component files are in the zip

Upload fails or file rejected?

  • Verify the shapefile is properly zipped (all component files together)
  • Ensure the shapefile isn't corrupted (open it in GIS software first)
  • Verify the zip file isn't password protected
  • Check that all required shapefile files are present (.shp, .shx, .dbf, .prj)

Features appear in wrong location after import?

  • Shapefile is likely in wrong coordinate system
  • Reproject to Web Mercator (EPSG:3857) and reimport
  • Verify the .prj file accurately describes the coordinate system
  • Check source data for coordinate system information

Can't find workflow, job, or asset type I need?

  • Verify the workflow is configured in the project
  • Check that the asset type exists in the selected workflow
  • Create a new job if needed before importing
  • Contact your Organization Administrator to add missing workflows or types

Attributes not mapping correctly?

  • Verify shapefile attribute names and data types
  • Check for special characters or spaces in attribute names
  • Ensure data types are compatible (text to text, numbers to numbers)
  • Try using different attribute mappings

Preview shows no features or map is blank?

  • Check that features exist in the shapefile
  • Verify the shapefile has valid geometry
  • Ensure features aren't outside the map extent (zoom out)
  • Check that the coordinate system is correct

Import process seems stuck or takes forever?

  • Large datasets take longer—be patient
  • Check your internet connection
  • Don't close the browser window during import
  • Contact support@terraflow.ca if import exceeds 10 minutes for a reasonably sized file

Imported wrong data—how do I delete it?

  • Navigate to the Map view
  • Select and delete features individually, or
  • Contact support@terraflow.ca for bulk deletion options
  • Consider creating a test project to practice imports before production use

Tips for Success

  • Test first: Import a small sample of your data into a test project to verify mapping before importing large datasets
  • Reproject in advance: Always reproject to Web Mercator before attempting import—this is the most common import issue
  • Include all files: Ensure your zip contains .shp, .shx, .dbf, .prj, and any other shapefile components
  • Clean data: Review and clean your shapefile in GIS software before importing (fix geometries, check attributes)
  • Attribute planning: Plan your attribute mapping before starting—know which fields map to which
  • Consistent values: Use Free Form text for fields that should have the same value across all features
  • Meaningful job names: Import into appropriately named jobs for easy data organization
  • Preview thoroughly: Check multiple features during preview—don't just click Import immediately
  • Document your mapping: Keep notes on how attributes were mapped for future reference or additional imports
  • Backup source data: Keep copies of original shapefiles in case you need to reimport
  • Batch similar data: Import features of the same type together (all poles in one import, all valves in another)
  • Coordinate with field staff: Let field users know when you've imported reference data they can use

Related Articles

Need more help? Contact TerraFlow Support at support@terraflow.ca