Class Import Converter

Contents

To view these instructions in a PDF file, click here.

Getting Started

Adding class schedule information in Destiny Resource Manager or DestinyTextbook Manager, then assigning resources, students, and teachers to them, helps you:

  • Ensure every student has the resources they need on day one.
  • Discover shortages and surpluses at each school.
  • Improve the efficiency and accuracy of resource acquisitions and transfers.
  • Prepare accurate reports.

Class schedule information includes:

  • The classes being held
  • The teacher for each class
  • The students who are enrolled in each class

Class information can be manually entered in Destiny. However, Destiny also accepts class schedule data in an XML (extensible markup language) file format. You can upload data from your Student Information System (SIS) that includes classes and their sections, and, optionally, assign teachers, resources, and patrons to the classes. Upload data for one school or the entire district.

The Class Import Converter (CIC) accepts a CSV file and generates an XML file that you can then import into Destiny. The Converter quickly processes large CSV files, which makes it efficient for entering class schedule information.

Before You Begin

A successful XML upload from the Class Import Converter requires that certain data currently exists in Destiny. Before you use the CIC, Follett recommends you update your patron records manually or using the Patron Import Converter and to verify the following:

  • If you will assign teachers or students to class sections, teacher and student records must be in Destiny and in the CSV file, along with the District ID or barcode number.
  • To assign a teacher to a section, the teacher's patron record must be associated with the site where the section is taught. If the site association does not exist at the time of the Class Schedules XML upload, a link is available to edit the teacher's patron record and add the required site association.
  • Each teacher’s Destiny patron record must have the Currently Teaching checkbox selected.
    Note: Ensure teachers are recognized as teachers by setting IsTeaching to true in the Patron Import Converter.
  • Students must be associated with the same site as their classes because the Class Schedules upload cannot transfer patrons between sites.

Next, follow the steps in this document to use the CIC to upload class schedule data to Destiny. The CIC CSV file should include information for current classes and sections. To forecast future textbook needs, include information for future classes and sections.

Important:

  • By default, the upload deletes pre-existing sections, including those with current checkouts. Any checkouts to a deleted section are converted to patron checkouts. This lets you delete last year's sections while retaining the classes and their resource associations. To update or add only a few sections, you can choose to retain sections not in the XML file.
  • All existing classes are always retained.
  • All existing default resource associations are retained. Default resources are those assigned to classes, not sections.

If you will upload Resource Associations to assign resources to your classes and sections, do this after the class schedule data is uploaded to Destiny. Resource description records must already exist in Destiny.

If you are updating existing class schedules and have existing resource associations:

  • Any class-resource associations are retained.
  • Any section-resource associations for deleted sections are deleted.
  • Any section-resource associations for updated sections are retained.

For example, if you update section information in the middle of a term, the resources already associated with the section remain. If the upload contains no information for a section, and you remove sections not in the update file – thus deleting them – the upload also deletes any resource associations for that section. It does not, however, delete any resource records.

CSV File Requirements

In order for Destiny to accept class schedule data, you must export it to a CSV file from your SIS and then use the CIC to convert it to an XML file. Contact your SIS vendor for information about exporting class schedule data to a CSV data file.

Important: It is strongly recommended that all CSV data fields be surrounded by quotation characters to ensure the data with embedded commas can be processed.

Example: For a class called "Dollars, Cents, and Sensibilities" to import correctly, surround the data with quotes.

Change this formatting: 1,Dollars, Cents, and Sensibilities,3,101

To this formatting: "1", "Dollars, Cents, and Sensibilities", "3", "101"

Note that some systems may list quotations as a text delimiter option.

Example CSV file

While there is some flexibility in the format of the CSV file, the following table outlines the optimal structure:

Field Description Required Comments and Rules

1

Site ID

Yes

 Make sure the Site ID values are mapped correctly to your Site Short Names.

2

Class name

Yes

 Example: Algebra I

3

Catalog designation

Yes

 The unique identifier for a Class.
Example: MAT 101

