Skip to main content
pdf?stylesheet=default
Blackboard Help

Mass Configuration for Mac

sThis administrator guide provides instructions and information for running the Blackboard Drive for Mass Configuration (Mass Config) utility. The Mass Config is used for configuration of Blackboard Drive installations for the end users. For example, the Mass Config can create a new Volume for the end user and specify what Drive letter this Volume should use. It can also be used to set various other options such as cache size.

Blackboard Drive Configuration Files

When it starts, Blackboard Drive loads its internal configuration files. It next looks for and, if necessary, loads an administrator-configured file. This file is downloaded from a URL specified by the administrator.

View and download admin-config-sample.xml. to use as the template for your admin-config.xml file. Either create a copy of the file and name it admin-config.xml, or create a new file named admin-config.xml.

When using the Auto-Update feature, the xdconfig_customer.xml calls out to the server's update-info.xml file, which contains versioning information for the admin-config.xml file. If the version information has been updated, the admin-config.xml file will be called, and the new values will be brought to the user's system via auto-update. The configuration file for Mass Config is named admin-config.xml. See the table in Description of Configurable Attributes section (below) for parameter settings and syntax.

Preventing a User from Overriding the Value

For some parameters, you may need to prevent a user from overriding it. This is done on a per attribute basis by the presence of the gen:locks="edit" attribute in the configuration file.

For example, to set the server to https://as91sp14 and prevent the user from updating this value, the configuration file would include a definition like the following:

<server gen:locks="edit">
  <gen:value>https://as91sp14</gen:value>
</server>

Description of Configurable Attributes

The following table provides the list of attributes that can be configured via the Mass Configuration utility, and provides details on the type of data and the possible and default values.

How to read the table:

  • The Name column lists how the item must be referenced in the configuration file.
  • The Description cell describes what the parameter is used for.
  • The Default value is the value that is used if none is specified.

1. globalSettings

Name cookiesPolicyURL
Description The value of this item is used as the URL to Privacy Center.
Type String
Default Value Edition dependent
Name disableCookiesPolicyInformationDisplay
Description The value of this item enables/disables displaying privacy information dialog containing cookies policy information at the startup. This dialog should be displayed on startup since new EU privacy law take effect in the EU on May 26, 2012 and it is related to the use of cookies. Users must receive detailed notice/info on cookies and their purpose.
Type Boolean
Default Value false
Name massUpdateUrl
Description The value of this item is used as the UURLof update-info xml. Should be specified (and possibly locked) on the customer level.
Type string
Default Value none
Lock Level none
Name massUpdateCurrentVersion
Description The value of this item is used by the auto-update feature to determine whether a new version of the configuration file needs to be retrieved from a mass-configuration server. When the massUpdateCurrentVersion in the config file on the remote mass-config server is higher that the massUpdateCurrentVersion in the local admin config, the remote config file is downloaded and applied. See Auto-update and Versioning for a detailed description of how the mass-config system works.
Type String
Default Value 0
Example <massUpdateCurrentVersion>
    <gen:value>10</gen:value>
