The Field Editor

Use the Field Editor to specify that a message field (data attribute) be populated by using or fulfilling certain criteria. Open the editor by double-clicking a field or element name within a message or a stub, by or right-clicking the field and selecting Contents > Edit.

Remember: The performance of the Field Editor is degraded if a single line of XML is larger than 50,000 bytes. Performance is not an issue if the XML is on multiple lines.

The standard field editor consists of a window with three action groups that are provided under their own tabs: Value, Validate, and Store (for outgoing messages) or Filter, Validate, and Store (for incoming messages).

Tip: Within each tab of the Field Editor, select the Ignore rule cache option to ignore a specific action type within a rule that is set on the field.
Tip:
Select the Field is optional to change the way in which a field is processed:
  • In the Subscriber view: When the option is enabled, no validation error will be generated in case the field is missing in the message.
  • In the Publisher view: If the value of the field is calculated as null at run time, either because it has a tag that resolves to null or it has a null field action, then the entire field is removed from the published message.

The Value tab

Use the Value tab to specify a value for the field.

Under the Formatting tab, various types of formatting can be applied to field values at run time. For more information, see Formatting field values.

For more information, see Setting a field value.

The Filter tab

By using the Filter tab, you can restrict which messages a subscriber processes based on the content of the selected field.

For more information, see Filtering fields.

The Validate tab

By using the Validate tab, you can define how to compare or verify the contents of a field that requires validation (for example, in the context of subscription).

For more information, see Validating scalar fields and Validating message fields.

The Store tab

By using the Store tab, you can store the contents of the field in a tag (for example, when you are receiving a message, or to record the value of a dynamic field in a published message).

If the "Append to list of values" option is enabled, the tag is updated as a list of values (for example, {val1, val2, val3}) when new values are stored.

For more information, see Storing field data in tags.

Action types

This following provides a list of available action types.

There is only one way at a time to populate a value, but there are many different ways to validate or store a value. Therefore, the Validate and Store tabs can accommodate one or more action types.

The availability of action types depends on the transport, formatter, and field type that you select:

Table 1. Field Editor action types
Action type Tab Field type Description
Does Exist Filter Scalar, Message-based Accept or ignore incoming messages depending on whether the selected field exists in each message.
Is Null Filter, Validate Scalar, Message-based Verify whether the selected field is null.
Not Null Filter, Validate Scalar, Message-based Verify whether the selected field contains a value.
Name Filter Scalar, Message-based Accept or ignore incoming messages depending on the name of the selected field in each message.
Type Filter Scalar, Message-based Accept or ignore incoming messages depending on the type of the selected field in each message.
Assert using Function Filter, Validate Scalar, Message-based Use a HCL OneTest API function (that returns a Boolean type) to filter/validate the selected field.
Value Value Scalar Validate the contents of the selected field of each outgoing message against a specific manually entered value.
File Value Scalar Populate the contents of the selected field with the contents of a selected file.

You must also select the file.

Function Value Scalar Execute a HCL OneTest API function (including custom functions).

The result of the function is used as the field value.

Decrement Value Scalar Decrease the selected fields value by a specified amount each time that the outgoing message is sent.

This involves setting an initial value and a step value.

Increment Value Scalar Increase the selected fields value by a specified amount each time that the outgoing message is sent.

This involves setting an initial value and a step value.

List Value Scalar HCL OneTest API treats each entry in the specified input as a separate value.

Values can be separated using any available delimiters (new line, comma, tab, or full stop).

The first time that the selected outgoing message is sent, the selected field will be set to the first value.

For each subsequent iteration, the next value in the sequence will be used.

If a message is published more times than the number of available values, the cycle will restart from the first value.

You can also reset the action and restart from the first value.

