API

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 regressions tests (e.g. CI runs). The XML and JSON schemas for Touchstone API are available within the schemas folder in touchstone-api.zip

We recommended that you use a separate test user account for Touchstone API. Test executions launched on behalf of this test user via Touchstone API will be visible to all members of your organization on the Touchstone UI. So if the Touchstone API does not provide enough details on what went wrong in a test execution, any member of your organization can log in as self on the Touchstone UI and investigate the test failures further.

You can register a test user account within your organization and assign only the Tester role to this account. As the Org Rep, when you approve the registration of this test user account, here’s where you assign the Tester role:

../_images/ciuser_a2.png

Authentication

This API call takes the user credentials in the request body and returns an API-Key in the response. Alternatively, the user credentials could be passed in the Authorization header using Basic Authentication. The API-Key value must then be passed in the request header for all subsequent API calls.

URL https://touchstone.aegis.net/touchstone/api/authenticate
Method POST
Examples See goodBasic-authenticateRequest-xxx and goodBasic-authenticateResponse-xxx files within authenticate folder in touchstone-api.zip

Before you could 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. It is recommended that you re-use the same API-Key for all subsequent API calls as re-authenticating would require another trip to the server which will start a new API “session”.

Launching 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. This will be needed in Retrieve Execution status API call later.

URL https://touchstone.aegis.net/touchstone/api/testExecution
Method POST
Examples See good-executeTestRequest-xxx and good-executeTestResponse-xxx files within executeTest folder in touchstone-api.zip

You should have Test Setups pre-created on the Touchstone UI before launching test executions using Touchstone API. Details on how to do that are covered in the Creating Test Setup section in this guide. It is also 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 Touchstone API.

Retrieve Execution status

This API call takes the id of the test execution in the request URL and returns the test execution status.

URL https://touchstone.aegis.net/touchstone/api/testExecution/[testExecId]
Method GET
Example URL https://touchstone.aegis.net/touchstone/api/testExecution/20160516101258248
Examples See good-testExecStatusRequest-xxx and good-testExecStatusResponse-xxx files within testExecStatus folder in touchstone-api.zip

You do not need to wait between “/api/testExecution” (POST) and “/api/testExecution” (GET) calls. But you do need to wait for 4 seconds between repeated “/api/testExecution” (GET) calls. The response returned from “/api/testExecution” (GET) aligns with a row on the following screen in Touchstone UI:

../_images/api_testexec_status_a1.png

Retrieve 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 test script executions within the test execution.

URL https://touchstone.aegis.net/touchstone/api/testExecDetail/[testExecId]
Method GET
Example URL https://touchstone.aegis.net/touchstone/api/testExecDetail/20160516101258248
Examples See good-testExecDetailRequest-xxx and good-testExecDetailResponse-xxx files within testExecDetail folder in touchstone-api.zip

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 only need to call “/api/testExecDetail” once. The response returned from “/api/testExecDetail” aligns with the following screen in Touchstone UI:

../_images/api_testexec_detail_a1.png

Retrieve Script Exec Detail

This API call takes the id of the test execution in the request URL as well as the name of a test script and returns the script execution details.

URL https://touchstone.aegis.net/touchstone/api/scriptExecDetail/[testExecId]?testscript=[value]
Method GET
Example URL https://touchstone.aegis.net/touchstone/api/scriptExecDetail/20180507121755387?testscript=/FHIR3-2-0-Connectathon17/Patient-02-Formal/FHIRServer/03-PatientRead/connectathon-17-patient-fhirserver-03-read-client-id-json
Examples See good-scriptExecDetaillRequest-xxx and good-scriptExecDetailResponse-xxx files within scriptExecDetail folder in touchstone-api.zip

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 test scripts 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 (i.e. the testExecId and the name of the test script you want to dig deeper into). The response returned from “/api/scriptExecDetail” call aligns with the following screen in Touchstone UI:

../_images/api_scriptexec_detail_a1.png

Pseudo code

