Halo Cloud API for Integrators (23.628)

Download OpenAPI specification:Download

Introduction

This document outlines the API endpoints available to integrators using Halo Connect's SQL Passthrough API. It includes endpoints for:

Creating immediate queries
Creating, checking the status of, and retrieving the results of async queries
Checking the status and Halo GUID of a site

This API reference is defined using the OpenAPI Specification.

You can find out more about Halo Connect on our website and blog.

Definitions

For in-depth documentation and guides, see our main docs. The following is only a quick reference guide.

Site: A practice server with Halo Link installed.
Halo GUID: The unique identifier for a site which is used by Halo Connect to route queries.
PMS: Practice Management Software
PMS ID: The identifier for a site given to them by their PMS. May be shared across multiple sites, as per Halo Connect's definition, if a practice has multiple servers.
Immediate query: A small, time-sensitive query that is returned in seconds.
Async query: A query which is queued for execution, and integrators can retrieve the results later.
Authoritative server: A site's server which integrators are allowed to query.
Non-authoritative server: A site's server which integrators are not allowed to query, such as for a backup system.

Immediate queries

Create an immediate query.

Send immediate query

This resource allows you to send an immediate query to a site, and receive a result or error in the POST response. The site to be queried is specified by its Halo GUID. You can also get the status of an immediate query using the GET Query status endpoint listed under Async queries.

Authorizations:

ApiKeyHeaderApiKeyQuery

path Parameters

siteId

required

string

Halo GUID of the site.

Request Body schema: application/json

maxTimeInQueue	number <milli-seconds> (ImmediateMaxTimeInQueue) [ 0 .. 60000 ] Default: 30000
required	object (Command)
catalogue	string (Catalogue) Indicates which database to run against. If no catalogue is specified a default catalogue will be chosen instead. Currently only supported for Zedmed, if querying best practice select the database in the query itself. Database catalogues can be identified from a site's database.name property and are consistent across all sites of a single PMS type.

Responses

Request samples

Payload

Content type

application/json

{"maxTimeInQueue": 15000,
"command": {"text": "GetPatientID",
"executionMode": "reader",
"type": "text",
"parameters": [{"name": "@siteid",
"direction": "output",
"type": "BigInt",
"value": "66",
"size": 43
}
]
},
"catalogue": "Patients"
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"integratorId": "1acd5efb-e960-4c96-8a84-ca37f187f58b",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"mode": "immediate",
"maxTimeInQueue": 15000,
"sqlQuerySize": 46,
"commandSize": 98,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"status": "successful",
"statusTiming": {"initialising": {"startTime": "2019-08-24T14:15:22Z",
"endTime": "2019-08-24T14:15:22Z"
},
"executing": {"startTime": "2019-08-24T14:15:22Z",
"endTime": "2019-08-24T14:15:22Z"
}
},
"metrics": {"sqlExecutionDuration": 1000
},
"result": {"rows": 30,
"size": 25,
"data": "e2lkIjogNDIsaW5mbyI6IHsgIm5hbWUiOiAiSmFuZSIsICJzdXJuYW1lIjogIlNtaXRoIiB9LGRvYiI6ICIzMDIyLTExLTA0VDEyOjAwOjAwfQ==",
"parameters": [{"name": "@siteid",
"direction": "output",
"type": "BigInt",
"value": "66",
"size": 43
}
]
}
}

Async queries

Create an async query, check its status, and retrieve its result pages.

Use the POST Send async query endpoint to create an async query. If the query is successfully queued, you will receive a 201 Async query created response which includes a queryID. You will need to note this queryID for checking the status of and retrieving the result of this query.
Use the GET Get query status endpoint to check the status of the query. Once the query is complete and the status is successful, the response object will include a result field which gives details of the rows, size, and pages of the query result.
Use the GET Get async result page endpoint to retrieve query result pages once the query is complete, using the page information returned by the GET Query status endpoint.

Send async query

This resource allows you to send an async query to a site to be queued for execution. The site to be queried is specified by its Halo GUID.

Authorizations:

ApiKeyHeaderApiKeyQuery

path Parameters

siteId

required

string

Halo GUID of the site.

Request Body schema: application/json

maxTimeInQueue	number <milli-seconds> (AsyncMaxTimeInQueue) [ 0 .. 7200000 ] Default: 3600000
required	object (Command)
catalogue	string (Catalogue) Indicates which database to run against. If no catalogue is specified a default catalogue will be chosen instead. Currently only supported for Zedmed, if querying best practice select the database in the query itself. Database catalogues can be identified from a site's database.name property and are consistent across all sites of a single PMS type.

Responses

Request samples

Payload

Content type

application/json

{"maxTimeInQueue": 900000,
"command": {"text": "GetPatientID",
"executionMode": "reader",
"type": "text",
"parameters": [{"name": "@siteid",
"direction": "output",
"type": "BigInt",
"value": "66",
"size": 43
}
]
},
"catalogue": "Patients"
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"integratorId": "1acd5efb-e960-4c96-8a84-ca37f187f58b",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"mode": "async",
"status": "initialising",
"maxTimeInQueue": 900000,
"sqlQuerySize": 46,
"commandSize": 98,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"statusTiming": {"initialising": {"startTime": "2019-08-24T14:15:22Z"
}
}
}

