Skip to main content
pdf?stylesheet=default
Blackboard Help

Configuring Drive

Configuration Files

Blackboard Drive uses the following configuration files (loaded in this order):

  1. Basic (mandatory, filename: xdconfig.xml)
  2. OS specific (mandatory, filenames: xdconfig_win.xml/xdconfig_mac.xml)
  3. Edition specific (mandatory, filename: xdconfig_edition.xml)
  4. OS and Edition specific (mandatory, filenames: xdconfig_edition_win.xml/xdconfig_edition_mac.xml)
  5. Customer (optional, filename: xdconfig_customer.xml)
  6. Administrator (optional, filename: xdconfig_admin.xml)
  7. User (optional, filename: xdconfig_user.xml)

Some files are signed in the installed product to prevent unauthorized modification. In these cases, the file extension is changed to *.xml.sig.

All of these files use the same tree structure in XML format. The full tree structure is defined in the Basic configuration file. The other files do not need to contain the whole structure. They contain only the subtrees with values that need to be changed in that configuration file. If the respective configuration file template does not contain the subtree with a value that you need to change, you need to copy that subtree from the Basic configuration file.

Configuration File Locations

Mac

/Library/Application Support/Blackboard/Drive/configdata/xdconfig.xml.sig

This is the signed master configuration file. It cannot be modified by a user.

/Library/Application Support/Blackboard/Drive/configdata/xdconfig_edition.xml.sig

This is the edition-specific signed configuration file. It cannot be modified by a user.

/Library/Application Support/Blackboard/Drive/configdata/xdconfig_mac.xml.sig

This is the signed platform (system)-specific configuration file. This file cannot be modified by a user.

/Library/Application Support/Blackboard/Drive/configdata/xdconfig_edition_mac.xml.sig

This is the signed edition- and system-specific configuration file. This file cannot be modified by a user.

/Library/Application Support/Blackboard/Drive/configdata/xdconfig_customer.xml

This is a customer configuration file that is used to change default package preferences according to customer's needs. It is typically used to preset the mass config server. If no changes are required, the file may be missing (both in the installation package and on the installed machine).

/Users/<username>/Library/Application Support/Blackboard/Drive/configdata/xdconfig_user.xml

This file contains user's preferences such as volumes.

/Users/<username>/Library/Application Support/Blackboard/Drive/configdata/xdconfig_admin.xml

This is the downloaded copy of the administrator-supplied configuration file distributed through the mass config server.

Windows

c:\Users\AllUsers\Blackboard\Drive\configdata\xdconfig.xml.sig

This is the signed master configuration file. It cannot be modified by a user.

c:\Users\AllUsers\Blackboard\Drive\configdata\xdconfig_edition.xml.sig

This is the edition-specific signed configuration file. It cannot be modified by a user.

c:\Users\AllUsers\Blackboard\Drive\configdata\xdconfig_win.xml.sig

This is the signed platform (system)-specific configuration file. This file cannot be modified by a user.

c:\Users\AllUsers\Blackboard\Drive\configdata\xdconfig_edition_win.xml.sig

This is the signed edition- and system-specific configuration file. This file cannot be modified by a user.

c:\Users\AllUsers\Blackboard\Drive\configdata\xdconfig_customer.xml

This is a customer configuration file that is used to change default package preferences according to customer's needs. It is typically used to preset the mass-configuration server. If no changes are required, the file may be missing (both in the installation package and on the installed machine).

c:\Users\AllUsers\Blackboard\Drive\configdata\xdconfig_customer.xml.sample

This file contains a sample of customization for mass config settings.

c:\Users\<username>\AppData\Local\Blackboard\Drive\configdata\xdconfig_user.xml

This file contains user's preferences such as volumes.

c:\Users\<username>\AppData\Local\Blackboard\Drive\configdata\xdconfig_admin.xml

This is the downloaded copy of the administrator-supplied configuration file distributed through the mass config server.

Example 1: Local Configuration of the Installed Blackboard Drive Instance

This kind of configuration is not usable for mass configuration of Blackboard Drive, but demonstrates how the configuration system works and is especially usable for validation of a configuration file before deploying it to users.

