tuOtempO Integration Guide for Softwares exposing Webservices/APIs

Print Friendly

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()
The Webservice should be called by tuOtempO with these parameters

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 Email
[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)
Note: KeyEntities dependence(*) These field should be NOT NULL if you want notifications to patients to contain this information.

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()
The Webservice should be called by tuOtempO with these parameters

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.
The Webservice, should return to tuOtempO the following data

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.

The Webservice should be called by tuOtempO with these parameters

PARAMETER (Bold = must be implemented) CORRESPONDS TO
[CENTER_LID] [nvarchar](50) NULL ID of the Center in Your Software.
The Webservice should return to tuOtempO the following information:

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.

The Webservice should be called by tuOtempO with these parameters

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.
The Webservice should return to tuOtempO the following information:

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)


Note: Restricting Online Reservation to a reduced set of Resources or Activities If you aim to restrict the online reservation to a subset of your Resources (aka Doctors), or Activities (aka Treatments),  we strongly recommend to let the Webservice return the whole set AND use the WEB_ENABLED field to specify their online availability.
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.

The Webservice should be called by tuOtempO with these parameters

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.
Insurances’ relationsInsurances use to be associated with either Doctors or treatments but usually not with both, so you should implement the input parameter which represents the correct architecture in Your Software’s database
The Webservice should return to tuOtempO the following information:

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.

The Webservice should be called by tuOtempO with these parameters

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
The Webservice should return to tuOtempO the following information:

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.

Patients Synchronization Pattern

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 Email
[USER_ID_NUMBER] [nvarchar](50) NULL User ID Number
[INSURANCE_LID] [nvarchar](50) NULL ID Insurance in Your Software
Note: Availability ID vs. Appointment Data * if AVAILABILITY_LID is implemented the combination of  ** (ACTIVITY_LID + RESOURCE_LID + APP_DATE + APP_START_TIME) is optional.
Note: USER_TID vs. USER_LID *** USER_TID and USER_LID are exclusive to each other. You should use only one of them accordingly with the chosen Users synchronization pattern.
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
Note: Patient ID Management (**) this field should be present only in case of USER_LID pattern. In this case:

  • 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

Note: Temporary IDSome applications assign a temporary ID when registering a new patient. tuOtempO will retrieve the definitive ID of the patient via the getAppointments (APP_LID) Webservice
Warning: Manual mergeIf an Operator manually merges two duplicate patients in Your Software it is important that the data relative to the online registration is conserved, otherwise tuOtempO is not capable of identifying with whom the fusion has been made and the associations with their reservations will be lost.

deleteAppointment()

This Webservice allows the removal of a reserved Appointment.

The Webservice should be called by tuOtempO with these parameters

VALUE (NULL = optional) CORRESPONDS TO
[APP_LID] [nchar](10) NOT NULL ID Appointment in Your Software
The Webservice should return to tuOtempO the following data

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

Note: Cancellations by mailtuOtempO can also send cancellations by mail : some centres opt to receive cancellations through an email account that is frequently checked manually by an administrator (often so they can call and fix a new appointment). In this case the Webservice DeleteAppointment is not needed.

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).

The Webservice should be called by tuOtempO with these parameters

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.

Merged Patients ManagementIf the USER_LID pattern has been chosen the APP_LID argument must be implemented because it represents  the only way of notifying tuotempo that an appointment’s holder has been merged with another user in Your Software (getAppointments(APP_LID)=MERGED_USER_LID).

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
[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 Email
[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)

Note: Strong MatchingIf Your Software allow to save tuOtempO patient’s id (USER_TID pattern) it could be possible to invoke the Webservice GetAppointments() passing USER_TID instead of USER_LID.
Warning: Status Cancelled => LAST_REQUEST_TIMESTAMPThe input parameter LAST_REQUEST_TIMESTAMP can only be used if the STATUS = ‘cancelled’ is implemented by the getAppointments() webservice.

 

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)
+-Show getTestResultsList Request
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 ))

+-Show getTestResultsList Response
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 Email
[USER_ID_NUMBER] [nvarchar](50) NOT NULL USER ID Number – it will be used together with DOWNLOAD_CODE to request result’s delivery
Note: Frequency and DurationtuOtempO will call this Webservice with a certain periodicity depending on the configuration setting, typically twice a day. The call will ask for all the results for which the date is equal or after the date specified in RESULT_START_DATE parameter.
Assume, as an example, this date is one week before the current date.
Note: Removing a Test ResultIf for some reason you need to remove a Test Result (e.g. removing Test Result ID=012324) you can choose between
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])

+-Show getTestResultsContent Response
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
Note: Content not availableThe field ERROR_MESSAGE should give an explanation of the result’s unavailability.