You do not need to make “/api/testExecDetail” and “/api/scriptExecDetail” calls when all is well in “/api/testExecution” (GET) response. These calls are available when your test execution has some test script execution errors that you expect (because of current capabilities of the test system) and you want to confirm that the errors are coming from the same scripts. Other uses for “/api/scriptExecDetail” include confirmation of negative assertion results, operation response times, etc. But these are more advanced use cases. You can start out with getting “/api/authenticate” and “/api/testExecution” calls working in your environment before integrating “/api/testExecDetail” and “/api/scriptExecDetail” calls ” if needed.

Here’s some pseudo-code for launching test execution and getting test execution status:

// Authenticate First
AuthenticateResponse authenticateResponse = RestClient.useRelaxedHTTPSValidation()
                                                .headers("Accept: "application/json'")
                                                .url("https://touchstone.aegis.net/touchstone/api/authenticate")
                                                .post("{ "email' : "myOrgCIUser@myOrg.com','password' : "password'}")

// Launch test execution using the API-Key retrieved and a test setup that was pre-created on UI
ExecuteTestResponse executeTestResponse = RestClient.useRelaxedHTTPSValidation()
                                             .headers("API-Key:"+ authenticateResponse.getApiKey()+"Accept: "application/json',
                                                                        Content-Type: "application/json''")
                                             .body("{"testSetup': "MyFavoriteTestSetup'}")
                                             .post("https://touchstone.aegis.net/touchstone/api/testExecution"))

// Retrieve the test execution status in a loop until completion.
TestExecStatusResponse execStatusResponse = RestClient.useRelaxedHTTPSValidation()
                                                      .headers("API-Key: authenticateResponse.getApiKey(), "Accept: "application/json'")
                                                      .get("https://touchstone.aegis.net/touchstone/api/ testExecution/"+
                                                                     executeTestResponse.getTestExecId())

while (execStatusResponse.getStatus()==null or execStatusResponse.getStatus()=="Not Started" or execStatusResponse.getStatus()=="Running") {
   waitFor(4 seconds)
   execStatusResponse = RestClient.useRelaxedHTTPSValidation()
                        .headers("API-Key: authenticateResponse.getApiKey(), "Accept: "application/json'")
                        .get("https://touchstone.aegis.net/touchstone/api/testExecution/"+ executeTestResponse.getTestExecId())
}
assert execStatusResponse.getStatus()=="Passed"

There is a lot more information in the responses. Many more assertions can be performed on the response body and headers. That and the “/api/testExecDetail” and “/api/scriptExecDetail” calls are left as an exercise for the reader. Once you’ve had a chance to look into touchstone-api.zip and get the “/api/authenticate” and “/api/testExecution” calls working in your environment, it should not be difficult to get “/api/testExecDetail” and “/api/scriptExecDetail” calls working as well. They follow the same paradigm.

Retrieve FHIR Test Report

This API call (“/api/testReport”) is available as an alternative to “/api/scriptExecDetail”. It has a subset of information available in “/api/scriptExecDetail” responses. The only advantage of this API is that it returns TestReport which is compliant to the FHIR specification. This API call takes the id of the test execution in the request URL as well as the name of a test script and returns the script execution details.

URL https://touchstone.aegis.net/touchstone/api/testReport/[testExecId]?testscript=[value]
Method GET
Example URL https://touchstone.aegis.net/touchstone/api/testReport/20180507121755387?testscript=/FHIR3-2-0-Connectathon17/Patient-02-Formal/FHIRServer/03-PatientRead/connectathon-17-patient-fhirserver-03-read-client-id-json
Examples See good-testReport-xxx and good-testReport-xxx files within testReport folder in touchstone-api.zip

You do not need to wait between “/api/testExecDetail” and “/api/testReport” calls. But you do need to wait for 4 seconds between repeated “/api/testReport” calls. Repeated “/api/testReport” calls would presumably be for different test scripts within the test execution. You should call “/api/testReport” 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/testReport” call (i.e. the testExecId and the name of the test script you want to dig deeper into). The response returned from “/api/testReport” call aligns with the screen below in Touchstone UI:

If “/api/testReport” call fails because of a bad request, an OperationOutcome response will be returned.

../_images/api_scriptexec_detail_a1.png