DevTest - Copybook Basics

Products

• CA Application Test
• CA Continuous Application Insight (PathFinder)
• Service Virtualization

Issue/Introduction

This document provides general instructions for applying a Copybook to recorded transactions.

Environment

All supported DevTest versions and environments.

Cause

N/A

Resolution

How to Use the Copybook Data Protocol

You can use the Copybook data protocol with any of the transport protocols that VSE supports. Commonly, the Copybook data protocol handler is used with a messaging protocol such as JMS or MQ or with the CICS transport protocol. A sample copybook application that uses HTTP is available in the demo server.

Note: The Copybook Bundle page in the DevTest Portal makes it easier to create, import, and manage your copybooks and mapping files. For more information, refer to section "Create Copybook Bundles" in the documentation of the DevTest release you are running.

Selection

Keep the following in mind when selecting the Copybook data protocol:

• Consider using the data protocol handler on both the Request and Response sides. Although you can use the data protocol on only one side, it is not common. This documentation does not cover the single-sided usage in detail.
• The Copybook data protocol changes the Request (or Response) body into XML. The Copybook data protocol does not automatically add arguments to the Request for every field. To do useful things with the Copybook data protocol, you also must include another data protocol handler on the Request side. Most commonly, the Generic XML Payload Parser is the second data protocol handler. However, any data protocol handler that does useful things with XML payloads is acceptable.

Configuration

When you have captured your traffic (or imported from Request/Response pairs, PCAP, or raw traffic files), the Copybook DPH configuration window opens.

Enter the following parameters:

• Copybook file definition folder
  Designates the folder in your project where you store your copybook file definitions. This folder becomes the base path for relative paths in the Payload Mapping File.
• Payload to file definition map path
  Specifies the XML document that serves as the Payload Mapping File for this virtual service.
• Encoding
  Specifies a valid Java Charset  If provided, this value is used to try to convert the bytes in the payload into text for use in the output XML.
  Default: UTF-8
  To configure the default charset, set lisa.vse.default.charset in local.properties.
• Copybook cache TTL
  VSE must reference a specific copybook at run time and potentially convert it to XML. The Copybook cache TTL parameter defines how long a cached version of the converted copybook can be kept in memory. When the specified interval expires, the converted copybook is removed from the cache. If the file is needed again, it is read again and reconverted.
  Values:
  
  • To define the timeout, set Copybook cache TTL to a positive number (in seconds).
  • To disable caching, set Copybook cache TTL to 0 or a negative number. VSE reads and parses the files each time that they are needed.
• Copybook parser column start
  Copybooks frequently start each line with a line number. This parameter defines the column on which the parser starts when trying to parse a copybook file definition.
  Value: A zero-based inclusive index. However, you can think of it as a "normal" one-based exclusive index.
  Default: 6
  Example: If you set this value to 6, the parser skips the first six characters in a line and starts with the seventh character.
• Copybook parser column end
  Occasionally, copybooks contain other reference data at the end of each line. When that happens, the parser must know on which column to stop. If there is no "extra" data at the end of the lines in the file, you can set this number to something greater than the length of the longest line in the file. If this number is greater than the length of a line, the parser stops at the end of the line.
  Value: A zero-based exclusive index. However, you can think of it as a "normal" one-based inclusive index.
  Example: If you set this value to 72, the parser reads the 72nd character in the line and then it stops (without trying to read the 73rd).
• Validate field lengths
  Specifies whether to enforce the values set in the Copybook parser column start and Copybook parser column end values. This option is only used in VSE, on the Response side. During recording, the payload is converted to XML and then back to bytes to ensure that it can convert symmetrically. Also, during playback the XML responses are converted back to records/payloads before responding to the caller. In both of those operations, VSE can validate that the value in each field is exactly the length that is specified in the copybook. However, it is not always desirable to have this validation.
  Values:
  
  • Selected: The records in your data align exactly with the length defined in your copybook.
  • Cleared: The records in your data do not align exactly with the length defined in your copybook.
  
  Example: if your record does not contain any data for some fields, they are seen as 0 length, whereas the copybook defines that field for a length greater than 0. If you select this option in that case, VSE fails the validation and reports it as an error.
• XML elements as request arguments
  Specifies whether to verify that the requests and responses are XML strings.
  Values:
  
  • Selected: Identifies variables from the XML messages that the recorder uses. This verifies that the requests and responses are XML strings.
  • Cleared: Does not verify that the requests and responses are XML strings.
  
  Verifies that the requests and responses are XML strings. Selecting this option lets you identify variables out of the XML messages that the recorder uses. For more detailed information about identifying variables, refer to section "Generic XML Payload Parser Data Protocol" in the documentation of the DevTest release you are running.

The same editor is also available on the data protocol filters in the VSM (one on the Request side and one on the Response side). This editor lets you change the configuration after recording, as necessary.

Additional Information

Most issues arise from an invalid or incomplete copybook or mapping file.