IQSS · kcondon · Mar 15, 2017 · Dec 20, 2016 · Dec 20, 2016 · Dec 20, 2016
diff --git a/.gitignore b/.gitignore
@@ -16,10 +16,14 @@ ehthumbs.db
 Thumbs.db
 .vagrant
 *.pyc
+*.swp
 scripts/api/py_api_wrapper/demo-data/*
 scripts/api/py_api_wrapper/test_data/*
 scripts/api/py_api_wrapper/local-data/*
 doc/sphinx-guides/build
 faces-config.NavData
 src/main/java/BuildNumber.properties
-/nbproject/
+/nbproject/
+oauth-credentials.md
+
+/src/main/webapp/oauth2/newAccount.html
diff --git a/doc/Architecture/update-user-account-info.puml b/doc/Architecture/update-user-account-info.puml
@@ -0,0 +1,28 @@
+@startuml
+actor user
+participant DataverseUserPage as page
+participant "provider: AuthenticationProvider" as prv
+participant AuthenticationServiceBean as authSvc
+user --> page: HTTP GET
+== page init ==
+...
+page -> authSvc : lookupProvider(session.user)
+activate authSvc
+page <-- authSvc: provider
+deactivate authSvc
+...
+
+== Can Update User? ==
+page -> prv: isUserInfoUpdateAllowed()
+activate prv
+page <-- prv: true/false
+deactivate prv
+...
+
+== Save User ==
+user --> page: save()
+page -> page: udi = createUserDisplayInfo()
+page -> prv: updateUserInfo( udi )
+page -> authSvc: updateAuthentictedUser( session.user, udi )
+
+@enduml
diff --git a/doc/sphinx-guides/Makefile b/doc/sphinx-guides/Makefile
@@ -55,7 +55,7 @@ htmldeploy: html $(GUIDESDIR)
 	@echo
 	@cp -Rf build/html/* $(GUIDESDIR)
 	@echo "HTML documentation deployed to $(GUIDESDIR)."
-	@echo "It should now be available at http://<YOURHOST>:<YOURPORT>/guides."
+	@echo "It should now be available at http://<YOURHOST>:<YOURPORT>/guides/index.html"
 
 $(GUIDESDIR):
 	@mkdir -p $(GUIDESDIR) 

diff --git a/doc/sphinx-guides/source/_static/docsdataverse_org.css b/doc/sphinx-guides/source/_static/docsdataverse_org.css
@@ -1,4 +1,4 @@
-/*!
+*!
  * Start Bootstrap - Heroic Features HTML Template (http://startbootstrap.com)
  * Code licensed under the Apache License v2.0.
  * For details, see http://www.apache.org/licenses/LICENSE-2.0.
@@ -54,6 +54,13 @@ a.headerlink {
     text-decoration: none;
 }
 
+.fixedwidthplain {
+    color:#606060; 
+    font-family: Menlo, Monaco, Consolas, "Courier New", monospace; 
+}
+
+/* alternative formattings:  font-weight: bold; font-size: 110%; etc. */
+
 /* #sidebar.bs-sidenav.affix {
 	position: static;
 } REMOVED STATIC ToC */
