Changing preferences

Much of HCL OneTest™ API behavior can be customized in the application preferences.

To view or modify these preferences, select Window > Preferences or Project > Preferences in the main HCL OneTest API menu bar.


General preferences control the behavior of HCL OneTest API on the whole, as follows:

Table 1. General preferences
Preference Description
Run Resources Controls how test resources are executed. From disk (saved) executes the last saved version of the resource. From memory (current) executes the resource in its current state, including any unsaved changes. If Auto save on run is enabled (when From disk is in use), test resources are saved automatically when executed.
Prompt for Suite Run Archive Policy If this option is selected, you are prompted to use a suite archive policy on the results from any suite that you run.
Display prompt on exit Asks the user to confirm whether to exit HCL OneTest API.
Show header information panels in editors In message editors, displays a description panel in the headers area (once you are more familiar with HCL OneTest API, they can be disabled to save screen space).
Show Tag Data Store with editors Displays the Tag Data Store automatically whenever a message editor is opened.
Show project name in title bar Toggles the display of the current project name in the HCL OneTest API title bar.
Default Run Tests action to parallel execution Select this option if you want the Run process in parallel option in the Run Test dialog to be selected by default.
Run Button Mode (Removed in version 9.0.1) Controls the behavior of the Run button and F5: Run Selected always runs the selected test resource; Run Last Launched always runs the test resource that was executed last.
URL Connection Timeout Specifies a default timeout to use for connections in test actions.
Maximum Preview Rows The maximum number of rows to display in previews (for example, when you are importing a WSDL).
Maximum filtered message logs Specifies the maximum number of messages to log when you are using a filter on a message. To log all messages, enable the Log All option.
Maximum dependencies shown Specifies the maximum number of dependencies to display at one time in Architecture School’s logical view.
Tooltip display time (secs) Specifies the amount of time (in seconds) that tooltips are displayed when the cursor rests on an applicable icon. If left empty or if an invalid entry is set, the default value (that is, four seconds) is used. If set to zero, tooltips are not displayed at all.
Synchronization Filter Specifies a filter that ignores certain items that are found within a synchronization source (currently applies to only TIBCO BusinessWorks projects). The filter string can be modified as needed. Click Reset filter to restore the default value, which ignores .svn and .cvs folders (that is, for projects in SVN or CVS repositories).
Sort Method Specifies the strength of the sorting method used when sorting items based on the locale in several places in HCL OneTest API, such as the providers in Library Manager and the item trees in Test Lab and Test Factory. The following methods are available:
Typically used to denote differences between base characters (for example, "a" < "b"). It is the strongest difference. For example, dictionaries are divided into different sections by base character.
Accents in the characters are considered secondary differences (for example, "as" < "às" < "at"). Other differences between letters can also be considered secondary differences, depending on the language. A secondary difference is ignored when there is a primary difference anywhere in the strings.
Upper and lower case differences in characters are distinguished (for example, "ao" < "Ao" < "aò"). In addition, a variant of a letter differs from the base form. An example is the difference between large and small Kana. A tertiary difference is ignored when there is a primary or secondary difference anywhere in the strings.
Typically used to distinguish words with and without punctuation (for example, "ab" < "a-b" < "aB"). A quaternary difference is ignored when there is a primary, secondary, or tertiary difference anywhere in the strings.
Used as a tiebreaker when all other strengths are equal. The Unicode code point values of the NFD form of each string are compared. For example, Hebrew cantillation marks are only distinguished at this strength. Using this strength substantially decreases performance and increases the size of the collation key.

Look and feel

Use the Look and Feel preferences to specify which fonts to use throughout HCL OneTest API and the color to be used for highlighting null fields in data sources. Fonts could be fixed width or proportional.

Table 2. Look and feel preferences
Preference Description
Fonts Provides combination lists for selecting an available fixed width or proportional system font and the size of the font, to use in HCL OneTest API. Below each selection is a Sample field that displays a sample of text in the selected font. You can now select the size of the font as required.

The size of the font is fixed in the Logical View of the Architectural School as you have an option to zoom in and out.

Colors Controls the Color for null values option. Specifies the color to use for highlighting fields that are treated as null when you preview the contents of a file or Excel data source. For more information, see Test data sources.

To change the current color, click it and select a new color by using the Select color dialog that is displayed.

Note: If the proportional font is modified, HCL OneTest API must be restarted for the change to take effect. After you close the Preferences dialog, you will be prompted to restart now or restart later. If you restart later, the proportional font changes that you made are not immediately apparent in HCL OneTest API.

