[Update November 2023]

From MicroStation 2023 and OpenX 2023 products onwards, we have introduced the Manage Configuration Utility that creates connections to one or more configurations, please follow the link for full details.

This results in ConfigurationSetup.cfg being used to redirect local machines to a networked source for the Manage Configuration settings, e.g.:

[General]
_USTN_USER_CONFIGURATION_LABEL=
_USTN_CUSTOM_CONFIGURATION=
MS_CONFIGURATIONXML_PATH = D:/_CONFIG_XML/M23/
# _USTN_RESTRICT_MANAGE_CONFIGURATION = 1

[SetConfiguration]
%if !defined (_USTN_USER_CONFIGURATION)
%if defined (_USTN_CUSTOM_CONFIGURATION) && ($(_USTN_CUSTOM_CONFIGURATION) != "") && exists ($(_USTN_CUSTOM_CONFIGURATION))
_USTN_CONFIGURATION = $(_USTN_INSTALLED_CONFIGURATION)
%endif

%endif

Optionally _USTN_RESTRICT_MANAGE_CONFIGURATION = 1 can be used to hide the Manage Configuration button from non-admin users.

Never edit anything below the [SetConfiguration] line, this will have unpredictable effects.

[Updated 31 March 2022]

We discourage manual editing of this file as it is written to by CONNECT Edition applications during active sessions, updating the value of _USTN_CONFIGURATION (in the [Set Configuration] section of the file) to correspond to the active WorkSpace selected in the User Interface.

In nearly all circumstances prior to MicroStation 2023 specifying the Custom Configuration via the installer User Interface is the only method that should be needed to change ConfigurationSetup.cfg for both manual and deployed installations:

Setting a path at this point in the installation results in that path being written to the [General] section of the file, e.g.:

_USTN_CUSTOM_CONFIGURATION=//HAL/configurations/MCE/

(The installer formats the input path)

If the location of the Custom Configuration changes after installation it is possible to modify this path via a text editor. This is not yet possible via the modify installation process.

Also see: CONNECT Edition - Custom Configuration - Part 1 : Initial Creation Steps

Manual editing steps

If an existing ConfigurationSetup.cfg does need to be modified refer to the active statements in the delivered file which are (from MicroStation 16.1 onwards; previously the _USTN_CONFIGURATION value was a hardcoded path):

[General]

_USTN_CUSTOM_CONFIGURATION=    

[SetConfiguration]

%if !defined (_USTN_USER_CONFIGURATION)

%if defined (_USTN_CUSTOM_CONFIGURATION) && ($(_USTN_CUSTOM_CONFIGURATION) != "") && exists ($(_USTN_CUSTOM_CONFIGURATION))

_USTN_CONFIGURATION = $(_USTN_CUSTOM_CONFIGURATION)

%endif

%endif

To manually edit the file:

1. In the [General] section go to the _USTN_CUSTOM_CONFIGURATION= statement then add enter the path to your Custom Configuration.
2. In the [Set Configuration] section, reset _USTN_CONFIGURATION to its default value pointing to the local example workspace, i.e.:
   _USTN_CONFIGURATION= $(_USTN_INSTALLED_CONFIGURATION)

Once edited the file can be distributed to users using methods described in CONNECT Edition - Deploying or Updating ConfigurationSetup.cfg

The three states of ConfigurationSetup.cfg

ConfigurationSetup.cfg is one of the few configuration files that MicroStation modified dynamically. Its contents store the active Configuration selected by a user. This is either the local Configuration on the C:\ drive (unless another installation location was specified) or the user organization’s Custom Configuration.

The file can existing in three states:

Out of the box ConfigurationSetup.cfg looks like this:

#----------------------------------------------------------------------

# ConfigurationSetup.cfg - Configures the root Configuration directory

# for Your Organization

#

# The main function of this configuration file is to allow user to specify

# the root Configuration directory to activate. The active Configuration

# directory is represented by _USTN_CONFIGURATION. By default, it points to

# the installed Configuration defined by _USTN_INSTALLED_CONFIGURATION,

# which can consist of example WorkSpaces and WorkSets.

# If your organization has its own Configuration directory, you can define

# _USTN_CUSTOM_CONFIGURATION to that directory path and use it as follows.

#

#_USTN_CUSTOM_CONFIGURATION = D:/.../MyConfiguration/

#_USTN_CONFIGURATION : ${_USTN_CUSTOM_CONFIGURATION}

#----------------------------------------------------------------------

#----------------------------------------------------------------------

# START: The section defines user selection at the time of installation.

# These lines are generated by installer.

[General]
_USTN_USER_CONFIGURATION_LABEL=

_USTN_CUSTOM_CONFIGURATION=

