This topic explains how to extend the SOAtest and Virtualize interfaces and operations to cover message formats not supported by default.

Sections include:

About Custom Message Formats

SOAtest and Virtualize include a framework that allows you to extend their built-in message formats. The framework can support any message format that you are working with—for example, mainframe message formats, binary formats, or any other kind of proprietary custom message format. The message formats are defined by creating a conversion between the native format and XML. This conversion allows the user to construct and validate messages using the rich XML tooling that is available. This extension is done using Java.

Once a custom message format has been added,SOAtest and Virtualize will automatically make a newclient or responder available for for configuring and sending request or response messages using that format. You can add instances of the new client/responder to your test scenarios or responder suites.

SeeCustom Client and Custom Message Responder for details about how to use them. The new message format will also appear in the XML Converter tool, which is described in XML Converter.

In addition to defining a general conversion between formats, you can also optionally define a set of specific message types that define the exact structure of each message within that format. For example, a user might define a general FIX to XML conversion, but then also define a set of specific FIX messages that are used by their application. The structure of each message type is defined with an XML schema and is provided by the SOAtest or Virtualize extension.

Interfaces to Implement for Custom Message Formats

After setting up your environment (see General Procedure of Adding an Extension for instructions in Virtualize or General Procedure of Adding an Extension for SOAtest), implement the following interfaces (described in the Extensibility API documentation):

ICustomXMLConverter Implementation

This is a required class that is used to implement the conversion logic to and from the native format and XML. The toXML() method should return your message in XML format, while the toNative() method should return your message in its native format. The methods take:

toXML() returns an INativeMessage while toNative() returns an IXMLMessage. There are default implementations of these interfaces when can be used for convenience (DefaultNativeMessage and DefaultXMLMessage).

For toNative, implementors must handle the case where the message type for the xmlMessage parameter is {@code null}. If the particular conversion being defined does not know how to convert from XML to the native message without being passed the specific message type, then a {@link CustomConversionException} should be thrown.

For toXML, the conversion may optionally be written so that it can auto-detect the message type for the passed-in nativeMessage. This auto-detection is used to determine the message type when switching from literal to form views or when using the traffic wizards to generate assets. If the conversion does not support auto-detection, you will need to explicitly choose the message type, or else SOAtest/Virtualize will try to detect the message type (which in some cases may be incorrect). To support auto-detection, implementors should ignore the message type for the passed-in nativeMessage. They should instead determine the message type themselves and set it into the returned XML message. 

Implementors must handle the case where the message type for the nativeMessage parameter is {@code null}, because that is how support for auto-detection is determined. If the particular conversion being defined does not support auto-detection and thus does not know how to do the conversion without being passed the message type, then a {@link CustomConversionException} should be thrown.

Errors that are encountered during conversion can be handled in two different ways. If the error is a fatal error that must abort the conversion, a CustomConversionException with an appropriate error message should be thrown. If the error is non-fatal (meaning the conversion can continue), a message can be reported using message) and a (possibly partial) converted message should still be returned by the method. If an error is reported by throwing an exception or calling report(), it will be reported either as a dialog in the client/responder UI, or as an error message when the client/responder is run.

These conversions are executed from clients/responders and the XML Converter tool in the following situations: 

ISchemaGenerator Implementation

When defining specific message types for a given message format, you must provide an XML schema for each message type. This is an optional class that provides one method of providing an XML schema for a given specific message type. If you don’t implement this class and reference it in parasoft-extension.xml, you must instead provide references to schema files (see Defining parasoft-extension.xml for a Custom Message Format below).

This interface has one method, generateSchema(), which takes:

generateSchema() returns a URI that is a reference to a schema file. It can be a reference to a dynamically generated schema, a reference to a schema that lives in the jar file providing the custom message format extension, or a reference to an external resource. An empty URI can be returned if there is an error in generating the schema; this will result in the Form Input view not being populated appropriately for the given message type. 

Defining parasoft-extension.xml for a Custom Message Format

After you have implemented the necessary classes, define parasoft-extension.xml (introduced inGeneral Procedure of Adding an Extension in SOAtest and General Procedure of Adding an Extension in Virtualize) using the following schema:

