Windchill Configuration Properties
Windchill uses standard Java property files to store many of its settings. The majority of the settings are stored in the property file wt.properties, which is located in the Windchill codebase directory. From this location, wt.properties is available to be downloaded by clients.
Although wt.properties holds most settings, there are other property files located under the codebase directory. These property files are also available to clients. Some property files are stored outside of codebase because they are not needed by clients or should not be available to clients. For example, the db.properties (which contains a password to your database instance) is located outside the codebase in the Windchill db directory.
 |
To view the value of any property in wt.properties, use the wt.util.jmx.WTPropEval command line utility. This utility returns the value for a specified property name. The value is in a fully evaluated form, which means any $(...) substitutions have been performed. The format for the utility is:
java wt.util.jmx.WTPropEval <wt.properties property name>
|
To manage site property settings, use the xconfmanager utility; using a text editor to edit individual property files is not supported. All site-specific changes to property files are maintained in the site.xconf file that is located in the directory where Windchill is installed. Editing properties directly most likely will result in problems updating the system or problems with the system after it is updated because the property files are regenerated from the XCONF files.
The xconfmanager is a command line utility that you can run to add, remove, or modify properties in any Windchill property file. By using the xconfmanager you modify the properties and then propagate the changes to the property values.
JMX provides MBeans which allow you to view and modify properties, change log settings, configure notifications, and so forth. The Properties MBean provides allows you to view and change the values for properties. For additional information about using JMX to view Windchill properties, see Using Java Management Extensions (JMX).
The changes made through a JMX client and xconfmanager are saved in the site.xconf file and propagated to respective property files. When you restart your Windchill system, the resulting changes are implemented.
The site.xconf file is created and updated by Windchill product installers. These installers also create the declarations.xconf file that contains a list of configuration references to PTC-supplied XCONF files that are used to specify the out-of-the-box default values for properties in many of the property files. Although not all property files are initially generated from XCONF files, you should always make changes to Windchill properties through the xconfmanager.
|
|
By using the xconfmanager utility or a JMX client, your site.xconf file always contains your site-specific changes. By maintaining site-specific changes to properties in the site.xconf file, you can easily identify what changes were made and these changes will be retained automatically when applying PTC-supplied maintenance updates to your installation.
|
As shown in the following diagram, making property changes through the xconfmanager utility that Windchill provides always updates the site.xconf file. Then Windchill propagates the changes to properties files using the site.xconf file and the XCONF files that it maintains. In this diagram, the declarations.xconf file has references to three sample internal XCONF files that then are used by Windchill to update referenced property files:
As part of installing Windchill, the Windchill Configuration Assistant is installed and run to set initial values of properties based on the available memory and CPU resources of the server. The actual property values set are stored in windchillconfigurator.xconf and Windchill Configuration Assistant installation adds the ConfigurationRef element to the site.xconf file to establish the link between site-managed property values and those values set as a result running the Windchill Configuration Assistant.
For additional Windchill Configuration Assistant details, see Using Windchill Configuration Assistant to Configure Windchill.
When you use a JMX client or the xconfmanager utility to update properties, Windchill always propagates the changes to the corresponding property files.
When using a JMX client, you must apply your changes using the applyPendingChanges operation available through the PropertiesManager MBean. For additional information about using JMX to view Windchill properties, see Using Java Management Extensions (JMX).
When using the xconfmanager, you must explicitly tell it to propagate XCONF file changes. Explicitly propagating changes allows you to make multiple command line changes before propagating all changes. To propagate changes using the xconfmanager, you must include the -p option. For information about using the xconfmanager utility, see .
Whenever you change a property setting using the xconfmanager, Windchill creates backup XCONF and property files of all files that are updated in the .xconf-backup directory where Windchill is installed. The file names for the back up files are modified to include a 3-digit number that identifies the backup file order. For example, the first three backup files created for the site.xconf file are named site.000.xconf, site.001.xconf, and site.002.xconf.
Windchill also maintains an internal cache containing the latest XCONF file information and maintains other internal XCONF files that it uses to determine what property files need to be updated. Do not manually modify these files.
The following sections provide information about the site.xconf file and the xconf.dtd file, which is used to validate all Windchill XCONF files.
The site.xconf File Format and Contents
The site.xconf file is an XML file that is formatted according to the xconf.dtd. The file is automatically updated to contain an element for every property setting change that is made through either the JMX client or the xconfmanager.
The configuration elements included in the site.xconf file are as follows:
• Each Property element names a property, its target property file, and the value of the property. The xconfmanager adds this element to the site.xconf file when you set specific property values.
• Each ResetProperty element names a property and its target property file. The xconfmanager adds this element to the site.xconf file when you reset properties to their default values.
• Each AddToProperty element names a property value to add to the end of a multi-valued property. The xconfmanager adds this element to the site.xconf file when you add a property value to the end of a multi-valued property.
• Each RemoveFromProperty element names a property value to remove from a multi-valued property. The xconfmanager adds this element to the site.xconf file when you remove a property value from a multi-valued property.
• Each UndefineProperty element names a property and its target property file. The xconfmanager adds this element to the site.xconf file when you undefine properties so that their values are null.
| | Although PTC recommends that you use either a JMX client or the xconfmanager to modify the contents of the site.xconf file, some administrators may chose to modify the site.xconf file without using the Windchill tools. If you do manually modify the site.xconf file, be sure to format elements according to the xconf.dtd, which is documented in the next section. To propagate your changes to the affected property files, you must run the xconfmanager with the -p option and, to use the updated property files, you must restart your Windchill solution. |
 | If you are attempting to batch script calls to the xconfmanager.bat script using the DOS scripting language, be sure to use call script.bat (and not script.bat). |
