====== HTTP Citing Protocol ======

The Google Docs plugin uses a simple HTTP protocol to communicate with Zotero. The below documentation applies to Zotero 6.0 and newer.

===== Basics =====

Zotero operates a server on port 23119 for [[dev/client_coding/connector_http_server|Zotero Connector integration]]. It includes endpoints for integrating with Zotero citing functionality. The integrating plugin or application only needs to be able to send HTTP JSON requests to fully implement the citing protocol.

A single [[#word_processor_commands|citing integration command]] is implemented as a series of requests and responses to the HTTP endpoints, constituting a transaction. The integration client begins a transaction by sending a request to [[http://127.0.0.1:23119/connector/document/execCommand]] which responds a command to be executed by the client, then subsequent requests with executed command results are made to [[http://127.0.0.1:23119/connector/document/respond]] until a transaction is complete.

==== An example ====

In order to add a citation to a document, the implementing client sends the following to [[http://127.0.0.1:23119/connector/document/execCommand]]:

<code>
{
  "command":"addEditCitation",
  "docId":"1ro9AmDxrwbys-xjazJqQG7UlSbBC76CU5xRJ71I8UjE"
}
</code>

Zotero then responds by asking for the active document:

<code>
{
  "command":"Application.getActiveDocument",
  "arguments":[]
}
</code>

The client then sends a response to [[http://127.0.0.1:23119/connector/document/respond]] consisting of the the document ID and config options for the implementing client:

<code>
{
  "documentID":"1ro9AmDxrwbys-xjazJqQG7UlSbBC76CU5xRJ71I8UjE",
  "outputFormat":"html",
  "supportedNotes":["footnotes"]
}
</code>

You can observe the communication between Zotero and Google Docs in the Zotero Connector background page, which is accessed at ''about:extensions'' on Chrome by enabling Developer mode and clicking "background page" for Zotero Connector, or at ''about:debugging'' on Firefox by clicking "Debug" for Zotero connector. The requests are listed under the Network tab in the developer tools window.

===== Integration Commands =====

These commands are sent from the word processor to Zotero, and do not receive a response. The command payload always follows this format.

<code>
{
  "command":"<Command>",
  "docId":"<Document ID>" // an unique document identifying string
}
</code>

^ Command ^ Description ^
| "addEditCitation" | Add a new or edit an existing citation |
| "addEditBibliography" | Add a new or edit an existing bibliography |
| "addNote" | Insert a Zotero note into the document |
| "refresh" | Refresh all fields in the document, verifying that they match expectations |
| "removeCodes" | Remove field codes from the document |
| "setDocPrefs" | Change the citation style or other document parameters |
| "exportDocument" | Export the citations in the document to a format importable in other word processors |

An up-to-date command list is always available by looking at the methods of [[https://github.com/zotero/zotero/blob/master/chrome/content/zotero/xpcom/integration.js#L619|Zotero.Integration.Interface]].

If Zotero responds with a 503 HTTP response, it means that another integration transaction is already in progress. If your integration client initiates an integration transaction and fails to complete it by either returning an error or responding to requests until ''#Document.complete'' is issued the Zotero integration layer will continuously respond with 503 until it is restarted. 

===== Word Processor Commands ====

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

<code>
{
  "command":"<Command Name>",
  "arguments":[]
}
</code>

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:

<code>
{
  "error": "<Error Name>",
  "message": "<Error Message>",
  "stack": "<Optional error stack Object or String>"
}
</code>

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.

A full and up-to-date API of commands is available as part of [[https://github.com/zotero/zotero/blob/master/test/tests/integrationTest.js|Zotero Integration tests]] and [[https://github.com/zotero/zotero-libreoffice-integration/blob/master/components/zoteroOpenOfficeIntegration.js#L358||LibreOffice plugin code]].

==== Application.getActiveDocument ====

Gets information about the client and the currently active document.

=== Parameters ===

N/A

=== Returns ===

| documentID | %%Integer|String%% | An ID corresponding to the document that is currently active |
| outputFormat | %%String%% | Either "html" or "rdt". Defaults to "html" |
| supportedNotes | %%Array%% | Supported options are an empty array if no Note support, "footnotes" and/or "endnotes". Note styles will not be available if this option is an empty array. Default to ["footnotes"]

==== Document.displayAlert ====

Shows an alert.

=== Parameters ===

| dialogText | String | The text to display inside the dialog. |
| icon | Integer| One of:<code>
DIALOG_ICON_STOP = 0
DIALOG_ICON_NOTICE = 1
DIALOG_ICON_CAUTION = 2
</code> |
| buttons | Integer | One of:<code>
DIALOG_BUTTONS_OK = 0
DIALOG_BUTTONS_OK_CANCEL = 1
DIALOG_BUTTONS_YES_NO = 2
DIALOG_BUTTONS_YES_NO_CANCEL = 3
</code> |

=== Returns ===

(Integer) The index of the button pressed, according to the value of buttons sent as a parameter.
| DIALOG_BUTTONS_OK | <code>OK = 1</code> |
| DIALOG_BUTTONS_OK_CANCEL | <code>CANCEL = 0
OK = 1</code> |
| DIALOG_BUTTONS_YES_NO | <code>NO = 0
YES = 1</code> |
| DIALOG_BUTTONS_YES_NO_CANCEL | <code>CANCEL = 0
NO = 1
YES = 2</code> |

==== Document.activate ====

Brings the document to the foreground.

=== Parameters ===

N/A

=== Returns ===

null

==== Document.canInsertField ====

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

=== Parameters ===

N/A
=== Returns ===

(Boolean) Whether a field can be inserted.

==== Document.setDocumentData ====

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

=== Parameters ===

| dataString | String | The data string|

=== Returns ===

null

==== Document.getDocumentData ====

Retrieves data string set by [[#setDocumentData]].

=== Parameters ===

N/A

=== Returns ===

(String) The document data string.

==== Document.cursorInField ====

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

=== Parameters ===

| fieldType | %%String%% | The type of field used by the document, always "Http" for HTTP integration and can be ignored |

=== Returns ===

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

| 0 | fieldID | %%Integer|String%% | A unique identifier corresponding to this field |
| 1 | fieldCode | %%Integer|String%% | The code stored within this field |
| 2 | noteIndex | %%Integer%% | The number of the footnote in which this field resides, or 0 if the field is not in a footnote. |

==== Document.insertField ====

Inserts a new field at the current cursor position.

=== Parameters ===

| fieldType | %%String%% | The type of field used by the document, either ReferenceMark or Bookmark |
| noteType | %%Integer%% | The type of note specified by the style:<code>
NOTE_IN_TEXT = 0
NOTE_FOOTNOTE = 1
NOTE_ENDNOTE = 2
</code>If noteType is not NOTE_IN_TEXT, the implementation should create a new note before inserting the field |

=== Returns ===

(Array)

| 0 | fieldID | %%Integer|String%% | A unique identifier corresponding to this field |
| 1 | fieldCode | %%Integer|String%% | The code stored within this field. Since no data has been set, this should be empty. |
| 2 | noteIndex | %%Integer%% | The number of the footnote in which this field resides, or 0 if the field is not in a footnote. |

==== Document.insertText ====

Inserts rich text (HTML) at cursor position. The rich text may contain citation placeholder hyperlinks (to https://www.zotero.org/?[placeholderID]) which are later converted to citations via [[#Document.convertPlaceholdersToFields]].

=== Parameters ===

| text | %%String%% | The text |


=== Returns ===

null

==== Document.getFields ====

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

=== Parameters ===

| fieldType | %%String%% | The type of field used by the document, always "Http" for HTTP integration and can be ignored |

=== Returns ===

(Array)

| 0 | fieldID | %%Array(Integer|String)%% | Unique identifiers for each field |
| 1 | fieldCode | %%Array(Integer|String)%% | The code stored in each field |
| 2 | noteIndex | %%Array(Integer)%% | The number of the footnote in which each field resides, or 0 if the field is not in a footnote |

==== Document.convert ====

Converts all fields in a document to a different fieldType or noteType. Called upon style change from a an in-text to note type or vice-versa

=== Parameters ===

| fields | %%Array(String)%% | Array of field IDs to be converted |
| toFieldType | %%Array(String)%% | Should be ignored |
| toNoteType | %%Array(Number)%% | Array of note types to be converted to. Each array entry corresponds to a field in the ''fields'' parameter and is one of<code>
NOTE_IN_TEXT = 0
NOTE_FOOTNOTE = 1
NOTE_ENDNOTE = 2
</code> |
| count | %%Number%% | Size of the above arrays |

=== Returns ===

null

==== Document.convertPlaceholdersToFields ====

Converts placeholders (which are text with links to https://www.zotero.org/?[placeholderID]) to fields and sets their field codes to strings in `codes` in the reverse order of their appearance

=== Parameters ===

| 0 | placeholderIDs | %%Array(String)%% | An array of placeholderID strings which are to be converted to citation fields in the document. |
| 1 | noteType | Number | Note type to convert citation placeholders to. Is one of<code>
NOTE_IN_TEXT = 0
NOTE_FOOTNOTE = 1
NOTE_ENDNOTE = 2
</code> |
| 2 | fieldType | Number | To be ignored |

=== Returns ===

Array of fields after conversion

(Array)

| 0 | fieldID | %%Array(Integer|String)%% | Unique identifiers for each field |
| 1 | fieldCode | %%Array(Integer|String)%% | The code stored in each field |
| 2 | noteIndex | %%Array(Integer)%% | The number of the footnote in which each field resides, or 0 if the field is not in a footnote |

==== Document.setBibliographyStyle ====

Sets parameters to be used to style the bibliography. Numbers are in [[https://en.wikipedia.org/wiki/Twip|twips]]

=== Parameters ===

| firstLineIndent | %%Number%% | First line indent of each bibliography paragraph |
| indent | %%Number%% | The indent of each bibliography paragraph |
| lineSpacing | %%Number%% | Paragraph line spacing |
| entrySpacing | %%Number%% | Line spacing between paragraphs |
| tabStops | %%Array(Number)%% | An array of tab stops |
| tabStopsCount | %%Number%% | Size of the ''tabStops'' array |

=== Returns ===

null

==== Document.complete ====

Indicates that the given documentID will no longer be used and associated resources may be freed. **NOTE: No further requests to http://127.0.0.1:23119/connector/document/respond should be made after this point**

=== Parameters ===

N/A

=== Returns ===

null

==== Field.delete ====

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

=== Parameters ===

| fieldID | %%Integer|String%% | The fieldID, as originally returned by [[#Document.cursorInField]], [[#Document.insertField]], or [[#Document.getFields]]|

=== Returns ===

null

==== Field.select ====

Moves the current cursor position to encompass a field.

=== Parameters ===

| fieldID | %%Integer|String%% | The fieldID, as originally returned by [[#Document.cursorInField]], [[#Document.insertField]], or [[#Document.getFields]]|

=== Returns ===

null

==== Field.removeCode ====

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

=== Parameters ===

| fieldID | %%Integer|String%% | The fieldID, as originally returned by [[#Document.cursorInField]], [[#Document.insertField]], or [[#Document.getFields]]|

=== Returns ===

null

==== Field.setText ====

Sets the (visible) text of a field.

=== Parameters ===

| fieldID | %%Integer|String%% | The fieldID, as originally returned by [[#Document.cursorInField]], [[#Document.insertField]], or [[#Document.getFields]]|
| text | %%String%% | The text |
| isRich | %%Boolean%% | Whether the text should be interpreted as RTF if Document.outputFormat is RTF, otherwise always true ||

=== Returns ===

null

==== Field.getText ====

Gets the (visible) text of a field.

=== Parameters ===

| fieldID | %%Integer|String%% | The fieldID, as originally returned by [[#Document.cursorInField]], [[#Document.insertField]], or [[#Document.getFields]]|

=== Returns ===

(String) The (visible) text

==== Field.setCode ====

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

=== Parameters ===

| fieldID | %%Integer|String%% | The fieldID, as originally returned by [[#Document.cursorInField]], [[#Document.insertField]], or [[#Document.getFields]]|
| code | %%String%% | The field code|

=== Returns ===

null

===== Other resources =====

See:

  * [[https://github.com/zotero/zotero/blob/01f3159b2f5baacff6423297d14d58230970f4ec/test/tests/integrationTest.js#L14-L183|Dummy Document Client]] implementation in Zotero tests 
  * The proper [[https://github.com/zotero/zotero-google-docs-integration/blob/267f45fb5203dec7bdbb9fea163b6d15bbe0ff16/src/connector/client.js#L112-L466|implementation of the HTTP client]] for our Google Docs plugin