4

Section ID

Yes

In combination with the loan period (Starts and Ends dates, fields 10 and 11), the unique identifier for a class section at a site.

Important: If two or more sections have the same Section ID but different loan periods, Destiny considers them different sections. This lets you upload future school terms while preserving information for current terms.

5

Teacher number: Barcode or District ID

No

If included, ensure the IsTeaching field in the teacher patron updates is set with a value of “true” or the Is Currently Teaching checkbox is selected in the teacher’s patron record in Destiny.

If not included, any existing assigned teacher is removed unless they have checkouts of the associated resources. Ensure the CSV file is set correctly for either the Barcode or District ID. Patron records must already exist in Destiny.

6

Period the class section meets

Yes

 School day period. Must be a number between 1 and 99, inclusive.

7

Student number: Barcode or District ID

No

If not included, any existing assigned students are removed unless they have checkouts of the associated textbooks. Ensure the CSV file is set correctly for either the Barcode or District ID. Patron records must already exist in Destiny.

8

Department

No

If not included – or included but not mapped in the properties file – set to the default department in the Converter's properties file. If there is no default, the department is set to "Undefined" in Destiny, where you can manually change it. If an incoming department does not exist in Destiny, the department is added.

9

Meets

No

The days of the week the section meets. Acceptable values are: SU, M, TU, W, TH, F, SA. Multiple days must be separated by commas. If not included in the CSV file, the default values from the Converter's properties file are used.

10

Starts

Both required if entered

The default format is mm/dd/yyyy. You can configure a different format in the properties file. If not included, Destiny uses the start and end dates you specify when you upload the file.

11

Ends

12

Loan period description

No

If you are creating loan periods by including new Starts/Ends date ranges, you can supply a name for each one "Added During Upload XXXX."
Not used for matching.

Important: The rows in the CSV file must be sorted in the following order.

CSV File Sorting Order
First by Site ID
Then by Class name (ClassName)
Then by Catalog designation (CatalogDesignation or Class ID)
Finally by Class section (Section ID)

Downloading the Class Import Converter

To download the Converter:

  1. Log in to Destiny.
  2. Do one of the following:
    If you are a...Then...
    Destiny Administrator
    1. Select Setup > District Options sub-tab.
    2. At the bottom of the screen, click Download.
    3. In the pop-up, select Open to open the zipped list of downloadable files.
    District user with the Manage Resources for the District permission
    1. Based on how Destiny is set up at your district, do one of the following:
      • Select Applications. > District Back Office.
      • From the top-right corner, click District.
    2. Select Admin > Download Tools.
    3. Click Download for the Class Import Converter.

    Class Import Converter Download button circled.

Creating a Working Folder

Create a working folder on your Destiny application server or local Windows computer with all the necessary files:

  1. Rename classimport.properties.sample to classimport.properties.
  2. Copy your CSV file to the working folder.

Ensure you keep the following files in the FSC-Destiny\fsc\bin folder from the unzipped CIC utility download:

  • ClassImportConverter.exe
  • ClassImportConverter.l4j.ini.sample
  • ClassImport.properties.sample

Note: If you are a Follett Destiny Cloud customer or not on your Destiny server, you can log in to Destiny as a Destiny Administrator to download the files.

Configuring the Class Import Converter

The Class Import Converter is controlled by the settings in its properties file. By default, the name of this file is classimport.properties. From your working folder, open classimport.properties in any text editor. The file lets you configure the Converter for your input data and consists of several sections:

Teacher and Student Identification

#---------------------------------------------------------
# Indicate whether the barcode (true) or DistrictID (false)
# should be the identifier inserted into the output XML
#---------------------------------------------------------

useBarcodeAsTeacherId=false
useBarcodeAsStudentId=false

You can identify the teacher of a class section either by their District ID or their Barcode Number. If your CSV file contains the teacher’s Barcode Number, set useBarcodeAsTeacherId to true. If the file contains the teacher's District ID, leave it at false. You can also identify students enrolled in a class section by either their District ID or their Barcode Number. If your CSV file contains the student’s Barcode Number, set useBarcodeAsStudentId to true. If the file contains the student's District ID, leave it at false.

