Getting started with Halo Cloud

This page outlines how to get started with Halo Cloud in general. Details of how to use specific products can be found under their respective docs pages.

Environments

Halo Connect has both production and staging environments for all products - Halo Link, Halo Cloud, docs, and API references.

	Production	Stage
Usage	Connects to live practice databases, and should only be used with production quality code.	Designed for development and testing, and receives updates before production so that integrators can test new features and bug fixes early.
API Base URL	https://api.haloconnect.io	https://api.stage.haloconnect.io
Docs URL	https://docs.haloconnect.io	https://docs.stage.haloconnect.io

To successfully connect to an environment, you will need for that environment:

• A Halo Connect subscription key
• The Halo Cloud API base URL
• A Halo Link instance that connects to a supported PMS database

Production subscription keys can not be used with staging Link instances and vice versa.

Installing Halo Link in Stage requires an extra step compared to production

Please see the Halo Link installation instructions for integrators for more information about setting Halo Link to Stage.

This is particularly important for any PMS which bundles Halo Link, which will install Halo Link in production by default. It is best to set Link to Stage before installing Halo Link or any PMS software.

Moving from staging to production

When your product is ready to rollout in production, please reach out to the Halo Connect team. There are a few steps to the process, including:

• Finalising the commercial agreement for a production subscription
• Analysis of your planned API usage, to ensure provisioning
• If possible, a beta test of your integration running as it would in production for at least one day on one practice server, to ensure all factors have been accounted for
• Coordination of a rollout strategy, to ensure both parties can manage and monitor the rollout over time

Depending on which PMS you are integrating with, they may also have requirements when moving from staging to production. Please check with the PMS provider regarding production requirements.

Query routing

Halo Cloud routes queries to specific practices based on the Halo GUID included in the request URI.

A Halo GUID is not the same as a practice's PMS ID, though the two are linked. Practices tend to be more aware of what their PMS ID is though, so the Get Halo GUIDs endpoint allows integrators to trade PMS IDs for Halo GUIDs.

See Working with Halo GUIDs for more information.

Connecting to Halo Cloud

Integrator API

Prerequisites

To get started with the Integrator API, you will need:

• Your Halo Connect subscription key
• A server running:
  • A supported PMS database which has:
    • The appropriate database credentials set up
    • If required, your integration enabled in the database and/or UI
  • An instance of Halo Link
• A way to send HTTP requests
  • For testing, a program like Postman or Insomnia is fine

Secure your Halo Connect subscription key

Please ensure your Halo Connect subscription key is kept secret. It should be stored in a secure manner, and only shared within your organisation as needed. Halo Connect staff will never ask for your subscription key.

If you think your subscription key has been compromised, please contact us immediately so we can enact security precautions and mitigate any potential risks.

You will also need to fetch the Halo GUID associated with your PMS database. See Working with Halo GUIDs below for how to do this.

Authentication

To authenticate with the Integrator API, include your subscription key in your request as a header with the name Ocp-Apim-Subscription-Key.

The Desktop API has its own authentication mechanism which is setup using the Integrator API.

Test queries

To test your connection to Halo Cloud, you could:

• Query the Get site status endpoint, to check the status of your Halo Link instance. In staging, use the URL https://api.stage.haloconnect.io/integrator/sites/{haloGUID} and substitute the Halo GUID of your test site for {haloGUID}.
• Try one of the SQL Passthrough API query examples.
• Try one of the FHIR API query examples.

For testing, programs such as Postman or Insomnia are perfectly suitable for querying Halo Cloud.

Desktop API

Prerequisites

Integrators will need the following in order to use the Desktop API:

• An application that is installed on machines or devices other than the practice server which have the ability to query Halo Cloud. This is usually practice desktops.
• A secure mechanism for authenticating application users and/or desktop application instances.
  • Please contact Support for further recommendations.
• A cloud presence capable of fetching, forwarding, and renewing Desktop API authorization tokens via the Integrator API.
• The ability to implement a token renewal workflow which, depending on use case, may involve either:
  • Renewing tokens when they expire and an error is thrown, or
  • Pre-emptively renewing tokens ahead of expiry to prevent service disruptions.
• A Halo Cloud subscription.
• A connection to the Integrator API (for auth).
• Approval from the relevant PMS to use the Desktop API.

Identifiers

The Desktop API requires a device identifier to identify the specific application connecting to Halo Cloud from a specific device, in addition to the Halo GUID used by all Halo Cloud APIs to identify the practice.

Two different devices at one practice running the same application (e.g. desktop machines or tablets) should not have the same Device ID.

Where Halo GUIDs are generated by Halo Cloud, Device IDs are generated by integrators. They are used to uniquely identify each desktop application at a practice, and device IDs are used with both authentication and query endpoints.

We recommend integrators ensure device IDs are secure values, and avoid enumerable or easily guessable formats such as ascending integers.

Authentication

Unlike the Integrator API, the Desktop API uses a combination of a Desktop API Token and a Device ID for authentication. An integrator's cloud must retrieve a Desktop API Token for a desktop application before the application can begin querying Halo Cloud, and the token must be renewed periodically as it expires after a set amount of time.

The Desktop API Token and Device ID must be supplied as headers on every request. See the Desktop API reference for the specifics. For example, sending an immediate query via the Desktop API. Details of the headers can be found for each endpoint under AUTHORIZATIONS.

The endpoint for retrieving a token is documented as part of the Desktop API reference, however it exists on the Integrator API route (/integrator/ not /desktop/) and uses Integrator API authentication. It should only be queried via an integrator's cloud servers, never a desktop application.

