Vevent API

The Vevents (or "events") are of serveral types:

1 – Appointments:

The appointments are required to be linked to an object of type « Fiche » via the fiche_id field, and to an object of type « Intervention » via the intervention_id field.

Important They can't be repeated!

2 – Plages:

The plages are simple text events (ex: "Lunchtime")

Important To create a plage, both fields intervention_id and fiche_id must have the value 0.

3 – Availabilities:

The availabilities are a "special" type of plages that delimit the slots which will be available on the appointment module.

Important The type field must have the following value: VfreebusyEvent

4 - Notes:

Notes are events that take place on a specific day but do not block this day for further booking.

• These events must have the note field set to 1.

• start and end fields must both be set to midnight (ex: start = end = "2010-01-22 00:00:00"), the duration of the note must be considered null.

Retrieve all the vevents on a group

GET /api/v1/groups/:group_id/vevents

Note Since the request does not specify the id of a calendars, the vevents returned belong to any calendar inside the group whose id is :group_id.

Retrieve the vevents on a calendar

GET /api/v1/groups/:group_id/vevents?calendar_id=:calendar_id

Create a vevent

POST /api/v1/groups/:group_id/vevents

Update a vevent

PUT /api/v1/groups/:group_id/vevents/:id

Delete a vevent

DELETE /api/v1/groups/:group_id/vevents/:id

Important This operation does not remove the vevent completely! It will change the value of the deleted attribute to true. The vevent can be restored later on.

Retrieve the vevents linked to a fiche

The vevents linked to a fiche are necessarily appointments:

GET /api/v1/groups/:group_id/vevents?fiche_id=:fiche_id

Standard fields

These fields are common to the 4 types of vevents.

Field	Type	Description
calendar_id	integer	(required) Linked "Calendar" identifier
start	datetime	The start time of the event ( ex: "2010-01-22 15:00:00" ). For a recurring event, this is the start time of the first instance.
end	datetime	The end time of the event ( ex: "2010-01-22 15:15:00" ). For a recurring event, this is the end time of the first instance.
taker	string(255)	Last and first names of the person that created the vevent. It can be either a pro via the Pro Interface, or a fiche via the appointment module.
colorref	string(7)	The color of the event as displayed on the Pro Interface, in hexadecimal format #RRGGBB (example: #FF6600)
text	text	The text describing the event. On appointments, text contains the last and first names of the « Fiche » object linked.
deleted	boolean	When true, the event is deleted (default: 0).

Fields for Vevent of type "appointments"

Field	Type	Description
intervention_id	integer	Linked «Intervention» identifier
fiche_id	integer	Linked «Fiche» identifier
state	integer	Status of the event. Possible values are: 0 (no value) - this is the default state 1 (attended) 2 (no-show) 3 (pending)
mailtime	datetime	Date and time at which the E-mail reminder will be sent.
smstime	datetime	Date and time at which the SMS reminder will be sent. Important The SMS reminder will be sent only if the "smsreminder" attribute of the same event equals to 1, and if the related Group is configured to send SMS reminders (smsreminder != 0).
smsreminder	boolean	Send a SMS reminder for this event (default: 0)
from_web	boolean	When true, indicates that the appointment has been created from the appointment module (from web) (default: 0)
comments	text	Comments about the event

Customised fields for appointments

See page : Customfields API

Fields for Vevent of type "availabilities"

Field	Type	Description
availableInterventions	text	List of comma separated IDs of "interventions". These interventions will be available for online booking during the specified slot, other interventions will not. If the list is empty (NULL or empty string), all interventions will be available (example: ",23,343,") (default: NULL).
type	string(20)	Important This field is required to have a value equal to VfreebusyEvent in the case of availabilities (default: empty string)

Fields for Vevent of type "notes"

Field	Type	Description
note	boolean	When true, this event is a note. Important start and end fields must both be set to midnight (ex: start = end = "2010-01-22 00:00:00"), the duration of the note must be considered null. (default: 0)

Recurring events

Important The Vevent of type "appointments" can't be recurring!

The Vevents of type "plage", "availability", and "note" can be recurring for more convenience, for example, to avoid manually entering the lunch break time slot for for each day.

A repeating pattern is set with the help of the field rrule, as per the functioning defined by the RRULE field in iCalendar standard. However, we don't handle every pattern of the standard (only "Daily/Weekly/Monthly/Yearly" repetitions).

The exceptions to the recurrence rule are defined by the field repeat_exceptions.

Fields for repetition

Important The fields repeat_freq, repeat_intervall, repeat_count and repeat_byday are obsolete and should no longer be used (see Appendix Earlier format for repetition).

