Configuration Files

This XML file enables you to both specify one or more PTC Servers that the PTC Server connection can access and to determine whether users can create a baseline when adding or checking objects into a PTC Server. The server(s) you include in this file are displayed in the Connect dialog box. When you enable prompting for a baseline, the Create baseline option is enabled on the Check In and Save As Properties dialog boxes.

The file is located at Arbortext-path\adapters\com.ptc.prowt.arbortext\siteprefs.xml. Use the siteprefs_template.xml file included in the same directory as a starting point for your siteprefs.xml file. These configuration settings can be shared across multiple groups by putting an XInclude element in the userprefs.xml configuration file that points to a shared siteprefs.xml on the network. See the section on userprefs.xml for more information about sharing the siteprefs.xml file.

For specifying PTC Servers, the siteprefs.xml file contains a ParameterName element with the value HostList. Following ParameterName is one or more ParameterValue elements. Each ParameterValue element must contain information about a PTC Server. If you want the PTC Server connection to be able to access multiple servers, include a ParameterValue element for each server.

If you are providing information for a specific PTC Server or for a PTC Server with a specific proxy server, the information contained in the ParameterValue element must be in the following format:

• Proxy Server — The TCP/IP address used to connect to the proxy server for this PTC Server, for example 132.254.69.1. This value is optional. You should only include this value if the PTC Server is in a cluster and is accessed through a proxy server.

• Proxy Server Port — The port number for the proxy server, for example 8003. This value is optional. You should only include this value if the PTC Server is in a cluster and is accessed through a proxy server.

If you are providing information for a PTC Server that uses a proxy auto-configuration (PAC) file to direct how client applications should connect to the server, the information contained in the ParameterValue element must be in the following format:

• PAC File URL — The URL to the PAC file where the proxy configuration is defined. This value is required. The URL must be in the format http://Proxy Server URL:Proxy Server Port/PAC File Name.

• SecurityCertificateSerialNumber — Specifies the serial number of a Secure Socket Layer (SSL) certificate that is stored in the Microsoft Windows certificate store.

When connecting to a PTC Server that uses 2-way Secure Socket Layer (SSL) HTTPS client authentication, you must provide the SSL certificate serial number for that PTC Server. This serial number is used to select the correct certificate from the store to authenticate with the specified PTC Server. You can have multiple SecurityCertificateSerialNumber entries, each representing a different PTC Server.

The serial number information contained in the ParameterValue element must be in the following format:

Server Name|Certificate Serial Number

◦ Certificate Serial Number — The serial number for the SSL certificate to be used for authentication with the specified server. The serial number is in hexadecimal format with each byte separated by a space. This value is required.

Following is an example of the ParameterName element value:

• ServerAuthentificationTypes — Specifies the required information about the Windchill Servers that is needed before authentication.

A ParameterValue element for each supported Windchill server should be included.

The content of the ParameterValue element must be in the following format:

Server Name|[Authentication Type]

◦ Server Name — The name for the Windchill Server as specified in the HostList parameter. This is Windchill Server that is displayed in the Connect dialog box.

◦ Authentication Type — The type of authentication configured on the Windchill server. Supported values are FBA for Forms Based Authentication or DEFAULT.

Following are examples of ParameterValue element values:

• SecurityCertificateStoreName — Specifies either the name of a specific Microsoft Windows certificate store that contains the SSL certificate used to authenticate with a PTC Server or indicates to search in all PTC supported certificate stores for the certificate.

When connecting to a PTC Server that uses 2-way Secure Socket Layer (SSL) HTTPS client authentication, you must specify in which certificate store or stores to search for the SSL certificate used to authenticate with that PTC Server. You can have multiple SecurityCertificateStoreName entries, each representing a different PTC Server.

The certificate store information contained in the ParameterValue element must be in the following format:

Server Name|Certificate Store Name

◦ Certificate Store Name — The name of the certificate store that contains the SSL certificate used for authentication with the specified server. If you want to search for the certificate in all supported certificate stores instead of a specific store, set the parameter to the value PTC_SEARCH_IN_ALL_KEY_STORES.

Following are examples of the ParameterName element values:

This parameter is set to off by default. To enable baseline support, set the value to on. If you leave baseline support off, then whether a baseline is created for an object is determined by the PTC Server preferences Create Baseline upon Check In and Create As Stored.

If the useroverride burst configuration setting is set to off in the atidefaults.bcf system-wide burst configuration file, the baseline creation options are still available to users if PromptForBaseline is set to on. In this case, only the options for creating baselines will be available in the Check In and Save As Properties dialog boxes.

You can set this parameter to the following values:

◦ from_document_type — Add dependent objects to the workspace based on information stored in the PTC Server related to the object’s document type.

• BackgroundSessionTimeout — Determines whether Arbortext Editor should run in the background for a specified amount of time.

