PDXpert service configuration settings

Last update 2022-09-02

Topic contents

• Warnings
• How to edit the configuration file
• Values in <appSettings />
  • Setting key="ClientInstallerPath"
  • Setting key="Culture"
  • Setting key="Index…"
  • Setting key="HostName"
  • Setting key="JobFactor"
  • Setting key="LDAPContextOptions"
  • Setting key="ServiceHostName"
  • Setting key="ServiceTcpPort"

Warnings

Fully test any change to these settings. The settings' default values are carefully selected for most conditions.

Retain a copy of changes that you make to the configuration file. Consider maintaining a revision history of the file as a document in PDXpert.

The service configuration file may be reset or replaced during application upgrade.

Review and, if needed, re-apply your custom settings after each system upgrade, or when you move your PDXpert Server to another computer.

How to edit the configuration file§

1. Ensure all users are logged out of the PDXpert client application.

2. On the server computer, close the PDXpert application server window.

3. In the Administrator Tools > Services window: Stop the PDXpert Server service. If asked, stop the PDXpert Filter service.

4. In the Program Files folder, go to the installed PDXpert application location. This is typically C:\Program Files\PDXpert\PDXpert PLM\Website\bin.

5. Select Notepad, Notepad++ or other plain text editor (not Word, Wordpad or other formatted text editor). Right-click to show the editor software's context menu, and select Run as administrator.

6. Using the text editor, find and open the PDXpert.Service.exe.config file in the installed PDXpert application location.

   Do not edit the PDXpert.Server.exe.config file.

7. Edit the setting, save the file, and close the text editor.

8. In the Administrator Tools > Services window: Start the PDXpert Server service.

   Do not start the PDXpert Filter service; it is started by the PDXpert Server service only when needed.

Values in <appSettings />

<add key="ClientInstallerPath" value="" />§

Purpose: Administrators can substitute their own network resource for users to download the PDXpert client installer.

Expected values: The URI or UNC absolute path to a network file. It could be a web server link, or the PDXpert Client Setup installer, or a text file with installation instructions.

For example, this setting:

value="M:\path\to\PDXpertClientSetup-x64.msi"

results in an email with text as highlighted below (text is not highlighted in the actual email):

Although the email sent by PDXpert uses only plain text for the path and file, some email clients may automatically format this text as a hyperlink.

Setting this value has no effect on the path shown on the PDXpert Server or copied by the Copy Installer Link button.

Default value: None - when empty, the new user's email shows a link to the client installer on the server (as modified by the HostName or ServiceTcpPort settings), similar to http://PDXpertServer:48084/client/setup

<add key="Culture" value="en-US" />§

Purpose: Identify the PDXpert service's culture resources. This setting is deprecated. Most service operations use InvariantCulture; database operations are generally fixed as en-US.

Expected values (culture): Any Microsoft Language Culture Name value. These are similar to the IETF language tag, and generally use a ISO 639 two-letter language code with a ISO 3166 two-letter country code.

Default value: en-US

<add key="HostName" value="" />

Purpose: Specify the client installer's network location for the server's Manage page's Copy Installer Link, Save Client Installer... and new user email. The value replaces the placeholder http://{location}:48084/client/setup For example, for <add key="HostName" value="10.0.2.127"/>, the link becomes http://10.0.2.127:48084/client/setup

Expected values (IP4/string): Any IP address or domain name that resolves to the server location.

Default value: None - the server computer's machine name is used when empty.

<add key="Index…" value="…" />

Introduced in PDXpert 16.0.

Database item records and file attachments are indexed using a variable-rate engine. The index engine

• obtains a set ("batch") of objects from a larger object queue;
• indexes this batch and saves the results in the index; and
• waits a specified idle period to allow full computer power to other processes.

During heavy workloads, the index engine slows to provide more processing to other user tasks, and the index queue may grow. However, beyond a specified queue length (the "slowest acceptable queue count"), idle time is gradually reduced as the queue size increases. For very large queues, the idle period is shortest.