When you need to create any custom configuration file, regardless of whether you plan to customize an installation package for mass-deployment or post the config file on a server for a remote mass-configuration, make sure that the configuration file is valid by testing it on the already installed instance first, otherwise it might be difficult to isolate what went wrong.

  1. Install Blackboard Drive and make sure it launches correctly.
  2. Quit Blackboard Drive and make sure it is not running.
  3. View and download xdconfig_customer.xml.
  4. Copy the file to the xdconfig_customer.xml folder location as mentioned above. For example, on a Mac, to: /Library/Application Support/Blackboard/Drive/configdata. You need administrative privileges to copy the file to the configuration folder.
  5. Launch Blackboard Drive. You should now see the main Blackboard Drive application window. Go to the Preferences tab.

The Cache Size should now be 123 MB.

Troubleshooting

Blackboard Drive failed to start:

  • Locate xdconfig_customer.xml in a location described in Configuration File Locations and delete it or move to another location. Try to launch Blackboard Drive again. If it runs, the configuration file is corrupt.

The Cache Size does not show 123 MB:

  • The configuration file is not in proper location.
  • The configuration file contains different Cache Size value.

Example 2: Create a Customized Installation Package

In this example, we will create a modified installation package that will be pre-configured with a custom value of the Blackboard Drive cache size. This package can be then distributed to users. When a user installs this modified package, the manufacturer-default values will be overridden by the configuration values specified during the customization procedure.

  1. Create a file with the same contents as in Blackboard Drive: Configuration Example 1 and name it xdconfig_customer.xml.When using the configuration file for package customization, the file can have any valid file name because the customization procedure places the file inside the installation package with correct name. But for simplicity and to demonstrate that you can use the same file as in Example 1, keep the name xdconfig_customer.xml.
  2. Create a new folder in your home folder and copy the xdconfig_customer.xml and the installation package. The name of the installation package will depend on your version. For example, the package names for the Blackboard Drive 1.5 SP 1 GA releases are BlackboardDrive64-x64_1.5.13477.exe for Windows and Blackboard Drive 1.5.13605.dmg for Mac. Although it should work most other folders, doing it as described here is a tested procedure and it will prevent potential problems with write permissions and collision with other files in the folder.
  3. Complete the appropriate step for your platform:
    • Mac: Copy the admin scripts that you received in the administrator documentation in the distribution package. You will need at least addcustomerconfig.sh and replaceconfig.sh. Make sure that you have executable permissions for these scripts. You can run it under any account, but during the procedure the script will ask you for the admin access.From a command line, go to the folder you created for package customization and run the following command:

      ./addcustomerconfig.sh Installation Package Name xdconfig_customer.xml

      For example:

      ./addcustomerconfig.sh Blackboard\Drive\1.5.13605.dmg xdconfig_customer.xml

      You should now see a new file in the current folder:

      Installation Package Name_customized.dmg

      For example:

      Blackboard Drive 1.5.13605.dmg_customized.dmg

    • Windows: From a command line, go to the folder you created for package customization and run the following command:

      Installation Package Name_setup.exe /au xdconfig_customer.xml

      For example:

      BlackboardDrive64-x64_1.5.13477_setup.exe /au xdconfig_customer.xml

      You should now see a new file in the current folder:

      Installation Package Name_setup.new.exe

      For example:

      BlackboardDrive64-x64_1.5.13477.exe_setup.new.exe

  4. Windows platforms only: From a command line, go to the folder that you created for package customization and run the following command:

    Installation Package Name_setup.exe /au xdconfig_customer.xml

    For example:

    BlackboardDrive64-x64_1.5.13477_setup.exe /au xdconfig_customer.xml

    You should now see a new file in the current folder:

    Installation Package Name_setup.new.exe

    For example:

    BlackboardDrive64-x64_1.5.13477_setup.new.exe

  5. Install the newly create package and restart/logout if the installer asks you to do so.

    Note:  For Windows: The installation package is signed with a certificate. If you customize a package and launch the installer, the User Account Control will show Publisher: Unknown, but the installation should run normally. If you need it to show valid company name, contact your Blackboard representative to request an unsigned package and instructions on how to sign it with your certificate.

You should now see the main Blackboard Drive application window. Go to the Preferences tab. The Cache Size should now be 123 MB.

