com.innovaphone.calendar

The com.innovaphone.calendar services api enables apps to use the whole websocket communication API from calendar. The users App uses this functionality on the C++ part of the app for reading, creating and modifying appointments as well as special requests that can be used for syncing.
All messages are send as JSON strings and must use the mt property which is the message type.

See services for the information how to exactly work with IServices!
When accessing the calendar using the service api (which means, that the user to access will be authenticated by the PBX), the acces to the calendar is on admin level. That means, that full access to the calendar database for all users is granted. Appointments for all users can be read (ignoring the private flag), updated and created. This comes in handy for synchronizing purposes.

IServicesApi * services = ...;    // must be retrieved within the PBX websocket connection PbxInfo message to the app service.
IService * service = services->GetService("com.innovaphone.calendar");
class IAppWebsocketClient * awsClient = IAppWebsocketClient::Create(iomux, this, tcpSocketProvider, tlsSocketProvider, dns, log);
awsClient->Connect(service->GetWebsocketUrl(), service->GetName(), session->services->CreateAuthenticator());

AppLogin

If you do not work with IServices and you know the intance password of the calendar instance, you can also use the standard AppLogin mechanism to login to calendar.
Note that using AppLogin doesn't give the ability to access the data of all users for synchronizing purposes. For this, admin rights are needed, which only will be granted for connections comming over a service, authenticated by the PBX.

Messages send to the service

Messages received by the service

Additional infos

Calendar JSON messages

Below is a detailed description of each message. The messages have all the same header. Note that all messages MUST include the header properties.

{
    "mt": MessageID,
    "src": "string"
}

This header must be set for all messages. The properties that will be added below depending on the message sent. Details about that fields can be found in the description of each message below.

Properties

{
    "mt": "GetAppointments",
    "src": "uniqueIDString",
    "userID": number,
    "start": number,
    "end": number,
    "syncID": number,
    "syncDatabase": string,
    "close": bool
    "properties": [appointmentProperties]
}

This message returns all appointments for the given time range and also registeres the app receiving continous updates. The src property is obligatory for that message. Each response will echo the value of src. With this, an app can define different sets of parameters to get appointments for (as well as further updates).

The message leads to a couple of responses. Aft first, a GetAppointmentsResult message will be received as answer. The status of the message tells, what is going to happen. If the status is "ok", then the calendar will send all available appointments for the given time range via AppointmentInfo messages. The last message will also have the property last set to true, to signal that all available data had been send. After that, the calendar will observe the database for changed and send each change for the requested user and time range with another AppointmentInfo message. Each appointment will be send with an own AppointmentInfo message.

The parameters for an existing observation can be changed by sending GetAppointments with the same src value again. That will lead to the same process as sending the message the first time. Note that each AppointmentInfo sended before the GetAppointmentResult response can be ignored, because they are part of the previous and now outdated GetAppointments message.

To stop from getting further updates, GetAppointments must be send again with the property close set to true. This will lead to an GetAppointmentsResult message, too, showing that the observation for changes is stopped. To continue receiving updates, GetAppointments must be send. When the connection closes, each observation will be canceled automatically.

The message can also be used to synchronize with the calendar database. For this, the property syncID and syncDatabase must be set. To do a first-time sync, set syncDatabase to an empty string and syncID to 0. To sync all data changed from the time of the last sync, set syncID and syncDatabase to the lastest values received. The syncID is a property of an appointment and must be requested via the properties array, while the syncDatabase will be received through the GetAppointments message (only if syncID and syncDatabase are given to GetAppointments). Note that for synchronizing purposes it will be a good idea to request all appointment properties. If there is need to syhcnronize multiple users, each user should be synchronized seperately. So at first send a GetAppointments message for the first user, until AppointmentInfo with last set to true will arraive (or GetAppointmentsResult with status set to noData). After that, only the incomming updates must be handled.