[SetConfiguration]

%if !defined (_USTN_USER_CONFIGURATION)

%if defined (_USTN_CUSTOM_CONFIGURATION) && ($(_USTN_CUSTOM_CONFIGURATION) != "") && exists ($(_USTN_CUSTOM_CONFIGURATION))

_USTN_CONFIGURATION = $(_USTN_CUSTOM_CONFIGURATION)

%endif

%endif

(Note that the optional use of _USTN_USER_CONFIGURATION_LABEL is described in Configuration Tips: What does _USTN_USER_CONFIGURATION do?)

The [SetConfiguration] section opens with a check that _USTN_USER_CONFIGURATION is not defined; if it is defined the whole [SetConfiguration] section is ignored and the application does not make any changes to the file.

If a Custom Configuration location is specified during installation (as described above), the specified value is written to the “_USTN_CUSTOM_CONFIGURATION=” statement, the [SetConfiguration] section takes effect and the application will look for the Custom Configuration at the location specified by the value of _USTN_CUSTOM_CONFIGURATION.

In the following example the Custom Configuration location \\server\CONFIGURATIONS\CE\ was entered during installation.

From the application UI the user selected the OpenBuildings Designer Example WorkSpace on the C:\ drive so the value of _USTN_CONFIGURATION in the [SetConfiguration] section was changed from $(_USTN_CUSTOM_CONFIGURATION) to $(_USTN_INSTALLED_CONFIGURATION):

#----------------------------------------------------------------------

# ConfigurationSetup.cfg - Configures the root Configuration directory

# for Your Organization

#

# The main function of this configuration file is to allow user to specify

# the root Configuration directory to activate. The active Configuration

# directory is represented by _USTN_CONFIGURATION. By default, it points to

# the installed Configuration defined by _USTN_INSTALLED_CONFIGURATION,

# which can consist of example WorkSpaces and WorkSets.

# If your organization has its own Configuration directory, you can define

# _USTN_CUSTOM_CONFIGURATION to that directory path and use it as follows.

#

#_USTN_CUSTOM_CONFIGURATION = D:/.../MyConfiguration/

#_USTN_CONFIGURATION : ${_USTN_CUSTOM_CONFIGURATION}

#----------------------------------------------------------------------

#----------------------------------------------------------------------

# START: The section defines user selection at the time of installation.

# These lines are generated by installer.

[General]

_USTN_CUSTOM_CONFIGURATION=//server/CONFIGURATIONS/CE/

[SetConfiguration]

%if !defined (_USTN_USER_CONFIGURATION)

%if defined (_USTN_CUSTOM_CONFIGURATION) && ($(_USTN_CUSTOM_CONFIGURATION) != "") && exists ($(_USTN_CUSTOM_CONFIGURATION))

_USTN_CONFIGURATION = $(_USTN_INSTALLED_CONFIGURATION)

%endif

%endif

Next, the user selected a WorkSpace located in the Custom Configuration, so the value of _USTN_CONFIGURATION in the [SetConfiguration] section was changed from $(_USTN_INSTALLED_CONFIGURATION) to $(_USTN_CUSTOM_CONFIGURATION):

#----------------------------------------------------------------------

# ConfigurationSetup.cfg - Configures the root Configuration directory

# for Your Organization

#

# The main function of this configuration file is to allow user to specify

# the root Configuration directory to activate. The active Configuration

# directory is represented by _USTN_CONFIGURATION. By default, it points to

# the installed Configuration defined by _USTN_INSTALLED_CONFIGURATION,

# which can consist of example WorkSpaces and WorkSets.

# If your organization has its own Configuration directory, you can define

# _USTN_CUSTOM_CONFIGURATION to that directory path and use it as follows.

#

#_USTN_CUSTOM_CONFIGURATION = D:/.../MyConfiguration/

#_USTN_CONFIGURATION : ${_USTN_CUSTOM_CONFIGURATION}

#----------------------------------------------------------------------

#----------------------------------------------------------------------

# START: The section defines user selection at the time of installation.

# These lines are generated by installer.

[General]

_USTN_CUSTOM_CONFIGURATION=//server/CONFIGURATIONS/CE/

[SetConfiguration]

%if !defined (_USTN_USER_CONFIGURATION)

%if defined (_USTN_CUSTOM_CONFIGURATION) && ($(_USTN_CUSTOM_CONFIGURATION) != "") && exists ($(_USTN_CUSTOM_CONFIGURATION))

_USTN_CONFIGURATION = $(_USTN_CUSTOM_CONFIGURATION)

%endif

%endif

Translated German Wiki article:
CONNECT Edition - Konfigurationstipps: Soll ich ConfigurationSetup.cfg bearbeiten?