The active portion of the indexing cycle can vary based on the number of items in the batch, their complexity, and other processes. The idle portion of the cycle is not a fixed amount of time, but a fixed multiple of the active indexing time. Regardless of how long a particular cycle takes, an idle period exactly equal to the active period is defined as 1.0, and gives a 50% duty cycle. Similarly, a 0.5 idle period is equivalent to a 67% active duty cycle, while a 0.25 idle period has an 80% active duty cycle. Since the active portion is always defined as 1, the active duty cycle is always 1/(1 + IdlePeriod)

Indexing starts out fast – that is, the idle period is at a minimum level – when there are very few items in the queue. The idle time increases, and indexing slows down, as users add more data. This provides fast search turn-around for small workloads, while prioritizing system operation during high-traffic periods. Indexing performance returns to its maximum with very large queue counts and little user demand; for example, when batch-importing data, re-indexing the system, and restoring a database backup. After the queue count reaches or exceeds the fastest point, indexing runs at the minimum idle period (the highest duty cycle).

The example graph shows a minimum idle period of 0.4, increasing to 0.8 as the queue grows from one item to a moderate count of 300 items. At the maximum idle (slowest index rate), the active duty cycle becomes 1/(1 + 0.8) = 55.6%. As the queue count increases beyond 300 items, the idle period falls (indexing is faster) until the queue reaches 5000 items; this is the minimum idle period and fastest indexing. Above 5000 items, the active duty cycle remains at 1/(1 + 0.4) = 71.4%

To set a consistent duty cycle, set the maximum idle period only slightly higher (0.1) than the minimum value. To equalize performance for virtually all queue sizes, set both slowest and fastest queue counts to their largest values (450000 and 500000, respectively).

<add key="IndexMinIdlePeriod" value="0.35" />

Purpose: Assign the idle (inactive) period for the most active indexing cycle: active duty% @ min = 1/(1 + [value]) A smaller value represents a shorter idle time, and a larger proportion of the cycle actively indexing. Consider temporarily reducing this value when using the Batch Importer tool during system initialization.

Expected values (decimal): Numbers from 0.1 (91%) to 9.5 (9.5%). Values outside this range are assigned the closest upper or lower value.

Default value: 0.35 (74% active)

<add key="IndexMaxIdlePeriod" value="0.9" />

Purpose: Assign the idle (inactive) period for the least active indexing cycle: active duty% @ max = 1/(1 + [value]) A smaller value represents a shorter idle time, and a larger proportion of the cycle actively indexing.

Expected values (decimal): Numbers from IndexMinIdlePeriod+0.1 to 10. The value must be larger than IndexMinIdlePeriod. Values outside this range are assigned the closest upper or lower value.

Default value: 0.9 (53% active)

<add key="IndexSlowestQueueCount" value="100" />

Purpose: This is the first inflection point as the queue grows from zero. The goal is to set a value that almost keeps up with new additions to the queue; both smaller and larger queue counts have better performance. In most cases, values between 50 and 500 provide a good balance between indexing speed and idle cycle allocation to other processes.

Expected values (integer): Numbers from 1 to 450000. Values outside this range are assigned the closest upper or lower value.

Default value: 100

<add key="IndexFastestQueueCount" value="2000" />

Purpose: This is the second inflection point that moves from an increasingly active index cycle to its final sustained value. Values between 1000 and 2000 work well for more capable hardware & software resources; higher queue counts are appropriate with less capable hardware or when using SQL Server Express. Consider temporarily reducing this value when using the Batch Importer tool during system initialization.

Expected values (integer): Numbers from IndexSlowestQueueCount+1 to 500000. The value must be larger than IndexSlowestQueueCount. Values outside this range are assigned the closest upper or lower value.

Default value: 2000

<add key="IndexItemBatchSize" value="50" />

Purpose: This specifies the number of items (part, document, and change records) that are indexed as a group. Smaller batch sizes require more database queries, while larger batch sizes have longer active cycles that may interfere with other processes.

Expected values (integer): Numbers from 1 to 1000. Values outside this range are assigned the closest upper or lower value.

Default value: 50

The following key values work together to control the item and file indexing engine.

<add key="IndexFileBatchSize" value="10" />

Purpose: This specifies the number of file attachments that are indexed as a group. Smaller batch sizes require more database queries, while larger batch sizes have longer active cycles that may interfere with Windows Search servicing other applications.

Expected values (integer): Numbers from 1 to 1000. Values outside this range are assigned the closest upper or lower value.

Default value: 10

