The TKW (ToolKit Workbench) Simulators are tools to assist with developing and assuring a solution to meet the Booking Standard. There are two tools in the suite, to support the Provider and Consumer functionality, and they can utilised locally or in the dedicated environments – OpenTest or INT. When utlised within the dedicated environments they are supported by the other services – DoS, SDS and SSP – to replicate as near to like-live scenarios as possible.

What are they?

Fundamentally, the TKW Simulators are (Docker) containers which neatly package all required resources, irrespective of the environment they are run on. There are two containers (Provider and Consumer) to replicate the different aspects of functionality and links to each of them can be found under the Resources section below.

Resources

Resources required to understand and run the TKW Simulators

Docker

Docker download

TKW Simulators Downloads

Deploying

When starting to build a solution the TKW Simulators can be deployed locally, to validate the requests and responses made by either Providers or Consumers. This section will explain how to deploy and later sections will go on to explain how to use the tool.

Windows

Click to see step-by-step setup guide

Prerequisites

Download Containers

  • Launch Powershell (local user)
  • Run the following to download the Container(s)
    • Provider - docker pull nhsdigitalmait/tkw_uec_provider_simulator
    • Consumer - docker pull nhsdigitalmait/tkw_uec_consumer_simulator

Run Containers

  • Create Docker compose (.yml) files to instantiate the Containers

  • Provider
    • Copy ‘docker-compose_provider_simulator.yml’ from here
    • Update volume references to local resources – see Appendix1
      • NB: The section after the colon (:) should not be altered because this is used by the Container
    • Save file
    • Run the following from Powershell – docker-compose -f docker-compose_provider_simulator.yml up
    • The Provider Simulator will start and report ‘ITK Testbench ready’ when successfully running
  • Consumer
    • Copy ‘docker-compose_consumer_simulator.yml’ from here
    • Update volume references to local resources – see Appendix2
      • NB: The section after the colon (:) should not be altered because this is used by the Container
    • Save file
    • Go to folder location ….Config/FHIR_111_UEC/autotest_config/endpoint_configs
    • Create an endpoint config file named ‘200000000359.sh’, with 200000000359 being the ASID of the test service, and amend the required configuration (only to_ep for a local install), see Appendix6
    • Save the 200000000359.sh file
    • Create batch file ‘run_consumer_test.cmd’ to instantiate the Container and run the various Consumer test routines – see Appendix3 for an example
    • Run Command
    • Call the batch file specifying the test routine required
      • run_consumer_test.cmd <ASID> <Routine>
      • See further detail in the Using TKW section below
    • Once execution is complete check the auto_tests folder and autotest logs folders for the test results and logs

Mac

Click to see step-by-step setup guide

Prerequisites

Download Containers

  • Launch Terminal
  • Download Container(s)
    • Provider - docker pull nhsdigitalmait/tkw_uec_provider_simulator
    • Consumer - docker pull nhsdigitalmait/tkw_uec_consumer_simulator

Run Containers

  • Create Docker compose (.yml) files to instantiate the Containers

  • Provider
    • Copy ‘docker-compose_provider_simulator.yml’ and ‘run_provider_simulator.sh’ from here
    • Now edit docker-compose_provider_simulator.yml
    • The section under ‘volumes’ requires amending such that the folder locations preceding the colon (:) refer to folders on the machine running the Docker Container, see Appendix4
      • NB: The section after the colon (:) should not be altered because this is used by the Container
    • Save docker-compose_provider_simulator.yml
    • Open a Terminal session
    • Execute run_provider_simulator.sh
    • The provider simulator container will now launch in Docker
    • The Provider Simulator will start and report ‘ITK Testbench ready’ when successfully running
  • Consumer
    • Copy ‘docker-compose_consumer_simulator.yml’ and ‘run_consumer_simulator.sh’ from here
    • Now edit docker-compose_consumer_simulator.yml
    • The section under ‘volumes’ requires amending such that the folder locations preceding the colon (:) refer to folders on the machine running the Docker Container, see Appendix5.
      • NB: The section after the colon (:) should not be altered because this is used by the Container
    • Go to …Config/FHIR_111_UEC/autotest_config/endpoint_configs
    • Create an endpoint config file named ‘200000000359.sh’, with 200000000359 being the ASID of the test service, and amend the required configuration (only to_ep for a local install) see Appendix6
    • Save the 200000000359.sh
    • Open a Terminal session
    • Execute run_consumer_simulator.sh file specifying the test routine required
      • run_consumer_test.sh <ASID> <Routine>
      • See further detail in the Using TKW section below
    • Once execution is complete check the auto_tests folder and autotest logs folders for the test results and logs

