A. Introduction - some concepts

A.1. What is a plugin?

Shortly put, a plugin is a part of Indico that is optional. They usually deal with external systems that the organization using Indico may or may not have. Therefore, organizations that use Indico can easily decide to use or not use them, or even remove their code from Indico.

Plugins in Indico are organized into Plugin Systems. Collaboration is one of those systems, and deals with videoconference systems (where you can book videoconferencing resources) and Service Requests such as a request to record an event. The first kind of plugins deal with external systems and use these system's APIs. The second kind of plugins usually help communicate (for example by email) a service responsible and an event manager. Other Plugin Systems in Indico include Epayment and Room Booking.

A.2. The Collaboration plugins core

The Collaboration plugins core (or core for short in this guide) is the part of Indico that interacts with the plugins:

• It defines the interface between Indico and the plugins.
• It calls the plugins' functions when it is necessary.
• It takes care of many common tasks so that the plugins do not have to implement them.
• It provides helper / utility functions to the plugins.

The core is present both in the server side (Python code) and the client side (HTML, CSS and Javascript code).

A.3. Bookings and requests

Among the Collaboration plugins, there are two sub-types of plugins so far:

• Booking plugins: they provide the user with a form where they can book resources in an external system. In most cases, there can be multiple bookings of the same type for the same Indico event. This means that in the database, there will be multiple "Booking" objects of the same type associated to an event.
• Request plugins: they provide the user with a form where they can request a service. For each Indico event, there can be only one Request of a given type.

Examples of Booking plugins are: EVO, CERNMCU, Vidyo. Examples of Reques plugins are Recording Request and Webcast Request.

A.4. Pages generated by Collaboration plugins

The Collaboration plugins will generate pages / information that will appear in several places in Indico:

• In the management interface of an Indico Event, in the Video Services section (left menu). Each plugin will appear in a given tab. Several plugins can share a tab (such as EVO, CERNMCU and Vidyo) or be alone in their own tab (like Recording Request).

• In the display page of events, for the Booking plugins. When a booking has been done in an external system, the Event manager can decide to show information about it on the event's display page to allow normal users to join the Videoconference.

• In the Server Admin interface, in the Plugins section, under the Collaboration tab. Each plugin will be represented in a sub-tab under which the plugin's options and actions will appear.

• In the Video Services Overview page, where Bookings and Requests are indexed (if the respective plugin wishes to) and queries can be made to have a global view.

B. Creating a new plugin

[TODO] This section will explain how to have a minimal skeleton of a plugin.

C. Plugin file structure

[TODO] This section will explain the different files of a Plugin, giving a short summary for each and specifying if a given file is optional or compulsory.

D. Configuring a plugin

D.1. Plugin characteristics

Different plugins cover different concepts or have different needs. In the collaboration.py file of each plugin, inside the CSBooking class, several class attributes can be defined that will help the Collaboration core know what to expect when dealing with the plugin.

All these class attributes are defined with their default values in the CSBookingBase class inside MaKaC/plugins/Collaboration/base.py. If you like the default value of a class attribute, you do not need to write it again in your CSBooking class, although sometimes it is not bad to do it anyway, for clarity.

List of class attributes and their functions:

• _allowMultiple: True by default. Should be False if the plugin does not wish to allow that more than one CSBooking object of its type should be created for each Indico Event. This is what distinguishes Booking-type plugins from Request-type plugins.

• _hasStart: False by default. Should be True if the plugin has a "start" concept, which means a "Start" button will appear next to a created Booking, allowing the Event Manager to start the Videoconference.

• _hasStop: False by default. Should be True if the plugin has a "stop" concept, which means a "Stop" button will appear next to a created Booking, allowing the Event Manager to stop the Videoconference.

• _hasStartStopAll: False by default. Should be True if the plugin has _hasStart == True and/or _hasStop == True, and they want "Start All" / "Stop All" buttons to appear for their bookings. These buttons will allow to start / stop all of the bookings at once (of all the plugins in the same tab who have _hasStartStopAll == True).

