Before you begin with the flat file implementation, you will need to have an FTP server configured and available.
Implement Grades Journey using flat files
- In System Admin, under Integrations, select Building Blocks.
- Select Installed Tools.
- In Blackboard Grade Journey Service, select Settings.
- Using the sections below, configure properties under each group of settings.
Assignment and grade column settings (incoming data)
Configure the following properties:
- Schedule Job
- Set Job Status - select Enabled
- CRON Schedule - choose how often the background extracts occur. For example, the extracts occur each hour with this value set to 0 0/60 * 1/1 * ? * Take a look at the Cron Trigger Tutorial to get familiar with the scheduler format.
- Provisioning Content Area - choose the default folder where the gradable items will be created, unless they are overridden in the transaction.
- Content Item Provisioning Check - This setting defines the matching rule for provisioned content items. The options are:
- No Restriction: Always adds items from the feed as new content items.
- One-time only: Adds any given item one time only (used for LIS).
- Update Matches By Name: Adds item on first pass and updates based on match by content item title during subsequent imports.
- Gradable Item Provisioning Check - This setting defines the matching rule for provisioned manual grade columns or grade columns created as a result of the provisioned content items. The options are:
- Update Matches By Name: Adds items on first pass and updates them based on match by content item title during subsequent imports.
- Update Matches By Metadata: Adds items on first pass and updates them based on match of the value stored in a metadata attribute called "Type" included in the optional data list of the item input data record during subsequent imports.
- Source Transfer Settings
- Receive input files via FTP - Choose as desired.
- If disabled, set the path to a local path available to each application server.
- If enabled, set the following:
- Server - set the URL to the FTP server.
- Port - Set the port.
- Username - Set the username.
- Password - Set the password.
- Path - Set the file location on the FTP server.
- Receive input files via FTP - Choose as desired.
- File Format
- Field Delimiter - Set if a delimiter other than | will be used.
- Field Qualifier - Set if a qualifier other than " will be used in fields that might contain a delimiter.
- Format for date column - This is a Java SimpleDateFormat that defines the format for any date columns in the feed file.
- Course filter mask - Set a regular expression to match the entire course ID for those courses that should be processed by the assignment and grade column service. Courses that do not match the expression will be skipped.
- Grade Column Settings
- Make Grade Columns visible to Students? - Enable if desired.
- Include Grade Columns in Calculations? - Enable if desired.
When finished, select Submit.
Grade extract settings (outgoing data)
Configure the following properties:
- Integration
- Integration Type - Choose Normal Integration or SITS Integration. Normal Integration results in one outgoing file. SITS Integration results in three outgoing files, a summary, an assessment file, and a reassessment file.
- CRON Schedule - Choose how often the background extracts occur. For example, the extracts occur each hour with this value set to 0 0/60 * 1/1 * ? * Take a look at the Cron Trigger Tutorial to get familiar with the scheduler format.
- Rounding Number - Choose the maximum number of fractional digits for a score.
- Extract Value for Unmarked Assessments - Choose the null value you want to unmarked or ungraded items to return.
- Column Filter - Select this option if the approval and extract columns list should be limited to a specified comma-separated list of grade column names when provisioning is disabled. The purpose of this setting is to allow the extract to contain only those columns that need to be reported.
- External Grade Column Only - Select this option if the approval and extract columns list should be limited to course external grade column, that is, the column in grade center marked as External Grade.
This setting takes precedence over the Column Filter setting.
- Provisioning Enabled - Select this setting if the approval and extract columns list should be limited to those imported as part of the Content Item and Gradable Item provisioned from SIS.
- Column Mapping - Enter a list of name/value pairs separated by a pipe symbol to identify the grade column data fields to include for each record in the report. If left empty, a default list of fields is included in the report:
EXTERNAL_COURSE_KEY|STUDENT_ID|BATCH_UID|TITLE|MARK|GRADE|EXTENDED_DATA
- Extract Course Role Requirement
- Course Roles - Specify the course role required for a user to be able to approve grades (i.e. instructor).
- Institutional Roles - Specify the institutional role required for a user to be able to approve grades (i.e. grade approver).
- Access Denied Message - Enter a message for users who attempt to extract grades but do not have appropriate permission.
- Result Transfer Settings
- Filename mask - Set the pattern for the extract file name.
- Transfer method - Set the transfer method.
- Transfer type - Set the transfer type. Each File extracts files separately. Combined File extracts one file with combined rows for all extracted files.
- Use Windows EOL - Set if this will be processed on Windows.
- Include Bb Fields (for SITS) - Used for debugging. Enable this setting if you wish to include additional Blackboard keys for debugging in the SITS file.
- Path - Set the path for the extract files.
- Extract File Format
- Field Delimiter - Set the delimiter between fields.
- Field Qualifier - Set the qualifier for the fields.
- Format for date column - Set the format for dates.
- Grade Approval and Transfer Settings
- Grade Approval Required - Enable this setting if you want grades to be approved at the column or grade level.
- Show History Page? - Enable this setting if you do not want grade-level approval and want the history page shown when you extract from the course.
- Perform Extract Button Enabled? - Enable this setting to allow graders to run the extract immediately.
- Schedule Extract Button Enabled? - Enable this setting to allow graders to schedule/approve the extraction.
- Lock on Approval? - Enable this setting to switch the Grade Center to read-only so grades cannot be modified after extraction.
When finished, select Submit.
Notification settings
If desired, edit notification settings.
Logging levels
Configure the following properties:
- Logging Configuration
- Log Verbosity - Configure this setting to determine the level of logging to the /logs/custom/bbc-GradeyJourney.log file. The default value is INFO, but you may want to add DEBUG for troubleshooting purposes. Production configuration should be set to INFO unless debugging.
Run a validation test
- In Settings, select Grade Extract Settings (Outgoing Data).
- Update the transfer method to Local and set the path to a local folder that can be read, updated, and deleted from the user running Blackboard Learn. Choose Normal Integration or SITS Integration based on your needs. Select Submit.
- In Settings, select Assignment and Grade Column Settings (Incoming Data).
- Update Receive Input Files via FTP to Disabled and set the Path to a local folder that can be read, updated, and deleted from the user running Blackboard. Select Submit.
- Create a weighted grade column in the course using a flat file. If using SITS, create the user files for the enrollments.
- Log in to Learn as the instructor and go to the course.
- Navigate to the Grade Center. The new weighted grade column should appear there.
- Create an assignment and map it 100% to the weighted column.
- Enter grades for the enrollments.
- In the Manage menu, select Grade Approval and Transfer.
- Select the Extract and Schedule button at the course, grade column, or grade level.
- If the extract was successful, the file or files appear in the extract folder.
- If the extract was not successful, consult the log in <bb home>/custom/log/bbgs-GradeJourney.log.