Null Value Scalar, Message-based Clear the contents of the selected field.
Process Children Value Message-based Process all the children of the selected field.
Process Tag Value Message-based Replace the contents of the selected field with the contents of a tag, then process the new contents. The tag must contain the contents of another message-based field.
Equality Validate, Filter Scalar Verify whether each outgoing message contains a value in the selected field that matches the specified value.
Length Validate, Filter Scalar Verify whether each outgoing message contains a value in the selected field that falls within the specified maximum and minimum values.
Regex Validate, Filter Scalar Use the specified regular expression to validate the contents of the selected field of each outgoing message.
XPath Validate, Filter Scalar Use the specified XPath expression to validate the contents of the selected field of each outgoing message.
Schema Validate, Filter Scalar Use the specified schema to validate the contents of the selected field of each outgoing message.
Note: If you are using HCL OneTest API 8.6.0 or later, you can validate any messaging action against a specific WSDL document in your project.
XSD Type Validate, Filter Scalar Verify whether the field is of the correct type as specified by the XSD used to build the message.
Name Validate Message-based Present by default, but the associated checkbox can be cleared.
Type Validate Message-based Present by default, but the associated checkbox can be cleared.
Validate Element Children Validate Message-based Validate the children of the selected field. Only available in XML messages.
Validate Message Children Validate Message-based Validate the children of the selected field.
Validate Using Tag Validate Message-based Validate a received value against a message or sub-message that has been previously tagged.
Validate Using Message from File Validate Message-based Validate the selected field against a predefined message created in the Requirements View.
Copy (Value) Store Scalar, Message-based Store the value of the field into a tag.
Regular Expression Store Scalar, Message-based Store the result of comparing a regular expression to the value of the selected field.

Use the Match option to store a boolean indicating if the regular expression matched any part of the value.

Use the Extract Instance option to extract the part of the value that matches the regular expression. The instance number given is used to select the occurrence if there are multiple matches.

XPath Query Store Scalar, Message-based Store the result of performing an XPath query on the XML in the selected field.

Use the Match option to store a boolean indicating whether the XPath expression matched any part of the value.

Use the Extract Instance option to extract the part of the value that matches the XPath expression. The instance number given is used to select the occurrence if there are multiple matches.

Available field types

The following list shows the field types that are available in HCL OneTest API. When you are using some schema-based formatters, the range of types changes according to the types supported by the formatter.

Table 2. The basic field types
Field type Contents
Boolean True or False
Byte 0-255
Date-Time example: 12/22/2005 5:15pm
Double 8-byte floating point
Float 4-byte floating point
Integer 4-byte integer
IP address valid IP address in the form nnn.nnn.nnn.nnn
IPPort 0-65535
Long 8-byte integer
Opaque Array of bytes
Message Collection of fields
Short 2-byte integer
String Arbitrary length string (Default)
XML XML content

Common menu

This following describes the common menu.

You can right-click in any of the editable text fields in the Field Editor to display the following menu:

Open Field Value: Replaces the contents of the editor with the contents of a user-selected file.

Save Field Value: Saves the contents of the text editor to a file.

Word Wrap Field Value: If enabled, the editor "wraps" words to the next line instead of scrolling horizontally.

Format XML: Format and indent the contents of the text editor if it contains XML. The formatting rules are defined in application preferences.

Flatten XML: Flattens the contents of the editor into a single string if it contains XML.

Search: Opens a dialog that you can use to search for (and optionally replace) a specific string in the editor

Copy/Cut/Paste: Copies, cuts, or pastes the selected contents of the editor to/from the clipboard.

Launch As: Launches the contents of the editor as a file of the specified type.

Edit As: Edits the contents of the text editor as a file of the specified type, opening the editor that is specified by the system file associations.

Note: The contents of the Launch As and Edit As submenus can be redefined by changing options in HCL OneTest API Preferences. For more information, see Changing preferences.

Insert Tag: Adds a tag at the current cursor position. You can create a tag with the New option, or select from a list of existing tags (split into Environment, Test Scope, or System menus).

Tag Data Store: Provides access to the tags that are available in the current test.