Site ID to Short Site Name Mapping

#-----------------------------------------------------------------
# SiteID to Destiny short site name mapping -- Add entries
# for each site to be mapped.
# Example: siteid_555=MySite
#-----------------------------------------------------------------

#siteID_default=Undefined

Note: If you leave this section as is, you will not have to map the value in the CSV file to the value in Destiny. It will take the value in the site id field in the CSV file. Ensure the site short name or building ID (Alias) is in Destiny.

Department ID to Department Name Mapping

#-----------------------------------------------------------------
# Department ID to department name mapping -- Add entries
# for each department id to be mapped to a department name.
# Example: dept_1=English
#-----------------------------------------------------------------
dept_default=

The incoming CSV data may or may not have department information. The entries in this section of the properties file allow the mapping of department identifiers to ones that are used in Destiny. Department names are not required in Destiny, and an empty value for dept_default is acceptable.

When the CSV data is imported, the department field in the CSV data can be converted to a Destiny Department Name value. As a CSV row is processed, the Converter looks up the department in the properties file. If there isn’t an entry for a department, the value of dept_default is used. If there is no value for dept_default, the class appears under Other in the Department list in Destiny.

In the example above, if a CSV row contains a department value of 1, the Department Name is set to English.

Note: Because the Converter wraps the Department Name in an XML CDATA entity, there is no need for you to add the <![CDATA[]] wrapper to ensure properly-formed XML.

Default Value for Days of Week that a Session Meets

#-----------------------------------------------------------------
#Default value for "meets" when one is not provided
#-----------------------------------------------------------------
meets_days_of_week_default=M,Tu,W,Th,F

Each class section in the Class Schedule XML requires an element that indicates the days of the week that the section meets. If the CSV file does not contain this information, the Converter uses the default value defined here. For a successful upload of the XML file, the default value cannot be empty.

Advanced Configuration in Properties File

The Converter allows flexible formatting of the input and output data fields to accommodate most field data. It is possible to "string together" (concatenate) multiple fields, and convert numerical or date/time information from one format to another. This flexibility introduces a little complexity.

Field Mapping

This section assigns CSV fields to internal fields that will be used to create the XML output file.

This section does not require any changes unless you have special rules in place.

#-----------------------------------------------------------------
# CSV fields to Destiny field mapping -- Associates XML fields
# that Destiny uses with incoming CSV fields.
#-----------------------------------------------------------------
field_siteID={1}
field_className={2}
field_classDesignation={3}
field_section={4}
field_teacherNumber={5}
field_period={6}
field_studentNumber={7}
field_department={8}
field_meets={9}
field_starts={10}
field_ends={11}

# LoanPeriodName is optional and rare
#field_loanPeriodName={12}

Data Type Definitions

The final section defines the data type of the CSV input fields. Unless an output field uses a date or number formatter, it is unnecessary to make any changes in this section.

#-----------------------------------------------------------------
# CSV input fields type mapping -- Defines the type and
# format of the data in a given CSV field.
#-----------------------------------------------------------------
field_type_1=string
field_type_2=string
field_type_3=string
field_type_4=string
field_type_5=string
field_type_6=string
field_type_7=string
field_type_8=string
field_type_9=string
field_type_10=string
field_type_11=string

# LoanPeriodName is optional and rare
#field_type_12=string

Examples:

A

Given this CSV row: "001","1","2","20120115"

Results in the fields being set to these values:

{1} = 001

{2} = 1

{3} = 2

{4} = 20220115

After configuring the mapping, concatenation, and formatting, the output values would change:

Mapping in the Properties File Resultant Output

field_test={2}

1

field_test={2}{1}

1001

field_test=IBE{2}-{1}

IBE1-001

field_test={3,number,00000000}

00000002

field_test=P{3,number,00000000}

P00000002

