System properties
Use the system properties in the TRIRIGAWEB.properties file to tune performance in TRIRIGA®.
TRIRIGAWEB.properties
Most system properties are maintained in the TRIRIGAWEB.properties file and are available dynamically in the Administrator Console. For changes in the TRIRIGAWEB.properties file to take effect, restart the application server.
The variables and settings in TRIRIGA properties files might change between versions. After an upgrade installation, review each newly installed properties file and adjust values for your implementation.
Configure the following key properties and values for your environment:
- CLEAN_HOUR
- Specifies the hour, from 0 to 23, at which the Platform Maintenance Scheduler Cleanup Agent
starts on the server.
- Recommended value: An hour when the system has the least number of users.
- Default value: 0
- CLEAN_TIMEOUT
- Specifies the number of minutes that the Platform Maintenance Scheduler can run.
- Default value: 120
- WF_INSTANCE_SAVE
- Configures when workflow instances are saved. Use WF_INSTANCE_SAVE to debug
in a nonproduction environment. In a production environment, always set to
ERRORS_ONLY because of the significant load on the entire system if turned on.
ERRORS_ONLY is the default and saves the tracing information only for those
workflows that fail with an ERROR condition. The value of NEVER was renamed to
ERRORS_ONLY, but the system accepts both values, where NEVER is equal to
ERRORS_ONLY. Change this property without a system restart by using the Workflow
Agent Manager in the Administrator Console. For more information, see Workflow Agent
and Workflow Performance.
- Recommended value: ERRORS_ONLY
- Default value: ERRORS_ONLY
- Value for mass or batch loading records: DATA_LOAD This value bypasses and never saves any instances, which increases performance and decreases database size. Use this value in production environments, especially if the production environment has many workflows that end in error or have Stop tasks, but no application developers are available to correct the problems in the workflows.
- WF_INSTANCE_SAVE_24HR_THRESHOLD
- Configures when workflow instances stop being saved. When excessive workflow instances are
saved, the platform stops saving if the number of saved instances exceeds a defined threshold.
Administrators can set an upper limit for how many workflow instances are saved in a 24-hour period.
This setting prevents excessive workflow instance data from affecting the Platform Maintenance
Scheduler. The default value is 1000. To override the default value, set
WF_INSTANCE_SAVE_24HR_THRESHOLD=#### where #### is a
positive integer, and restart the server. Set WF_INSTANCE_SAVE_24HR_THRESHOLD
on each server in the environment. Do not set this value to a number larger than 10000 or the
Platform Maintenance Scheduler takes a long time to remove the debugging records.
- Default value: 1000
- Maximum Value: 10000
- USE_WF_BINARY_LOAD
- If set to Y, the system uses the binary workflow load process, which provides a
faster load time. If the workflow templates cannot be found in the workflow template cache, they are
loaded with their stored binary version.
- Recommended value: Y
- WF_HISTORY_RETENTION_DAYS
- The Platform Maintenance Scheduler deletes workflow instances that are not waiting on user or
approval tasks that are older than this number of days. This value does not have a large impact if
the WF_INSTANCE_SAVE property is set to ERRORS_ONLY. But on a
system that is saving many workflow instances, this value can significantly impact system performance.
- Recommended value: 5
- Default value: 10
- DC_HISTORY_RETENTION_DAYS
- The Platform Maintenance Scheduler deletes completed or obsolete DataConnect jobs that are older
than this number of days. If you do not use DataConnect, then changing this value does not affect
your system.
- Recommended value: 5
- Default value: 10
- REPORT_MEMORY_USAGE_LIMIT
- Specifies the maximum percentage of available server memory that can be used while running a
user report. If a user sees a There are not enough resources available to run the
report error for a query, the query might be the cause of the error. However, other
concurrent processes might consume memory while the query was assembling its results. Valid values
are between 0 and 100. Values of 0 and
100 disable enforced limits and allow a single query that a user initiates to run
the server out of memory. Tune this value so that no report uses more than 1-2 GB of heap size.
However, temporarily increase the value to handle especially large reports.
- Default value: 90
- BIRT_MEMORY_USAGE_LIMIT
- Specifies the maximum percentage of available server memory that can be used to assemble the
BIRT report query results. If the memory requirement for a query exceeds
BIRT_MEMORY_USAGE_LIMIT, the query gives an error. However, other concurrent
processes might use memory while the query was assembling its results. Valid values are between
0 and 100. Values of 0 and 100
disable any enforced limits and allow a single query that a single user initiates to run the server
out of memory.
- Recommended value: 35
- TREE_PAGING_SIZE
- Specifies the maximum number of child records to show in the hierarchy tree for Location,
Organization, Geography, Classification, Cost Code, and newly-created hierarchical managers. The
system includes the child records of the root node in the count. Increasing this value can affect performance.
- Recommended value: 1000
- BRAVA_EXCLUDE_LIST
- Specifies a comma-separated list of file extensions that cannot be viewed with Brava while using
the Document Manager component. Any file extension that is not listed is passed to Brava. This
property is only used when using Brava. If Brava is not installed, then the property is ignored.
- Recommended value: html, htm, svg, rpt, zip, exe, doc, docx, xls, xlsx, ppt, pptx, pdf, txt, xml
- SESSION_HISTORY_TRACKING
- Indicates which user sessions are logged to the SESSION_HISTORY table. If set to
WEB_USER, user sessions from IBM®
TRIRIGA Connector for Business Applications
(CBA) are not logged to the SESSION_HISTORY table. If your system has many integration transactions,
this table can grow quickly and use system resources.
- Recommended value: WEB_USER
- Default value: ALL
- BIRT_PROCESS_SERVER
- The following properties enable BIRT report offloading. By sending the report processing to
another JVM, BIRT report offloading can eliminate system resource usage by BIRT reports on a server
with user sessions. For more information, see Advanced Reporting (BIRT).
- BIRT_PROCESS_SERVER_HOST_NAME
- BIRT_PROCESS_SERVER_PORT
- BIRT_PROCESS_SERVER_LISTENING_PORT
For more information about system properties, see the Installation and Implementation Guide.
Agents
The IBM TRIRIGA Application Platform uses business process agents to perform automated work for its applications. When the system identifies an event that requires a business process agent to fulfill, it places the event into a queue where the agent can perform work on it. These agents are critical to sustaining a healthy system and managing system performance.
Disable or stop any unused agents. Also, do not configure these agents to start on system restart. These agents consume system resources, and some are multi-threaded, which can allow for multiple instances, and, if not tuned properly, can either restrict or overrun system resources. On a system that has a minimum of 2 servers (JVMs), most agents must run on a designated process server that does not have users logging in to it. Agents that require user connectivity, such as the Data Import Agent, are an exception to the rule for running an agent on the process server.
The following sections describe properties that are related to agents and are managed by editing the TRIRIGAWEB.properties file or by using the Administrator Console managers. For more information about agents, see Business process agents.
The following table shows the suggested startup locations and descriptions of the agents.
Agent | Location | Description |
---|---|---|
Data Import Agent | Application Server |
|
DataConnect Agent | Application Server |
|
Object Migration Agent | Application Server |
|
Object Publish Agent | Application Server |
|
Platform Maintenance Scheduler. Formerly Cleanup Agent. |
Process Server |
|
Extended Formula Agent | Process Server |
|
Formula Recalc Agent | Process Server |
|
Incoming Mail Agent | Process Server |
|
Report Queue Agent | Process Server |
|
Reserve SMTP Agent | Process Server |
|
Scheduler Agent | Process Server |
|
SNMP Agent | Process Server |
|
Workflow Agent | Process Server |
|
Workflow Future Agent | Process Server |
|
Workflow Notification Agent | Process Server |
|
Disabling agents that are not needed limits the use of system resources and keeps them from being started:
- AGENTS_NOT_ALLOWED: This property limits the agents that administrators can use.
- The value is a comma-delimited list of agents that are not allowed to run on this server. For an example, or for the names of the agents to use in this list, see the comments in the TRIRIGAWEB.properties file.
- A blank value allows any agent to be started on a server but does not start any agent automatically.
If you plan to have multiple JVMs on the same machine, set the following properties to allow for unique names per server instead of the default hostname and ID.
- INSTANCE_ID
- Overrides the default machine ID.
- When two or more TRIRIGA servers are running on the same physical machine, INSTANCE_ID must be unique for independent agent management.
- Leave a blank value if you are running a single instance per physical machine.
- INSTANCE_NAME
- Overrides the default machine name.
- When two or more TRIRIGA servers are running on the same physical machine, INSTANCE_NAME must be unique for independent agent management.
- Leave a blank value if you are running a single instance per physical machine.
Multi-threaded agents allow you to set a limit on how many threads each agent uses. Increasing the following threads can increase the JVM heap usage, but also increase the JDBC connections and the load on the database server.
These agent threads can also be managed dynamically without a restart by the Threads Manager in the Administrator Console.
The following list shows which agents have their own unique maximum thread count per server.
- Data Import Agent
- This multi-threaded agent controls data loads by using the Data Integrator tool. The thread
count is also used by IBM
TRIRIGA
Connector for Business Applications (CBA) to allow for throttling integration requests. The agent
does not have to be enabled to use the Connector for Business Applications (CBA).
- Property: DataImportAgentMaxThreads
- Recommended Value is 2 to 8 depending on the need.
- Report Queue Agent
- This agent retrieves queued report requests then runs the report and notifies users. For more
information on queued reports, see Queued Reports (Asynchronous).
- Property: ReportQueueAgentMaxThreads
- Recommended Value is 1 to 4 depending on the need. If unused, set this agent to 1.
- Scheduler Agent
- This agent looks for and processes all scheduled and recurring events in the system. This agent
must always be on, but the threads that are needed are low.
- Property: SchedulerAgentMaxThreads
- Recommended Value is 1 to 4 depending on the need.
- Workflow (WF) Agent
- This multi-server, multi-threaded agent processes queued workflow events and runs the
asynchronous workflows that are registered for them. Setting the Workflow Agent maximum threads to a
large value can slow the system. Typically, the maximum threads value for the Workflow Agent does
not exceed more than 2 to 4 times the CPU core count on the database server but can be adjusted
higher if tested properly. For more information, see Workflow Agent and Workflow
Performance.
- Property: WFAgentMaxThreads
- Related Property: WF_AGENT_MAX_ACTIVE_PER_USER
- Recommended Value is 4 to 32 depending on load.
- CAD Integrator
- This setting controls server-side work when syncing attached CAD drawings from CAD
Integrator/Publisher. The number of CAD Integrator threads that the platform allocates to CAD
Integrator/Publisher is managed by the Threads Manager in the Administrator Console.
- Property: CadIntegratorMaxThreads
- Recommended Value is 5.
Do not implement multiple Workflow Agents unless the additional agents are configured for dedicated users or groups. For more information, see Limiting the Number of Workflow Agents.
Take the following actions in an environment with multiple workflow agents:
- Add and change the WF_AGENT_SLEEPTIME property value at the direction of IBM Support or if you see contention on the WF_EVENT table in the database.
- If you change the WF_AGENT_SLEEPTIME property, make sure that each process server running the Workflow Agent has a unique value that is not duplicated on any other server that is connected to the same database. This setup prevents Workflow Agents from waking up at the same time and eases contention on the WF_EVENT table by giving more control for when the Workflow Agent wakes up. On each server, set a different value. But if the property is not set, the default value is a random number between 4500-5500 milliseconds.
- Add the WF_AGENT_SLEEPTIME property to the TRIRIGAWEB.properties file to change the time when the Workflow Agent wakes up and checks for new events. If events are already in the queue, the WF_AGENT_WAITTIME property waits before picking up new workflows that are already in the queue.
The Workflow Agent must always have at least one instance running to process asynchronous workflows. Almost every application process in TRIRIGA uses synchronous and asynchronous workflows, including all types of integrations, especially CAD Integrator/Publisher. System performance is affected by the Workflow Agent if it is not processing asynchronous processes quickly enough. If the Workflow Agent properties are not tuned properly, then the workflow queue can get backed up and grow quickly.
Use the Administrator Console to configure all the workflow tuning properties.
Use the following methods to manage Workflow Agent performance:
- Multiple Workflow Agents: If multiple agents are set up, you can designate specific users for a Workflow Agent exclusively or to give priority. Do not implement multiple Workflow Agents unless the additional agents are configured for dedicated users or groups. For more information, see Limiting the Number of Workflow Agents.
- Tune the threads and threads per user: With multiple agents, configure threads independently. A
typical scenario for having multiple is when you have one process server that is configured as a
general process server and another process server for integrations or data loads with a dedicated
user to process these items.
- Property: WFAgentMaxThreads
- Property: WF_AGENT_MAX_ACTIVE_PER_USER. If you have a Workflow Agent that is assigned to a single user, for example, a unique user for integration purposes, set this value equal to the value of WFAgentMaxThreads. For general-purpose process servers, the workflow max active per-user property must be set to 70% of the agent maximum threads, which prevents a single user from maxing out the use of workflow threads.
- Workflow Instance Saving: Set the workflow instance recording property WF_INSTANCE_SAVE to ERRORS_ONLY to achieve the best workflow performance. For more information, see Workflow Performance.
The Platform Maintenance Scheduler performs multiple system cleanup activities at a specified time each day. The Platform Maintenance Scheduler is a critical agent in sustaining your TRIRIGA system. This agent must always be enabled to help maintain system health. By default, the Platform Maintenance Scheduler performs the following activities:
- Clean up BO instance records that are stale, such as records marked for deletion and temporary objects.
- Clean up workflow instance data.
- Clean up scheduled events.
- Clean up Document Manager data.
- Run cleanup commands, for example database analyze.
The following cleanup commands are maintained in TRIRIGAWEB.properties file. You can configure the cleanup commands by using the Platform Maintenance Scheduler Manager in the Administrator Console. The commands are the only components that can be turned off if you choose to run them externally from the agent.
- CLEAN_HOUR
- Specifies the hour, from 0 to 23, at which the Platform Maintenance Scheduler Cleanup Agent
starts on the server.
- Recommended value: A time when the system has the least number of users.
- Default value: 0
- CLEAN_TIMEOUT
- Specifies the number of minutes that the Platform Maintenance Scheduler can run.
- Default value: 0
- WF_HISTORY_RETENTION_DAYS
- The Platform Maintenance Scheduler deletes workflow instances that are not waiting on a user or
on approval tasks that are older than this number of days. This value does not have a large impact
if the WF_INSTANCE_SAVE property is set to ERRORS_ONLY. But on
a system that is saving many workflow instances, this value can significantly impact system performance.
- Recommended value: 5
- Default value: 10
- DC_HISTORY_RETENTION_DAYS
- The Platform Maintenance Scheduler deletes completed or obsolete DataConnect jobs that are
older than this number of days. If you do not use DataConnect, then changing this value does not
affect your system.
- Recommended value: 5
- Default value: 10
Ensures that records are not put into the Extended Formula queue when it is not required. Objects that are being loaded must have their formulas calculated once at the end of the process. If you encounter any workflows that are not exhibiting this behavior, contact IBM Support.
Invalid email addresses in the TO: or CC: line can impact the acceptance and delivery of the individual email messages. The agent attempts to process all mail that is sent to the inbox. If an email contains an invalid address, that message might be removed from the inbox and not processed, and the agent continues processing the other messages in the inbox.
For outgoing mail, an invalid email in the TO: or CC: line might cause that message to not be sent, and an error is written in the log. Other outgoing notifications in the queue continue to be processed.