Settings Management

Revolution Design software uses a robust settings module that allows easy management of user settings, even after the initial install.

This page explains the process of ‘pushing’ settings to end user machines after the initial install. The process for deployment to new installs is very similar; more information on that can be found on the deployment page.

Important = Important Note

Settings XML file

Creating the Settings File

In order to deploy settings and licensing you need to start by creating the XML settings file that you will deploy. The best way to begin is to install the software on a single machine, start it, and use the UI to modify the settings until they match what you would like to deploy.

Once you have the settings how you want them you will need to locate the settings file on the setup machine. Settings files can be found in a sub folder of C:\Users\{username}\AppData\Roaming\Revolution Design Important Note. Software specific sub folders are as follows:

  • Keynote Manager – Keynote Manager\{version}\Keynote Manager_Settings.xmlImportant Note
  • Revit workFlow – Workflow\{version}\workFlow_Settings.xmlImportant Note
  • Selection Master – Selection Master\{version}\Selection Master_Settings.xmlImportant Note

 

Modifying Settings Important Note

After creation of the initial settings file, the file can be modified in several ways:

  • Environment Variables – Some settings contain user specific paths, creating different text on each users machine. In this case, environment variables can be entered in the deployment file. These environment variables will be expanded when the software first starts and the correct path will be inserted.
  • Partial Files – The settings file may be modified to deploy only specific settings. You may purge the file of any settings that you do not wish to deploy simply by deleting the XML nodes for undesired settings. For example, if you only wish to deploy a new license key you can delete all other setting nodes in the file causing only the new license key to be deployed and all other user settings to remain as they are.

Here are a few common non-UI settings that you may need or want to set:

  • Licensing – Both standalone and portable licenses can be deployed and silently activated thought he settings file (please make sure your company account allows key based activation or this will not work). Simply enter your key in the ‘Stored Activation Key’ setting and the software will automatically attempt to activate your license on first startup.
  • Locking – To lock a setting simply set the ‘Locked’ attribute to ‘True’. This will disable changing the setting in the program UI. Note that this will not prevent users from finding the settings xml file and unlocking it, but they will not be able to change the setting through the UI.

For ‘collection’ settings types there are several more options to allow more control over user settings. You can recognize collection type settigs by the value of the XML attribute ‘StorageType’; collection types will have a value of either ‘asList’, ‘asSettingCollection’, or ‘asObservableCollection’ (the differences are internal code requirements and do not effect deployment). The following tools are available for collection types:

  • Push Type – You will notice that each collection type setting node also has an XML attribute named ‘PushType’. The value of this attribute determines how the list in your deployment file will interact with the list that may already be in the users settings file. There are only two valid values for this attribute:
    • Merge – This is the default value and it will merge your list with the users list and the end list will be all the unique values from the combined lists. You can use this to insure that the user has a specified standard list of settign values without removing any custom values they may have added to the list. For example if you wish to make sure that Keynote Manager users have a specific list of office standard master files but don’t want to remove any project specific master files they may have added you should set the push type to merge.
    • Overwrite – This option allows you to completely overwrite the users settings with the values you have in the deployment file. Deploying with overwrite will remove any custom values the user may have entered that are not in your deployment file.
  • Value Attributes – For settings that are ‘asList’ or ‘asObservableCollection’ there are a few additional options for controlling the list of values (asSettingCollection holds a list of settings that have their own overrides per the above so this section is not relevant for them). If the push type of any of these setting nodes is set to ‘Merge’ the following attributes can be added to its ‘Value’ nodes to modify the way they are imported.
    • Replace – This attribute allows you to replace a specific value with a new value. If you do not wish to remove all the users custom values but wish to replace a previous standard value with a new one you can use the replace attribute. The name of the attribute should be ‘Replace’ and the value should be the value you are wishing to replace. For example, if you wish to replace a value of ‘ABC’ with ‘DEF’ the node would look like <Value Replace=”ABC”>DEF</Value>. If the replaced value does not exist in the users settings file, the new value is added and the replaced value is ignored.
    • Index – This value allows you to control the order of the values in the final settings file. The value of this attribute should be an integer and should be the final 0 based index (0 is the first item, 1 is the second, etc.) of the value in the list. If this valueis negative or the attribute doesn’t exist the value will be placed at the end of the list which is the default. If the index is larger than the total number of items in the collection it will be added to the end of the list. If you want to place the value ‘ABC’ at the beginning of the list (before any user custom values) you the node would look like <Value Index=”0″>ABC</Value>.

Pushing Settings to Users

‘Forced’ vs. ‘Soft’ Push

Settings can be pushed in one of two ways:

  • Soft Push –  With a soft push the settings essentially become a machine default, but users that already have settings in their profile retain their current settings; only new users or those without settings already defined will get the updated setting values.
  • Forced Push – A force push allows the manager to overwrite settings for all users on the machine regardless if that user already has a setting value or not.  With this mode the pushed settings will be the machine default for new users AND will overwrite any values of that setting for existing users.

As soft push is the default, no additional steps need to be done to create a soft push, simply deploy the file as specified below.  For a forced push, you will need to add the attribute ‘Force’ (if it doesn’t already exist) and set it to true.  Note that since settings are hierarchical, setting force to true on a setting that has sub-settings will effectively set it to true on the entire branch.  This value can also be set on the root ‘RDSettings’ node to force all settings in the file without having to add this attribute to each individually.

As an example, if you wish to push a setting that looks like this:

    <Setting Value=”False” StorageType=”asBoolean” Name=”Use Reporting” Locked=”False” />

It should be updated to look like this:

<Setting Value=”False” StorageType=”asBoolean” Name=”Use Reporting” Locked=”False” Force=”True” />

 

Deploying Settings

Once the settings file is ready to deploy, it must be deployed to end user machines; this can be done via manual copy or through a script or other deployment system that copies the file to the target machine. The settings file can be copied to several locations with slightly different results:

  • User Folder – The settings file can be copied directly into the location shown above for each user on the machine that will use the software.  However, it is not recommended that you deploy to the user folder for post-install settings deployments as it will completely overwrite all settings the user had customized (unless of course you are trying to completely remove all user set values).
  • All Users Folder – The settings file can be deployed to the all users folder. Program specific folders for all users are the same as the user folder location, but they are based in C:\ProgramData, so simply use the format C:\ProgramData\Revolution Design\{Software path from above}.  Note that this folder will not be created by Keynote Manager or its installer, you will need to create this folder to deploy here. This location will cause the settings file to become a machine default for all new users or users that have not used the software previously. Upon the next restart of the program (Revit or Keynote Manager) the program will recognize that new settings have been deployed and will merge values into the user folder settings file (or copy them there if this is a first run of the program for the current user).
  • Execution Folder – The settings file can be copied into the executing directory of the program with the same result as the all users folder.  NOTE: The executing directory is no longer recommended for deployments. Due to Revit API constraints installations must place files into multiple folders which would require deployment of settings to each of these folders for effective deployment.