Configuring Background Method Servers

Installation and Upgrade > Advanced Deployment Considerations > Advanced Windchill Configurations > Configuring Background Method Servers

Background servers are used to process background queues. Under most circumstances, a single background method server is sufficient for processing background queues. For information on managing background queues, see Background Queues.

However, it may be necessary to configure multiple background method servers to distribute the load across multiple processes.

The following sections describe how to configure background method servers and set up queue groups that are used by the background servers.

Configuring a Method Server for Background Queues

Set the following Windchill properties in the wt.properties file to configure a separate method server dedicated to running background queues:

wt.manager.monitor.start.BackgroundMethodServer=1
wt.queue.executeQueues=false

Setting the wt.queue.executeQueues=false property in wt.properties generally stops queue processing. Then including wt.queue.executeQueue=true in the background method server launch command ensures that only the background method server associated with the launch command executes queues.

Configuring Multiple Background Method Servers

Configuring multiple background method servers consists of the following:

• Deciding on a new service name and then constructing the corresponding launch command property for each background method server.

• Adding each new service name to the list of services that the server manager monitors.

To construct the launch command property for a background method server, you can use many of the defaults from the wt.manager.cmd.BackgroundMethodServer property, overriding the defaults only as necessary by specifying values for properties that are nested within the wt.manager.cmd.BackgroundMethodServer property. Name each new property using the following format:

wt.manager.cmd.<service_name>

where <service_name> is the name of the new background method server.

When only one background method server is used, the service name is BackgroundMethodServer. The general Windchill convention for naming multiple background servers is to append an underscore and digit when there are multiple background method servers, starting with 0 for the first server. For example, you can use the following names for three background method servers:

BackgroundMS_0
BackgroundMS_1
BackgroundMS_2

The following properties set up a new background server named BackgroundMS_1 that uses the defaults from the wt.manager.cmd.BackgroundMethodServer property:

wt.manager.cmd.BackgroundMS_1=$(wt.manager.cmd.BackgroundMethodServer)
wt.manager.cmd.BackgroundMS_1Launcher=
$(wt.manager.cmd.BackgroundMethodServerLauncher)

Additionally, change the following defaults that are established through the wt.manager.cmd.BackgroundMethodServer property:

• The server manager normally starts a replacement method server when a method server becomes unresponsive. However, this does not occur when the service name is "BackgroundMethodServer". When this service name is used, the server manager ensures that the previous instance is really gone, and not just hung, prior to starting a new instance. Ensuring that the previous instance is gone is important to avoid possible data corruption. To ensure that there is only one instance of a background method server that is not named "BackgroundMethodServer", set the following property:

wt.manager.cmd.BackgroundMS_1.singleton.enforce=true

• The maximum heap size for method servers is set in the wt.method.maxHeap property. This is overridden for the service named "BackgroundMethodServer". This service uses the value set in the wt.method.bg.maxHeap property. To use the value set in the wt.method.bg.maxHeap property in a background method server that is not named "BackgroundMethodServer", set the following property:

wt.manager.cmd.BackgroundMS_1.param.4=$(wt.method.bg.maxHeap)

Alternatively, you can set this property to a different value for each background method server instead of setting it to the value stored in the wt.method.bg.maxHeap property.

• The queue group name set by wt.manager.cmd.BackgroundMethodServer is Default. Change the name of the queue group to the group name or names that have been set up for the background method server by setting the following property:

wt.manager.cmd.BackgroundMS_1.param.5=<list_of_groups>

where <list_of_groups> is a comma-separated list of group names.

• When a system is configured to use a BackgroundMethodServer, by default the BackgroundMethodServer runs the Embedded Servlet Engine with the Solr web application. The Solr web application runs the search capabilities in Windchill. Only a single BackgroundMethodServer across an entire Windchill system (including across all clusters) should run the Embedded Servlet Engine that has the Solr web application. You must disable the Embedded Servlet Engine in all other background method servers.

Disabling the Embedded Servlet Engine in a background method server is done by setting the following property to an empty value

wt.manager.cmd.<service_name>.param.12

where <service_name> is the name of the background method server.

For example, when two BackgroundMethodServers are configured: BackgroundMS_0 and BackgroundMS_1 and BackgroundMS_0 is used to run the Solr web application, then the following property must be set to disable the Embedded Servlet Engine in BackgroundMS_1:

wt.manager.cmd.BackgroundMS_1.param.12=

For details on grouping queues, see the section Grouping Queues for Background Method Server Distribution. Be sure to include the Default queue group on one background method server.

The wt.manager.cmd.BackgroundMethodServer property overrides wt.method.minPort property value so that the minimum port number for background method servers is 3000. You do not need to change this value for individual background method servers. Only change the wt.manager.cmd.BackgroundMethodServer port specification to specify something other than 3000 if you believe starting with a port number of 3000 is inappropriate in your environment.

For additional information about the nested properties that are used to construct background method servers, refer to the property descriptions in properties.html that is located in your <Windchill>/codebase directory and to the Javadoc for the wt.manager.cmd.MethodServerLauncher class and its base class, wt.manager.BaseServerLauncher, that is located in your <Windchill>/codebase/wt/clients/library/api directory.

After setting up queue groups, use the xconfmanager to set and propagate the properties for each new background method server. For example, assume you want to set up two background method servers as follows:

• Service names of BackgroundMS_0 and BackgroundMS_1.

• Embedded Servlet Engine with the Solr web application is set up in only BackgroundMS_0.

• The maximum heap size for background method servers is set in wt.method.bg.maxHeap.

