Protocol Hook script

A Protocol Hook allows changing the raw message payload and metadata before it enters and after it leaves Service Virtualization processing.

Hook script overview

Using a Protocol Hook, you can change the raw message payload and metadata ahead of the Service Virtualization processing. You can also modify the raw message and metadata after SV processing, before the message leaves Service Virtualization.

You can execute a Protocol Hook in Simulation, Stand-By, and Learning modes. The Protocol Hook exists on the service level.

Back to top

Add a Protocol Hook Script to your virtual service

You can define a single Protocol Hook per virtual service.

  1. In the Virtual Service Editor, under Service Description, click Edit. The Protocol Hook section is displayed in the Service Description Editor.

    Note: The Protocol Hook section is available for the following protocols:

    • Binary messages over file system, Generic JMS, HTTP, IBM MQ

    • CSV messages over file system

    • FIX over IBM MQ

    • Fixed length messages over file system, IBM MQ, TCP

    • JSON over Generic JMS

    • REST

    • SOAP over Generic JMS, HTTP/HTTPS, IBM MQ

    • Text-delimited messages over file system

    • XML over file system, Generic JMS, HTTP, IBM MQ

  2. Click Add. The Protocol Hook script file content is displayed.

    The default script contains the ProcessingHook class with methods that you can use to modify the raw message payload as well as message metadata. It also contains an example.

  3. Click Enable to enable the protocol (it is disabled by default).

  4. Edit the script as required.

    • Click Edit to edit the script directly in the SV Designer.

    • Click Edit in Visual Studio project to edit in Visual Studio.

    For examples of protocol hook scripts, see the Github repository:

Back to top

ProcessingHook class

In the ProcessingHook class you can override up to three methods inherited from the base ProcessingHookBase class. You can override these methods by specifying code to modify the message payload and metadata.

Examples of use

Make payload or metadata structure easier to work with

You might want to amend the payload or metadata so that the structure inside the data model is easier to work with. In such cases, you need to modify the data both before it enters SV processing, and after SV processing is finished (to undo your changes) so that the adjusted data only appears inside SV processing.

  • If you have a message type that Service Virtualization cannot parse, you can write your own parser to convert the message type into XML or another known format, to make such messages supported in Service Virtualization. This enables you to add new protocols to Service Virtualization. You need to convert the message to XML before it enters SV processing and convert it back to the original format after SV processing is finished. This needs to be done for requests and responses in Simulation, as well as the Learning and Stand-By mode, since both the real service and the clients of your virtual service need to work with messages in their original format.

    • You can share support for new message types with other team members by exporting your virtual service as a template.

    • You can write the parser as an external DLL and use it from within the Processing Hook script in the same way you use external references from the data model scripting. For details, see Use a third-party library in a C# rule.

  • If you have an XML request that contains an array of keys and values which is difficult to use in data model request matching. You might want to convert that part of the message to a more convenient format. For instance, a sequence of named XML elements:

    <item key=”a”>value of a</item> → <a>value of a</a>

Make security token acceptable You might need to modify a security token to make it acceptable to the real service (or achieve similar things). Often the client IP is a part of token data. In Stand-By or Learning mode, the token needs to be based on the SV Server IP address, since the SV Server will be sending requests to the real service, not the original client. In this case, you can adjust the token using a Protocol Hook script.
Fix malformed messages You have a malformed message which you want to make processable in Service Virtualization. In such cases, you can use a Protocol Hook script to fix the message.

Methods to override

Preprocess method

Override this method to change the message payload or metadata before the message enters SV processing.

PostprocessMetadata method

Override this method to change the message metadata after SV processing has finished.

PostprocessPayload method

Override this method to change the message payload after SV processing has finished.

Metadata Retrieval

You can access a subset of message metadata from a Protocol Hook script. You can read metadata values, and in certain cases, you can change their values. Every piece of metadata is uniquely identified by its name and the protocol namespace. You can use the following namespaces:

use the HttpProtocolMetadata.Namespace constant use the JmsProtocolMetadata.Namespace constant use the CommonProtocolMetadata.Namespace constant use the FileProtocolMetadata.Namespace constant

For performance reasons, you need to specify the metadata values you intend to work with on the method level using the MessageMetadataAccess attribute. Having specified them, you can read the message metadata value inside the method.


