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.

Table 1. Agent startup locations and descriptions
Agent Location Description
Data Import Agent Application Server
  • Looks for all tab-delimited files that are uploaded and imports the data into the platform.
  • On all application servers, if there are multiple application servers.
  • Must be turned on only if you are using Data Integrator (DI). For more information, see Multi-Threaded Agents.
DataConnect Agent Application Server
  • Looks for DataConnect (DC) jobs in the Job Control table that are ready to run. When the agent finds a job, it creates an appropriate smart object for the job. Then the agent posts an asynchronous workflow event to initiate the workflow that pulls the external data into the IBM TRIRIGA database tables.
  • This agent is on an application server because it needs access to the userfiles directory.
  • Turn on this agent only if you are using DataConnect.
Object Migration Agent Application Server
  • Migrates TRIRIGA objects from one environment to another environment.
  • Regardless of how many application servers exist, only one instance of this agent can run.
  • Turn on this agent only if you are performing an object migration (OM) task. If left on constantly, the system might make unscheduled application changes.
Object Publish Agent Application Server
  • Publishes TRIRIGA objects in the platform.
  • Regardless of how many application servers exist, only one instance of this agent can run.
  • Turn on this agent when you are changing application objects in the Data Modeler.

Platform Maintenance Scheduler. Formerly Cleanup Agent.

Process Server
  • Conducts data cleanup and runs an analysis on the database. Removes all data in the state of null and removes DataConnect (DC) jobs and staging table entries that are obsolete or completed. Cleans up completed workflow instances that do not have any user-operable tasks, such as user tasks and approval tasks, within the workflow.
  • This significant agent must always be turned on. Review the server log regularly to confirm its proper execution. For the location of log files, see Identifying performance problems.
  • The cleanup commands in the Administrator Console are different per database type. These commands can be modified and expanded based on system requirements.
Extended Formula Agent Process Server
  • Looks for and processes queued extended formulas.
  • Significant agent that must always be turned on.
Formula Recalc Agent Process Server
  • Recalculates paths.
  • Must always be turned on.
Incoming Mail Agent Process Server
  • Downloads mail from a Post Office Protocol 3 (POP3) server or Internet Message Access Protocol (IMAP) server and converts them into email message records.
  • Turn on this agent only if you have an IBM TRIRIGA Connector for Offline Forms license and are using the Offlining component.
Report Queue Agent Process Server
  • Retrieves queued report requests, processes the report, and notifies the user.
  • On the process server where BIRT reports are processed, if a separate BIRT process server is used.
  • Turn on this agent only if you are using queued reports. No reports are delivered this way with the as-delivered TRIRIGA. For more information, see the Multi-Threaded Agents section.
Reserve SMTP Agent Process Server
  • Receives and processes reservation emails that Microsoft Exchange sends. This SMTP receiver service allows Exchange to communicate with TRIRIGA and allows it to manage resources in Reserve. A Send connector in Microsoft Exchange is configured to forward any email address with the reservation-specific subdomain to the TRIRIGA application server that runs this SMTP agent.
  • Turn on this agent only if you have an IBM TRIRIGA Workplace Reservation Manager (Reserve) license and are using the Reserve product.
Scheduler Agent Process Server
  • Looks for and processes all scheduled and recurring events in the platform.
  • Significant agent that must always be turned on.
SNMP Agent Process Server
  • Receives and processes Simple Network Management Protocol (SNMP) traps. An analytic event from a building equipment asset is created for an SNMP trap. When the SNMP trap is received, a configured workflow is triggered. This workflow is given information on the SNMP trap by using triSnmpPdu and triSnmpPduVariable system business objects. SNMP traps include traps that are used for the IBM TRIRIGA Real Estate Environmental Sustainability Impact Manager.
  • Turn on this agent only if you are using SNMP traps. For more information, see the Prerequisite setup for using TRIRIGA Real Estate Environmental Sustainability Impact Manager.
Workflow Agent Process Server
  • Processes queued workflow events and the asynchronous workflows that are registered for those events.
  • Significant agent that must always be turned on.
Workflow Future Agent Process Server
  • Processes actions from a workflow that are set up to trigger at a future date.
  • Lightweight agent that must always be turned on.
  • Used by many applications including, but not limited to, BIM, Job Scheduling, Reserve, and Lease.
Workflow Notification Agent Process Server
  • Looks for and processes workflow notifications in the platform, including those notifications to be sent at a scheduled time.
  • Significant agent that must always be turned on.
Disabling Agents

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.
Multiple JVMs Per Server

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

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.
Workflow agent
Multiple workflow agents:

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.
Platform Maintenance Scheduler

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
Extended formula agent

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.

Incoming mail agent

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.