• _requiresServerCallForStart : False by default. Should be True if the plugin has _hasStart == True and wishes that the CSBooking object on the server side should be notified when the Event Manager clicks on the "Start" button, by calling CSBooking 's _start() method.

• _requiresServerCallForStop : False by default. Analogous to _requiresServerCallForStart, but for the "Stop" action.

• _requiresClientCallForStart : False by default. Should be True if the the plugin wishes a Javascript function to be called when the Event Manager presses the "Start" button. The function called will be the start() function in Main.js.

• _requiresClientCallForStop : False by default. Should be True if the the plugin wishes a Javascript function to be called when the Event Manager presses the "Stop" button. The function called will be the stop() function in Main.js.

• _hasCheckStatus: False by default. Should be True if the plugin has a "check status" concept, which means a "Check status" button will appear next to the Booking / Request status, allowing the Event Manager to reload all the information of the Booking / Request from the Indico Server into his browser.

• _hasAcceptReject: False by default. Should be True if the plugin has a "check status" concept. In that case, "Accept" and "Reject" buttons will appear next to the Booking / Request status, only visible to plugin admins or server admins, who can use them to change the state of the Booking / Request object to "Accepted" or "Rejected".

• _needsBookingParamsCheck : False by default. Should be True if the the plugin wishes to check the Booking / Request parameters in the server after the booking is created / edited. In that case, the _checkBookingParams() method of the plugin's CSBooking class will be called to verify the parameters.

• _needsToBeNotifiedOnView: False by default. Should be True if the plugin wishes its CSBooking objects to be notifies when an user "sees" the booking, for example when returning the list of booking. The _notifyOnView() method of the plugin's CSBooking class will be called.

• _shouldBeIndexed: True by default. Should be False if the plugin does not wish to allow its CSBooking objects to be indexed, i.e. to appear in the Video Services Overview page.

• _commonIndexes: [] by default. A list of strings. Useful when _shouldBeIndexed == True. If left empty, the plugin's CSBooking object will appear in the "All" index and in the plugin's own index, but not in any shared index. If set to ["Videoconference"], for example, they will also appear in the common "Videoconference" index. For example, currently EVO, CERNMCU and Vidyo bookings appear in this index.

• _hasStartDate: True by default. Should be True if the plugin's CSBooking objects have a start date attribute. This will allow the Collaboration Core to index these objects by start date.

• _hasEventDisplay : False by default. Should be True if the plugin's CSBooking objects wish to be displayed in the Event's display page.

• _hasTitle: False by default. Useful if _hasEventDisplay == True. Should be True if the plugin's CSBooking objects have a Title. This will affect how the objects appear in the Event display page.

• _adminOnly: False by default. If set to True, only Server Admins, Video Services Admins, and Plugin Admins (for the corresponding Plugin) will be able to interact with the plugin / see the plugin's tab in the Video Services section of the events. It will not stop normal users from seeing information about bookins in Events Display pages (if any, and if the booking is not Hidden).

It is recommended to see the values of these class attributes defined by each existing plugin in their collaboration.py file.

D.2. Plugin options

As other types of plugins, Collaboration plugins can define Options with different attributes. The options' values will be stored in the database. Options are useful to store things such as the remote system URL, the plugin list of admins, etc. In other words, things that should be in the database not attached to any Event in particular, but of global scope in Indico.

Options are defined in the options.py file. More information on the declaration syntax, and how to read their values in your plugin's code, can be found in the Plugin System page, in the corresponding section.

It's compulsory for Collaboration Plugins to declare the following options:

• tab: the name of the tab, in the Video Services section of an Indico Event's management interface, that this plugin will appear in.

• allowedOn: a list of one to three strings. The strings inside the list can be: "conference", "meeting" or "simple_event" (this last one representing lecture events). The Collaboration Core will allow the plugin to appear only for these kind of events.

• admins: put an empty list as defaultValue. Here the plugin admins (Avatar objects) will be stored.