Skip to content
English
Sign in
Contact us
  • There are no suggestions because the search field is empty.

Imported Students – Troubleshooting & Triage

When to use this article

Use this article when an Imported Students file fails or partially succeeds in VisualZen (VZ). This guide applies whether the file was uploaded manually through the Control Panel or processed automatically through the Import Engine (.exe), WSDL, or SFTP.

If your student records are not appearing after an import, this article will help you determine whether the issue lies with the data file, the automation process, or an environmental factor such as a timeout or connection interruption.

Learning Objective

By the end of this article, you should be able to:

  • Identify whether an import issue is related to the file, automation setup, or system connection.

  • Locate and interpret details in Data Transfer Logs.

  • Validate headers, required fields, and file structure.

  • Escalate securely to VZ Support with the correct information and process.

Step-by-Step Troubleshooting Guide

Step 1: Check Data Transfer Logs

  1. In the VZ Control Panel, go to Data Transfer Logs (top navigation).

  2. Review the most recent entry for the Imported Students import:

    • Confirm date/time, source (Manual, Import Engine, WSDL, or SFTP), rows imported successfully, and failed count.

  3. If no record appears, verify that:

    • Your automation job (scheduler, WSDL call, or SFTP upload) executed as planned.

    • The file was sent to the correct environment (Pre-Production vs. Production).

Step 2: Determine the Import Path

  • Manual Import:
    If the import was uploaded directly through the Control Panel, proceed to file validation.

  • Automated Import (Import Engine, WSDL, or SFTP):
    Obtain the exact file that was transferred and attempt a manual import test.

    • If the manual import succeeds, the problem is within the automation layer (credentials, timeout, network, or permissions).

    • If the manual import fails, the issue is in the data file itself.

Step 3: Validate the Data File

Check Expected Behavior / Resolution
File Type VZ accepts .csv, .xlsx, and .txt formats.
Headers All mapped headers configured in VZ must exist in the file. Missing headers cause a full import failure. Extra columns are allowed but ignored.
Required Fields per Row Each row should include: First Name, Last Name, SISID, Date of Birth, and Email Address. Missing values in these fields can prevent a student record from importing.
Row/Column Alignment Each row must have the same number of columns as the header. Errors like:
The number of columns (71) in row 6 does not equal the number of columns (70) in the header row indicate mismatched or malformed data.
Delimiter & Quoting Ensure consistent delimiters (commas for .csv, tabs for .txt). Fields with commas or line breaks should be wrapped in quotes.
Extra Blank Rows Delete any empty rows at the end of the file before uploading.
File Size / Timeout Very large files can time out or fail during automated runs. Consider splitting the file or extending the timeout setting on the client or server side.

Step 4: Validate Automation Configuration

Import Engine (.exe)

  • Confirm the Settings.xml file contains:

    • Correct email for the service account (must have Executes Export Engine permission).

    • Updated password (after first login reset).

    • File path and token value.

  • Ensure the .exe and Settings.xml files are stored in the same directory.

  • The machine must be Windows-based with .NET 4.6 or higher.

  • If scheduled, confirm the task runs under valid credentials.

WSDL

  • Confirm the correct WSDL URL, email/password, and token are in use:

     
    https://secure1.vzorientation.com/{schoolname}/webservices/exportengine.asmx?WSDL

  • Review the result codes:

    Code Message Meaning
    1 Invalid Authentication Incorrect credentials or permission missing.
    2 Invalid Token Token mismatch between file and environment.
    3 Partial Success File or row-level data problem.
    0 Success Import completed successfully.

SFTP

  • Confirm SFTP credentials are valid and the file was uploaded to the expected directory.

  • Verify file name and timestamp match the scheduled import.

  • If an import fails:

    • Confirm the file structure matches a known working template.

    • Check for truncated uploads or timeout limits.

Step 5: Manual Verification & Retest

  1. Correct any identified file issues.

  2. Manually import the updated file through the Control Panel.

  3. Confirm the results screen displays:

    • “X rows imported successfully.”

    • Any failed rows include an error message with the reason.

  4. Compare the number of imported students in Data Transfer Logs with the data team’s expected count.

Step 6: Secure Escalation

If the import continues to fail after validation:

  1. Upload the file securely to:
    🔒 https://secure.vzorientation.com/vzuploader/default.aspx

  2. Send an email to support@visualzen.com including:

    • A summary of the issue (manual or automated import).

    • The results of your manual test (success or failure).

    • Import timestamps, environment (Pre-Production or Production), and file size.

    • Confirmation that the file was uploaded to the secure portal.

⚠️ Important: Do not send student data via email. VZ does not receive automatic alerts for uploaded files—please notify Support once the file is uploaded.

Common Error Messages

Error Message Meaning Resolution
Invalid Authentication Incorrect credentials or missing permissions. Update credentials or verify permissions.
Invalid Token Token value in Settings.xml or WSDL call does not match environment. Use the correct token from configuration.
Missing mapped header(s) One or more expected headers are missing from the file. Add the missing mapped headers exactly as configured.
The number of columns (X) in row N does not equal the number of columns (Y) in the header row Row misalignment (extra delimiter, missing value, or unclosed quote). Correct row formatting or re-export a clean file.
Partial Success Some rows imported, others failed. Review Data Transfer Logs for specific errors.
Timeout / Connection Error The file is too large or connection was interrupted. Split the file or increase timeout threshold.

Check Your Work

  • ✅ Data Transfer Logs show “0 failed rows.”

  • ✅ Imported row count matches the original file count.

  • ✅ Spot-check several student records in VZ to confirm import success.

  • ✅ Next automation run completes without errors.