Overview
tuOtempO has a wide range of possibilities available based on the use of Webservices, Database Synchronization or the exchange of files. This article explains the implementation of the online reservation through the pubblication of Webservices from your side.
Table of Contents
A. Automatic communications with patients - [tuOtempO memo]
This section regards automatic communication based on events (for example, reservations, confirmations, cancellations, modifications, etc) or mass communication campaigns. Choose the solution which is most adapted to your way of working.
A.1 Retrieving appointments
You will have to build up or publish a Webservice which will be consumed by tuOtempO. This Webservice should expose the following methods:
searchAppointments()
VALUE (NULL = optional) | CORRESPONDS TO |
---|---|
[USER_LID] [nvarchar](50) NOT NULL | ID Patient in Your Software. |
[START_DATE] [nchar](10) NULL | Start date of the search interval |
[END_DATE] [nchar](10) NULL | End date of the search interval |
[RESOURCE_LID] [nvarchar](50) NULL | ID Resource (ex. Doctor) in Your Software |
[LAST_REQUEST_TIMESTAMP] [datetime] NULL | Date and time of the last call of SearchAppointments (permits to get only the appointments that have been added or modified after the last call) |
The Webservice should return to tuOtempO the following information:
VALUE (NULL = optional) | CORRESPONDS TO |
---|---|
[APP_LID] [nchar](10) NOT NULL | ID Appointment in Your Software |
[APP_STATUS] [nchar](10) NOT NULL | Status of the appointment (Confirmed, Cancelled) |
[APP_DATE] [nchar](10) NOT NULL | Date of the appointment |
[APP_START_TIME] [nchar](5) NOT NULL | Start time |
[APP_END_TIME] [nchar](5) NULL | End time |
[USER_LID] [nvarchar](50) NOT NULL | ID Patient in Your Software. |
[USER_MOBILE_PHONE] [nvarchar](50) NULL | Mobile number |
[USER_EMAIL] [nvarchar](50) NULL | |
[USER_INSURANCE_LID] [nvarchar](50) NULL | ID Insurance in Your Software |
[USER_PRIVACY] [nvarchar](1) NULL | Acceptation of privacy regulations (1=OK/0=NOT ACCEPTED) |
[ACTIVITY_LID] [nvarchar](50) NOT NULL | ID Activity in Your Software |
“*[ACTIVITY_NAME] [nvarchar](50) NULL” | Name of the activity in Your Software“ |
“*[ACTIVITY_GROUP_LID] [nvarchar](50) NULL” | ID Group of services in Your Software |
*[ACTIVITY_GROUP_NAME] [nvarchar](50) NULL | Name of group of services |
[RESOURCE_LID] [nvarchar](50) NOT NULL | ID Resource (ex. Doctor) in Your Software |
*[RESOURCE_FIRST_NAME] [nvarchar](50) NULL | First name of the resource |
*[RESOURCE_SECOND_NAME] [nvarchar](50) NULL | Second name of the resource |
[APP_SHOW] [int](1) NULL | Informs If the appointment has been attended by the USER (null=UNKNOWN, 0=didn’t show up,1=showed up) |
A.2 Appointment Confirmation/Cancellation Option
When you send a communication, you can give the patient the opportunity to cancel or confirm the appointment and to send the reply via SMS, email or voice message. If you want to use this feature it is necessary to manage the return of the information. In this case your webservice needs to expose the following webservice:
cancelAppointment()
VALUE (NULL = optional) | CORRESPONDS TO |
---|---|
[APP_LID] [nchar](10) NOT NULL | ID Appointment in Your Software |
[USER_LID] [nvarchar](50) NOT NULL | ID Patient in Your Software. |
FIELD | CORRESPONDS TO |
---|---|
[DELETE_RESULT] [nvarchar](50) NULL | OK / ERROR |
[RESULT] [nchar](10) NOT NULL | OK/ERROR |
[APP_LID] [nvarchar](50) NULL | ID Appointment in Your Software (concatenation of all the fields that compose the primary key PK) OR Error Message |
B. Management of Online Appointments - [tuOtempO Web]
The synchronization with Webservices is achieved in two phases:
B.1 Exchange of information which doesn’t change frequently (KeyEntities Webservices).
In this category are included for example:
- Prices or special tariffs
- Service catalogs
- Locations
- Resources (Doctors, etc.)
and all the relationships between these entities (for example, “which services and prices does a Doctor offer for a particular insurance”).
To let tuOtempO retrieve the KeyEntities which should be presented for the online booking you should publish the following webservices:
getResources()
This Webservice allows the retrieval of the Doctors which an appointment can be reserved with.
PARAMETER (Bold = must be implemented) | CORRESPONDS TO |
---|---|
[CENTER_LID] [nvarchar](50) NULL | ID of the Center in Your Software. |
VALUE (NULL = optional) | CORRESPONDS TO |
---|---|
[RESOURCE_LID] [nvarchar](50) NOT NULL, UNIQUE | ID Resource (aka Doctor) in Your Software |
[RESOURCE_FIRST_NAME] [nvarchar](50) NOT NULL | First Name of the resource |
[RESOURCE_SECOND_NAME] [nvarchar](50) NULL | Second Name of the resource |
[RESOURCE_MOBILE_PHONE] [nvarchar](50) NULL | Mobile of the resource |
[RESOURCE_EMAIL] [nvarchar](50) NULL | Email of the resource |
[RESOURCE_NOTICE] [text] NULL | Notes or advices related to the Resource you want to display to the user during the reservation process |
[LOCATION_LID] [nvarchar](50) NULL | ID Location in Your Software |
[LOCATION_NAME] [nvarchar](50) NULL | Name of of the location in Your Software |
[LOCATION_NOTICE] [text] NULL | Notes or advices related to the Location you want to display to the user during the reservation process |
[WEB_ENABLED] [int](1) NULL | Web enabled online(=1) |
[AVAILABILITIES_STEP] [int](3) NULL | Recommended interval between two availabilities |
getActivities()
This Webservice allows the retrieval of the Treatments offered by the Center and can be filtered on the Doctor.
PARAMETER (Bold = must be implemented) | CORRESPONDS TO |
---|---|
[RESOURCE_LID] [nvarchar](50) NOT NULL | ID of the Doctor in Your Software. Can be left empty if all activities are to be retrieved. |
VALUE (NULL = optional) | CORRESPONDS TO |
---|---|
[ACTIVITY_LID] [nvarchar](50) NOT NULL, UNIQUE | ID Activity in Your Software |
[ACTIVITY_NAME] [nvarchar](50) NOT NULL | Name of Activity in Your Software |
[ACTIVITY_GROUP_NAME] [nvarchar](50) NOT NULL | Name of of the Group of Activities |
[ACTIVITY_GROUP_LID] [nvarchar](50) NOT NULL | ID of the Group of Activities in Your Software |
[ACTIVITY_DURATION] [int] NULL | Duration of the activity in minutes |
[ACTIVITY_PRICE] [float] NULL | Price of the activity |
[ACTIVITY_NOTICE] [text] NULL | Notes or advices you want to display to the user during the reservation process |
[ACTIVITY_PREPARATION] [text] NULL | Instructions you would like to be sent or shown to the User |
[WEB_ENABLED] [int](1) NULL | Web enabled (=1) |
There is always the possibility to manage the online availability of each entity manually through the tuOtempO administration panel.
getInsurances()
This Webservice allows the retrieval of the Insurances/pricelists to which Doctors or Treatments can be associated.
PARAMETER (Bold = must be implemented) | CORRESPONDS TO |
---|---|
[RESOURCE_LID] [nvarchar](50) NULL | ID of the Doctor in Your Software. Should be left empty if no relation between insurances and Doctors exists in Your Software. |
[ACTIVITY_LID] [nvarchar](50) NULL | ID of the Treatment in Your Software. Should be left empty if no relation between insurances and treatments exists in Your Software. |
VALUE (NULL = optional) | CORRESPONDS TO |
---|---|
[INSURANCE_LID] [nvarchar](50) NOT NULL, UNIQUE | ID Insurance in Your Software |
[INSURANCE_NAME] [nvarchar](50) NOT NULL | Insurance Name in Your Software |
[ACTIVITY_PRICE] [float] NULL | Price of the treatment related to this insurance (not empty if ACTIVITY_LID has been specified as an argument) |
[WEB_ENABLED] [int](1) NULL | Web enabled online(=1) |
B.2 Exchange of information which changes frequently (Reservations Webservices)
In this case, you will have to make the Webservices (either SOAP or Rest) capable being ccalled by tuOtempO. Below we present the essential set of methods which this webservice should implement:
searchAvailabilities()
This Webservice allows the retrieval of the Doctor’s (or the Treatment’s) reservable time slots.
PARAMETER (Bold = must be implemented) | CORRESPONDS TO |
---|---|
[ACTIVITY_LID] [nvarchar](50) NOT NULL | ID Activity in Your Software. Can be empty if activities have all the same durations. |
[AVA_START_DAY] [nvarchar](10) NULL | Availability search starting day. Defaults to TODAY |
[AVA_END_DAY] [nvarchar](10) NULL | Availability search ending day. Defaults to AVA_START_DAY + 1 week |
[AVA_START_TIME] [nvarchar](5) NULL | Starting time of the availability search on AVA_START_DAY. Defaults to 00:00 |
[AVA_END_TIME] [nvarchar](5) NULL | End time of the availability search on AVA_END_DAY |
[AVA_MIN_TIME] [nvarchar](5) NULL | time slot beginning |
[AVA_MAX_TIME] [nvarchar](5) NULL | time slot ending |
[AVA_RESULTS_NUMBER] [nvarchar](5) NOT NULL | Quantity of availabilities to return |
[RESOURCE_LID] [nvarchar](50) NULL“ | ID Resource (ex. Doctor) in Your Software. If NULL then returns availabilities for all doctors |
[LOCATION_LID] [nvarchar](50) NULL | ID Location (ex. establishment) in Your Software. If NULL then returns availabilities for all locations |
[INSURANCE_LID] [nvarchar](50) NULL | ID Insurance in Your Software |
VALUE (NULL = optional) | CORRESPONDS TO |
---|---|
[RESOURCE_LID] [nvarchar](50) NOT NULL | ID Resource (ex. Doctor) in Your Software |
[ACTIVITY_LID] [nvarchar](50) NOT NULL | ID Activity in Your Software |
[LOCATION_LID] [nvarchar](50) NULL | ID Location (ex. establishment) in Your Software |
[INSURANCE_LID] [nvarchar](50) NULL | ID Insurance in Your Software |
[AVA_DATE] [nvarchar](10) NOT NULL | Availability date (preferred format dd/mm/yyyy) |
[AVA_START_TIME] [nvarchar](5) NOT NULL | Starting time of the availability on the day |
[AVAILABILITY_LID] [nvarchar](50) NULL | ID Availability (intervals between reservable slots) |
[AVA_END_TIME] [nvarchar](5) NULL | En time of the availability on the day |
[AVA_PRICE] [float] NULL | Price of the tratment according to all the rules matched by current the search_criterias |
addAppointment()
This webservice allow the reservation of a new appointment.
It’s important to point out that this Webservice should follow one of two possible patterns for dealing with the Patients synchronization between tuOtempO and Your Software. The choice consist in using:
- the patientID in tuOtempO (USER_TID), or
- the patientID in Your Software (USER_LID)
as the patient’s mapping key between the two environments.
The use of the USER_TID implies that you are able to store and link this data to your patients in your database but as a major beefit it allows a better control over the matching between the patient in tuOtempO and the patient in Your Software, especially in case of manual merging of patients in Your Software.
The use of the USER_LID on the other hand makes tuOtempO responsible of dealing with patients’ duplications and merging allowing a lower level of precision.
VALUE (NULL = optional) | CORRESPONDS TO |
---|---|
*[AVAILABILITY_LID] [nvarchar](50) NOT NULL | ID Availability in Your Software, previously returned by the SearchAvailability |
**[ACTIVITY_LID] [nvarchar](50) NOT NULL | ID Activity in Your Software |
**[RESOURCE_LID] [nvarchar](50) NOT NULL | ID Resource (ex. Doctor) in Your Software |
**[APP_DATE] [nchar](10) NOT NULL | Date of the appointment |
**[APP_START_TIME] [nchar](5) NOT NULL | Starting time |
***[USER_TID] [nvarchar](50) NOT NULL | ID Patient in tuOtempO. Should be used if you can store this information in Your Software‘ database |
***[USER_LID] [nvarchar](50) NOT NULL | ID Patient in Your Software. Not available for new patients. Should be used when it’s not possible to store USER_TID in Your Software‘ database |
[USER_FIRST_NAME] [nvarchar](50) NULL | First Name |
[USER_SECOND_NAME] [nvarchar](50) NULL | Second Name |
[USER_THIRD_NAME] [nvarchar](50) NULL | Third Name |
[USER_GENDER] [nchar](10) NULL | Gender (M, F) |
[USER_DATE_OF_BIRTH] [nchar](10) NULL | Date of birth |
[USER_MOBILE_PHONE] [nvarchar](50) NULL | Mobile number |
[USER_LANDLINE_PHONE] [nvarchar](50) NULL | Landline |
[USER_EMAIL] [nvarchar](50) NULL | |
[USER_ID_NUMBER] [nvarchar](50) NULL | User ID Number |
[INSURANCE_LID] [nvarchar](50) NULL | ID Insurance in Your Software |
VALUE (NULL = optional) | CORRESPONDS TO |
---|---|
[ADD_RESULT] [nvarchar](50) NOT NULL | OK / ERROR |
[ERROR_MESSAGE] [nvarchar](500) NULL | Error Message |
[APP_LID] [nvarchar](50) NULL | ID Appointment in Your Software (concatenation of all the fields that make up the primary key PK) OR NULL in case of error |
**[USER_LID] [nvarchar](50) NULL | ID Patient in Your Software |
- New Patient. In the case in which a reservation comes from a new patient who registers for the first time online, your Webservice should manage the matching or the insertion of the patient in Your Software’s database using the data which tuOtempO has sent. If the patient is not matched with an existing patient in Your Software’s database, your Webservice should insert them and return the new USER_LID assigned following the insertion of the appointment. The Patients’ matching algorithm we suggest is the following:- similarity (USER_FIRST_NAME AND USER_SECOND_NAME) AND identity (USER_ID_NUMBER OR USER_DATE_OF_BIRTH OR USER_MOBILE_PHONE)
- Old Patient. If the patient is already present, the Webservice will return a USER_LID that already exists. The next time that the patient reserves Online, tuOtempO will send to the addReservation Webservice the USER_LID. If this USER_LID is no longer present in your Software’s database(for example because they have been deleted manually) then your Webservice should carry out a search as if it was a new patient
deleteAppointment()
This Webservice allows the removal of a reserved Appointment.
VALUE (NULL = optional) | CORRESPONDS TO |
---|---|
[APP_LID] [nchar](10) NOT NULL | ID Appointment in Your Software |
VALUE (NULL = optional) | CORRESPONDS TO |
---|---|
[DELETE_RESULT] [nvarchar](50) NOT NULL | OK / ERROR |
[ERROR_MESSAGE] [nvarchar](500) NULL | Error Message |
[APP_LID] [nvarchar](50) NULL | ID Appointment in Your Software (concatenation of all the fields that make up the primary key PK) OR Error Message |
getAppointments()
This Webservice is needed when you want the patient to be able to online view or cancel all his existing appointments regardless of their origin (online/offline).
VALUE (NULL = optional) | CORRESPONDS TO |
---|---|
[USER_LID] [nvarchar](50) NULL | ID Patient in Your Software. |
[USER_TID] [nvarchar](50) NULL | ID Patient in tuOtempO |
[START_DATE] [nchar](10) NULL | Start date of the search interval |
[END_DATE] [nchar](10) NULL | End date of the search interval |
[RESOURCE_LID] [nvarchar](50) NULL | ID Resource (ex. Doctor) in Your Software |
[LAST_REQUEST_TIMESTAMP] [datetime] NULL | Date and time of the last call of getAppointments (permits to get only the appointments that have been added or modified after the last call) |
[APP_LID] [nchar](10) NULL | ID Appointment in Your Software |
USER_TID and USER_LID are exclusive to eachother. You should use only one of them according to the Users synchronization pattern chosen.
VALUE (NULL = optional) | CORRESPONDS TO |
---|---|
[APP_LID] [nchar](10) NOT NULL | ID Appointment in Your Software |
[APP_STATUS] [nchar](10) NOT NULL | Status of the appointment (Confirmed, Cancelled) |
[APP_DATE] [nchar](10) NOT NULL | Date of the appointment |
[APP_START_TIME] [nchar](5) NOT NULL | Start time |
[APP_END_TIME] [nchar](5) NULL | End time |
[APP_PRICE] [float] NULL | Price of this treatment |
[APP_CREATED] [nchar](10) NULL | The booking date in Your Software |
[USER_LID] [nvarchar](50) NOT NULL | ID Patient in Your Software. |
[USER_MOBILE_PHONE] [nvarchar](50) NULL | Mobile number |
[USER_LANDLINE_PHONE] [nvarchar](50) NULL | Landline number |
[USER_WORK_PHONE] [nvarchar](50) NULL | Work number |
[USER_EMAIL] [nvarchar](50) NULL | |
[USER_INSURANCE_LID] [nvarchar](50) NULL | ID Insurance in Your Software |
[USER_PRIVACY] [nvarchar](1) NULL | Acceptation of privacy regulations (1=OK/0=NOT ACCEPTED) |
[ACTIVITY_LID] [nvarchar](50) NOT NULL | ID Activity in Your Software |
[RESOURCE_LID] [nvarchar](50) NOT NULL | ID Resource (ex. Doctor) in Your Software |
[APP_SHOW] [int](1) NULL | Informs If the appointment has been attended by the USER (null=UNKNOWN, 0=didn’t show up,1=showed up) |
B.3 Multi center environment
This webservice is important only in case of high number of centers, it allows to automate the creation of new tuOtempO accounts whenever a new center is added to the pool of centers managed by Your Software.
On tuOtempO side there will be an instance for each center and, if needed, an additional “portal instance” that will permit to have a single point of access on the web which will take care of making parallel searches on the centers, return availabilities and forward to the centers new reservations or cancellations requests. The portal instance could also host, without loss of functionality, centers that have been integrated by views and temporary tables using tuOtempO Sincro.
getCenters()
The Webservice should return to tuOtempO the following information:
Response(Array (CENTER_LID , CENTER_NAME, [DESCRIPTION], [ADDRESS], [PHONE],[WEBSITE_URL])
C. [tuOtempO VIEW] – Access to Medical Results
To enable web access to medical results it is necessary to activate a synchronized communication between Your Software and tuOtempO by choosing one of the available procedures. The synchronization with Webservices is achieved in two phases:
C.1 Transmitting web available results
Your Webservices (SOAP possibly) will be capable of replying to this call from tuOtempO:
getTestResultsList([USER_LID|USER_TID], RESULT_START_DATE)
VALUE (NULL = optional) | CORRESPONDS TO |
---|---|
[USER_LID] [nvarchar](50) NULL | ID Patient in Your Software |
[USER_TID] [nvarchar](50) NULL | ID Patient in tuOtempO |
RESULT_START_DATE [nvarchar](10) NULL | Test result starting day |
The Webservice should return the following information to tuOtempO:
Response(Array (DOWNLOAD_LID, [STATUS (Valid, Cancelled)], DOWNLOAD_CODE, DOWNLOAD_FILENAME, DOWNLOAD_TYPE, USER_LID, [USER_TID], USER_MOBILE_PHONE, [USER_EMAIL], USER_ID_NUMBER ))
FIELD | CORRESPONDS TO |
---|---|
[DOWNLOAD_LID] [nvarchar](50) NOT NULL, UNIQUE | ID Result in Your Software |
[STATUS] [nchar](10) NOT NULL | Status of the result (Valid, Cancelled) |
[DOWNLOAD_CODE] [nvarchar](50) NOT NULL | The code the user owns and use to request result’s delivery |
[DOWNLOAD_FILENAME] [nvarchar](255) NULL | Name of the result’s file |
DOWNLOAD_TYPE [nvarchar](10) NOT NULL | Result’s file extension (ex.: pdf) |
[USER_LID] [nvarchar](50) NOT NULL | ID of the Patient in Your Software |
[USER_TID] [nvarchar](50) NULL | ID Patient in tuOtempO |
[USER_MOBILE_PHONE] [nvarchar](50) NOT NULL | Mobile number |
[USER_EMAIL] [nvarchar](50) NULL | |
[USER_ID_NUMBER] [nvarchar](50) NOT NULL | USER ID Number – it will be used together with DOWNLOAD_CODE to request result’s delivery |
Assume, as an example, this date is one week before the current date.
a) just reply to the call omitting the Test Result ID=012324
b) change status to Test Result ID =012324 setting status=cancelled
If a test result is out of the time-slot specified by RESULT_START_DATE the system will notice its cancellation when calling the Webservice getTestResultContent.
C.2. Transmitting test result content
Your Webservices (SOAP possibly) will be capable of replying to this call from tuOtempO:
getTestResultContent(DOWNLOAD_LID)
The Webservice should return the following information to tuOtempO:
Response(DOWNLOAD_LID, [DOWNLOAD_CONTENT],STATUS(Valid,Cancelled),[ERROR_MESSAGE])
FIELD | CORRESPONDS TO |
---|---|
[DOWNLOAD_LID] [nvarchar](50) NOT NULL, UNIQUE | ID Result in Your Software |
[STATUS] [nchar](10) NOT NULL | Status of the result (Valid, Cancelled) |
[DOWNLOAD_CONTENT] [varbinary](max) NOT NULL | Result’s file binary content |
[ERROR_MESSAGE] [nvarchar](500) NULL | Error Message |