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
|-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 Add||Batch Add and Modify||Batch Modify||Batch Delete|
Deleting a parent Unit will fail if its children have not already been deleted.
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.
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:
|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|
|Educational Experience Membership||Educational Experience and User|
|Goal or Objective||Unit or Course or Educational Experience or Program|
|Program Membership||Program and User|
|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.