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
  12 * This YammerImport plugin enabled on your StatusNet instance
  13
  14 Setup
  15 -----
  16
  17 The import process will be runnable through an administration panel on
  18 your StatusNet site.
  19
  20 The user interface and OAuth setup has not yet been completed, you will
  21 have to manually initiate the OAuth authentication to get a token.
  22
  23 Be patient, there will be a UI soon. ;)
  24
  25
  26 Limitations
  27 -----------
  28
  29 Paging has not yet been added, so the importer will only pull up to:
  30 * first 50 users
  31 * first 20 groups
  32 * last 20 public messages
  33
  34
  35 Subscriptions and group memberships
  36 -----------------------------------
  37
  38 Yammer's API does not expose user/tag subscriptions or group memberships
  39 except for the authenticating user. As a result, users will need to re-join
  40 groups and re-follow their fellow users after the import.
  41
  42 (This limitation may be lifted in future for sites on the Silver or Gold
  43 plans where the import is done by a verified admin, as it should be possible
  44 to fetch the information for each user via the admin account.)
  45
  46
  47 Authentication
  48 --------------
  49
  50 Account passwords cannot be retrieved, but the primary e-mail address is
  51 retained so users can reset their passwords by mail if you're not using a
  52 custom authentication system like LDAP.
  53
  54
  55 Private messages and groups
  56 ---------------------------
  57
  58 At this time, only public messages are imported; private direct and group
  59 messages are ignored. (This may change with Silver and Gold plans in future.)
  60
  61 Yammer groups may be either public or private. Groups in StatusNet currently
  62 have no privacy option, so any private groups will become public groups in the
  63 imported site.
  64
  65
  66 Attachments
  67 -----------
  68
  69 Attached image and document files will be copied in as if they had been
  70 uploaded to the StatusNet site. Currently images do not display inline like
  71 they do on Yammer; they will be linked instead.
  72
  73 File type and size limitations on attachments will be applied, so beware some
  74 attachments may not make it through.
  75
  76
  77
  78
  79 Code structure
  80 ==============
  81
  82 Standalone classes
  83 ------------------
  84
  85 YammerRunner: encapsulates the iterative process of retrieving the various users,
  86               groups, and messages via SN_YammerClient and saving them locally
  87               via YammerImporter.
  88
  89 SN_YammerClient: encapsulates HTTP+OAuth interface to Yammer API, returns data
  90                  as straight decoded JSON object trees.
  91
  92 YammerImporter: encapsulates logic to pull information from the returned API data
  93                 and convert them to native StatusNet users, groups, and messages.
  94
  95 Web UI actions
  96 -------------
  97
  98 YammeradminpanelAction: web panel for site administrator to initiate and monitor
  99                         the import process.
 100
 101 Command-line scripts
 102 --------------------
 103
 104 yammer-import.php: CLI script to start a Yammer import run in one go.
 105
 106 Database objects
 107 ----------------
 108
 109 Yammer_state: data object storing YammerRunner's state between iterations.
 110
 111 Yammer_notice_stub: data object for temporary storage of fetched Yammer messages
 112                     between fetching them (reverse chron order) and saving them
 113                     to local messages (forward chron order).
 114 Yammer_user,
 115 Yammer_group,
 116 Yammer_notice: data objects mapping original Yammer item IDs to their local copies.
 117