Importer

Importing to a Site – Preliminary Steps

Click the Site Manager icon under the Admin Tools

(1) You will see in the left pane the name of your school district, for example "Demo School District" Click the site to select it and highlight it. This will be the site or district you are wanting to run the import file from.

There are two different types of imports:

A. Selecting a site and then importing that data into the single site. For example if you just want to update a single sites staff in "Demo Elementary School" you might want to run that import file on that specific site.

B. Selecting a site (has to be a district level site) to import your data and update all the staff in the sibling sites. In this example you would select the "Demo School District" in order to run your import file to update all the staff in the demo schools listed under the district site.

(2) Once you selected the appropriate site click the "Import" button

Starting the Import

NOTE: In this tutorial, we explain how to import students to several schools in a district at once. In other words, we will perform a district-wide import. Study the name of the site as displayed in the right-hand side of the window to make sure you have selected a school district, rather than one of its schools.

Click the Manage Templates icon.

Please note that the Import Manager tool has been started.

Using the Import Wizard to Define a Template

Click the New Template icon to start the Import Wizard. The Import Wizard allows to define a template, which is required for every import.

1. Click Browse….

2. Select the Sample File (aka Preview Data File) that will be used to define the template.

3. Click Next.

A Sample File is displayed in a pop-up window:

You may put together a Sample File simply by extracting a few records from the import file.

NOTE: The first of the five rows is the header row. The header row is recommended, but it is optional in both the Sample File and the Import File (which will be discussed later).

The role should be one of the following: S (student), A (administrator), T (teacher), P (principal). In this Sample File, there are people of all four roles. In general, the Sample File (just as the Import File) may contain just students, or just teachers, or just teachers and principals, or any other subset of the four roles.

Pay attention to the message that may be displayed by your browser. At this point, you may be required to allow pop-ups in your browser.

Please have another look at the Sample File pop-up window:

Please note that Field 1 is the role, Field 2 the member's unique id, Field 3 the school id, Field 4 the member's first name etc. These implied mappings will be needed later.

It is not the actual fields, but merely the type and order of fields in the Sample File, that is relevant to the import. The field values may, but do not need to be accurate in the Sample File. All the field values must, however, be accurate in the Import File.

TIP: You will later need the IDs of the schools to which you want to import people in the Import File. The ID of a school can be seen by clicking the school’s name in order to select it.

The second step of the Import Wizard becomes available after you click Next:

1. Type in the name of the template in the Template name input box.

NOTE: The template name may, but does not need to be, identical to the Sample File name.

2. Check the Has header row checkbox.

NOTE: The Import File used in this tutorial does have a header row (just as the Sample File). Whenever the Import File has a header row, check this checkbox. Please remember that header rows are optional. They are, however recommended, in both sample files and import files.

3. Select Field 3 using the Import Side ID drop-down.

NOTE: Remember that Field 3 is the school_id. This will instruct the importer to import a student to the school whose ID is the value stored in the third field of the respective student data record (row). In this example, we configure a template to be used for imports to an entire school district, since we selected a district rather than a school. Had we initially selected a school, rather than a school district, we would have used the Import Site ID drop-down to choose All data belong to same parent site.

WARNING: It is necessary to provide an Import Site ID when you start the importer from a school district. If you don’t, the members (teachers, students, etc.) will be imported to the school district, rather than to the schools that belong to it.

4. Click on the Expand icon beside Members.

Scroll down.

WARNING: To define the template you must map the field numbers to the respective field names by using the drop-downs provided for this purpose.

Please note that the mapping you must define is that displayed by the Sample File window. Thus, for example, select Field 2 for the member's Unique ID, Field 4 for the member's First name, etc. All fields in red font are mandatory. They are required in the import file (and in the sample file) and must be all matched. The Privileges field refers to the role of each member i.e. student (S), teacher (T), principal (P) administrator (A).

NOTE: You may ignore for now the Overwrite checkboxes. These checkboxes will be discussed in the next section.

Click on Import Manager in the navigation bar.

Using the Overwrite Checkboxes

WARNING: The tutorial will be continued in the next section.

This section discusses the two types of imports. It may be skipped and referred to later.

There are two types of imports:

1. Synchronous Imports

1. All previous data is removed and replaced (i.e. overwritten) with the import file data.

2. All members in the import file are added to their respective site.

3. Any member that is not in the import file is removed.

WARNING: The Import File should include all relevant members. In the case of a district-wide import, the Import File should include all the members of all the schools.

2. Non-Synchronous Imports

Existing members are never removed.

All new members present in the import file are added.

Existing members’ data may or may not be updated, subject to the Overwrite checkboxes’ user-determined status (checked or unchecked).

NOTE: Members are identified by their Unique ID, which never changes. Based on this field, the importer knows whether a member is new or not.

The Overwrite checkboxes should be checked if

1. The imports based on the template will be non-synchronous ones.

2. In relation to the respective field, members already stored against a site before the import should have their data replaced (i.e. overwritten) with import data. The overwrite takes effect whenever the field’s at-site data and import data are different.

The Overwrite checkboxes should not be checked if

1. The imports based on the template will be non-synchronous ones.