Get query status

Check the status of a query. The same endpoint is used for both immediate and async queries, though it returns a different response with successful async queries returning a "results" object which includes pagination details for GET Result Page. Also be aware immediate queries retrieved using this endpoint will not include a results object indicating pages since it is returned with the initial request unlike async queries.

Authorizations:

ApiKeyHeaderApiKeyQuery

path Parameters

siteId required	string Halo GUID of the site.
queryId required	string Id of the query.

Responses

Response samples

Content type

application/json

Example

successful

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"integratorId": "1acd5efb-e960-4c96-8a84-ca37f187f58b",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"mode": "async",
"status": "successful",
"maxTimeInQueue": 900000,
"sqlQuerySize": 46,
"commandSize": 98,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"statusTiming": {"initialising": {"startTime": "2019-08-24T14:15:22Z",
"endTime": "2019-08-24T14:15:22Z"
},
"queued": {"startTime": "2019-08-24T14:15:22Z",
"endTime": "2019-08-24T14:15:22Z"
},
"executing": {"startTime": "2019-08-24T14:15:22Z",
"endTime": "2019-08-24T14:15:22Z"
},
"uploading": {"startTime": "2019-08-24T14:15:22Z"
}
},
"metrics": {"sqlExecutionDuration": 1000
},
"result": {"rows": 30,
"size": 25,
"pages": [{"pageNumber": 1,
"status": "queued",
"size": 0,
"rows": {"count": 10,
"rangeStart": 1,
"rangeEnd": 11
}
}
]
}
}

Get result page

Get a result page from a successful async query.

Authorizations:

ApiKeyHeaderApiKeyQuery

path Parameters

siteId required	string Halo GUID of the site.
queryId required	string Id of the query.
pageNumber required	number >= 1 Page number of the results for a query.

Responses

Response samples

Content type

application/json

Example

Query Result

{"data": "e2lkIjogNDIsaW5mbyI6IHsgIm5hbWUiOiAiSmFuZSIsICJzdXJuYW1lIjogIlNtaXRoIiB9LGRvYiI6ICIzMDIyLTExLTA0VDEyOjAwOjAwfQ==",
"parameters": [{"name": "@siteid",
"direction": "output",
"type": "BigInt",
"value": "66",
"size": 43
}
]
}

Halo sites

Retrieve a site's Halo GUID or check its status.

Get Halo GUIDs

Retrieve the list of Halo GUIDs for Halo Connect sites that match all of the supplied query parameters. This endpoint allows integrators to exchange a known PMS ID (e.g. Best Practice Site ID) for the corresponding Halo GUID which can then be used to query the site.

Authorizations:

ApiKeyHeaderApiKeyQuery

query Parameters

practiceManagementSiteId required	string Filters by the Best Practice Site Id.
practiceManagementName required	string (PracticeManagementName) Enum: "Best Practice" "Zedmed" Filters by the name of the Practice Management Software used by the site.

Responses

Response samples

200
400
401
403
500

Content type

application/json

{"sites": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pmsType": "Best Practice",
"availability": "online",
"haloLinkVersion": "22.1207.209",
"enrichedAt": "2019-08-24T14:15:22Z",
"catalogue": [{"name": "Patients",
"isDefault": true
}
],
"practiceMetadata": {"pmsType": "Best Practice",
"practiceName": "Halo Clinic South",
"practiceManagementSiteId": "12345",
"practiceManagementVersion": "3.4.1"
},
"name": "Halo Clinic",
"practiceManagementSiteId": "string",
"practiceManagementName": "Best Practice",
"practiceManagementVersion": "3.4.1",
"status": "initialising",
"createdAt": "2019-08-24T14:15:22Z",
"authoritative": true,
"clientTimestampUTC": "2022-12-25T12:25:01Z",
"heartbeatTimestampUTC": "2022-12-25T12:25:01Z"
}
]
}

Get site status

Check the status of a site using its Halo GUID.

Authorizations:

ApiKeyHeaderApiKeyQuery

path Parameters

siteId

required

string

Halo GUID of the site.

Responses

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pmsType": "Best Practice",
"availability": "online",
"haloLinkVersion": "22.1207.209",
"enrichedAt": "2019-08-24T14:15:22Z",
"catalogue": [{"name": "Patients",
"isDefault": true
}
],
"practiceMetadata": {"pmsType": "Best Practice",
"practiceName": "Halo Clinic South",
"practiceManagementSiteId": "12345",
"practiceManagementVersion": "3.4.1"
},
"name": "Halo Clinic",
"practiceManagementSiteId": "string",
"practiceManagementName": "Best Practice",
"practiceManagementVersion": "3.4.1",
"status": "initialising",
"createdAt": "2019-08-24T14:15:22Z",
"authoritative": true,
"clientTimestampUTC": "2022-12-25T12:25:01Z",
"heartbeatTimestampUTC": "2022-12-25T12:25:01Z"
}