Substation CONNECT Edition Deployment Guide:ProjectWise Managed Configuration

Before You Begin

A fully operational and configured ProjectWise Design Integration CONNECT Edition server and a defined datasource must be available. Access to ProjectWise Administrator CE and the ProjectWise Explorer CE applications with corresponding administrator privileges is also required. Please consult your ProjectWise implementation team and/or administrators before initiating ProjectWise Manage WorkSpaces

It is recommended the enable the “Force case-insensitive search” option in the datasource settings in ProjectWise administrator (see settings options below). Substation configurations and the Microsoft OS are case insensitive. By default, ProjectWise is delivered with case sensitivity. If the option to “Force case-insensitive search” is not enabled for the ProjectWise datasource, the managed workspace may experience issues resolving files from the configuration files that do not exactly match the case used in the file name.

ProjectWise Explorer CE Client must be installed to include the iDesktop Integration for Bentley Application Base Integration, to fully support Substation CE application integration for a ProjectWise Managed Configuration.

Install and configure Substation onto a client workstation. This will ensure that the application workspace has all the required components for your application prior to importing it into ProjectWise. Use this client to complete the instructions in this document.

Desktop integration:

As previously mentioned, when working with ProjectWise Managed Configuration, it is highly recommended that users access files through the ProjectWise Explorer and not through application shortcuts in the start menu, quick launch toolbar, or desktop. Therefore, unlike MicroStation, ProjectWise Desktop integration is disabled by default within Substation

Overview of Steps:

1. Import WorkSpace & Dataset files into PW, Managed Configuration Import Wizard

2. Add/Edit ProjectWise CSBs 3. Add Exclusions4. ProjectWise Application Definition 5. Link CSBs to Project folders 6. Test/Validate 7. Troubleshooting

Step 1: Import WorkSpace & Dataset files into PW, Managed Configuration Import Wizard

1. In ProjectWise Administrator, under WorkSpaces >Managed (Right-Click) and select “Import Managed Configuration”. This will open the Import Managed Configuration Wizard. In the Welcome dialog, Click Next

2. On the Choose Desired Action page, select the second option "Import Data to ProjectWise from File System", Then click Next

3. On the Import and Validate ProjectWise Folder Structure and Documents page, select the workspace to import in the Local File System list

Default workspace paths:

Windows 8/Windows 10 - - C:\ProgramData\Bentley\Bentley Substation CONNECT Edition\Configuration

Then in the ProjectWise list, select the folder to import the workspace into. If the folder does not exist yet, you can right-click in the list and select New Folder to create one.

In your ProjectWise repository, create a folder that will contain the Configuration to manage. For the purpose of this document define a directory called "Substation CE Managed Configuration"

Once you have selected a folder on both sides of the lists, click the Map button that is between the two lists, this will enable the Validate option.

4. Click Validate.

During the validation process, the wizard compares the content of the local workspace with the contents stored in ProjectWise. Since this is a fresh install, there shouldn’t be any files with which to compare and this process should be rather quick. In the future, you can use this utility to update a workspace and/or dataset. It will compare the two directories and identify whether files exist or not. It does not compare the contents of the file, only whether the files exist or not.

Once the validation is complete, the Validation of File System Structure against ProjectWise dialog opens.

The tree structure in the left-hand panel will display the status of each item as either present or not present in the ProjectWise repository. Items with a red ‘X’ indicates the file/folder is not present in the ProjectWise repository, while the green check indicates it is present in ProjectWise repository. Select an item in the list on the left to see what the status of the item is in ProjectWise. Since this is a fresh install, the entire workspace will be marked as not present.

For the purpose of this document, we will NOT import the entire configuration. While it is acceptable to import the configuration in its entirety, it may be somewhat unnecessary. We can streamline the configuration by importing only what is necessary. Reducing the number of files being exchanged between the ProjectWise datasource and local machine translates into shorter download times and greater performance for your users. For Substation, we only need to be concerned about three items; the “Datasets”, specific “WorkSpaces” and its associated “WorkSets”.

The WorkSpace configuration files and the WorkSet configuration files need to be available in the ProjectWise repository. The Configuration files are copied to the users local working directory and are processed when Substation is started.

Select the “Datasets”, “Organization” and “Workspaces/Substation Example” directories and their corresponding configuration files. Click Resolve to import the selected items into ProjectWise.