Troubleshooting

Blackboard Drive failed to start:

  • Locate xdconfig_customer.xml in a location described in Configuration File Locations and delete it or move it to another location. Try to launch Blackboard Drive again. If it runs, the configuration file is corrupt.
  • Uninstall the customized package and try to install the original. If it works, the customized package is corrupt.

The Cache Size does not show 123 MB:

  • The package was incorrectly customized.
  • The configuration file contains different Cache Size value

The xdconfig_customer.xml filename can be any valid filename in this case because the actual filename is specified on the command line and the customization procedure will rename the file to appropriate filename before adding it to the package. This is different from  where the name does matter, because we copy it directly to the installed instance, where the exact filename is expected.

Example 3: Set up Remote Configuration of the Installed Blackboard Drive Instance

In this example, similar to Example 1, we will add the configuration file to the existing (locally installed) instance. Although not usable in production, we avoid potential problems with incorrect package customization or installation.

This time, instead of changing the cache size using local configuration, we will set the link to remote configuration file, and the remote configuration file will contain the modified cache size.

  1. Install Blackboard Drive and make sure it launches correctly.
  2. Quit Blackboard Drive and make sure it is not running.
  3. Rename the xdconfig_customer.xml file created in Example 1 to admin-config.xml.
  4. Place the admin-config.xml file on a webdav server, for example, on http://learnserver:8080/bbcswebdav/admin-config.xml. Set the file permissions so that the file has public access, that is, readable without a username and password.
  5. View and download update-info.xml.
  6. Place the update-info.xml file on a webdav server, for example, on http://learnserver:8080/bbcswebdav/update-info.xml. Set the file permissions so that the file has public access, that is, readable without a username and password.
  7. View and download xdconfig_customer.xml.
  8. Copy the xdconfig_customer.xmlfile to the folder location as mentioned above. For example, for Blackboard Drive on Mac: /Library/Application Support/Blackboard/Drive/configdata. You need administrative privileges to copy the file to the config folder.
  9. Launch Blackboard Drive.You should now see the main Blackboard Drive application window. Go to the Preferences tab. The Cache Size should now show value 123 MB.
  10. Quit Blackboard Drive.
  11. Modify the update-info.xml file on the server to change the massUpdateCurrentVersion value to 11.
  12. Modify the admin-config.xml on the server:
    1. Change the massUpdateCurrentVersion value to 11.
    2. Change the cacheSize value to 456.
  13. Launch Blackboard Drive.

You should now see the main Blackboard Drive application window. Go to the Preferences tab. The Cache Size should now show a value of 456 MB.

If you make any changes to admin-config.xml on the server, you must increase the configuration version inside the massUpdateCurrentVersion tag in update-info.xml to let Blackboard Drive know that there is a new version of the file on the server.

Troubleshooting

Blackboard Drive failed to start:

  • Locate xdconfig_customer.xml in the location described in Configuration File Locations and delete it or move it to another location. Try to launch Blackboard Drive again. If it runs, the configuration file is corrupt.
  • Locate xdconfig_admin.xml in the location described in Configuration File Locations and delete it or move it to another location. Try to launch Blackboard Drive again. If it runs, the remote admin-config.xml configuration file is corrupt.

The Cache Size does not show 456 MB:

  • The local xdconfig_customer.xml file is not in proper location.
  • The URL in the local xdconfig_customer.xml file does not point to a proper remote update-info.xml file location.
  • The remote update-info.xml file is inaccessible. Try opening it in a browser. You should see the contents of the file.
  • The remote admin-config.xml file is inaccessible. Try opening it in a browser. You should see the contents of the file.
  • The admin-config.xml file contains a different Cache Size value.
  • The attempt to download the admin-config.xml timed out (default timeout is 10 seconds), so Blackboard Drive skipped the download and launched without the remote configuration.
  • The massUpdateCurrentVersion value in the admin-config.xml file was not updated properly.

Example 4: Create a Customized Installation Package Preconfigured for Remote Configuration

This example is a combination of Example 2 and Example 3: We will create a customized installation package that contains a link to the remote configuration files so that when a configuration file on the server changes, the changes will be downloaded to the user's computer.

  1. Follow steps 3-7 from Example 3
  2. Follow steps 2-4 from Example 2.