Using TKW Simulators

The TKW Provider and Consumer Simulators will interact with each. It is advisable to set them up like that initially to ensure they’re working before proceeding to use them to test any other implementation.

The TKW Simulators can be run locally or within the dedicated Path-to-Live environments (OpenTest, INT). You will need to register via a Portal (See Appendix8) to utilise their functionality in these environments. An additional benefit of utilising the TKW tools in this way is the ability to prove end-to-end functionality with the core infrastructure components (SDS and SSP).

This section will further explain how the tools are intended to be used and their functionality.

Consumer

The TKW Consumer Simulator will test a Provider endpoint and is capable of running in three modes –

  • All test suites (see Test Suites section below)
    • e.g. ./run_consumer_simulator.sh <toAsid>
  • Single test suite (see Test Suites section below)
    • e.g. ./run_consumer_simulator.sh <toAsid> [A S B C]
  • Single test within a test suite (see Appendix7 for individual test names)
    • e.g. ./run_consumer_simulator.sh -s <toAsid> <TestName>

The simulator is instantiated by running either a batch (Windows) or shell (Mac) file, the mode being defined by the parameters assigned. It will perform the requested tests and output a validation report for review under ‘..\auto_tests\<ASID>'.

There are logs of activity of the Consumer Simulator under ‘..\autotest_logs’.

NB: To point the TKW Consumer Simulator at the Provider solution to be tested edit the <ASID>.sh file in the ..\endpoint_configs folder, editing the ‘to_ep=<provider solution endpoint>’ value.

Test Suites

To run a single test suite, use the Initial value when invoking the Consumer Simulator.

Initial Test Suite
A cApability
S Search for free slots
B Book appointment
C Cancel appointment

Provider

The TKW Provider Simulator is capable of testing a Consumer solution. As with any Provider system solution, it is passive and waits to accept requests.

Once the container is up and running, reporting ‘ITK Testbench ready’, requests can be sent to it. The supplier’s Consumer solution can be directed to the Provider Simulator, based on the address it was configured to listen via the Docker compose file - docker-compose_provider_simulator.yml.

The Provider Simulator can also be tested using an API Test Tool such as Postman. A collection of all the requests which can be made to the Provider Simulator have been documented and can be imported into the Postman tool to assist seeing what the requests contain and envisage the eventual workflows.

A validation report of activity sent to the Provider Simulator resides under ‘..\all_evidence\<ASID>’ and logs of activity is recorded in ‘..\logs’.

Support

For any issues or assistance with the TKW Simulators you can contact the Team

Assuring with TKW

Another key feature of the TKW Simulator Tools is to assist with the self assurance process and provide the required evidence for the SCAL submission. Once the solution is complete, depending on whether it is fulfilling Provider or Consumer functionality, it can be configured to make or receive requests from the corresponding Simulator Tool. The Tool will record and collate the necessary evidence to be attached as part of the assurance process, as detailed in Using TKW Simulators section above.

Appendices

Click to expand appendices

Appendix1 – Docker Compose file for Provider Simulator (Windows)

version: '2.0'
services:
tkw_uec_provider_simulator:
    ports:
        - '4434:4434'
    volumes:
        - 'C:/Users/xxx/AppData/Local/Temp/assurance/scratch/data:/home/service/data'
        - 'C:/Users/xxx/AppData/Local/Temp/assurance/scratch:/home/service/fhir'
    image: 'nhsdigitalmait/tkw_uec_provider_simulator:0.5'

Appendix2 – Docker Compose file for Consumer Simulator (Windows)

#
#  docker-compose file supporting a docker stack comprised of a 
#  111_uec consumer simulator suite instance 
#
version: "3"
services:
tkw_uec_consumer_simulator:
image: nhsdigitalmait/tkw_uec_consumer_simulator:0.5

environment:
  - TZ=Europe/London

network_mode : "host"

volumes:
    # <host path to mount> : <mount point within docker>
    # auto_tests folder
    - 'C:/Users/xxx/AppData/Local/Temp/config/FHIR_111_UEC/autotest_config/auto_tests:/home/service/TKW/config/FHIR_111_UEC/autotest_config/auto_tests'
    # endpoint_configs folder
    - 'C:/Users/xxx/AppData/Local/Temp/config/FHIR_111_UEC/autotest_config/endpoint_configs:/home/service/TKW/config/FHIR_111_UEC/autotest_config/endpoint_configs'
    # autotest logs folder
    - 'C:/Users/xxx/AppData/Local/Temp/config/FHIR_111_UEC/autotest_config/autotest_logs:/home/service/TKW/config/FHIR_111_UEC/autotest_config/autotest_logs'