field_test={4,date,MM/dd/yyyy}

01/15/2022

If you use the date or number formatters, you must make entries in the section that defines the field types and formats used in the input CSV file.

In the example above, the entries would look like this:

field_type_1=string
field_type_2=string
field_type_3=number,0;0
field_type_4=date,yyyyMMdd

B

For another example, some districts construct the teacherNumber by appending the Site ID:

field_teacherNumber={5}{1}

C

Here is an example of taking the student number, right-justifying it, and adding a P at the beginning to create a Destiny patron barcode. 1 becomes P0000001:

field_studentNumber=P{7,number,0000000}
field_type_7=number,0;0

Following are links to additional information about the formatting characters that can be used for dates and numbers:

Date: http://download.oracle.com/javase/1.5.0/docs/api/java/text/SimpleDateFormat.html

Number: http://download.oracle.com/javase/1.5.0/docs/api/java/text/DecimalFormat.html

Running the Class Import Converter

Once you have copied ClassImportConverter.exe, ClassImportConverter.l4j.ini.sample, and classimport.properties.sample to your working folder, renamed classimport.properties.sample to classimport.properties, and edited the properties file as needed, you can run the Class Import Converter.

Note: The Class Import Converter utility does NOT have a graphical user interface like the Patron Import or Resource Import Converters do. It is only run using DOS command lines.
  1. Open a command prompt, and change to your working directory.
  2. Enter the following command with the parameters in the correct order:

    ClassImportConverter inputFile outputFile propertyFile fileEncoding

    Example:

    C:\FSC-Destiny\fsc\bin> classimportconverter newclassinfo.csv newclassinfo.xml classimport.properties UTF-16
    Parameter nameRequiredDescription

    inputFile

    		YesCSV input file

    outputFile

    		Yes XML input file

    propertyFile

    		Yes Properties file, default provided is classimport.properties

    fileEncoding

    		NoSpecifies the character encoding used to read the input file.
    For some Microsoft SQL Server csv export files, UTF-16 may be required.
    Defaults to windows-1252 (Windows Latin-1).
  3. Note the name and location of the log file, named <outputFileName>.xml.log, that the command window displays.
  4. Review the log file for any exceptions.

Possible Errors

If you run the Converter and there is no Java™ Virtual Machine available, the Converter launches a browser window that lets you download and install the required JVM.

Data Ordering Issues were Detected

This message indicates that the incoming CSV file is not sorted properly.
Before running the Converter, you must ensure that the first four fields are sorted correctly.
The Converter can sort the CSV file for you:

  1. At a command prompt, enter the following command, using the correct file names for your input and output files:
    ClassImportConverter unsorted.csv sorted.csv /s
  2. After sorting, run the Converter using the newly sorted CSV file.

Remember, this sort option is a convenience feature and should not replace the requirement that the input CSV file be ordered by the first four fields. There is no assurance that you will have the required memory to sort very large CSV files.

Out of Memory Error

By default, the Converter uses the default amount of memory set up for the JVM. If you encounter this error when sorting your CSV file, perform the following steps:

  1. Rename ClassImportConverter.l4j.ini.sample to ClassImportconverter.l4j.ini. This enables the Converter to use more RAM than the default amount allocated for the JVM.
  2. If necessary, edit ClassImportConverter.l4j.ini to modify the maximum memory to use.
    Note: This is typically only done by large districts because the file size is large.
  3. Run the Converter again.

Depending on the amount of memory available, it should be possible to sort all but the largest input files.

Automating the Conversion

To automatically convert your class data on a regular basis, you can use the Windows Scheduled Tasks and a batch file.

Initially, you'll need to configure your batch file. The Converter can return error codes as ErrorLevel from the command line utility. You can test for these values in a batch file, and then the batch file can take appropriate action based on the value returned.

Error Codes

ERR_NONE = 0
ERR_NO_INPUT_FILE = 1
ERR_FILE_NOT_FOUND = 2
ERR_IO_READ = 3
ERR_IO_WRITE = 4
ERR_SORTING = 6
ERR_XML_PARSE = 7
ERR_INVALID_CHARACTERS_IN_XML = 8