This enables you to hide Arbortext Editor for a time enabling a user to open the editor from the PTC Server HTML Interface more quickly and without having to reconnect to the PTC Server. If this parameter is not set, when a user chooses File > Exit in Arbortext Editor the editor closes as usual.

If you set this parameter to a number higher than zero, when a user chooses File > Exit in Arbortext Editor the editor will run hidden in the background for the number of minutes indicated by the parameter value. For example, if you set the value to 30, Arbortext Editor runs in the background for 30 minutes and then automatically exits and disconnects from the PTC Server. In this case, there is a new choice added to the File menu named Exit and Close PTC Server Connection Session. When a user selects this choice, Arbortext Editor closes as usual and does not run in the background.

This parameter is set to on by default. To disable HTTP compression, set the value to off. If you leave HTTP compression on, then both request and response metadata is compressed using the gzip format for HTTP 1.1 encoding. The XML text content is always transferred uncompressed, regardless of the setting of this parameter.

HTTP compression is a way to compress the content transferred between web servers and clients. Compression reduces the size of the transmitted content and improves network performance. Note that data compression does increase the processing required for the PTC Server and clients. The PTC Server zips the data before sending it across the network and the client must unzip the received data before processing it. Therefore, enabling HTTP compression improves data transfer time over the network but increases processing time. If you notice your PTC Server has higher processing needs than desired, disable HTTP compression.

• AlwaysUsePrimaryContentForGraphics — Determines whether to search for image content that matches the format specified in the notation parameter.

This parameter is set to false by default indicating to search a graphic's representations, primary content, and secondary content to find content that matches that specified in the notation parameter. Set this parameter to true to disregard the notation parameter and always use the graphic’s primary content.

This parameter is set to on by default. When set to on, the PTC Server creates content reference links for cross references, DITA content references, and similar DITA references (those indicated in the document-type-specific burst configuration file by a customref element with the mode attribute set to the value dita-partial). Note that content reference links do not enforce referential integrity.

Content reference links do enable you to include the objects associated with these DITA references in save as and similar operations on the PTC Server HTML interface by including all dependent objects in the operation. The content reference objects are also now listed in the References Documents table in the HTML interface for the referencing object, though this part of the feature is only supported for PTC Servers running releases 10.0 M040 or later and 10.1 F000 or later.

Set this parameter to off to disable the creation of content reference links for DITA documents.

• RefreshContentOnCheckin — Determines whether modified documents are reloaded in Arbortext Editor from the PTC Server after a successful save, upload, or check in operation.

This parameter is set to false by default. When set to true, Arbortext Editor reloads modified documents from the PTC Server whenever one of the following operations is performed successfully:

Reloading documents in these cases can affect performance, so you should only set this parameter to true if you do some sort of document processing on the PTC Server after a successful save and check in.

• UseNewWorkspaceUpdateFormat — Determines whether operations that update the PTC Server workspace on the Arbortext Editor client use an update format that requires less data.

This parameter is set to false by default. When set to true, the PTC Server uses a workspace update format that requires less information be exchanged between the PTC Server and Arbortext Editor during operations that require workspace updates. Examples of this type of operation include Check Out Object, Undo Check Out Object, and Check In Object. Setting this parameter to true can improve performance for these operations when the workspace contains a large number of objects.

When this parameter is set to the true and logging is enabled in the userprefs.xml configuration file, then the PTC Server connection writes a message to the log file indicating either that this parameter has been set or that the current PTC Server version does not support the new update format. This feature is only supported for PTC Servers running releases 10.0 M040 or later and 10.1 F000 or later.

• AddMetadataToWorkspaceOnDITAInsert — Determines whether to add a DITA topic being inserted as a topic reference in a DITA map to the active workspace.

This parameter is set to true by default. In this case, when the user enters a topic reference into a map to a topic stored on a PTC Server, the PTC Server connection both downloads the topic reference information from the PTC Server and also adds the referenced topic to the active workspace.

When this parameter is set to the false, the PTC Server connection only downloads the topic reference information from the PTC Server. The referenced topic is not added to the workspace. This can improve performance when several topic references are added to a map at the same time. However, when the map has been opened from the PTC Server, then other operations such as File > Save on the map can take longer.

• PubStructRDEReadOnly — Determines whether the Resolved Document for Editing (RDE) related to a Publication Structure or a Publication Section is read only when a Service Information Manager user performs the operation Open In > Open All Topics in Arbortext Editor in Windchill Service Information Manager

The property is set to false by default. In this case, when the user clicks Open all topics in Arbortext Editor to open the related topics stored on the PTC server, the RDE that is created has both read and write access.

When the property is set to true, the RDE is created as a read only document.

• VerifyIfCanCheckoutInAdvance—Determines whether the check to see if a document is valid for checkout is performed before you attempt to checkout the document. This allows the checkout button and the menu items to be disabled in advance if the checkout will fail. By default, this parameter is set to true. It should be set to false only if there are any significant performance issues or this behavior interferes with your customizations.

