Installing and running the PATCHS SystmOne Agent on your TPP Gateway Machine

How the SystmOne Integration works

Most of PATCHS is accessed entirely through the browser, with no installation required. Integration with SystmOne, however, requires a small application, called an 'agent', to be installed and run on the TPP Gateway machine for your practice. The agent allows the PATCHS servers to communicate with your SystmOne instance, which enables your practice to match patients and save PATCHS requests to SystmOne.

Setting up the integration

1. [Administrator access required] Install the PATCHS SystmOne Agent software on the TPP Gateway machine

Often this step will have already been done by your IT team. If you have a desktop shortcut called 'PATCHS SystmOne Agent' on your Gateway machine's desktop then you already have the agent installed and can proceed to Step 2

  1. Log into your gateway machine as the TPP user (this is the Windows user that you use to run SystmOne). It often has a name like 'TPP.[your practice code]'
  2. Check that you do not already have the agent installed. Look for a shortcut called 'PATCHS SystmOne Agent' on your desktop:
    If you already have this shortcut you can skip straight to '2. Set up your practice on PATCHS' below
  3. Download the agent software from
  4. Install the agent software
  5. Ensure that any firewalls are set up to allow outgoing connections to * on port 443
  6. Ensure any antivirus software is set to allow the agent software (if it doesn't already)

2. Set up your practice on PATCHS

If you haven't already done so, use the links sent to you during your onboarding process to set up your practice on PATCHS. See the other articles in this section for further information on this.

3. Download the SystmOne configuration file

  1. Log into your gateway machine as the TPP user (this is the Windows user that you use to run SystmOne). It often has a name like 'TPP.[your practice code]'
  2. Log in to PATCHS, and visit the Practice Details page (see Practice Details for more information)
  3. Click on the 'TPP Installation' tab
  4. Under the 'TPP Gateway Machine Config' section, click the 'Generate new config file' button
  5. In the window that pops up, enter the username of the TPP user on the gateway machine. This is the user you logged in as in step 1
  6. Click 'Generate'. This will download a configuration file called 'agent.yml' to your Downloads folder.
  7. a) If you use a generic windows user on your Gateway machine Move this file to the user's home folder (C:\Users\[username of generic user]\agent.yml)
    b) If you do not use a generic windows user on your Gateway machine Ask your IT support desk to move the file to C:\Program Files\PATCHS\agent.yml (requires Admin permissions)

4. Set the SystmOne Agent to run on login

  1. Find 'PATCHS SystmOne Agent' on your desktop, right-click it and select Copy

  2. With the file location open, press the Windows logo key  + R, type shell:startup, then select OK. This opens the Startup folder.

  3. Right click in the Startup folder and select Paste

5. Start the agent software

  1. The agent software will start on login, but if it doesn't start you can start it manually by searching 'PATCHS SystmOne Agent' in the Windows search bar.
  2. If everything is working the software will show a black window which says "Listening for requests...", like the screenshot below
  3. You can now minimise this window. It will run in the background, and must be kept running for the SystmOne integration to work.

6. Ensure the user logged in to SystmOne has the correct Local Access Rights

  1. All users who log in to the Gateway machine need to have Local Access Rights in SystmOne to 'Retrieves Patients' and 'Saves Records'. To check this, please see the video below:

7. Make a test request and approve the PATCHS connection

  1. On PATCHS, register an example patient (the patient does not need to exist in your clinical system)
  2. Log in to your TPP Gateway machine and go to SystmOne. SystmOne will ask you to approve the connection with PATCHS. You must approve the connection for the integration to work.
  3. Register a second example patient (again, the patient does not need to exist in your clinical system). Find the patient in PATCHS. It should show a message saying 'Patient not found' - this shows that the system is working correctly.

Best Practices and Troubleshooting

  • For PATCHS to work with SystmOne correctly, the SystmOne Agent software must be running at all times. The Windows user running the SystmOne Agent should be left logged in (can be locked). If another user needs to log in to the TPP Gateway, they should use 'Switch User'.
  • The first time PATCHS interacts with SystmOne, a popup will appear in SystmOne on the Gateway machine asking to approve PATCHS. Access must be approved for the integration to work.
  • The user logged into SystmOne on the gateway machine must have must have access to ‘Retrieves patients’ and ‘Saves records’ in the ‘Local Access Rights’ setting in SystmOne

  • The SystmOne integration will not pick up patients that are marked as 'test' in SystmOne - these patients will show as 'Not Found'