1 files changed, 182 insertions, 0 deletions
diff --git a/plugins/YammerImport/README b/plugins/YammerImport/README
new file mode 100644
index 000000000..975faa213
--- /dev/null
+++ b/plugins/YammerImport/README
@@ -0,0 +1,182 @@
+Yammer Import Plugin
+====================
+
+This plugin allows a one-time import pulling user accounts, groups, and
+public messages from an existing Yammer instance, using Yammer's public API.
+
+Requirements
+------------
+
+* An account on the Yammer network you wish to import from
+* An administrator account on the target StatusNet instance, or
+  command-line administrative access
+* This YammerImport plugin enabled on your StatusNet instance
+
+
+Limitations
+-----------
+
+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
+-----------------------------------
+
+Yammer's API does not expose user/tag subscriptions or group memberships
+except for the authenticating user. As a result, users will need to re-join
+groups and re-follow their fellow users after the import.
+
+(This limitation may be lifted in future for sites on the Silver or Gold
+plans where the import is done by a verified admin, as it should be possible
+to fetch the information for each user via the admin account.)
+
+
+Authentication
+--------------
+
+Account passwords cannot be retrieved, but the primary e-mail address is
+retained so users can reset their passwords by mail if you're not using a
+custom authentication system like LDAP.
+
+
+Private messages and groups
+---------------------------
+
+At this time, only public messages are imported; private direct and group
+messages are ignored. (This may change with Silver and Gold plans in future.)
+
+Yammer groups may be either public or private. Groups in StatusNet currently
+have no privacy option, so any private groups will become public groups in the
+imported site.
+
+
+Attachments
+-----------
+
+Attached image and document files will be copied in as if they had been
+uploaded to the StatusNet site. Currently images do not display inline like
+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.
+
+
+
+
+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.
+