TestScript Editor

The TestScript Editor is an Eclipse-based desktop development environment. It provides a comprehensive suite of development tools for creating, managing and publishing FHIR TestScript resources. It is designed to simplify test script development and accommodate a large number of users, ranging from beginners to experts.

The TestScript Editor can be used to:

  • Upload Test Groups and TestScript resources to Touchstone.

  • Upload Test Groups to and download them from Simplifier.

  • Manage TestScript resources by integrating with Version Control systems such as SVN, GIT etc.

The TestScript Editor leverages the following built-in Eclipse editors:

  • XML Editor (*.xml)

  • JSON Editor (*.json)

  • Groovy Editor (*.groovy)

  • Text Editor (*.txt)

  • Java Editor (*.java)

Download

You can download the TestScript Editor by going to Docs > Downloads and selecting the appropriate platform:

../_images/download_a1.png

Once the download is complete, unzip the zip file to a directory of your choice.

Install a JVM

Note

  • TestScript Editor is a Java-based application and it requires a Java runtime environment (JRE) in order to run.

Regardless of your operating system, you will need to install Java virtual machine (JVM). You may either install a Java Runtime Environment (JRE), or a Java Development Kit (JDK), depending on what you want to do with TestScript Editor. A Java Development Kit (JDK) includes many useful extras for Java developers including the source code for the standard Java libraries.

Current releases of TestScript Editor require Java 8, click this link below for detailed instructions to install JDK 8 or JRE 8 on Microsoft Windows, Linux, and OS X computers.

Set JAVA_HOME:

1. Microsoft Windows:

  • Go to “Control Panel / System Properties / Advanced tab” and select “Environment Variables”.

  • Set the JAVA_HOME variable value to the location of the JDK or JRE e.g. “C:\Program Files\Java\jdk1.8.0_181”.

  • Add “%JAVA_HOME%\bin” to the PATH variable and click ‘OK’ to save the changes.

  • To verify, open command line and run ‘java -version’. This should display the details of the JDK or JRE selected above.

2. Linux:

  • To set JAVA_HOME in Linux for all users, we can use /etc/profile or /etc/environment (preferred).

  • Open /etc/environment in any text editor and add:

    JAVA_HOME=/path/to/java_installation

Note

  • Please note that /etc/environment is not a script, but a list of assignment expressions (that is why export is not used). This file is read at the time of login.

  • To set JAVA_HOME using /etc/profile, open the file and add:

    export JAVA_HOME=/path/to/java_installation

  • Run the source command to load the variable:

    source /etc/profile

  • Now we can check the value of the JAVA_HOME variable.

    echo $JAVA_HOME

  • The result should be the path to the JDK or JRE installation, for example:

    /usr/lib/jvm/jdk1.8.0_181

3. Mac OS X:

  • To set JAVA_HOME in Mac OS X for single user, we can use ~/.bash_profile

  • Open ~/.bash_profile in any editor and add:

    export JAVA_HOME=/path/to/java_installation

  • Save and close the file.

  • Open a Terminal and run the source command to apply the changes:

    source ~/.bash_profile

  • Now we can check the value of the JAVA_HOME variable:

    echo $JAVA_HOME

  • The result should be the path to the JDK/JRE installation, for example:

    /Library/Java/JavaVirtualMachines/jdk1.8.0_181.jdk/Contents/Home

Note

  • To set JAVA_HOME globally for all users, the steps are the same as above, but the file /etc/profile is used.

JAVA Info for .ini file:

You will need to point the IDE to the older Java JDK 8 in the TouchstoneIDE.ini file. Please check to see where the JDK 8 built and ensure your path is correct for your machine. Your TouchstoneIDE.ini should reflect what is provided below.

Microsoft Windows:

-startup

plugins/org.eclipse.equinox.launcher_1.4.0.v20161219-1356.jar

--launcher.library

plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.1.551.v20171108-1834

--launcher.appendVmargs

-vm

C:Program FilesJavajdk1.8.0_221bin

-vmargs

-Dosgi.requiredJavaVersion=1.8

--add-modules=ALL-SYSTEM

Mac OS X:

-startup

../Eclipse/plugins/org.eclipse.equinox.launcher_1.4.0v20161219-1356.jar

--launcher.library

../Eclipse/plugins/

org.eclipse.equinox.launcher.cocoa.macosx.x86_64_1.1.551.v20171108-1834

--launcher.appendVmargs

-vm

/Library/Java/JavaVirtualMachines/jdk1.8.0_251.jdk/Contents/Home/bin

-vmargs

-Dosgi.requiredJavaVersion=1.8

--add-modules=ALL-SYSTEM

-XstartOnFirstThread