When requesting appointments from other users, the title will set to "Private" if the private flag of an appointment is set to true. Except for connections established by a service (authenticated through the PBX). In that case, the title will be as saved in the database. This is important for synchronizing purposes. Be careful and respect the users privacy! If there is need to synchronize the appointments of all users, one user after an other should be synchronized to spare resources.

Properties

Remarks

If the syncID property is given, the synchronizing mode will be enabled. That leads to the following differences:

• Only appointments changed or created since the time, the given sync id had been created, will be send.
• Appointment series won't be calculated. The recurring masters will be send instead.
• If the value of syncDatabase won't combine with the value from the database of the calendar, an error will be reported.

{
    "mt": "GetAppointmentsResult",
    "src": "streamIDString",
    "syncDatabase": string,
    "status": "statusCodeString",
    "errorMsg": "errorMessageString"
}

This is the response for GetAppointments.

Properties

Remarks

The values for status are:

• ok: No error - everything is fine.
• noData: Everything is fine, but no appointment exists for the given time range. Only further updates combining with the time range will be send.
• closed: The current observation had been closed by GetAppointments with property close set to true.
• userNotFound: The given userID doesn't exist in the users database.
• syncDatabaseMissmatch: The given syncDatabase id doesn't match with the one of the calendar.
• srcMissing: The source property is missing - note that src is obligatory for GetAppointments.
• error: An unexpected error occured. The error message will be send with the errorMsg property.

{
    "mt": "AppointmentInfo",
    "src": "uniqueIDString",
    "last": bool,
    "status": "statusCodeString",
    "properties": {
        appointmentProperties
    }
}

This message will be send to an open appointment stream.

Properties

Remarks

When sending GetAppointments, the calendar will send all appointents for the requested time range available first. These messages won't have a status property. AppointmentInfos send later because of changes to the calendar database (in the defined time range), will be send with the status property to tell the reason for the update. In that case, status have one of the following values:

• created: The appointment had been created an thus added to the database.
• modified: The appointment had been changed. You need to check the timestamp of the appointment to make sure, it still lies inside the defined time range.
• deleted: The appointment had been deleted. In this case, only the id and user id will be send.
• recurringMasterChanged: Will be send with the id of an recurring master that had been changed. The app needs to discard all occurrences. The new, updated occurrences will be send after that message, too. Only for streams that have not set the resolveSeries property to false.

{
    "src": optionalString,
    "mt": "GetAppointment",
    "id": number
}

Returns the appointment with the requested id. The message will lead to a GetAppointmentDone response message with the requested appointment.

Properties

{
    "mt": "GetAppointmentResult",
    "src": optionalString,
    "status": "statusString",
    "errorMsg": "errorMessageString",
    "properties": [appointmentProperties]
}

The answer for GetAppointment with the requested appointment.

Properties

Remarks

Status will be one of the following values:

• ok: Everything is fine, no special status reported.
• missing: The requested appointment could not be found.
• deleted: The requested appointment had been deleted.
• idMissing: The message was send without the id property.
• error: An unexpected error occurred - details will be send with errorMsg.

{
    "mt": "WriteAppointment",
    "src": optionalString,
    "properties": [appointmentProperties]
}

Write the appointment with the given properties to the database. This message will lead to a WriteAppointmentResult response message. The message will be used to create or change an appointment. The details of an appoimtment are defined by the appointment properties inside the properties object. In general, all properties must be set, with some exceptions:

• To create a new appointment, the id must not be given. If an id will be part of the property list, the appointment will be updated.
• If userID is not given, the user of the current connection will be used. If that user is a service connection, an error will be raised.
• The type must be set to define the type of the appointment to write / update. If type is RECURRING_EXCEPTION, the fields for the rrecurring exception must be given, too. Same for the fields for recurring masters, if type is RECURRING_MASTER. If type is NORMAL, properties for recurring exceptions or recurring masters will be ignored.
• The type OCCURRENCE is invalid for WriteAppointment and will be rejected. To create an exception for a recurring master, user DELETED_EXCEPTION or MODIFIED_EXCEPTION.
• The organizer property is optional.
• The location property also is optional.
• The readonly fields changedAt and syncID will be ignored, if set.
• Missing properties will lead to an error reported by the response for the message send.