Field	Type	Description
rrule	text	Defines the repeating pattern (frequency, duration, etc.), using the following value types : FREQ (required) : possible values: "DAILY", "WEEKLY", "MONTHLY", "YEARLY" INTERVAL : number >= 1 COUNT : number >= 2 UNTIL : date in format YYYYmmddTHHMMSSZ, expressed in UTC timezone. BYDAY : if FREQ=WEEKLY : possible values: "MO", "TU", "WE", "TH", "SA", "SU" or combination of days separated by commas (ex: "MO,TU,WE,TH,FR") if FREQ=MONTHLY : value composed of a number between -5 et 5 and a day of the week (ex: "1FR", "2MO" or "-1WE") Each key and value is associated with the symbol "equal" = and each key/value pair is separated from each other by a semi-colon ; (ex: FREQ=WEEKLY;INTERVAL=2;BYDAY=TU,TH). see Detailed repetition examples
repeat_exceptions	text	List of dates separated by commas, in format YYYY-mm-dd 00:00:00, that will be excluded from the repeating pattern. Thus, the events will not be repeated on the dates in this list. (ex : "2016-03-22 00:00:00,2016-03-23 00:00:00")
repeat_until	datetime	End date for repetition (translated in group's timezone) Important The field repeat_until is a Read Only value, it is generated automatically from the value of key UNTIL of the rrule field, if exists.

Repetition examples

1 Repeating every 2 days, without end

  rrule = "FREQ=DAILY;INTERVAL=2"

In the example above,

• The frequency of repetition with key FREQ is "DAILY" (= occurring daily)
• The interval of repetition with key INTERVAL is 2 (= repeat every 2nd day)

2 Repeat each week on Monday and Wednesday for 5 times

  rrule = "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE;COUNT=5"

If we suppose here that start = "2016-01-18 10:00:00" (starting of event - Monday, 18th January 2016 at 10:00AM), the event will also repeat at 10:00AM on Wednesday, 20th January 2016; Monday, 25th January 2016; Wednesday 27 January 2016 and Monday 1st February 2016 (we have overall 5 occurrence including the original event).

In the example above,

• The frequency of repetition with key FREQ is "WEEKLY"
• The interval of repetition with key INTERVAL is 1 (= every week)
• The weekdays to repeat with key BYDAY has possible values from Monday to Sunday : "MO", "TU", "WE", "TH", "FR", "SA", "SU". It is also possible to repeat event on multiple days in a week, by separating them with commas (ex : BYDAY=MO,WE for a repetition on Monday and Wednesday).
• The number of occurrences with key COUNT (number >= 2)
  Important The original event is also counted as an occurrence (thus "COUNT=2" correspond to the original event + 1 repetition).

3 Repeating every 3 months, on 10th day of the month, until 10th February 2017 (included)

Here we suppose that start = "2016-02-10 16:00:00" and end = "2016-02-10 18:00:00", and that the group has a timezone configured as timezone = "Paris".

Therefore, rrule is written as:

  rrule = "FREQ=MONTHLY;INTERVAL=3;UNTIL=20170201T170000Z"

Here, the event of 10th February 2016 will thus be repeated on 10th May 2016, 10th August 2016, 10th November 2016, and 10 February 2017.

In the example above,

• The frequency of repetition with key FREQ is "MONTHLY"
• The interval of repetition with key INTERVAL is 3 (= every 3 months)
• The end date and time of the repetition with key UNTIL is in format YYYYmmddTHHMMSSZ, in the UTC timezone. Here we have "20170210T170000Z" which corresponds to: year 2017, month 02 (= February), day 10 (= 10th day of the month), at 17h (in UTC timezone). The end time of the event is 18h in "Paris" timezone (CET, UTC+01:00), which is 17h in UTC. Hence, we set the end of repetition on 10th February 2017 at 18h Paris Time, after the last occurrence of the event has taken place on this day.

Important In this mode, the Vevent must start before the value of UNTIL.

Important The keys COUNT and UNTIL are exclusive, and only one of these should be used at a time.

4 Repeating every 2nd Tuesday of the month

  rrule = "FREQ=MONTHLY;INTERVAL=1;BYDAY=2TU"

If we suppose here that the event starts on Tuesday, 9th February 2016 at 9h30 (start = "2016-02-09 09:30:00"), then the event will repeat at 9h30 on Tuesday 8th March 2016, Tuesday 12th April 2016, Tuesday 10th May 2016, etc.

In the example above,

• The frequency of repetition with key FREQ is "MONTHLY"
• The interval of repetition with key INTERVAL is 1 (= every month)
• The repeating unit with the key BYDAY is "2TU" which means "2nd Tuesday of the month". similarly, "1MO" means "first Monday of the month", "3WE" means "third Wednesday of the month", and "-1FR" means "last Friday of the month".

5 Repeating annually on 21st June, except on 21st June 2018

  rrule = "FREQ=YEARLY;INTERVAL=1"
  repeat_exceptions = "2018-06-21 00:00:00"

If we suppose here that the event starts on Tuesday, 21st June 2016 at 19h (start = "2016-06-21 19:00:00"), then the event will repeat at 19h on 21st June 2017, 21st June 2019, 21st June 2020, etc.

In the example above,

• The frequency of repetition with key FREQ is "YEARLY"
• The interval of repetition with key INTERVAL is 1 (= every year)

We also specify

• the exceptions in the field repeat_exceptions, in format YYYY-mm-dd 00:00:00
• If multiple values are to be added in the field repeat_exceptions, they must be separated by commas, for example : repeat_exceptions = "2018-06-21 00:00:00,2019-06-21 00:00:00"

Appendix Earlier format for repetition

Important The fields repeat_freq, repeat_intervall, repeat_count and repeat_byday are obsolete and should no longer be used.

Migrating towards the new format :

For example, the repeating pattern in earlier format :

  start = "2016-02-01 08:00:00"
  end   = "2016-02-01 09:00:00"
  repeat_freq = "weekly"
  repeat_intervall = 2
  repeat_until = "2016-06-01 09:00:00"
  repeat_byday = 62

should now be translated into the new format :

  start = "2016-02-01 08:00:00"
  end   = "2016-02-01 09:00:00"
  rrule = "FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,TU,WE,TH,FR;UNTIL=20160601T070000Z"

How to convert the value of repeat_byday in the new format key BYDAY ?

The value of repeat_byday should be converted into a binary number and the days of the week that have the value 1 should be picked. For example, the value repeat_byday = 62 is 0111110 in binary:

We pick therefore, from the table (from right to left), the following days : BYDAY=MO,TU,WE,TH,FR.