Token workflow

In order to onboard a new desktop application so that it can send queries to Halo Cloud:

1. The integrator authenticates and onboards a new application. From that process, a Device ID should be assigned to the new application, which both the integrator's cloud and the desktop application should know.
2. The integrator’s cloud requests a Desktop API Token from the Get token API endpoint, and includes in the request the practice's Halo GUID and the application's Device ID.
3. Halo Cloud validates the identifiers and issues a token.
4. The Integrator's cloud provides the Desktop API Token to the desktop application.

The Desktop API Token is then used by the desktop application, in combination with its device ID provided via header, to authenticate the desktop application when sending queries.

The token will need to be renewed periodically.

The expiry of a specific token can be found in the relevant token request response.

Token expiry error

If an application sends a query to Halo Cloud with an expired token, the error message will be:

{ 
  "error": 
  { 
    "statusCode": 401, 
    "message": "Invalid token" 
  } 
}

Test queries

To test your connection to the Desktop API, you could:

• Onboard a test application, give it a Device ID, and request a Desktop API Token.
• Then, using the Desktop API, you could:
  • Try one of the SQL Passthrough API query examples.
  • Try one of the FHIR API query examples.

For testing, programs such as Postman or Insomnia are perfectly suitable for querying Halo Cloud.

Webhook notifications

Available for:

• Async queries
• Registered queries

Integrators can be notified of completed async and registered queries via webhooks, once the feature has been configured for their subscription. This removes the need to poll Halo Cloud to check for new results.

For security reasons, the webhook payload includes as little data as possible. It does not include the query result, due to risks around who might see that data or how it might be stored. Webhooks must also be configured for an integrator’s subscription, rather than being a per-query option. This allows us to ensure the webhook payload goes to a designated, pre-negotiated, secure URL or URL pattern.

Webhook notifications work as follows:

• When an async or registered query completes successfully, a webhook will be sent to the specified URL.
• All webhooks are sent as a HTTP POST.
• The webhook payload will only contain:
  • The Halo GUID the query was sent to
  • The Query GUID of the query run
  • The type of source query (async or registered)
• There is no retry logic in the webhooks. We only send each webhook once.

To configure webhook notifications for your subscription, please contact Support. You will need to supply the URL you wish the webhooks to be sent to.

Currently, this can only be a single URL per integrator, however the following optional URL template variables are available:

• {siteId} is replaced with the siteId from the query
• {queryId} is replaced with the queryId from the query
• {source} is replaced with the source of the query, either “async” or “registered”

These variables will be replaced with the respective value when the webhook is sent. These values are also included in the payload. For example, if an integrator's webhook URL is:

myintegration.com/webhooks/{siteId}

For a practice with site ID 12345, webhooks will be sent to:

myintegration.com/webhooks/12345

The payload will also include "siteId": "12345".

Working with Halo GUIDs

Halo Cloud routes queries to practices by Halo GUID. The following outlines how to use Halo GUIDs, including recommendations for handling errors and changes.

Staging vs production

There are a few differences between how PMS IDs and Halo GUIDs work in production vs staging.

Production

• All connected PMS databases must be full production copies. Developer licenses and demo databases can not connect to production.
• Halo GUIDs should be fetched by trading the practice's unique PMS ID for their Halo GUID using the Get Halo GUID API endpoint.
• Each PMS has a different PMS ID system. To check what each PMS's PMS ID is called and where to find it, see the relevant PMS guide page.

Staging

• Developer licenses and demo versions of PMS databases often do not have a unique PMS ID, in which case Halo Link will assign a fake PMS ID so that the database can be uniquely addressed. This will be the first 8 characters of the database's Halo GUID.
• Fake PMS IDs can be used with the Get Halo GUID API endpoint. Non-unique real PMS IDs can not.
• It is easiest to get the Halo GUID of a Halo Link instance set to Stage from its:
  • Application logs
  • Registry values

Recommendations

Record PMS IDs

We recommend integrators store the PMS ID of practices they connect to. A practice's PMS ID does not tend to change unless the business itself changes significantly, so this is the best way to identify practices if something changes.

It is particularly useful when a practice's Halo GUID changes, such as due to a server migration, because it allows the integrator to automatically fetch the practice's new Halo GUID.

Use secondary identifiers

For each PMS, our Get Halo GUID and Get status endpoints will return at least one other piece of identifying information for each practice, such as the practice's business name (as fetched from their database) or their ABN.

We recommend integrators use this information to check they have the right practice when onboarding new practices.

If you're comfortable with storing or caching the secondary identifier, this can also be used to check for business changes. For example, a practice's name changing could be a sign of a practice split or merger.

See the relevant PMS guide to check what secondary identifier(s) are available for each PMS.

Automate handling of Halo GUID changes

Halo GUIDs are assigned by Halo Link when it is installed. While we have ways to account for most server changes that might invalidate a Halo GUID, there are cases in which a practice's Halo GUID may change.

We recommend integrators implement workflows to account for such changes with minimal service interruption for customers.

Fetching a Halo GUID

To fetch a practice's Halo GUID, we recommend:

1. Ask the practice for their PMS ID and optionally their secondary identifier(s).
2. Use the Get Halo GUIDs API endpoint to trade the PMS ID for the practice's current Halo GUID.
3. Check the second identifier(s) are correct.
4. Store or cache the Halo GUID for that practice for use when sending queries.
5. Optional: Send a test query to check everything works.

---

Prev: Halo Cloud overview

Next: SQL Passthrough overview Next: FHIR API overview