Properties

{
    "mt": "WriteAppointmentResult",
    "src": optionalString,
    "id": number,
    "status": "status",
    "errMsg": "errorMessageString"
}

Will be sent as a result of WriteAppointment.

Parameters

Remarks

Status will be one of the following values:

• created: The appointment had been created successfully.
• updated: The appointment had been updated successfully.
• missing: The appointment to update could not be found.
• deleted: The appointment to update had been already deleted.
• userNotFound: The user given in the appointments userID property doesn't exist.
• error: An unexpected error occurred - details will be send with errorMsg.

{
    "mt": "DeleteAppointment",
    "src": optionalString,
    "id": number
}

Will delete the appointment with the given id. This message will lead to a DeleteAppointmentResult response message.

Parameters

{
    "mt": "DeleteAppointmentResult",
    "src": optionalString,
    "status": "status",
    "errMsg": "errorMessageString"
}

Will be sent as a result of DeleteAppointment.

Parameters

Remarks

Status will be one of the following values:

• ok: The appointment had been deleted successfully.
• missing: The appointment to delete could not be found.
• deleted: The appointment to delete had been deleted.
• error: An unexpected error occurred - details will be send with errorMsg.

{
    "mt": "GetUser",
    "src": optionalString,
    "close": bool
}

Get all available users and observes the user database of the calendar for changes. Instead of GetAppointments only on observation per connection will be allowed.

The message will lead to couple of responses. At first, a GetUserResult message will be send. If the status of that message is not error, a bunch of UserInfo messages will follow. The last user for the request will be send the the last flag of the UserInfo message set. After that, update for a user or the user list will be send with additional UserInfo messages. The updates will be send until the connection had been closed or GetUsers will be send again with the close flag set to true.

Parameters

{
    "mt": "UserInfo",
    "src": optionalString,
    "status": "statusString",
    "last" : boolean
    "userID": number,
    "userName": string
}

Will be send for each user after sending GetUser as well as every time, if something changes in the user database.

Parameters

Remarks

Status only will be send for update messages and will be one of the following values:

• created: The The user had been created.
• deleted: The user had been deleted.
• modified: The user name had been changed.

{
    "mt": "GetUserResult",
    "src": optionalString,
    "status": "statusString",
    "errorMsg": "errorMessageString"
}

Will be send after sending a GetUser message, If the status will be ok (GetUser sent the first time) or restarted (GetUser sent again to get a while refresh), a bunch uf UserInfo messages will folow, whith the last UserInfo message having the last flag set to true. That message also occures after the observation had been closed because of a GetUser message with close set to true.

Parameters

Remarks

Status will be one of the following values:

• ok: No errors - everything is fine.
• error: An error occurred. Details of the error will be send in errorMsg.
• restarted: The observation had been canceled due another GetUser message.

{
    appointmentProperties
}

Each message that writes, requests or sends appointments need a list of properties of the appointment. The requested properties will be send in the respose and can be one of the properties below. For creating or updating appointments, all relevant properties must be set. For requesting appointments, the properties id, userID and type will always be send. Note that the properties array will be optional for messages that request appointments (GetAppointments, GetAppointment). In that case, all relevant properties for an appointment will be send. Only properties that exist for an appointment will be part of the answer. Readonly properties (type, syncID, changedAt) will be ignored if tried to use for WriteAppointment.

Note: The recurring masters have additional fields to calculate the series. The calculation will be done by the calendar using functions provided by the innovaphone SDK. The properties for the recurring masters depending highly on that functions, so it is recommended to read the time occurrence documentation to understand the usage of the properties as well as the values of the fields (like for the days property, which is a bitfield).