The LibreOffice plugin uses a simple wire protocol to communicate with Zotero. (The Word for Mac and Word for Windows plugins both run in process, and use AppleEvents and COM respectively to communicate with the word processor.) The below documentation applies to Zotero LibreOffice Integration 3.5.3 and newer.

The Firefox or Zotero Standalone process operates a server on port 23116, which the extension residing within LibreOffice connects to. All frames consist of a 32 bits specifying the transaction ID, a big-endian 32-bit integer specifying the length of the payload, and the payload itself, which is either UTF-8 encoded JSON or an unescaped string beginning with “ERR:”.

There are two types of commands: integration command, sent by the word processor to Zotero initiate an operation (e.g., to add a new citation), and word processor commands, sent from Zotero to the word process to retrieve data from a document or to make changes to the document. Integration commands are sent from the word processor to Zotero, and must never receive a response. Word processor commands are sent from Zotero to the word processor, and must always receive a response.

The transaction ID allows Zotero to determine whether the given frame is a response to another frame. When the client sends an integration command, it must send 0 as the transaction ID. Word processor commands always specify a non-zero transaction ID, and the response to these commands must maintain the same transaction ID.

In order to add a citation to a document, LibreOffice sends the following:

                TRANS ID    LENGTH      PAYLOAD
HEXADECIMAL     00 00 00 00 00 00 00 0C 22 61 64 64 43 69 74 61 74 69 6F 6E 22
INTERPRETATION  0           11          "addCitation"

Zotero then responds by asking for the active document, and supplying the API version it supports:

                TRANS ID    LENGTH      PAYLOAD
HEXADECIMAL     00 00 00 01 00 00 00 24 5B 22 41 70 70 6C 69 63 61 74 69 6F (...)
INTERPRETATION  1           36          ["Application_getActiveDocument", 3]

The client then sends a response consisting of the API version it supports and the document ID:

                TRANS ID    LENGTH      PAYLOAD
HEXADECIMAL     00 00 00 01 00 00 00 24 5B 33 2C 20 31 5D
INTERPRETATION  1           6           [3, 1]

You can observe frame payloads sent between Zotero and LibreOffice in the Zotero debug output.

These commands are sent from the word processor to Zotero, and do not receive a response. The command payload is always a quoted string.

These commands are sent from Zotero to the word processor. They must always receive a response. The command payload is always JSON-encoded in the form

[COMMAND_NAME, [...PARAMETERS...]]

If the request is successful, the client must send a response with a JSON-encoded payload. This response is often null if the command returns no output, but may also be an array, an integer, a string, or a boolean value depending on the command.

If the request is unsuccessful, the client must send a response with the payload:

ERR:(Error string goes here).

Zotero will cancel the current operation, log this error, and present it to the user using the Document_displayAlert command if possible. If the subsequent Document_displayAlert command fails, Zotero will present the error using its own dialog box.

Gets information about the client and the currently active document.

Shows an alert.

(Integer) The index of the button pressed, according to the value of buttons sent as a parameter.

OK = 1

CANCEL = 0
OK = 1

NO = 0
YES = 1

CANCEL = 0
NO = 1
YES = 2

Brings the document to the foreground. This is a no-op on non-Mac systems.

null

Indicates whether a field can be inserted at the current cursor position.

(Boolean) Whether a field can be inserted.

Stores a document-specific persistent data string. This data contains the style ID and other user preferences.

(Array)

null

Retrieves data string set by setDocumentData.

(String) The document data string.

Indicates whether the cursor is in a given field. If it is, returns information about that field.

Either null, indicating that the cursor isn't in a field, or (Array)

Inserts a new field at the current cursor position.

(Array)

Get all fields present in the document, in document order.

(Array)

TODO

TODO

Indicates that the given documentID will no longer be used and associated resources may be freed.

null

Deletes a field from the document (both its code and its contents).

null

Moves the current cursor position to encompass a field.

null

Removes the field code from a field, leaving it as plain text.

null

Sets the (visible) text of a field.

null

Gets the (visible) text of a field.

(String) The (visible) text

Sets the (hidden, persistent) code of a field.

null