Version 6.9.1
Last Update: 05/18/2022

Contents:

Overview

When a student submits a CCCApply (Standard or International) or CC Promise Grant application, their application responses are stored in the CCC Technology Center's submitted application database in two tables: submitted_application and submitted_question_response (for supplemental question responses). The submitted_application table contains the applicants' responses on their application and a number of fields from their user account at the time they submit.

The Download Client is a platform-neutral, command-line tool you use to download all students' application data for all three applications to a local computer, allowing you to import it into your college's SIS. After you unzip the Download Client, you will use a text or XML editor to set up a properties file and then edit two sample XML files (job and format definitions) that allow you to:

• configure which student application data to retrieve

• define the data format for the download file

Sample job and format definitions XML files are available for each CCCApply application (Standard/Noncredit, International, and CC Promise Grant) as a part of the Download Client package.

After configuring your properties and job and format definitions XML files you can run download jobs in your test environment and SIS to confirm the data is mapping and storing correctly in your SIS prior to downloading data from the production server. Download jobs can be set for both the application data and supplemental question responses.

Working with XML

Although working with computer languages can be daunting, you don't need to be an expert to work with the Download Client XML files, and you don't need any sophisticated tools. A simple text editor and a rudimentary understanding of XML hierarchy will be helpful.

If you are comfortable writing computer software, you can of course use the tools that best suit you. Otherwise, create your XML files using your operating system's built-in text editor. On Windows, the text editor is called Notepad, and on OS X, it is called TextEdit.

If you run your download and get the BOM error, you can take one of the following actions to remove it:

• Copy and paste your XML content into a plain text editor or some other suitable tool to remove the extra characters (the BOM), such at Notepad. You can save the file as ANSI to remove the BOM.

• Switch to an XML editor that allows you to save the content and remove the BOM, such as one of the following:

• XML Copy Editor

To remove the BOM, click on options from the Tools menu and de-select "Save UTF byte order mark". Save your file.

• Notepad ++

To remove the BOM, select "Encode in UTF-8 without BOM" from the Encoding menu. Save your file.

Download Client System Requirements

• A Virtual Machine dedicated for the Download Client installation

• Java 7 or higher of either the Java Runtime Environment (JRE) or Java Development Kit (JDK)