-Dorg.eclipse.swt.internal.carbon.smallFonts

Start TestScript Editor

To bring up the TestScript Editor, run/open the Touchstone IDE file in the unzipped directory. It will be Touchstone IDE.exe on Windows, Touchstone IDE.app on Mac, and Touchstone IDE on Linux.

Feel free to create a shortcut to this file.

The first time, the editor is brought up, it will prompt you for the location of your workspace. You can select any location. The workspace location can be different from the location of your TestScript resources.

../_images/workspace_a1.png

Use of TestScript Editor requires Enterprise-Level subscription. You must use the same credentials you use to sign into Touchstone web site:

../_images/credentials2_a1.png

Create TestScript Project

You can start by creating a simple project as follows:

  1. From the menu bar, select File > New > Project...

    ../_images/new_project_a1.png

  2. In the New Project wizard, select General > Project and click Next:

    ../_images/ts_new_project_wizard1_a1.png

  3. In the Project name field, type the name of your new project e.g. FHIRSandbox.

  4. Leave the box checked to use the default location or uncheck the default location and select a new location for your new project. Click Finish when you are done.

    ../_images/ts_new_project_wizard2_a1.png

The navigation view will now contain the FHIRSandbox project you just created.

../_images/ts_new_project_wizard3.png

Create a Test Group

Test Groups in Touchstone are represented by folders in TestScript Editor. You can create a new folder using the Project Explorer view’s popup menu:

  1. Activate the Project Explorer view and select the project FHIRSandbox (the first project we created in the Project Explorer view). Right click on FHIRSandbox folder and select New > Folder.

    ../_images/new_folder_a1.png

  2. In the Folder name field, type a unique name for your new folder, e.g. Patient:

    ../_images/new_folder2_a1.png

  3. Click Finish when you are done. The Project Explorer view will update to show your newly created folder:

    ../_images/ts_new_folder_wizard2.png

  4. Repeat the folder creation steps. This time, create Client Assigned Id under the Patient folder:

    ../_images/ts_new_folder_wizard3_a1.png

  5. The Project Explorer view will update to show your newly created folder:

    ../_images/ts_new_folder_wizard4.png

Create a TestScript

You can create a TestScript by following the steps below:

  1. Select the folder Client Assigned Id in one of the navigation views.

    ../_images/folder_selection_a1.png

  2. In the toolbar, activate the drop-down menu on the New Wizard button new_file_icon and select File:

    ../_images/new_file_a1.png

  3. Enter the file name including the extension e.g. Patient-client-id-json.xml:

    ../_images/new_file_name_a1.png

    The file extension is “.xml” indicating that the source will be written in XML format.

    The file name has “-json” indicating that the TestScript will be used to call REST operations in JSON format. You don’t have to follow this convention.

  4. Click Finish when you are done.

  5. The Workbench has an editor capable of editing XML files. The editor is automatically opened on the newly created file:

    ../_images/ts_xml_file_editor_a1.png

  6. Select the Source tab and copy into it the contents of the Patient test scripts. Current up-to-date scripts may be obtained from Test Definitions in Touchstone. You can download these example Patient test scripts and fixtures: Example Patient Test

../_images/testscript_source_a1.png ../_images/source_tab_a1.png

Notice that the editor tab has an asterisk (*) at the left of the filename. The asterisk indicates that the editor has unsaved changes.

../_images/unsaved_a1.png

  1. In the Workbench window’s toolbar, click the Save button save_icon to save your work.

The Outline panel shows the high-level structure of the TestScript file:

../_images/testscript_outline_a1.png

Note that a new file can also be created by using the context menu which you can get to by right-clicking the folder:

../_images/new_file_context_menu_a1.png

Code Completion

The TestScript editor provides pre-defined easy-to-use XML templates which increase reusability and speed up development of test scripts.

To access the templates, open any XML file and enter CTRL + SPACE. This displays the predefined list of templates that you can select for code completion:

../_images/ts_xml_template_a1.png

You can use the provided templates, customize them, or create your own templates.

For example, you can work on a group of testscripts that should all contain a rule/ruleset element with a specific definition. Create a template that contains the tags for that rule/ruleset, including the appropriate attributes and attribute values for each tag. You can copy and paste the tags from a structured text editor into the template’s Pattern field. Then select the name of the template from a content assist proposal list whenever you want to insert your custom rule/ruleset into an XML file.

To create a new XML template, you can take the following steps:

  1. Click Window > Preferences and select XML > XML Files > Templates.

  2. Click New if you want to create a completely new template.

  3. Supply a new template Name and Description.

  4. Specify the Context for the template. This is the context in which the template is available in the proposal list when content assist is requested.

  5. Specify the Pattern for your template using the appropriate tags, attributes, or attribute values to be inserted by content assist.

  6. If you want to insert a variable, click the Insert Variable button and select the variable to be inserted. For example, the date variable indicates the current date will be inserted.

  7. Click OK and then Apply to save your changes.

