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 recommend 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_a3.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.

For target test systems that are configured to use OAuth2 tokens, you can refer to the OAuth2 Static Token and OAuth2 Grant Flow sections for details.

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=/FHIR4-0-1-Basic/A-C/Account/Client Assigned Id/Account-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=/FHIR4-0-1-Basic/A-C/Account/Client Assigned Id/Account-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

OAuth2 Static Token

Destination test systems can be configured to support OAuth2 with static OAuth2 tokens:

../_images/oauth2-static-testsystem-a1.png

Touchstone API allows the token that has been configured on Test Setup (on the UI) for such test systems to be overwritten as part of the API call.

URL

https://touchstone.aegis.net/touchstone/api/testExecution

Method

POST

Examples

See good-oauth2TokenexecuteTestRequest-xxx and good-oauth2TokenexecuteTestResponse-xxx files
within executeTest folder in touchstone-api.zip

As detailed in ExecuteTestRequest, the request payload would normally have the TestSetup name to execute:

{
  "testSetup" : "FHIR4-0-1-Basic-P-R-Patient-Client Assigned Id--All"
}

To specify the static OAuth2 token for the destination test system as part of the ExecuteTestRequest, the token would be specified along with the full name of the test system:

{
  "testSetup" : "FHIR4-0-1-Basic-P-R-Patient-Client Assigned Id--All",
  "destOAuth2Tokens" : [
    {
      "dest" : "Org1-TestSystemA",
      "token" : "token1"
    },
    {
      "dest" : "Org1-TestSystemB",
      "token" : "token2"
    },
    {
      "dest" : "Org1-TestSystemC",
      "token" : "token3"
    }
  ]
}

In the example above, we have three separate destination test systems. In most cases, there will only be one destination involved. The number of destinations is specified in the test script.

The dest value would be [Organization]-[Test System] from Test Systems where [Organization] is the value under Organization column and [Test System] is the value under Test System column. The token value would be the current OAuth2 token for the target test system.

OAuth2 Grant Flow

This section pertains to operation calls that require OAuth2 Authorization for test system servers configured with Dynamic OAuth2:

../_images/oauth2-dynamic-testsystem-a1.png

When test execution reaches such an operation, the status changes to OAuth2-Authorize and a popup is displayed on the UI requiring the user to take action:

../_images/oauth2-authorization_a3.png

This section covers how to successfully get past this operation using REST APIs.

In the popup above, the user is required to either cancel or continue to the OAuth2-Authorize URL displayed in the popup. This URL is now returned in the API responses from Touchstone when the test execution has reached OAuth2-Authorize status. The oauth2AuthzUrl element value in GET “/api/testExecution”, “/api/testExecDetail”, and “/api/scriptExecDetail” responses will be identical to the OAuth2-Authorize URL value in the popup above.

There are two ways of resuming the test execution using the APIs:

  1. Test execution can be launched with oauth2AuthzApiRedirected absent or specified as false in the payload of “/api/testExecution” (POST) request:

{
  "testSetup" : "FHIRSandbox--security-fhir-r4-standalone-launch-patient",
  "oauth2AuthzApiRedirected": false
}

This will require the client to grab the oauth2AuthzUrl value from the response to “/api/testExecution” (GET) call and use that in automated browser (e.g. Selenium) to hit the test system’s OAuth2 server and authorize the requested scopes. The end of that process will result in browser redirecting to Touchstone’s OAuth2 Redirect URL. This mechanism will require the automated browser (e.g. Selenium) to enter credentials in the Touchstone Login screen (after being redirected) to resume the test execution in Touchstone.

Note that no additional API calls are needed with this mechanism to resume the test execution. The downside is that the client’s Selenium browser will need to interact with Touchstone UI (in addition to the test system’s OAuth2 server).

  1. Alternatively, Test execution can be launched with oauth2AuthzApiRedirected specified as true in the payload of “/api/testExecution” (POST) request:

{
  "testSetup" : "FHIRSandbox--security-fhir-r4-standalone-launch-patient",
  "oauth2AuthzApiRedirected": true
}

This will again require the client to grab the oauth2AuthzUrl value from the response to “/api/testExecution” (GET) call and use that in automated browser (e.g. Selenium) to hit the test system’s OAuth2 server and authorize the requested scopes. The end of that process will again result in browser redirecting to Touchstone’s OAuth2 Redirect URL. But this time, the browser will not be redirected to the Login screen. It will instead stay on the Redirect URL in the browser to allow the automated test software to grab the content of the OAuth2-Authorize Redirect URL. This URL will contain data that will be needed to resume the test execution.

The OAuth2-Authorize Redirect URL obtained from previous step has to be provided in payload of request to a new API endpoint:

URL

https://touchstone.aegis.net/touchstone/api/oauth2grant

Method

POST

Payload

{ “oauth2RedirectUrl” : “[the redirect url in browser after OAuth2 grant]”}

Test execution should resume after that and GET “/api/testExecution” can be called as usual to get the status of the test execution.