• Queue groups named group0 and group1, where qroup0 is assigned to BackgroundMS_0, and group1 and Default are assigned to BackgroundMS_1.

Enter the following xconfmanager commands:

Enter each command on a single line. The double quote marks are used to ensure that the $ character is read correctly as the variable indicator. On UNIX systems, the $ character must be escaped with the \ character. For example:

"wt.manager.cmd.BackgroundMS_0=\$(wt.manager.cmd.BackgroundMethodServer)"

After setting the new properties, you must also update wt.manager.monitor.services to include the new background method servers.

For example, to monitor the method server and two background method servers, use the following xconfmanager command:

xconfmanager -s
wt.manager.monitor.services="MethodServer BackgroundMS_0 BackgroundMS_1" -p

If you want to configure high availability queue processing, set up two background method servers to process the same queue groups. For example, assume you want to set up three background method servers as follows:

• Service names of BackgroundMS_0, BackgroundMS_1, and BackgroundMS_2.

• Embedded Servlet Engine with the Solr web application is set up in only BackgroundMS_0.

• The maximum heap size for background method servers is set in wt.method.bg.maxHeap.

• Queue groups named group0 and group1, where qroup0 is assigned to BackgroundMS_0, and group1 and Default are assigned to both BackgroundMS_1 and BackgroundMS_2.

Enter the following xconfmanager commands:

xconfmanager -s
"wt.manager.cmd.BackgroundMS_0=$(wt.manager.cmd.BackgroundMethodServer)"
-s "wt.manager.cmd.BackgroundMS_0Launcher=
$(wt.manager.cmd.BackgroundMethodServerLauncher)"
-s wt.manager.cmd.BackgroundMS_0.singleton.enforce=true
-s "wt.manager.cmd.BackgroundMS_0.param.4=$(wt.method.bg.maxHeap)"
-s wt.manager.cmd.BackgroundMS_0.param.5=group0
-p

xconfmanager -s
"wt.manager.cmd.BackgroundMS_1=$(wt.manager.cmd.BackgroundMethodServer)"
-s "wt.manager.cmd.BackgroundMS_1Launcher=
$(wt.manager.cmd.BackgroundMethodServerLauncher)"
-s wt.manager.cmd.BackgroundMS_1.singleton.enforce=true
-s "wt.manager.cmd.BackgroundMS_1.param.4=$(wt.method.bg.maxHeap)"
-s "wt.manager.cmd.BackgroundMS_1.param.5=group1,Default"
-s wt.manager.cmd.BackgroundMS_1.param.12=
-p

xconfmanager -s
"wt.manager.cmd.BackgroundMS_2=$(wt.manager.cmd.BackgroundMethodServer)"
-s "wt.manager.cmd.BackgroundMS_2Launcher=
$(wt.manager.cmd.BackgroundMethodServerLauncher)"
-s wt.manager.cmd.BackgroundMS_2.singleton.enforce=true
-s "wt.manager.cmd.BackgroundMS_2.param.4=$(wt.method.bg.maxHeap)"
-s "wt.manager.cmd.BackgroundMS_2.param.5=group1,Default"
-s wt.manager.cmd.BackgroundMS_2.param.12=
-p

If you are considering configuring high availability queue processing, see Configuring the Worker Agent in a High Availability Windchill Cluster for more information.

Grouping Queues for Background Method Server Distribution

Queues can be distributed among background method servers by using queue grouping.

When you assign groups to background method servers, the queues that have not been assigned to any group are automatically assigned to the Default queue group and run on the background method server that has the Default group assigned. Each queue group must be assigned to at least one running method server. If a group is not assigned to a running background method server, the queues that from the group are not executed.

Set the same group to run on more than one background method server only when configuring high availability queue processing.

You can assign queues to groups in either of the following ways:

• Assign queues to groups through the Queue Manager utility. The group names can consist of alphanumeric characters. One or more queues can be assigned to the same group.

• Set properties manually, as follows.

Use the following properties to configure queue groups:

wt.queue.[queue name]=[group name]

This property assigns the queue to a group. A queue that is not given a group name is automatically assigned to the group Default.

The following example manually sets up two groups. One is for executing WfSharedPropagationQueues and all other queues, and the other is for executing WfSharedUserWorkQueue.

Set the following properties to assign the WfSharedPropagationQueues to queue group0:

wt.queue.WfSharedPropagationQueue1=group0
wt.queue.WfSharedPropagationQueue2=group0
.
.
wt.queue.WfSharedPropagationQueue9=group0
wt.queue.WfSharedPropagationQueue10=group0

Set the following properties to assign WfSharedUserWorkQueues to queue group1:

wt.queue.WfSharedUserWorkQueue1=group1
wt.queue.WfSharedUserWorkQueue2=group1
.
.
wt.queue.WfSharedUserWorkQueue9=group1
wt.queue.WfSharedUserWorkQueue10=group1

Set the following properties to assign WfSharedUserWorkQueues to queue group1:

wt.queue.WfSharedUserWorkQueue1=group1
wt.queue.WfSharedUserWorkQueue2=group1
.
.
wt.queue.WfSharedUserWorkQueue9=group1
wt.queue.WfSharedUserWorkQueue10=group1

Set the following property embedded in the wt.manager.cmd property to establish the list of queue groups that the server is to process. The default value for this property is the Default queue group.

wt.manager.cmd.<service_name>.param.5=<list_of_groups>

where <service_name> is the name of the background server and <list_of_groups> is a comma separated list of group names. Be sure to include Default as one of the group names for at least one background method server.