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.
Add a Protocol Hook Script to your virtual service
You can define a single Protocol Hook per virtual service.
-
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:
-
CSV messages over file system
-
REST
-
SOAP over HTTP/HTTPS
-
SOAP over Generic JMS
-
XML over HTTP
-
XML over Generic JMS
-
Binary messages over HTTP
-
-
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.
-
Click Enable to enable the protocol (it is disabled by default).
-
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: https://github.com/MicroFocus/sv-protocolhook-examples
-
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.
|
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. |
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:
http://hp.com/SOAQ/ServiceVirtualization/2010/HTTP |
use the HttpProtocolMetadata.Namespace constant |
http://hp.com/SOAQ/ServiceVirtualization/2010/JMS | use the JmsProtocolMetadata.Namespace constant |
http://hp.com/SOAQ/ServiceVirtualization/2010/ | use the CommonProtocolMetadata.Namespace constant |
http://hp.com/SOAQ/ServiceVirtualization/2010/FS | 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.
Example:
[MessageMetadataAccess(HttpProtocolMetadata.AuthorizationHeaderKey,HttpProtocolMetadata.Namespace)]
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.
Example:
[DefaultMessageMetadataProtocol(HttpProtocolMetadata.Namespace)]
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
In SV 2022 R2 and later, 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)
.SetMessagePayload(payloadByteArray);
See also: