Installation Guide

Overview

Your Booking is an online appointment booking system for optometry practices using Optomate Touch. A lightweight agent runs on your practice server and connects securely to the Your Booking platform. No patient data is stored outside your practice.

Prerequisites

• Windows 10/11 or Windows Server 2016+
• Optomate Touch with the Touch API installed (version 2.12.12 or later — 2.12.12 fixes an availability bug that affects online booking)
  • The API is a free download from Monkey Software
  • Which build you need depends on where Optomate runs. The names are counter-intuitive, so check this before downloading:
    • Optomate runs on a server in your practice (the usual case) — download "Optomate Touch Hosted x86 API". Despite the name, this is the build for practice-owned servers — it runs inside Optomate Touch itself.
    • Optomate runs on a hosted or remote server (you connect to it over the internet or via remote desktop, often supplied by Monkey Software) — download the x64 build instead, which runs under IIS. If you're not sure which applies, ask Monkey Software or us before installing.
  • If you have an earlier version installed, download and install the latest version to update
• Internet access (outbound only — no inbound ports or firewall changes required)
• Your practice licence key (provided during onboarding)

Step 1: Optomate Touch Configuration

Before installing the agent, configure Optomate Touch for API access.

1.1 Create API credentials

1. Open Optomate Touch
2. Go to System Settings → API Access tab
3. Click in the Username field, enter a username, then enter a password, an optional description, and then click Add
   • Use a username like YOURBOOKING — this appears as the staff code on appointments created by the booking system
4. Note the username and password — you'll need these during installation

1.2 Configure API access permissions

1. Click Access List next to the new account you created
2. Enable the following resources:

If you plan to use the Recalls & Reminders module (can be enabled later), also add:

1.3 Enable appointment types for online booking

1. Go to Appointment Types in Optomate
2. For every appointment type that relates to an eye examination, tick Available for Online Appointments (you can leave non-examination types like spectacle collections or repairs switched off)
3. Only types with this option enabled will appear in the Your Booking admin for configuration

1.4 Create a patient source (recommended)

1. Go to Patient Settings → Sources
2. Add a new source (e.g. "Online Booking")
3. This tags patients who register through the booking system, making them easy to identify in Optomate

1.5 Verify the API is accessible

Open a browser on the server and navigate to:

http://localhost:12000/OptomateTouch/OData4/Branches

Because the browser doesn't send any login details, you'll get a short "missing credentials" error, like this:

{"error":{"code":"100","message":"Missing Credentials!"}}

This is expected and is exactly the result you want — it confirms the API is running and reachable. You do not need to see your branch details at this step.

If instead the page won't load at all — "can't connect", "connection refused", or it times out — then the API isn't reachable: check that Optomate Touch is running and the API module is installed.

If the page loads but shows a long error message mentioning BranchesController or "the underlying provider failed on Open", the API is installed and running correctly but can't reach the Optomate database. There are two possible causes.

First, the quick one. In Services, find the entry starting with SQL Server and make sure it is Running, with Startup Type set to Automatic. A recent restart can leave it stopped. If that wasn't it, read on.

Second, a known bug in the Optomate API installer. This one is not something you've done wrong. The installer writes a configuration file that leaves out the name of the database instance, so the API has no way to find your Optomate data. It's a one-line correction, and you have three ways to get it done:

• Ask Monkey Software. It's their installer and they'll recognise the problem immediately — usually a few minutes' work for their support team.
• Ask us. Send through a photo of the Data Source= line described below and we'll tell you exactly what it should say, or we can walk through it with you on a screen-share.
• Do it yourself, if you're comfortable editing a configuration file:
  1. Open the folder C:\Optomate Touch\Optomate API Host Service. Find the Optomate API program file (the application), then look for the file with exactly the same name plus .config on the end — that's the one you want. On the small number of servers where the API runs under IIS, the file is C:\Optomate Touch\Optomate Touch API\web.config instead. Open it in Notepad — run Notepad as Administrator first (right-click → Run as administrator), or it won't let you save.
  2. Find out what your database instance is actually called before changing anything: open Services and look at the entry starting with SQL Server — the name is shown in brackets after it, for example SQL Server (SQLEXPRESS).
  3. Find the <connectionStrings> section and look for Data Source=. It should read localhost\ followed by the instance name from the previous step — most often localhost\SQLEXPRESS. Two versions of this are commonly wrong:
     • Just localhost, with no instance name — add the one you found.
     • A computer name, such as DESKTOP-12AB34C\SQLEXPRESS — replace the computer name with localhost, keeping the part after the backslash.
  4. Save the file, then restart the API: open Services, find Optomate API Service, and choose Restart. Reload the address above. (On the small number of servers where the API runs under IIS instead, run iisreset from an Administrator Command Prompt.)

A note on the Your Booking status showing Offline: the agent won't connect to us until it can talk to Optomate, so an Offline status alongside a healthy-looking agent service almost always points at Optomate rather than at the agent.

Once the check above succeeds, restart the agent: open Services, find YourBookingAgent, and choose Restart. The status should turn green within a minute. You don't need to reinstall anything.

Step 2: Install the Agent

2.1 Download and run the installer

Download the installer from:

https://yourbooking.au/downloads/YourBookingAgent-Setup.exe

Run it on the practice server.

2.2 Choose install location

The default location is C:\Program Files\YourBookingAgent. You can change this if needed.

2.3 Enter practice details

The installer will prompt for:

2.4 Complete installation

The installer will:

• Copy all required files
• Create a Windows service (YourBookingAgent) that starts automatically on boot
• Start the agent and connect to the Your Booking platform

Step 3: Verify

Open your practice's booking page (e.g. yourpractice.yourbooking.au) in a browser.

• The page should load with your practice's branding.
• In the top-right corner of the header you should see a green dot and the word Online. This confirms the agent is connected to the Your Booking platform. If it says Offline (red dot), the agent isn't reaching the server — check the agent service is running and try restarting it.
• The body of the page will say "Online booking is currently unavailable". This is expected on a fresh install — online booking is off by default so you can finish configuring the system before patients can see it. You'll turn it on in Step 4.

Step 4: Set Up Your Booking

Once the agent is installed and connected, follow the Setup Guide to configure the booking system. This covers:

• Logging in to the admin dashboard
• Syncing appointment types from Optomate
• Configuring which appointment types are available for online booking
• Setting up optometrists, booking rules, and practice settings
• Enabling online booking when you're ready to go live

Online booking is off by default, so you can take your time configuring everything before patients can see the booking page.

Optional: send patient emails from your own address

By default, patient emails (booking confirmations, reminders, recalls, follow-ups) come from bookings@yourbooking.au with your reception address as the reply-to. To have them come from your own address instead — either by adding DNS records to your domain, which needs no password, or by sending through your own Gmail or Outlook account — see the Practice Branded Email guide.

Step 5: Add to Your Website

To embed the booking page on your website, see the Website Integration Guide. It covers the iframe embed code, configuring email links, and optional redirect rules for SMS/recall links.

In-store kiosk (iPad)

Set up a tablet in the waiting room so patients can book themselves when staff are busy.

1. Open https://yourpractice.yourbooking.au/?kiosk in Safari on the iPad
2. Tap Share (square with arrow) then Add to Home Screen
3. Name it (e.g. "Book Appointment") and tap Add

The app launches full-screen with no browser chrome. It shows a welcome screen with the practice logo and a "Book an Appointment" button. After a booking completes or 2 minutes of inactivity, it resets back to the welcome screen for the next patient.

iPad setup for shared use:

Disable autofill so patients don't see each other's saved information:

• Settings > Passwords > AutoFill Passwords — turn off
• Settings > General > AutoFill — turn off Contact Info and Credit Cards

Add to phone home screen

Patients can add the booking page to their own phone's home screen by visiting https://yourpractice.yourbooking.au/ directly and choosing "Add to Home Screen". This gives them a branded app icon and a full-screen booking experience. If you've uploaded a square icon in Branding → Square icon, that's used for the home-screen icon — otherwise your main logo is used (which may look cropped on square icon slots).

Patients who visit the booking page via your own website (the embedded iframe) need the additional manifest setup described in the Website Integration Guide → Step 4: Add to Home Screen to get the same experience.

Firewall

The agent only makes outbound connections. No inbound firewall rules or port forwarding are required.

If your network has outbound filtering, ensure the server can reach:

• yourbooking.au on port 443 (HTTPS/WSS)

Changing Configuration

To change the Optomate API credentials or other settings:

1. Edit the .env file in the install directory (e.g. C:\Program Files\YourBookingAgent\.env)
2. Restart the service using one of:
   • Windows Services: open services.msc, find "Your Booking Agent", right-click → Restart
   • Command line: open a command prompt as Administrator in the install directory and run winsw restart

Logs

Agent logs are at logs\winsw.err.log in the install directory. To view:

type "C:\Program Files\YourBookingAgent\logs\winsw.err.log"

Log files rotate automatically at 5MB.

Service Management

The agent runs as a Windows service called YourBookingAgent. You can manage it from the Windows Services console (services.msc) or from the command line:

winsw start
winsw stop
winsw restart
winsw status

Run these from the install directory (e.g. C:\Program Files\YourBookingAgent).

Uninstalling

Use Add or Remove Programs in Windows Settings, or run the uninstaller from the Start Menu. This stops the service, removes it from Windows, and deletes all installed files.

Troubleshooting

Agent won't start

• Check logs: type "C:\Program Files\YourBookingAgent\logs\winsw.err.log"
• Verify the .env file has all required values
• Check the Windows service status in services.msc

"Optomate authentication failed"

• Verify the username and password in .env match what you configured in Optomate's API Access settings
• Ensure the API access list has the required permissions (Step 1.2)

"Cannot reach Optomate"

• Check Optomate Touch is running
• Verify the API is reachable: open http://localhost:12000/OptomateTouch/OData4/Branches in a browser on the server — a Missing Credentials! error means it's reachable and running; "can't connect" or a timeout means it isn't
• If Optomate is on a different machine, use that machine's IP in the API URL

Booking page shows "agent offline"

• Check the service is running: winsw status (from install directory) or check Windows Services
• Check the logs for connection errors
• Verify internet connectivity from the server

Booking shows "temporarily unavailable"

• The agent is not connected. Check the service is running and review the logs.
• If the agent connects but disconnects quickly, check that no other agent is using the same licence key.