<?xml version="1.0" encoding="UTF-8"?>
<extension xmlns="urn:ocm/parasoft/extensibility-framework/extension"
		name='the name of your message format, appears in menus' description='A more detailed description'>
    <class>com.myCompany.MyConverter</class> <!-- implements ICustomXMLConverter -->
    <messageFormat xmlns="">
		<messageTypes generatorClass="com.myCompany.SchemaGenerator">
		<messageType id='unique ID' name='name' xsd='path to schema in jar'/>
			. . .
		<client icon="myClient.gif" defaultTransport='default transport' /> 
		<responder icon="myResponder.gif" /> 
    <version id='your version ID' updaterClass="com.myCompany.myUpdater"/>    
	<form xmlns="urn:com/parasoft/extensibility-framework/gui">
		<section label="field group 1">
			<field id="key 1" label="field 1"/>
			<field id="key 2" label="field 2"/>
		<section label="field group 2">
			<field id="key 3" label="field 3"/>
			. . . 
		. . .

The field ids under the section elements are used to retrieve values from the ICustomXMLConverterConfiguration instance that is passed in to the various API methods, and that allows for the values provided by the user to be passed in to your implementation. They are also used to persist the userprovided values to the responder deployment descriptor file when it is saved. The field labels appear in the GUI that is constructed based on this XML. The section layout does not have a programmatic impact; it merely helps organize the various GUI fields into sections or categories for easy access and usability by the end user. 

The fully qualified class name of the class that implements ICustomXMLConverter, along with the name of the extension, is used to identify the message format that is being used in clients/responders. Changing the qualified class name or the name of the extension after you have saved .tst or .pva files will prevent saved clients or responders from being able to resolve the message format that they are using. 

<MessageFormat> Element

This element is unique to this extension type. It must be valid and correct for your custom message format to be imported.

Verifying the New Message Format

  1. Build the project (seesee General Procedure of Adding an Extension in Virtualize or General Procedure of Adding an Extension in SOAtest) and restartSOAtest or Virtualize.Virtualize.

  2. Verify that a new client/responder that contains the name of your message format is available to add to a .tst or .pva file by choosing Add New> Test or Responder.

Your new format should also be listed in the drop-down menu in the XML Converter.



Assume that you have the custom message format SimpleMessage, which consists of key and values pairs with a space delimiter (for example: key1=value1 key2=value2 key3=value3 key4=value4).

Once this custom format is added to SOAtest, SOAtest will be able to convert between SimpleMessage and XML. For example, it can convert 

key1=value1 key2=value2 key3=value3 key4=value4


<?xml version="1.0" encoding="UTF-8"?> 
<message xmlns="">

There are two messages types defined for this project. 

There are two ways to add this sample custom format to SOAtest: from the Java source project you can download from Parasoft’s Marketplace, or from a jar file that you can create from this project.

Adding the Format from the Java Source Project

To add the sample format from a Java source project:

  1. Download the file from and extract it.
  2. Import the extracted files into your workspace as a Java project.

  3. In the SOAtest perspective, choose Parasoft> Preference, select System Properties, click Add Java Project, indicate the location of the sample Java project, then click Apply.

  4. Restart SOAtest

Creating a Jar File

The Java source project is provided so you can review the sample source code. Jar files are typically easier ways to share custom formats across a team. 

To convert this sample Java project to a jar file:

  1. In the Java perspective, right click the Java project, then choose Export.
  2. Choose Java> JAR file, then click Next.

  3. Indicate where you want the jar file created, then click Finish.


Adding the Format from the Jar File

Other team members can now add the custom format from a jar file (rather than from the Java project—you do not need to complete these steps if you have already added the format from the Java project as described above):

  1. In the SOAtest perspective, choose Parasoft> Preference, select System Properties, click Add JARs, indicate the location of the sample jar file, then click Apply.

  2. Restart SOAtest

Using the Custom Format in SOAtest Tools

Once the example is added to SOAtest, you can create SimpleMessage Client tools as well as use the format in the XML Convertor tool. 

For SimpleMessage clients, you can use one of the message types or enter your own key value pairs in literal mode.