Toolkit-Glossary

Test Engine - Element of toolkit that runs tests that start with toolkit initiating a connection to the SUT. Generates log files that can be browed with Inspector. The Home page holds tools that use the Test Engine in two different ways. Under the Tools column is a tool labeled Pre-Connectathon Tests. This tab lists pre-built tests (based on Test Engine) that are used to qualify systems for Connectathon. Tests are organized by the Actor and Transaction they test. The tools in the Queries & Retrieves and Send Test Data columns use the Test Engine to provide utility functions for poking and prodding configured systems. Both uses of Test Engine result in log information be stored that can be browsed using the Inspector.

Environment - toolkit can be loaded with multiple environment selections that are selected in the UI on any tab where it is relevant. Each selectable environment is labeled with a unique name. Behind each environment is an Affinity Domain configuration to be used as well as a certificate for TLS. By selecting a different environment, toolkit can quickly change configurations. The TLS certificate only affects outgoing connections generated by the Test Engine. The Affinity Domain is used to validate messages received back by the Test Engine. Certificates used to anchor incoming connections (see Simulators) must be installed directly in the servlet container (Tomcat). Environment definitions are stored in the External Cache in the environments directory.

TestSession - a name used to identify logs. In some ways this is a simple user_id but it is not used in authentication (toolkit does not use authentication). Test results (log files) are maintained in a directory named for the current user/testsession (the two terms are used interchangeably). Toolkit is intended for local use only (download and install) and not for Internet use (can be used this way but its structure and model don't really fit that environment). A test session can be used in many ways: to enable multiple users to keep their test results separate; to allow a single use to keep test results for multiple SUTs separate etc. Toolkit architecture and implementation do not dictate a use.

Actor - term used by IHE to identify a particular personality of a system. A system can be built entirely on the definition of an actor or multiple actors or the system can have some other purpose but pulls in the actor identity to supplement/complement its function. Talking about an actor vs the entire system focuses the discussion on the functionality described by an IHE profile.

Transaction - an interaction between actors. Typically a message sent.

Site - a collection of configuration information managed by toolkit. Each site has a unique name which shows up on tabs that drive the test engine. Each site can contain at most 1 of each type of actor. Each actor does not have to be behind the same network address or port.

Site/Actor Configuration - tab listed on the home page that can be used to create/edit sites. Sites managed here are stored in actors.xml. If enabled by the checkbox on the UI, sites created by simulators can also be displayed on this tab.

Simulator - a lightweight actor implementation provided by toolkit. Most simulators cannot manage tons of data like an actual implementation. The Simulator Control page is used to create, destroy, and alter the configuration of simulators. A single instance of the toolkit can support multiple instances of a simulator concurrently. So you can have two Document Repositories and two Document Registries running at the same time each with their own independent document/metadata storage facilities.

Simulator Control tab - tab used to create, configure, and destroy simulators. Simulators created here have their endpoints listed in other tabs that reference that actor/transaction. The refresh link on a tab may have to be used to force the display update. Once created, a simulator runs until it is deleted as long as the servlet container (tomcat) is running. The Simulator Control tab does not have to be open. There is good reason to keep the Simulator Control tab open with simulators of interest loaded.

Simulator Message View tab - display messages to simulators and the responses for all open simulators. The brings up the distinction between open and active simulators. An active simulator is one that will accept messages and reply, logging the interaction. An active simulator can be open. When a simulator is open, two things happen on the UI. First, the site defined by the simulator is visible in other menus. So an open Document Registry simulator will show up in the list of selectable registries on the Find Documents Stored Query tab. Second, open simulators show up in the listing on the Simulator Message View tab. Logs are kept for all active simulators but only the open simulators are shown in the log listing. Basically, opening a simulator means you will be focusing on it in the UI.

Test Data

External Cache - maintained in a directory on the system where toolkit is installed. Contains configuration information and log files for toolkit. The toolkit file toolkit.properties contains a property that points to the External Cache. This separate cache is maintained so information is not lost when upgrading to a new version of toolkit. External Cache be any writable empty directory on the system with one exception. Its path may not contain whitespace characters (blanks, tabs etc.).

actors.xml - a file in the External Cache where the configurations for all known sites are kept. These configurations include TLS and non-TLS endpoints for defined transactions, repositoryUniqueId, homeCommunityId values etc. The UI actor lists displayed are driven from the contents of this file. There is an alternate form of the file, the actors directory, also kept in the External Cache. This form is useful when there are a great number of actor configurations being used as in the context of an IHE Connectathon. The file toolkit.properties controls which of these two storage mechanisms for actors is used through the property named Use_Actors_File.

simdb - a directory in the External Cache where the state of all active simulators is maintained. Within this directory is a directory for each simulator named by the simulator id. The only practical reason to manipulate this directory is to delete a simulator directory. This deletion destroys the simulator, its state, and logs.

TestLogCache - every invocation of the test engine results in a test log being created. When the test engine is used via the Pre-Connectathon Tests tab the resulting log files are stored in TestLogCache. The top level directories under TestLogCache name the TestSession (user) so that multiple users can operate independently off one installation of toolkit. TestLogCache is a directory under the External Cache.

tk_props.txt - properties file that controls/configures the toolkit. Resides in the External Cache. At this time tk_props is primarily used to configure the MU 2 functionality but in the future most all configuration will be managed through this file.

Test Log

Logs

Message Validator - a message validator takes as input a message or document and validates its structure and content. This term is also used to label the entire sub-system of the toolkit that maintains and operates individual validators. The architecture is based on the onion model (Ogres are like onions - they have layers - validators are also like onions - they have layers too!). Message validators are driven by a structure called a Validation Context which defines the validation challenges. An example of a set of challenges is an XDS.b Provide and Register transaction wrapped in SOAP encode with MTOM wrapped in HTTP as defined by ... Oh, and add to that the requirement that the message must be carrying a document identified as a CCDA of type x. A message validator operates by using a queue to manage future validations. As a message is decoded, its pieces are cordoned off and their individual validation is schedule through the validation queue. In this way, each validator is written independently of the others allowing them to be mixed and matched at runtime. The simulator system uses this message validator architecture as its underpinning.

Inspector - a graphical browser for messages and metadata. All UI tabs whose operation results in messages being sent and returned have a button to launch the inspector (in a separate toolkit tab) to view the results. In many cases, secondary operations can be initiated from the inspector. And example is running a GetDocuments stored query and inspecting the resulting metadata. When the DocumentEntry object is displayed in the inspector the user has the option of requesting a Retrieve Document transaction based on the contents of the DocumentEntry object. After the Retrieve is complete, an addition operation to display the retrieved document can be invoked.

toolkit.properties - file stored in the WAR file in the directory WEB-INF. Contains the most basic configuration parameters including the location of the External Cache.

Database engine - something not used by toolkit. Instead, toolkit uses filesystem directories and files to store stuff. Complicated stuff frequently uses persistent Java objects. The lack of a database engine leads to the simple/lightweight installation requirements.

tabs - there are two kinds of tabs, browser tabs and toolkit tabs. Browser tabs are the native ability of a browser, like Firefox, to display multiple tabs in a window. Toolkit operates inside a single browser tab. Within the browser tab running toolkit, toolkit itself implements tabs for isolated display of toolkit content. Tabs within tabs.