public override PostprocessMetadataResult PostprocessMetadata(PostprocessMetadataContext context)
var authorizationHeader = context.GetMessageMetadataValue<string>(HttpProtocolMetadata.AuthorizationHeaderKey);
return new PostprocessMetadataResult()
.SetMessageMetadataValue(HttpProtocolMetadata.AuthorizationHeaderKey, authorizationHeader);

If you define a default namespace on the class level, you don’t have to specify the namespace on the method level using the DefaultMessageMetadataProtocol attribute.


public class ProcessingHook : ProcessingHookBase

The following classes contain constants with names of standard metadata:

  • HttpProtocolMetadata: HTTP protocol-related metadata

  • JmsProtocolMetadata: JMS protocol-related metadata

  • CommonProtocolMetadata: Metadata common to all protocols

  • FileProtocolMetadata: File system and FTP related metadata

You can work with any metadata even if it is not defined in the above classes, provided it has a proper metadata name in the MessageMetadataAccess attribute. While the standard built-in metadata access is often restricted to prevent unwanted effects (see the Service Virtualization API reference), for custom metadata you can freely add, delete, and update their values.

Note: While metadata columns are treated in a case-sensitive manner at the Data Model level, certain types of metadata (such as HTTP headers) can be accessed in a case-insensitive manner inside the Protocol Hook.

Context Object

The Processing Hook methods Preprocess, PostprocessMetadata, and PostprocessPayload all have a single argument called context. This object has the following methods and properties:

Method/Property Description
GetMessageMetadataValue<type>(name) method Retrieves the value of metadata by its name, converted to a type of your choice. To make a piece of metadata available for retrieval, you need to use the MessageMetadataAccess attribute as explained in Metadata Retrieval.
IsMessageMetadataPresent(name) method Returns true if a metadata of the specified name is available.
GetMessagePayload() method

Retrieves the byte array with message payload. This is only available for the Preprocess and PostprocessPayload methods.

IsRequest property

Is true if the processed message is a request, and false for responses.

Logger property

Use this object to log messages into the text log file. For details, see Configure logging for scripted rules.

MessageLogger property

Use this object to log messages into the Problem List. For details, see Configure logging for scripted rules.

Changing payload and metadata values

To change the payload and metadata, you need to call respective methods on the result object in the Processing Hook methods. This is how you create and return a result for the methods without requesting any change in an SV message:

Method Use
Preprocess return new PreprocessResult();
PostprocessMetadata return new PostprocessMetadataResult();
PostprocessPayload return new PostprocessPayloadResult();

If you want to change message payload or message metadata (which you previously made available for retrieval by the method level annotation), you need to use the following methods:

To Use
Change message payload .SetMessagePayload(payload)
Change message metadata .SetMessageMetadataValue(metadataName, metadataValue);
Delete message metadata .DeleteMessageMetadataValue(metadataName);

Example: Changing metadata and payload in the PostprocessMetadata method

return new PostprocessMetadataResult()
.SetMessageMetadataValue(HttpProtocolMetadata.AuthorizationHeaderKey, authorizationHeaderValue)

Back to top

Shortest possible example of a Protocol Hook script

For REST services, clients sometimes send custom headers with a different name casing.

In the following example, three different Data Model columns (with case-sensitive names) would be created during recording:

Copy code
X-ProblematicHeader, x-problematicheader, x-ProblematicHeader. 

This script reads the value of X-ProblematicHeader, removes the header, and creates it again with the single proper name.

Since metadata in REST are accessed in a case-insensitive manner, the get method reads any header variant, the delete method deletes it, and the set method creates it again under the single proper name of X-ProblematicHeader.

Note: You need to annotate the method declaration with the metadata to use inside the method; for REST it is case-insensitive.

Copy code
Example: Shortest possible Protocol Hook script
using HP.SV.DotNetRuleApi.Hook.Processing;
using HP.SV.DotNetRuleApi.Hook.Processing.Attributes;
using HP.SV.DotNetRuleApi.Hook.Processing.ProtocolMetadata;
namespace HP.SV
   public class ProcessingHook : ProcessingHookBase
      public override PreprocessResult Preprocess(PreprocessContext context)
        string headerValue = context.GetMessageMetadataValue<string>("X-ProblematicHeader");
        return new PreprocessResult()
            .SetMessageMetadataValue("X-ProblematicHeader", headerValue);

Back to top

See also: