Creating a shared multi-user configuration

Creating a shared multi-user configuration

The multi-tier approach to configuration properties enables a project or system administrator to provide a set of configuration properties (code-generation rules for example) for all users of the installation. By marking some configuration options as final at the Default (installation-wide) level or project level, an administrator can prevent users from overriding the configuration settings. Options not marked final leave individual users free to use their own settings. There are two basic scenarios for shared configurations:

Together runs on a server, all users access the server installation's global configuration settings which merge with individual settings at runtime:

Together runs on individual workstations and users share a centralized set of global configuration properties which merge with individual settings at runtime:

Shared configuration for a server-based installation

To set up a server-based configuration for a shared installation:

The administrator or manager (ADMIN) should run Together on the server console and edit the configuration options as described in the following configuration topics, marking as final those options that individual users may not override :
If additional one or more additional configuration levels are desired, create them as described below in Adding new levels.
Next, the ADMIN should make a copy of the ./config directory (and the properties directories of any added configuration levels) for each user of the shared installation. This copy can reside on the user's local drive or on the network in a separate folder intended for an individual user.
Finally, the ADMIN should create a start-up batch or command file for each user that launches the shared Together application from the command line. This file should be installed to the user's computer.

To get server-based installation with developer-specific configuration settings, see Modifying the default configuration levels below.

For information on launching Together from the command line, see Reference: Command Line Parameters.

Sharing configuration among workstation installations

It is also possible for multiple users with their own copies of Together running on separate workstations to access a shared multi-level configuration. In this case, the configuration properties customized by an administrator or manager reside in a centrally accessible location on the network. Individual users launch Together from a batch or command file specifying the path to the central configuration using the -config.path command-line switch.

To set up a multi-workstation shared configuration for a shared installation:

Install Together to the ADMIN's workstation. Make a back-up copy of the original config directory of the Together installation.
ADMIN runs Together on the ADMIN workstation.
If additional configuration levels are desired, ADMIN should create these as described in Adding new levels below.
Open the Options dialog, click Advanced, and edit any or all configuration options. Mark individual options as final at the desired level for those options that you don't want to allow individual users to override from a "lower" level. (For example, you could mark code-gen Blueprints options as final at the Default level so they can't be changed for a specific project at the Project level.)
Next, ADMIN should copy the modified ./config directory (plus any additional directories created for added config levels) to a shared network location (e.g. <server>/tg_shared_config) that is accessible to all Together users who should use this configuration.

Creating the start-up pointer file

When the entire configuration is to be centrally shared, it's necessary to create pointer file to define the centralized location and override Together's hard-coded configuration locations. Once it is created and the correct location(s) defined, you need to reference the pointer file in the -config.path switch when you start Together from the command line (or a batch or command file). The easiest way to create the pointer file is to let Together generate a copy of its on defaults.

To generate a default pointer file:

Run the Together launcher for your OS and pass -debug.config.saveDefaultPath=<path to file> in the command line. For example: Together.exe -debug.config.saveDefaultPath=c:\Together3.1\lib\pointer.config
Together starts up and writes the specified file to disk. You can then close Together.

The file name is just a suggestion. You can name it anything that doesn't conflict with Together's property file names. You can store the pointer file anywhere but it's probably most convenient to keep it in the ./lib directory of each local installation. Immediately after you generate it, the pointer.config file will contain the following lines:

config.level.$internal.group = basic

config.level.$internal.0 = $TOGETHER_LIB$/internal.config

config.level.$internal.1 = $TOGETHER_LIB$/path.config

config.level.$default.group = session

