# Data Import System

## Table of Contents

* [Overview](#overview)
* [Getting Started](#getting-started)
* [Understanding Import Records](#understanding-import-records)
  * [Import Header Record](#import-header-record)
  * [Import Types](#import-types)
  * [Import Update Types](#import-update-types)
* [Working with Import Records](#working-with-import-records)
  * [Viewing the Import List](#viewing-the-import-list)
  * [Filtering and Searching Imports](#filtering-and-searching-imports)
  * [Viewing Import Details](#viewing-import-details)
  * [Creating an Import Record](#creating-an-import-record)
  * [Editing an Import Record](#editing-an-import-record)
  * [Deleting an Import Record](#deleting-an-import-record)
* [Imported Data Categories](#imported-data-categories)
  * [Districts](#districts)
  * [Schools](#schools)
  * [Members](#members)
  * [Units](#units)
* [Managing Import Types](#managing-import-types)
  * [Viewing Import Types](#viewing-import-types)
  * [Adding an Import Type](#adding-an-import-type)
  * [Editing an Import Type](#editing-an-import-type)
  * [Deleting an Import Type](#deleting-an-import-type)
* [Managing Import Update Types](#managing-import-update-types)
  * [Viewing Import Update Types](#viewing-import-update-types)
  * [Adding an Import Update Type](#adding-an-import-update-type)
  * [Editing an Import Update Type](#editing-an-import-update-type)
  * [Deleting an Import Update Type](#deleting-an-import-update-type)
* [Permissions Reference](#permissions-reference)
* [Common Scenarios](#common-scenarios)
* [Troubleshooting](#troubleshooting)

## Overview

The Data Import System is the area where administrators track, review, and manage batch imports of educational data from external sources. When data is synchronized into OtisEd.Nimble — such as district rosters, school listings, staff and student accounts, and organizational units — each batch is recorded as an import. These records give administrators a full audit trail of when data arrived, how many records were processed, and what category of import it was.

The system is organized around a small set of concepts that work together:

* An **import record** captures the high-level summary of a single data batch, including start and end timestamps and a count of records processed.
* An **import type** identifies the general category of the import, such as a nightly sync or a one-time load.
* An **import update type** describes how individual records within the import were handled, for example whether a district was newly created, updated, or left unchanged.
* **Imported data categories** (districts, schools, members, and units) hold the individual records that were part of each import batch.

Keeping import records accurate helps administrators verify that data synchronization is working as expected and provides a starting point when investigating discrepancies in organizational data.

## Getting Started

To access the Data Import System, navigate to the relevant Import administration sections from the main navigation menu. The level of access you have depends on your assigned permissions:

* To view import records, districts, schools, members, units, import types, and import update types: your account needs the corresponding Default view permission for each section.
* To create or edit records: your account needs the Create or Edit permission for the relevant section.
* To delete records: your account needs the Delete permission for the relevant section.

If import menu items are not visible, contact your system administrator to confirm your account has the appropriate permissions.

## Understanding Import Records

### Import Header Record

Each batch import is represented by a single import header record with the following information:

* **Start Date** — the date and time the import batch began.
* **End Date** — the date and time the import batch completed.
* **Records Processed** — the total number of records included in the batch.
* **Import Type** — the type of import that describes what category of synchronization this batch represents.

Import records are tenant-scoped, meaning each tenant sees only its own import history.

### Import Types

Import types are the labels that classify the kind of data being imported. They have a unique identifier and a descriptive name. Examples might include labels like "Nightly Roster Sync" or "Annual Enrollment Load." Import types serve as a reference that is linked to both the import header record and the import update types that belong to it.

Administrators with the appropriate permissions can define, rename, or remove import types from the Import Types management area.

### Import Update Types

Import update types sit beneath import types and describe the specific operation that was performed on a record during processing. For example, an import type of "Roster Sync" might have update types like "New," "Updated," and "Unchanged." Each district, school, member, and unit record that comes through an import is tagged with one of these update types so you can see at a glance what happened to that record during the import run.

Import update types are always linked to a parent import type. When you create or edit an import update type, you must select the import type it belongs to.

## Working with Import Records

### Viewing the Import List

The import list shows all import batches for your tenant. Each row displays the import type, start date, end date, and record count. The list supports paging and sorting to help you navigate large histories.

### Filtering and Searching Imports

You can narrow the import list using the following filters:

* **Text search** — filters by the import type name associated with the record.
* **Start Date range** — show only imports that started within a given date range.
* **End Date range** — show only imports that completed within a given date range.
* **Records Processed range** — filter by minimum and maximum record counts.
* **Import Type** — select a specific import type to view only batches of that category.

Apply filters and the list will update to show only matching records.

### Viewing Import Details

Select any import from the list to open its detail view. The detail view shows the full header record along with its linked import type information. From here you can also navigate to the districts, schools, members, and units that were part of that import.

### Creating an Import Record

Import records are typically created automatically by the data synchronization process. If you need to create one manually:

1. Open the Imports management area.
2. Select **New** or the equivalent create action.
3. Enter the start date, end date, records processed count, and select an import type.
4. Save the record.

Creating import records manually requires the Imports Create permission.

### Editing an Import Record

1. Locate the import in the list.
2. Open the record and select **Edit**.
3. Update the fields as needed.
4. Save your changes.

Editing requires the Imports Edit permission.

### Deleting an Import Record

1. Locate the import in the list.
2. Select the delete action for that record.
3. Confirm the deletion when prompted.

Deleting an import record requires the Imports Delete permission. Use caution: deleting an import header removes it from the audit trail.

## Imported Data Categories

Each import batch carries detail records in one or more of the following categories. These records represent the individual items that were processed during the batch.

### Districts

Import district records capture the districts included in a given import batch. Each record contains:

* **District ID** — the external identifier for the district.
* **District Name** — the display name of the district.
* **Import Update Type** — the operation that was performed on this district during the import (for example, "New" or "Updated").
* **Import** — the parent import batch this record belongs to.

The district list can be filtered by text, district ID, district name, import update type, and parent import batch.

### Schools

Import school records capture the schools included in a batch. Each record contains:

* **School ID** — the external identifier for the school.
* **School Name** — the display name of the school.
* **District ID** — the district this school belongs to, as provided in the source data.
* **Import Update Type** — the operation performed on this school during the import.
* **Import** — the parent import batch.

The school list can be filtered by text, school ID, school name, district ID, import update type, and parent import batch.

### Members

Import member records capture staff and student accounts included in a batch. Each record contains:

* **User ID** — the external identifier for the user.
* **First Name** and **Last Name** — the user's name as provided in the source data.
* **Email** — the user's email address.
* **Role Name** — the role assigned to this member in the source system.
* **Organizational Unit** — the organizational unit this member is associated with.
* **Role** — the internal role reference linked to this member.
* **Import Update Type** — the operation performed on this member record.
* **Import** — the parent import batch.

The member list can be filtered by text, user ID, first name, last name, email, role name, organizational unit, role, import update type, and parent import batch.

### Units

Import unit records capture organizational units included in a batch. Each record contains:

* **Unit ID** — the external identifier for the unit.
* **Unit Name** — the display name of the unit.
* **Import Update Type** — the operation performed on this unit during the import.
* **Import** — the parent import batch.

The unit list can be filtered by text, unit ID, unit name, import update type, and parent import batch.

## Managing Import Types

### Viewing Import Types

Open the Import Types management area to see a list of all defined import types. Each entry shows the type's unique ID and display name. The list supports filtering by name and paging.

### Adding an Import Type

1. Open the Import Types management area.
2. Select **New**.
3. Enter a unique ID and a display name for the import type.
4. Save the record.

Creating an import type requires the Import Types Create permission.

### Editing an Import Type

1. Locate the import type in the list.
2. Select **Edit**.
3. Update the name as needed.
4. Save your changes.

Editing requires the Import Types Edit permission.

### Deleting an Import Type

1. Locate the import type in the list.
2. Select the delete action.
3. Confirm the deletion.

Deleting an import type requires the Import Types Delete permission. Removing a type that is still referenced by existing import records or import update types may cause those records to lose their type association. Verify that the type is no longer in use before deleting it.

## Managing Import Update Types

### Viewing Import Update Types

Open the Import Update Types management area to see all defined update types, grouped or filterable by their parent import type. Each entry shows the update type's name and its associated import type.

### Adding an Import Update Type

1. Open the Import Update Types management area.
2. Select **New**.
3. Enter a display name for the update type.
4. Select the parent **Import Type** this update type belongs to.
5. Save the record.

Creating an import update type requires the Import Update Types Create permission.

### Editing an Import Update Type

1. Locate the import update type in the list.
2. Select **Edit**.
3. Update the name or the associated import type as needed.
4. Save your changes.

Editing requires the Import Update Types Edit permission.

### Deleting an Import Update Type

1. Locate the import update type in the list.
2. Select the delete action.
3. Confirm the deletion.

Deleting requires the Import Update Types Delete permission. Removing an update type that is still referenced by existing district, school, member, or unit import records will leave those records without an update type. Verify there are no active references before deleting.

## Permissions Reference

Access to each area of the Data Import System is governed by separate permission groups. All groups follow the same pattern:

| Area                | View                      | Create                   | Edit                   | Delete                   |
| ------------------- | ------------------------- | ------------------------ | ---------------------- | ------------------------ |
| Imports             | Imports.Default           | Imports.Create           | Imports.Edit           | Imports.Delete           |
| Import Districts    | ImportDistricts.Default   | ImportDistricts.Create   | ImportDistricts.Edit   | ImportDistricts.Delete   |
| Import Schools      | ImportSchools.Default     | ImportSchools.Create     | ImportSchools.Edit     | ImportSchools.Delete     |
| Import Members      | ImportMembers.Default     | ImportMembers.Create     | ImportMembers.Edit     | ImportMembers.Delete     |
| Import Units        | ImportUnits.Default       | ImportUnits.Create       | ImportUnits.Edit       | ImportUnits.Delete       |
| Import Types        | ImportTypes.Default       | ImportTypes.Create       | ImportTypes.Edit       | ImportTypes.Delete       |
| Import Update Types | ImportUpdateTypes.Default | ImportUpdateTypes.Create | ImportUpdateTypes.Edit | ImportUpdateTypes.Delete |

Your system administrator assigns these permissions through the role and permission management area.

## Common Scenarios

**Verifying a nightly sync ran correctly** Open the Imports list and filter by the relevant import type. Confirm there is a record for today with a start date, end date, and a records processed count that matches your expectations. If no record is present, the sync may not have run or may have failed to log.

**Checking why a district is missing from the portal** Open the Import Districts list and search by the district's ID or name. If no import district record exists for that district, it was not included in any import batch. If a record exists, check the import update type to see whether it was processed as new, updated, or unchanged.

**Reviewing what changed during an import for a specific school** Open the Import Schools list, filter by the relevant import batch and by the school ID or name, and review the import update type on the matching record.

**Setting up a new kind of data load** First create an Import Type that describes the new kind of load. Then create one or more Import Update Types under that type to represent the operations (such as "New," "Updated," "Skipped") that will be used when records are tagged during processing.

## Troubleshooting

**Import records are not appearing in the list**

* Confirm your account has the Imports.Default view permission.
* Check whether any active filters are hiding records. Clear all filters and try again.
* Verify the synchronization process completed successfully. A failed sync may not have written any import records.

**A district, school, member, or unit is not linked to an import**

* The import ID field on individual records is optional. Records that were not part of a tracked batch may have no import association.
* Open the record in its respective list and check whether the Import field is populated.

**An import update type dropdown is empty when creating a district or school record**

* Import update types must exist before they can be assigned. Open the Import Update Types management area and confirm that at least one update type is defined for the relevant import type.

**Cannot delete an import type**

* Ensure your account has the Import Types Delete permission.
* Check whether any import update types still reference this import type. Delete or reassign those update types first.


---

# 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://nimble.docs.otised.com/guides/data-import-system.md?ask=<question>
```

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.