Server Settings

Server settings preferences control default behavior when servers are specified.

Table 3. Server setting preferences
Preference Description
Show server URL validation failed dialog This option is checked when you specify URLs for HCL Quality Server, HCL OneTest Server, and for the project results server configured in the project settings window. If you select this option and either URL fails validation, a dialog is displayed.
HCL OneTest Server Offline Token The offline token generated from the HCL OneTest Server is copied in this field. This token enables HCL OneTest API to connect to the HCL OneTest Server and access the secrets contained in the secrets collections that can be deployed in test runs and publish test reports to the HCL OneTest Server. For more information about offline tokens, see Accessing HCL OneTest Server.


You can configure the Git preferences so that the project test assets can be accessed from HCL OneTest API. For more information, see Setting preferences for Git.


Schema preferences control how HCL OneTest API works with schemas, as follows:

Table 4. Schema preferences
Preferences Description
Analysis Settings Controls the default selections to use for schema analysis (see Analyzing schemas), which can be overridden during analysis.
Cache Displays the number of files that are currently stored in HCL OneTest API schema cache, as well as the cache’s current size. To clear the cache (for example, to save disk space), click the Clear button.
Rebuild when saving resource Controls how HCL OneTest API rebuilds referenced schemas when it saves resources (for example, a SOAP message).
Schema Library Specifies whether to save schemas automatically (that is, when you are clicking away from the schema after you finish making changes).
Record Layouts Controls the appearance of grouping rows in record layouts (see Record layouts.) You can change the background color and the color of the text that is used in such rows.


With Message preferences, you can enable or disable default options to be applied when you are working with messages, as described in the following table.

Table 5. Message preferences
Preference Description
Message Expansion Level The number of levels of a message to expand in editors (used only when the editor is opened for the first time). A value of "0" expands all nodes in the message.
Enable initial interesting node expansion Controls which fields are expanded by default. If selected, HCL OneTest API only expands what are considered interesting nodes. If not selected, HCL OneTest API expands all nodes.

HCL OneTest API determines what is interesting, depending on the context.

For case action, stub input action, consumer actions (subscribe, receive request, receive reply), and producer actions (publisher, send request, send reply) , the following nodes are considered interesting:
  • Enabled store actions.
  • Enabled filter actions on leaf nodes.
  • Enabled validate or assert actions that contain tagged expressions on leaf nodes.
  • Enabled validate or assert actions that do not have expressions on leaf nodes. For example, DoesExist, IsNull, Length, NotNull (excluding type and name as they exist and are enabled by default).
  • Schema errors.
  • Nodes populated from the Rule Cache. See Rule Cache overview.
  • Nodes marked as repeating
For the message differencing window, the following nodes are considered interesting:
  • Difference, for example, added, removed, modified.
Content Default settings to use when you are creating messages:
Include Text nodes
Adds text nodes to message elements automatically when you create a message.
Include optional fields
Adds optional fields to a message according to the schema in use.
Limit generation of optional fields
Activates the Maximum Optional Fields field.
Maximum Optional Fields
Specify the maximum number of optional fields to add to the message.
Assert Default validation options when you are creating a message:
Accept fields in any order
Controls whether the order of message fields is considered during validation.
Ignore missing fields in received message
Controls whether missing fields in the received message causes a validation error.
Ignore additional fields in received message
Controls whether more fields in the received message cause a validation error.
Enable validation of time-based fields
Controls whether time-based fields (which are likely to be different) are considered during validation.
Message Import Option to handle imported messages:
Always link
Do not copy the text of the imported message.
Always copy
Copy the text rather than linking to it.
Always prompt
Ask whether to link or copy for each message.


Console preferences control the appearance and behavior of the output console in the Test Lab.

Table 6. Console preferences
Preference Description

Success color
Error color
Information color
Warning color

Controls the colors that are used to indicate message status in the console. By default, green is used for success messages, red is used for errors, blue is used for information, and orange is used for warnings.

To modify the default colors, click an existing color and select a new one in the Select color dialog.

Retain message context data Enables or disables the selection of console output (where validation errors occur) to invoke the message comparison tool.
Enable debugging output Enables or disables debug messages in the console when you are running a test. When enabled, more details of the various actions that are processed in the test are provided.
Action Prefix Determines whether the Technical or Business view descriptions are displayed in the console for test step action names.
Console Caching When enabled, users can specify that console output for no more than the selected number of tests be cached by HCL OneTest API. Caching is disabled if no results database provider is specified.
Stub default log level Levels include:
  • None
  • Normal
  • Debug