diff --git a/doc/sphinx-guides/source/_static/installation/files/etc/shibboleth/shibAuthProvider.json b/doc/sphinx-guides/source/_static/installation/files/etc/shibboleth/shibAuthProvider.json
@@ -0,0 +1,5 @@
+{
+    "id":"shib",
+    "factoryAlias":"shib",
+    "enabled":true
+}
diff --git a/doc/sphinx-guides/source/_static/installation/files/root/auth-providers/github.json b/doc/sphinx-guides/source/_static/installation/files/root/auth-providers/github.json
@@ -0,0 +1,8 @@
+{
+    "id":"github",
+    "factoryAlias":"oauth2",
+    "title":"GitHub",
+    "subtitle":"",
+    "factoryData":"type: github | userEndpoint: NONE | clientId: FIXME | clientSecret: FIXME",
+    "enabled":true
+}
diff --git a/doc/sphinx-guides/source/_static/installation/files/root/auth-providers/google.json b/doc/sphinx-guides/source/_static/installation/files/root/auth-providers/google.json
@@ -0,0 +1,8 @@
+{
+    "id":"google",
+    "factoryAlias":"oauth2",
+    "title":"Google",
+    "subtitle":"",
+    "factoryData":"type: google | userEndpoint: NONE | clientId: FIXME | clientSecret: FIXME",
+    "enabled":true
+}
diff --git a/doc/sphinx-guides/source/_static/installation/files/root/auth-providers/orcid.json b/doc/sphinx-guides/source/_static/installation/files/root/auth-providers/orcid.json
@@ -0,0 +1,8 @@
+{
+    "id":"orcid",
+    "factoryAlias":"oauth2",
+    "title":"ORCID",
+    "subtitle":"",
+    "factoryData":"type: orcid | userEndpoint: https://api.orcid.org/v1.2/{ORCID}/orcid-profile | clientId: FIXME | clientSecret: FIXME",
+    "enabled":true
+}
diff --git a/doc/sphinx-guides/source/_static/util/clear_timer.sh b/doc/sphinx-guides/source/_static/util/clear_timer.sh
@@ -0,0 +1,33 @@
+#!/bin/sh
+
+# EBJ timers sometimes cause problems; utility to clear generated directories and database rows
+
+# assumes this script is being run as root, and that the postgres user had passwordless 
+# access to the database (local sockets, or appropriate environmental variables).
+
+# will restart glassfish if it's stopped; comment out the `start-domain` command at the end
+# if you'd like to avoid that.
+
+# directory where glassfish is installed
+GLASSFISH_DIR=/usr/local/glassfish4
+
+# directory within glassfish (defaults)
+DV_DIR=${GLASSFISH_DIR}/glassfish/domains/domain1
+
+# name of dataverse database
+DV_DB=dvndb
+
+# OS user for the database
+DB_USER=postgres
+
+# stop the glassfish domain (generates a warning if glassfish is stopped)
+${GLASSFISH_DIR}/bin/asadmin stop-domain
+
+rm -rf ${GLASSFISH_DIR}/${DV_DIR}/generated/
+rm -rf ${GLASSFISH_DIR}/${DV_DIR}/osgi-cache/felix
+
+sudo -u ${DB_USER} psql ${DV_DB} -c 'delete from "EJB__TIMER__TBL"';
+
+# restart the domain (also generates a warning if glassfish is stopped)
+${GLASSFISH_DIR}/bin/asadmin start-domain
+
diff --git a/doc/sphinx-guides/source/admin/index.rst b/doc/sphinx-guides/source/admin/index.rst
@@ -18,3 +18,4 @@ Contents:
    harvestserver
    metadataexport
    timers
+   troubleshooting
diff --git a/doc/sphinx-guides/source/admin/timers.rst b/doc/sphinx-guides/source/admin/timers.rst
@@ -1,3 +1,5 @@
+.. role:: fixedwidthplain
+
 Dataverse Application Timers
 ============================
 
@@ -20,7 +22,7 @@ The following JVM option instructs the application to act as the dedicated timer
 
 ``-Ddataverse.timerServer=true``
 
-**IMPORTANT:** Note, that this option is automatically set by the Dataverse installer script. That means that when configuring a multi-server cluster, it will be the responsibility of the installer to remove the option from the domain.xml of every node except the one intended to be the timer server. 
+**IMPORTANT:** Note that this option is automatically set by the Dataverse installer script. That means that when **configuring a multi-server cluster**, it will be the responsibility of the installer to remove the option from the :fixedwidthplain:`domain.xml` of every node except the one intended to be the timer server. We also recommend that the following entry in the :fixedwidthplain:`domain.xml`: ``<ejb-timer-service timer-datasource="jdbc/VDCNetDS">`` is changed back to ``<ejb-timer-service>`` on all the non-timer server nodes. Similarly, this option is automatically set by the installer script. Changing it back to the default setting on a server that doesn't need to run the timer will prevent a potential race condition, where multiple servers try to get a lock on the timer database. 
 
 Harvesting Timers 
 -----------------
@@ -41,3 +43,8 @@ This timer runs a daily job that tries to export all the local, published datase
 This daily job will also update all the harvestable OAI sets configured on your server, adding new and/or newly published datasets or marking deaccessioned datasets as "deleted" in the corresponding sets as needed. 
 
 This job is automatically scheduled to run at 2AM local time every night. If really necessary, it is possible (for an advanced user) to change that time by directly editing the EJB timer application table in the database.  