5. When finished, a summary of the imported files will be provided, click Next.

6. For this exercise, we are done with the Managed Configuration Import Wizard. Click Next, then Close.

Step 2: Add/Edit ProjectWise CSBsIn ProjectWise Administrator, under WorkSpaces >Managed

In this step, you are going to complete the following tasks:

Create a new ‘Predefined’ level CSB for called Substation_Configuration_CE Create a new ‘Global’ level CSB called Global_Variables_CE Create a new ‘WorkSet/Project’ level CSB called Substation_Workset_Link Create “ DefaultProject ” folder in ProjectWise Explorer Upgrade WorkSpaces,WorkSets & Project folder to Work Area Import individual Catalog in ProjectWise

Create a new ‘Predefined’ level CSB for Substation called Substation_Configuration_CE(This CSB will make the vital connection between the CSBs and the ProjectWise datasource.)

1. In ProjectWise Administrator, under WorkSpaces >Managed>Predefined, right mouse click over the ‘Predefined’ Level and select New> Configuration Block

2. In the New Configuration Block Properties, enter the name Substation_Configuration_CE and the description Substation CONNECT Edition Configuration Root. Once complete, click Apply. The dialog title will change to Substation_Configuration_CE Properties.

3. Add the following variables and/or directives:

Add Variable to the Substation_Configuration_CE CSB

Name _USTN_CONFIGURATIONDescription Substation PW Configuration

(_USTN_CONFIGURATION)Add Value Operation Type: '='- Assignment

Value Type: ProjectWise FolderValue: Change value to point to ProjectWise WorkSpace, browse to pw:\\<server name>:<datasource name>\Documents\Substation Managed Configuration\

Locked YES

Note: _USTN_CONFIGURATION defines the folder containing the entire Managed Configuration.

Tip: Since Configurations can be version specific, the Substation_Configuration_CE CSB includes the CE (CONNECT Edition) moniker to designate and differentiate between configuration versions.

Create new ‘Global’ level CSB called Global_Variables_CE

1. In ProjectWise Administrator, under WorkSpaces >Managed>Global, right mouse click over the ‘Global’ Level and select New> Configuration Block

2. In the New Configuration Block Properties, enter the name Global_Variables_CE and the description Global Variables CONNECT Edition. Once complete click Apply.

The dialog title will change to Global_Variables_CE Properties.

3. Add the following variables and/or directives:

Add Variable to the Global_Variables_CE CSB -

Name _USTN_DISPLAYALLCFGVARSDescription Display All Configuration VariablesAdd Value Operation Type: '='- Assignment

Value Type: StringValue: 1

Locked YES

Note: _USTN_DISPLAYALLCFGVARS displays all system level configuration variable and is useful for Administrators during certification and debugging.

The Final Global_Variables_CE CSB:

Create a new ‘WorkSet/Project’ level CSB called " Substation_Workset_Link “ (This CSB will make the vital connection between the CSB and the ProjectWise WorkSet.)

1. In ProjectWise Administrator, under WorkSpaces > Managed > WorkSet/Project, right mouse clicks the ‘WorkSet/Project’ Level and select New > Configuration Block

2. In the New Configuration Block Properties, enter the name Substation_WorkSet and the description Substation WorkSet Link. Once complete click Apply.

3. Add directive%include $(dms_project(_dgndir))Substation_Workspace.cfgIn case of “Promise” %include $(dms_project(_dgndir))Promise_Workspace.cfg

Tip: The configuration variable dms_project(_DGNDIR) resolves the directory path to the first ProjectWise Project definition it encounters as it traverses backwards through the directories. This could resolve to a single parent Project (with no subprojects) or a Subproject. The configuration variable dms_parentproject(_DGNDIR) resolves the directory path to only the parent ProjectWise Project.

Tip: The configuration variable LastDirPiece (dms_project(_DGNDIR)) resolves the project name based on the directory path to the first ProjectWise Project definition it encounters as it traverses backwards through the directories. This project name may be required or used in other CSB’s.

Create “DefaultProject” folder in ProjectWise Explorer

1. Create “DefaultProject” folder in ProjectWise Explorer

This is not a valid project, but it is just a folder in PW Explorer. This is used to enable Managed Configuration in Desktop integration when we launch Substation from Desktop.

2. Upgrade this folder to Work Area a) Select folder and right click.b) Click “Upgrade to Work Area…” menu item