For examples of using the xconfmanager, see . For information about using a JMX client, see Using Java Management Extensions (JMX).
The xconf.dtd File
Windchill uses the xconf.dtd to validate all elements in all XCONF files that it uses, including the site.xconf file. To ensure that this validation takes places for all XCONF files, no matter where they are located in the codebase and without access to the internet, the xconf.dtd is supplied using a JAR file and is not readily available through the Windchill directory structure.
The contents of the DTD file is as follows:
<!ENTITY % targetFile 'targetFile CDATA #IMPLIED'>
<!ENTITY % serviceProvider 'serviceProvider (wt|wtCustom|typeBased) #IMPLIED'>
<!ENTITY % name 'name CDATA #REQUIRED'>
<!ENTITY % context 'context CDATA "default"'>
<!ENTITY % overridable 'overridable (true|false) "true"'>
<!ENTITY % multivalued 'multivalued CDATA #IMPLIED'>
<!ELEMENT Configuration (Property|AddToProperty|RemoveFromProperty|Service|Resource|
ConfigurationRef|ResetProperty|UndefineProperty|PropagationAction)*>
<!ATTLIST Configuration
xmlns:xlink CDATA #IMPLIED
%targetFile;
%serviceProvider;
>
<!-- PTC to set "defaults", configurer to set "values" -->
<!ELEMENT Property (Documentation)?>
<!ATTLIST Property
%name;
default CDATA #IMPLIED
defaultUnix CDATA #IMPLIED
defaultWindows CDATA #IMPLIED
value CDATA #IMPLIED
%targetFile;
%overridable;
%multivalued;
>
<!ELEMENT AddToProperty EMPTY>
<!ATTLIST AddToProperty
%name;
value CDATA #REQUIRED
>
<!ELEMENT RemoveFromProperty EMPTY>
<!ATTLIST RemoveFromProperty
%name;
value CDATA #REQUIRED
>
<!ELEMENT Documentation (Synopsis,Description,Deprecation?)>
<!ATTLIST Documentation
category CDATA #IMPLIED
key CDATA #IMPLIED
>
<!ELEMENT Synopsis (#PCDATA)>
<!ELEMENT Description (#PCDATA)>
<!ELEMENT Deprecation (#PCDATA)>
<!ELEMENT ResetProperty EMPTY>
<!ATTLIST ResetProperty
%name;
%targetFile;
>
<!ELEMENT UndefineProperty EMPTY>
<!ATTLIST UndefineProperty
%name;
%targetFile;
>
<!ELEMENT Service (Option)*>
<!ATTLIST Service
%name;
%context;
%targetFile;
%serviceProvider;
>
<!ELEMENT Resource (Option)*>
<!ATTLIST Resource
%name;
%context;
%targetFile;
%serviceProvider;
>
<!-- For Service/Options requires serviceClass and cardinality. For
Resource/Options requires resource attribute -->
<!ELEMENT Option EMPTY>
<!ATTLIST Option
selector CDATA #IMPLIED
requestor CDATA #REQUIRED
order CDATA "0"
serviceClass CDATA #IMPLIED
cardinality (duplicate|singleton) "duplicate"
resource CDATA #IMPLIED
%overridable;
%targetFile;
>
<!ELEMENT ConfigurationRef EMPTY>
<!ATTLIST ConfigurationRef
xlink:href CDATA #REQUIRED
>
<!ELEMENT PropagationAction (ClassPathEntry)*>
<!ATTLIST PropagationAction
className CDATA #REQUIRED
>
<!ELEMENT ClassPathEntry EMPTY>
<!ATTLIST ClassPathEntry
dir CDATA #IMPLIED
file CDATA #IMPLIED
>
<!ENTITY % serviceProvider 'serviceProvider (wt|wtCustom|typeBased) #IMPLIED'>
<!ENTITY % name 'name CDATA #REQUIRED'>
<!ENTITY % context 'context CDATA "default"'>
<!ENTITY % overridable 'overridable (true|false) "true"'>
<!ENTITY % multivalued 'multivalued CDATA #IMPLIED'>
<!ELEMENT Configuration (Property|AddToProperty|RemoveFromProperty|Service|Resource|
ConfigurationRef|ResetProperty|UndefineProperty|PropagationAction)*>
<!ATTLIST Configuration
xmlns:xlink CDATA #IMPLIED
%targetFile;
%serviceProvider;
>
<!-- PTC to set "defaults", configurer to set "values" -->
<!ELEMENT Property (Documentation)?>
<!ATTLIST Property
%name;
default CDATA #IMPLIED
defaultUnix CDATA #IMPLIED
defaultWindows CDATA #IMPLIED
value CDATA #IMPLIED
%targetFile;
%overridable;
%multivalued;
>
<!ELEMENT AddToProperty EMPTY>
<!ATTLIST AddToProperty
%name;
value CDATA #REQUIRED
>
<!ELEMENT RemoveFromProperty EMPTY>
<!ATTLIST RemoveFromProperty
%name;
value CDATA #REQUIRED
>
<!ELEMENT Documentation (Synopsis,Description,Deprecation?)>
<!ATTLIST Documentation
category CDATA #IMPLIED
key CDATA #IMPLIED
>
<!ELEMENT Synopsis (#PCDATA)>
<!ELEMENT Description (#PCDATA)>
<!ELEMENT Deprecation (#PCDATA)>
<!ELEMENT ResetProperty EMPTY>
<!ATTLIST ResetProperty
%name;
%targetFile;
>
<!ELEMENT UndefineProperty EMPTY>
<!ATTLIST UndefineProperty
%name;
%targetFile;
>
<!ELEMENT Service (Option)*>
<!ATTLIST Service
%name;
%context;
%targetFile;
%serviceProvider;
>
<!ELEMENT Resource (Option)*>
<!ATTLIST Resource
%name;
%context;
%targetFile;
%serviceProvider;
>
<!-- For Service/Options requires serviceClass and cardinality. For
Resource/Options requires resource attribute -->
<!ELEMENT Option EMPTY>
<!ATTLIST Option
selector CDATA #IMPLIED
requestor CDATA #REQUIRED
order CDATA "0"
serviceClass CDATA #IMPLIED
cardinality (duplicate|singleton) "duplicate"
resource CDATA #IMPLIED
%overridable;
%targetFile;
>
<!ELEMENT ConfigurationRef EMPTY>
<!ATTLIST ConfigurationRef
xlink:href CDATA #REQUIRED
>
<!ELEMENT PropagationAction (ClassPathEntry)*>
<!ATTLIST PropagationAction
className CDATA #REQUIRED
>
<!ELEMENT ClassPathEntry EMPTY>
<!ATTLIST ClassPathEntry
dir CDATA #IMPLIED
file CDATA #IMPLIED
>