You can edit, remove, import, or export a template by using the same preferences page. If you have modified a default template, you can restore it to its default value. You can also restore a removed template if you have not exited from the workbench since it was removed.

If you have a template that you do not want to remove but you no longer want it to appear in the content assist list, clear its check box in the table on the Templates preferences page.

Touchstone Integration

Note

  • You need to be connected to internet

  • You need Starter or higher subscription level to upload test scripts to Touchstone.

Upload to Touchstone

  1. Upload to Touchstone can be initiated in one of the following ways:

    1.1. Toolbar upload button - In the toolbar, click the upload icon upload_icon button. The file or folder selected in the Project Explorer view will be uploaded.

    ../_images/toolbar_upload_a1.png

    1.2. Popup menu - In Project Explorer, right-click a folder or file and click on Upload to Touchstone:

    ../_images/ts_upload_menu2_a1.png

    1.3. Touchstone menu - Click on Touchstone > Upload to Touchstone on the menu bar. The file or folder selected in the Project Explorer view will be uploaded.

    ../_images/ts_upload_menu1_a2.png

    1.4. Editor popup menu - In the editor, right-click the content pane and click on Upload to Touchstone:

    ../_images/ts_upload_menu3_a1.png

    Warning

    You should upload the root folder first before attempting to upload sub-folders and files.

  2. Notice the absence of Patient folder in FHIRSandbox in Touchstone UI:

    ../_images/upload_tsweb_no_orgfolder_a1.png

  3. Select the Patient folder and click on the Upload icon:

    ../_images/upload_patient_folder1_a1.png

  4. Select the View/Modify options and click the Upload button to submit or Cancel to cancel the request.

    ../_images/ts_upload_dialog2_a4.png

    The Can be viewed by and Can be modified by options are explained in Upload Destination and Test Definition access.

  5. If the validator you selected has any additional validators linked to it, you will be prompted with another window where you can optionally choose to select zero or more validators to upload along with. If Upload is selected, the upload will run in the background:

    ../_images/ts_upload_dialog_add_val_a2.png

  6. You will get an error from the server stating that all dependent fixtures were not included as part of the upload. Fixtures referred to by this test script should already exist in Touchstone or should be included as part of the upload.

    ../_images/test_script_upload_failed_a1.png

  7. Current up-to-date scripts may be obtained from Test Definitions in Touchstone. You can download these example Patient test scripts and fixtures: Example Patient Test

    ../_images/patient-test-group_a2.png

  8. This time when we upload the Patient folder, the upload succeeds:

    ../_images/upload_patient_folder2_a1.png ../_images/ts_upload_response_dialog_a1.png

  9. Notice that the test group Patient lands under the name of the organization the user belongs to:

    ../_images/upload_tsweb_orgfolder_a3.png

  10. Now that the root folder (Patient) has been uploaded to Touchstone, you can make changes and create/upload individual folders within any level of the hierarchy:

    ../_images/upload_subfolder_a1.png ../_images/ts_upload_response_dialog2a_a1.png

  11. You can also upload changes to individual test scripts and create new test scripts:

    ../_images/upload_testscript_a1.png ../_images/ts_upload_response_dialog3_a1.png

  12. You can do the same with individual fixtures:

    ../_images/upload_fixture_a3.png ../_images/ts_upload_response_dialog4_a1.png

  13. You can see the history of completed upload jobs in progress view:

../_images/ts_progress_view_show.png ../_images/ts_progress_view.png

Simplifier Integration

Simplifier Preferences

To upload or download files you need to configure the Simplifier user credentials in preferences page Windows -> Preferences -> Simplifier

Enter your Simplifier user credentials and click Apply and Close button to save the preferences. This will be used to authenticate and authorize the requests in Simplifier.

../_images/ts_simplifier_preferences_a1.png

Create New Project

Start by creating a simple project as follows:

  1. From the menu bar, select File > New > Project...

    ../_images/ts_new_project_wizard1_a1.png

  2. In the New Project wizard, select General > Project then click Next.

  3. In the Project name field, enter the Simplifier Project key as the name of your new project e.g. FHIR3-0-1-Connectath. The Simplifier project key can be found in Simplifier account page Settings > Project URL

    ../_images/simplifier_page.png ../_images/simplifier_page1.png

  4. Leave the box checked to use the default location for your new project. Click Finish when you are done.

    ../_images/ts_new_project_wizard4_a1.png

    In the navigation view, you will see the FHIR3-0-1-Connectath project we just created.

    ../_images/ts_new_project_wizard5.png