3. Copy Ecad.dgn and Substation_Workspace.cfg from local configuration to this folder.

4. Modify contents of Substation_Workspace.cfg as per default values you want to keep.

5. Assign Configuration Settings Block to this folder

Upgrade WorkSpaces, WorkSets & Project folder to Work Area

For e.g.

Import individual Catalog in ProjectWise

1.Import Catalog in ProjectWise For e.g. “MyCatalog”

             

2. Start Substation and Open Configuration Variables dialog and click OK.

3. Now Close Substation and Restart it again which will download this imported Catalog automatically.

Step 3: Add Exclusions (variables to be excluded from copy-out)

In certain scenarios, there are configuration variables that you may not want ProjectWise to use in managed workspaces. You can define and “exclude” ProjectWise from using these configuration variables by adding them to the list of excluded variables.

In ProjectWise Administrator, under WorkSpaces >Managed>Variables to exclude from copy out

Below are some optional variables that may be excluded from copy out, depending on the Substation workflows:

MS_BUMP (supports Visualization - optional)

If you are not using project explorer the following can be excluded:

MS_DESIGNDIR ( supports Project Explorer harvesting of Dynamic Views- optional)

MS_DRAWINGDIR (supports for Project Explorer harvesting of Dynamic Views - optional)

MS_SHEETDIR (supports for Project Explorer harvesting of Dynamic Views - optional)

The files defined by these configuration variables will be excluded during the download of the workspace.

Step 4: ProjectWise Application DefinitionProjectWise Application definition using the Program Class Name

Program Class Name - A Program Class Name defines and stores in the Windows registry both the executable and any command line arguments as defined during the installation on the local machine. This is the most reliable and universal application definition because ProjectWise does not store any hard-coded directory path information. Registry support relies on the client registry to provide ProjectWise with the proper drive/directory location of application to launch.

Tip: The Program Class Name is used by the newest installed version? Meaning if multiple versions of Substation are installed on the machine and using the program class name, the last Substation version installed will own the program class name, Bentley.Substation.Application.

The Program Class Name will be defined by default. It should not be necessary to modify the program associations in ProjectWise with a standard Substation Install.

Application Definitions in ProjectWise Administrator:

In ProjectWise Administrator, under Applications, locate the application definitions for Substation in the right panel. ProjectWise CE is delivered with predefined application definitions for Substation

If the predefined applications are not available, the applications can be imported using the administrative dmsconv.exe utility, using the corresponding XML application definition file (ABD_CE_appdef.xml for CONNECT Edition) available on the BE Communities. Instructions on how to apply the XML, using the dmsconv.exe, are include within the XML file.

Step 5: Link CSBs to “DefaultProject” & Working folder [e.g. “MyProjects”] 

The “DefaultProject” and “MyProjects” folders should be promoted to ProjectWise Projects [Upgrade to Work Area] in order to support a Managed Configuration. Once they are a ProjectWise Projects, then the _USTN_WORKSPACENAME and _USTN_WORKSETNAME can be automatically extracted by using ProjectWise Project Macros. To upgrade the folders to ProjectWise Projects, right-click on the folder and select ‘Upgrade to Work Area’. Follow the ‘Project Creation Wizard’ and consult the help documentation for further information on “Converting Folders to Projects”

Additional Configuration Variables defined in the WorkSpace configuration file i.e. Substation.cfg. These variables are used for internal logic purpose.

.

Step 6: Test/Validate (Troubleshoot)

To test or validate your Integration, in the ProjectWise Explorer, locate the delivered file Ecad.dgn in the “Default Project” (pw:\\PWMW2008SRV.bentley.com:SUBSTATION_MANAGED_DS\Documents\DefaultProject\Ecad.dgn).

Set the file to be associated to the Substation application. This can be achieved by selecting the Ecad.dgn file in ProjectWise Explorer, then selecting the Modify option from the right-click menu. In the Modify document dialog, select Substation from the drop down list under “Application:” Select OK to complete the association.

Double click on the Ecad.dgn file to open it. If it is properly configured, you should see the Manage WorkSpace Export Progress dialog, indicating the initial workspace download.

Note: To make further use of Sample Project Data, you will need to run Tools>Scan References and Linksets… from the ProjectWise Explorer Client to reconnect and resolve all the project references and linksets. Please consult the ProjectWise help documentation for more information.