• The latest Download Client version (the latest version is available here (as a transfer-client.v.xxx.jar file): Download Client Jar File

Supported Versions

Troubleshooting 

If you experience issues downloading your application data after a major release, use the following steps to determine your Download Client version:

1. Type the following command at the ../transfer-client/ command prompt:  
   java -jar transfer-client.jar --version

2. If you have Download Client V5.4.0 installed, this will display:
   VERSION: 2016-03-08 12:35:19, 1.0-SNAPSHOT

3. If you have Download Client V5.3.0 installed, this will display:
   VERSION: 2015-10-16 16:00:27, 1.0-SNAPSHOT 2

4. If you have a Download Client version that is prior to V5.3.0, an error message displays. You can upgrade to the latest version of the Download Client jar file by obtaining the latest version here: Download Client Jar Files or contact your Implementation & Configuration Engineer representative at the CCCTC Enabling Services & Support.

CCCApply Download Client - Current Production Version

When new data fields are added to CCCApply in a scheduled release, they need to be manually added to each relevant Application-specific Format Definitions XML file (every CCCApply application has it's own Format Definition XML and Job File XML) AND you must update your Download Client with the corresponding, release-specific “transfer-client.v.xxx” Jar file.  A new 'transfer-client-jar" is created for each release that includes database changes.  

Unzipping, Installing, and Configuring the Download Client

The following steps outline a "quick-start" process for a first-time unzip and configuration of the Download Client.

• Detailed information about the underlying database information, as well as detailed XML and schema information, follows this quick-start section. Links to more detailed information are provided and noted where necessary.

• If you have already installed and used the Download Client, then you may want to skip some of these steps and/or go directly to the detailed information provided in the job and format file configuration and data field sections.
  
  

Download Client Installation Steps

1. Contact your CCCTC Implementation & Configuration Engineer (ICE) representative (Enabling Services & Support) to order your Download Client. The ICE representative will deliver the Download Client zip file to you via Dropbox or some other secure method that they will arrange with you.
   
   

2. Once you receive your Download Client zip file, download the file to your local computer and extract it into a local file directory of your choice.
   Once you extract your Download Client, it should look something like this, with the expanded files within the transfer-client root folder:
   
   
   

   Open

   

    

It is assumed that the FTT_HOME environment variable indicates the fully-qualified path to this directory, e.g. FTT_HOME=c:\downloads\transfer-client

3.  Change your college keystore password using the steps in this section. When you first receive the Download Client from the CCC Tech Center, a certificate is created for your college that controls which MIS code(s) you can access for downloads. The default password for this initial certificate is “password.” The CCC Tech Center recommends that you change this password using the following steps.

a. Navigate to the transfer-client\conf\ directory and create a backup of your current client.jks file.

b. At a command prompt, navigate to the transfer-client\conf directory and locate your college key alias by entering the following command at a command prompt (press the Enter key after you type the command): keytool -list -keystore client.jks  The output from running this command will be a list of keys contained in the keystore.

c. Locate your college key alias by looking at the key name at the beginning of the entry of type "PrivateKeyEntry". The college key alias will usually be in the format of "xxx.edu" where xxx is your college’s initials.

d. Update your college keystore password by entering the following command at the command prompt from the transfer-client\conf directory (press the Enter key after you type the command): keytool -storepasswd -keystore client.jks

e. When prompted to enter your current keystore password, enter your current password (the password = password for all first-time Download Clients). You’ll be prompted to enter your new keystore password, and then prompted to re-enter the new keystone password (press the Enter key after each entry).

f. Update your college key password to match the keystore password you just set in step 3e above by entering the following command at the command prompt from the transfer-client\conf directory (press the Enter key after you type the command): keytool -keypasswd -alias <key_alias> -keystore client.jks

g. When prompted to enter your current keystore password, enter they keystore password you set in step 3e, above.

h. Enter the same password as in step 3e when prompted to enter and re-enter your new key password.

i. Open the conf/ccctransfer.properties file and edit the ccctransfer.keystore.password value to have your new password instead of the old one (password). That is, edit the word password after the = sign in this entry: ccctransfer.keystore.password=password

Open

j. Save and close the conf/ccctransfer.properties file. You have now updated your college keystore password for all applications (CCCApply Standard and International, and CC Promise Grant).

k. Test the new keystore by entering the following command at the command prompt for each application.

• For the CCCApply application:

• java -jar transfer-client.jar -test https://pilot.admin.openccc.net:8443/ccctransfer/debug

• For the CC Promise Grant application:

• java -jar transfer-client.jar -test https://pilot.admin.openccc.net:8443/ccctransferbog/debug

• For the International application (coming soon):

• java -jar transfer-client.jar -test https://pilot.admin.openccc.net:8443/ccctransferintl/debug

• For the CCCApply application:

• java -jar transfer-client.jar -test https://admin.openccc.net/ccctransfer/debug

• For the CC Promise Grant application:

• java -jar transfer-client.jar -test https://admin.openccc.net:8443/ccctransferbog/debug

• For the International application (coming soon):

• java -jar transfer-client.jar -test https://admin.openccc.net:8443/ccctransferintl/debug

Preparing to Download Applications

Configuring Your Job and Format Files

After installing the Download Client, you will need to configure the job and format XML files to specify which application data you want to download.

 1.  You will have sample job and format definition XML files included in your package. These files will usually include the application name in the file name (i.e. SampleBogJob1.xml in the image above is a sample job file for the BOG application).

2.  Using a text or XML editor, open the sample job XML file for the application for which you plan to download student application data.

3.  Ensure that the job element's misCode attribute includes your college's three-digit MIS code. The job element's URL attribute points to the Pilot database environment in the above image.

4. Update the file element's directory attribute by replacing the "downloads" in the above example to be the name of the directory on your local computer where you want the download file to be saved.

5. Update the formatId attribute by replacing the ccInst in the above example to be the same name of the formatId in the format definitions file.

6. Update the prefix and suffix attributes by replacing the "mycollege-inst" and ".txt" values with the file name prefix for your choice and the file-type extension of your choice (i.e. .csv, .txt, etc.).

7.  Save the job file by using Save As, and rename the file to the name of your choice. It's best practice to include the application name in the file name. (e.g. Standard Job.xml for the CCCApply Standard application.)

8.  Using a text or XML editor, open the format definitions XML file for the application for which you plan to download student application data.

9.  Edit the XML elements and attributes in the format definitions XML file to include the specific database fields that you want to download into your college's SIS. Use the following items to assist you in editing and validating this XML file:

• the XML schema file for the format definitions file

• the Data Fields for each of the student applications (CCCApply Standard and International, and CC Promise Grant)

• the Data Dictionaries for each of the student applications

When you are done creating and validating the format definitions XML file, save the file using Save As, and rename the file to the name of your choice. It's best practice to include the application name in the file name. (e.g. StandardFormat.xml for the CCCApply Standard application.)

Running a Download Job

After installing the Download Client and configuring your job and format XML files, use the following steps to run a job to download your college's student applications (in order to import them into your college's SIS).

1. Open a command prompt (Start Menu -> type command for Windows) or open your Terminal window (Mac/ *nix).

2. At the command, navigate to the directory where your job and format definitions XML files are located and then type the following command:
   
   

   • For Windows: 
     download.bat jobs\StandardJob.xml
     
     

   • For Mac/*nix: .
     /download.sh jobs/StandardJob.xml

   
   
   

   
   
   

3. Press your enter key and the download file will run.

4. You can navigate to the downloaded file and open it in a text editor to see the downloaded data (remember that you set the directory for the download file to be saved to in the job XML file's file element directory attribute, in step 9, above). The data for all student applications that have not previously been downloaded appears in a single row, per student as in the image below.

5. Follow the data import steps for your college's SIS to import the download file data. It is highly recommended you perform this for a test SIS database to ensure the downloaded data imports into your SIS correctly.
   
   

Job File Configuration Details

The job file contains information about what student applications to download and what directories to use for the output file. A job file is created for each download job. When a job is set up in the college's scheduler, the job file name is passed as a parameter to the job.

The Job File

The job file controls the high-level aspects of the download, such as the server from which to retrieve the data. It also allows you to specify multiple downloads that may retrieve different datasets or present the data in different formats.

The Format Definitions File

The format definitions file allows you to select the specific fields you want to retrieve from the student applications and control the format of the data that the Download Client delivers to you.

Sample Job file

Filter Elements

Any given job has the basic constraint that only applications for the specified MIS codes can be retrieved. An optional filter is allowed to further restrict which student application data gets downloaded for a given job. With no filter specified, only data for "new" student applications for that MIS code are retrieved. An application is considered new if it has not previously been downloaded by the Download Client.

<job> element

The job is the root element for all download definitions.

Attributes

Environments for the URL Attribute

<file> element

The file element specifies the directory to create the download file, how the file name is formatted and which format definition to use.

<file directory="/somedir/downloads" prefix="main" suffix=".txt" formatId="fixedMain1" />

Full File Name

Besides the prefix and suffix, the date and time are also included in the file name. Based on this example: <file directory="/ somedir / downloads" prefix="main" suffix=".txt" formatId="fixedMain1" /If the transfer job ran on feb 6 2014, the file name would be / somedir / downloads / main-140206-081228.txt where "140206" represents the date and "081228" represents the run time of the job.

Format Definitions File Configuration Details

The format definitions file is an XML file used to define student application data download format:

• Which fields to include

• How each field is formatted

• Type of file (fixed or delimited)

• id (must match the associated job file's formatID).

The example sample format definitions file below can be used in conjunction with clicking the links in the navigation panel to the left to find the data fields for:

• Standard application data fields

• CC Promise Grant data fields

• International application data fields

• Supplemental Questions answers
  
  

Sample Format Definition File

formatDefinition Element

Fields in the download file appear in the order they are defined in the format definitions XML file.

Attributes

Child Elements

<fieldList>

The fieldList contains a list of field definitions.

<field>

The field element defines how an individual field is formatted. The element value is the name of the field in the submitted_application table (see the Download Data section, below).

<field len="10" name="app_id" /> Attributes

<whitespace>

The whitespace element is only used in fixed format definitions when you want to insert fixed width spaces in between two fields.

<whitespace len="3" />

<constant>

The constant element is used to insert a constant string value into the file. If you specify the len attribute, it will right pad the text with spaces if the len is greater than the length of the text. If you do not specify len, if will not add any padding.

<constant len="30">College one starts here</constant>

<newline>

The newline causes a carriage return (line feed). The newline element is aware of the operating system. For Windows it will add CR & LF. For Unix it will just add LF.

<newline />

<byAppId>

The byAppId element allows you to specify a single application for download when you provide a specific app_id value.

<byAppId app_id = '16197'/>

<dateFormatter>

A date formatter allows customization of how date/time values can be formatted using a pattern string. Example pattern strings are: MM/dd/yyyy, yyyy-MM-dd, etc.

<field name="tstmp_submit" len="20">

<dateFormatter pattern="yyyy-MM-dd HH:mm:ss z" timezone="US/Pacific"/> </field>

<booleanFormatter>

The booleanFormatter allows you to configure what text displays/downloads for boolean-date type fields with true, false, and null values.

<booleanFormatter trueValue="1" falseValue="0" nullValue="?"/>

<ssnFormatter>

The ssnFormatter applies formatting to social security numbers to include or remove dashes. <field name="ssn" len="9">

<ssnFormatter /> </field>

<field name="ssn" len="11">

<ssnFormatter removeDashes="false" /> </field>

<simpleMapper>

The simpleMapper formatter provides a way to make simple translations of data.

<field len="2" name="res_status">
<simpleMapper>
<unmatched>D4</unmatched>
<map>
<from>1</from>
<to>A1</to>
</map>
<map>
<from>2</from>
<to>B2</to>
</map>
<map>
<from>3</from>
<to>C3</to>
</map>
</simpleMapper>
</field>

The following example translates the res_status field as follows:

Here are the attribute definitions:

<stringFormatter>

The stringFormatter allows you to configure text field values to display/download as all upper-case or lower-case letters and what text displays/downloads for text fields with null values.

<stringFormatter caseConversion="lowercase" nullValue="[null]"/>

<phoneFormatter>

The phoneFormatter is used to format phone numbers.

<field len="15" name="mainphone">
<phoneFormatter pattern="(999) 999-9999"/>
</field>

Here are some sample patterns:

<numberFormatter>

The numberFormatter can be used for applying a variety of formats to numbers.

Example for applying a format for currency:

<field name="dep_other_income" len="20">
<numberFormatter format="%,d.00"/>
</field>

Data Fields

CCCApply Standard and Noncredit Applications

The latest version of the CCCApply Standard & Noncredit Application Data Dictionary includes a complete table of all data columns/fields that can be downloaded to your college SIS for the CCCApply Standard and/or Noncredit applications. See "Appendix E: Table of Downloadable Fields" in the most current version of the CCCApply Standard & Noncredit Data Dictionary.

CCCApply International Application

The latest version of the CCCApply International Application Data Dictionary includes a complete table of all data columns/fields that can be downloaded to your college SIS for the CCCApply International application. See "Appendix E: Table of Downloadable Fields" in the current version of that data dictionary for specs.

Supplemental Questions Responses

When you configure your format definition XML file for supplemental question download by including the database field name below, the "nn" in the Database Field Name column example below is replaced with the number for each field of that type that you included in your supplemental questions (i.e. <field name = "supp_secret_01"/>, <field name = "supp_secret_02"/>, etc.).

California College Promise Grant Online Application

The latest version of the California College Promise Grant Online Application Specification & Data Dictionary includes a complete table of all data columns/fields that can be downloaded to your college SIS for the CC Promise Grant Online application. See "Appendix B: Table of Downloadable Fields" in the current version of that data dictionary for specs.

Account Data Fields Mapping Chart

The table below shows a mapping of all OpenCCC Account data field names across all CCCApply applications.