Well, here we are – just 2 short months away from the next HL7 FHIR DevDays event. This time kicking off Summer in June on our side of the pond in Boston, MA. And, once again the Firely (formerly Furore) team have given me the honor of presenting one of the opening sessions “A General Introduction to FHIR” along with my Touchstone and FHIR Testing sessions “Test Driven Development I – Intro” and “Test Driven Development II – Advanced“. Check out the full DevDays 2018 Boston event schedule and you’ll find my sessions under the “FHIR Testing” Track.
Hope you can make it there. I’m looking forward to starting off the Summer on FHIR!
And now, back to Touchstone and FHIR Testing, Take 2…
Following up on my last post “Ready, FHIR, Test!“, let’s continue our exploration of Touchstone and its capabilities. Last time I introduced Touchstone as our [AEGIS] conformant FHIR Testing Framework that is a publicly accessible, open access, cloud based, Testing as a Service (TAAS) solution. A couple of initial, key features I pointed out are Touchstone’s use of the FHIR TestScript resource and the ability to support both happy-path and negative test scenarios. I’d like to now take a look at some of the other features that provide our user community with the ability to do what we call ‘continuous testing‘ and provide a view into their test systems’ conformance to the FHIR specification.
Continuous testing – what does it mean and how does it work?
Ok, this will probably make a little more sense to the developers out there, especially those that are familiar with incorporating automated testing frameworks into their application development; e.g. JUnit, TestNG, Selenium, etc. When someone mentions or talks about “Test Driven Development”, that’s what most developers think of, right? As I mentioned in my last post, a key component of testing your application on a continuous basis is incorporating these unit level testing frameworks into the overall development process. The testing that Touchstone supports, however, is at the integration level, or system to system. And, that’s the level where we need tools, like Touchstone, to provide that needed continuous testing.
Just like the application development automated unit testing frameworks, Touchstone provides for the manual execution of individual or multiple tests. A Touchstone Test Setup can be created based on one or more TestScripts. I might choose just one TestScript to focus my testing, or I can choose All TestScripts within a Test Definition Group:
 
Once executed, the results are then displayed for review:
But, did you know there’s another way to do this? Automated, remote test execution of Test Setups can be done through the Touchstone API.
Touchstone API – Definition
Test executions can be launched and monitored via remote RESTful web services. This allows for integration of Touchstone test executions as part of your internal automated regression tests (e.g. CI runs).
There is a downloadable ZIP archive, touchstone-api.zip, that contains:
- The XML and JSON schemas for the Touchstone API message request and response payloads
- Example request and response message payloads showing good and bad content
There are 5 Touchstone API services available:
Authentication
This API call takes the user credentials in the request body and returns an “API-Key” in the response. The “API-Key” value must then be passed as a request header for all subsequent API calls.
URL: POST https://touchstone.aegis.net/touchstone/api/authenticate
Before you can call any of the other APIs, you must authenticate with Touchstone. Successful authentication will start a new API “session” with Touchstone. There are no limits on how long an API “session” can last. However, there are limits to the number of API “sessions” an organization can use in any given day. For that reason, you should re-use the same “API-Key” for all subsequent API calls as re-authenticating again would start a new API “session”.
Launching Test Executions
This API call takes the Test Setup name in the request body and returns the id of the test execution (that was launched) in the response.
URL: POST https://touchstone.aegis.net/touchstone/api/testExecution
Test Setups must be pre-created on the Touchstone UI before launching test executions using Touchstone API. It is recommended to have your Test Executions reach expected results on the Touchstone UI before you integrate them via Touchstone API. The UI offers a lot more navigation and information than the Touchstone API.
Retrieve Test Execution status
This API call takes the id of the test execution in the request URL and returns the test execution summary status.
URL: GET https://touchstone.aegis.net/touchstone/api/testExecution/[testExecId]
You do not need to wait between “/api/testExecution” (POST) and “/api/testExecution” (GET) calls. But you do need to wait at least 4 seconds between repeated “/api/testExecution” (GET) calls in order for test execution to sufficiently proceed forward and provide updated results.
Retrieve Test Execution Detail
This API call takes the id of the test execution in the request URL and returns the test execution status along with summary status for all the TestScript executions within the test execution.
URL: GET https://touchstone.aegis.net/touchstone/api/testExecDetail/[testExecId]
You do not need to wait between “/api/testExecution” (GET) and “/api/testExecDetail” calls. But you do need to wait for 15 seconds between repeated “/api/testExecDetail” calls. The reason for the long wait time is to discourage bypassing of “/api/testExecution” (GET) calls. You should call “/api/testExecDetail” only when the test execution has reached completion. To determine if a test execution has reached completion, you can call “/api/testExecution” (GET) repeatedly every 4 seconds. Once it has reached completion, you then only need to call “/api/testExecDetail” the one time.
Retrieve Script Execution Detail
This API call takes the id of the test execution in the request URL as well as the name of a TestScript and returns the script execution details.
URL: GET https://touchstone.aegis.net/touchstone/api/scriptExecDetail/[testExecId]?testscript=[testScriptId]
You do not need to wait between “/api/testExecDetail” and “/api/scriptExecDetail” calls. But you do need to wait for 4 seconds between repeated “/api/scriptExecDetail” calls. Repeated “/api/scriptExecDetail” calls would presumably be for different TestScripts within the test execution. You should call “/api/scriptExecDetail” when the test execution has reached completion (determined by “/api/testExecution” GET call) and after calling “/api/testExecDetail”. The “/api/testExecDetail” response will contain the parameters needed to make “/api/scriptExecDetail” call(s); i.e. the testExecId and the TestScript id(s).
So, how do we use the Touchstone API? Well, I have a great use case documented in our Touchstone User Guide that describes how I integrated the Touchstone API with a Jenkins Continuous Integration build server. Check it out here –Â https://touchstone.aegis.net/touchstone/userguide/html/continuous-integration/jenkins.html.
Until next time, happy FHIR Testing!