About the XML Library

The XML Library is the repository for all of the test configurations, XML Snippets, and report configurations that you'll create with dsClient Desktop. Within the application library is an xmlLibrary directory and that is your Local Library to organize as you see fit. You can create sub-directories, nest directories, and group your files in whatever arrangement is useful to you. In addition, you and your colleagues can share libraries, enabling you to establish a standard test library that everyone can read from but only a select few can update. In this topic we'll discuss managing your library with the Library Browser as well as how to import dsClient files, import dsTest XML configurations, and how to export from your library.

dsClient Desktop establishes two libraries - the Local Library and the Examples Library - the first time the application is run. Thereafter, whenever dsClient starts it scans your Local Library, and any remote libraries you may have added, to discover the structure and content of each library. This allows you to restructure your library or to add or remove library files directly in the file system rather than through dsClient if you prefer.

The test configuration files in your library are written in dsClient Desktop XML, not dsTest XML. You cannot directly configure dsTest with these files but must use dsClient to either load your test or to generate dsTest XML files. In order to clearly distinguish between the two, dsClient library files are named with a .dsx file extension.

We provide example test configurations for every interface application, including examples that illustrate dsTest features. Each example consists of two test configurations - a client-side and a server-side - that are configured to run on the same platform using its local interface. dsClient downloads those examples from dsTest and stores them in the application library, refreshing them when a new version becomes available. If you have more than one dsTest installation, you can set a default server in your preferences and dsClient will only update the examples when that server is upgraded. Otherwise the latest version available will be maintained. These test configurations are presented in the Library Browser as a read-only remote library as shown below, with the dsTest version for which the examples were published identified. You can run the examples as is, assuming dsTest is licensed for the requisite applications, or modify them to suit your test goals and save them in your library.

If you want to load a specific version of examples, or if you otherwise need to update the library, you can download examples from a particular dsTest server from the Status and Operations screen.

You can access and manage all of your libraries - no matter where they are located - with the Library Browser. Click the folder icon (

) on the Explorer tool bar or select File>Open... from the menu to display it. It will also be displayed in a horizontal layout when you click Save As... to establish a new file.

The upper, or left, panel contains the library tree that displays the directory structure of your libraries, and each library is represented by a tree node descending from XML Library. The Examples library appears as a protected library (

) and when populated will display the corresponding dsTest version in the root tree node. A library can be protected to prevent changes through file system permissions or in the library's configuration (see Managing Libraries below). Using either method will cause the lock icon to be displayed for that library, and dsClient will prohibit any action that would modify that library's content or structure.

The lower, or right, panel contains a table that displays the file content of the directory that is currently selected in the tree. The files are sorted alphabetically by default. You can click on a column header to sort by that column and click again to reverse the sort order.

The icons in the browser's toolbar will become enabled or disabled depending on whether you last clicked on a tree node or on a file table row. These actions are not applicable to the tree nodes that represent libraries. Use the Manage... button to add, remove, or modify libraries.

(edit) Opens the selected file for editing. Double-clicking the table row also opens the file.

(new directory) Displays a dialog to collect the name of the new directory. If a directory of that name does not already exist under the parent directory, one is created and shown in the tree.

(duplicate) Creates a duplicate object of the selected object in place with the name Copy of <object name>. This is the only way to copy a file and leave the copy in the same directory.

(rename) Displays a dialog to collect the new name of the directory or file. .dsx will be appended to file names if needed. An overwrite warning is displayed if the resulting name matches a sibling file or directory, and the sibling will be overwritten upon confirmation.

(refresh) Performs the same library scan that is executed at application start-up, resulting in a reconstructed library tree. You can kick off a scan to synchronize with the client file system after adding or removing items manually, or if an error is encountered during a copy or move action.

(delete) Deletes, upon confirmation, the selected object. The delete key will also invoke this action, assuming the action is enabled. No additional warning is given if you delete a snippet that is referenced by another file.