Appendix3 – Batch file to instantiate the Consumer Simulator

REM 
REM invokes execution of tkw_uec_consumer_simulator in autotest mode to test Emeregncy Booking providers 
REM 
docker-compose -f docker-compose_consumer.yml run --rm tkw_uec_consumer_simulator %*

Appendix4 – Docker Compose file for Provider Simulator (Mac)

version: '2.0'
services:
tkw_uec_provider_simulator:
    ports:
        	- '4434:4434'
    volumes:
	- '/Users/xxx/Work/NHS-D/UEC/Testing/Data:/home/service/data'
	- '/Users/xxx/Work/NHS-D/UEC/Testing/Data:/home/service/fhir'
    image: 'nhsdigitalmait/tkw_uec_provider_simulator:0.5'

Appendix5 – Docker Compose file for Consumer Simulator (Mac)

#
#  docker-compose file supporting a docker stack comprised of a 
#  111_uec consumer simulator (provider test suite) instance 
#
version: "3"
services:
  tkw_uec_consumer_simulator:
  image: nhsdigitalmait/tkw_uec_consumer_simulator:0.5

environment:
  - TZ=Europe/London

network_mode : "host"

volumes:
# <host path to mount> : <mount point within docker>
# auto_tests folder
- /Users/xxx/Work/NHS-D/UEC/Testing/Config/FHIR_111_UEC/autotest_config/auto_tests:/home/service/TKW/config/FHIR_111_UEC/autotest_config/auto_tests
# endpoint_configs folder
- /Users/xxx/Work/NHS-D/UEC/Testing/Config/FHIR_111_UEC/autotest_config/endpoint_configs:/home/service/TKW/config/FHIR_111_UEC/autotest_config/endpoint_configs
# autotest logs folder
- /Users/xxx/Work/NHS-D/UEC/Testing/Config/FHIR_111_UEC/autotest_config/autotest_logs:/home/service/TKW/config/FHIR_111_UEC/autotest_config/autotest_logs

Appendix6 - Endpoint configuration file example (default)

# Autotest endpoint config file
#
# to local clear
to_ep=http://localhost:4434/STU3
#to_ep=http://localhost/STU3

# to local secure
#to_ep=https://localhost:4431/STU3
# to local via reverse proxy
#to_ep=http://192.168.1.112/STU3 

# defaults
#toasid=200000000359
#fromasid=200000000359
#sendtls=No
#truststore=/TKW_ROOT/config/FHIR_111_UEC/autotest_config/endpoint_configs/certs/opentest.jks
#keystore=/TKW_ROOT/config/FHIR_111_UEC/autotest_config/endpoint_configs/certs/vpn-client-1003.opentest.hscic.gov.uk.jks

Appendix7 - Single Consumer Tests

