------------
* 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.
+Limitations
+-----------
-The user interface and OAuth setup has not yet been completed, you will
-have to manually initiate the OAuth authentication to get a token.
+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.
-Be patient, there will be a UI soon. ;)
+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.
-Limitations
------------
+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:
-Paging has not yet been added, so the importer will only pull up to:
-* first 50 users
-* first 20 groups
-* last 20 public messages
+ 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
File type and size limitations on attachments will be applied, so beware some
attachments may not make it through.
+
+
+
+Code structure
+==============
+
+Standalone classes
+------------------
+
+YammerRunner: encapsulates the iterative process of retrieving the various users,
+ groups, and messages via SN_YammerClient and saving them locally
+ via YammerImporter.
+
+SN_YammerClient: encapsulates HTTP+OAuth interface to Yammer API, returns data
+ as straight decoded JSON object trees.
+
+YammerImporter: encapsulates logic to pull information from the returned API data
+ and convert them to native StatusNet users, groups, and messages.
+
+Web UI actions
+-------------
+
+YammeradminpanelAction: web panel for site administrator to initiate and monitor
+ the import process.
+
+Command-line scripts
+--------------------
+
+yammer-import.php: CLI script to start a Yammer import run in one go.
+
+Database objects
+----------------
+
+Yammer_state: data object storing YammerRunner's state between iterations.
+
+Yammer_notice_stub: data object for temporary storage of fetched Yammer messages
+ between fetching them (reverse chron order) and saving them
+ to local messages (forward chron order).
+Yammer_user,
+Yammer_group,
+Yammer_notice: data objects mapping original Yammer item IDs to their local copies.
+