Skip to main content
pdf?stylesheet=default
Blackboard Help

Batch Processing Using a Command Line

While most of the batch processing of data can be done using the graphical user interface, certain functionality had been reserved for command line batch processes only. The ability to combine the Batch Add and Batch Modify operation is reserved for the command line. This handling adds records when the unique identifier does not match a record and modify records when the unique identifier matches a record that already exists. The combined functions of Batch Add and Batch Modify facilitates integration with external systems so that the same file can be sent at regular intervals, for example nightly, to update the system with both new records and changes to existing records. This function is not provided in the graphical user interface because it is potentially hazardous. Uninformed users could easily modify an existing record when they intended to add a record if they did not know that the record exists or if there is a mistake in the ID.

Using Command Line Batch Processes

Only authorized administrators with access to the server have the ability to issue command line actions. Command line actions do not check entitlements. Command line batch processes use the same file formats as the graphical user interface, a plain-text file with a .txt or .csv extension that contains a header row and data rows separated by a hard return. Each field in the rows must be separated by a delimiter. The Automatic delimiter setting recognizes common delimiters such as a pipe (|).

Commands issued to Blackboard Learn must follow a specific syntax to be processed correctly. Flags are used to specify arguments in the command line. Enter command line actions in the following directory: apps/Outcomes SystemBatch.sh

Syntax Flags

Command Line Actions
Flag Value Description
-t file This flag is required and denotes the absolute file path of the batch file to be uploaded. Examples: Windows: c:\batch\batchfile.csvunix - /usr/local/batch/batchfile.csvUNIX: /usr/local/batch/batchfile.csv
-f function This flag is required and denotes the function to be performed. The entity and action are combined into one function name, just like snapshot. A table of all the available function names (case-insensitive) appears below.
-m delimiter This flag is optional and denotes the delimiter used in the batch file. If the delimiter is not provided, an "automatic" function attempts to figure out the delimiter. Automatic delimiter detection assumes that the delimiter is not A-Z, 0-9, or an underscore (_). For a tab delimiter, use the word "tab". Characters such as a comma ‘,’ and a pipe ‘|’ do not work on the command line, so the autodetect function (not specifying the delimiter) should be used in these cases.
-e encoding This flag is optional and denotes the encoding of the batch file. Default encoding is "ISO-8859-1".
-q quote character This flag is optional and denotes the character that is specified as the quote character so that data can contain instances of the delimiter. The default quote character is double quotes ' " '.
-d date format This flag is optional and denotes the simple date format string that defines the elements and pattern of the date. The default pattern is "yyyyMMdd". For steps to create the pattern, see http://java.sun.com/j2se/1.5.0/docs/api/java/text/SimpleDateFormat.html.
-a time format This flag is optional and denotes the simple date format string that defines the elements and pattern of the time. The default pattern is "h:mm a". For steps to create the pattern, see http://java.sun.com/j2se/1.5.0/docs/api/java/text/SimpleDateFormat.html.
-g datetime format This flag is optional and denotes the simple date format string that defines the elements and pattern of a datetime. The default pattern is date format + “ “ + time format. For steps to create the pattern, see http://java.sun.com/j2se/1.5.0/docs/api/java/text/SimpleDateFormat.html.
-b ignores blanks This flag is optional and indicates whether to ignore blanks in the batch file. This does not apply to missing columns, as all missing columns are ignored. Accepted values are "true" or "false".  Default is "true".

Command Line Batch Functions

Batch Functions
Batch Add Batch Add and Modify Batch Modify Batch Delete
person_insert person_insertupdate person_update person_delete
unitaff_insert aff_insertupdateunit unitaff_update aff_delete
progaff_insert progaff_insertupdate progaff_update progaff_delete
secaff_insert secaff_insertupdate secaff_update secaff_deleteUnit
unit_insert unit_insertupdate unit_update unit_delete
Deleting a parent Unit will fail if its children have not already been deleted.
program_insert program_
insertupdate
program_update program_delete
course_insert course_insertupdate course_update course_delete
section_insert section_insertupdate section_update section_delete
ougoal_insert ougoal_
insertupdate
ougoal_update ougoal_delete
eesection_insert eesection_
insertupdate
eesection_update eesection_delete
programgoal_insert programgoal_
insertupdate
programgoal_update programgoal_delete
courseobjective_
insert
courseobjective_
inserupdate
courseobjective_
update
courseobjective_
delete
eeobjective_insert eeobjective_
insertupdate
eeobjective_update eeobjective_delete
stdcategory_insert stdcategory_
insertupdate
stdcategory_update stdcategory_delete
standard_insert standard_
insertupdate
standard_update standard_deleteUnit
membership_insert    unit membership_
delete
program_
membership_insert
    program_