Test Name Test Group Short Description
Capability_xml_accept Capability Request capability statement with a fhir+xml accept http header
Capability_json_accept Capability Request capability statement with a fhir+json accept http header
Capability_xml_parameter Capability Request capability statement with a xml _format parameter
Capability_json_parameter Capability Request capability statement with a json _format parameter
Capability_xml_parameter_json_accept Capability Request capability statement with xml _format parameter and a fhir+json accept http header
Capability_json_parameter_xml_accept Capability Request capability statement with json _format parameter and a fhir+xml accept http header
Capability_xml_accept_gzip Capability Request capability statement requiring a gzipped response
SFFSWithValidParameters_parameter_json Search For Free Slots Search for free slots with a json _format parameter
SFFSWithValidParameters_header_json Search For Free Slots Search for free slots with a fhir+json http accept header
SFFSWithValidParameters_parameter_xml Search For Free Slots Search for free slots with a xml _format parameter
SFFSWithValidParameters_header_xml Search For Free Slots Search for free slots with a fhir+xml http accept header
SFFSWithValidParameters_JWT_NoPractitioner Search For Free Slots Search for free slots with a JWT that does not contain a practitioner claim element
SFFSWithValidParameters_3_days Search For Free Slots Search for free slots with a three day window from tomorrow to tomorrow+2
SFFSWithValidParameters_includes Search For Free Slots Search for free slots with added _include parameters
SFFSWithValidParameters_includes_slots_only Search For Free Slots Search for free slots with added _include parameters response returning slots only
SFFSNoSlots_HappyPath Search For Free Slots Search for free slots returning no slots
SFFSInvalid Search For Free Slots Search for free slots using an invalid request
SFFSForbidden Search For Free Slots Search for free slots forbidden repsonse
SFFSWrongMethod Search For Free Slots Search for free slots wrong method response
SFFSWithBusySlots Search For Free Slots Search for busy slots
SFFSWithNoIncludes Search For Free Slots Search for slots with no _include parameters
SFFSWithNoIncludesSlotsOnly Search For Free Slots Search for slots with no _include parameters response returning slots only
SFFSWithFreeSlotsWithRevIncludes Search For Free Slots Search for free slots with a full set of _include and _revInclude
SFFSWithFreeSlotsWithGzipEncoding Search For Free Slots Search for free slots requiring a gzipped response
BookAppointment_HappyPath Book Appointment Happy Path Appointment booking
BookAppointment_NoNHSNumber Book Appointment Happy Path Appointment booking where no patient nhs number is supplied
BookAppointment_SlotAlreadyBooked Book Appointment Attempt to book an already booked appointment
BookAppointment_FailedValidation Book Appointment Book an apppintment with an invalid request
BookAppointment_Invalid Book Appointment Book an apppintment with an invalid request
BookAppointment_Forbidden Book Appointment Book appointment forbidden response
BookAppointment_ServerError Book Appointment Book appointment server error response
BookAppointment_UnsupportedMediaType Book Appointment Book appointment requesting an unsupported media type
BookAppointment_BadGateway Book Appointment Book appointment bad gateway response
BookAppointment_TelecomAndContact Book Appointment Book appointment with a rank 1 telecom of type phone in patient and rank2 in contact
BookAppointment_Contact Book Appointment Book appointment with a rank 1 telecom of type phone in contact
BookAppointment_TwoRank1 Book Appointment Book appointment with a rank 1 telecom of type phone in patient and rank1 in contact
BookAppointment_TwoRank2 Book Appointment Book appointment with a rank 2 telecom of type phone in patient and rank 2 in contact
BookAppointment_HappyPathWithGzip Book Appointment Book appointment with both request and response gzipped
BookAppointment_HappyPathWithResentRequestID Book Appointment Book appointment then rebook with the same request id
ReadNonExistentAppointment Cancel Appointment Read an appointment that does not exist
CancelAppointment_HappyPath Cancel Appointment Successfully cancel an appointment
CancelAppointment_DifferencesDetected Cancel Appointment Attempt to cancel an appointment supplying different appointment details
CancelAppointment_VersionConflict Cancel Appointment Attempt to cancel an appointment supplying incorrect version
CancelAppointment_If-MatchHeaderMissing Cancel Appointment Attempt to cancel an appointment without supplying an if match http header
CancelAppointment_ServerError Cancel Appointment Cancel appointment server error response
CancelAppointment_Forbidden Cancel Appointment Cancel appointment forbidden response
CancelAppointment_BadGateway Cancel Appointment Cancel appointment bad gateway response
CancelAppointment_GatewayTimeout Cancel Appointment Cancel appointment gateway timeout response

Appendix8 - Using TKW Portal on the INT environment

Registering

Navigate to Portal - http://itw-work.itblab.nic.cfh.nhs.uk/Account/Register.aspx(HSCN access required)

Login with the following credentials - Username = admin Password = uecbooking

Fill out the registration form and click ‘Register’

NB: You will need to have registered your endpoint on INT and been provided with an ASID - See Path-to-Live

Testing your Consumer/Sender

Contact the Booking and Referrals Team for the configured DoS endpoint.

Testing your Provider/Receiver

Login with your newly created credentials -

You will be presented with the following options

This Portal will allow you to send tests directly to your API

Click ‘Consumer Simulator’ and you will be presented with a list of tests for different areas of functionality i.e. Search for Slots, Booking, etc. Ensure that the ‘Provider ASID’ (indicated at the top of the screen) is the one configured to direct traffic to your endpoint.

Tick the box next to the tests you wish to perform or the ‘Select All..’ for all test for an area of functionality or all tests available (top option ‘Select All Tests’)

Click ‘Run Consumer Simulator’ at the bottom of the page

When complete, the following dialog will display

The Test and Validation Report can be viewed and downloaded under the ‘Download Reports’ menu option

Viewing Reports

Consumer Reports (for reports run against a Provider/Receiver solution from the TKW Test Tool)

Provider Reports (for reports run against the TKW Provider/Receiver Test Tool from a Consumer)

Subscribing for Reports

The Portal will also email reports directly to the email address used when registering. Tick the box to subscribe to this feature.