This topic provides an overview of how to create parameterized message responders from traffic that are captured in traffic logs. Sections include:
Prerequisites
- Your team must have a Data Repository Server installed and running. For details, see Installing a Remote Data Repository Server
- Message contents must be well-formed. SOAP Message Responders must have only one top-level XML element.
- The Data Repository does not support parameterization of JSON arrays with mixed types. If a JSON array does have mixed types, Virtualize will assume that all elements in the array are the same type as the first element.
Monitoring the Console View
It’s helpful to keep the Console view visible as you are creating tests and/or message responders from traffic. This view will display any warnings, errors, and informational messages that are generated while processing the traffic file.
Using the Wizard
Choose the Traffic > Generate Parameterized Messages option in one of the available creation wizards. See Adding Projects, Virtual Assets, and Responder Suites for basic information about adding responders.
- Specify the following information in the Traffic wizard:
- Specify the location of the traffic file. This is optional if a Definition file has been entered.
- Change the character encoding if needed.
- (Optional) Specify the service definition file. Providing a service definition helps Virtualize create better message groupings and data source correlations.
If you want to populate the wizard with a previous group of settings saved in a template, enter the location of that template. See Using Configuration Templates to Reuse and Share Wizard Settings for details about creating and using templates in Virtualize.
- Click Next and choose one of the following modes from the Connection Mode dropdown and configure the connection details accordingly:
- Host/Port:
- Enter the Data Repository Server's host and port. You can also choose the embedded server or an existing remote server from the drop-down menu.
- If you select the embedded server, the Port, Username, and Password fields will be grayed out. If you select a remote server, the Port, Username, and Password fields will be automatically populated, but these can be adjusted if necessary.
- Select or enter the name of the repository you want to use in Repository name. If you enter the name of a new repository, that repository will be created.
- Specify your credentials to access the data repository server (if required).
- To use SSL to connect to the server, enable Use SSL.
- Enter the Data Repository Server's host and port. You can also choose the embedded server or an existing remote server from the drop-down menu.
Connection String: Enter the MongoDB connection string. An example of a connection string that connects to a local server with SSL is shown below. See https://www.mongodb.com/docs/manual/reference/connection-string/ for more information about MongoDB connection strings.
MongoDB Connection String Examplemongodb://localhost:2424/?tls=true&tlsAllowInvalidHostnames=true
If an authentication database is specified in the connection string, you should use the
/defaultauthdb
component; only use the?authsource=defaultauthdb
option if credentials are specified in the connection string.
- Host/Port:
Click Validate to verify the connection settings.
Click Next and configure the settings in the Message Format and Grouping Strategy screen.
Verify that Request message format and Response message format are set to the correct format. Virtualize will attempt to identify the message format of the request and response based on the first message in the traffic file. All requests in a single traffic file are expected to have one format, and all responses in the same file are expected to have one format. The request format may be different than the response format. If the message format is not detected, Plain Text will be selected.
Conversion options are available for some formats, such as EDI or custom formats. Click the Conversion Options button and make the desired changes.
Choose a message grouping option. See Message Grouping Options for details.
- If you specified a service definition or template file, you can enable the Constrain option in the Message Group Creation Options section. If this option is enabled, only the message groups defined in either the template or service definition file will be grouped. All other messages will be ignored. If this option is disabled, Virtualize will group all messages that appear in the traffic file. If a service definition and template file are provided and this option is enabled, groupings will be constrained according to the template file prior to being constrained by the service definition. As a result, a message will be ignored if it is defined in the service definition but not in the template file. The Constrain option is enabled by default.
- If you specified a service definition or template file, you can enable the Empty groups option in the Message Group Creation Options section. When this option is enabled, groups will be created based on a service definition or template file even if the traffic file does not contain messages that match the group criteria. When this option is disabled, groups without messages will not be created. The Empty Groups option is set to false by default if a traffic file is specified alongside a service definition or traffic template. The Empty Groups option is set to true by default if no traffic file is specified.
- Click Next and review the information about the operations and messages in the Message Grouping Review screen. See Message Grouping Review Screen for details.
- Click Next. If the Autoconfig option for each group was enabled, the Data Reuse screen will open and you can skip the next step.
- If the Autoconfig option was disabled in the previous screen, you will need to manually configure the request matching options in the Request Matching screen. See Configuring Request Mapping Options.
- Configure how the imported traffic should be reused or how it should affect existing data in the Data Reuse screen. See Configuring Data Reuse Options for details.
- Click Next and specify any additional configurations in the Final Options screen:
- Enable the Form or Literal option in the Payload section to configure the wizard to create messages in Form or Literal mode. See Form Input or Literal for details.
You can enable the Export configuration data into a reusable template option and specify a file name and location to save the settings you used in this wizard as a template. See Using Configuration Templates to Reuse and Share Wizard Settings for details about creating and using templates.
- Click Finish.
Results
A Message Responder with parameterized elements as well as preconfigured responder correlation and data source correlation will be added. The tools will default to Form Input / Form JSON view unless the message is XML or the JSON is so large that performance is affected. Literal input mode will be used in these cases.
(For new data repositories) A new Data Repository with applicable data sets and record types will be added. One data set will be added per message group identified by analyzing the traffic.
(For existing data repositories) New data sets and record types will be added to the existing repository.
A repository data source will be added for each added data set and each test client or message responder will be configured to use the associated data source.
If the .pva was created in the Virtual Asset folder, the virtual asset will be automatically deployed to the local Virtualize server as the wizard completes. Otherwise, it can be manually deployed to local or remote servers.
For details on how to edit and extend the data stored in the data repository, see Viewing and Modifying the Repository Structure and Contents.
Note that custom transport headers and any SOAP Headers (e.g. WS-Security Headers) that are present in the traffic file are not configured automatically into the generated assets or data repository data sets. You can specify them in the generated Message Responders (see Message Responder Overview for details).
Message Grouping Options
You can use the following message grouping options in the Message Format and Grouping Strategy screen:
Based on operation/type: Group messages based on the operation or message type. This is useful for service traffic that contains messages that are distinctly identifiable either by operation or by the format's message type (i.e., the name of the element under the SOAP Body, the name of the root element in plain XML messages, or the message type of a specified message format). A responder is generated for each operation/type discovered within the traffic file. If you select this option, Virtualize will recommend grouping heuristics to apply, based on its analysis of the traffic file. You can change the pre-selected heuristics. To learn more about the heuristics, see Understanding Heuristics for Grouping by Operation - Type.
- Based on similar requests: Group messages based on request message structure. This tells Virtualize to analyze the request message structures and group the request/response into responders so that each responder will contain responses that correlate with requests that have a similar structure. Messages are considered "similar" when they have an identical DOM tree model, even if they have different values. This option is used to optimize and simplify the rules for correlating requests to responses within each Message Responder.
Based on similar responses: Group messages based on response message structure. This tells Virtualize to analyze the response message structures and group the request/response pairs into responders so that each responder will contain responses that have a similar structure. Messages are considered "similar" when they have an identical DOM tree model, even if they have different values.
None: No grouping. A responder is generated for each response message in the traffic file. Use this option if you want every request/response pair in separate Message Responders.
Message Grouping Review Screen
The columns in in the Message Grouping Review screen are based on the grouping strategy applied. Each table row represents the criteria for defining a group. One group will be generated for each table row. One responder will be generated for each group. Complete information for using this screen is in the Customizing Grouping Criteria section.
The correlation criteria will be processed in the order in which they appear in the table (from top to bottom). For details on how these groupings were created, see Understanding Heuristics for Grouping by Operation - Type.
You can use the controls to add, modify, reorder, and remove grouping criteria. If you change the criteria, be sure to click Regroup before proceeding.
The Autoconfig option enables Virtualize to automatically configure Message Responders for the specified groups. Disable the Autoconfig option to manually configure Message Responders for each message group (see Configuring Request Mapping Options).
Auto-configuration is typically available when there are multiple requests within a message group and there are differences in the paths, the parameters, or the body. If the Autoconfig box is grayed out, this means that auto-configuration is not available for this group; for more details on why a specific group cannot be automatically configured, see the tooltip for that item.
For more details on any of the items listed at the top of the panel (processed pairs, unprocessed pairs, messages that don’t match groups, etc.), click the associated hyperlinks.
To review the messages associated with a particular responder—and/or to change the responder and data set name—click the related row in the Count column.
Configuring Request Mapping Options
The Request Matching screen enables you to remap the request/response pairs, customize which parameter values are used to determine the response messages of the virtual asset, and specify the service definition associated with this message. Complete details about configuring the options in the Request Matching screen are in the Customizing Request Matching and Correlations chapter.
Configuring Data Reuse Options
The defined record identity is used to determine which data is new and which new records match existing records. If it has not already been specified for this data set, the identity can be added/modified in the data tree. The tree indicates identity fields with green arrow icons. Existing data sets are noted with annotations. Complete details about configuring reuse are discussed in the Configuring Data Reuse and Updating chapter.
You can control how new data from the traffic file will extend and/or update existing repository data sets.
You can also control whether matching data (data that matches existing record types, as determined by the identity) reuses existing record types or updates an existing record:
The Reuse option enables you to reuse/share the existing records that match. The Update option enables you to update the existing records’ corresponding fields with data from the traffic and add new records for new record types.
Replace: Erase existing data then add the new data.
Merge: Import new data without modifying existing data.
Update: Update matching records with new data and create new records as needed.
Overwrite: Update matching records (with matching keys) with new data, do not create any additional records.
The Infer constraints from option enables the Virtualize to determine the characteristics of the data stored in the repository. You can infer constraints based on the data or a service definition.
Deploying the Virtual Assets
If the .pva was created in the Virtual Asset folder, the virtual assets is automatically deployed to the local Virtualize server as the wizard completes. Otherwise, you can deploy it to local or remote servers whenever you are ready. For a more detailed discussion of deployment procedures and options, see Deploying Virtual Assets - Overview.
Customizing the Virtual Assets
For details on how to customize the Message Responder’s behavior, see Message Responder Overview.
Understanding Choice/Extension Type Support
If you do not enter a WSDL or schema file at the end of the wizard, Virtualize uses the data structure of recorded traffic to create the data repository. When the data structure of an element varies in the recorded traffic, it is likely that the type for that element is a choice in the underlying schema. However, the wizard does not explicitly support choice types; it interprets an element’s data structure as a sequence of all possible child elements. For example, assume an element whose actual schema is like this:
<element name="parent"> <complexType> <choice minOccurs="0" maxOccurs="unbounded"> <element name="child1"/> <element name="child2"/> <element name="child3"/> </choice> </complexType> </element>
Virtualize will represent the element with the following data structure:
<element name="parent"> <complexType> <sequence> <element name="child1" minOccurs="0" maxOccurs="unbounded"/> <element name="child2" minOccurs="0" maxOccurs="unbounded"/> <element name="child3" minOccurs="0" maxOccurs="unbounded"/> </sequence> </complexType> </element>
Although the recorded traffic might have child elements appear in a varying order (e.g., the "parent" in one of the response message has "child1" and then "child2", while the "parent" in another response message has "child2" and then "child1"), Virtualize will parameterize message data in a fixed order. Thus, in this example, the elements "child1" and "child2" will always be in the same order within the response message.
Completing the Virtualize Wizard: Advanced Topics
The following topics provide additional details that will help you complete the wizard:
- Using Configuration Templates to Reuse and Share Wizard Settings
- Understanding Heuristics for Grouping by Operation - Type
- Customizing Grouping Criteria
- Customizing Request Matching and Correlations
- Configuring Data Reuse and Updating
Video Tutorial: Creating Virtual Assets from Traffic Recorded with a Message Proxy
In this video you'll learn how to create a virtual asset from traffic recorded with a message proxy.