From 5b3de9aaa465b217e857bc651cce6c86212de0b6 Mon Sep 17 00:00:00 2001 From: Brion Vibber Date: Mon, 27 Sep 2010 17:12:06 -0700 Subject: [PATCH] update README for YammerImport --- plugins/YammerImport/README | 93 +++++++++++++++++++++++++++++++------ 1 file changed, 79 insertions(+), 14 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. +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: + + 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 -Paging has not yet been added, so the importer will only pull up to: -* first 50 users -* first 20 groups -* last 20 public messages +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 -- 2.39.5