Merge branch 'testing' of gitorious.org:statusnet/mainline into testing

[quix0rs-gnu-social.git] / plugins / YammerImport / README

diff --git a/plugins/YammerImport/README b/plugins/YammerImport/README
index 5ab080647a8816ebc242d5afa72a37ae9be06371..975faa21326dee9e01fb50312222f5e08a43fd4c 100644 (file)
--- 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 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
 
 * 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
 
 
 Subscriptions and group memberships


@@ -73,3 +138,45 @@ they do on Yammer; they will be linked instead.
 File type and size limitations on attachments will be applied, so beware some
 attachments may not make it through.
 
 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.
+