config.level.$default.0 = $TOGETHER_CONFIG$/*.config

config.level.$default.write = $TOGETHER_CONFIG$/changes.config

config.level.$commandLine.group = basic

config.level.$project.group = project

config.level.$workspace.group = project

config.level.$workspace.0 = $PROJECT_DIR$/*.config

config.level.$workspace.write = $PROJECT_DIR$/$PROJECT_NAME$.tws

The highlighted lines are the ones you need to edit to point to your shared configuration. Note that paths must reference mapped drives (\\appserver\tg_shared_config\*.config will not work, for example). Thus, if your shared configuration is on appserver, and that is locally mapped to drive s:, then the edited lines would look like this (Windows style paths shown):

config.level.$default.0 = s:\tg_shared_config\*.config

config.level.$default.write = s:\tg_shared_config\changes.config

Launching via the command line and pointer file

Finally, ADMIN should create for each user, or instruct each user to create on their workstation, a start-up batch or command file that launches Together locally from the command line using the -config.path switch to specify the path to the pointer file. In Windows, the command would look something like this: c:\Together3.1\bin\Together.exe -config.path=c:\Together3.1\lib\pointer.config

For more information on launching Together from the command line, see Reference: Command Line Parameters.

Adding new levels to the predefined ones

It is possible to add up to three additional configuration levels to the pre-defined ones (i.e. Default, Project, and Diagram). For example, a Corporate level could be added to enforce certain configuration settings across the enterprise. As a simple example: you could define the File prologue option in Source Code options so that all generated source code files contain the corporate copyright. Marking this final at the Corporate level prevents changes from lower levels. New levels can only be inserted above the installation-wide Default level in Options Dialog order.

To add configuration levels, you must do two things:

Copy the contents of the $TOGETHER_HOME$/config directory to some other location to create a separate set of configuration properties for the new level. This could be a shared network location (as described in the previous section) or a local directory in your Together installation (e.g. config/corporate).
Create a file path.config file in the ./lib directory and point it to the directory you set up for the new level(s) . Together searches this file and loads additional configuration levels from the location(s) specified. If the location in 1 above is shared, be sure to do this second step on all the local machines that need to share the configuration.

Adding new properties directories to a shared location

If you are creating the new level(s) for a configuration that will be shared from a central location, you must create a set of configuration properties files for each new configuration level. To do this:

Copy the ./config directory of your Together installation to the shared location and rename it tg_shared_config (or some other meaningful name).
For each configuration level you plan to add, copy the ./config directory of your Together installation to a new subdirectory of tg_shared_config . Rename each new subdirectory with the name of the level it represents. For example, tg_shared_config/corporate.

TIP: You may find it easier to create the subdirectory(ies) under your local config directory, test that you have defined the new level(s) correctly, and then copy the config structure to the shared location and modify the levels from there.

Adding new properties directories to a local installation

If you are creating the new level(s) for a configuration on a local installation:

Copy the ./config directory of your Together installation some other location and rename it with the name of the level it represents. For example, ./config/corporate.

For example, to create a Corporate configuration level, you first copy everything in the config directory to some other directory... let's say $TOGETHER_HOME$/config/corporate.

Creating the path.config file

Use a text editor to create the file $TOGETHER_HOME$/lib/path.config (check to see that someone else hasn't already created it). If you are setting up a shared configuration, you'll need to place a copy of this file in the Together installation of all users.

Add the following lines to the file:

=== path.config ===

optionsEditor.level.$corporate.name = Corporate

optionsEditor.level.$corporate.visible = true

config.level.$corporate.name = Corporate

config.level.$corporate.visible = true

config.level.$corporate.0 = <path to this level>

=== path.config ===

Replace <path to this level> with the path to the properties files for the level you are defining; for example $TOGETHER_CONFIG/corporate/*.config).

TIP: Note that config.level.<level name>.<number> = <path> defines the source for config files. For shared locations, use the full path. For local paths, specify the full path if outside your Together installation; within that structure you can substitute an appropriate Together System Macro ($TOGETHER_LIB$, $TOGETHER_CONFIG$, $TOGETHER_HOME$ for example) part of the pathspec.

If you are adding more than one level, you must add some additional lines for each one. For example, to add a Division level:

...

optionsEditor.level.$division.name = Division

optionsEditor.level.$division.visible = true

config.level.$division.name = Division

config.level.$division.visible = true

config.level.$division.1 = $TOGETHER_CONFIG$/division/*.config

Viewing the added configuration level(s)

To verify that you have correctly added a new level, run Together and choose Options | Default on the main menu. Click the Advanced button to see the levels. (If you created the new levels in a shared location, you'll need to launch Together from the command line specifying the path to the configuration.)

In the case of our Corporate example, you should see the new 0. Corporate level in the left column:

Added Corporate configuration level in Options dialog's advanced mode

In this way you can configure local installations to include company-wide configuration. Company-wide levels will be configured through path.config, and installation-wide Default level will become user-specific.

Modifying the default configuration levels

To get server installation with user-specific configuration, the entire configuration order should be redefined. Together has command line parameter -config.path=<path to file which defines all levels>. This option overrides hardcoded levels configuration.

To get the hardcoded settings written to a file, pass -debug.config.saveDefaultPath=<path to file> in the command line. You will get a file which can be used in the config.path option to set the default behavior. This file can be modified to add new levels.

To make level visible in the Options dialog, you should add more lines to config (e.g. misc.config ):

optionsEditor.level.$corporate.name = Corporate

optionsEditor.level.$corporate.visible = true

optionsEditor.level.$department.name = Department

optionsEditor.level.$department.visible = true

[...].name is optional. If absent, the internal name will be shown ("corporate").

[...].visible is necessary, because the level is not visible by default.