<add key="IndexNoEventWaitTime" value="30000" />

Purpose: Forces a periodic polling of the index queues, in the rare case where an indexing event was not detected. The value is in milliseconds. Very short times can interfere with normal indexing cycles, while large values don't provide much benefit. The default value usually works well.

Expected values (integer): Numbers from 1000 (1 second) to 300000 (5 minutes). Values outside this range are assigned the closest upper or lower value.

Default value: 30000

<add key="IndexUseStopWords" value="True" />

Purpose: When value is True, do not index low-utility English words (and, the). When False, all words are indexed as searchable tokens.

Expected values (Boolean): Values of True or False (case-insensitive). An unrecognized value is assigned as True.

Default value: True

<add key="JobFactor" value="1" />§

Purpose: Service scheduled task polling interval, where a higher number represents a longer pause between scheduled events like indexing. Shorter pauses (a smaller number) result in more frequent processing and a heavier load on system resources. Total cycle time is processing time plus pause time.

When the JobFactor is 1, pause values are:

• SMTP mail sender service: 2 minutes

• Access refresh service: 1 hour

• Client cache regen service: 4 hours

• Collection summaries regen service: 4 hours

Expected values (decimal): Numbers from 0.1 (fast) to 10 (slow); values outside this range are assigned the closest upper or lower value.

Default value: 1

<add key="LDAPContextOptions" value="0" />§

Introduced in PDXpert 15.0.

Purpose: Specifies the AD/LDAP options that are used for binding to the server. The value can include multiple options that are summed to an integer value, and then applied to the ValidateCredentials(string, string, ContextOptions) method overload.

Some settings may require or exclude other settings; or not be useful with the LDAP PrincipalContext(ContextType.Domain, string) parameter. System.DirectoryServices.AccountManagement.PrincipalContext

Name	Value	Summary
(default)	0	The ContextOptions value is not specified, and uses the ValidateCredentials(user, password) overload with .NET default value.
Negotiate	1	The client is authenticated by using either Kerberos or NTLM. When the user name and password are not provided, the Account Management API binds to the object by using the security context of the calling thread, which is either the security context of the user account under which the application is running or of the client user account that the calling thread represents.
SimpleBind	2	The client is authenticated by using the Basic authentication.
SecureSocketLayer	4	The channel is encrypted by using the Secure Sockets Layer (SSL). Active Directory requires that the Certificate Services be installed to support SSL.
Signing	8	The integrity of the data is verified. This flag can only be used with the Negotiate context option and is not available with the simple bind option.
Sealing	16	The data is encrypted by using Kerberos.
ServerBind	32	Specify this flag when you use the domain context type if the application is binding to a specific server name.

See: .NET ContextOptions reference

Expected values (integer): Summed value from 0 to 63; values outside this range are assigned 0. For example:  Negotiate + Signing + Sealing = 25 

Default value: 0 or empty

Introduced: PDXpert 15.0. If the PDXpert.Service.exe.config file doesn't include this tag, you can add it to the file after the JobFactor setting:

<add key="ServiceHostName" value="" />§

Purpose: Specify the binding IP address used to listen for client communications. For example, you can exclude all LAN/WAN IP addresses in favor of the server's VPN address.

Expected values (IP4): Any IP address assigned to server computer.

Default value: None - server listens on all available network connections when empty.

<add key="ServiceTcpPort" value="48084" />§

The PDXpert client uses the default base value of 48084, unless it is directed to use a different value when the user logs into the client.

After setting a new ServiceTcpPort value, the PDXpert client log-in must include the same value in the Server computer's machine name textbox. For example, if the server's machine name is PLMSERVER and the ServiceTcpPort is set as 24042, then the client log-in value would be PLMSERVER:24042

Purpose: Specify the base TCP port number for client communications. Ports are defined as

• BASE+0 is used to send software updates to PDXpert client application. The value is also used in the client download links as http://servername:{base port}/client/setup
• BASE+1 is used for unencrypted communications, usually when local workstations connect to the server on a trusted network or VPN.
• BASE+2 is used for encrypted communications, usually when remote workstations connect to the public IP address of the server.
• BASE+3 is reserved for future use.

Expected values (integer): Any available range of four sequential TCP ports within the range 1024 to 49151.

Default value: 48084