Display a more user-friendly error for integration errors

chrome/content/zotero/xpcom/integration.js

@@ -204,7 +204,7 @@ Zotero.Integration = new function() {
 			throw new Zotero.Exception.Alert("integration.error.notInstalled",
 				[], "integration.error.title");
 		}	
-	},
+	};
 	
 	/**
 	 * Executes an integration command, first checking to make sure that versions are compatible
@@ -252,49 +252,10 @@ Zotero.Integration = new function() {
 			await document.setDocumentData(session.data.serialize());
 		}
 		catch (e) {
-			if(!(e instanceof Zotero.Exception.UserCancelled)) {
+			if (!(e instanceof Zotero.Exception.UserCancelled)) {
-				try {
+				Zotero.Integration._handleCommandError(document, e);
-					var displayError = null;
+			}
-					if(e instanceof Zotero.Exception.Alert) {
+			else {
-						displayError = e.message;
-					} else {
-						if(e.toString().indexOf("ExceptionAlreadyDisplayed") === -1) {
-							displayError = Zotero.getString("integration.error.generic")+"\n\n"+(e.message || e.toString());
-						}
-						if(e.stack) {
-							Zotero.debug(e.stack);
-						}
-					}
-					
-					if(displayError) {
-						if (Zotero.Integration.currentSession && Zotero.Integration.currentSession.progressBar) {
-							Zotero.Promise.delay(5).then(function() {
-								Zotero.Integration.currentSession.progressBar.hide();
-							});
-						}
-						
-						var showErrorInFirefox = !document;
-						
-						if(document) {
-							try {
-								await document.activate();
-								await document.displayAlert(displayError, DIALOG_ICON_STOP, DIALOG_BUTTONS_OK);
-							} catch(e) {
-								showErrorInFirefox = true;
-							}
-						}
-						
-						if(showErrorInFirefox) {
-							Zotero.Utilities.Internal.activate();
-							Components.classes["@mozilla.org/embedcomp/prompt-service;1"]
-								.getService(Components.interfaces.nsIPromptService)
-								.alert(null, Zotero.getString("integration.error.title"), displayError);
-						}
-					}
-				} finally {
-					Zotero.logError(e);
-				}
-			} else {
 				// If user cancels we should still write the currently assigned session ID
 				await document.setDocumentData(session.data.serialize());
 			}
@@ -341,6 +302,60 @@ Zotero.Integration = new function() {
 		}
 	};
 	
+	this._handleCommandError = async function (document, e) {
+		try {
+			const supportURL = "https://www.zotero.org/support/kb/debugging_broken_documents";
+			var displayError;
+			if (e instanceof Zotero.Exception.Alert) {
+				displayError = e.message;
+			}
+			else {
+				if (e.toString().indexOf("ExceptionAlreadyDisplayed") === -1) {
+					displayError = Zotero.getString("integration.error.generic")
+						+ "\n\n" + Zotero.getString("integration.error.seeTroubleshootingInfo");
+				}
+				else {
+					return;
+				}
+				if (e.stack) {
+					Zotero.debug(e.stack);
+				}
+			}
+			
+			if (Zotero.Integration.currentSession && Zotero.Integration.currentSession.progressBar) {
+				Zotero.Promise.delay(5).then(() =>
+					Zotero.Integration.currentSession.progressBar.hide());
+			}
+			
+			
+			// display alerts in the document processor
+			if (document) {
+				try {
+					await document.activate();
+					let index = await document.displayAlert(displayError, DIALOG_ICON_STOP, DIALOG_BUTTONS_YES_NO);
+					if (index == 1) {
+						Zotero.launchURL(supportURL);
+					}
+					return;
+				}
+				catch (e) {
+					Zotero.debug("Integration: An error occurred while trying to display an alert. Falling back to Zotero");
+					Zotero.logError(e);
+				}
+			}
+			
+			Zotero.Utilities.Internal.activate();
+			let ps = Services.prompt;
+			let index = ps.confirm(null, Zotero.getString('integration.error.title'), displayError);
+			if (index == 1) {
+				Zotero.launchURL(supportURL);
+			}
+		}
+		finally {
+			Zotero.logError(e);
+		}
+	};
+	
 	/**
 	 * Displays a dialog in a modal-like fashion without hanging the thread 
 	 * @param {String} url The chrome:// URI of the window

chrome/locale/en-US/zotero/zotero.properties

@@ -873,6 +873,7 @@ integration.error.styleNotFound = The citation style %S could not be found.
 integration.error.macWordSBPermissionsMissing.title = Missing Permission
 integration.error.macWordSBPermissionsMissing = Zotero does not have permission to control Word. To grant this permission:\n\n1) Open System Preferences\n2) Click on “Security & Privacy”\n3) Select the “Privacy” tab\n4) Find and select “Automation” on the left\n5) Check the checkbox for “Microsoft Word” under “Zotero”\n6) Restart Word
 integration.error.macWordSBPermissionsMissing.pre2016 = If “Microsoft Word” does not appear under “Automation”, make sure you are running Word 2011 version 14.7.7 or later.
+integration.error.seeTroubleshootingInfo	= Would you like to see the troubleshooting instructions?
 
 integration.replace						= Replace this Zotero field?
 integration.missingItem.single			= The highlighted citation no longer exists in your Zotero database. Do you want to select a substitute item?