This XML file contains parameters that enable you to customize the behavior of the PTC Server connection for your installation. It also contains a reference to the siteprefs.xml configuration file. The file is located at Arbortext-path\adapters\com.ptc.prowt.arbortext\userprefs.xml. Use the userprefs_template.xml file included in the same directory as a starting point for your userprefs.xml file.

The userprefs.xml file contains a series of ParameterName elements that contain a ParameterValue element. The names of the parameters you can set are contained in the ParameterName elements. Enter the value for these parameters in the associated ParameterValue elements.

• WindchillAdapterHomeDir — Specifies the path to a directory on the file system that the PTC Server connection can use for caching and to store system files.

The specified directory must exist, as the connection will not create it automatically.

If you do not specify a value for this parameter, the user.home\.wcAdapter directory is used by default. Note that user.home is a Java system property. For example, the default home directory might be the following: C:\Documents and Settings\jsmith\Application Data\PTC\Windchill Integration\.wcAdapter

• WindchillAdapterTempDir — Specifies the path to a directory on the file system that the PTC Server connection can temporarily use to store system files that do not persist between sessions.

If the specified directory does not exist, the connection will automatically create it. If you do not specify a value for this parameter, the default temporary file directory for the operating system is used.

This parameter enables you to specify the format of the log file in Apache log4j format. For example, if you want the entries in your log to contain the date and time add the following parameter and value to your file:

• WindchillConnectionParams — Specifies the connection settings for a PTC Server. You can set this parameter for one or more of the PTC Servers defined in the siteprefs.xml configuration file.

The parameter has the following format:

The parameter allows the following values:

◦ Download Threads — The number of threads the PTC Server connection is allowed to use when downloading objects from the server.

◦ Upload Request Size — The size in bytes of the upload request that the PTC Server connection is allowed to use when uploading objects to the server.

Following are some example settings for this parameter:

This example sets both the download threads and upload request size for Server1.

This example sets just the upload request size for Server2.

This example sets just the download threads for Server3.

• WorkspaceCleanupThreshold — Specifies whether objects that are not checked out should be automatically removed from the active workspace when a user disconnects from the PTC Server. This feature is disabled by default. To enable the feature, set the value of the parameter to the maximum number of objects you want to allow in the workspace when a user disconnects.

For example, setting the parameter value to 10 results in all objects that are not checked out being removed on disconnect when there are more than 10 documents in the workspace:

Setting the parameter value to 0 results in all objects that are not checked out being removed from the workspace whenever a user disconnects:

• PromptForWorkspaceChange — Determines whether the user will be prompted to change the active workspace when the Open in Arbortext action is selected for a document in the Windchill HTML interface and the context of the document is different than the context of the workspace.

This parameter is set to yes by default. In this case, the PTC Server connection opens the Change Active Workspace dialog box when the context of the requested object and the context of the active workspace are not the same. The user must change the active workspace to one appropriate for the object.

When this parameter is set to the no, the PTC Server connection only opens the dialog box in two cases. First, when the context of the requested object is a project and the current context is a different project, product, or library. Second, when the context of the requested object is a product or library and the current context is a project.

• UseNewAuthentication — Determines whether to use an alternate authentication process when connecting to the PTC Server.

This parameter is set to false by default. This indicates to use the default authentication process and dialog boxes when connecting to a PTC Server.

When this parameter is set to true, the authentication process is changed so that the initial options on the Connect dialog box only request the name of the PTC Server to which you want to connect. The dialog box displayed after that depends on the type of authentication used by the server. Once the user is authenticated, the Connect dialog box enables you to select the context and workspace in which you want to work.

If you use HTTPS Client Authentication to connect to your PTC Server, it is recommended you set this parameter to true. The alternate authentication process provides a better user experience in this case.

• RemoveObjectsFromWorkspaceAfterCheckIn — Determines whether the Remove From Workspace option is selected by default on the following dialog boxes:

This parameter is not set by default. In this case, the default value is the setting of the Remove objects from Workspace after Check In preference in the PTC Server HTML interface.

When this parameter is set to Yes, the Remove From Workspace option is selected on the dialog boxes. In this case, any documents affected by the dialog box are removed from the client workspace after being checked into the server.

When this parameter is set to No, the Remove From Workspace option is not selected on the dialog boxes. In this case, any documents affected by the dialog box are not removed from the client workspace after being checked into the server.

• ShowOrganizationNameWithContainer — Determines whether to display the organization name next to the context in the Browser.

In some cases your site might have multiple contexts, such as a product, that have the same name but are in different organizations. This parameter enables you to display the organization for a context in the Browser.

The default setting for the parameter is no meaning not to display organization names. Set the parameter to yes to display the organization name next to the context in the Browser.

It is recommended that you put a master version of siteprefs.xml on a shared network drive and edit the href attribute to specify the full path to the master file. This enables you to specify global site parameters for all users that reference the master file. Any changes to the master file are processed by the PTC Server connection the next time a user invokes the connection.