Manage WorkSpace Export Progress Dialog, which shows successful completion of all tasks:

Note: Errors in the first three tasks usually are the result of an error in the application definition or association. Please validate the application definition in the ProjectWise Administrator.

Note: Opening a managed project or application the first time will require ProjectWise to download the workspace and datasets locally, which can take 10 minutes or more the first time, depending on your connection speed and size of your workspace and dataset. Please be patient, subsequent loads will have much faster load times. In many cases, you will experience performance better than that of loading the same design file from a typical LAN server or shared network drive.

From within the Substation application, you can verify you are successfully using a ProjectWise Manage WorkSpace by selecting Workspace>About Workspace from the File menu. You should be presented with a ProjectWise Manage WorkSpace Dialog, similar to what is displayed below.

Step 7. TroubleshootingApplication must be restarted dialog:

If you are presented with the following message to restart your Substation Session, then there is something different in the managed configuration that requires a change in your Managed Configuration.

This dialog is common and is to be expected if you are opening files from another project or if you are using ProjectWise desktop Integration (launching Substation from the desktop and connecting to ProjectWise). However, this dialog does not typically appear if you are opening different files from within the same project. If it does occur:

Verify that the files contain the same ProjectWise Manage Configuration assignments. They should all be inherited from the ProjectWise Project Folder. CSB’s assigned must match or you will receive the restart dialog.

Verify that there are no ProjectWise Manage Configuration CSB assignments on the ProjectWise Application associated to the document. This alert will appear if you switch to a file that does not share the same application association as the original file opened and the application has a CSB assigned to the application definition.

Inspect your configuration files, any configuration variable defined to equal _DGNDIR or _DGNFILE will need to be add the exclusion list defined by PW_MWP_COMPARISON_IGNORE_LIST in the ProjectWise mcm.cfg file. You can use file compare utility, (e.g. Beyond Compare 4+), to compare the <DocID>.cfg file generated to look for any differences in the configuration.

Inspect the ProjectWise MCM integration log files. In the ProjectWise mcm.log.xml edit the section, <Change following priority to “all” to see managed workspace differences that cause MS restart>. Change the Priority of, category name=”pwise.dms.workspace.managed.compare”, from “warn” to “all”. Recreate the MicroStation restart and inspect the, mcmintgr.log file. This file will show the difference which prompted MicroStation to restart.

Enabling ‘Export relative path errors handling’:

The ProjectWise Explorer client does offer some error handling that may assist you in troubleshooting a Managed Configuration configuration in the form of ‘Export relative path Errors handling’. By enabling this option, ProjectWise will now report on any directory/file validation issue it encounters during the CSB processing. Please note, there are a couple of situations in which this tool may report a validation warning against a valid configuration options and are not indicative of a Manage WorkSpace configuration problem. The follow scenarios are reported as errors but are not truly since they cannot be explicitly resolved.

Any time a configuration variable uses a wild card to define a series of files (i.e. *.cell, *.rsc, *.dgn, *.dgnlib, etc…). Since ProjectWise isn’t able to explicitly validate this definition, it will register a warning.

Resource and user setting files created on demand or on the fly.

To enable ‘Export relative path errors handling’, access the user properties in the ProjectWise Client from the file menu Tools>Options. In the users properties dialog, select the ‘Settings’ tab and expand the ‘Manage WorkSpaces’ options, then further expand the ‘Export relative path errors handling’ options and select the ‘Prompt User’ option.

Once enabled, a new dialog will appear after the processing of the Managed WorkSpace. This dialog will display files and directories that could not be resolved. This could indicate an error in the configuration, missing directories or even that your configuration is not being resolved where you think it is. Below is an example of the ‘Managed WorkSpace Export Error’ dialog, based on the configuration of the Example WorkSpace and Multi-Use_Retail_Building_US WorkSet used in this document. In this case, there are no significant errors and it the correct results of a properly configured Substation. If you recall, this tool does not resolve relative paths and files where the file is defined with a wildcard or the directories and/or files are created on the fly. Warnings of these type will have no impact on the performance of your Managed WorkSpace environment and are informational in nature.

A valid and totally acceptable ‘Manage WorkSpace Export Error’ report and configuration for Substation.

Once you have addressed any potential configuration issues, set the ‘Export relative path errors handling’ in the user setting to ‘ignore invalid relative path errors’ for day to day operations.