Batch File Example

As an example, the following batch file incorporates the error codes to detect problems with the conversion and skips the upload of a faulty XML file.

-----------------------------------------------------------------

rem Execute the conversion utility
ClassImportConverter input.csv output.xml classimport.properties
rem Check the status of the conversion and continue if no errors
IF ERRORLEVEL 8 GOTO InvalidXMLCharacters
IF ERRORLEVEL 7 GOTO ParseError
IF ERRORLEVEL 6 GOTO SortError
IF ERRORLEVEL 4 GOTO WriteError
IF ERRORLEVEL 3 GOTO ReadError
IF ERRORLEVEL 2 GOTO FileNotFoundError
IF ERRORLEVEL 1 GOTO NoInputFileError

rem Otherwise -- success
rem continue processing and then exit
goto END

:InvalidXMLCharacters
echo Invalid characters were found in the output XML file
goto END

:ParseError
echo Unable to parse the output XML file
goto END

:SortError
echo A processing error occurred during the file sort phase
goto END

:WriteError
echo Unable to write output file to disk
goto END

:ReadError
echo Unable to read file from disk goto END

:FileNotFoundError
echo CSV input file was not found
goto END

:NoInputFileError
echo No CSV file was specified to convert
goto END

:END

-----------------------------------------------------------------

Uploading XML File to Destiny

You can upload the final XML file to Destiny in either of two ways:

In Destiny Back Office

  1. Log in to Destiny as a district user with the Manage Resources for the District permission or a site user with the Update class information permission.
  2. Select Admin > Update Classes > Upload Changes sub-tab.
  3. From Sections that are not included in the update file should be, select to either remove or retain existing sections not in the XML file.
  4. From the If section start and end dates are missing drop-down, select the loan period to use if dates are missing from the XML file.
  5. Click Choose File (or Browse, depending on your browser) to find and select your XML file.
  6. Click Update.
  7. When the Job Manager opens, review the job summary for any errors or exceptions.

Through a Command Line

  1. Log in to the Destiny server.
  2. Find the updateclasses.properties.sample file in the FSC-Destiny\fsc\bin folder.
  3. If you have not yet done so, rename updateclasses.properties.sample to updateclasses.properties.
  4. Open updateclasses.properties.
  5. Enter the Destiny username and password for a user with the permission to upload class schedules.

    The following users can upload class schedules:

    • Destiny Administrator
    • District textbooks manager
    • Site user granted the Update class information permission
  6. Save and close the file.
  7. Open a command prompt.
  8. Change to your working folder.
  9. Enter the command in the correct order:

    UpdateClasses configurationFile inputFileName contextName removeSections startDate endDate

    Example: C:\FSC-Destiny\fsc\bin> updateclasses updateclasses.properties classinfo.xml district_123 no 8/15/2021 6/15/2022
    Parameter NameRequiredDescription
    configurationFileYesProperties file name
    inputFileNameYesXML file name
    contextName Yes - if a member of a consortiumDatabase/Context name of the consortium member. To find the context name, log in as Super Administrator, open Setup and then the "Edit member" page.
    removeSections YesWhether Destiny is to remove existing sections not included in the XML update file. Acceptable values are yes or no.
    startDateNo The default Start Date for sections without a Start Date defined in the XML file. In mm/dd/yyyy format.
    endDateNo The default End Date for sections without an End Date defined in the XML file. In mm/dd/yyyy format.
  10. When the upload completes, open the Job Manager, and review the job summary for any exceptions.

Once you have successfully created an XML output file, you can continue to run the Class Import Converter manually, automatically as a Windows Scheduled Task, or by using the Scheduled Classes Update (Resource Manager customers only) feature. To schedule a nightly update, save the class schedule CSV file in a folder on the Destiny application server, or save the CSV file to an SFTP server (Follett Destiny Cloud customers).