You should now see the main Blackboard Drive application window. Go to the Preferences tab. The Cache Size should now show value 123 MB.

Troubleshooting

Blackboard Drive failed to start:

  • Locate xdconfig_customer.xml in the installation folder and delete it or move to another location. Try to launch Blackboard Drive again. If it runs, the admin-config.xml configuration file is corrupt.
  • Locate xdconfig_admin.xml in the location described in Configuration File Locations and delete it or move it to another location. Try to launch Blackboard Drive again. If it runs, the remote admin-config.xml configuration file is corrupt.
  • Uninstall the customized package and try to install the original. If it works, the customized package is corrupt.

The Cache Size does not show 123 MB:

  • The package was incorrectly customized.
  • The configuration file contains different Cache Size value.

The update-info.xml filename can be any valid filename as long as xdconfig_customer.xml contains the correct link to it in the <massUpdateUrl> tag. For example, if you rename update-info.xml to update-info-student.xml, the <massUpdateUrl> should be something like <gen:value>http://learnserver:8080/bbcswebdav/update-info-student.xml</gen:value. Using this method, you can create multiple groups for different types of users. You can creating multiple preconfigured packages, each customized with different xdconfig_customer.xml files (with different URLs for the remote configuration file), and then distribute each type of the installation package to the appropriate group of users.

Example 5: Create a Customized Installation Package with Remote Configuration and Auto-update

In this example, we will assume knowledge of how to check the validity of configuration files, so we will skip the check of the configuration file on a locally installed Blackboard Drive instance and rather directly create the customized installation package.

  1. View and download xdconfig_customer.xml.
  2. Follow steps 2-4 from Example 2 to create the customized package.
  3. Take a newer build of Blackboard Drive and create a customized package named BlackboardDrive <version number+1>.dmg_customized.dmg. You should now have two customized packages: BlackboardDrive<version number>.dmg_customized.dmg and BlackboardDrive<version number+1>.dmg_customized.dmg, both of which contain the same xdconfig_customer.xml from Step 1.
  4. Rename the file xdconfig_customer.xml created in  Example 1 to admin-config.xml.
  5. Put the admin-config.xml file on a webdav server, for example, on http://learnserver:8080/bbcswebdav/admin-config.xml. Set the file permissions so that the file has public access, that is, readable without a username and password.
  6. Upload BlackboardDrive <version number+1>.dmg_customized.dmg to a folder on your test server so that the URL of the new version would be http://server:port/bbcswebdav/BlackboardDrive%20<version number+1>.exe_customized.exe. For example, for http://learnserver:8080/bbcswebdav, the new URL would be http://learnserver:8080/bbcswebdav/BlackboardDrive%20<version number+1>.exe_customized.exe.

Note:  You must use the encoded path of the build in xdconfig .xml and the location of the build on the server must match the location in the <location> tags in update-info.xml. Change the value of <version> to match the new version of the Blackboard Drive installation package. Set the file permissions so that the file has public access, that is, readable without a username and password.

  1. View and download& update-info.xml.
  2. Place the update-info.xml file on a webdav server, for example, on http://learnserver:8080/bbcswebdav/update-info.xml. Set the file permissions so that the file has public access, that is, readable without a username and password.

Blackboard Drive starts and displays a message that it will update to a newer version. Confirm the update and follow instructions to install, logout, and restart. After the procedure is finished, you should see the main Blackboard Drive application window. Go to the Preferences tab. The Cache Size should now show value 123 MB.

Notes

  1. The xdconfig_customer.xml and admin-config.xml files follow the same syntax because they are parts of the same configuration tree. They have different names in the examples to emphasize how the file will be used. But as you can see, to change cache size for example, you use the file with the same contents regardless of whether you add it to the configuration chain by copying to an installed instance through package customization or through remote configuration. The only difference is how the file is distributed.
  2. When the remote configuration file is downloaded successfully to the client machine, it is stored locally as xdconfig_admin.xml in the location mentioned above.
  3. The installation package on the server used for the auto-update of the application needs to be customized with the link to update-info.xml, otherwise the upgraded application will lose the remote update functionality.