Recording preferences control various aspects of the recording process in the Recording Studio.

Table 7. Recording preferences
Preference Description
Sequence Numbering Two numbering options are available:
Unified counter
Numbers events in the order that they are received, regardless of the monitor that recorded them. For example, six events from two different monitors are numbered 1, 2, 3, 4, 5, 6.
Counter per monitor
Numbers events sequentially for each monitored operation. For example, six total events from two different monitors might be numbered 1, 2, 1, 2, 3, 4
Database Recording If you are recording from a database resource and the stub information in the database definition is incomplete, you have the following options:
  • Prompt when the stub settings are incomplete
  • Always record with incomplete stub settings
  • Do not record with incomplete stub settings
Simulation Data Editing You have the following options for editing a virtual database when the associated stub is running:
  • Prompt when database stubs are running
  • Always edit when database stubs are running
  • Do not edit when database stubs are running
Transport Specific Recording You can set two preferences:
Default Method for IP based
Select a default recording mode for IP-based transports (FIX, TCP/IP, HTTP):
Packet Capture
Requires packet capture software. For information about packet capture software, see Web services and Limitations of packet capture.
External Proxy Server
The proxies in the HCL Quality Server enable HCL OneTest API and HCL OneTest Virtualization to record all HTTP(S) traffic that is routed through the proxy. For information about this option, see HCL OneTest API reference and HTTP/TCP proxy setup.
Default Mode for WebSphere® MQ
You can select any of the following default modes for IBM® WebSphere MQ:
  • Queue Browsing
  • Proxy Queues
  • Mirror Queues
  • Dynamic Mirror Queues
  • Queue Aliasing
For information about these modes, see Recording settings.

Message Comparison

Message comparison preferences control the appearance and behavior of the Message Differences window.

Table 8. Message comparison preferences
Preference Description
Colors Controls the colors that are used to indicate difference types or ignored nodes. To modify a selected color, click it and select a new one in the Select color dialog.
Reset to Color Scheme Click one of the buttons to set all colors to the Pastel or Vibrant scheme.
Navigation Controls whether looping is enabled in the Message Differences window. If Do not loop when navigating differences is enabled, the Next difference and Previous difference buttons are disabled when the last or first difference is selected. In that case, you cannot loop back to the beginning or end of the differences. If this option is cleared, the buttons are always enabled and they loop to the beginning or end of the message to view the next or previous difference. Both buttons are disabled if there are no differences between the messages.
Always retain the rules Sets the default behavior when you are overwriting an expected message (that is to repair a validation failure) that uses validation rules. For more information, see Overwriting messages that use validation rules.
Always apply changes without prompting If you select this option, changes that are made to the expected message in the Message Differences window are applied without prompting when the window is closed. If disabled, the user is prompted to save and apply changes, discard any changes, or cancel the action and return to the window.
Always keep repairs While the Message Differences window is open, you can edit the message in the Test Factory perspective. If you do, a message about unsaved changes is displayed when you close the Message Differences window. You can avoid this message by selecting the Always keep repairs preference.

Test Editor

Test Editor preferences control the display color for missing business view descriptions, the rendering of comments within a test, and the behavior of the test or stub action editor (inline or pop up).

Table 9. Test editor preferences
Preference Description
Missing business descriptions color Controls the color to use for a test name or test step that is not customized in the Business View. To modify the default color, click the existing color and select a new one in the Select color dialog.
Render comments as HTML 2.0 Controls whether the text within new comment actions are rendered as HTML, by default. You can override this feature on a per-comment basis when such actions are created.
Restart resources automatically If you select this option and you edit a stub that is currently running, the stub is restarted automatically when you save your changes.
Action Editor Settings The following settings are available:
Action Editor
Enables and sets the position of the inline Action Editor for editing the selected action in a test or stub, below or to the right of the editing panel. If set to Popup, test and stub actions can be edited by double-clicking them.
Apply changes automatically
When enabled, changes made in the Action Editor are applied automatically. If disabled, changes must be applied or discarded when you click away from the item that is open in the Action Editor.
Subscriber Settings The following settings are available:
Default Timeout
The default timeout (in milliseconds) to use for Receive Reply and Subscribe actions.
Default Tolerance
The default timeout tolerance (in milliseconds) to use for Receive Reply and Subscribe actions.


Virtualization preferences control the pass-through options for the available transport types.

