From 0477101af7bda9d8e58f3315837a81fca17d06b4 Mon Sep 17 00:00:00 2001
From: Brion Vibber <brion@pobox.com>
Date: Mon, 27 Sep 2010 17:12:06 -0700
Subject: [PATCH] update README for YammerImport

---
 plugins/YammerImport/README | 97 +++++++++++++++++++++++++++++++------
 1 file changed, 81 insertions(+), 16 deletions(-)

diff --git a/plugins/YammerImport/README b/plugins/YammerImport/README
index 1bac69a243..975faa2132 100644
--- a/plugins/YammerImport/README
+++ b/plugins/YammerImport/README
@@ -8,28 +8,93 @@ Requirements
 ------------
 
 * An account on the Yammer network you wish to import from
-* An administrator account on the target StatusNet instance
+* An administrator account on the target StatusNet instance, or
+  command-line administrative access
 * This YammerImport plugin enabled on your StatusNet instance
 
-Setup
------
-
-The import process will be runnable through an administration panel on
-your StatusNet site.
-
-The user interface and OAuth setup has not yet been completed, you will
-have to manually initiate the OAuth authentication to get a token.
-
-Be patient, there will be a UI soon. ;)
-
 
 Limitations
 -----------
 
-Paging has not yet been added, so the importer will only pull up to:
-* first 50 users
-* first 20 groups
-* last 20 public messages
+Yammer API key registrations only work for your own network unless you make
+arrangements for a 'trusted app' key, so for now users will need to register
+the app themselves. There is a helper in the admin panel for this.
+
+In theory any number of users, groups, and messages should be supported, but
+it hasn't been fully tested on non-trivial-sized sites.
+
+No provision has yet been made for dealing with conflicting usernames or
+group names, or names which are not considered valid by StatusNet. Errors
+are possible.
+
+Running via the web admin interface requires having queueing enabled, and is
+fairly likely to have problems with the application key registration step in
+a small installation at this time.
+
+
+Web setup
+---------
+
+The import process is runnable through an administration panel on your
+StatusNet site. The user interface is still a bit flaky, however, and if
+errors occur during import the process may stop with no way to restart it
+visible.
+
+The admin interface will probably kinda blow up if JS/AJAX isn't working.
+
+You'll be prompted to register the application and authenticate into Yammer,
+after which a progress screen will display.
+
+Two big warnings:
+* The progress display does not currently auto-refresh.
+* If anything fails once actual import has begun, it'll just keep showing
+  the current state. You won't see an error message, and there's no way
+  to reset or restart from the web UI yet.
+
+You can continue or reset the import state using the command-line script.
+
+
+CLI setup
+---------
+
+You'll need to register an application consumer key to allow the importer
+to connect to your Yammer network; this requires logging into Yammer:
+
+  https://www.yammer.com/client_applications/new
+
+Check all the 'read' options; no 'write' options are required, but Yammer
+seems to end up setting them anyway.
+
+You can set the resulting keys directly in config.php:
+
+    $config['yammer']['consumer_key'] = '#####';
+    $config['yammer']['consumer_secret'] = '##########';
+
+Initiate authentication by starting up the importer script:
+
+    php plugins/YammerImport/scripts/yammer-import.php
+
+Since you haven't yet authenticated, this will request an auth token and
+give you a URL to open in your web browser. Once logged in and authorized
+there, you'll be given a confirmation code. Pass this back:
+
+    php plugins/YammerImport/scripts/yammer-import.php --verify=####
+
+If all is well, the import process will begin and run through the end.
+
+In case of error or manual abort, you should be able to continue the
+import from where you left off by running the script again:
+
+    php plugins/YammerImport/scripts/yammer-import.php
+
+To reset the Yammer import state -- without removing any of the items
+that have already been imported -- you can pass the --reset option:
+
+    php plugins/YammerImport/scripts/yammer-import.php --reset
+
+This'll let you start over from the requesting-authentication stage.
+Any users, groups, or notices that have already been imported will be
+retained.
 
 
 Subscriptions and group memberships