Generally, drag-n-drop actions are supported in the browser. The image attached to your mouse pointer will indicate if the dragged object cannot be dropped at the current location with a "not allowed" icon (

Move: You can drag a file from the table into a different directory within a library or into any library that is not protected. You can also drag a directory (other than a library) into another directory. An overwrite warning is displayed if indicated.

Copy: You can copy a file or directory by dragging while pressing the Ctrl key. A "+" symbol is displayed on the drag image when copying, and the original object remains in place.

The protection status of a library can affect drag-n-drop behavior. You will be prohibited from dragging anything into a protected library, and dragging out of a protected library will always be treated as a copy regardless of whether the Ctrl key was used.

Click on the Manage... button in the tool bar to open the Manage Libraries dialog. Here you can add a library (

) or remove a library you previously added (

), or modify a library's location or protected status. When you remove a library you have a choice of whether to delete the content from disk or simply remove the library from your list of libraries.

Use the Browse... button to specify the location of a new library or to change the location of an existing library. If a remote library is unreachable it will be represented as a protected library and the application will otherwise operate normally.

You can use the Protect Library checkbox to prevent inadvertently saving changes to a colleague's library or to a standard library that you don't control. dsClient also inspects file system permissions of library root directories during the scan, and if you have linked to a library where you lack write permissions the Read-only Library checkbox will be selected and the application will consider that library to be protected.

Once committed, the name of a library cannot be changed. This is because paths to XML Snippet files, when they are referenced in a configuration, begin with the library name.

You can use the export feature to share your configurations with colleagues or to send configurations to our Support Team. The advantages to using this feature are that all content is included in a single file and the receivers have more control over how the bundled items are imported into their libraries.

The left panel of the screen displays a read-only Library Browser while the right panel lists the paths of the files that will be exported. You can drag any number of files and/or sub-directories from within a library into that panel to add files to export. XML Snippets are shown indented below the files that reference them.

You can remove a library file from the list by selecting it and clicking the

icon, which will also remove the rows for any XML Snippets referenced by that file.

In order to protect the integrity of your configurations, XML Snippets may only be removed using one of the following methods:

Note that in the example shown, the Diameter Interface snippets used in the test configurations were from the read-only Examples library, providing an example of mixing your configuration with standard configurations. Also note that XML Snippets were globally excluded. When sharing content between lab facilities, this could allow interface snippets configured for the recipient's lab to be used instead if the root library names matched.

When you are satisfied with the content to be exported, click the Export... button and then use the file chooser to enter the file name and navigate to the desired location for the bundle file. dsClient library bundle files have a .dsb extension, which will automatically be appended to the file name if needed.

The free-form structure of the XML Library makes it very easy to share single, standalone configurations among dsClient applications. As mentioned above, the library scan will pick up changes that you make through the file system. You can also use the Import Library Files screen to import standalone dsClient Desktop library files as well as library bundles and dsTest XML configurations. Selecting the File>Import... menu option opens this screen.

It is always safest to work with clients that are running the same version of dsClient, although it should be safe to copy files from an older client version to a newer client version. Copying files from a newer client version to an older client version, however, may produce undesirable results.

This screen contains four sections, each dedicated to the type of file that is being imported: XML Library Bundle, XML Library File, Workspace XML, and Protocol Dictionary XML. Select the radio button associated with the type of file you're importing and then follow the applicable instructions below.

This option imports the content of XML Library Bundle files described in Exporting from Your Library.

Use the Browse... button to open the file chooser and select the bundle file. Only files with a .dsb extension will be shown. The contents of the bundle file will be shown in the Bundle Structure tree.

If the bundle contains libraries with names that match your libraries you can import into those same libraries, assuming you can write to all of them, by using the Keep bundle structure selection. The application will create any missing sub-directories during the import. You can also choose to import into a different library or into a subordinate directory within a library by selecting Import files into selected directory. If library names do not match, or if the bundle includes files from a protected library, you'll be forced to use the latter option. If you chose to import into a directory, you can use the Create new sub-directory checkbox to house the imported files in a newly created directory.

The Import Structure tree displays a preview of the imported files in their ultimate destination. Click the Update Import Structure button to update this tree if you've made any structural changes.

Regardless of which destination method you choose, you have the option to overwrite files of the same names or to create unique file names with the Overwrite files and Prepend file name with options respectively.

When you import from a bundle file that includes XML Snippets, changes in the relative library path to those files will be replicated in the configurations that reference them.

Finally, click the Import button to make any structural changes you've configured and import the files.

Use this option to import individual test configuration, XML Snippet, or report configuration files.

In this case you must select both the source file and the destination directory. Here again, you may choose to create a new sub-directory to house the file. If you do not want to immediately open the file after importing it, clear the Open file after importing checkbox. Otherwise, assuming the file can be parsed, it will be opened after it is written to disk and you'll be presented with a dialog to select the dsTest server, schema version, or report source depending on the type of file.

You can import either test configurations with the Import Workspace XML option or dictionary configurations with the Import Protocol Dictionary XML. In both cases the file will be parsed and opened. These files will not be brought into your library, however, until you save them.