Note

  • You need to be connected to internet

  • You need to have a Simplifier account with active projects.

  • You need to configure the Simplifier user credentials in the editor before uploading or downloading files from Simplifier.

Download from Simplifier

  1. In the Project Explorer view select the new project FHIR3-0-1-Connectath > Right Click > Simplifier > Download from Simplifier. If authentication is successful the files will be downloaded from Simplifier:

    ../_images/ts_simplifier_download_a1.png ../_images/ts_simplifier_download_dialog_a1.png

  2. Refresh project FHIR3-0-1-Connectath and you should be able to see the downloaded files

    ../_images/ts_new_project_wizard6.png

Upload to Simplifier

  1. In the Project Explorer view select the new project FHIR3-0-1-Connectath > Right Click > Simplifier > Upload to Simplifier. The confirmation dialog window is displayed:

    ../_images/ts_simplifier_upload_a1.png ../_images/ts_simplifier_upload_dialog_a1.png

  2. Select Ok to submit or Cancel to cancel the upload process.

  3. If authentication is successful the files are uploaded to Simplifier project.

    ../_images/ts_simplifier_upload_success_a1.png

  4. You can verify the uploads on the Log tab in Simplifier as shown below.

    ../_images/simplifier_log_screen.png

Updating TestScript Editor

You can update the TestScript Editor as follows:

1. Check for Updates: (Recommended)

To check to see whether there are updates for the TestScript Editor in your system (requires Internet access):

  1. Click command link Help > Check for Updates or by clicking the Updates Available notification shown below. The notification is displayed when new updates are available on startup and reminds the user every 4 hours if not updated.

    ../_images/ts_update_notification.png

  2. This will contact the Web sites defined in your Available Software Sites preferences to look for upgrades. If upgrades are available, they will be presented in the Available Updates wizard as shown below.

    ../_images/ts_available_updates_wizard.png

  3. Check the updates that you wish to install. Click Next to see the details of the updates available as shown below.

    ../_images/ts_available_updates_details_wizard.png

  4. Click Next to review the license for selected items. If the terms of all these licenses are acceptable, check “I accept the terms in the license agreements and click Finish to install the updates.

    ../_images/ts_update_software_license.png

  5. Since TestScript Editor updates are not digitally signed the security warning dialog will be displayed. Click Install Anyway to continue the installation.

    ../_images/ts_updates_security_warning.png

  6. Once the updates are installed successfully, you will be prompted to restart the workbench. Click ‘Restart Now’ to restart the Workbench for the changes to take effect.

    ../_images/ts_update_restart.png
2. Using the Install New Software Wizard

The Install New Software Wizard allows you to add new or update software to your installation. To install new or update an existing software:

  1. Click Help > Install New Software.... This wizard shows you the items that are available for installation.

  2. Select the TestScript Editor update site using the Works With combo at the top of the page. By default the items in the site are grouped by category and the latest version of each item is shown.

  3. As you browse the available software, you can check the items that you wish to install.

    ../_images/ts_new_install_wizard.png

  4. When you have finished making your selections, click Next to install the checked items. If the items you are installing require other software items in order to operate, those requirements will be included in your request. A checkbox at the bottom of this page controls whether all software sites will contacted when looking for requirements, or only the site shown in the Work With combo box.

  5. Once you click Next, the wizard will validate your selections against your installed software, and may display the ‘Install Remediation page’ if the items selected are already installed. Select Update my installation to be compatible with the items to be installed and click Next.

    ../_images/ts_new_install_remedy_page.png

  6. If all of the requirements are available and there are no other installation conflicts, clicking Next will show the Install Details page. The items to be installed will be listed. Expanding each item will show what additional items will be required to complete the install. You will see an estimated size of the installation at the bottom of the page.

    ../_images/ts_new_install_details.png

  7. If the selected items have license agreements to be reviewed, you must click Next. Carefully review the license agreements for the items you wish to install. If the terms of all these licenses are acceptable, check “I accept the terms in the license agreements.” Do not proceed to download the features if the license terms are not acceptable.

    ../_images/ts_new_install_license_page.png
  8. If the license agreements are acceptable, click Finish. This will begin the download and installation of the new software.

    1. Since TestScript Editor updates are not digitally signed the security warning dialog will be displayed. Click Install Anyway to continue the installation.

    ../_images/ts_updates_security_warning.png

  9. Once the updates are installed successfully, you will be prompted to restart the workbench. Click ‘Restart Now’ to restart the Workbench for the changes to take effect.

    ../_images/ts_update_restart.png