</massUpdateCurrentVersion>
Lock Level None
Name massUpdateTimeout
Description The value of this item is used by the auto-update feature to determine how many seconds Blackboard Drive for Mac can wait for mass-configuration server during retrieving of configuration file. There are also fixed timeouts for establishing connection and downloading of file. Both are set to 10 seconds and cannot be changed. Value in this configuration item sets maximal accumulated value for both actions. Minimum value is 1 second.
Type Integer
Default Value 10
Name disableSavingPassword
Description This value disables saving password in Drive. When it is set to true, all controls that provides saving of password will be hidden and password storage factory will return dummy password storage which does not save password and always returns null for password. null means password is not in the password storage.
Type boolean
Default Value true for SAS & SAP editions; false for other editions
Lock Level Set for SAS & SAP edition; None for other editions
Name disableSavingUsername
Description This value disables saving of user name. When it is set to true text box in service edit dialog is disabled and all dialogs that offers user name don't display previously entered username. Username is actually stored in cache, but it can be eliminated by clearCacheOnServerDisconnect.
Type boolean
Default Value false
Lock Level edition specific
Name forceSecureRenegotiation
Description The item is associated with Transport Layer Security (TLS) Renegotiation Issue (see http://java.sun.com/javase/javaseforbusiness/docs/TLSReadme.html). A security vulnerability in all versions of the Transport Layer Security (TLS) protocol (including the older Secure Socket Layer (SSLv3)) can allow Man-In-The-Middle (MITM) type attacks where chosen plain text is injected as a prefix to a TLS connection. This vulnerability does not allow an attacker to decrypt or modify the intercepted network communication once the client and server have successfully negotiated a session between themselves. This security bug has been solved by interim fix that disables TLS/SSL renegotiation in the Java Secure Sockets Extension (JSSE) by default. This fix caused that client is not able to connect server which uses renegotiation. It can be easily solved by can be re-enabling renegotiations for Drive, but it will cause potential risk for MITM attacks. Most of current servers do not support this fix so for more user friendly behavior this config option for enabling/disabling renegotiation is set to enable renegotiation by default.
Type boolean
Default Value true
Lock Level none
Name forceUnmountOnEndSession
Description This parameter forces unmounting of the volumes that cannot be gracefully unmounted during system Log off, Restart or Shutdown. Note that it might cause the interruption of unfinished transfers, resulting in the data loss. The accompanying sign of this problem is never ending black screen appearance waiting for Drive to exit, that results in a user's necessity of choosing Cancel or Force Log off/Shutdown/Restart button to leave the black screen. The parameter should be set to true only when customer experiences troubles with black screen on Windows Vista and later.
The Force Log off/Shutdown/Restart button causes Drive to terminate immediately without chance to do proper actions needed during the exit of the application, in contrast to proper exit, with an exception of mounted volumes, when the forceUnmountOnEndSession is set to true. Note that sometimes an application can hold the opened file, which can cause the volume cannot be unmounted. That might be also good reason for setting this option to true, but administrator should remember that the amount of data loss depends on good or bad decision of the user. For example there might be a lot of files in the queue to save to the server from previous Drag&Drop action.
Type boolean
Default Value false
Lock Level none
Since Version 1.7
Name notificationWindowPopupTime
Description This item defines lifetime of certain notification dialogs in seconds.
Type integer
Default Value 30
Lock Level None

1.1. Edition info

Name mainVersion
Description The value of this item is used to denote the main version of the product. It should be in the format X.X where X is a number. This string is used as a prefix for revision number, when the full version of the application is assembled. This item should be changed and locked on EDITION level and is the same for all modules of Drive.
Type string
Default Value 1.0
Lock Level Edition
Name moreInfoURL
Description This value contains URL for button "More Info" in About Dialog of Drive, which usualy opens company home page. The value differs for each edition.
Type string
Default Value none
Lock Level Edition
Name isBuildTrial
Description true if the build is trial, otherwise false.
Type string
Default Value none
Lock Level Edition
Name helpPageURL
Description The url of Blackboard Drive help page.
Type string
Default Value Depends on edition.
Lock Level Edition

1.2. sharingLevelList

Name sharingLevel
Description Force the sharing level on all volumes by using gen:locks="edit".
Possible values are:
None
Light
Medium
Heavy (default)
Type String
Default Value Heavy
Example <sharingLevel>
   <!-- This volume will have medium sharing level -->
   <gen:value>Medium</gen:value>
</sharingLevel>
Name SharingLevelNone
Sharing Level name none
checkBeforeOpen false
autoLocks false
cachedListings true
refreshTimeout 60 min
itemOrder 0
guid Xythos;04:03:08 12:30:35 +0100;None
Name SharingLevelLight
Sharing Level name Light
checkBeforeOpen true
autoLocks true
cachedListings true
refreshTimeout 15 min
itemOrder 1
guid Xythos;04:03:08 12:30:36 +0100;Light
Name SharingLevelMedium
Sharing Level name Medium
checkBeforeOpen true
autoLocks true
cachedListings true
refreshTimeout 5 min
itemOrder 2
guid Xythos;04:03:08 12:30:37 +0100;Medium
Name SharingLevelHeavy
Sharing Level name Heavy
checkBeforeOpen true
autoLocks true
cachedListings true
refreshTimeout 1 min
itemOrder 3
guid Xythos;04:03:08 12:30:38 +0100;Heavy
sharingLevelSettings (template)
Name name
Description The name of a volume. It is mandatory for a volume to have a unique name.
The name must match the following regex pattern: [a-zA-Z_0-9]+[a-zA-Z_0-9-:\.]*
Type string
Default Value none
Lock Level none
Example <name>
   <gen:value>xpHTTPS</gen:value>
</name>
Name checkBeforeOpen
Description Tells Blackboard Drive if a file should be checked for any recent change before open (by means of PROPFIND method). If Blackboard Drive finds out that the file was changed on server and the file contents in cache is stale, new download is issued.
Type Boolean
Default Value false
Lock Level Edition
Example <checkBeforeOpen>
   <gen:value>false</gen:value>
</checkBeforeOpen>
Name autoLocks
Description Tells Drive if a file should be autolocked during editing or not.
Type boolean
Default Value false
Lock Level none
Name cachedListings
Description If true and directory contents was cached, remote dirlist is not done.
Type boolean
Default Value false
Lock Level None
Example <cachedListings>
   <gen:value>true</gen:value>
</cachedListings>
Name refreshTimeout
Description Time in seconds. Tells Blackboard Drive after how much time is cached dirlist or remote attributes considered out of date. The Drive does not need to honor this value. It serves as a hint.
Type integer
Default Value 0
Lock Level None
Example <refreshTimeout>
   <gen:value>3600</gen:value>
</refreshTimeout>
Name checkBeforeOpenTimeout
Description Time in seconds. Tells Drive after how much minimum time should be performed checkBeforeOpen. In other words, if there is a file system operation asking for remote attributes of a file and cached information on such remote attributes is available, we do not make remote operation to verify the validity of the data, unless the data is older than the value of the checkBeforeOpenTimeout.
Type integer
Default Value 0
Lock Level none
Name itemOrder
Description This is the number giving the sharing level the order in the GUI list presented to user. It should reflect "heaviness" of the sharing level as much as possible. The least "checking" sharing level has the least number.
Type Interger
Default Value 0
Lock Level none

1.3. RemoteAttributeTab

Name DisableRemoteAttributesTab
Description Controls whether or not the RemoteAttributes tab is displayed
Type boolean
Default Value false
Lock Level none
Name DisableRemoteAttributesAddition
Description Disables adding of new file or folder remote attributes (e.g. WebDAV properties) in Properties dialog. Modification or deletion of existing attributes is unaffected.
Type boolean
Default Value false
Lock Level none
Name DisableRemoteAttributesModification
Description Disables modifying existing file or folder remote attributes (e.g. WebDav properties) values in Properties dialog. Adding or deletion of attributes is unaffected.
Type boolean
Default Value false
Lock Level none
Name DisableRemoteAttributesDeletion
Description Disables deleting existing file or folder remote attributes (e.g. WebDAV properties) in Properties dialog. Adding or modification of attributes is unaffected.
Type boolean
Default Value false
Lock Level none

1.4 Authentication

Name NegotiateSpnWithCanonicalName
Description The value determines whether Canonical Name is used for Service Principal Name when the Negotiate (SPNEGO) authentication protocol is used. Note that the Canonical Name is not an alias determined by a DNS CNAME record, however it is the primary host name determined by a DNS A-Record which should be unique.
Type string with constraint
   It can be set just to following values:
      FALSE - The SPN contains the host-name taken from URL used for the connection to the WebDAV server.
      TRUE - The SPN contains the Canonical Name which is returned by the DNS system for given host-name.
      SYSTEM_DEFAULT - The value is read from registry key FEATURE_USE_CNAME_FOR_SPN_KB911149 as documented in Microsoft KB911149. If the setting for IE process is not equal to one the TRUE value is set for this option. All the other cases are translated into the FALSE value. Note that CNAME refers to a DNS CNAME record, but not to Canonical Name, so value of FEATURE_USE_CNAME_FOR_SPN_KB911149 has to be negated when it is translated into NegotiateSpnWithCanonicalName value.
Default Value TRUE
Lock Level None
Name NegotiateSpnWithPort
Description The value determines if Service Principal Name contains the port when non-default port is used in the URL when connecting to the WebDAV server. The SPN is needed when the Negotiate (SPNEGO) authentication protocol is used.
Type string with constraint
   It can be set just to following values:
      FALSE - The SPN contains the host-name taken from URL used for the connection to the WebDAV server.
      TRUE - The SPN contains the Canonical Name which is returned by the DNS system for given host-name.
      SYSTEM_DEFAULT - The value is set to be in parity with Internet Explorer setting - FALSE.
Default Value FALSE
Lock Level None
Name javaSecurityAuthLoginConfig
Description Allows to setup java system property java.security.auth.login.config for SPNEGO/KerberosV5 (Negotiate/KerberosV5) HTTP authentication. The value determines the location of login config file. The file must contain the configuration section named as com.xythos.client.http.auth.mac.NegotiateScheme. This file is not installed by XD for Mac Installer. This file is supposed to be distributed to the client machines by an administrator through 3-rd party tool or manually. Blackboard Drive for Mac has to be restarted to accept the file that has just been placed. This is Mac OS X platform specific option.
Type string
Default Value /Library/Preferences/Blackboard/Drive/auth-config/login.conf
Lock Level delete,edit
Example com.xythos.client.http.auth.mac.NegotiateScheme {
  com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true renewTGT=true debug=true;
};
Name javaSecurityKrb5Conf
Description Allows to setup java system property java.security.krb5.conf for SPNEGO/KerberosV5 (Negotiate/KerberosV5) HTTP authentication. The value determines the location of kerberos V5 config file. The file contains Kerberos configuration. The information includes mapping between domains and realms and Key Distribution Center host name for each realm. This file is not installed by XD for Mac Installer. This file is supposed to be distributed to the client machines by an administrator through 3-rd party tool (e.g. Apple Remote Desktop) or manually. Blackboard Drive for Mac has to be restarted to accept the file that has just been placed. This is Mac OS X platform specific option.
NOTE Since JRE 1.7, we have to set _default_realm_ to be able connect successfully, see example below.
Type string
Default Value /Library/Preferences/Blackboard/Drive/auth-config/krb5.conf
Lock Level delete,edit
Example

[libdefaults]
	default_tkt_enctypes = aes256-cts aes128-cts rc4-hmac des3-cbc-sha1
	default_tgs_enctypes = aes256-cts aes128-cts rc4-hmac des3-cbc-sha1
	permitted_enctypes   = aes256-cts aes128-cts rc4-hmac des3-cbc-sha1
	default_realm = BRNO.LOCAL


[realms]
   	TEST1.BRNO.LOCAL = {
		 kdc = dc.test1.brno.local
		 default_domain = TEST1.BRNO.LOCAL
         }

        BRNO.LOCAL = {
		 kdc = brno.local
		 default_domain = BRNO.LOCAL
         }

[domain_realm]
    .TEST1.BRNO.LOCAL = TEST1.BRNO.LOCAL
    .BRNO.LOCAL = BRNO.LOCAL

1.5 ContextMenu

Name DisableContextMenu
Description Disables shell/finder context menu items
Type boolean
Default Value false
Lock Level none
Name HideCopyUrlToClipboard
Description When set to 'true', the item "Copy URL to Clipboard" is not available in the context menu after right-clicking on a file
Type boolean
Default Value false
Lock Level none
Name HideRefreshCachedData
Description When set to 'true', the item "Refresh Cached Data" is not available in the context menu after right-clicking on a file
Type boolean
Default Value false
Lock Level none

1.6. Intellitach

Name DisableIntellittach
Description Enables or disables the Create Intellittach feature
Type Boolean
Default Value false

1.7. Reporting

Name DisableSend
Description Enables or disables sending logs. User could only save logs to disk
Type boolean
Default Value false
Lock Level none
Name DisableEmailCreation
Description Enables or disables the creating email when logs are uploaded
Type boolean
Default Value false
Lock Level none
Name EmailRecipient
Description Comma separated list of email recipients
Type string
Default Value Edition dependent: Blackboard - 
Lock Level none
Example <xdConfig>
 <globalSettings>
  <Reporting>
    <EmailRecipient>
       <gen:value>support@blackboard.com</gen:value>
    </EmailRecipient>
  </Reporting>
 </globalSettings>
</xdConfig>
Name UploadUrl
Description Report upload URL
Type string
Default Value Edition dependent
Lock Level none
Example <xdConfig>
 <globalSettings>
  <Reporting>
    <UploadUrl>
       <gen:value>https://files.xythos.com/XD_Logs/Blackboard</gen:value>
    </UploadUrl>
  </Reporting>
 </globalSettings>
</xdConfig>
Name Password
Description User password if authentication is required
Type string
Default Value null
Lock Level none
Name Username
Description Username if authentication is required
Type string
Default Value null
Lock Level none

1.8. Versioning

Name DisableVersioning
Description Enables or disables the create Versioning feature
Type Boolean
Default Value false
Name DisableVersioningStateChange
Description Defines if the options Enable Versioning and Disable Versioning on a file will be available to the user.
Type boolean
Default Value false
Lock Level None
Name DisableCheckoutStateChange
Description Defines if the options Check Out, Check In and Undo Check Out on a file will be available to the user.
Type boolean
Default Value false
Lock Level None

1.9. Locking

Name DisableManualLockStateChange
Description Defines if the options Lock and Unlock on a file will be available to the user.
Type boolean
Default Value false
Lock Level None

1.10. Collaboration

Name ConcurrentAccessPolicy
Description During a file open, a test is performed if the file is locked by someone else. This option defines what will happen when such lock is discovered. If the application which opens the file is not in the AlwaysNotifyList or NeverNotifyList and the file is opened only with the read access, then the file is opened normally without any notification. Also when the file is opened only for reading file attributes, it is opened normally without any notification
ALLOW - The file will have only read-only attribute and will open normally.
WARNING - The file will have the read-only attribute, will open normally and a notification window will be displayed by whom the file is locked.
DENY - The open will fail with the access deny error and a notification window will be displayed by whom the file is locked.
Type enum
Default Value WARNING
Lock Level none
Name AlwaysNotifyList
Description When a file is locked by a different user and the file is opened by an application which process name is in this list, depending on the ConcurrentAccessPolicy setting a notification will be displayed even if the open is performed only with the read-only access. You can add processes. For example, to add notepad++ because it's known to not keep the file open during editing: <AlwaysNotifyList>    <gen:newElement gen:guid="Notepad++" gen:val="notepad++.exe"/> </AlwaysNotifyList>
Type list
Default Value Notepad, Wordpad, Microsoft Excel, Microsoft Excel Compatibility Pack, Microsoft Word, Microsoft Word Compatibility Pack, Microsoft PowerPoint, Microsoft PowerPoint Compatibility Pack, Paint, Word Perfect, MS Office Publisher, MS Office Outlook, Visio, Visio 2000, Microsoft Project, Microsoft FrontPage, GVim, WinRAR, WinZip, Flash Professional
Lock Level none
Name NeverNotifyList
Description When a file is locked by a different user and the file is opened by an application which process name is in this list, a notification will never be displayed regardless the ConcurrentAccessPolicy setting and even if the file is opened with the write access. You can add processes. For example, to add notepad++ because it's known to not keep the file open during editing: <NeverNotifyList>    <gen:newElement gen:guid="Notepad++" gen:val="notepad++.exe"/> </NeverNotifyList>
Type list
Default Value Explorer, Total Commander, Total Commander 64, Salamander, Windows Commander, cmd.exe, ESET Smart Security, svchost.exe, Dropbox
Lock Level none
Name NotificationSuppressTime
Description No notification for the the same file and the same process will be displayed during the time interval defined by this value. This prevents displaying multiple identical notifications in a short time.
Type integer
Default Value 10
Lock Level none

1.11. platformSpecific

Name cooallowExtendedAttributes
Description If this flag is set to false, .com/XD_Logs/ Drive for Mac does not allow standard way of using extended attributes (using Apple Single file format). The system is than forced to use Apple double file format, which helps to persist the extended attributes in the form of the "._" files. When the flag is set to true, the persisting of the extended attributes does not work - the extended attributes are preserved only for the current session.
Type boolean
Default Value true
Lock Level None

2. userSettings

2.1. userList

Name userList
Description The template which creates all user settings is updated through gen:updateListType.
Type String
Default Value None
Name updateListType
Description The template which creates all volumes is updated through gen:updateListType.
Type  
Default Value <gen:updateListType>
userSettings (template)
Name cookiesPolicyAccepted
Description The value of this item is used for displaying privacy information dialog containing cookies policy information at the startup for the user. If the value is "false" (default value) the dialog is displayed at the startup. If the cookie policy is accepted by clicking appropriate button in the cookies policy dialog the "true" value is stored to this item and dialog is never more shown for the user at the startup (till "true" value is presented in this item)
Type boolean
Default Value false
Lock Level none
Name logDirectory
Description It is the path to the directory where logs files are placed. For this path customization you can use macros as described in Usage of macros in config.
Type Expstring
Default Value %LOG%/%SHORT_COMPANY_FOLDER%/%PRODUCT_FOLDER%/
Lock Level None
Name userCacheDir
Description It is the path to the directory where user cache files are placed. For this path customization you can use macros as is described in Usage of Macros in Config.
Type expstring
Default Value %LOCAL_APPLICATION_DATA%/%SHORT_COMPANY_FOLDER%/%PRODUCT_FOLDER%/cache/
Example Mac OS X /Users/<username>/Library/Application Support/<Short Company name>/<Short Product name>/cache
Lock Level None
Name userDataDir
Description The location which will be used for data storing during disaster recovery. The default location is user home. For this path customization, you can use macros as is described here: Usage of macros in config.
Type expstring
Default Value %USER_HOME%
Example Mac OS X /Users/<username>/
Lock Level None
Name username
Description Name of a user used to authenticate against a remote server.
Type string
Default Value none
Lock Level none
Example <username>
   <gen:value>testuser1</gen:value>
</username>
Name serverTimeDifferenceWarning
Description This value specifies tolerance for difference of time between server and client machine. If time lag is higher than this value, info message box will be displayed to the user. Time is set in seconds
Type integer
Default Value 300
Lock Level none
uiSettings
Name activityNotificationSettings
Description This list of values sets how notification window is displayed. There are two types of dialogs:
  - One displays progress bar of uploaded/downloaded file. This is called Slow operations
  - Second is displayed when lot of small operations are detected. It shows indeterminate progress bar. This is called Fast operations
Structure - slowOperations
    - notificationDelay
    - showNotification
- fastOperations
    - sampleInterval
    - operationCount
    - showNotification
    - dismissExpirationTime
Types - slowOperations
    - notificationDelay : integer
    - showNotification : boolean
- fastOperations
    - sampleInterval :integer
    - operationCount : integer
    - showNotification: boolean
    - dismissExpirationTime: integer
Default Values - slowOperations
    - notificationDelay : 5
    - showNotification : true
- fastOperations
    - sampleInterval :3
    - operationCount : 10
    - showNotification: true
    - dismissExpirationTime: 30
Lock Level none
Name trayIconSettings
Description Tray icon settings section:
  - showIconVisibilityTip: Enables/disable tip, that suggests user to set Tray icon to always visible
  - iconVisibilityTipTime: Tray icon tip visible time (seconds)
Structure   - showIconVisibilityTip
  - iconVisibilityTipTime
Types   - showIconVisibilityTip : boolean
  - iconVisibilityTipTime : integer
Default Values   - showIconVisibilityTip : true
  - iconVisibilityTipTime : 30
Confirmations
Name showConflictDiscardConfirmation
Description When set to 'true', a confirmation dialog is shown when the user clicks the Discard button on the conflict resolution dialog. This confirmation dialog warns the user that continuing will discard the current file version, potentially resulting in a data loss, and provides the option to change it.
Type boolean
Default Value true
Lock Level none
Name confirmDisconnect
Description When set to true, a confirmation dialog is shown when a user clicks the Disconnect button on the ConnectionPanel. This confirmation dialog warns users that they will disconnect the volume and provides the option to cancel the action.
Type boolean
Default Value true
Lock Level none
intellitachSettings
Name disableIntellilinkOpen
Description Setting this option to true disables opening Intellilinks using Drive
Type boolean
Default Value false
Lock Level none
Name IntellittachType
Description Defines the default Intellittach type. The default type is selected in the Create Intellittach dialog by default.
Possible values are: LINK - create links by default; TICKET - create tickets by default
Type String
Default Value Ticket
Name ShowIntellittachDialog
Description Disables or enables the Create Intellittach dialog. When set to false, the dialog is not displayed and the link or ticket is created according to default values.
Type Boolean
Default Value true
Ticket
Name ReadOnly
Description Defines the ticket privilege
false = Read & Write | true = Read Only
Type boolean
Default Value true
Lock Level none
Name Timeout
Description Defines the number of time units for the ticket lifetime defined in the TimeoutUnit. Value 0 means that the timeout is set to infinite.
Type integer
Default Value 30
Lock Level none
Name TimeoutUnit
Description The timeout unit for ticket lifetime. The number of units is defined in Timeout
Possible values are:
  • Minutes
  • Hours
  • Days
  • Weeks
  • Years
Type string
Default Value Days
Lock Level none
Name PasswordProtected
Description If set to true, the "Password Enable this Ticket" checkbox on the Ticket Options dialog is checked by default and tickets are created with a password from the "Ticket Password" text field. When this value is set to true and PasswordProtectedChangeAllowed is set to false, the user is not allowed to create a ticket without a password.
Type boolean
Default Value false
Lock Level none
Name PasswordProtectedChangeAllowed
Description When set to true a status of the checkbox indicating usage of password in the dialog for creating a ticket is changeable.
Type boolean
Default Value true
Lock Level none
proxyList
Name proxyList
Description List of user proxies. By default the list contains only one main proxy only. Currently XD is able to operate with one proxy and does not give a user chance to maintain more of them. This is likely to change in future releases.
Type  
Default Value <gen:updateElement gen:templateguid="Xythos;15:03:08 14:14:46 +0100;MainProxy">
Name MainProxy
Description Currently XD is able to operate only with one proxy and does not give user chance to maintain more of them. The setting of this main proxy ("MainProxy") is created according to "proxySettings (template)" and contains following items:
proxyUsage
proxyServer
proxyPort
proxyUsername
proxyPassword
Guid Xythos;15:03:08 14:14:46 +0100;MainProxy
Example <gen:updateElement gen:templateguid="Xythos;15:03:08 14:14:46 +0100;MainProxy">
Values proxyUsage - "DONT_USE_PROXY", not locked
proxyServer - "", not locked
proxyPort - 8080, not locked
proxyUsername - "", not locked
proxyPassword - "", not locked
Type proxySettings (template)
Name proxyUsage
Description This value decides if this proxy will be used or not. Posible values are:
DONT_USE_PROXY - no proxy will be used; USE_PROXY - use this proxy with its settings; AUTO_DETECT - auto-detect the proxy (from system) and use just username and pwd.
Type enum
Default Value DONT_USE_PROXY
Lock Level None
Example <proxyUsage>
   <!-- Possible values: DONT_USE_PROXY(default), USE_PROXY, AUTO_DETECT To force proxy usage by a user, add the attribute gen:locks="edit" to proxyUsage tag -->
   <gen:value>USE_PROXY</gen:value>
</proxyUsage>
Name proxyServer
Description The url of proxy server without port.
Type string
Default Value none
Lock Level None
Example <proxyServer>
   <!-- The proxy server address. This value must be changed as it's only an example. -->
   <gen:value>200.200.200.200</gen:value>
</proxyServer>
Name proxyPort
Description The port of proxy server. It has to be from the correct port range.
Type Integer
Default Value The default proxy port value is 8080 and typically does not need to be modified.
Lock Level None
Example <proxyPort>
   <gen:value>8080</gen:value>
</proxyPort>
Name proxyUsername
Description User name for authentication
Type string
Default Value none
Lock Level none
Name proxyPassword
Description Proxy password for authentication
This setting can be used when it's necessary to set the proxy password through the massconfig. Passwords entered by the user are not stored in the massconfig, they are always stored into the local password storage.
  • If there is a password in the massconfig and there is no password in the password storage, the massconfig password will be used
  • If there is a password in the massconfig and there is a password in the password storage, the password from the password storage will be used
  • If there is a password in the massconfig and this password is locked and there is a password in the password storage, the massconfig password will be used
  • If there is no password in the massconfig and there is a password in the password storage, the password from the password storage will be used
Type string
Default Value none
Lock Level none
volumeManager
Name volumeList
Description List of all users' volumes.
Type list
Default Value  
volumeSettings (template)
Name name
Description The name of volume. For volume it is mandatory to have its unique name
The name must match with the following regex pattern: [a-zA-Z_0-9]+[a-zA-Z_0-9-:\.]*
Type string
Default Value none
Lock Level none
Name defaultMountPoint
Description The place in system where should be this volume mounted. uses the path "/Volumes/" + nameOfTheVolume.
If the value of defaultMountPoint is not valid or is empty, uses the path "/Volumes/" + nameOfTheVolume
Type string
Default Value none
Lock Level none
Name server
Description The url of server where the volume should be connected. It must be valid url.
Type string
Default Value none
Lock Level None
Example <server gen:locks="edit">    <!-- The server can not be changed in this volume due to edit lock -->
   <gen:value>https://xp:444</gen:value>
</server>
Name serverUrlCustomerConstraint
Description The server volume constraint where the volume should be connected. Represented as regular expression.
Type String
Default Value None
Lock Level None
Example <server>
   <gen:constraintData gen:name="serverUrlCustomerConstraint">
   <gen:value>.*wfs71ga\.com.*</gen:value>
   </gen:constraintData>
</server>
Name username
Description Name of the user used to authenticate against remote server
Type string
Default Value none
Lock Level none
Name password
Description Volume password for authentication.
This setting can be used when it's necessary to set the volume password through the massconfig. Passwords entered by the user are not stored in the massconfig, they are always stored into the local password storage.
      1.  If there is a password in the massconfig and there is no password in the password storage, the massconfig password will be used.
      2.  If there is a password in the massconfig and there is a password in the password storage, the password from the password storage will be used.
      3.  If there is a password in the massconfig and this password is locked and there is a password in the password storage, the massconfig password will be used.
      4.  If there is no password in the massconfig and there is a password in the password storage, the password from the password storage will be used.
Type string
Default Value none
Lock Level none
Name bypassProxy
Description If true, the proxy will not be used for the connection of this volume to remote server (even if otherwise the proxy is used).
Type boolean
Default Value false
Example <bypassProxy gen:val="true"/>
Lock Level none
Name autoConnectAfterStart
Description Tells the Drive if this volume should be automatically connected after start.
Possible values: DISCONNECTED - default value, the volume stays disconnected; ONLINE - the volume will be connected.
Type enum
Default Value DISCONNECTED
Lock Level None
Example <autoConnectAfterStart gen:val="DISCONNECTED"/>
Name openFileManagerUponConnection
Description If true, the default file manager window will be opened immediately after volume connection.
Type boolean
Default Value false
Lock Level None
Example <openFileManagerUponConnection>
   <gen:value>true</gen:value>
</openFileManagerUponConnection>
Name sharingLevel
Description The sharing level which should be used for this volume. Possible values are names of sharing levels from the sharingLevelList.
Possible values: None, Light, Medium, Heavy (or name of any new sharing level created by administrator)
Type boolean
Default Value false
Lock Level none
langageSettings
Name langage
Description Language to use. The value must be one of the ISO language codes
Type string
Default Value en
Lock Level none
Name country
Description One of the country ISO codes
Type string
Default Value US
Lock Level none
dirmanSettings
Name appsThatKeepFileClosedWhileEditing
Description A list of process names, which does not keep file opened during editing. The list helps to decide e.g. when to auto-unlock the opened file - such file cannot be unlocked after last fs close, but we have to wait for closing the whole application.
You can add processes which are known to behave as described. For example if you want to add notepad++ application, because it is known it does not keep file opened during editing, you can do it like this:
<appsThatKeepFileClosedWhileEditing>
    <gen:newElement gen:guid="notepad+.exe" gen:val="notepad+.exe"/>
</appsThatKeepFileClosedWhileEditing>
Type List
Default Value TextEdit, Preview, Pages, Keynote, Numbers
Lock Level None
Example <appsThatKeepFileClosedWhileEditing>
   <!-- Add additional processes -->
   <gen:newElement gen:guid="NameOfProcess">
      <gen:value>NameOfProcess</gen:value>
   </gen:newElement>
   <!-- You can delete any of the predefined processes Preview and Numbers from the appsThatKeepFileClosedWhileEditing list by using the prefix "guid:" and the delimiter "|" -->
   <!-- <dellistedelements>guid:Preview|guid:Numbers</dellistedelements> -->
</appsThatKeepFileClosedWhileEditing>
Name manualLockTimeout
Description Timeout for manual lock. Note, that the server has right to override this value. In seconds
Type Longnum
Default Value 86400
Lock Level none
Name ignoreFileManagerDBFile
Description

When this value is set to true, the file manager's cache file is not created, read or written to. The name of the cachefile to ignore can be set using fileManagerDBFile config item e.g. the file named Thumbs.db

Currently this option should not be used on Mac - in other words this flag should stay set to false on Mac.

Type boolean
Default Value false
Lock Level none
Name FileManagerDBFile
Description The name of a file manager's file which is ignored by the Drive when the other config item ignoreFileManagerDBFile is set to true
Type string
Default Value  
Lock Level none
autolockSettings
Name lockTimeout
Description Time in seconds, after which the autolock on a file on the server expires. The value is sent to the server when locking a file. Note that WebDAV server may not respect this value and may use its own preferred value.
Type Longnum
Default Value 900
Lock Level Edition
Example <lockTimeout> <gen:value>900</gen:value> </lockTimeout>
Name refreshPeriod
Description The time in seconds after which the autolock is refreshed if a document is still opened.
Type Longnum
Default Value 300
Lock Level None
Example <refreshPeriod> <gen:value>300</gen:value> </refreshPeriod>
Name unblockFileAfterAppCloseTimeout
Description The time after which the file is considered to be really closed, measured since closure of the application used to edit the file.
Type longnum
Default Value 3
Lock Level None
Example <unblockFileAfterAppCloseTimeout> <gen:value>5</gen:value> </unblockFileAfterAppCloseTimeout>
Name normalUnlockDelay
Description The time after which the file is considered to be really closed. Measured since the close which makes the open count on the file equal zero. Applicable only to the processes not listed in appsThatKeepFileClosed list. For example after this timeout file is auto-unlocked.
Type longnum
Default Value 5
Lock Level None
Example <normalUnlockDelay><gen:value>6</gen:value></normalUnlockDelay>
Name neverLockList
Description A list of names of such processes, which will not autolock a file even if they open the file for writing. You can add new processes. For example if you want to add the file manager servant salamander, you can do it like this:
<neverLockList>
    <gen:newElement gen:guid="salamand.exe" gen:val="salamand.exe"/>
</neverLockList>
Type List
Default Value Finder, quicklookd, Preview, mv, cp
Lock Level None
Example <neverLockList>
    <!-- you can add and delete applications as in appsThatKeepFileClosedWhileEditing -->
    <gen:newElement gen:val="NameOfProcess" gen:guid="NameOfProcess"/>
    <!-- <gen:delListedElements>guid:Finder</gen:delListedElements> -->
</neverLockList>
Name alwaysLockList
Description A list of names of processes, for which autolocking will be invoked even if the file is opened only for read.
You can add processes. For example if you want to add application Notepad++, because it is known it does not keep file opened during editing, you can do it like this:
<alwaysLockList>
    <gen:newElement gen:guid="notepad+
Type List
Default Value TextEdit, Microsoft Word, Microsoft Excel, Microsoft PowerP, Pages, Keynote, Numbers
protocolSettings
Name connectTimeout
Description How long will Drive wait for server response on initial volume connect. In seconds.
Type integer
Default Value 10
Lock Level None
Example <connectTimeout> <gen:value>20</gen:value> </connectTimeout>
Name localConnectivityRecoveryTimeout
Description The timeout determines the maximum period for which the HTTP request might be postponed in case the local connectivity was lost. The local connectivity can be lost after resuming the computer from sleep mode or while switching between networks like Wi-Fi to Wi-Fi, Wi-Fi to Ethernet or Ethernet to Wi-Fi. Note that accidentally Java can cache negative DNS request for some period (by default 10 seconds: see the property sun.net.inetaddr.negative.ttl in java.security file) so this interval should be also taken into account.
Type integer
Default Value 30
Lock Level None
Name defaultMethodTimeout
Description How long will Drive wait for server response on a method. This value will be applied to all methods except those which have their explicit values listed in MethodTimeoutsList. In seconds.
Type integer
Default Value 30
Lock Level None
Example <defaultMethodTimeout>
   <gen:value>100</gen:value>
</defaultMethodTimeout>
timeoutRecord (template)
Name name
Description Method name (e.g. DELETE, PROPFIND)
Type string
Default Value none
Lock Level none
Name timeout
Description The value of timeout for this method. In seconds
defaultMethodTimeout is used if timeout for particular method is not set
Type integer
Default Value 0
Lock Level none
Name PROPFIND
Description The record of timeout for PROPFIND method. Defines the socket timeout for PROPFIND methods (SO_TIMEOUT), which is the timeout for waiting for data or, put differently, a maximum period inactivity between two consecutive data packets. A timeout value of zero is interpreted as an infinite timeout.
If this parameter is not set, defaultMethodTimeout is used
Type integer
Default Value 40
Lock Level none
Example <gen:updateElement gen:templateguid="Xythos;06:10:09 07:26:40 +0100;PROPFIND">
   <timeout gen:val="100"/>
</gen:updateElement>
Name DELETE
Description The record of timeout for DELETE method. Defines the socket timeout for DELETE methods (SO_TIMEOUT), which is the timeout for waiting for data or, put differently, a maximum period inactivity between two consecutive data packets. A timeout value of zero is interpreted as an infinite timeout.
If this parameter is not set, defaultMethodTimeout is used
Type integer
Default Value 45
Lock Level none
Example <gen:updateElement gen:templateguid="Xythos;06:10:09 07:28:30 +0100;DELETE">
   <timeout gen:val="100"/>
</gen:updateElement>
cacheSettings
Name cachedFileRetentionTime
Description Sets retention time for cached file
The retention time is the time before which newly downloaded/cached file can not be deleted during cache pruning. In minutes
Type integer
Default Value 15
Lock Level none
Name pruningMinimalTimeout
Description Minimal time after which XD cache pruning is started after previous prunning. In minutes.
Type string
Default Value 15
Lock Level None
Example <pruningMinimalTimeout><gen:value>15</gen:value></pruningMinimalTimeout>
Name cacheSize
Description Maximum cache size in megabytes (MB). The cache size can be temporarily greater than the value set here - e.g. due to working with a large file, which size is greater than the cacheSize. Note that the small cache size (which often leads to cache pruning) may result in very bad user experience.
Type integer
Default Value <cacheSize gen:val="512"/>
Name clearCacheOnServerDisconnect
Description If set to true, the cache from a server is cleared after disconnection from the server.
Type boolean
Default Value false
Lock Level None
Example <cacheSize><gen:value>1024</gen:value></cacheSize>
Name alwaysLocalFilesList
Description List of regular expressions. If a filename matches one of the expressions in this list, the file is considered to be local (is not uploaded).
You can add new regular expressions:
<alwaysLocalFilesList>
    <gen:newElement gen:guid="mytmp" gen:val=".*\.mytmp"/>
</alwaysLocalFilesList>
Type  
Default Value "(\.[^\.]*|\.\..+))" , "\.DS_Store" and "\.appdisk"
guid=.DS_Store val="\.DS_Store"
Name alwaysLocalDirectoriesList
Description List of regular expressions. If a directory name matches one of the expressions in this list, the directory is considered local (as well as its content). You can add new regular expressionss: <alwayslocalfileslist> <newelement gen:guid="mytmpdir" gen:val=".*\.mytmpdir"/> </alwayslocalfileslist>
You can add new regular expressions:
<alwaysLocalDirectoriesList>
   <gen:newElement gen:guid="mytmp" gen:val=".*\.mytmpdir"/>
</alwaysLocalDirectoriesList>
Type list
Default Values
  • \.TemporaryItems
  • \.Trashes
  • \.fseventsd
Lock Level none

 

appFiltersSettings
AppFilterInfo (template)
Name className
Description The full name of a class which implements com.xythos.client.drive.fs.filters.AppFilter interface.
For example "com.xythos.client.drive.fs.filters.AppFilterGeneric"
Type string
Default Value none
Lock Level none
Name OS
Description The OS for which should be the filter used if it is active (isActive is true)
Possible values:
  • Mac - will be used only when running Mac
  • Win - will be used only when running Win
  • General - will be used on every system
Type enum
Default Value none
Lock Level none
Name isActive
Description If true, this application filter will be used
Type boolean
Default Value true
Lock Level none
Name checkBeforeOpenTimeout
Description Filter can change the checkBeforeOpenTimeout otherwise gained from sharing level settings. In this way, different checkBeforeOpenTimeout for different applications and scenarios can be used
Time in milliseconds
Type integer
Default Value none
Lock Level none
Name uploadEmptyFile
Description If true, this filter will make sure no zero-length file will be uploaded when such file is created by scenario where this filter is involved
Type boolean
Default Value true
Lock Level none
Name delayedUploadTime
Description The time for which should be upload of a file delayed. It is common that editors creates temporary files which are created and immediattely deleted. If the time between creation and deletion of such file is lesser than the value of delayedUploadTime, no remote operation is issued
Time in milliseconds
Type integer
Default Value 0
Lock Level none
Name disabledApplications
Description List of applications for which the filter is disabled. If enabledApplications is defined then the filter will be used just with these apps. If disabledApplications is defined then the filter will be used for all applications excluding these. You can add the processes:
<disabledApplications>
    <gen:newElement gen:guid="notepad.exe" gen:val="notepad.exe"/>
</disabledApplications>
Type List
Default Value None
Lock Level None
Example <gen:updateElement gen:templateguid="Xythos;10:11:10 11:34:00 +0100;WinGeneric">
   <disabledApplications>
     <gen:newElement gen:val="NameOfProcess" gen:guid="NameOfProcess"/>
     <!-- <gen:delListedElements>guid:Explorer</gen:delListedElements> -->
   </disabledApplications>
</gen:updateElement>
Name enabledApplications
Description List of applications for which the filter is enabled. If enabledApplications is defined then the filter will be used just with these apps. If disabledApplications is defined then the filter will be used for all applications excluding these. You can add the processes:
<disabledApplications>
    <gen:newElement gen:guid="notepad.exe" gen:val="notepad.exe"/>
</disabledApplications>
Type List
Default Value None
Lock Level None
Example <gen:updateElement gen:templateguid="Xythos;10:11:10 11:34:00 +0100;WinGeneric">
   <enabledApplications>
     <gen:newElement gen:val="NameOfProcess" gen:guid="NameOfProcess"/>
     <!-- <gen:delListedElements>guid:Explorer</gen:delListedElements> -->
   </enabledApplications>
</gen:updateElement>
Name applicationDescription
Description Description of applications for which the filter should be applied
Type string
Default Value none
Lock Level none
Name tempFileRegexPatterns
Description List of regular expressions. If the lower case version of a file name matches a regex from this list, the file is considered to be a temporary file. Note that if a regex contains concrete alphabet characters they must be in the lower case like in the example below.
For example the modification of regex ".*\.TMP" or ".*\.Tmp" from the example below would not work for us.
Type string
Default Value none
Lock Level none
Example <tempFileRegexPatterns>
     <gen:newElement gen:guid="tempFile-*.tmp" gen:val=".*\.tmp"/>
</tempFileRegexPatterns>

Usage of Macros in Config

Introduction

The configuration files allow customers to change paths. These paths need to be absolute, which makes it difficult to specify a path that would work for multiple users because the paths usually differ by a user name or a user home folder, for example. To overcome this limitation, the Drive since version 1.7 allows usage of special values, macros.

Basic principles

Default macros list

Here is the list of default macros:

Macro name  Macro value  Macro value type (absolute path/single name)
%COMPANY_FOLDER%  company folder  single name
%SHORT_COMPANY_FOLDER%  short company folder  single name
%PRODUCT_FOLDER%  product folder  single name
%DOCUMENTS%  folder to store user's documents, like "My Documents"  absolute path
%APPLICATION_DATA%  roamable application data  absolute path
%LOCAL_APPLICATION_DATA%  non-roamable application data  absolute path
%COMMON_APPDATA%  application data folder shared by all users  absolute path
%DESKTOP%  current user's desktop folder  absolute path
%COMMON_DESKTOP%  all users common desktop  absolute path
%USER_HOME%  current user's home folder  absolute path
%TEMP%  default temporary directory  absolute path
%PROGRAM_FILES%  program files directory  absolute path
%COMMON_PROGRAM_FILES%     absolute path
%STARTUP%     absolute path
%COMMON_STARTUP%     absolute path
%LOG%  default log folder  absolute path
%USERS%  folder with all users accounts  absolute path
%USERNAME%  current user name  single name 

System environment variables

Besides the macros described above, it is possible to use all the system environment variables. All these variables have their macros formed by prefixing the name of the variable with SYSENV_ string. So for example if we want to use the TMP system environment variable in the config, we can do so by using macro named SYSENV_TMP. Following the same pattern one can use SYSENV_USERNAME macro for USERNAME variable, etc.

"gen:macros" attribute

The macros are expanded only if the node containing the value was enabled to use the macros. This can be done simply by adding xml attribute gen:macros (where gen is xml namespace "http://www.xythos.com/jconf/schema" as usual) to that particular xml node definition. The attribute can have either value "true" (to enable the expanding of macros) or "false" (to forbid the expanding). Moreover, the value has to be of the type STRING.

If you want to add or change a value containing a macro, you need to make sure the macro expanding is enabled for that value. If the value is not enabled in any higher-level config file, you need to add the gen:macros="true" next to the tag name, for example:

Enabling macro expansion when changing a value

...
<username gen:macros="true">
   <gen:value>%USERNAME%</gen:value>
</username>
...

Macro usage

Each macro starts and ends with "%" mark (as it can be seen in the table above in "Macro name" column). Currently it is possible to use macros from the list above anywhere under user settings node in the config.

Escaping "%" character

If it is necessary to use the "%" character in path, it needs to be escaped with another "%" character.

For example "/aaa/%%b" will be expanded to "/aaa/%b"

For example, user wants to change logging directory using macro to user's desktop folder.

There is "logDirectory" element in "userSettings" node (it is of string type and has the expanding of attributes enabled by gen:macros attribute in the main config file xdconfig.xml).
The default logging directory value for user "x" would look like:

 

Default logging directory on OS X

...
<logDirectory>
   <gen:value>C:\Documents and Settings\x\Local Settings\Temp\logs\Blackboard\Drive</gen:value>
</logDirectory>
...

We can change this default value to directory "logs" in user's desktop using macros in Blackboard Drive configuration file, for example xdconfig_customer.xml, like this:

Example of configuration file to change logging directory on Windows 7

 

<?xml version="1.0" encoding="UTF-8"?>
<gen:config xmlns:gen="http://www.xythos.com/jconf/schema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" gen:version="1">

  <xdConfig>
     <usersSettings>
       <userList>
         <gen:updateListType>
           <logDirectory>
             <gen:value>%DESKTOP%\xdlogs</gen:value>
           </logDirectory>
         </gen:updateListType>
       </userList>
    </usersSettings>
  </xdConfig>
</gen:config>
 

Example of configuration file to change logging directory on OS X

 

<?xml version="1.0" encoding="UTF-8"?>
<gen:config xmlns:gen="http://www.xythos.com/jconf/schema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" gen:version="1">

  <xdConfig>
     <usersSettings>
       <userList>
         <gen:updateListType>
           <logDirectory>
             <gen:value>%DESKTOP%/xdlogs</gen:value>
           </logDirectory>
         </gen:updateListType>
       </userList>
    </usersSettings>
  </xdConfig>
</gen:config>

When value of "logDirectory" is read at Blackboard Drive startup, the %DESKTOP% is expanded to user's desktop directory, e.g. "c:\Users\x\Desktop" on Windows 7 or "/Users/x/Desktop" on OS X, resulting in "c:\Users\x\Desktop\xdlogs" or "/Users/x/Desktop/xdlogs" respectively.