Zum Hauptinhalt springen

Protocol

The Protocol module allows participants to to collaboratively edit a document in real-time by utilizing Etherpad. Etherpad is an open source online editor that allows users to collaboratively edit a document in real-time. The Etherpad is a separate process that runs along the controller. When in a room, participants can click an access link that opens another browser tab where the Etherpad document (pad) can be accessed.

The Etherpad's state is lazily initialized for each room. To initialize and make the etherpad accessible, the moderator has to select one or more writers from the present participants. Once selected, each participant will receive either a write- or read url, depending on if they were picked as a writer.

Each participant has an individual etherpad session that gets set as cookie on the client by the ep_auth_session Etherpad plugin. The plugin provides the additional endpoint /auth_session that takes the clients session id as a query parameter, sets the session cookie on the clients browser, and the forwards the client to the actual pad.

A participants write access can be revoked with the deselect_write message. The participant will then receive a new read url.

Joining the room

JoinSuccess

The join_success control event contains the module-specific fields described below.

Fields

The protocol module does not provide data in the join_success message.

Joined

When joining a room, the joined control event sent to all other participants does not contain module-specific data.


Commands

SelectWriter

The SelectWriter message can be sent by a moderator to select a number of participants as writers. The underlying etherpad state gets lazily initialized when this message is received by the controller.

Can return Error of kind insufficient_permissions, currently_initializing failed_initialization.

Fields

FieldTypeRequiredDescription
participant_idsstring[]yesAn array of participant ids that shall get write access to the etherpad pad.
Example
{
"action": "select_writer",
"participant_ids": ["00000000-0000-0000-0000-000000000000", "00000000-0000-0000-0000-000000000001"]
}

Response

Each participant receives an access url. Depending if they were selected as a writer they will receive either a WriteUrl or ReadUrl.


DeselectWriter

The DeselectWriter message can be sent by a moderator to deselect a number of writers.

The deselected participants will have their write session invalidated and will receive a read access url.

Response

Each selected participant that has write access, receives a new read-only access url.

Can return Error of kind insufficient_permissions, currently_initializing, not_initialized or invalid_participant_selection.

Fields

FieldTypeRequiredDescription
participant_ids[string]yesAn array of participant ids that shall lose write access to the etherpad pad.

Examples

{
"action": "deselect_writer",
"participant_ids": ["00000000-0000-0000-0000-000000000000", "00000000-0000-0000-0000-000000000001"]
}

GeneratePdf

Allows a moderator to generate a PDF from the current contents of the protocol.

Access to the PDF is given to all participants in the room via the PdfAsset event.

Response

A PdfAsset message with the asset id of the PDF document is sent to every participant in the room.

Fields

FieldTypeRequiredDescription
actionenumyesMust be "generate_pdf".

Example

{
"action": "generate_pdf",
}

Events

WriteUrl

Received by participants that got selected as a writer by a moderator. (See SelectWriter)

Fields

FieldTypeRequiredDescription
urlstring[]yesA url to the etherpad that grants write access
Example
{
"message":"write_url",
"url":"http://localhost/auth_session?sessionID=s.session&padName=protocol&groupID=g.group"
}

ReadUrl

Received by all participants that did not get selected as a writer by a moderator. (See SelectWriter)

Fields

FieldTypeRequiredDescription
urlstring[]yesA url to the etherpad that will set write access
Example
{
"message":"read_url",
"url":"http://localhost/auth_session?sessionID=s.session&padName=protocol&groupID=g.group"
}

Control Update

The update message in the control namespace contains the current etherpad access level of the updated participant.

This information is only present when the receiver is a moderator.

An update message is issued when a participants etherpad access level changes.

Fields

FieldTypeRequiredDescription
readonlyboolyesThe current access level of the participant

Examples

{
"namespace": "control",
"timestamp": "2022-06-14T17:18:52Z",
"payload": {
"message": "update",
"id": "24500907-334b-47d4-b54a-00db40b9a613",
...
"protocol": {
"readonly": false
}
}
}

PdfAsset

Contains the filename and asset id of the PDF document of the protocol.

This event is received by every participant when a moderator generates a PDF document for the protocol.

Fields

FieldTypeRequiredDescription
messageenumyesIs "pdf_asset".
filenamestringyesThe file name of the PDF document of the protocol
asset_idstringyesThe id of the PDF document asset

Example

{
"message": "pdf_asset",
"filename": "vote_protocol_2023-01-16_12:34:56-UTC.pdf",
"asset_id": "5be191a8-3eb1-4c79-afe1-d4857dcf0e73"
}

Error

An error has occurred while issuing a command.

Fields

FieldTypeRequiredDescription
InsufficientPermissionsstring[]yesThe requesting user has insufficient permissions for the operation
CurrentlyInitializingstring[]yesA moderator just send a SelectWriter message and the etherpad is still initializing
FailedInitializationstring[]yesThe etherpad initialization failed
NotInitializedstring[]yesThe etherpad is not yet initialized
Example
{
"message":"error",
"error":"insufficient_permissions"
}
{
"message":"error",
"error":"currently_initializing"
}
{
"message":"error",
"error":"failed_initialization"
}
{
"message":"error",
"error":"not_initialized"
}