Skip to main content

About the FieldAware Import Export Tool

Learn how to import, update, export, and validate FieldAware records using the Import Export Tool with guided workflows and schema mapping.

R
Written by Ruairi Shanahan
Updated over 2 months ago

The FieldAware Import Export Tool is a powerful interface that allows users to import and export records into their instance of FieldAware. Whether you're onboarding new data, updating existing records or requesting old records, the Import Export Tool streamlines the process with guided workflows, validation checks, and seamless mapping features.

What You Can Do with the Import Tool

  • Import records for supported FieldAware entities from CSV files.

  • Update existing records by mapping UUIDs in your data.

  • Export data from FieldAware to use in other systems or for bulk editing.

  • Download CSV templates that match the data structure for each entity.

  • Validate and troubleshoot data before sending it to the API.

Supported Entities

The first step when importing data is to choose the entity type. Each entity has a distinct API schema and set of validation rules. The Import Tool currently supports the following entities:

  • assets

  • customers

  • contacts

  • items

  • jobs

  • historicalJobs

  • jobTypes

  • locations

  • quotes

  • fieldQuotes

  • webQuotes

  • tasks

  • users

The schema and validation logic dynamically adapt based on your selected entity.

Import Workflow

After logging into the Import Tool, you'll land on the Import workflow by default. From here, you can:

  1. Select the entity you wish to import data into.

  2. Upload a CSV file containing the records.

  3. Map your CSV columns to schema fields.

  4. Review any validation errors.

  5. Run the import.

You can return to the import workflow at any time via the Navigation Bar.

Export Workflow

Use the Export workflow to download existing records for any supported entity. This is useful for creating backups, making bulk changes, or preparing CSVs for re-import.

Access the export section from the Navigation Bar.

Templates

To simplify the import process, the tool provides downloadable CSV templates for each entity. These templates include:

  • Standard fields defined in the entity schema.

  • Any custom fields configured in your FieldAware account.

Templates are accessible via the Navigation Bar.

Uploading a CSV File

You can upload a CSV file by:

  • Using the file system browser, or

  • Dragging and dropping your .csv file into the upload area.

Important: Your CSV must include a header row with unique column names. These headers are used for mapping to FieldAware’s API schema.

Mapping CSV Columns to Schema Keys

Once a CSV file is uploaded, you’ll be guided to map each column to a corresponding data field in the API schema.

Flat Schema Keys

Simple, top-level fields are mapped directly. For example:

  • "name" → Name

  • "tel" → Phone Number

Nested Schema Keys

Nested objects use dot notation in the mapping. For example:

  • "address.street" → Street Name

  • "device.make" → Device Make

Custom Fields

Custom fields are treated as flat fields within the UI and are marked with a CF badge. They appear below standard fields in the mapping table.

Auto Mapping & Saved Mappings

Auto Mapping

When a CSV is uploaded, the Import Tool attempts to automatically map headers to schema fields. It intelligently detects matches like:

  • "name" in the schema ↔ "Name" in the CSV

  • "someLongKey" ↔ "Some Long Key"

You can override these using Unmap or Unmap All options.

Saved Mappings

Once you've created a mapping, it will be saved for future sessions. You can clear all saved mappings from the menu in the Navigation Bar.

UUIDs and Record Updates

FieldAware uses UUIDs (Universally Unique Identifiers) to distinguish records. If a uuid field is present and mapped in your CSV:

  • The Import Tool will attempt to update the existing record with that UUID.

  • If no uuid is mapped, new records will be created for each row.

UUIDs must follow the 128-bit format and are represented as 32-character hexadecimal strings.

Data Validation

Every field in the API schema includes validation logic. These rules ensure that:

  • Data types are correct (e.g., strings, numbers, booleans).

  • Required fields are not missing.

  • Field values match expected formats or lengths.

Validation occurs immediately after mapping and parsing your CSV. Any errors are shown in a CSV Validation Preview, and rows with errors are excluded from the import run.

Troubleshooting Errors

Validation Errors

Rows that don’t meet schema validation rules will be flagged before import. You’ll be able to review the errors and adjust your CSV accordingly.

Import Errors

Even if data passes validation, import requests may fail due to:

  • Network issues

  • Schema mismatches

  • API rejections

These failed rows will appear in the Import Summary Report, with error details and the original request payload.

Exporting Error Logs

You can export a CSV containing all rows that failed either:

  • Validation, or

  • Import

This file includes:

  • Original row data

  • A new column with error messages (e.g., validation issues or API response messages)

This allows you to correct and re-import only the problematic records.

Get Started

The FieldAware Import Tool is designed to save time, reduce data errors, and give you full control over your business records. For best results, use the templates provided and carefully review any validation messages before importing.

Need help? Expand the sections within the Import Tool interface for step-by-step guidance at any point.

Did this answer your question?