+
+Known Issues
+------------
+
+We've got several reports of an intermittent issue where the applicaiton fails to deploy with the error message "EJB Timer Service is not available." Please see the :doc:`/admin/troubleshooting` section of this guide for a workaround. 
diff --git a/doc/sphinx-guides/source/admin/troubleshooting.rst b/doc/sphinx-guides/source/admin/troubleshooting.rst
@@ -0,0 +1,29 @@
+.. role:: fixedwidthplain
+
+Troubleshooting
+===============
+
+.. contents:: :local:
+
+This new (as of v.4.6) section of the Admin guide is for tips on how to diagnose and fix system problems. 
+
+Deployment fails, "EJB Timer Service not available"
+---------------------------------------------------
+
+Sometimes the Dataverse application fails to deploy, or Glassfish fails to restart once the application is deployed, with the following error message: :fixedwidthplain:`"remote failure: Error occurred during deployment: Exception while loading the app : EJB Timer Service is not available. Please see server.log for more details."`
+
+We don't know what's causing this issue, but here's a known workaround: 
+
+- Stop Glassfish; 
+
+- Remove the ``generated`` and ``osgi-cache`` directories; 
+
+- Delete all the rows from the ``EJB__TIMER__TBL`` table in the database;
+
+- Start Glassfish
+
+The shell script below performs the steps above. 
+Note that it may or may not work on your system, so it is provided as an example only, downloadable :download:`here </_static/util/clear_timer.sh>`. Aside from the configuration values that need to be changed to reflect your environment (the Glassfish directory, name of the database, etc.) the script relies on the database being configured in a certain way for access. (See the comments in the script for more information)
+
+.. literalinclude:: ../_static/util/clear_timer.sh
+
diff --git a/doc/sphinx-guides/source/api/apps.rst b/doc/sphinx-guides/source/api/apps.rst
@@ -1,7 +1,7 @@
 Apps
 ====
 
-The introduction of Dataverse APIs has fostered the development of apps that are listed at http://datascience.iq.harvard.edu/collaborations
+The introduction of Dataverse APIs has fostered the development of apps that are listed at http://dataverse.org/integrations
 
 The apps below are open source, demonstrating how to use Dataverse APIs. Some of these apps (and others) are built on :doc:`/api/client-libraries` that are available for Dataverse APIs.
 
@@ -40,7 +40,7 @@ https://github.com/CenterForOpenScience/osf.io/tree/master/website/addons/datave
 GeoConnect
 ~~~~~~~~~~
 
-GeoConnect allows Dataverse files to be visualized on http://worldmap.harvard.edu with a "Map It" button.
+GeoConnect allows Dataverse files to be visualized on http://worldmap.harvard.edu with the "Explore" button. Read more about it in the :doc:`/user/data-exploration/worldmap` section of the User Guide.
 
 https://github.com/IQSS/geoconnect
 

diff --git a/doc/sphinx-guides/source/api/client-libraries.rst b/doc/sphinx-guides/source/api/client-libraries.rst
@@ -22,6 +22,6 @@ It was created by `Thomas Leeper <http://thomasleeper.com>`_ whose dataverse can
 Java
 ----
 
-https://github.com/IQSS/dataverse-client-java is the offical Java library for Dataverse APIs.
+https://github.com/IQSS/dataverse-client-java is the official Java library for Dataverse APIs.
 
 `Richard Adams <http://www.researchspace.com/electronic-lab-notebook/about_us_team.html>`_ from `ResearchSpace <http://www.researchspace.com>`_ created and maintains this library.
diff --git a/doc/sphinx-guides/source/api/index.rst b/doc/sphinx-guides/source/api/index.rst
@@ -13,6 +13,8 @@ APIs. In 4.0, we require to get a token, by simply registering for a Dataverse a
 
 Rather than using a production installation of Dataverse, API users are welcome to use http://demo.dataverse.org for testing.
 
+Please note that the APIs in this guide are shipped with the Dataverse software itself but additional APIs are available if you install the "miniverse" application from https://github.com/IQSS/miniverse and give it read only access to your production Dataverse database. http://dataverse.org/metrics is powered by miniverse.
+
 Contents:
 
 .. toctree::