Table 10. Virtualization preferences
Preference Description
Transports The following setting is available:
Default WebSphere MQ Stubbing mode
The default mode for routing messages. For more information, see Stubbing settings for MQ transport.
Pass Through Double-click a row in the table to display the Pass Through action to be taken for the associated transport type. For more information about these actions, see Configuring transports to use the sift-and-pass-through capability.
Discard any message that the stub cannot process and do not send any reply.
Pass Through
You can specify a Delay for the data that is passed through to the stub.
Simulate Error
Pass through a simulated error with the following characteristics:
Enter the number of milliseconds the simulated error should be delayed.
Status Code
Select the status code for the error message (200-505).
Status Text
Enter free-form text for the error message.

Not all options are available for all transports.


You can specify custom application associations for various file extensions. Click Add to enter a new association and provide the following information:

Table 11. File association fields
Field Description
File Extension Enter the file extension characters (such as XML) that you want to associate with an application.
Program List Select this option if you want to choose the associated program from the displayed list. Highlight the program in the list.
Launch Command Select this option if the program you want is not displayed. You must provide a full path to the executable program in the Command field.

Options are available to Delete a highlighted association or to Edit the fields in the table for a highlighted association.


If you use the United Nations Electronic Data Interchange For Administration, Commerce, and Transport (EDIFACT), you have the following preference available:

Table 12. EDIFACT preferences
Preference Description
Schema Processing The following setting is available:
Make UNG/UNE segments mandatory
If you select this option, the Functional Group Header (UNG) and Footer (UNE) are required when processing schemas.


SOAP preferences control the default options in the Field Properties dialog for SOAP messages.

Table 13. SOAP preferences
Preference Description
SOAP Version Select the default SOAP version (1.1 or 1.2) to apply in the Field Properties dialog.
SOAP Headers Controls whether SOAP headers are enabled by default in the Field Properties dialog.

Byte Arrays

If you use byte arrays, you can set the following preferences:

Table 14. Byte array preferences
Preference Description
Encoding The following character encoding systems are available:
  • UTF-8
  • UTF-16
New Line You can set the newline character to any of the following options:
  • Native
  • Unix-like (LF)
  • Windows (CR + LF)
  • Mac (CR)


Copybook preferences control the default behavior for handling Copybook schema files.

Table 15. Copybook preferences
Preference Description
Schema Processing Specify the Start Column and End Column values for each line of the schema.
File Serialization The following Encoding values are available:
  • CP037
  • CP285
  • ISO-8859-1
Processing Properties The following settings are available:
Truncate content when buffer overflows
Select this option to ensure that the contents of the copybook do not exceed the size of the buffer.
Text Padding
Enter a character to be used to fill out the lines in the schema.


The following preference is available for controlling file access:

Table 16. File preferences
Preference Description
Default Retry Interval The number of milliseconds that HCL OneTest API should wait before retrying file access.

WS-* Extensions

Preferences are available for web services addressing and web services security.

Table 17. Web services extension preferences
Preference Description
WS Addressing If you select the Enable by default option, the WS-Addressing transport-neutral mechanisms are enabled by default in the Field Properties editor for SOAP messages.
WS Security If you select the Enable by default option, the WS-Security communications protocol is enabled by default in the Field Properties editor for SOAP messages.

If you enable WS-Security, you can select the Enable milisecond precision for timestamps option to increase the granularity of the timestamp tokens within WS-Security.


These preferences control the default options that are used when you process XML.

Table 18. SOAP preferences
Preference Description
File Serialization The following setting is available:
The default encoding type for serializing XML, either UTF-8 or UTF-16.
Processing Properties The following settings are available:
The default formatting for XML, either Single-line or Multi-line indented.
The default encoding to use when you are processing XML, either UTF-8, UTF-16, or ISO-8859-1.
Normalize the document
Enables or disables the default normalization of empty text nodes to a single space character.
Send NULL values
Enables or disables the sending of XML elements whose text contains only a Tag, the value of which is NULL (not empty string ""). If Send NULL values is not selected, this element is not sent.
Include XML Declaration
Enables or disables the inclusion of the XML declaration by default.
Treat CDATA as Text
Enables or disables the treatment of CDATA fields as text by default.
Preserve Whitespace
Enables or disables the preservation of white space in XML.
XML Name Matcing The following settings are available:
Qualified Name
Enables the use of namespace prefixes during message comparison.
Local Name
Enables local name matching, ignoring namespace prefixes, during message comparison.
Message Editing Preview The following settings are available:
Sets the default number of levels to be expanded in XML previews.
Sets the default message field length to display in XML previews.