Workgroups (XSISDK)

Table of contents


Be sure to read: Using Workgroups (

Installing to a workgroup

In versions of XSI, before v5.0, the emphasised mechanism for installing to a workgroup was via the .xsiaddon file. However with XSI v5.0 the workflow has been simplified by allowing creation of content directly onto a workgroup.

Most customization is now installed automatically once the file is found during XSI startup, so there is no need to go through a special "xsi -i" stage to get files properly registered.

Creating Content Directly on a Workgroup

Using the Plug-in Manager you can create toolbars, self-installed plug-ins and Shaders directly on a workgroup. It is recommended that you do this on a workgroup that is not in use by other users, e.g. a local workgroup or a development copy of the official workgroup.

Moving Tools from your User Directory to a Workgroup

The plug-in manager lets you drag and drop SPDLs, Self-Installed Plugins and other types of files from your user directory to a workgroup.

Or you can use the Windows Explorer, Command Line or some other tool to move the files directly. Workgroups and the User location support exactly the same directory structure.

You will tend to get a "conflict" situation if you copy the files rather than moving them. For example, if you copy a toolbar to a workgroup, XSI will continue to use the user location copy of that file.

Updating a Workgroup that is being used by other users

One challenge when using a workgroup that is shared between multiple users is the fact that DLLs and other files cannot be replaced while they are in use. So, if a developer fixes a bug in a shader and tries to update the .dll on the workgroup there may be a file access denied error if someone is actually using the shader.

This boils down to a basic problem of file sharing, the same problem would occur trying to replace any network based file that is being used by another user. In fact the same thing can happen on you own computer when an application tries to update a file that is being read by another application.

Note: XSI loads script files into memory and does not hold on to the file on disk after it has been read. So it is normally possible to update script-based plug-ins on a workgroup easily.

Here are some suggested workarounds. The most suitable approach will depend on the nature of the pipeline:

  • It is technically feasible to force XSI sessions off the network so that you can do an update. For example a Windows network share can be turned off, forcing connected users to disconnect. Talk to your IT person(s) about the least disruptive way to do this.
  • Send a mail to all users asking them to close XSI while an update to the workgroup is made. (This approach might be feasible for a small group, but would start to cause too much disruption for larger organizations).
  • Offer a distraction, such as free food or beer, and update the workgroup while users are away from their desks. You may find that different techniques are necessary to distract batch render boxes, but updates to RAM or Hard Drive space might do the trick.
  • Do workgroup development on a separate copy of the workgroup and make updates to the "production workgroup" when everything is totally tested and ready to go live. This will reduce the potential for conflicts during actual bug fixing and development.
  • Perform updates to the workgroup at times when no one is using XSI, perhaps based on batch scripts that runs during the early morning hours.
  • Build a new copy of the workgroup, which copies the entire workgroup but includes updated versions of the plugins. Once it is tested and ready, use a script or send instructions to the users to move to the new copy of the workgroup. Use a naming convention for the workgroups to make it easy to figure out the latest copy. Because harddisk space is not usually a limiting factor this can be a very practical solution because it completely bypassing the problem of updating files that are in use.
  • Use a separate copy of the workgroup for each user. There is a single "official" version of the workgroup, possibly under source control. The production machines run a script each day to update their local copy based on the official version. This script can be automated so that it occurs each morning before the user logs in. Although extra harddisk space is used, this approach has the advantage of increasing XSI speed because all workgroup content is cached locally.
  • Rather than replacing existing plug-ins add new plug-ins. This could get very messy if the number of updates is huge, but for occaisional use it might be helpful.
    • For self-installed C++ plug-ins leave the existing .DLL or .SO but update the XSILoadPlugin function to increase the version number, then recompile to a new file name and put it in the same directory. For clairity you may wish to encode the version number into the filename, for example Foo.1.0.dll becomes Foo.2.0.dll. This solution requires that each workgroup users has the plugin_manager.plugin_conflict_resolution preference set to "0", which is Conflict Resolution by Versioning (the default is "1" for Conflict Resolution by Origin Ordering). XSI will log messages warning about the conflict but will correctly use the plug-in with the highest version.
    • For Shaders and other SPDLS you will need to update the name of the file, the GUID of the SPDL, regenerate the Preset and compile a new DLL/SO also with a different filename. For example if fixing a shader "Foo", rename the project to generate "Foo2" and install that alongside Foo. Users would normally always apply the latest version of "Foo". This only works if you don't mind if existing Scenes continue to render with older versions of the shader.

Debugging a Slow Workgroup

Filemon ( is a useful free tool from the SysInternals website. It can show how XSI or any other application is accessing the network and local disk, to give you an idea what is going on if a workgroup seems too slow.

Workgroups and Mapped Network Drives

On windows you can map a network location onto a drive letter.

XSI will automatically remap any network location to the mapped drive, including workgroup paths.

The problem is that this sometimes cause the workgroup to misbehave.

Enable this preference to turn off the remapping of UNC Paths:

SetValue "preferences.data_management.use_unc_paths", True

Where is the list of workgroups persisted?

The workgroups are stored as a single string inside the preferences.

For example inside:


there will be a line similar to this:

data_management.workgroup_appl_path     = C:\local;!\\srv1\oldworkgroup;\\srv2\productions\tvshow_x\workgroup

XSI v5 tip: The "!" character at the beginning of a workgroup path means that it is disabled. XSI will not load this path as a workgroup but it will remember it.

Alternative Preference File

XSI will load any .xsipref file it finds in the \Data\Preferences directory of the user or factory location. So, for convenience, you could generate and store the workgroup path in a preference file of its own. This would work best in scenarios where you don't expect the users to connect and disconnect from workgroups themselves and want to establish the correct workgroups through configuration scripts.

Environmental Variables

Starting with XSI v5.0, you can specify Environmental Variables in your Workgroup paths. XSI always shows the fully resolved path in user interface, but it will remember the original environmental variable as its persisted value. This can be useful if you want to control aspects of your pipeline by changing environmental variables. Alternatively you can automate a users workgroup settings by changing the contents of the workgroup preference file, via an XSI script or via the "xsi -w" command line option.

Remember that XSI uses a linux style syntax for environmental variables in paths, even on windows.

Mental Ray shaders used inside a distribute rendering pipe for XSI 4.2

If you're interrested to add MR slave to your workstation. Be on the lookout, if you're dealing with custom shaders residing inside workgroup, that these shaders will need to be communicate to the MR slave machines.

For this only case scenario, for each slave machine, you would need to edit the file located under $XSI_LOCATION/Application/bin and add the env variable call XSI_WORKGROUP_SHADERPLUGINS and defined it's value to be the location of your workgroup where the shader reside.

(Starting with XSI 5.0 this configuration is not necessary, as XSI will send the full shader path to each slave. However this implies that all shaders must be visible through an identical path, e.g. on the network)

Storing Plug-ins Inside an XSI Project

This example relies on siOpenProjectWorkgroup event, which is only available starting XSI v5.1

Use this plug-in to automatically associate a workgroup with each XSI Project.

// ProjectWorkgroups Plug-in
// This Plug-in lets you automatically load and unload workgroups
// that are associated with the concept of XSI projects.  
// This is a common request because certain Custom Properties, 
// Custom Operators, toolbars, shaders and other content are often 
// associated with a specific project and are only needed when 
// working on scenes associated with that project.  With this
// plug-in installed the workgroup associated with the project
// is automatically loaded as soon as any scene is opened within 
// that project.
// For this plug-in to work you just need to create an (optional)
// workgroup within the project structure, using a specific
// naming convention.
// For example if you have two projects:
// 		c:\projects\ActionFilm
// and
// 		\\netserver\Projects\Drama
// Then you can associated workgroups with these projects by creating:
// 		c:\projects\ActionFilm\workgroup
// and
// 		\\netserver\Projects\Drama\workgroup
// Note: This plug-in does not prevent you from having other workgroup
// connections that are not project related.  For example
// custom commands shared by all projects can be stored into a separate 
// workgroup that does not follow the naming convention expected by this plug-in.

//Note: the expected folder name can be customized
var strWorkgroupFoldername = "workgroup" ;

function XSILoadPlugin( in_reg )
	in_reg.Author = "Softimage";
	in_reg.Name = "ProjectWorkgroups Plug-in";
	in_reg.Major = 1;
	in_reg.Minor = 0;

	//RegistrationInsertionPoint - do not remove this line

	return true;

function siOpenProjectWorkgroup_OnEvent( ctxt )

	// Workgroup is found within the project structure	
	strOldProjectWorkgroup = XSIUtils.BuildPath(
					strWorkgroupFoldername) ;
	strNewProjectWorkgroup = XSIUtils.BuildPath(
					strWorkgroupFoldername) ;

	var f = new ActiveXObject( "Scripting.FileSystemObject" ) ;
	// Unload old workgroup, if found		
	if ( f.FolderExists( strOldProjectWorkgroup ) )
			Application.RemoveWorkgroup( strOldProjectWorkgroup ) ;			
			Application.LogMessage( "Unloaded project workgroup : " 
							+ strOldProjectWorkgroup, siInfo ) ;
			// Probably the workgroup had never been loaded,
			// e.g. if this event was muted when projects were changed			
		// Verbose debugging info
			"siOpenProjectWorkgroup - no workgroup found to unload inside " 
			+ ctxt.GetAttribute("OldProjectPath"),
			siVerbose ) ;

	if ( f.FolderExists( strNewProjectWorkgroup ) )
			Application.AddWorkgroup( strNewProjectWorkgroup ) ;	
			Application.LogMessage( "Loaded project workgroup " 
							+ strNewProjectWorkgroup, 
							siInfo ) ;
			// Unexpected
			Application.LogMessage( "Failure to load project workgroup " 
							+ strNewProjectWorkgroup + " " + e.description , 
							siError	) ;
			"siOpenProjectWorkgroup - no workgroup found inside " 
			+ ctxt.GetAttribute("NewProjectPath"),
			siVerbose ) ;

	return true;

This page was last modified 15:46, 24 Mar 2006.
This page has been accessed 19153 times.

© Copyright 2009 Autodesk Inc. All Rights Reserved. Privacy Policy | Legal Notices and Trademarks | Report Piracy