Skip to main content

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"
}