membership_delete
course_membership_
insert
    course_membership
_delete
ee_membership_
insert
    ee_membership_
delete
workspace_
membership_insert
    workspace_
membership_delete

Command Line Batch Rules

Command line batch actions follow these rules:

  • Batch Add adds records only when the unique identifier does not match a record that already exists.
  • Batch Add and Modify adds records only when the unique identifier does not match a record and modifies records only when the unique identifier matches a record that already exists.
  • Batch Modify modifies records only when the unique identifier matches a record that already exists. Batch modify overwrites any data in the existing record with data from the batch file. If an attribute is blank in a specific record or if the entire attribute column is not included in the batch file, data in the existing record(s) is not overwritten by blanks.
  • Batch Delete removes records only when the unique identifier matches a record that already exists. Delete operations occur in real time. Disabling of records is not available here. Records must be disabled using the Snapshot tool.
  • Any enumerated attribute must have acceptable values provided in the graphical user interface.
  • Blanks within records are ignored.

Attribute data that uses the content editor (formatted text) cannot be batch loaded. Institutions that plan to batch load Units or other Places with a vision or mission statement that relies on the content editor should instead create attributes for those forms into which those values can be batch loaded and displayed, such as a value type of Long Text String.

Sample Commands

The following is a sample Windows command for adding Units to Outcomes Assessment:

c:\blackboard\apps\caliper\CaliperBatchTool.bat -t "c:\batchfiles\Unit-batch.txt" -f Unit_insertupdate -m "tab" -e "UTF-8" -q "'" -d "MMddyyyy" -a "kk:mm" -g "yyyyMMdd h:mm a" -b "true"

The following is a sample UNIX command for adding Units to Outcomes Assessment:

/usr/local/blackboard/apps/caliper/CaliperBatchTool.sh -t "/usr/local/batchfiles/Unit-batch.txt" -f Unit_insertupdate -m "tab" -e "UTF-8" -q "'" -d "MMddyyyy" -a "kk:mm" -g "yyyyMMdd h:mm a" -b "true"

Dependencies Among Outcomes Assessment Entities

The following table specifies which entities must exist before a new record can be added:

Entities Which Must Exist
Type of Record Required Parent or Associated Records
Unit Affiliation Record Person and Unit
Program Affiliation Record Person and Program
Section Affiliation Record Person and Section
Course Membership Course and User
Course Unit
Educational Experience Membership Educational Experience and User
Educational Experiences Unit
Goal or Objective Unit or Course or Educational Experience or Program
Person Record None
Program Membership Program and User
Program Unit
Section Course or Educational Experience
Standard Categories Parent Standard (the Standard Category above this one in the hierarchy) if present.
Standards (note that this is standards goals, not standards categories) Standard Category
Unit Membership Unit and User and Unit Role
Unit Parent Unit. If the parent Unit is added in the same batch add file in a row prior to the child, the parent Unit will already exist and the child Unit will be successfully added.

Batch Process Errors

Error messages for batch operations are captured in a log file. Success messages are not captured in the log file.

Individual records fail during a batch process under any of these conditions:

  • In Batch Add, a unique identifier matches a unique identifier that already exists.
  • In Batch Modify, a unique identifier does not match a unique identifier that already exists.
  • In Batch Delete, a unique identifier does not match a unique identifier that already exists.

The entire batch process fails under any of these conditions:

  • Any of the attributes in the header row do not match attributes for the entity type.
  • Any attribute in the header row is repeated.
  • A batch required attribute is not provided.
  • A dependency requirement is not met (see Dependencies table).
  • An Outcomes Assessment required attribute is not provided.
  • An attribute data does not comply with the type or size data requirements for that attribute (too long, not an integer, incorrect date format, and so on.).
  • An enumerated value is not valid.