plugins/YammerImport/README

   1 Yammer Import Plugin
   2 ====================
   3
   4 This plugin allows a one-time import pulling user accounts, groups, and
   5 public messages from an existing Yammer instance, using Yammer's public API.
   6
   7 Requirements
   8 ------------
   9
  10 * An account on the Yammer network you wish to import from
  11 * An administrator account on the target StatusNet instance, or
  12   command-line administrative access
  13 * This YammerImport plugin enabled on your StatusNet instance
  14
  15
  16 Limitations
  17 -----------
  18
  19 Yammer API key registrations only work for your own network unless you make
  20 arrangements for a 'trusted app' key, so for now users will need to register
  21 the app themselves. There is a helper in the admin panel for this.
  22
  23 In theory any number of users, groups, and messages should be supported, but
  24 it hasn't been fully tested on non-trivial-sized sites.
  25
  26 No provision has yet been made for dealing with conflicting usernames or
  27 group names, or names which are not considered valid by StatusNet. Errors
  28 are possible.
  29
  30 Running via the web admin interface requires having queueing enabled, and is
  31 fairly likely to have problems with the application key registration step in
  32 a small installation at this time.
  33
  34
  35 Web setup
  36 ---------
  37
  38 The import process is runnable through an administration panel on your
  39 StatusNet site. The user interface is still a bit flaky, however, and if
  40 errors occur during import the process may stop with no way to restart it
  41 visible.
  42
  43 The admin interface will probably kinda blow up if JS/AJAX isn't working.
  44
  45 You'll be prompted to register the application and authenticate into Yammer,
  46 after which a progress screen will display.
  47
  48 Two big warnings:
  49 * The progress display does not currently auto-refresh.
  50 * If anything fails once actual import has begun, it'll just keep showing
  51   the current state. You won't see an error message, and there's no way
  52   to reset or restart from the web UI yet.
  53
  54 You can continue or reset the import state using the command-line script.
  55
  56
  57 CLI setup
  58 ---------
  59
  60 You'll need to register an application consumer key to allow the importer
  61 to connect to your Yammer network; this requires logging into Yammer:
  62
  63   https://www.yammer.com/client_applications/new
  64
  65 Check all the 'read' options; no 'write' options are required, but Yammer
  66 seems to end up setting them anyway.
  67
  68 You can set the resulting keys directly in config.php:
  69
  70     $config['yammer']['consumer_key'] = '#####';
  71     $config['yammer']['consumer_secret'] = '##########';
  72
  73 Initiate authentication by starting up the importer script:
  74
  75     php plugins/YammerImport/scripts/yammer-import.php
  76
  77 Since you haven't yet authenticated, this will request an auth token and
  78 give you a URL to open in your web browser. Once logged in and authorized
  79 there, you'll be given a confirmation code. Pass this back:
  80
  81     php plugins/YammerImport/scripts/yammer-import.php --verify=####
  82
  83 If all is well, the import process will begin and run through the end.
  84
  85 In case of error or manual abort, you should be able to continue the
  86 import from where you left off by running the script again:
  87
  88     php plugins/YammerImport/scripts/yammer-import.php
  89
  90 To reset the Yammer import state -- without removing any of the items
  91 that have already been imported -- you can pass the --reset option:
  92
  93     php plugins/YammerImport/scripts/yammer-import.php --reset
  94
  95 This'll let you start over from the requesting-authentication stage.
  96 Any users, groups, or notices that have already been imported will be
  97 retained.
  98
  99
 100 Subscriptions and group memberships
 101 -----------------------------------
 102
 103 Yammer's API does not expose user/tag subscriptions or group memberships
 104 except for the authenticating user. As a result, users will need to re-join
 105 groups and re-follow their fellow users after the import.
 106
 107 (This limitation may be lifted in future for sites on the Silver or Gold
 108 plans where the import is done by a verified admin, as it should be possible
 109 to fetch the information for each user via the admin account.)
 110
 111
 112 Authentication
 113 --------------
 114
 115 Account passwords cannot be retrieved, but the primary e-mail address is
 116 retained so users can reset their passwords by mail if you're not using a
 117 custom authentication system like LDAP.
 118
 119
 120 Private messages and groups
 121 ---------------------------
 122
 123 At this time, only public messages are imported; private direct and group
 124 messages are ignored. (This may change with Silver and Gold plans in future.)
 125
 126 Yammer groups may be either public or private. Groups in StatusNet currently
 127 have no privacy option, so any private groups will become public groups in the
 128 imported site.
 129
 130
 131 Attachments
 132 -----------
 133
 134 Attached image and document files will be copied in as if they had been
 135 uploaded to the StatusNet site. Currently images do not display inline like
 136 they do on Yammer; they will be linked instead.
 137
 138 File type and size limitations on attachments will be applied, so beware some
 139 attachments may not make it through.
 140
 141
 142
 143
 144 Code structure
 145 ==============
 146
 147 Standalone classes
 148 ------------------
 149
 150 YammerRunner: encapsulates the iterative process of retrieving the various users,
 151               groups, and messages via SN_YammerClient and saving them locally
 152               via YammerImporter.
 153
 154 SN_YammerClient: encapsulates HTTP+OAuth interface to Yammer API, returns data
 155                  as straight decoded JSON object trees.
 156
 157 YammerImporter: encapsulates logic to pull information from the returned API data
 158                 and convert them to native StatusNet users, groups, and messages.
 159
 160 Web UI actions
 161 -------------
 162
 163 YammeradminpanelAction: web panel for site administrator to initiate and monitor
 164                         the import process.
 165
 166 Command-line scripts
 167 --------------------
 168
 169 yammer-import.php: CLI script to start a Yammer import run in one go.
 170
 171 Database objects
 172 ----------------
 173
 174 Yammer_state: data object storing YammerRunner's state between iterations.
 175
 176 Yammer_notice_stub: data object for temporary storage of fetched Yammer messages
 177                     between fetching them (reverse chron order) and saving them
 178                     to local messages (forward chron order).
 179 Yammer_user,
 180 Yammer_group,
 181 Yammer_notice: data objects mapping original Yammer item IDs to their local copies.
 182