2. In relation to the respective field, members already stored against a site before the import should never have their data replaced (i.e. overwritten) with the import data.

NOTE: In the case of a synchronous import, the checkboxes’ checked or unchecked status is irrelevant.

Uploading the Import File and Linking the Template to It

WARNING: The tutorial is now continued.

1. Type the Import File name in the File name text input box.

2. Select the template using the|Template drop-down.

3. Click the Synchronise checkboxes as shown in the above image.

4. Click Link template.

Performing the Import

Click [Start import].

Wait until the import is completed and a dialog window pops up.

Click OK in the dialog window.

If the import was successful, you will see a green status for every Import File record (row of data) that has been imported successfully:

If the Status codes are displayed against a background that is not green, click the magnifier to view the names of the error and/or warning codes.

Troubleshooting Imports

A few things to be aware of or to check in case the import fails:

1. Your import file may not be a proper CSV (Comma Separated Values) file. Note that the last field in each row is not followed by a comma.

2. You may have indicated that the Import File doesn’t have a header row even though it has one.

3. You may have selected a school and indicated one of the fields to be the Import Site ID}}. This is incorrect. When you import data to one single school, select the school in the Site Manager, then select All data belong to same parent site using the Import Site ID drop-down. Incidentally, when you import data to one single school, the import file does not need to include the school id.

4. When you import data to several schools in a district, select the district in the Site Manager and indicate the school id field in the import file using the Import Site ID drop-down. A serious mistake (one which will not be flagged by the Importer as an error) consists in selecting a district in the Site Manager and then indicating All data belong to the same parent site. This mistake results in school members being added to the district, rather than to their respective schools.

5. Exercise caution when synchronous imports are performed since they start by wiping out all the members. The schools are then repopulated with only the members listed in the import file. Incomplete import files result in (potentially severe) loss of data. The Site Manager deactivates members not supplied in the import file. Data recovery by reactivating erroneously deactivated members can be pain staking and time consuming.

6. Do not perform district-wide synchronous imports unless you import data for all the schools in the district. If you only import data for some of the schools, the remaining schools will be depopulated.

Importing Elementary School Members to Classes

The import example described in the Using the Import Wizard to Define a Template section is related to elementary schools. Once imported to their respective homerooms, students and teachers may populate the classes associated to the homeroom by using the School Manager's Homerooms tab. You may want to refer to the Homerooms Tab chapter of the School Manager article. By clicking the Apply Now button all the imported students are assigned to the classes associated with the homeroom. As you may remember, classes are associated with a homeroom when the homeroom is created.

NOTE: Unlike courses and classes, homerooms can only be defined using the School Manager. Courses and classes may be defined using the Site Manager, too, but it is recommended to set them up using the School Manager.

Importing Middle School Students to Classes

Unlike elementary school students, middle school students that are assigned to a homeroom may not take all exactly the same classes. To import middle school students, you may use import files similar to those used for elementary schools and, following the import, move some of the students to alternate classes, or remove them from certain classes altogether, as explained in the Students Tab chapter of the School Manager article. This may be, however, impractical.

A more direct way to handle middle schools is to import the students to grades, subjects, courses and classes in addition to homerooms. The import file is therefore more complex and it is also longer. For any given student and class, there may be up to three records (lines), corresponding to the three school year terms. A line is required for each term. In particular, optional courses may need less than three records per student and per class.

Assume that subject IDs are defined by two-digit numbers, e.g. 18, course IDs hyphen together subject IDs and grades, e.g. 18-7, while class IDs append letters to the course IDs e.g. 18-7A, 18-7B etc. A typical middle school student import template file or import file snippet is shown in the two next images. The students are imported in this example to only one school, hence there is no school id field. Due to the large number of fields, the first seven and the next seven fields are listed separately:

The mapping of the fields during the template set-up time using the Important Wizard is shown in the three images below:

Assuming the import file's complete accuracy, no further manipulation of the students will be required after the import, at least until such a time that certain students need to be moved to different classes or new students need to be added.

NOTE: Import files for teachers are similar. The Homeroom and Grade fields are however not present in the import file, and of course, they are not mapped in the Import Wizard.

Importing Members to Sites and Groups

Members can be imported “in one shot” to both sites and groups. To do so:

1. The import file needs two additional fields, group id and group name.

2. The Import Wizard’s Expand icon beside Groups is expanded along with that of Members.

3. The two new fields, group id and group name, are mapped.

As seen in the tutorial, the Sample File fields are numbered in the pop-up window:

The Groups mappings are shown below:

2. The Import Wizard is started. You will need first to load the Sample File again.

1. Click Browse….

2. Select the Sample File (aka Preview Data File) that will be used to define the template.

3. Click Next.

Adjust the template as necessary. This is explained in the Using the Import Wizard to Define a Template section.

3. Upload the Import File and link the template to it. This is explained in the Uploading the Import File and Linking the Template to It section.

You may now import data, as explained in the Performing the Import section.

Repeated Imports

Once a template is in place and linked to an Import File, only two steps are required to perform each additional import that is consistent with the template:

1. The Import File uploading

2. The import

NOTE: Each of the successive import files should have the name that was specified when the template and the initial Import File were linked. Moreover, each import file must have the same field structure, which is that defined by the template.