Troubleshooting Failed Imports

When an import does not complete successfully, review the Data Source configuration, source connection, and import results to identify the cause.

Import Stops Before Processing Begins

SIS Connection Failure

For PowerSchool SIS and eSchoolPlus Data Sources, the system performs a connectivity check before processing records.

If the SIS connection is unavailable, the import stops immediately and no records are processed.

Resolution

1. Verify that the SIS Connection is configured correctly.

2. Test the SIS Connection from the SIS configuration page.

3. Resolve any connection issues.

4. Run the import again.

Imported Fields Are Missing Expected Source Properties

For PowerSchool SIS Data Sources, source-property lists and Extension Table selections depend on Metadata Sync.

If expected fields are missing, the cached schema information may be outdated.

Resolution

1. Open the Data Source.

2. Select Sync & Validate.

3. Wait for synchronization to complete.

4. Reopen the affected Field Mapping.

Run a new Metadata Sync when:

• Extension Tables have been added to PowerSchool SIS.

• The SIS Connection has changed.

• Expected source fields do not appear.

• Validation errors reference stale tables or fields.

Validation Errors Prevent Configuration Completion

Field-level validation and holistic validation identify configuration problems.

Examples include:

• Missing required values

• Missing source properties

• Removed target form fields

• Missing Integration Mapping Lists

• Missing Script functions

Resolution

1. Review error badges on Source Records, Subrecords, and Field Mappings.

2. Open the affected configuration item.

3. Correct the reported issue.

4. Save the configuration.

The system automatically reruns validation after each save.

Unable to Find Invalid Mappings

When a Data Source contains many mappings, invalid items can be difficult to locate.

Resolution

1. Enable Only show invalid mappings.

2. Review the filtered list.

3. Correct each reported issue.

4. Disable the filter to return to the complete mapping list.

When no issues exist, the page displays:

All field mappings are valid.

Records Were Not Imported

A student record may be skipped during processing.

Records are skipped when:

• The primary key is invalid.

• The primary key is missing.

• The matching Roster record is already in a Started status.

• The matching Roster record is already in a Submitted status.

• The matching Roster record is already in an On Hold status.

Resolution

1. Review the import results.

2. Verify that the primary key is present and valid.

3. Check the status of the matching Roster record.

4. Run the import again after correcting the issue.

Unexpectedly Small Student Population

Import Filters determine which students are included before any processing occurs.

A restrictive filter configuration can significantly reduce the imported population.

Resolution

1. Review configured Import Filters.

2. Verify:

   • Student Status filters

   • School ID filters

   • Grade Level filters

   • Student Number filters

3. Confirm that the intended students satisfy all enabled filters.

Remember:

• Import Filters are subtractive.

• All enabled filters must be satisfied.

• Student Number filtering takes priority over other filters.

Expected Records Are Missing

Import Conditions determine which records are selected for each student.

A record can be excluded because:

• It does not satisfy configured Import Conditions.

• It is removed by automatic PowerSchool SIS exclusions.

For PowerSchool SIS Roster imports, the system automatically excludes:

Contacts

• Contacts without a last name

• Inactive contacts

• Deceased contacts

• Contacts with inactive relationships

• Contacts with expired relationship end dates

Relationships

• Inactive relationships

• Relationships with expired end dates

Contact Addresses

• Addresses with expired association end dates

Resolution

1. Review Import Conditions.

2. Verify that the expected record satisfies all configured conditions.

3. Verify that the record does not meet any automatic exclusion criteria.

Integration Mapping List Errors

If a selected Integration Mapping List no longer exists, the Field Mapping becomes invalid.

Validation displays the message:

The selected integration mapping list is no longer available.

Resolution

1. Open the affected Field Mapping.

2. Select a valid Integration Mapping List.

3. Save the mapping.

Script Function Errors

If a referenced Function Library function has been removed, the Field Mapping becomes invalid.

Validation displays the message:

The selected script function is no longer available.

Resolution

1. Open the affected Field Mapping.

2. Select a valid function.

3. Save the mapping.

Legacy Configuration Migration Fails

Migration may not complete successfully in the following situations.

SIS Connection Cannot Be Identified

Migration completes, but no SIS Connection is assigned.

Resolution

1. Edit the migrated Data Source.

2. Select the correct SIS Connection.

3. Save the Data Source.

SIS Sync Failure

Migration completes, but validation issues may appear because schema information could not be retrieved.

Resolution

1. Resolve the SIS Connection issue.

2. Run Sync & Validate.

3. Review and correct any remaining validation errors.

Unexpected Migration Error

Migration stops before completion.

The legacy configuration is not marked as migrated.

Resolution

Open the legacy configuration again to restart the migration process.

Review Import Errors

Regardless of the selected Error Handling Mode:

• Records with invalid primary keys are skipped.

• Skipped records are recorded in the import error report.

• Excluded fields are recorded in the import error report.

Review the import error report to identify records and fields that were not imported successfully.