Creating and Using Workgroups

Workgroups provide a method for easily sharing customizations among a group of people working on the same project. Anybody accessing the workgroup can take advantage of any customizations installed there, including presets, commands, operators, add-ons, shaders, toolbars, views, layouts, and more.

The main tool for managing workgroups is the Plug-in Manager: choose File Plug-in Manager and click on the Workgroups tab. For more information about the Plug-in Manager in general, see Plug-in Manager.

About Workgroups

Workgroup Directory Structure

A workgroup is simply a file folder with subfolders that mirror the structure found in a user location:

  • The Addons folder holds items that have been packaged and installed as add-ons in various subfolders. An add-on is like a small workgroup within a workgroup that helps to keep your plug-ins organized.

  • The Application folder holds subfolders for toolbars, views, layouts, plug-ins, key maps, and similar items.

  • The Data folder holds subfolders for presets, scripts, and similar items.

Multiple Workgroups

You can connect to multiple workgroups at the same time. The first workgroup in the list is the default path for new elements. This is the path that is used when you choose Workgroup from the Paths button in the browser. It is also the only workgroup where you can install or uninstall .xsiaddon files.

Resolving Plug-in Conflicts

Plug-in conflicts occur when Softimage finds multiple versions of the same self-installing plug-in. Softimage can resolve a plug-in conflict in either of two ways:

  • Versioning: Softimage loads the most recent version of the plug-in.

  • Origin Ordering: Softimage loads the plug-in from the location with the highest precedence.

By default, Softimage tries to load the most recent version of a self-installing plug-in. For example, if your User location contains version 1.2 of a plug-in, and a workgroup contains 1.3, then Softimage loads version 1.3. If all copies of a plug-in are the same version, then Softimage uses origin ordering to resolve the conflict.

You can change how Softimage resolves conflicts by setting the Plug-in Manager preference named Conflict Resolution.

For non-self-installing plug-ins and other customizations, Softimage uses origin ordering and loads the first copy of the plug-in that it finds.

When Softimage searches for plug-ins, it first searches custom locations, then the user path, then the workgroups, and finally the factory path:

  1. Custom locations. Custom locations are the paths specified by the XSI_PLUGINS environment variable.

  2. User location. Add-ons in the User location are loaded after any other plug-ins found in the User location (for example, plug-ins in %XSI_USERHOME%\Application\Plugins are loaded before plug-ins in%XSI_USERHOME%\Addons).

  3. Workgroups. Softimage searches workgroups in the order they are listed in the Plug-in Manager (so the first workgroup in the list takes precedence).

    Add-ons in a workgroup are loaded after any other plug-ins found in the workgroup (for example, plug-ins in MyWorkgroup\Application\Plugins are loaded before plug-ins in MyWorkgroup\Addons).

  4. Factory location. This is the directory in which Softimage is installed.

Using Workgroups

One workflow for using workgroups is for a developer or technical director to develop customizations in his or her user directory or a private workgroup. Once the customizations are tested and working properly, they can be copied to a shared workgroup by dragging and dropping on the Tree tab of the Plug-in Manager.

If the customizations need to be updated, the developer or technical director modifies the files in the user location or private workgroup. He or she can develop, test, and debug the customizations while everyone else still has access to the previous version in the shared workgroup. Once the changes are ready, he or she can copy the updated version to the shared workgroup.

Softimage automatically scans the workgroup paths at startup, so new or updated plug-ins will be available when users restart Softimage. Alternatively, users can click Update All on the Tree tab of the Plug-in Manager without restarting Softimage. They can also choose FileRescan on the Workgroup tab — this performs a more complete unload and reload of all the workgroups and is only necessary to ensure that the plug-ins are loaded exactly with the order of priority described in Resolving Plug-in Conflicts. Restarting Softimage is required only for layouts, UFOs, devices, and old-style (non-self-installing) custom commands.

Another approach is to put the workgroup in some form of version control. Users can synchronize with a stable branch and connect to the local copy, while the developer or technical director works on a development branch.

Creating a Workgroup

You can create a workgroup using the Plug-in Manager.

To create a workgroup

  1. On the Workgroups tab of the Plug-in Manager, choose File Create.

  2. In the Create Workgroup dialog box:

    • Enter a name for the workgroup directory in Workgroup Folder Name.

    • Enter the base path for the workgroup in Location of Workgroup, or click the Browse button select a location.

    • Full Workgroup Path shows the complete path of the workgroup (location and name).

  3. Click OK. The workgroup and its subfolders are created, and the workgroup is automatically connected.

  4. Get the members of your workgroup to connect to the workgroup path as described in Connecting to a Workgroup. They now have access to all the customizations in the workgroup.

Connecting to a Workgroup

The workgroup path is stored in each user's Data Management preferences. However, it is more convenient to use the Plug-in Manager to connect and disconnect workgroups.

To connect to a workgroup

  1. On the Workgroups tab of the Plug-in Manager, click Connect.

  2. Enter the path to the workgroup directory or click the browse button to find and select it, and click OK.

    You can reference environment variables using the Linux-style syntax, for example:


    The workgroup is scanned, and most plug-ins that it contains become available immediately.

  • If a workgroup contains SPDL files, then make sure you have permission to install software on your machine (write access to the HKEY_LOCAL_MACHINE section of the registry) when you first connect to the workgroup. Otherwise, SPDL files in the workgroup are not installed and hence not accessible. You also require this permission each time new SPDLs are installed to the workgroup (whether alone or as part of an add-on).

  • If there are any problems with SPDL files not working over the workgroup, delete the \Application\spdl.xsiindex file in the user directory. This causes a more complete reinstallation of the workgroup SPDL files when Softimage is restarted.

  • In some situations, antivirus software can interfere with SPDL registration.

  • Old-style (non-self-installing) commands and events stored in the workgroup path will not work unless your environment is homogeneous — that is, all Windows or all Linux.

  • You should not use the factory path for a workgroup.

To connect to a workgroup from the command line

You can also start Softimage and set the workgroup to a given path at startup. For example:

xsi -w $wglocation

To connect to a workgroup using a data file

An alternative way of managing workgroups is to store the workgroup paths to which you want to connect in a file called and then place this file in the Data folder of the Softimage installation (Factory) location or User location. Softimage automatically scans these locations at startup and if this file is found, Softimage will connect to the workgroup path of each entry it finds.

The file is a simple text file that can contain multiple directory paths. Each path must be added on a separate line and each line must end with a newline character.

To change the order of workgroups

  1. On the Workgroups tab of the Plug-in Manager, click on a workgroup to select it in the list.

  2. Click Move Up or Move Down until the workgroup is in the desired position. Remember that the first workgroup in the list is the default path for new elements. It is also the only workgroup where you can install or uninstall .xsiaddon files.

To disconnect from a workgroup

  1. On the Workgroups tab of the Plug-in Manager, click on the workgroup to select it in the list.

  2. Choose Selection Disconnect.

    Any plug-ins in the workgroup are unloaded and no longer available.

To temporarily disable a workgroup

  • On the Workgroups tab of the Plug-in Manager, click to remove the check next to the workgroup's path. This is equivalent to placing an exclamation mark (!) at the beginning of the workgroup's path in your Data Management preferences.

    Any plug-ins in the workgroup are unloaded and no longer available. However, you can easily re-enable the workgroup by clicking to add the check back.

SDK Example Workgroup

The SDK example workgroup contains many sample customizations that you can use, study, or adapt for your own purposes. See Softimage SDK Examples [SDK Guide].