Dialog ‘No WorkSet Alert’ or ‘Mismatch Alert’:

In a Managed Configuration, if you see the ‘No WorkSet Alert’ or ‘Mismatch Alert’ then most likely MicroStation application is unable to locate the WorkSpace or WorkSet configuration files being resolved by the Managed Configuration. MicroStation needs to locate the WorkSet configuration files (*.cfg) to properly load the Configuration. Evaluate the configuration resolving around the, _USTN_WORKSPACESROOT, _USTN_WORKSPACENAME, _USTN_WORKSETSROOT, and _USTN_WORKSETNAME. Verify the appropriate *.cfg file can be

located and processed. If you see this dialog when opening a design file with a Managed Configuration the configuration will most likely be corrupt. A corrupt configuration could be MicroStation appending variables after the resolved working directory dms folder, e.g. C:\WorkingDir\dms00000\Cells. ProjectWise uses a flat storage structure so this would not be correct.

Configuration Level Processing:

The configuration processing is slightly differnet as MicroStation CONNECT Edition requires the configuration files to be available to have a valid configuration. If the WorkSpace and WorkSet configurations file are not available MicroStation will run in a “NoWorkSet” mode. The temporary CsbID.cfg files are still created in the ..\WorkingDir\workspace\ folder and compiled to create the final DocID.cfg which is passed on the command line to open the design file with the managed configurations. The WorkSpace generation will process the configuration files from the ProjectWise folders. User can basically run the entire configuration from ProjectWise using the MicroStation configuration files as described in this document. With MicroStation CONNECT Edition users can control the configuration from within the CSB’s or from the configuration files stored in ProjectWise.

ProjectWise Levels (Order of Processing):

Predefined (0)Global (0)Application (1)Customer (2-)Organization/Site (2)WorkSpace (3)WorkSet/Project (4)Role (5)User (6)Personal (6+)

Level processing order to be aware of:

The Customer level CSB’s will be processed before the Organization level CSB’s but after the Standards level in MicroStation. Meaning if you have the same variable in the standards configuration file, standards.cfg, and a customer level CSB defined with ‘=’operator the customer level CSB will win. There is a defect filed for this but should be low impact and may not be fixed in update 2.1. The MicroStation Organization level configuration, standards.cfg, will be processed prior to the Organization level CSB’s WorkSpace level CSB’s are processed before the MicroStation WorkSpace level configuration, workspacename.cfg. WorkSet level CSB’s are processed before the MicroStation WorkSet level configuration, worksetname.cfg Role Level CSB’s are processed before the MicroStation Role level configuration, USER_ROLE defined.cfg Personal.ucf file is not processed.

Miscellaneous Tips and Tricks:

(macro) DMS_PROJECT Resolves to the nearest Project folder (Rich Project or CONNECT Project) of the design file being opened

(macro) DMS_PARENTPROJECT Resolves to the nearest Parent Project folder (Rich Project or CONNECT Project) of the design file being opened

(macro) DMS_CONNECTEDPROJECT Resolves to the nearest ProjectWise CONNECTED Project folder (associated with Bentley CONNECT project)

(macro) DMS_CONNECTEDPROJECTGUID Resolves to the guid value of associated Bentley CONNECT project

(MicroStation command) Show Configuration Will open the current MicroStation configuration in notepad. Can be used check values of current variables. Will show the working directory dms##### folders instead of the ProjectWise monikers

(MicroStation command) mdl load cfgvars Shortcut to load the MicroStation configuration dialog. MicroStation Configuration dialog will show the

vairables with the ProjectWise monikers

(MicroStation command) expand echo $(variable_name)

Print the value of the specified variable to the MicroStation message center

(tip) @:Equivalent of the ProjectWise Device, pw:\\<servername>:<datasourcename\Documents\

If a “ProjectWise folder” is not specified in the configuration, users can use the @:/<pw path>/<pw path>/ in the CSB or configuration file to specify a ProjectWise folder or document is being defined.

e.g. MS_CELLLIST > @:/Company/Cells/*.cel

(tip) -DEBUG Don’t rely on msdebug.txt to show you the correct configuration. With MicroStation CONNECT Edition the msdebug.txt is basically obsolete, (even with non-integrated MicroStation). It prints the configuration to launch MicroStation and the WorkSpace and WorkSet variables will not be resolved yet. It can be used to check the cfg files being used but not the final configuration.