A common task for a virtual API (virt) is to provide responses that have the same structure, but different data. For instance, your virt may return different temperature values for different places specified by parameters of incoming requests.
To solve this task, you may want to decouple the response structure from data and store the content outside of your virt, for example, in some file or database. In ReadyAPI, virts support loading data from external data sources like Excel sheets, CSV files or database tables and inserting this data into the responses. This feature also allows you to create virts that share the same set of data for their responses of different types. This topic describes how you can configure and use data sources in your virts.
You specify a data source for your virts on the DataSources page of the virt editor:
Each data source has properties. They correspond to data source columns and provide access to the data source’s data.
Switch to the DataSources page of the virt editor. Click on the page toolbar and specify the data source name in the subsequent dialog box. You will use this name to refer to a data source:
Select the data source type and specify connection settings:
The connection settings are common across ReadyAPI tools. For detailed information, see DataSource Reference.
Create properties for the data source. The properties provide access to the data source’s data. If your data source is based on an Excel sheet, on a database or a comma-separated value (CSV) file, the property names you enter must coincide with column names of the data source.
ReadyAPI automatically suggests importing property names from the data source after you finish configuring the connection settings. We recommend accepting this suggestion. If you decline it, you can import properties any time later by clicking the button or create properties manually by clicking on the property list toolbar:
|Tip:||For REST virt users: If the response body you defined contains a JSON object, you can create data source properties from this object – simply click in the DataSource section of the response editor. This will create data source properties whose names coincide with the property names of the object. You can add the properties to a new data source, or to an existing one:|
After you set up data source settings and created properties, you can use the properties in responses (see below).
Select the data source you want to configure. Click to open the configuration dialog.
Set up the options:
Trim – Commands the data source to remove leading and trailing spaces from the retrieved text values.
Entitize – Commands the data source to replace special HTML symbols (like
>) with the appropriate entities (like
Switch to the Setup page of the virt editor.
Select the desired response.
In the property editor on the right, select your data source from the DataSource drop-down list:
Use the property expansion syntax to refer to a property:
– or –
You can insert these expressions into the response body or in a header. The property names are case-insensitive:
If needed, you can use multiple property expansions, for instance:
For REST virt users: The described functionality is available only when the Response Property Expansion property is
true. By default, the property value is
true. You may need to check it if the property expansion stopped working for some reason.
To refer to a data source property in script code, you use the
mockResponse.getPropertyValue(...) function. The property names are case-insensitive:
def propertyValue = mockResponse.getPropertyValue('my-property-name')
mockResponse.responseContent = "<data>" + propertyValue + "</data>"
When you start a virt that uses a data source, the virt connects to the data source and positions the data cursor to the first record.
When the virt receives a request, it selects a response according to the dispatch settings and runs script event handlers. At that, the virt can retrieve data from the current data record and insert this data into the response. During all these actions, the data cursor points to the same record of the data source.
After sending the response, the virt forwards the cursor to the next record. Note that the virt forwards the cursor even if the selected response does not retrieve data from the data source.
When the virt reaches the last record of a data source, it jumps to the first record.
In the virt property editor, you can see some statistics on using the data source:
Select your virt in the Navigator and look at the properties on the right.
The DataSources section displays the list of data sources defined in your virt. The Loops column indicates how many times that virt goes through all the data source records:
Virtual services use the following data source types. Find information on data source settings by the links below:
|Data Source Type||Description|
|Excel||A worksheet in an Excel workbook.|
|File||A file with comma-separated values.|
|Grid||An arbitrary table which you create on the DataSources page and to which you enter data manually. The data source properties you create on the DataSources page are columns of this table.|
|JDBC||A table, view, query or stored procedure of some database, to which you connect through JDBC.|
|Data Connection||A table, view, query or stored procedure of some database, with which you work through a predefined JDBC connection created in the Databases wizard.|
|Data Generator||This data source generates test data for the properties you created on the DataSources page.|
You use the Data Generator data source to generate test data for properties directly from the ReadyAPI UI. The entire procedure is quick and easy:
Select the Data Generator type for your data source.
For each property, configure the data generator parameters to get the values that suite your needs best:
ReadyAPI offers over a dozen of generators that create data of various types: human names, numbers, dates, emails, street addresses, and so on. For complete information on the generators and their parameters, see topics of the Data Generator section.
ReadyAPI stores the generated data as part of your virtual API data. When you deploy your virt to a remote server, the generated data will be copied along with the virt settings to the server automatically.
You use the Grid data source to create test data manually. Select the Grid data source type, create properties and then enter data into the grid cells:
To clone values quickly, enter some value into a cell (press Enter to confirm the input), then click this cell and select Fill Down or Fill Right at the bottom to clone values across other rows or columns correspondingly.
The Grid data source settings and data are stored in your ReadyAPI project as part of your virt data.